Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 6 - Component Manager / Component Manager Reference

Routines for Components / Registering Components

RegisterComponent

The RegisterComponent function makes a component available for use by applications (or other clients). Once the Component Manager has registered a component, applications can find and open the component using the standard Component Manager routines. To register a component, you provide information identifying the component and its capabilities. The Component Manager returns a component identifier that uniquely identifies the component to the system.

Components you register with the RegisterComponent function must be in memory when you call this function. If you want to register a component that is stored in the resource fork of a file, use the RegisterComponentResource function. Use the RegisterComponentResourceFile function to register all components in the resource fork of a file.

Note that a component residing in your application heap remains registered until your application unregisters it or quits. A component residing in the system heap and registered by your application remains registered until your application unregisters it or until the computer is shut down.

FUNCTION RegisterComponent (cd: ComponentDescription; 
                            componentEntryPoint: ComponentRoutine; 
                            global: Integer; 
                            componentName: Handle;
                            componentInfo: Handle;
                            componentIcon: Handle): Component;

cd

A component description record that describes the component to be registered. You must correctly fill in the fields of this record before calling the RegisterComponent function. When applications search for components using the FindNextComponent function, the Component Manager compares the attributes you specify here with those specified by the application. If the attributes match, the Component Manager returns the component identifier to the application.

componentEntryPoint

The address of the main entry point of the component you are
registering. The routine referred to by this parameter receives all requests for the component.

global

A set of flags that control the scope of component registration. You can use these flags to specify a value for the global parameter:

registerCmpGlobal = 1;
Specify this flag to indicate that this component should be made available to other applications and clients as well as the one performing the registration. If you do not specify this flag, the component is available for use only by the registering application or component (that is, the component is local to the A5 world of the registering program).

registerCmpNoDuplicates = 2;
Specify this flag to indicate that if a component with identical characteristics to the one being registered already exists, then the new one should not be registered (RegisterComponent returns 0 in this situation). If you do not specify this flag, the component is registered even if a component with identical characteristics to the one being registered already exists.

registerCompAfter = 4;
Specify this flag to indicate that this component should be registered after all other components with the same component type. Usually components are registered before others with identical descriptions; specifying this flag overrides that behavior.

componentName

A handle to the component's name. Set this parameter to NIL if you do not want to assign a name to the component.

componentInfo

A handle to the component's information string. Set this parameter to NIL if you do not want to assign an information string to the component.

componentIcon

A handle to the component's icon (a 32-by-32 pixel black-and-white icon). Set this parameter to NIL if you do not want to supply an icon for this component. Note that this icon is not used by the Finder; you supply an icon only so that other components or applications can display your component's icon if needed.

DESCRIPTION

The RegisterComponent function registers the specified component, recording the information specified in the cd, componentName, componentInfo, and componentIcon parameters. The function returns the component identifier assigned to the component by the Component Manager. If it cannot register the component, the RegisterComponent function returns a function result of NIL.

SEE ALSO

For a complete description of the component description record, see "Data Structures for Components" beginning on page 6-50.