DISCUSSION

If the specified control is invisible, the ShowControl function makes it visible and immediately draws the control within its window without using your window's standard updating mechanism. If the specified control has embedded controls, ShowControl makes the embedded controls visible as well. If the control is already visible, ShowControl has no effect.

If you call ShowControl on a latent embedded control whose embedder is disabled, the embedded control will be invisible until its embedder control is enabled. For a discussion of latency, see Manipulating Controls .

You can make a control invisible in several ways:

• Specifying its invisibility in the control resource.
• Passing a value of false in the visible parameter of NewControl.
• Calling HideControl .
• Calling SetControlVisibility . The setting takes effect the next time the control is drawn.

SPECIAL CONSIDERATIONS

The ShowControl function draws the control in its window, but the control can still be completely or partially obscured by overlapping windows or other objects.

VERSION NOTES

Changed with Appearance Manager 1.0 to support embedding hierarchies.

HideControl

Makes a visible control, and any latent embedded controls, invisible.

pascal void HideControl (ControlHandle theControl);

theControl

A handle to the control to hide.

DISCUSSION

The HideControl function makes the specified control invisible. This can be useful, for example, before adjusting a control's size and location. It also adds the control's rectangle to the window's update region, so that anything else that was previously obscured by the control will reappear on the screen. If the specified control has embedded controls, HideControl makes the embedded controls invisible as well. If the control is already invisible, HideControl has no effect.

If you call HideControl on a latent embedded control, it would not be displayed the next time ShowControl was called on its embedder control. For a discussion of latency, see Manipulating Controls .

To make the control visible again, you can use the functions ShowControl or SetControlVisibility .

VERSION NOTES

Changed with Appearance Manager 1.0 to support embedding hierarchies.

ActivateControl

Activates a control and any latent embedded controls.

pascal OSErr ActivateControl (ControlHandle inControl);

inControl

A handle to the control to activate. Passing a window's root control activates all controls in that window.

function result

A result code; see Result Codes .

DISCUSSION

The ActivateControl function should be called instead of HiliteControl to activate a specified control and its latent embedded controls. For a discussion of latency, see Manipulating Controls .

You can use ActivateControl to activate all controls in a window by passing the window's root control in the inControl parameter.

If a control definition function supports activate events, it will receive a kControlMsgActivate message before redrawing itself in its active state.

VERSION NOTES

Available with Appearance Manager 1.0 and later.

SEE ALSO

DeactivateControl .

Embedding Controls .

DeactivateControl

Deactivates a control and any latent embedded controls.

pascal OSErr DeactivateControl (ControlHandle inControl);

inControl

A handle to the control to deactivate. Passing a window's root control deactivates all controls in that window.

function result

A result code; see Result Codes .

DISCUSSION

The DeactivateControl function should be called instead of HiliteControl to deactivate a specified control and its latent embedded controls. For a discussion of latency, see Manipulating Controls .

You can use DeactivateControl to deactivate all controls in a window by passing the window's root control in the inControl parameter.

If a control definition function supports activate events, it will receive a kControlMsgActivate message before redrawing itself in its inactive state.

VERSION NOTES

Available with Appearance Manager 1.0 and later.

SEE ALSO

ActivateControl .

Embedding Controls .

IsControlActive

Returns whether a control is active.

pascal Boolean IsControlActive (ControlHandle inControl);

inControl

A handle to the control to be examined.

function result

Returns a Boolean value. If true , the control is active. If false , the control is inactive.

DISCUSSION

If you wish to determine whether a control is active, you should call IsControlActive instead of testing the contrlHilite field of the control structure.

VERSION NOTES

Available with Appearance Manager 1.0 and later.

SendControlMessage

Sends a message to a control definition function.

pascal SInt32 SendControlMessage (
                     ControlHandle inControl,
                     SInt16 inMessage,
                     SInt32 inParam);

inControl

A handle to the control that is to receive a low-level message.

inMessage

A bit field representing the message(s) you wish to send; see Messages .

inParam

The message-dependent data passed in the param parameter of the control definition function.

function result

Returns a signed 32-bit integer which contains varying data depending upon the message sent; see Messages .

DISCUSSION

Your application does not normally need to call the SendControlMessage function. If you have a special need to call a control definition function directly, call SendControlMessage to access and manipulate the control's attributes.

Before calling SendControlMessage , you should determine whether the control supports the specific message you wish to send by calling GetControlFeatures and examining the feature bit field returned. If there are no feature bits returned that correspond to the message you wish to send (for messages 0 through 12), you can assume that all system controls support that message.

VERSION NOTES

Available with Appearance Manager 1.0 and later.

SEE ALSO

MyControlDefProc .