Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

PATHDocumentation > Mac OS 8 and 9 > Human Interface Toolbox > Control Manager >

Mac OS 8 Control Manager Reference

Accessing and Changing Control Settings and Data

The following Control Manager functions for accessing and changing control settings and data are new, changed, or not recommended with Appearance Manager 1.0:


GetBestControlRect

Obtains a control's optimal size and text placement.

pascal OSErr GetBestControlRect (
                     ControlHandle inControl,
                     Rect *outRect,
                     SInt16 *outBaseLineOffset);
inControl
A handle to the control to be examined.
outRect
Pass a pointer to an empty rectangle (0, 0, 0, 0). On return, the rectangle is set to the optimal size for the control. If the control doesn't support getting an optimal size rectangle, the control's bounding rectangle is passed back.
outBaseLineOffset
Pass a pointer to a signed 16-bit integer value. On return, the value is set to the offset from the bottom of control to the base of the text (usually a negative value). If the control doesn't support optimal sizing or has no text, 0 is passed back.
function result
A result code; see Result Codes .

DISCUSSION

You can call the GetBestControlRect function to automatically position and size controls in accordance with human interface guidelines. This function is particularly helpful in determining the correct placement of control text whose length is not known until run-time. For example, the StandardAlert function uses GetBestControlRect to automatically size and position buttons in a newly created alert box.


VERSION NOTES

Available with Appearance Manager 1.0 and later.


SetControlAction

Sets or changes the action function for a control.

pascal void SetControlAction (
                     ControlHandle theControl,
                     ControlActionUPP actionProc);
theControl
A handle to the control whose action function is to be changed.
actionProc
A universal procedure pointer to an action function defining what action your application takes while the user holds down the mouse button.

DISCUSSION

The SetControlAction function changes the contrlAction field of the control structure to point to the action function specified in the actionProc parameter. If the cursor is in the specified control, HandleControlClick or TrackControl call this action function when the user holds down the mouse button. You must provide the action function, and it must define some action to perform repeatedly as long as the user holds down the mouse button. HandleControlUnderClick and TrackControl always highlight and drag the control as appropriate.

Note

SetControlAction should be used to set the application-defined action function for providing live feedback for standard system scroll bar controls.


VERSION NOTES

Changed with Appearance Manager 1.0 to support live feedback.


SEE ALSO

MyActionProc .


SetControlColor

Customizes the color table for a control.

When the Appearance Manager is available and you are using standard controls, colors are determined by the current theme. If you are creating your own control definition function, you can still set your own colors with the SetControlColor function.


VERSION NOTES

Not recommended with Appearance Manager 1.0 and later.


SetControlData

Sets control-specific data.

pascal OSErr SetControlData (
                     ControlHandle inControl,
                     ControlPartCode inPart,
                     ResType inTagName,
                     Size inSize,
                     Ptr inData);
inControl
A handle to the control for which data is to be set.
inPart
The part code of the control part for which data is to be set; see Control Part Code Constants . Passing kControlEntireControl indicates that either the control has no parts or the data is not tied to any specific part of the control.
inTagName
A constant representing the control-specific data you wish to set; see Control Data Tag Constants .
inSize
The size (in bytes) of the data pointed to by the inData parameter. For variable-length control data, pass the value returned in the outMaxSize parameter of GetControlDataSize in the inSize parameter. The number of bytes must match the actual data size.
inData
A pointer to a buffer allocated by your application. This buffer contains the data that you are sending to the control. After calling SetControlData , your application is responsible for disposing of this buffer, if necessary, as information is copied by control.
function result
A result code; see Result Codes . The result code errDataNotSupported indicates that the inTagName parameter is not valid.

DISCUSSION

The SetControlData function sets control-specific data represented by the value in the inTagName parameter to the data pointed to by the inData parameter. SetControlData could be used, for example, to switch a progress indicator from a determinate to indeterminate state. For a list of the control attributes that can be set, see Control Data Tag Constants .


VERSION NOTES

Available with Appearance Manager 1.0 and later.


SEE ALSO

GetControlData .


GetControlData

Obtains control-specific data.

pascal OSErr GetControlData (
                     ControlHandle inControl,
                     ControlPartCode inPart,
                     ResType inTagName,
                     Size inBufferSize,
                     Ptr inBuffer,
                     Size *outActualSize);
inControl
A handle to the control to be examined.
inPart
The part code of the control part from which data is to be obtained; see Control Part Code Constants . Passing kControlEntireControl indicates that either the control has no parts or the data is not tied to any specific part of the control.
inTagName
A constant representing the control-specific data you wish to obtain; see Control Data Tag Constants .
inBufferSize
The size (in bytes) of the data pointed to by the inBuffer parameter. For variable-length control data, pass the value returned in the outMaxSize parameter of GetControlDataSize in the inBufferSize parameter. The number of bytes must match the actual data size.
inBuffer
Pass a pointer to a buffer allocated by your application. On return, the buffer contains a copy of the control-specific data. If you pass nil on input, it is equivalent to calling GetControlDataSize . The actual size of the control-specific data will be returned in the outActualSize parameter. For variable-length data, the number of bytes must match the actual data size.
outActualSize
Pass a pointer to a Size value. On return, the value is set to the actual size of the data.
function result
A result code; see Result Codes . The result code errDataNotSupported indicates that the inTagName parameter is not valid.

