Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 6 - Component Manager / Creating Components

Defining a Component's Interfaces

You define the interfaces supported by your component by declaring a set of functions for use by applications. These function declarations specify the parameters that must be provided for each request. The following code illustrates the general form of these function declarations, using the setup request defined for the sample drawing component as an example:

FUNCTION DrawerSetup (myInstance: ComponentInstance; 
                      VAR r: Rect): ComponentResult;

This example declares a function that supports the setup request. The first parameter to any component function must be a parameter that accepts a component instance. The Component Manager uses this value to correctly route the request. The calling application must supply a valid component instance when it calls your component. The second and following parameters are those required by your component function. For example, the DrawerSetup function takes one additional parameter, a rectangle. Finally, all component functions must return a function result of type ComponentResult (a long integer).

These function declarations must also include inline code. This code identifies the request code assigned to the function, specifies the number of bytes of parameter data accepted by the function, and executes a trap to the Component Manager. To continue with the Pascal example used earlier, the inline code for the DrawerSetup function is

INLINE $2F3C, $0004, $0000, $7000, $A82A;

The first element of this code, $2F3C, is the opcode for a move instruction that loads the contents of the next two elements onto the stack. The Component Manager uses these values when it invokes your component.

The second element, $0004, defines an integer value that specifies the number of bytes of parameter data required by the function, not including the component instance parameter. In this case, the size of a pointer to the rectangle is specified: 4 bytes.

Note

Note that Pascal calling conventions require that Boolean and 1-byte parameters are passed as 16-bit integer values.

The third element, $0000, specifies the request code for this function as an integer value. Each function supported by your component must have a unique request code. Your component uses this request code to identify the application's request. You may define only request code values greater than or equal to 0; negative values are reserved for definition by the Component Manager. Recall from the oval drawing component that the request code for the setup request, kDrawerSetUpSelect, has a value of 0.

The fourth element, $7000, is the opcode for an instruction that sets the D0 register to 0, which tells the Component Manager to call your component rather than to field the request itself.

The fifth element, $A82A, is the opcode for an instruction that executes a trap to the Component Manager.

If you are declaring functions for use by Pascal-language applications, your declarations should take the following form:

FUNCTION DrawerSetup (myInstance: ComponentInstance; 
                      VAR r: Rect): ComponentResult;
INLINE $2F3C, $0004, $0000, $7000, $A82A;

If you are declaring functions for use by C-language applications, your declarations can take the following form:

pascal ComponentResult DrawerSetup 
                     (ComponentInstance myInstance, Rect *r) = 
                           {0x2F3C,0x4,0x0,0x7000,0xA82A}; 

Alternatively, you can define the following statement to replace the inline code:

#define ComponentCall (callNum, paramSize) 
                      {0x2F3C,paramSize,callNum,0x7000,0xA82A}

Using this statement results in the following declaration format:

pascal ComponentResult DrawerSetup 
                  (ComponentInstance myInstance, Rect *r) = 
                   ComponentCall (kDrawerSetUpSelect, 4);

When a client application calls your function, the system executes the inline code, which invokes the Component Manager. The Component Manager then formats a component parameters record, locates the storage for the current connection, and invokes your component. The Component Manager provides the component parameters record and a handle to the storage of the current connection to your component as function parameters.