TweetFollow Us on Twitter

September 94 - Pick Your Picker With Color Picker 2.0

Pick Your Picker With Color Picker 2.0


[IMAGE 068-084_Holland_final_ht1.GIF]

The limitations of the old Color Picker Package forced many developers to write their own color pickers. The flexibility of Color Picker version 2.0 overcomes the old limitations and provides many new features -- most notably, use with ColorSync color. Now it's easy to design color pickers to suit your needs. This article describes how to use the new Color Picker Manager and take advantage of its customization features from within your application.

Apple designed the Color Picker Package as a way for applications to present a standard user interface for color selection. The goal in developing Color Picker version 2.0 was to remain compatible with the existing Color Picker Package while providing tighter integration of color pickers with the application and allowing development of customized color pickers (for example, to support other color spaces or specific devices).

These goals were achieved by adding a Color Picker Manager, turning color pickers into components, and separating the color picker components from the Color Picker Manager. As components, color pickers are now accessed through the Component Manager, which provides a layer between the application and the color picker component. In other words, the application calls the Color Picker Manager, which then calls the Component Manager, which calls the color picker component. In the old Color Picker Package, the application called the color picker directly.

This separation of the color picker components from the Color Picker Manager allows new color picker components to be dynamically added to the system by the user or an application. Once a new color picker component has been registered to the Component Manager, it's available for use by the Color Picker Manager.

The interface to the new Color Picker Manager is divided into high- and low-level calls:

  • The high-level calls are designed to be used with a minimum of fuss, but provide access to nearly the whole feature set available to the application through the Color Picker Manager. For compatibility with previous versions, the old high-level call, GetColor, is still there. A new high-level call, PickColor, replaces GetColor and offers a much broader feature set.
  • The low-level calls are designed to allow maximum flexibility. They let the application determine the type of dialog the color picker is placed in, rather than using the modal dialog you get with high-level calls. The application can also set the current color and maintain explicit control over the event loop. Color pickers that are invoked through the low-level calls can exist for the life of an application. This article discusses how to use these calls and take advantage of the new Color Picker Manager. The code examples are provided on this issue's CD. Color Picker 2.0 allows multiple color picker components to exist on a system at one time (through the Component Manager). Although the interface for these components is public, this article doesn't discuss the creation of color picker components.


Unlike the old Color Picker Package, Color Picker 2.0 uses the more complete ColorSync definition of a color, which contains both a color and a profile. The profile defines the color space of the color (which includes the type of color -- CMYK, HSL, RGB, and so on). You can also specify a destination profile, which describes the color space of the device for which the color is being chosen (for example, a color printer that will eventually print the document). Given knowledge of the destination profile, color pickers that are ColorSync aware can help the user choose a color that's within the destination device's gamut.

ColorSync is described in the forthcoming Inside Macintosh: Advanced Color Imaging . See also "Print Hints: Syncing Up With ColorSync" in develop Issue 14.*

The ColorSync definition for a color, shown below, is used only with the new calls. The old call, GetColor, still uses RGBColor for compatibility. These structures are compatible with QuickDraw GX.

typedef struct CMProfile **CMProfileHandle;

typedef union {
    RGBColor        rgb;
    unsigned short  reserved[4];
} CMColor, *CMColorList;

typedef struct PMColor {
    CMProfileHandle     profile;
    CMColor             color;
} PMColor, *PMColorPtr;

If you're specifying an RGB color with no particular profile, you can simply set the CMProfileHandle field of PMColor to nil, which uses the system profile. To specify a color that uses a profile, you need to provide the profile that describes that color.


The high-level calls are designed to handle the most common uses for the Color Picker Manager. The old GetColor call provides access to the new dialog and the color picker component, but not to any of the new features that are accessible through the Color Picker Manager (such as ColorSync colors).

The new PickColor call is designed to replace GetColor. It can be used very simply, providing roughly the same feature set as GetColor, or it can be used to take advantage of some of the more advanced features of Color Picker 2.0.

The new dialog for the high-level calls is much the same as the old one. A new button, More Choices, reveals a list of all available color pickers (and changes to "Fewer Choices"; see Figure 1). Clicking a color picker in the list makes it the current color picker for the dialog. Both PickColor and GetColor display this dialog.

The biggest difference between PickColor and GetColor is that PickColor allows the application to provide a pointer to an event filter procedure. If the application supplies such a procedure, a movable modal dialog will be created rather than the old modal dialog. You can do this from within PickColor because you're now able to pass update events to windows within the same application layer as the color picker. PickColor also uses the new ColorSync color definition, so you can specify a color in any color space along with a destination profile. Likewise, a color can be returned in any color space.

[IMAGE 068-084_Holland_final_ht2.GIF]

Figure 1. Color picker dialog for high-level calls

Listing 1 shows the parameter block that you pass through to PickColor. The first two fields, theColor and dstProfile, are pretty obvious; they're simply the input (and output) color and the profile for the final output device. If there's no output device, you just set dstProfile to nil.

Listing 1. PickColor parameter block

