From previous chapters, we know about registry entries such as those that appear under an object's ProgID, VersionIndependentProgID, and CLSID. Additional entries hold information relevant to OLE Documents. (This example is taken from the version of Cosmo we'll implement in Chapter 18.)1
\
Cosmo.Figure.2 = Cosmo Figure (Chap 18)
CLSID = {002114E-000-0000-C000-000000000046}
Insertable
\
CLSID
{002114E-000-0000-C000-000000000046} = Cosmo Figure (Chap 18)
LocalServer32 = c:\inole\chap18\cosmo\cosmo18.exe
InprocHandler32 = OLE32.DLL
ProgID = Cosmo.Figure.2
VersionIndependentProgID = Cosmo.Figure
Insertable
DataFormats
GetSet
0 = Polyline Figure,1,1,3
1 = Embed Source,1,8,1
2 = 3,1,32,1
3 = 2,1,16,1
DefaultIcon = c:\inole\chap18\cosmo\cosmo18.exe,0
verb
0 = &Edit,0,2
-1 = Show,0,0
-2 = Open,0,0
-3 = Hide,0,1
AuxUserType
2 = Cosmo
3 = Cosmo from Chapter 18
MiscStatus = 16
1 = 17
Conversion
Readable
Main = Cosmo1.0,Polyline Figure
Readwritable
Main = Cosmo1.0,Polyline Figure
We've seen many of these entries already, including DataFormats, which we first encountered in Chapter 10 along with the OleRegEnumFormatEtc function that worked with such entries. Also, these entries mark OLE32.DLL as the object handler for this particular object type. OLE32.DLL is the default handler itself. If you do not include an InprocHandler32 entry, OLE uses the default handler anyway.
The new entries for OLE Documents are described in the following table:
Key | Subkeys and Values |
Insertable | Marks the object as one that supports OLE Documents, meaning that it should appear in a container's Insert Object dialog box. |
DefaultIcon | A path to a module and the index of an icon in that module to use by default when the user checks Display As Icon in the container's Insert Object and Paste Special dialog boxes. If no entry is given or if the path is invalid, the dialog boxes will show a default icon (a sheet of paper with a corner folded down, your standard document icon). |
verb | This key has no value, but each subkey is of the form <verb identifier> = <text>,<menu flags>,<verb flags>. This list of keys identifies the object's supported verbs; those with zero or positive identifiers can appear in a container's pop-up menu. As a whole, this list defines the supported verbs that can be passed to IOleObject::DoVerb. In the value for each identifier is first a text string suitable for user interface. This can include an ampersand if the verb is allowed to appear in a menu. The <menu flags> provide MF_* values from WINDOWS.H that should be used for this item in a menu. Usually, this value is MF_STRING ¦ MF_ENABLE ¦ MF_UNCHECKED, which translates to 0. The <verb flags> are values taken from the enumeration OLEVERBATTRIB and can include OLEVERBATTRIB_NEVERDIRTIES (value 1, which indicates that the verb does not modify the object in any way) and OLEVERBATTRIB_ONCONTAINERMENU (value 2, which indicates that the verb should appear on a pop-up menu). |
AuxUserType | This key has no value itself but instead has subkeys of the format <form number> = <string>; <form number> is either 2 or 3 (never 1, for reasons known only to the gods)* and <string> is some user-readable name of the object. Form number 2 should always be a short name (under 10 characters) that describes the type of the object, as in "Cosmo". Form number 3 is a longer application name, such as "Cosmo from Chapter 18", used specifically with the Paste Special dialog box. |
* Actually, 1 is defined as the name stored as the value of the object's CLSID, so it need not be stored here.
Key | Subkeys and Values |
MiscStatus | The value of this key is the default set of flags for the object. Each subkey is of the form <aspect> = <status>, where <aspect> is a DVASPECT value and <status> is an integer flag. |
Conversion | Under this key, the object describes the other data formats that it can either convert to its own (listed under Readable) or emulate (listed under Readwritable). The subkey Main has a value of the form <format,format,format,format,...>. Each format is either a clipboard format string, as in "Polyline Figure", or an OLE 1 server ProgID, as in "Cosmo1.0".† These entries are used to populate a container's Convert dialog box, as will be explained later. |
† Specific considerations for OLE 1 conversion can be found in the file OLE1.WRI on thesample CD.
The OLE API functions OleRegEnumVerbs, OleRegGetUserType, and OleRegGetMiscStatus will read some of these entries for you effortlessly. OleReg-EnumVerbs returns an enumerator for the OLEIVERB type (IEnumOLEI-VERB), OleRegGetUserType returns a string, and OleRegGetMiscStatus returns a DWORD with the MiscStatus bits. The MiscStatus values come from the C++ enumeration OLEMISC and are the same flags that an object will return from IOleObject::GetMiscStatus:
enum tagOLEMISC
{
OLEMISC_RECOMPOSEONRESIZE = 1, //Run object to resize.
OLEMISC_ONLYICONIC = 2, //Object only appears iconic.
OLEMISC_INSERTNOTREPLACE = 4, //Paste instead of delete.
OLEMISC_STATIC = 8, //Static object
OLEMISC_CANTLINKINSIDE = 16, //No linking to embedding
OLEMISC_CANLINKBYOLE1 = 32, //Too complex for OLE 1
OLEMISC_ISLINKOBJECT = 64, //Object is linked.
OLEMISC_INSIDEOUT = 128, //In-place activation
OLEMISC_ACTIVATEWHENVISIBLE = 256, //In-place activation
OLEMISC_RENDERINGISDEVICEINDEPENDENT = 512
} OLEMISC;
Many of these flags are self-explanatory, and we'll see them in context as we go along. OLEMISC_RECOMPOSEONRESIZE specifically tells a container to run the object whenever its space is changed in the compound document, allowing the object to control its output quality when scaling is used. OLEMISC_INSERTNOTREPLACE tells a container that performing a Paste operation with this object selected should not replace the object but rather paste into it through IOleObject::InitFromData. OLEMISC_CANTLINKBYOLE1 says that an object uses link source information that is too complicated for OLE 1 containers to handle—OLE 1 can work with a File or a File!Item moniker, but nothing more.
Besides the flags shown here, OLE Controls adds a large number of other OLEMISC flags for its various uses, as we'll see in Chapter 24. For the most part, a simple embedding container or an embedded object will deal with only a few of these.
1 An entry named protocol can also appear here for compatibility with OLE 1 containers. This key has a subkey named StdFileEditing, which itself has two subkeys. The first is an entry named server, whose value is a path to the OLE 2 local server. (Only local servers are allowed.) The other is named verb and contains any number of subkeys 0, 1, 2, and so on, each with a value of a verb string to show in the OLE 1 container. You can look in the REG files of Chapter 18's Cosmo sample for details about these entries. |