Type Library Elements

From RAD Studio
Jump to: navigation, search

Go Up to Type Library Editor


The Type Library interface as represented in the Type Library Editor can seem overwhelmingly complicated at first. This is because it represents information about a great number of elements, each of which has its characteristics. However, many of these characteristics are common to all elements. For example, every element (including the type library itself) has the following:

  • Name, which is used to describe the element and which is used when referring to the element in the code.
  • GUID (globally unique identifier), which is a unique 128-bit value that COM uses to identify the element. It should always be supplied for the type library itself as well as for CoClasses and interfaces. It is optional otherwise.
  • Version number, which distinguishes between multiple versions of the element. It is always optional, but should be provided for CoClasses and interfaces, because some tools can not use them without a version number.
  • Help properties that link the element to a Help topic. They include a Help String, and Help Context or Help String Context value. The Help Context is used for a traditional Windows Help system where the type library has a stand-alone Help file. The Help String Context is used when help is supplied by a separate DLL instead. The Help Context or Help String Context refers to a Help file or DLL that is specified on the type library's Attributes page. It is always optional.

Interfaces

An interface describes the methods (and any properties expressed as get and set functions) for an object that must be accessed through a virtual function table (vtable). If an interface is flagged as dual, it will inherit from IDispatch, and your object can provide both early-bound, vtable access, and runtime binding through OLE automation. By default, the type library flags all interfaces you add as dual.

Interfaces can be assigned members: methods and properties. These appear in the object list pane as children of the interface node. Properties for interfaces are represented by the get and set methods used to read and write the property's underlying data. They are represented in the tree view using special icons that indicate their purpose.

Special Icons for 'get' and 'set' Methods

Putprop.jpg

A write (set, put) by value property function.

Refprop.jpg

A read (get) | write (set, put) | write by reference property function.

Getprop.jpg

A read (get) property function.


Note: Write by Reference: When a property is specified as Write By Reference, it is passed as a pointer rather than by value. Some applications, such as Visual Basic, use Write By Reference, if it is present, to optimize performance. To pass the property only by reference rather than by value, use the property type By Reference Only. To pass the property by reference as well as by value, select Read > Write > Write By Ref . To invoke this menu, go to the toolbar and select the down-arrow next to the property icon.

After you add the properties or methods using the toolbar button or the object list pane context menu, you describe their syntax and attributes by selecting the property or method and using the pages of type information.

The Attributes page lets you give the property or method a name and dispatch ID (so that it can be called using IDispatch). For properties, you also assign a type. The function signature is created using the Parameters page, where you can add, remove, and rearrange parameters, set their type and any modifiers, and specify function return types.

Note: Members of interfaces that need to raise exceptions should return an HRESULT and specify a return value parameter (PARAM_RETVAL) for the actual return value. Declare these methods using the safecall calling convention.

Note that when you assign properties and methods to an interface, they are implicitly assigned to its associated CoClass. This is why the Type Library editor does not let you add properties and methods directly to a CoClass.

Dispinterfaces

Interfaces are more commonly used than dispinterfaces to describe the properties and methods of an object. Dispinterfaces are only accessible through dynamic binding, while interfaces can have static binding through a vtable.

You can add methods and properties to dispinterfaces in the same way you add them to interfaces. However, when you create a property for a dispinterface, you can't specify a function kind or parameter types.

CoClasses

A CoClass describes a unique COM object that implements one or more interfaces. When defining a CoClass, you must specify which implemented interface is the default for the object, and optionally, which dispinterface is the default source for events. Note that you do not add properties or methods to a CoClass in the Type Library editor. Properties and methods are exposed to clients by interfaces, which are associated with the CoClass using the Implements page.

Type definitions

Enumerations, aliases, records, and unions all declare types that can then be used elsewhere in the type library.

Enums consist of a list of constants, each of which must be numeric. Numeric input is usually an integer in decimal or hexadecimal format. The base value is zero by default. You can add constants to your enumeration by selecting the enumeration in the object list pane and clicking the Const button on the toolbar or selecting New > Const command from the object list pane context menu.

Note: It is strongly recommended that you provide help strings for your enumerations to make their meaning clearer. The following is a sample entry of an enumeration type for a mouse button and includes a help string for each enumeration element.

mbLeft = 0 [helpstring 'mbLeft'];
mbRight = 1 [helpstring 'mbRight'];
mbMiddle = 3 [helpstring 'mbMiddle'];
typedef enum TxMouseButton
{
[helpstring("mbLeft")]
mbLeft = 0,
[helpstring("mbRight)]
mbRight = 1.
[helpstring("mbMiddle)]
mbMiddle = 2
} TxMouseButton;

An alias creates an alias (type definition) for a type. You can use the alias to define types that you want to use in other type info such as records or unions. Associate the alias with the underlying type definition by setting the Type attribute on the Attributes page.

A record consists of a list of structure members or fields. A union is a record with only a variant part. Like a record, a union consists of a list of structure members or fields. However, unlike the members of records, each member of a union occupies the same physical address, so that only one logical value can be stored.

Add the fields to a record or union by selecting it in the object list pane and clicking the field button in the toolbar or right clicking and choosing field from the object list pane context menu. Each field has a name and a type, which you assign by selecting the field and assigning values using the Attributes page. Records and unions can be defined with an optional tag.

Members can be of any built-in type, or you can specify a type using alias before you define the record.

Modules

A module defines a group of functions, typically a set of DLL entry points. You define a module by

  • Specifying a DLL that it represents on the attributes page.
  • Adding methods and constants using the toolbar or the object list pane context menu. For each method or constant, you must then define its attributes by selecting the it in the object list pane and setting the values on the Attributes page.

For module methods, you must assign a name and DLL entry point using the attributes page. Declare the function's parameters and return type using the parameters page.

For module constants, use the Attributes page to specify a name, type, and value.

Note: The Type Library Editor does not generate any declarations or implementation related to a module. The specified DLL must be created as a separate project.

See Also