Description

Attaches the side of a user control to the side of another user control.

When a user window's size changes, the user control's position and size (layout) on the window often needs to be recalculated. By attaching the sides of a user control to other user controls, the user control's layout will automatically be handled by the framework. This is easier than calling setControlPos on each user control every time the user window's size changes.

User controls can be anchored to the sides of forms and/or other user controls. For a description of forms, see createForm. To be anchored to the side of a form, the user control must have been created with the -form flag, and thus added to the form's list of user controls to manage. When anchoring to a form, controlSide and targetSide are typically the same (e.g. the left side of a control is anchored to the left side of a form. When the form's left side gets moved, the user control's left side is moved with it.).

Alternatively, a user control can be attached to another user control. This allows user controls to be laid out with respect to each other (e.g. the left side of a control can be anchored to the right side of another control. When the right side of the other control gets moved, the user control's left side will be moved as well.).

To dynamically control the size of a user control, anchor the control's opposing sides. If opposite sides of a user control are anchored, the control's size is also affected because it has anchors pulling its sides in opposite directions.

Note that controlSide and targetSide must specify either matching or opposing sides, but not adjacent sides. E.g. specifying "left" and "top" is illogical and will result in an error.

Functional area

User Window

Command syntax

Syntax

Arguments

Flags

Return value

void

Examples

// Anchor two controls two each other, and to the
// form top-level 
int $windowId;
int $staticId, $textId;
int $formId; 
  
// First create a User Window to place the Controls 
on$windowId = `createWindow "MyWindow"`;
 
// Get the top-level form 
Id$formId = `getTopLevelForm $windowId`;
 
// Create a label User Control, and add it to the form
$staticId = `createStaticBox $windowId -text "Name" -form $formId`;
 
// Create a Text Box Control in the window. Also add it to the
// top-level form.
$textId = `createTextBox $windowId -form $formId`;
 
// Attach the Static User Control to the top and to the left
// of the top-level form
setControlAnchor $staticId "left" "left" 0;
setControlAnchor $staticId "top" "top" 0;
 
// Make the Text Box User Control stretch from the right side
// of the Static Box, to the right side of the User Window
setControlAnchor $textId "top" "top" 0 -target $staticId;
setControlAnchor $textId "left" "right" 5 -target $staticId;
setControlAnchor $textId "right" "right" 0;
 
// Issue the call to layout the top level form. We only
// need to do this once
layoutForm $formId;

Additional information

Related commands

• createForm
• getControlPos
• getTopLevelForm
• layoutForm
• setControlPos