typedef struct ColorPickerInfo {
    PMColor                 theColor;
    CMProfileHandle         dstProfile;
    long                    flags;
    DialogPlacementSpec     placeWhere;
    Point                   dialogOrigin;
    long                    pickerType;
    UserEventProc           eventProc;
    ColorChangedProc        colorProc;
    long                    colorProcData;
    Str255                  prompt;
    MenuItemInfo            mInfo;
    Boolean                 newColorChosen;
} ColorPickerInfo;

The flags field is a little more complicated. (It's also used in many of the low-level calls.) With PickColor, there are three flags you need to worry about:

  • CanModifyPalette. If you set this flag, you're telling the color picker component that it's able to install a palette of its own that may modify (but not animate) the current color table. If you don't want the colors in your document to change as you make choices in the color picker dialog, don't set this flag.
  • CanAnimatePalette. This flag is similar to CanModifyPalette, except that it allows the color picker component to modify or animate the palette as much as it wants to.
  • AppIsColorSyncAware. This informs the Color Picker Manager that your application understands ColorSync colors. This means that a color may be returned to you in a different space than the one you passed in. For example, you could pass an RGB color (with no profile) to the Color Picker Manager and receive back a CMYK color (with its associated profile). If you don't set this flag, the Color Picker Manager automatically converts any color it receives back from the color picker component to RGB space.

The placeWhere field tells the Color Picker Manager where to position the color picker dialog. The choices are kAtSpecifiedOrigin (at the point specified by the dialogOrigin field), kDeepestColorScreen (centered on the deepest color screen), and kCenterOnMainScreen (centered on the main screen).

The dialogOrigin field (in conjunction with kAtSpecifiedOrigin) is used when you request that the color picker dialog be placed at a specific point. When PickColor returns, this field contains the location of the color picker dialog at the time it was closed.

You use the pickerType field to specify the component subtype of the color picker to select initially. If you set this field to 0, the default system color picker will be used (the last color picker chosen by the user). When PickColor returns, this field contains the component subtype of the color picker that was open when the user closed the dialog.

You should set the eventProc field to point to an event filter procedure that will handle events meant for your application. If this procedure returns true, the Color Picker Manager won't process the event further. If it returns false, the Color Picker Manager will handle the event if it was meant for the color picker. If you set this field to nil, a modal dialog will be created (rather than a movable modal dialog).

The colorProc field can contain a pointer to a procedure that will be called whenever the color changes. This allows live updating of colors in application documents as the user selects them. The colorProcData field contains a long integer that's passed to the color-changed procedure and can be used for any private data.

The prompt field is a prompt string that the color picker displays to give the user some indication as to what the new color is for (for example, a highlight color).

The mInfo field tells the Color Picker Manager what the Edit menu ID is and where the various menu items are located within it.

The newColorChosen field is set on return from PickColor. If true, it means that the user chose a color and clicked OK; otherwise, the user clicked Cancel.

Now let's look at an example of how all this would be used. Listings 2 and 3 show two callbacks -- the event filter procedure (MyEventProc) and the color-changed procedure (MyColorChangedProc). In the color-changed procedure we assume that ColorSync is installed. This is because we'll be setting the AppIsColorSyncAware flag when we call PickColor, so a non-RGB color might come back from the picker and, if so, you need to call ColorSync to convert it to RGB.

Listing 2. Event filter procedure

WindowPtr   myDocWindow;

pascal Boolean MyEventProc(EventRecord *event) {
    Boolean     handled = false; // Assume we don't handle the event.

    switch (event->what) {
        case updateEvt:
            // Check to see if the update is for our window.
            if ((WindowPtr) event->message == myDocWindow) {
                handled = true;
    return handled;

Listing 3. Color-changed procedure

pascal void MyColorChangedProc(long userData, PMColorPtr newColor) {
    GrafPtr     port;
    CWorld      cWorld;
    CMColor     color;
    CMError     cwError;

    // Now check to see if the color has a profile. If so, we need to
    // convert it to RGB space.
    if (newColor->profile) {
        // Create a color world and convert the color. This color
        // world matches from the color's space to the system space
        // (RGB).
        cwError = CWNewColorWorld(&cWorld, newColor->profile, 0L);
        if (cwError == noErr || cwError == CMProfilesIdentical) {
            // We created the color world. Now match the color using
            // a copy so that we don't munge the original.
            color = newColor->color;
            CWMatchColors(cWorld, &color, 1);
    } else
        color.rgb = newColor->color.rgb;

    // Set the new color and paint the port with it.
    myRGBColor = color.rgb;


Once you have the two callback procedures, you can go ahead and call PickColor (see Listing 4). Listing 4. Calling PickColor

ColorPickerInfo     cpInfo;
PMColor             savedColor;

// Set the input color to be an RGB color in system space.
cpInfo.theColor.color.rgb = myRGBColor;
cpInfo.theColor.profile = 0L;

cpInfo.dstProfile = 0L;
cpInfo.flags =
    AppIsColorSyncAware | CanModifyPalette | CanAnimatePalette;

// Center the picker on the deepest color screen.
cpInfo.placeWhere = kDeepestColorScreen;

// Use the default picker.
cpInfo.pickerType = 0L;

// Install the callbacks.
cpInfo.eventProc = MyEventProc;
cpInfo.colorProc = MyColorChangedProc;
cpInfo.colorProcData = 0L;

strcpy(cpInfo.prompt,"\pChoose a new color");
// Tell the Color Picker Manager about the Edit menu.
cpInfo.mInfo.editMenuID = kMyEditMenuID;
cpInfo.mInfo.cutItem = kMyCutItem;
cpInfo.mInfo.copyItem = kMyCopyItem;
cpInfo.mInfo.pasteItem = kMyPasteItem;
cpInfo.mInfo.clearItem = kMyClearItem;
cpInfo.mInfo.undoItem = kMyUndoItem;

// Save the current color, in case the user cancels.
savedColor = cpInfo.theColor;

// And finally, pick that color!
if (PickColor(&cpInfo) == noErr && cpInfo.newColorChosen)
    // Go use this new color. Remember it can be in any color space.
    // Canceled or an error; restore old color.


The low-level Color Picker Manager calls are designed to allow tight integration of an application and a color picker (a floating palette, for example). Two features make this possible: the application can specify the type of dialog to put the color picker in, and the application maintains control over the event loop.

You can create three types of color picker dialogs with the low-level calls: system-owned, application- owned, and color picker-owned.

  • A system-owned dialog is exactly like the dialog created by the high-level calls -- it has OK, Cancel, and More Choices buttons. However, with the low-level calls, you can make the dialog modal, movable modal, or modeless.
  • An application-owned dialog is actually owned (and supplied) by the application. You can use this type of dialog to integrate the color picker with other application window features or to extend the controls of the color picker. For example, you could add controls for altering the style of an object as well as its color.
  • A color picker-owned dialog is created and owned by the color picker component itself, which gives that component great flexibility because it can determine the size and shape of the color picker and the dialog (color pickers in system-owned and application-owned dialogs are always the same size). This is useful for implementing floating pickers (such as the color wheel in Color MacCheese).

The application interacts with all three types of dialogs in the same way once they're created. The rest of this section describes how to create each type and then moves on to discuss how the application interacts with the color pickers, no matter what type of dialog you use. In other words, the type of dialog a color picker is in is abstracted enough that the application can use roughly the same code to handle all three types.

When creating a system-owned dialog, the application needs to choose whether the dialog will be modal, movable modal, or modeless. This is handled by the use of two flags: DialogIsModal and DialogIsMoveable. Through obvious combinations of these flags, all three dialog types can be created. A nonmovable, modeless dialog (neither flag set) is illegal.

Listing 5 shows the code used to create a modeless system-owned dialog.

Listing 5. Creating a modeless system-owned dialog

SystemDialogInfo    sInfo;
OSErr               result;

sInfo.flags = DialogIsMoveable + AppIsColorSyncAware
    + CanModifyPalette + CanAnimatePalette;
sInfo.pickerType = 0L;
sInfo.placeWhere = kDeepestColorScreen;

sInfo.mInfo.editMenuID = kMyEditMenuID;
sInfo.mInfo.cutItem = kMyCutItem;
sInfo.mInfo.copyItem = kMyCopyItem;
sInfo.mInfo.pasteItem = kMyPasteItem;
sInfo.mInfo.clearItem = kMyClearItem;
sInfo.mInfo.undoItem = kMyUndoItem;

result = CreateColorDialog(&sInfo, &myPicker);

Listing 6 shows how to add a color picker to an application's own dialog (application-owned dialog).

Listing 6. Creating an application-owned dialog

DialogPtr               myDialog;
ApplicationDialogInfo   aInfo;
OSErr                   result;

// First create the dialog (make sure it's a color dialog so that the
// color picker can do all the color stuff it needs to do!).
myDialog = GetNewDialog(kMyDialogID, nil, (WindowPtr)-1);

// Set up the ApplicationDialogInfo structure.
aInfo.flags = DialogIsMoveable + AppIsColorSyncAware
    + CanModifyPalette + CanAnimatePalette;
aInfo.pickerType = 0L;
aInfo.theDialog = myDialog;

// Put the color picker's origin at (0,0) in the dialog.
aInfo.pickerOrigin.h = 0;
aInfo.pickerOrigin.v = 0;

// Set the Edit menu information.
aInfo.mInfo.editMenuID = kMyEditMenuID;
aInfo.mInfo.cutItem = kMyCutItem;
aInfo.mInfo.copyItem = kMyCopyItem;
aInfo.mInfo.pasteItem = kMyPasteItem;
aInfo.mInfo.clearItem = kMyClearItem;
aInfo.mInfo.undoItem = kMyUndoItem;

// Finally, add the color picker to the dialog.
result = AddPickerToDialog(&aInfo, &myPicker);

Listing 7 shows how to create a color picker-owned dialog. As you can see, the code to create all three types of dialogs is nearly identical. Likewise the code to manage them after creation is very similar. Any explicit differences or requirements will be pointed out and explained as they're encountered.

Listing 7. Creating a color picker-owned dialog

PickerDialogInfo    pInfo;
OSErr               result;

pInfo.flags = DialogIsMoveable + AppIsColorSyncAware
    + CanModifyPalette + CanAnimatePalette;
pInfo.pickerType = 0L;

pInfo.mInfo.editMenuID = kMyEditMenuID;
pInfo.mInfo.cutItem = kMyCutItem;
pInfo.mInfo.copyItem = kMyCopyItem;
pInfo.mInfo.pasteItem = kMyPasteItem;
pInfo.mInfo.clearItem = kMyClearItem;
pInfo.mInfo.undoItem = kMyUndoItem;

result = CreatePickerDialog(&pInfo, &myPicker);

One of the most obvious requirements for making a color picker useful is that there be a way to set and get the current color. This is very simple. Complexities arise only if you need to convert colors from the space they're returned in to a space you can understand (such as RGB). The following examples assume you're familiar enough with ColorSync to do this (Listing 2 shows how to convert from any space to system RGB space). If you don't want to deal with this, don't set the AppIsColorSyncAware flag and the Color Picker Manager will automatically convert any color it gets back from the color picker to RGB.

The concepts of original color and new color have been carried through from the old Color Picker Package to the new Color Picker Manager. Simply put, theoriginal color is the color that the user is about to change and thenew color is the color to which the user changes it. When setting the color for a color picker, you need to set both colors. Suppose, for example, that you're writing an object-based paint program and have created a floating color picker. When the user clicks an object, you want the color picker to show the color of that object. You would do this by setting the original color and new color for the color picker to the current color of that object. As the user changes the color of the object, the original color would remain the same and the new color would change. This gives feedback as to what would happen if the user were to cancel the color change. The code to do this is very simple:

void SetPickerToColor(RGBColor *rgb) {
    PMColor  aColor;
    aColor.color.rgb = *rgb;
    aColor.profile = 0L;
    SetPickerColor(myPicker, kOriginalColor, &aColor);
    SetPickerColor(myPicker, kNewColor, &aColor);

Whenever the user changes the current color, you need to be able to get the new color so that you can update your object accordingly:

void GetCurrentColor(RGBColor *rgb) {
    PMColor  aColor;
    GetPickerColor(myPicker, kNewColor, &aColor);
    *rgb = aColor.color.rgb;

Some of you might be saying, "But wait, this example is stupid. Isn't that what the color-changed callback is for?" The answer is yes, in the modal case, when the color-changed procedure is the only way the application knows that the color changed. In the modeless case, as we'll see below in the section "Giving Events to the Color Picker," the application is informed in other ways when the color changes. So in the modeless case, you might want to view the colors that the color-changed procedure provides you with as temporary colors and not update your internal data until the user has actually chosen a color (or at least stopped dragging on a slider). You should then make an explicit call to the Color Picker Manager to get the color, and update your internal data.

If you're picking a color for an output device for which you have a ColorSync profile, you can give this profile to the color picker component so that it can communicate the profile's information to the user (assuming it knows how). You do this with a simple call, SetPickerProfile. There's also a matching call, GetPickerProfile, to get the current profile from the color picker. It's important to remember that the application owns the memory of any profiles it gives or receives from the color picker. When you set the destination profile, the color picker component makes a copy of the profile handle; when you get the destination profile, you give the color picker component a handle into which it copies the profile data. The following code shows how to set and get the destination profile. Setting it is optional; the color picker assumes that there's no profile unless you explicitly set one.

void SetDestinationProfile(CMProfileHandle profile) {
    if (SetPickerProfile(myPicker, profile) != noErr)

void GetDestinationProfile(CMProfileHandle profile) {
    if (GetPickerProfile(myPicker, profile) != noErr)

The basic model for giving events to the color picker is similar to DialogSelect. For the most part, you give the event to the Color Picker Manager through the DoPickerEvent call. It either handles the event or returns it to the application for the application to handle.

There's one exception to this rule: menus. If you've created a modal system dialog, the Color Picker Manager can handle the Edit menu events for you (as it does when you call PickColor). However, for modeless color pickers there are many menu items that the Color Picker Manager has no idea how to handle. If you do send these events through to the Color Picker Manager, it will assume all Edit menu selections are meant for the color picker and ignore everything else. Therefore, with modeless dialogs, the application needs to be sure to handle its own menu events before calling DoPickerEvent.

You'll also need to do some extra work in order for the Color Picker Manager to handle the Edit menu correctly. If an Edit menu choice will be for the color picker (that is, the color picker dialog is frontmost and the current text item in the dialog belongs to the color picker), you need to set up the Edit menu as the Color Picker Manager and color picker component want it. To determine how they want the Edit menu, call GetPickerEditMenuState. If the user does choose an Edit menu item, the application needs to call DoPickerEdit to tell the Color Picker Manager which edit operation to perform. There's more on this later under "Handling the Edit Menu."

Each time you call DoPickerEvent and the color picker component or the Color Picker Manager handles the event, it returns a constant describing what happened. There are several possible results, which are listed in Table 1.

Table 1. DoPickerEvent return constants

kDidNothingNothing happened that's worth reporting.
kColorChangedThe user changed the color; you may need to call GetPickerColor to get the new color.
kOKHitThe user clicked OK; returned only by system- or color picker-owned dialogs.
kCancelHitThe user clicked Cancel; returned only by system- or color picker- owned dialogs.
kNewPickerChosenThe user chose a new color picker from the More Choices list; returned only by system-owned dialogs.
kApplItemHitThe Dialog Manager returned an item intended for one of the application's dialog items; returned only by application-owned dialogs.

Internally, the Color Picker Manager handles the event by calling DialogSelect and then processing the event from there. If the color picker is in an application dialog and an application item is selected, the Color Picker Manager returns kApplItemHit as well as the item number.

There are a few things to keep in mind regarding the DoPickerEvent return constants. How you handle kColorChanged with application dialogs depends on your application; for system-owned and color picker-owned dialogs you probably should wait until the user clicks OK before treating the color as final. With kOKHit, you should save the new color and close the dialog. With kCancelHit, you should restore the old color and dispose of the color picker. If kApplItemHit is returned, you need to handle the event as you would for the Dialog Manager. You don't need to care about kNewPickerChosen, which happens only with a system-owned dialog.

If you have a color-changed procedure for the color picker to call, you supply the procedure, along with any data it needs to be called with, to DoPickerEvent.

Listing 8 shows what your event loop might look like. In this code we assume that you always want to handle the menu events yourself, as discussed above. Listing 8. Sample event loop

#define IsMenuKey(x)    ((x)->what == keyDown && \
                        (x)->modifiers & cmdKey)
Boolean SampleDoEvent(EventRecord *event) {
    Boolean     handled = false, isMenuEvent = false;
    EventData   pEvent;
    short       inWhere;
    WindowPtr   whichWindow;

    // We are assuming that the application always wants to handle
    // menus.
    if (event->what == mouseDown) {
        inWhere = FindWindow(event->where, &whichWindow);
        if (inWhere == inMenuBar)
            isMenuEvent = true;
    if (isMenuEvent || IsMenuKey(event)) {
        handled = true;
    // If the event's not handled yet, call the Color Picker Manager
    // to give it a shot.
    if (!handled) {
        pEvent.event = event;
        pEvent.colorProc = MyModelessColorChangedProc;
        pEvent.colorProcData = 0L;
        DoPickerEvent(myPicker, &pEvent);
        handled = pEvent.handled;

        // If the color picker handled it, we might want to do
        // something with the results.
        if (handled) {
            switch (pEvent.action) {
                case kDidNothing:
                case kColorChanged:
                case kOKHit:
                    myPicker = nil;
                case kCancelHit:
                    myPicker = nil;
                case kNewPickerChosen:
                    // You shouldn't care about this.

                case kApplItemHit:
                    // Handle the item as you would for the Dialog
                    // Manager.
    if (!handled) {
        // The event hasn't been handled. Treat it as you would any
        // normal Macintosh event. If you have other dialogs, you
        // need to call DialogSelect. Remember, if the event is a
        // mouseDown, you already called FindWindow!
    return handled;

When dealing with a color picker, you'll sometimes need to warn it about a user action that might affect it. For example, if you have a color picker in an application dialog and the user closes that dialog, you might want to see if the color picker is in a state that can handle this. If the user had just typed some numbers into the color picker that left it in an inconsistent state, it would be nice if the color picker could have a chance to complain to the user before it was indiscriminately closed.

You can do this by usingforecast events. These aren't really events in themselves, butare warnings to the color picker. To send forecast events to the color picker component,you use the same call as for regular events -- DoPickerEvent -- except that you set the event field to nil and set the forecast field to an appropriate constant. The color picker component tells you whether it's ready for the action to occur by setting the handled field of the EventData structure to true if it's not ready and false if it is.

For the most part, the only time your application needs to worry about this is when the color picker is about to be closed. If the Color Picker Manager has instigated theclosing (such as when the action field is set to kOKHit after you called DoPickerEvent),you don't need to worry about telling the color picker component because the Color Picker Manager has already done so. However, if the user has just clicked the window's close box (for an application dialog) or has chosen Close from a menu, you should send a forecast event to the color picker component.

The following example shows a function called CheckIfPickerCanClose. If this function returns true, the color picker can close; otherwise, it can't close for some reason. It's safe to assume that the color picker has informed the user of the problem.

Boolean CheckIfPickerCanClose() {
    EventData  pEvent;
    pEvent.event = 0L;      // Make it a forecast event.
    pEvent.forcast = kDialogAccept;
    DoPickerEvent(myPicker, &pEvent);
    return !pEvent.handled;

As mentioned earlier, the Edit menu takes some special work. In addition to standard menu processing, if an Edit menu choice will be for the color picker, you need to set the state of the Edit menu items according to the color picker specifications and, if an Edit menu item is chosen, send the appropriate message to the color picker. This is done through two simple calls: GetPickerEditMenuState and DoPickerEdit.

Once you've determined that there has been a mouse-down event in the menu bar or a keyboard equivalent has been pressed, you need to determine who owns the Edit menu. If the color picker is in a color picker-owned or system-owned dialog and it's frontmost, the color picker obviously owns it. If the color picker is in an application-owned dialog and it's frontmost, ownership of the Edit menu depends on the current item. The choice really depends on your application. As a general rule, whoever owns the current item owns the Edit menu. If you do call DoPickerEdit while the current item belongs to your application, it will implement the standard cut, copy, paste, and clear features for you. If your application needs to do more than this, you'll need to handle it yourself. In Listing 9 we assume that the owner of the current item owns the Edit menu. The item number for the application's last dialog item is kMyLastItem. If you have a system-owned or color picker-owned dialog, this constant should be set to 0. In an application-owned dialog the picker's items will always be added after the application's, so your item numbers remain the same.

Listing 9. Handling the Edit menu

Boolean DoMenu(EventRecord *event) {
    long            mChoice;
    EditData        eData;
    EditOperation   eOperation;

    // If picker is in front and current edit item is the picker's,
    // set up the Edit menu the way the picker wants it.
    if (FrontWindow() == myDialog &&
            ((DialogPeek)myDialog)->editField + 1 > kMyLastItem) {
        MenuState       mState;
        MenuHandle      theMenu;
        GetPickerEditMenuState(myPicker, &mState);
        theMenu = GetMenu(kMyEditMenuID);
        if (mState.cutEnabled)
            EnableItem(theMenu, kMyCutItem);
            DisableItem(theMenu, kMyCutItem);
        if (mState.copyEnabled)
            EnableItem(theMenu, kMyCopyItem);
            DisableItem(theMenu, kMyCopyItem);
        if (mState.pasteEnabled)
            EnableItem(theMenu, kMyPasteItem);
            DisableItem(theMenu, kMyPasteItem);
        if (mState.clearEnabled)
            EnableItem(theMenu, kMyClearItem);
            DisableItem(theMenu, kMyClearItem);
        if (mState.undoEnabled) {
            SetItem(theMenu, kMyUndoItem, mState.undoString);
            EnableItem(theMenu, kMyUndoItem);
            DisableItem(theMenu, kMyUndoItem);

    // Give the event to the Menu Manager.
    if (event->what == mouseDown)
        mChoice = MenuSelect(event->where);
        mChoice = MenuKey(event->message);
    // If not the Edit menu, handle normally.
    if (HiWord(mChoice) != kMyEditMenuID) {
        return true;
    switch (LoWord(mChoice)) {
        case kMyCutItem:
            eOperation = kCut;
        case kMyCopyItem:
            eOperation = kCopy;
        case kMyPasteItem:
            eOperation = kPaste;
        case kMyClearItem:
            eOperation = kClear;
        case kMyUndoItem:
            eOperation = kUndo;
            eOperation = -1;
    if (eOperation >= 0) {
        eData.theEdit = eOperation;
        DoPickerEdit(myPicker, &eData);
        // Ignore the results here; assume that the color changed.
    return true;


The Color Picker Manager provides support for Balloon Help. Most applications don't need to do anything special for Balloon Help to work for a color picker in any type of dialog. However, for applications in which you need more control over Balloon Help, you can call ExtractPickerHelpItem to get the balloon for the color picker. It's up to the application to determine whether the cursor is over a color picker's item or one of its own. The best way to do this is to check to see if it's over one of the application items. If so, put up your own balloon; otherwise, call ExtractPickerHelpItem and put up the balloon it returns. ExtractPickerHelpItem will ask the color picker for a balloon and search the color picker's help resource for an appropriate balloon. If it can't find one, it returns the error noHelpForItem.

The hardest part about using ExtractPickerHelpItem is determining which item the cursor is over. Fortunately, there's a Dialog Manager call, FindDItem, that does the dirty work for you. Listing 10 shows how you would use these calls. Everything in this example is actually done by the Color Picker Manager internally; the example just gives you a general idea of how to use the ExtractPickerHelpItem call.

Listing 10. Using ExtractPickerHelpItem

void DoBalloonHelp(void) {
    HelpItemInfo    helpInfo;
    short           itemNo;
    Point           where;
    OSErr           err;

    itemNo = FindDItem(myDialog, where) + 1;

    // Go and get the color picker's help item.
    helpInfo.options = 0;
    helpInfo.tip.v = helpInfo.tip.h = 0;
    SetRect(&helpInfo.altRect, 0, 0, 0, 0);
    helpInfo.theProc = 0;
    helpInfo.variant = 0;   
    helpInfo.helpMessage.hmmHelpType = 0;
    helpInfo.helpMessage.u.hmmPictHandle = 0L;
    err = ExtractPickerHelpItem(myPicker, itemNo, 0, &helpInfo);

    // Show the balloon if we found one.
    if (err == noErr) {
        // If altRect is empty, we need to use the item's rectangle.
        if (EmptyRect(&helpInfo.altRect)) {
            short       iType;
            Handle  iHandle;
            GetDItem(myDialog, itemNo, &iType, &iHandle,
        // Convert the tip to dialog coordinates.
        helpInfo.tip.h += helpInfo.altRect.left;
        helpInfo.tip.v +=;
        // Convert the tip and altRect to global coordinates.
        LocalToGlobal((Point *) &;
        LocalToGlobal((Point *) &helpInfo.altRect.bottom);

        // Finally, put the balloon up.
        HMShowBalloon(&helpInfo.helpMessage, helpInfo.tip,
            &helpInfo.altRect, 0L, helpInfo.theProc,
            helpInfo.variant, kHMRegularWindow);


You should now have a general idea of how to use the new Color Picker Manager. Most applications will need only the high-level calls. However, developers who use color more thoroughly may want to take advantage of the low-level calls. The low-level calls were designed to be very flexible and easy to use. The simple implementations shown in this article are trivial; more complicated uses are possible, and shouldn't be much harder to write.

Having experimented with the new features of Color Picker 2.0, you may still want to write your own color picker component -- for example, to implement your own floating color picker. The new Color Picker Manager makes it easier for you to write your own color picker component and allows you to share it among several applications (and make it available for general system use as well).

So take your pick of the color pickers already available through the high-level or low-level calls or move beyond this article to create your own custom color picker component. Either way, you're looking at a colorful future with Color Picker 2.0.

SHANNON HOLLAND, once of Apple and now starting up something elsewhere, had little time to write his bio for this article. His only three activities include working, eating, and sleeping. Once upon a time he had a life in which he enjoyed photography, cultural activities, and abusing his friends.*

Color Picker version 2.0 ships with QuickDraw GX and also with System 7.5. The forthcoming Inside Macintosh: Advanced Color Imaging will describe Color Picker 2.0 in detail. *

Thanks to our technical reviewers Don Moccia, Konstantin Othmer, and David Surovell. *


Community Search:
MacTech Search:

Software Updates via MacUpdate

Dash 3.4.0 - Instant search and offline...
Dash is an API documentation browser and code snippet manager. Dash helps you store snippets of code, as well as instantly search and browse documentation for almost any API you might use (for a full... Read more
RapidWeaver 7.1.7 - Create template-base...
RapidWeaver is a next-generation Web design application to help you easily create professional-looking Web sites in minutes. No knowledge of complex code is required, RapidWeaver will take care of... Read more
Printopia 2.1.22 - Share Mac printers wi...
Run Printopia on your Mac to share its printers to any capable iPhone, iPad or iPod Touch. Printopia will also add virtual printers, allowing you to save print-outs to your Mac and send to apps.... Read more
SteerMouse 5.0 - Powerful third-party mo...
SteerMouse is an advanced driver for USB and Bluetooth mice. It also supports Apple Mighty Mouse very well. SteerMouse can assign various functions to buttons that Apple's software does not allow,... Read more
Arq 5.5.1 - Online backup to Google Driv...
Arq is super-easy online backup for Mac and Windows computers. Back up to your own cloud account (Amazon Cloud Drive, Google Drive, Dropbox, OneDrive, Google Cloud Storage, any S3-compatible server... Read more
Slack 2.3.0 - Collaborative communicatio...
Slack is a collaborative communication app that simplifies real-time messaging, archiving, and search for modern working teams. Version 2.3.0: Note: Now requires OS X 10.8 or later New The app... Read more
Cocktail 10.1 - General maintenance and...
Cocktail is a general purpose utility for macOS that lets you clean, repair and optimize your Mac. It is a powerful digital toolset that helps hundreds of thousands of Mac users around the world get... Read more
Firefox 49.0.2 - Fast, safe Web browser.
Firefox offers a fast, safe Web browsing experience. Browse quickly, securely, and effortlessly. With its industry-leading features, Firefox is the choice of Web development professionals and casual... Read more
Art Text 3.1 - $49.99
Art Text is graphic design software to create stunning illustrations, such as badges, flyers, logos, social headers and icons, text mockups, website graphics and buttons, picture captions, word art,... Read more
AirRadar 3.1.9 - $9.95
With AirRadar, scanning for wireless networks is now easier and more personalized! It allows you to scan for open networks and tag them as favourites or filter them out. View detailed network... Read more

Latest Forum Discussions

See All

WitchSpring2 (Games)
WitchSpring2 1.27 Device: iOS Universal Category: Games Price: $3.99, Version: 1.27 (iTunes) Description: This is the story of Luna, the Moonlight Witch as she sets out into the world. This is a sequel to Witch Spring. Witch Spring 2... | Read more »
4 popular apps getting a Halloween makeo...
'Tis the season for all things spooky. So much, so, in fact, that even apps are getting into the spirt of things, dressing up in costume and spreading jack o' lanterns all about the place. These updates bring frightening new character skins, scary... | Read more »
Pokémon GO celebrates Halloween with can...
The folks behind Pokémon GO have some exciting things planned for their Halloween celebration, the first in-game event since it launched back in July. Starting October 26 and ending on November 1, trainers will be running into large numbers of... | Read more »
Best Fiends Forever Guide: How to collec...
The fiendship in Seriously's hit Best Fiends has been upgraded this time around in Best Fiends Forever. It’s a fast-paced clicker with lots of color and style--kind of reminiscent of a ‘90s animal mascot game like Crash Bandicoot. The game... | Read more »
5 apps for the budding mixologist
Creating your own cocktails is something of an art form, requiring a knack for unique tastes and devising interesting combinations. It's easy to get started right in your own kitchen, though, even if you're a complete beginner. Try using one of... | Read more »
5 mobile strategy games to try when you...
Strategy enthusiasts everywhere are celebrating the release of Civilization VI this week, and so far everyone seems pretty satisfied with the first full release in the series since 2010. The series has always been about ultra-addictive gameplay... | Read more »
Popclaire talk to us about why The Virus...
Humanity has succumbed to a virus that’s spread throughout the world. Now the dead have risen with a hunger for human flesh, and all that remain are a few survivors. One of those survivors has just called you for help. That’s the plot in POPCLAIRE’... | Read more »
Oceans & Empires preview build sets...
Hugely ambitious sea battler Oceans & Empires is available to play in preview form now on Google Play - but download it quickly, as it’s setting sail away in just a few days. [Read more] | Read more »
Rusty Lake: Roots (Games)
Rusty Lake: Roots 1.1.4 Device: iOS Universal Category: Games Price: $2.99, Version: 1.1.4 (iTunes) Description: James Vanderboom's life drastically changes when he plants a special seed in the garden of the house he has inherited.... | Read more »
Flippy Bottle Extreme! and 3 other physi...
Flippy Bottle Extreme! takes on the bottle flipping craze with a bunch of increasingly tricky physics platforming puzzles. It's difficult and highly frustrating, but also addictive. When you begin to master the game, the sense of achievement is... | Read more »

Price Scanner via

64GB Apple TV on sale for $159, save $40
Best Buy has the 64GB Apple TV on sale for $40 off MSRP on their online store. Choose free shipping or free local store pickup (if available). Sale price for online orders only, in-store price may... Read more
EyeQue Introduces iOS And Android Based Advan...
Affordable vision technologies developers EyeQue have announced what they claim to be the world’s most advanced intelligent vision solution, pitched as enabling anyone, anywhere to easily and... Read more
Smartwatch Market Tanks, Declining 51.6% in 2...
The worldwide smartwatch market experienced a round of growing pains in the third quarter of 2016 (3Q16), resulting in a year-over-year decline in shipment volumes. According to data from the... Read more
CAZE announces Ultra Thin Glass Screen Protec...
Hong Kong based CAZE has announced its first ultra thin glass screen protector, the Glazz Pro for iPhone 7/7 Plus. Glazz Pro is made from chemically reinforced glass with an anti-fingerprint... Read more
11-inch MacBook Airs on sale for up to $120 o...
Newegg has 11″ MacBook Airs on sale for up to $120 off MSRP. Shipping is free: - 11″ 1.6GHz/128GB MacBook Air: $799.99 $100 off MSRP - 11″ 1.6GHz/256GB MacBook Air: $979 $120 off MSRP Read more
Up to $300 off Macs, $20 off iPads with Apple...
Purchase a new Mac or iPad using Apple’s Education Store and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free, and... Read more
Apple’s Thursday “Hello Again” Event A Largel...
KGI Securities analyst Ming-Chi Kuo, who has a strong record of Apple hardware prediction accuracy, forecasts in a new note to investors released late last week that a long-overdue redo of the... Read more
12-inch Retina MacBooks on sale for $100 off...
Amazon has 2016 12″ Apple Retina MacBooks on sale for $100 off MSRP. Shipping is free: - 12″ 1.1GHz Silver Retina MacBook: $1199.99 $100 off MSRP - 12″ 1.1GHz Gold Retina MacBook: $1199.99 $100 off... Read more
Save up to $600 with Apple refurbished Mac Pr...
Apple has Certified Refurbished Mac Pros available for up to $600 off the cost of new models. An Apple one-year warranty is included with each Mac Pro, and shipping is free. The following... Read more
PixelStyle Inexpensive Photo Editor For Mac W...
PixelStyle is an all-in-one Mac Photo Editor with a huge range of high-end filters including lighting, blurs, distortions, tilt-shift, shadows, glows and so forth. PixelStyle Photo Editor for Mac... Read more

Jobs Board

*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Solutions Consultant - Apple (United...
# Apple Solutions Consultant Job Number: 52812872 Houston, Texas, United States Posted: Oct. 18, 2016 Weekly Hours: 40.00 **Job Summary** As an Apple Solutions Read more
Lead *Apple* Solutions Consultant - Apple (...
# Lead Apple Solutions Consultant Job Number: 52812906 Houston, Texas, United States Posted: Oct. 18, 2016 Weekly Hours: 40.00 **Job Summary** The Lead ASC is an Read more
*Apple* Retail - Multiple Positions- Towson,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Software Engineering Intern: Integration / QA...
Job Summary Apple is currently seeking enthusiastic interns who can work full-time for a minimum of 12-weeks between Fall 2015 and Summer 2016. Our software Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.