DISCUSSION

The GetControlData function will only copy the amount of data specified in the inBufferSize parameter, but will tell you the actual size of the buffer so you will know if the data was truncated.


VERSION NOTES

Available with Appearance Manager 1.0 and later.


SEE ALSO

SetControlData .


GetControlDataSize

Obtains the size of a control's tagged data.

pascal OSErr GetControlDataSize (
                     ControlHandle inControl,
                     ControlPartCode inPart,
                     ResType inTagName,
                     Size *outMaxSize);
inControl
A handle to the control to be examined.
inPart
The part code of the control part with which the data is associated; see Control Part Code Constants . Passing kControlEntireControl indicates that either the control has no parts or the data is not tied to any specific part of the control.
inTagName
A constant representing the control-specific data whose size is to be obtained; see Control Data Tag Constants .
outMaxSize
Pass a pointer to a Size value. On return, the value is set to the size (in bytes) of the control's tagged data. This value should be passed to SetControlData and GetControlData to allocate a sufficiently large buffer for variable-length data.
function result
A result code; see Result Codes . The result code errDataNotSupported indicates that the inTagName parameter is not valid.

DISCUSSION

Pass the value returned in the outMaxSize parameter of GetControlDataSize in the inBufferSize parameter of SetControlData and GetControlData to allocate an adequate buffer for variable-length data.


VERSION NOTES

Available with Appearance Manager 1.0 and later.


GetControlFeatures

Obtains the features a control supports.

pascal OSErr GetControlFeatures (
                     ControlHandle inControl,
                     UInt32 *outFeatures);
inControl
A handle to the control to be examined.
outFeatures
Pass a pointer to an unsigned 32-bit integer value. On return, the value contains a bit field specifying the features the control supports. For a list of the features a control may support, see Specifying Which Appearance-Compliant Messages Are Supported .
function result
A result code; see Result Codes . The result code errMsgNotSupported indicates that the control does not support Appearance-compliant features.

DISCUSSION

The GetControlFeatures function obtains the Appearance-compliant features a control definition function supports, in response to a kControlMsgGetFeatures message.


VERSION NOTES

Available with Appearance Manager 1.0 and later.


SetControlFontStyle

Sets the font style for a control.

pascal OSErr SetControlFontStyle (
                     ControlHandle inControl,
                     const ControlFontStyleRec *inStyle);
inControl
A handle to the control whose font style is to be set.
inStyle
Pass a pointer to a ControlFontStyleRec structure. If the flags field is cleared, the control uses the system font unless the control variant kControlUsesOwningWindowsFontVariant has been specified (control uses window font).
function result
A result code; see Result Codes .

DISCUSSION

The SetControlFontStyle function sets the font style for a given control. To specify the font for controls in a dialog box, it is generally easier to use the dialog font table resource. SetControlFontStyle allows you to override a control's default font (system or window font, depending upon whether the control variant kControlUsesOwningWindowsFontVariant has been specified). Once you have set a control's font with this function, you can cause the control to revert to its default font by passing a control font style structure with a cleared flags field in the inStyle parameter.


VERSION NOTES

Available with Appearance Manager 1.0 and later.


SetControlVisibility

Sets the visibility of a control, and any embedded controls, and specifies whether it should be drawn.

pascal OSErr SetControlVisibility (
                     ControlHandle inControl,
                     Boolean inIsVisible,
                     Boolean inDoDraw);
inControl
A handle to the control whose visibility is to be set.
inIsVisible
A Boolean value indicating whether the control is visible or invisible. If you set this value to true , the control will be visible. If false , the control will be invisible. If you wish to show a control (and latent embedded subcontrols) but do not want to cause screen drawing, pass true for this parameter and false in the inDoDraw parameter.
inDoDraw
A Boolean value indicating whether the control should be drawn or erased. If true , the control's display on the screen should be updated (drawn or erased) based on the value passed in the inIsVisible parameter. If false , the display will not be updated.
function result
A result code; see Result Codes .

DISCUSSION

You should call the SetControlVisibility function instead of setting the contrlVis field of the control structure to set the visibility of a control and specify whether it will be drawn. If the control has embedded controls, SetControlVisibility allows you to set their visibility and specify whether or not they will be drawn. If you wish to show a control but do not want it to be drawn onscreen, pass true in the inIsVisible parameter and false in the inDoDraw parameter.


VERSION NOTES

Available with Appearance Manager 1.0 and later.


IsControlVisible

Returns whether a control is visible.

pascal Boolean IsControlVisible (ControlHandle inControl);
inControl
A handle to the control to be examined.
function result
Returns a Boolean value. If true , the control is visible. If false , the control is hidden.

DISCUSSION

If you wish to determine whether a control is visible, call IsControlVisible instead of testing the contrlVis field of the control structure.


VERSION NOTES

Available with Appearance Manager 1.0 and later.

\xA9 1998 Apple Computer, Inc. – (Last Updated 19 Nov 98)