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

Embedding Controls

This section provides functions that you can use to establish an embedding hierarchy. This can be accomplished in two steps: creating a root control and embedding controls within it.

To embed controls in a window, you must create a root control for that window. The root control is the container for all other window controls. You create the root control in one of two ways--by calling the CreateRootControl function or by setting the appropriate dialog flag. The root control can be retrieved by calling GetRootControl .

The root control is implemented as a user pane control. You can attach any application-defined user pane functions to the root control to perform actions such as hit testing, drawing, handling keyboard focus, erasing to the correct background, and processing idle and keyboard events. For information on how to write these functions, see Defining Your Own User Pane Functions .

Once you have created a root control, newly created controls will automatically be embedded in the root control when you call NewControl or GetNewControl . You can specify that a specific control be embedded into another by calling EmbedControl .

By acting on an embedder control, you can move, disable, or hide groups of items. For example, you can use a blank user pane control as the embedder control for all items in a particular "page" of a tab control. After creating as many user panes as you have tabs, you can hide one and show the next when a tab is clicked. All the controls embedded in the user pane will be hidden and shown automatically when the user pane is hidden and shown.

The Dialog Manager uses AutoEmbedControl to position dialog items in an embedding hierarchy based on both visual containment and the item list resource order. As items are added to a dialog box during creation, controls that already exist in the window will be containers for new controls if they both visually contain the control and have set the kControlSupportsEmbedding feature bit. For this reason, you should place the largest embedder controls at the beginning of the item list resource. As an example, the Dialog Manager would embed radio buttons in a tab control if they visually "fit" inside the tab control, as long as the tab control was already created in a 'DITL' resource and established as an embedder control.

In addition to calling CreateRootControl , you can establish an embedding hierarchy in a dialog box by either setting the feature bit kDialogFlagsUseControlHierarchy in the extended dialog resource or passing it in the inFlags parameter of the Dialog Manager function NewFeaturesDialog . An embedding hierarchy can be created in an alert box by setting the kAlertFlagsUseControlHierarchy bit in the extended alert resource. It is important to note that a preexisting alert or dialog item will become a control if it is in an alert or dialog box that now uses an embedding hierarchy.

The embedding hierarchy enforces drawing order by drawing the embedding control before its embedded controls. Using an embedding hierarchy also enforces orderly hit-testing, since it performs an "inside-out" hit test to determine the most deeply nested control that is hit by the mouse. An embedding hierarchy is also necessary for controls to make use of keyboard focus, the default focusing order for which is a linear progression that uses the order the controls were added to the window. For more details on keyboard focus, see Handling Keyboard Focus .

The following Control Manager functions for embedding controls are new with Appearance Manager 1.0:


CreateRootControl

Creates the root control for a specified window.

pascal OSErr CreateRootControl (
                     WindowPtr inWindow,
                     ControlHandle* outControl);
inWindow
A pointer to the window in which you wish to create a root control.
outControl
Pass a pointer to a ControlHandle value. On return, the ControlHandle value is set to a handle to the root control.
function result
A result code; see Result Codes .

DISCUSSION

The CreateRootControl function creates the root control for a window if no other controls are present. If there are any controls in the window prior to calling CreateRootControl , an error is returned and the root control is not created.

The root control acts as the top-level container for a window and is required for embedding to occur. Once the root control is created, you can call EmbedControl and AutoEmbedControl to embed controls in the root control.

Note

The minimum, maximum, and initial settings for a root control are reserved and should not be changed.


VERSION NOTES

Available with Appearance Manager 1.0 and later.


SEE ALSO

Embedding Controls .


GetRootControl

Obtains a handle to a window's root control.

pascal OSErr GetRootControl (
                     WindowPtr inWindow,
                     ControlHandle* outControl);
inWindow
A pointer to the window to be examined.
outControl
Pass a pointer to a ControlHandle value. On return, the ControlHandle value is set to a handle to the root control.
function result
A result code; see Result Codes .

DISCUSSION

You can call GetRootControl to determine whether or not a root control (and therefore an embedding hierarchy) exists within a specified window. Once you have the root control's handle, you can pass it to functions such as DisposeControl , ActivateControl , and DeactivateControl to apply specified actions to the entire embedding hierarchy.

Note

The minimum, maximum, and initial settings for a root control are reserved and should not be changed.


VERSION NOTES

Available with Appearance Manager 1.0 and later.


SEE ALSO

Embedding Controls .


EmbedControl

Embeds one control inside another.

pascal OSErr EmbedControl (
                     ControlHandle inControl,
                     ControlHandle inContainer);
inControl
A handle to the control to be embedded.
inContainer
A handle to the embedder control.
function result
A result code; see Result Codes .

DISCUSSION

An embedding hierarchy must be established before your application calls the EmbedControl function. If the specified control does not support embedding or there is no root control in the owning window, an error is returned. If the control you wish to embed is in a different window from the embedder control, an error is returned. see Embedding Controls for more details on embedding.


