Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 5 - Control Manager / Control Manager Reference

Data Structures

The Control Color Table Record

By creating a control color table record and using the SetControlColor procedure (described on page 5-94), your application can draw a control that uses colors other than the system default. (Alternatively, you can use nonstandard colors for a control you define in a control resource by creating a control color table resource--described on page 5-114--with the same resource ID as the control resource.) Be aware that controls in nonstandard colors may initially confuse your users.

A control color table record is a data structure of type CtlCTab; it is defined as follows:

TYPE CtlCTab = 
RECORD
   ccSeed:     LongInt;    {reserved; set to 0}
   ccRider:    Integer;    {reserved; set to 0}

   ctSize:     Integer;    {number of ColorSpec records in next }
                           { field; 3 for standard controls}
   ctTable:    ARRAY[0..3] OF ColorSpec;
END;

Field Description

ccSeed

Reserved in control color tables; set to 0.

ccRider

Reserved in control color tables; set to 0.

ctSize

The number of ColorSpec records in the next field. For controls drawn with the standard definition procedure, this field is always 3, because a standard control has three parts: frame, control body, and scroll box for scroll bars, and frame, control body, and text for other controls. If you want to supply ColorSpec records for additional parts, you must define your own controls, as described in "Defining Your Own Control Definition Function" beginning on page 5-102.

ctTable

An array of ColorSpec records. Each ColorSpec record describes the color of a different control part. Here is how a ColorSpec record is defined:

               TYPE ColorSpec = 
               RECORD
                  partIdentifier:   Integer;    {control part}
                  partRGB:          RGBColor;   {color of part}
               END;

The partIdentifier field of the ColorSpec record holds an integer that associates an RGBColor record with a particular part of the control.

Three ColorSpec records are used to describe the parts of buttons, checkboxes, and radio buttons. Here are the constants that are used in the partIdentifier fields of the three ColorSpec records used to describe these controls:

                           {for buttons, checkboxes, and radio buttons}
                           CONST cFrameColor = 0;  {frame color}
                                 cBodyColor = 1;   {fill color for body of }
                                                   { control}
                                 cTextColor = 2;   {text color}

When highlighted, buttons exchange their body and text colors; checkboxes and radio buttons change their appearance without changing colors. All three types indicate deactivation by dimming their text with no change in colors.

A number of ColorSpec records are used to describe the parts
of scroll bars. Here are the constants that are used in the partIdentifier fields of the ColorSpec records used to describe the colors in scroll bars:

CONST
cFrameColor       = 0;  {Used to produce foreground color for scroll arrows }
                        { & gray area}
cBodyColor        = 1;  {Used to produce colors in the scroll box}
cArrowsColorLight = 5;  {Used to produce colors in arrows & scroll bar }
                        { background color}
cArrowsColorDark  = 6;  {Used to produce colors in arrows & scroll bar }
                        { background color}
cThumbLight       = 7;  {Used to produce colors in scroll box}
cThumbDark        = 8;  {Used to produce colors in scroll box}
cHiliteLight      = 9;  {Use same value as wHiliteColorLight in 'wctb'}
cHiliteDark       = 10; {Use same value as wHiliteColorDark in 'wctb'}
cTitleBarLight    = 11; {Use same value as wTitleBarLight in 'wctb'}
cTitleBarDark     = 12; {Use same value as wTitleBarDark in 'wctb'}
cTingeLight       = 13; {Use same value as wTingeLight in 'wctb'}
cTingeDark        = 14; {Use same value as wTingeDark in 'wctb'}

When highlighted, scroll arrows are filled with the foreground color. A deactivated scroll bar shows no scroll box and displays its gray areas in a solid background color with no pattern.

The ColorSpec records for a control can appear in any order. If you include a part identifier that is not found, the Control Manager uses the first ColorSpec record with an identifiable part. If you do not specify a part identifier, the Control Manager uses the default color for that part.

The partRGB field of the ColorSpec record specifies an RGBColor record, which in turn specifies the red, green, and blue values for the part's color. Use three 16-bit unsigned integers to give the intensity values for the three additive primary colors. Here is how the RGBColor record is defined:

               TYPE RGBColor = 
               RECORD
                  red:     Integer; {red value for control part}
                  green:   Integer; {green value for control part}
                  blue:    Integer; {blue value for control part}
               END;

When you create a control color table record, your application should not deallocate it if another control is still using it.

When drawing a control, the standard control definition functions search the linked list of auxiliary control records for the record whose acOwner field points to that control.
If a standard control definition function finds such a record, it uses the color table designated by that record; otherwise, it uses the default system colors. Each control using colors other than the system default has its own auxiliary control record, even if that control uses the same control color table record as another control; two or more auxiliary records can share the same control color table record. (Auxiliary control records are described on page 5-69.)

If you create a control definition function (as explained in "Defining Your Own Control Definition Function" beginning page 5-102), you can use color tables of any desired size and define their contents in any way you wish, except that part indices 1 through 127 are reserved for system definition. Any such nonstandard control definition function should bypass the defaulting mechanism by allocating an explicit auxiliary record for every control it creates.