Legacy Document
Important: The information in this document is obsolete and should not be used for new development.
Important: The information in this document is obsolete and should not be used for new development.
Summary of the Color Picker Manager
Constants and Data Types
enum {/* gestalt selector */ gestaltColorPickerVersion = 'cpkr' /* returns version of Color Picker Manager */ }; typedef struct PMColor { CMProfileHandleprofile; /* a handle to a profile */ CMColor color; /* a color-matching structure */ } PMColor,*PMColorPtr; typedef struct PrivatePickerRecord **picker; /* actions returned to the application from DoPickerEvent */ enum PickerAction { kDidNothing, /* no action worth reporting */ kColorChanged, /* user chose different color */ kOkHit, /* user clicked OK */ kCancelHit, /* user clicked Cancel */ kNewPickerChosen, /* user chose new color picker */ kApplItemHit /* Dialog Manager returned an item in an application-owned dialog box */ }; typedef short PickerAction; /* types of colors a picker must maintain */ enum ColorTypes { kOriginalColor, /* the starting color--the one to change */ kNewColor /* the last color selected by the user */ }; typedef short ColorType; /* types of edit operations that are sent with the kEdit message */ enum EditOperations { kCut, /* perform the Cut command */ kCopy, /* perform the Copy command */ kPaste, /* perform the Paste command */ kClear, /* perform the Clear command */ kUndo /* perform the Undo command */ }; typedef short EditOperation; /* Item hit modifiers. These are sent along with the itemHit message and inform the picker of what it was that caused the item hit. */ enum ItemHitModifiers { kMouseDown, /* mouse-down event on item */ kKeyDown, /* key-down event in current edit item */ kFieldEntered, /* tab into an edit field */ kFieldLeft, /* tab out of an edit field */ kCutOp, /* cut in current edit field */ kCopyOp, /* copy in current edit field */ kPasteOp, /* paste in current edit field */ kClearOp, /* clear in current edit field */ kUndoOp /* undo in current edit field */ }; typedef short ItemModifier; /* The dialog placement specifiers. These tell the picker manager where to place the picker dialog (used for system dialogs). */ enum DialogPlacementSpecifiers { kAtSpecifiedOrigin,/* place the top-left corner of the dialog box at the point specified in the dialogOrigin field of the color picker parameter block */ kDeepestColorScreen,/* center the dialog box on the screen with the greatest color depth */ kCenterOnMainScreen/* center the dialog box on the main screen */ }; typedef short DialogPlacementSpec; /* these flags may be set by the app and are passed through to the picker */ #define DialogIsMoveable1 /* the user can move the dialog box */ #define DialogIsModal 2 /* the dialog box is modal */ #define CanModifyPalette4 /* the picker is allowed to install a palette */ #define CanAnimatePalette8 /* the picker is allowed to animate the palette */ #define AppIsColorSyncAware16/* The application is ColorSync aware and can therfore convert colors between spaces (that is, it can accept non-RGB colors) */ /* these flags are set by the Color Picker Manager (overriding any application settings) */ #define InSystemDialog 32 /* the color picker is in a system-owned dialog box */ #define InApplicationDialog64/* the color picker is in an application- owned dialog box */ #define InPickerDialog 128/* the color picker is in its own dialog box */ #define DetachedFromChoices256/* the color picker has been detached from the More Choices list */ /* Color Picker attributes (bits 23 to 0 in the componentFlags field of the component 'thng') */ #define CanDoColor 1 /* the color picker supports Color QuickDraw */ #define CanDoBlackWhite 2 /* the color picker supports Basic QuickDraw */ #define AlwaysModifiesPalette4/* the color picker will modify palette entries on indexed devices */ #define MayModifyPalette 8 /* the color picker will modify palette if told it can */ #define PickerIsColorSyncAware16/* the color picker is ColorSync aware and can accept non-RGB colors */ #define CanDoSystemDialog32/* the color picker supports a system-owned dialog box */ #define CanDoApplDialog 64 /* the color picker supports an application- owned dialog box */ #define HasOwnDialog 128/* the color picker has its own dialog box */ #define CanDetach 256/* the picker can detach from a system-owned dialog box */ typedef struct PickerInitData { short scriptCode; /* script code */ short iconSuiteID; /* resource ID for icon family */ ResType helpResType; /* resource type for help balloon */ short helpResID; /* resource ID for help balloon */ } PickerInitData; /* the application-defined event filter function for DoPickerEvent */ typedef pascal Boolean (*UserEventProc)(EventRecord *event); /* the application-defined function for dynamically changing colors */ typedef pascal void (*ColorChangedProc)(long userData,PMColorPtr newColor); enum EventForcasters { kNoForcast, /* no forecast (e.g., an update event) */ kMenuChoice, /* this event causes a menu to be chosen */ kDialogAccept, /* the dialog box will be accepted */ kDialogCancel, /* the dialog box will be cancelled */ kLeaveFocus, /* the focus will leave the color picker */ kPickerSwitch, /* new color picker chosen in More Choices list */ kNormalKeyDown, /* a normal key down to an edit field */ kNormalMouseDown /* a normal click in the color picker's focus */ }; typedef short EventForcaster; #define PickerComponentType 'cpkr' 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 a pointer to the dialog box; if using the default dialog box, return nil */ kGetItemList, /* return a list of items for dialog box */ kGetColor, /* return original or last chosen color */ kSetColor, /* change original or last chosen 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 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 information about local coordinate system of dialog box */ kExtractHelpItem /* return information about help balloons */ } PickerMessages; typedef struct MenuItemInfo { short editMenuID; /* resource ID of the edit menu */ short cutItem; /* item number of Cut command */ short copyItem; /* item number of Copy command */ short pasteItem; /* item number of Paste command */ short clearItem; /* item number of Clear command */ short undoItem; /* item number of Undo command */ } MenuItemInfo; typedef struct MenuState { Boolean cutEnabled; /* whether Cut menu item is enabled */ Boolean copyEnabled; /* whether Copy menu item is enabled */ Boolean pasteEnabled; /* whether Paste menu item's enabled */ Boolean clearEnabled; /* whether Clear menu item's enabled */ Boolean undoEnabled; /* whether Undo menu item is enabled */ Str255 undoString; /* text for Undo menu item */ } MenuState; typedef struct ColorPickerInfo { /* color picker parameter block */ PMColor theColor; /* a picker color */ CMProfileHandle dstProfile; /* profile for destination device */ long flags; /* color picker flags */ DialogPlacementSpecplaceWhere;/* dialog box placement specifier */ Point dialogOrigin;/* upper-left corner of dialog box */ long pickerType; /* color picker type */ UserEventProc eventProc; /* event filter function */ ColorChangedProc colorProc; /* color change function */ long colorProcData;/* data for color change function */ Str255 prompt; /* color picker prompt */ MenuItemInfo mInfo; /* application's edit menu items */ Boolean newColorChosen;/* whether user changed color */ } ColorPickerInfo; typedef struct SystemDialogInfo { long flags; /* color picker flags */ long pickerType; /* color picker type */ DialogPlacementSpecplaceWhere;/* dialog box placement specifier */ Point dialogOrigin;/* upper-left corner of dialog box */ MenuItemInfo mInfo; /* application's Edit menu items */ } SystemDialogInfo; typedef struct PickerDialogInfo { long flags; /* color picker flags */ long pickerType; /* color picker type */ Point *dialogOrigin; /* upper-left corner of dialog box */ MenuItemInfo mInfo; /* application's menu items */ } PickerDialogInfo; typedef struct ApplicationDialogInfo { long flags; /* color picker flags */ long pickerType; /* color picker type */ DialogPtr theDialog; /* pointer to dialog box */ Point pickerOrigin; /* upper-left corner of dialog box */ MenuItemInfo mInfo; /* application's Edit menu items */ } ApplicationDialogInfo; typedef struct EventData { EventRecord *event; /* an event record */ PickerAction action; /* action performed by color picker */ short itemHit; /* the item number for the item associated with the event */ Boolean handled; /* true if color picker handled event */ ColorChangedProc colorProc; /* application-defined function for changing colors in the document */ long colorProcData;/* data used by application for function in ColorChangedProc field */ EventForcaster forcast; /* event forecaster */ } EventData; typedef struct EditData { EditOperation theEdit; /* the editing operation */ PickerAction action; /* action performed by color picker */ Boolean handled; /* whether action was handled */ } EditData; typedef struct ItemHitData { short itemHit; /* item receiving event */ ItemModifier iMod; /* type of event */ PickerAction action; /* picker's action */ ColorChangedProc colorProc; /* color-changed function */ long colorProcData;/* data for color-changed function */ Point where; /* mouse location */ } ItemHitData; typedef struct HelpItemInfo { long options; /* 'hmnu' options bits */ Point tip; /* tip location */ Rect altRect; /* alternate rectangle */ short theProc; /* res ID of balloon-definition function */ short variant; /* variation code */ HMMessageRecordhelpMessage;/* help message structure */ } HelpItemInfo; typedef unsigned short SmallFract;/* unsigned fraction between 0 and 1 */ enum {MaxSmallFract = 0x0000FFFF};/* Maximum small fract value, as long */ struct HSVColor { SmallFract hue; /* fraction of circle, red at 0 */ SmallFract saturation; /* 0-1, 0 for gray, 1 for pure color */ SmallFract value; /* 0-1, 0 for black, 1 for maximum intensity */ }; typedef struct HSVColor HSVColor; struct HSLColor { SmallFract hue; /* fraction of circle, red at 0 */ SmallFract saturation; /* 0-1, 0 for gray, 1 for pure color */ SmallFract lightness; /* 0-1, 0 for black, 1 for white */ }; typedef struct HSLColor HSLColor; struct CMYColor { SmallFract cyan; /* cyan component */ SmallFract magenta; /* magenta component */ SmallFract yellow; /* yellow component */ }; typedef struct CMYColor CMYColor;Color Picker Manager Functions
Using the Standard Color Picker Dialog Box
pascal OSErr PickColor(ColorPickerInfo *theColorInfo); pascal Boolean GetColor(Point where, Str255 prompt, RGBColor *inColor, RGBColor *outColor):Creating a Customized Color Picker Dialog Box
pascal OSErr CreateColorDialog(SystemDialogInfo *info, picker *thePicker); pascal OSErr CreatePickerDialog(PickerDialogInfo *info, picker *thePicker); pascal OSErr AddPickerToDialog(ApplicationDialogInfo *info, picker *thePicker); pascal OSErr SetPickerVisibility(picker thePicker, short visible); pascal OSErr GetPickerVisibility(picker thePicker, Boolean *visible); pascal OSErr SetPickerPrompt(picker thePicker, Str255 promptString); pascal OSErr GetPickerOrigin(picker thePicker, Point *where); pascal OSErr SetPickerOrigin(picker thePicker, Point where); pascal OSErr DisposeColorPicker(picker thePicker);Handling Events in a Color Picker Dialog Box
pascal OSErr DoPickerEvent(picker thePicker, EventData *data); pascal OSErr DoPickerEdit(picker thePicker, EditData *data); pascal OSErr DoPickerDraw(picker thePicker);Getting Colors From and Setting Colors for a Color Picker
pascal OSErr GetPickerColor(picker thePicker, ColorType whichColor, PMColor *color); pascal OSErr SetPickerColor(picker thePicker, ColorType whichColor, PMColor *color);Getting the Menu State and the Help Balloons for a Color Picker
pascal OSErr GetPickerEditMenuState ( picker thePicker, MenuState *mState); pascal OSErr ExtractPickerHelpItem ( picker thePicker, short itemNo, short whichState, HelpItemInfo *helpInfo);Getting and Setting Color-Matching Profiles for a Color Picker
pascal OSErr GetPickerProfile(picker thePicker, CMProfileHandle *profile); pascal OSErr SetPickerProfile(picker thePicker, CMProfileHandle profile);Converting Colors Among Color Models
pascal void CMY2RGB(const CMYColor *cColor, RGBColor *rColor); pascal void RGB2CMY(const RGBColor *rColor, CMYColor *cColor); pascal void HSL2RGB(const HSLColor *hColor, RGBColor *rColor); pascal void RGB2HSL(const RGBColor *rColor, HSLColor *hColor); pascal void HSV2RGB(const HSVColor *hColor, RGBColor *rColor); pascal void RGB2HSV(const RGBColor *rColor, HSVColor *hColor);Converting Between SmallFract and Fixed Values
pascal SmallFract Fix2SmallFract(Fixed f) pascal Fixed SmallFract2Fix(SmallFract s);Application-Defined Functions
Handling Application-Directed Events in a Color Picker
pascal Boolean MyPickerFilterFunction ( EventRecord *event)Changing Colors in a Document
pascal void MyColorChangedFunction ( long userData, PMColorPtr newColor)Color Picker-Defined Functions
Responding to Creation and Initialization Requests
pascal long MyTestGraphicsWorld(PickerStorageHndl storage, PickerInitData *data); pascal long MyInitPicker(PickerStorageHndl storage, PickerInitData *data); pascal DialogPtr MyGetDialog(PickerStorageHndl storage); pascal long MyDrawPicker(PickerStorageHndl storage); pascal long MySetVisibility(PickerStorageHndl storage, Boolean visible);Responding to Requests to Return and Set Color Picker Information
pascal long MyGetColor(PickerStorageHndl storage, ColorType whichColor, PMColorPtr color); pascal long MySetColor(PickerStorageHndl storage, ColorType whichColor, PMColorPtr color); pascal long MyGetItemList(PickerStorageHndl storage); pascal long MySetBaseItem(PickerStorageHndl storage, short baseItem); pascal long MyGetIconData(PickerStorageHndl storage, PickerIconData *data); pascal long MyGetPrompt(PickerStorageHndl storage, Str255 prompt); pascal long MySetPrompt(PickerStorageHndl storage, Str255 prompt); pascal long MySetOrigin(PickerStorageHndl storage, Point where); pascal CMProfileHandle MyGetProfile ( PickerStorageHndl storage); pascal long MySetProfile(PickerStorageHndl storage, CMProfileHandle profile); pascal long MyGetEditMenuState(PickerStorageHndl storage, MenuState *mState); pascal long MyExtractHelpItem(PickerStorageHndl storage, short itemNo, short whichMsg, HelpItemInfo *helpInfo);Responding to Events in a Color Picker
pascal long MyDoEvent(PickerStorageHndl storage, EventData *data); pascal long MyItemHit(PickerStorageHndl storage, ItemHitData *data); pascal long MyDoEdit (PickerStorageHndl storage, EditData *data);