Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Advanced Color Imaging on the Mac OS /: Chapter 2 - Color Picker Manager / Using the Color Picker Manager

Using the Standard Dialog Box for Color Pickers
When your application calls the PickColor function, your application passes it a pointer to a color picker parameter block. Your application uses the color picker parameter block (described in "Color Picker Parameter Block" (page 2-20) in Advanced Color Imaging Reference) to specify information to and obtain information from the Color Picker Manager. For example, Listing 2-1 uses the color picker parameter block to specify which color to initially display in the dialog box and to place the dialog box on the deepest color screen. You also use the color picker parameter block to determine whether the user has selected a new color, and, if so, which color is selected.
Listing 2-1 Using the PickColor function
void MyPickAColor(void)
{
   ColorPickerInfo cpInfo;
   /* setting input color to be an RGB color */
   cpInfo.theColor.color.rgb = gMyRGBColor;
   cpInfo.theColor.profile = 0L;
   /* no destination profile */
   cpInfo.dstProfile = 0L;
   cpInfo.flags = AppIsColorSyncAware | CanModifyPalette | 
                  CanAnimatePalette;
   /* center dialog box on the deepest color screen */
   cpInfo.placeWhere = kDeepestColorScreen;
   /* use the system default picker */
   cpInfo.pickerType = 0L;
   /* install event filter and color-changed functions */
   cpInfo.eventProc = MyEventProc;/* see Listing 2-2 (page 2-10) */
   cpInfo.colorProc = MyColorChangedProc;/* see Listing 2-3 */
   cpInfo.colorProcData = 0L;
   strcpy(cpInfo.prompt,"\pChoose a highlight color:");
   /* describe the Edit menu for Color Picker Manager */
   cpInfo.mInfo.editMenuID = kMyEditMenuID;
   cpInfo.mInfo.cutItem = kMyCutItem;
   cpInfo.mInfo.copyItem = kMyCopyItem;
   cpInfo.mInfo.pasteItem = kMyPasteItem;
   cpInfo.mInfo.clearItem = kMyClearItem;
   cpInfo.mInfo.undoItem = kMyUndoItem;
   /* display dialog box to allow user to choose a color */
   if(PickColor(&cpInfo) == noErr && cpInfo.newColorChosen)
      /* use this new color */
      DoNewColor(&cpInfo.theColor);
}
The PickColor function displays the modal dialog box shown in Figure 2-1 (page 2-4). Your application uses the prompt field of the color picker parameter block to specify the text string prompting the user to choose a color for a particular use (for example, "Choose a highlight color").
When the user clicks the Cancel button, PickColor removes the dialog box, and the newColorChosen field of the color picker parameter block contains the value false. When the user clicks the OK button, PickColor removes the dialog box, the newColorChosen field of the color picker parameter block contains the value true, and the field theColor contains a structure describing the newly selected color. Your application can then use this color for the purpose described in the prompt string (for example, highlighting text or filling shapes).
When the dialog box is first displayed, the color that your application specifies in the field theColor is used as the original color from which the user begins to edit. Upon completion, PickColor sets this field to the last color that the user chose before clicking OK. Although the new colors selected by the user may vary widely, the original color remains fixed for comparison. Figure 2-1 (page 2-4) shows how the standard dialog box displays both the original and the new colors.

Defining an Event Filter Function
Applications can generally allow the Color Picker Manager to handle all events that might occur while the standard dialog box is displayed. Update events are exceptions to this, however.
The PickColor function calls the Dialog Manager function DialogSelect. As described in the chapter "Dialog Manager" in Inside Macintosh: Macintosh Toolbox Essentials, DialogSelect does not allow background windows to receive update events; therefore, at a minimum, your event filter function should handle update events. If your application needs to filter or preprocess other events before DialogSelect handles them, your application should do so in its event filter function.
As you can see in Listing 2-1, your application should supply the eventProc field of the color picker parameter block with a pointer to an application-defined filter function for handling user events meant for your application. If your filter function returns true, the Color Picker Manager won't process the event any further. If your filter function returns false, the Color Picker Manager handles the event as if it were meant for the color picker. Listing 2-2 illustrates such an event filter function.
Listing 2-2 An event filter function for the PickColor function
pascal Boolean MyPickerEventFilterFunction (EventRecord *event) 
{  /* returning false sends events to the Color Picker Manager */
   Boolean handled = false;
   switch(event->what) 
   {
      case updateEvt:
         DoTheUpdate((WindowPtr) event->message);
         handled = true;
   }
   return handled;
}
Defining a Color-Changed Function
As shown in Listing 2-1, your application can supply the colorProc field of the color picker parameter block with a pointer to an application-defined function that handles color changes. This function, illustrated in Listing 2-3, should support the updating of colors in a document as the user selects them. To support faster feedback as the user changes color, this function doesn't update the application's internal data structures.
Listing 2-3 A color-changed function
pascal void MyColorChangedFunction(long userData, PMColorPtr newColor) 
{
   GrafPtr  port;
   CWorld   cWorld;
   CMColor  color;
   CMError  cwError;

   GetPort(&port);
   SetPort(myDocWindow);
   /* determine whether the color has a profile */
   if(newColor->profile) 
   {
      /* convert the color to an RGB color */
      cwError = CWNewColorWorld(&cWorld, newColor->profile, 0L);
      if(cwError == noErr || cwError == CMProfilesIdentical) 
      {
         color = newColor->color;
         CWMatchColors(cWorld, &color, 1);
         CWDisposeColorWorld(cWorld);
      }
   } 
   else
      color.rgb = newColor->color.rgb;
   /* change the color of currently highlighted objects */
   MyChangeHighlight(&color.rgb);
   SetPort(port);
}
In this example, it is assumed that ColorSync is installed because the application sets the AppIsColorSyncAware flag when calling PickColor. Because a non-RGB color might come back from the color picker, this example uses ColorSync 1.0 functions to convert the color to an RGB color.