Control Manager Data Types

The following Control Manager data types are new, changed, or not recommended with Appearance Manager 1.0:

ControlFontStyleRec

You can use the ControlFontStyleRec type to specify a control's font. You pass a pointer to the control font style structure in the inStyle parameter of SetControlFontStyle to specify a control's font. If none of the flags in the flags field of the structure are set, the control uses the system font unless the control variant kControlUsesOwningWindowsFontVariant has been specified, in which case the control uses the window font. The ControlFontStyleRec type is available with Appearance Manager 1.0 and later.

Note that if you wish to specify the font for controls in a dialog box, you should use a dialog font table resource, which is automatically read in by the Dialog Manager.

Field descriptions

flags: A signed 16-bit integer specifying which fields of the structure should be applied to the control; see Control Font Style Flag Constants . If none of the flags in the flags field of the structure are set, the control uses the system font unless the control variant kControlUsesOwningWindowsFontVariant has been specified, in which case the control uses the window font.
font: If the kControlUseFontMask bit is set, then this field contains a value specifying the ID of the font family to use. If this bit is not set, then the system default font is used. A meta font constant can be specified instead; see Meta Font Constants .
size: If the kControlUseSizeMask bit is set, then this field contains a value specifying the point size of the text. If the kControlAddSizeMask bit is set, this value will represent the size to add to the current point size of the text. A meta font constant can be specified instead; see Meta Font Constants .
style: If the kControlUseFaceMask bit is set, then this field contains a value specifying which styles to apply to the text. If all bits are clear, the plain font style is used. The bit numbers and the styles they represent are
mode: If the kControlUseModeMask bit is set, then this field contains a value specifying how characters are drawn in the bit image. See Inside Macintosh: Imaging With QuickDraw for a discussion of transfer modes.
just: If the kControlUseJustMask bit is set, then this field contains a value specifying text justification. Possible values are teFlushDefault (0), teCenter (1), teFlushRight (-1), and teFlushLeft (-2).
foreColor: If the kControlUseForeColorMask bit is set, then this field contains an RGB color value to use when drawing the text.
backColor: If the kControlUseBackColorMask bit is set, then this field contains an RGB color value to use when drawing the background behind the text. In certain text modes, background color is ignored.

	Bit value	Style
	0	Bold
	1	Italic
	2	Underline
	3	Outline
	4	Shadow
	5	Condensed
	6	Extended

ControlButtonContentInfo

You can use the ControlButtonContentInfo structure to specify the content for a bevel button or image well. Values of type ControlButtonContentInfo are set via SetControlData and obtained from GetControlData , in conjunction with the kControlBevelButtonContentTag and kControlImageWellContentTag constants; see Control Data Tag Constants . The ControlButtonContentInfo type is available with Appearance Manager 1.0 and later.



 
struct ControlButtonContentInfo {

    ControlContentType contentType;

    union {

        SInt16      resID;

        CIconHandle cIconHandle;

        Handle      iconSuite;

        Handle      iconRef;

        PicHandle   picture;

    } u;

};

typedef struct ControlButtonContentInfo ControlButtonContentInfo;

typedef ControlButtonContentInfo *ControlButtonContentInfoPtr;

contentType: Specifies the bevel button or image well content type and whether the content is text-only, resource-based, or handle-based; see Bevel Button and Image Well Content Type Constants . The value specified in the contentType field determines which of the other fields in the structure are used.
resID: If the content type specified in the contentType field is kControlContentIconSuiteRes , kControlContentCIconRes , or kControlContentPictRes , this field contains the resource ID of a picture, color icon, or icon suite resource.
cIconHandle: If the content type specified in the contentType field is kControlContentCIconHandle , this field contains a handle to a color icon.
iconSuite: If the content type specified in the contentType field is kControlContentIconSuiteHandle , this field contains a handle to an icon suite.
iconRef: If the content type specified in the contentType field is kControlContentIconRef , this field contains an IconRef value. IconRef values are supported under Mac OS 8.5 and later.
picture: If the content type specified in the contentType field is kControlContentPictHandle , this field contains a handle to a picture.

ControlEditTextSelectionRec

You can use the ControlEditTextSelectionRec type to specify a selection range in an editable text control. You pass a pointer to the editable text selection structure to GetControlData and SetControlData to access and set the current selection range in an editable text control. The ControlEditTextSelectionRec type is available with Appearance Manager 1.0 and later.



 
struct ControlEditTextSelectionRec {

    SInt16  selStart;

    SInt16  selEnd;

};

typedef struct ControlEditTextSelectionRec ControlEditTextSelectionRec;

typedef ControlEditTextSelectionRec *ControlEditTextSelectionPtr;

selStart: A signed 16-bit integer indicating the beginning of the editable text selection.
selEnd: A signed 16-bit integer indicating the end of the editable text selection.

ControlTabInfoRec

You can use the ControlTabInfoRec type to specify the icon and title for a tab control. If you are not creating a tab control with a 'tab#' resource, you can call SetControlMaximum to set the number of tabs in a tab control. Then use the functions SetControlData and GetControlData with the ControlTabInfoRec structure to access information for an individual tab in a tab control. The ControlTabInfoRec type is available with Appearance Manager 1.0.1 and later.



 
struct ControlTabInfoRec {

    SInt16  version;

    SInt16  iconSuiteID;

    Str255  name;

};

version: A signed 16-bit integer indicating the version of the tab information structure. The only currently available version value is 0.
iconSuiteID: A signed 16-bit integer indicating the ID of an icon suite to use for the tab label. If the specified ID is not found, no icon is displayed for the tab label. Pass 0 for no icon.
name: A string specifying the title to be used for the tab label.

