Legacy Document

Inside Macintosh: Advanced Color Imaging on the Mac OS /

Chapter 2 - Color Picker Manager / Writing Your Own Color Pickers

Dispatching to Functions Defined by a Color Picker

As explained in "Creating a Component Resource for a Color Picker" (page 2-30), the code for your color picker should be contained in a resource. The Component Manager expects the entry point in this resource to be a function having this format:

pascal ComponentResult MyColorPickerDispatch (
                                  ComponentParameters *params, 
                                  Handle storage)

Whenever the Color Picker Manager uses the Component Manager to send a request to your color picker, the Component Manager calls your component's entry point and passes any parameters, along with information about the current connection, in a component parameters structure. The Component Manager also passes a handle to the global storage associated with that instance of your color picker.

When your color picker receives a request, it should examine the parameters to determine the nature of the request, perform the appropriate processing, set an error code if necessary, and return an appropriate function result to the Component Manager.

The component parameters structure is defined by a data structure of type ComponentParameters. The what field of this structure specifies the type of request. Your color picker's entry point should interpret the request code and then possibly dispatch to some other subroutine. Your color picker must be able to handle the required request codes represented by the constants kComponentOpenSelect, kComponetCloseSelect, kComponentCanDoSelect, and kComponentVersionSelect.

Note

For complete details on required component request codes and the ComponentParameters structure, see the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox.

In addition to these required request codes, your color picker must also be able to handle the request codes defined by the elements of the PickerMessages enumerated data type, which is shown here and described in detail in "Request Codes" (page 2-12) in Advanced Color Imaging Reference.

typedef enum   {     /* request codes handled by a color picker */
 kInitPicker,  /* initialize any private data */
 kTestGraphicsWorld, /* test operability on current system */
 kGetDialog,   /* if using own dialog box, return its pointer; for 
                  default dialog box, return nil */
 kGetItemList, /* return a list of items for dialog box */
 kGetColor,    /* return original or newest color */
 kSetColor,    /* change original or newest color */
 kEvent,       /* perform any special processing necessary for an event */
 kEdit,        /* perform an editing command */
 kSetVisibility,/* make color picker visible or invisible */
 kDrawPicker,  /* redraw color picker */
 kItemHit,     /* respond to event in a dialog box item */
 kSetBaseItem, /* set base item for dialog box items */
 kGetProfile,  /* return a handle to the destination profile */
 kSetProfile,  /* change the destination color-matching profile */
 kGetPrompt,   /* return prompt string */
 kSetPrompt,   /* set a new prompt */
 kGetIconData, /* return script code and resource ID of icon family */
 kGetEditMenuState,/* return information about edit menu */
 kSetOrigin,   /* update any info about local coordinate system */
 kExtractHelpItem/* return information about help balloons */
} PickerMessages;

Your color picker should respond to these request codes by performing the requested action. Your color picker may need to access additional information provided in the params field to service the request. The params field of the component parameters structure is an array that contains the parameters specified by the Color Picker Manager. Your color picker can use the CallComponentFunctionWithStorage function to extract the parameters from this array and pass these parameters to a subroutine of your color picker. Listing 2-16 illustrates how to define a color picker entry point routine. This example inspects the params->what field to determine which request code to handle.

Listing 2-16 Handling Component Manager request codes

pascal ComponentResult MyColorPickerDispatch(ComponentParameters *params, 
                                  Handle storage)
{
   short             message;
   ComponentResult   result;
   ComponentFunction RoutineToCall = 0;

   message = params->what;
   if (message < 0)
      /* negative values are Component Manager request codes */
      switch (message)
      {
         case kComponentOpenSelect:
                              RoutineToCall = MyOpen; break;
         case kComponentCloseSelect:
                              RoutineToCall = MyClose; break;
         case kComponentCanDoSelect:
                              RoutineToCall = MyCanDo; break;
         case kComponentVersionSelect:
                              RoutineToCall = MyVersion; break;
         case kComponentRegisterSelect:
                              RoutineToCall = MyRegister; break;
         case kComponentTargetSelect:
                              RoutineToCall = MySetTarget; break;
         default:             return 0;    /* no error */
      }
   else
   {
      switch (message)
      {
         case kInitPicker:       RoutineToCall = MyInitPicker; break;
         case kTestGraphicsWorld:RoutineToCall = MyTestGraphicsWorld; break;
         case kGetDialog:        RoutineToCall = MyGetDialog; break;
         case kGetItemList:      RoutineToCall = MyGetItemList; break;
         case kGetColor:         RoutineToCall = MyGetColor; break;
         case kSetColor:         RoutineToCall = MySetColor; break;
         case kEvent:            RoutineToCall = MyDoEvent; break;
         case kEdit:             RoutineToCall = MyDoEdit; break;
         case kSetVisibility:    RoutineToCall = MySetVisibility; break;
         case kDrawPicker:       RoutineToCall = MyDrawPicker; break;
         case kItemHit:          RoutineToCall = MyItemHit; break;
         case kSetBaseItem:      RoutineToCall = MySetBaseItem; break;
         case kGetProfile:       RoutineToCall = MyGetProfile; break;
         case kSetProfile:       RoutineToCall = MySetProfile; break;
         case kGetPrompt:        RoutineToCall = MyGetPrompt; break;
         case kSetPrompt:        RoutineToCall = MySetPrompt; break;
         case kGetIconData:      RoutineToCall = MyGetIconData; break;
         case kGetEditMenuState: RoutineToCall = MyGetEditMenuState; break;
         case kSetOrigin:        RoutineToCall = MySetOrigin; break;
         case kExtractHelpItem:  RoutineToCall = MyExtractHelpItem; break;
         default:                return 0;
      }
   }
   result=CallComponentFunctionWithStorage(storage, params, RoutineToCall);
   return result;
}

"Color Picker-Defined Functions" (page 2-59) in Advanced Color Imaging Reference describes the interfaces your color picker must provide to respond to these request codes. The next several sections provide examples of how your color picker can respond to most of these request codes.