Color Picker Item

The color picker item lets the user select one color from a palette of 255 choices. It is a small colored square surrounded by a beveled rectangle. It has an optional label that is right-justified next to the left edge of the beveled rectangle. This label is usually omitted since color picker items usually have an associated text item to their left.

When the user presses the data button while the cursor is in the beveled rectangle, a palette of 255 colored squares displays. The user can then select a new color by releasing the data button while the cursor is in one of the 255 squares. If the user releases the data button while the cursor is outside of the popped-up color palette, the current color associated with the color picker item is not changed.

Item list specification

The DialogItemRsc field extent specifies the location of the color picker. The x position specifies the location of the left side of the color picker item's 3D beveled rectangle. The y position specifies both the top of the 3D beveled rectangle. Width and height should be set to 0. Setting them to 0 ensures that the color picker item will look the same in different dialog boxes. The default width or height is the height of the current dialog font.

The type field should be ColorPicker.

The ID determines the DItem_ColorPickerRsc instance to load.

The attributes field can be ON or OFF and optionally combined with HIDDEN. It will usually be ON.

The itemArg field is unused and should usually be set to 0.

The label field can override the label contained in the DItem_ColorPickerRsc instance.

The auxInfo field can currently override only the access string contained in the DItem_ColorPickerRsc instance.

The following is an example of a color picker item list specification:

{{XC, YC, 0, 0}, ColorPicker, COLORPICKERID_ElementColor, ON, 0, "", ""} 

Item resource specification

The color picker item is defined in a resource file with the following structure:

typedef struct ditem_colorpickerrsc 
{ 
    ULong commandNumber; 
    ULong commandSource; 
    long synonymsId; 
    ULong helpInfo; 
    ULong helpSource; 
    long itemHookId; 
    long itemHookArg; 
    long associatedTextId; 
    ULong mask; 
#if defined (resource) 
    char label[]; 
    char accessStr[]; 
#else 
    long labelLength; 
    char label[1]; 
#endif 
} DItem_ColorPickerRsc; 

The DItem_ColorPickerRsc structure has the following unique fields. (See "Common item resource fields" for a description of any field not in this table).

Field	Description
associatedTextId	This field specifies the resource ID of a text item that will be associated with the color picker item. As the user drags the mouse over the popped-up color palette, the associated text item will be dynamically set to the index of the color square the cursor is on.
mask	mask indicates the bits of the variable specified by accessStr that are used to determine the current color index. Usually, mask should be set to NOMASK (defined as 0xFFFFFFFF), which indicates that the entire variable will be used to derive the color index.
accessStr	For a color picker, accessStr specifies a variable used to determine the current color index.

The following is an example of a color picker item resource. Defined in MicroStation's resource file, this item is used in the Element Attributes dialog box.

DItem_ColorPickerRsc COLORPICKERID_ElementColor=
{
    CMD_ACTIVE_COLOR, MCMD, SYNONYMID_ElementColor, NOHELP, MHELP,
    NOHOOK, NOARG, TEXTID_ElementColor, NOMASK, "","tcb->symbology.color"
};

Item hook function messages

The following messages are sent to item hook functions that are attached to color picker items:

  DITEM_MESSAGE_CREATE
  DITEM_MESSAGE_INIT
  DITEM_MESSAGE_DESTROY
  DITEM_MESSAGE_BUTTON
  DITEM_MESSAGE_SYNCHRONIZE
  DITEM_MESSAGE_GETSTATE
  DITEM_MESSAGE_SETSTATE
  DITEM_MESSAGE_STATECHANGED
  DITEM_MESSAGE_QUEUECOMMAND

Color picker item functions

Function	Description
mdlDialog_colorPickerGetInfo	retrieves detailed information about a color picker item.
mdlDialog_colorPickerSetInfo	sets various aspects of a color picker item.
mdlDialog_colorPickerSetColortable	sets the color table in the color picker.