AuxCtlRec

The auxiliary control structure is not recommend with the Appearance Manager. When the Appearance Manager is available and you are using standard controls, most of the fields of the auxiliary control structure are ignored except the acCTable and acFlags fields. If you are creating your own control definition function, the entire auxiliary control structure can be used.

PopupPrivateData

The pop-up menu private structure is not recommend with the Appearance Manager. When the Appearance Manager is available, you should not access the pop-up menu private data structure. Instead, you should pass the value kControlBevelButtonMenuHandleTag in the tagName parameter of GetControlData to get the menu handle of a bevel button, and the menu handle and the menu ID of the menu associated with a pop-up menu.

CtlCTab

The control color table structure is not recommend with the Appearance Manager. When the Appearance Manager is available and you are using standard controls, the control color table structure is ignored and the colors are determined by the current theme. If you are creating your own control definition function, you can use the control color table structure to draw a control using colors other than the system default.

`'CNTL'`

The control resource is changed with the Appearance Manager to support the additional standard controls that are available with the Appearance Manager. You can use a control ('CNTL' ) resource to define a standard control. All control resources must have resource ID numbers greater than 127 . Use GetNewControl to create a control defined in a control resource. The Control Manager uses the information you specify to create a control structure in memory. Figure 1-1 shows the structure of this resource.

Figure 1-1 Structure of a compiled control ('CNTL') resource

The compiled version of a control resource contains the following elements:

The rectangle, specified in coordinates local to the window, that encloses the control and thus determines its size and location.
The initial setting for the control; see Settings Values for Standard Controls .
The visibility of the control. If this element contains the value true , GetNewControl draws the control immediately, without using the application's standard updating mechanism for windows. If this element contains the value false , the application must use ShowControl when it's prepared to display the control.
Fill. Set to 0.
The maximum setting for the control; see Settings Values for Standard Controls .
The minimum setting for the control; see Settings Values for Standard Controls .
The control definition ID, which the Control Manager uses to determine the control definition function for this control; see Control Definition IDs .
The control's reference value, which is set and used only by the application--except when the application adds the kControlPopupUseAddResMenuVariant variation code to the kControlPopupButtonProc control definition ID.
For controls that need a title, the string for that title; for controls that don't use titles, an empty string.

Note

The titles of all Appearance-compliant standard system controls appear in the system font. You should generally use the system font or small system font in your controls; see Mac OS 8 Human Interface Guidelines for more details.

'cctb'

The control color table resource is not recommend with the Appearance Manager. When the Appearance Manager is available and you are using standard controls, the control color table ('cctb' ) resource is ignored and the colors are determined by the current theme. If you are creating your own control definition function, you can still use the control color table structure to draw a control using colors other than the system default.

'ldes'

You can use a list box description resource to specify information in a list box. A list box description resource is a resource of type 'ldes' . All list box description resources must have resource ID numbers greater than 127. The Control Manager uses the information you specify to provide additional information to the corresponding list box control. The list box description resource is available with Appearance Manager 1.0 and later.

Figure 1-2 shows the structure of this resource.

Figure 1-2 Structure of a compiled list box description ('ldes') resource

You define a list box description resource by specifying these elements:

Version number. An integer specifying the version of the resource format.
Number of rows. An integer specifying the number of rows in the list box.
Number of columns. An integer specifying the number of columns in the list box.
Cell height. An integer specifying the height of a list item. If 0 is specified, the list item height is automatically calculated.
Cell width. An integer specifying the width of a list item. If 0 is specified, the list item width is automatically calculated.
Has vertical scroll bar. A Boolean value that indicates whether the list box should contain a vertical scroll bar. If true , the list box contains a vertical scroll bar; if false , no vertical scroll bar.
Reserved. Set to 0.
Has horizontal scroll bar. A Boolean value that indicates whether the list should contain a horizontal scroll bar. Specify true if your list requires a horizontal scroll bar; specify false otherwise.
Reserved. Set to 0.
Resource ID. This is the resource ID of the list definition procedure to use for the list. To use the default list definition procedure, which supports the display of unstyled text, specify a resource ID of 0.
Has size box. A Boolean value that indicates whether the List Manager should leave room for a size box. If true , a size box will be drawn; if false , a size box will not be drawn.
Reserved. Set to 0.

'tab#'

You can use a tab information resource to specify the icon suite ID and name of each tab in a tab control. A tab information resource is a resource of type 'tab#' . All tab information resources must have resource ID numbers greater than 127. The Control Manager uses the information you specify to provide additional information to the corresponding tab control. The tab information resource is available with Appearance Manager 1.0 and later.

Figure 1-3 shows the structure of this resource.

Figure 1-3 Structure of a compiled tab information ('tab#') resource

A compiled version of a tab information resource contains the following elements:

Version number. An integer specifying the version of the resource.
An integer that specifies the number of entries in the resource (that is, the number of tab information structures).
A series of tab information structures, each of which consists of a 2-byte icon suite identifier and a variable-length string indicating the tab name.

Figure 1-4 shows the format of a compiled entry in a 'tab#' resource. A tab information entry specifies the icon suite ID and the name of a tab control.

Figure 4 Structure of a tab information entry

Each entry in a 'tab#' resource contains the following:

Icon suite ID. A value of 0 indicates no icon.
Tab name. The title of the tab control.
Reserved. Set to 0.
Reserved. Set to 0.

Legacy Document