VERSION NOTES

Available with Appearance Manager 1.0 and later.


SEE ALSO

AutoEmbedControl .


AutoEmbedControl

Automatically embeds a control in the smallest appropriate embedder control.

pascal OSErr AutoEmbedControl (
                     ControlHandle inControl,
                     WindowPtr inWindow);
inControl
A handle to the control to be embedded.
inWindow
A pointer to the window in which to embed the control.
function result
A result code; see Result Codes .

DISCUSSION

The Dialog Manager uses AutoEmbedControl to position dialog items in an embedding hierarchy based on both visual containment and the item list resource order. For information on embedding hierarchies in dialog and alert boxes, see Embedding Controls .


VERSION NOTES

Available with Appearance Manager 1.0 and later.


SEE ALSO

EmbedControl .


CountSubControls

Obtains the number of embedded controls within a control.

pascal OSErr CountSubControls (
                     ControlHandle inControl,
                     SInt16* outNumChildren);
inControl
A handle to a control whose embedded controls you wish to count.
outNumChildren
Pass a pointer to a signed 16-bit integer value. On return, the value is set to the number of embedded subcontrols.
function result
A result code; see Result Codes .

DISCUSSION

The CountSubControls function is useful for iterating over the control hierarchy. You can use the count produced to determine how many subcontrols there are and then call GetIndexedSubControl to get each.


VERSION NOTES

Available with Appearance Manager 1.0 and later.


SEE ALSO

Embedding Controls .


GetIndexedSubControl

Obtains a handle to a specified embedded control.

pascal OSErr GetIndexedSubControl (
                     ControlHandle inControl,
                     SInt16 inIndex,
                     ControlHandle* outSubControl);
inControl
A handle to an embedder control.
inIndex
A 1-based index--an integer between 1 and the value returned in the outNumChildren parameter of CountSubControls --specifying the control you wish to access.
outSubControl
Pass a pointer to a ControlHandle value. On return, the ControlHandle value is set to a handle to the embedded control.
function result
A result code; see Result Codes . If the index passed in is invalid, the paramErr result code is returned.

DISCUSSION

The GetIndexedSubControl function is useful for iterating over the control hierarchy. Also, the value of a radio group control is the index of its currently selected embedded radio button control. So, passing the current value of a radio group control into GetIndexedSubControl will give you a handle to the currently selected radio button control.


VERSION NOTES

Available with Appearance Manager 1.0 and later.


SEE ALSO

Embedding Controls .


GetSuperControl

Obtains a handle to an embedder control.

pascal OSErr GetSuperControl (
                     ControlHandle inControl,
                     ControlHandle* outParent);
inControl
A handle to an embedded control.
outParent
Pass a pointer to a ControlHandle value. On return, the ControlHandle value is set to a handle to the embedder control.
function result
A result code; see Result Codes .

DISCUSSION

The GetSuperControl function gets a handle to the parent control of the control passed in.


VERSION NOTES

Available with Appearance Manager 1.0 and later.


SEE ALSO

Embedding Controls .


SetControlSupervisor

Routes mouse-down events to the embedder control.

pascal OSErr SetControlSupervisor (
                     ControlHandle inControl,
                     ControlHandle inBoss);
inControl
A handle to an embedded control.
inBoss
A handle to the embedder control to which mouse-down events are to be routed.
function result
A result code; see Result Codes .

DISCUSSION

The SetControlSupervisor function allows an embedder control to respond to mouse-down events occurring in its embedded controls.

An example of a standard control that uses this function is the radio group control. Mouse-down events in the embedded controls of a radio group are intercepted by the group control. (The embedded controls in this case must support radio behavior; if a mouse-down event occurs in an embedded control within a radio group control that does not support radio behavior, the control tracks normally and the group is not involved.) The group handles all interactions and switches the embedded control's value on and off. If the value of the radio group changes, TrackControl or HandleControlClick will return the kControlRadioGroupPart part code. If the user tracks off the radio button or clicks the current radio button, kControlNoPart is returned.


VERSION NOTES

Available with Appearance Manager 1.0 and later.


SEE ALSO

Embedding Controls .


DumpControlHierarchy

Writes a textual representation of the control hierarchy for a specified window into a file.

pascal OSErr DumpControlHierarchy (
                     WindowPtr inWindow,
                     const FSSpec* inDumpFile);
inWindow
A pointer to the window whose control hierarchy you wish to examine.
inDumpFile
A pointer to a file specification in which to place a text description of the window's control hierarchy.
function result
A result code; see Result Codes .

DISCUSSION

The DumpControlHierarchy function places a text listing of the current control hierarchy for the window specified into the specified file, overwriting any existing file. If the specified window does not contain a control hierarchy, DumpControlHierarchy notes this in the text file. This function is useful for debugging embedding-related problems.


VERSION NOTES

Available with Appearance Manager 1.0 and later.


SEE ALSO

Embedding Controls .

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