` | | | ## Property descriptions

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

forsearch

ContainerControl.AllowAutoDeactivate **AllowAutoDeactivate** As `Boolean` Determines whether the control should be deactivated (on macOS) when the parent window is deactivated. This example turns AllowAutoDeactivate off. ``` xojo ContainerControl11.AllowAutoDeactivate = False ```

forsearch

ContainerControl.AllowFocus **AllowFocus** As `Boolean` If `True`, the control will be included in the Tab order and can accept the focus. The `GotFocus` and `LostFocus` events are called at the appropriate times. Some controls automatically allow focus, e.g. text fields or lists, so they do not have AllowFocus property.

Note

Not all controls allow focus on every platform.

This code enables the AllowFocus property. It is in the Open event of the control. ``` xojo Me.AllowFocus = True ```

forsearch

ContainerControl.AllowFocusRing **AllowFocusRing** As `Boolean` If `True`, the ContainerControl indicates that it has the focus with a ring around its border; if `False`, the appearance of the object does not change when it has the focus.

forsearch

ContainerControl.AllowTabs **AllowTabs** As `Boolean` If `True` and `AllowFocus` is `True`, then pressing Tab triggers the `KeyDown` event for processing. If AllowTabs is `False`, pressing the Tab key does not trigger the `KeyDown` event; pressing Tab triggers the LostFocus event and selects the next object in the `Window` that can accept the focus.

forsearch

ContainerControl.Composited **Composited** As `Boolean` When True, reduces flickering on Windows when the ContainerControl is scrolled. Has no effect on macOS or Linux.

forsearch

ContainerControl.Enabled **Enabled** As `Boolean` Determines if the ContainerControl should be enabled when the owning window is opened. The default is `True`. The following example disables the ContainerControl. ``` xojo ContainerContol11.Enabled=False ```

forsearch

ContainerControl.LockBottom **LockBottom** As `Boolean` Determines whether the bottom edge of the ContainerControl should stay at a set distance from the bottom edge of the parent `control`, if there is one, or the owning `Window`. ``` xojo Me.LockBottom = True ```

forsearch

ContainerControl.LockLeft **LockLeft** As `Boolean` Determines whether the left edge of the ContainerControl should stay at a set distance from the left edge of the parent `control`, if there is one, or the owning `Window`. Beginning with version 2009r5, `LockTop` and `LockLeft` default to `True` when you add a control to a window. Existing controls will be altered only if `LockRight` and/or `LockBottom` are not set.

forsearch

ContainerControl.LockRight **LockRight** As `Boolean` Determines whether the right edge of the ContainerControl should stay at a set distance from the right edge of the parent `control`, if there is one, or the owning `Window`. ``` xojo Me.LockRight = True ```

forsearch

ContainerControl.LockTop **LockTop** As `Boolean` Determines whether the top edge of the ContainerControl should stay at a set distance from the top edge of the parent `control`, if there is one, or the owning `Window`. Beginning with version 2009r5, `LockTop` and `LockLeft` default to `True` when you add a control to a window. Existing controls will be altered only if `LockRight` and/or `LockBottom` are not set. ``` xojo Me.LockTop = True ```

forsearch

ContainerControl.Parent **Parent** As `RectControl` Gets the containing control, if any.

forsearch

ContainerControl.Tooltip **Tooltip** As `String` Text of help message displayed as a Windows or Linux "tip" or macOS help tag. ``` xojo Me.Tooltip = "This is a tooltip." ```

forsearch

ContainerControl.Transparent **Transparent** As `Boolean` If `True`, the background shows through to the ContainerControl; if `False`, the ContainerControl is opaque. The default is True. ContainerControls by default are transparent controls, which means the background shows through. The Transparent property can be set (at design time or runtime) to turn this off/on as needed. An opaque ContainerControl flickers less on Windows, is more optimized on macOS, and on Linux child controls on ContainerControl are clipped properly. This example turns Transparent off: ``` xojo Me.Transparent = False ```

forsearch

ContainerControl.Window **Window** As `Window` Gets the containing window. ## Method descriptions

forsearch

ContainerControl.EmbedWithin **EmbedWithin**(ContainingWindow As `Window`, \[left As `Integer`, top As `Integer`, width As `Integer`, height As `Integer`\]) Embeds the ContainerControl in the specified *Container* control. ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

forsearch

ContainerControl.EmbedWithin **EmbedWithin**(ContainerControl As `RectControl`, \[left As `Integer`, top As `Integer`, width As `Integer`, height As `Integer`\]) Embeds the ContainerControl in the specified *Container* control. This code is in the Action event of a button and add a container control to a window: ``` xojo Var tc As New TestContainer tc.EmbedWithin(Self, 10, 100, 300,400) ``` If you need to later remove the container, then you'll need to have a reference to it. In this case, use a property for the container. Add the container using EmbedWithin and remove it using Close. ``` xojo ' Add the container MyContainer = New TestContainer MyContainer.EmbedWithin(Self, 10, 100, 300, 400) ``` Elsewhere you can remove the container: ``` xojo MyContainer.Close ```

forsearch

ContainerControl.EmbedWithinPanel **EmbedWithinPanel**(ContainingPanel As `PagePanel`, Page As `Integer`, \[left As `Integer`, top As `Integer`, width As `Integer`, height As `Integer`\]) Embeds the ContainerControl on a page in the passed `PagePanel` or `TabPanel`. An instance of a ContainerControl can only be embedded into one page. The ContainerControl is embedded on the passed page and the containing control is the parent of the ContainerControl. The optional *Left* and *Top* parameters determine the location of the top-left corner, relative to the containing control, not the parent window. If the ContainerControl itself has Left and Top values (not typical as they default to 0) then they are added to what is specified here. The optional parameters *Width* and *Height* determine the size of the ContainerControl. This example adds a new tab to a `TabPanel` and then add a ContainerControl to it: ``` xojo MainTab.AddPanel("New Tab") Var tabNum As Integer tabNum = MainTab.PanelCount - 1 Var cc As New MyContainer cc.EmbedWithinPanel(MainTab, tabNum) ``` ## Event descriptions

forsearch

ContainerControl.GotFocus **GotFocus** Called when the ContainerControl gets focus. The AllowFocus property must be set to True in order for this event to be called.

forsearch

ContainerControl.LostFocus **LostFocus** Called when the ContainerControl loses focus. The AllowFocus property must be set to True in order for this event to be called. ## Notes

Warning

In the Layout Editor, do not layer other controls onto ContainerControls that have been added to a Window layout. Controls added this way are not part of the ContainerControl and will not display properly. Instead, add your controls directly to the ContainerControl in its layout.

Warning

ContainerControls can not be part of a Control Set.

ContainerControl is not a `Control` (despite its name), nor is it a `Window`. It is a separate class that is similar to `Control` and to `Window`, providing many of the same events, properties, and methods. Like a `Window`, a ContainerControl can encapsulate related `Controls` (and other ContainerControls) in a self-contained, reusable class. Like a `Control`, a ContainerControl can be added to a `Window`, a `TabPanel`, a `PagePanel`, or to another ContainerControl. You can embed a ContainerControl in a `Window` or ContainerControl in either the IDE or via code. Multiple levels of embedding are supported. To add the ContainerControl to a window via code, use either the EmbedWithin or EmbedWithinPanel methods. Use EmbedWithin to embed the ContainerControl in either a window or a control, depending on whether the first parameter is a `Window` or a `control`. For the special case of embedding within a `PagePanel` or a `TabPanel`, use EmbedWithinPanel instead. It allows you to pass the page number on which the ContainerControl will be embedded. To remove the container, use the Close method. The following statement embeds a ContainerControl at so that its top left corner is 50 points from the left side of the window and 100 points from the top. ``` xojo ContainerControl1.EmbedWithin(Self, 50, 100) ``` When the project is run, the controls in the ContainerControl appear in the default window, Window1. Use the same approach to embed the ContainerControl in a control other than a PagePanel or TabPanel; for the latter types of controls, use EmbedWithinPanel and pass the name of the control and the desired panel number. ContainerControls have multiple uses, You can: Organize groups of controls into reusable interface components, Create custom controls made up of several constituent controls, Increase encapsulation of complex window layouts, Create dynamic layouts. For the most part, ContainerControls act as you would expect. For example, if you put code in the MouseMove event of an embedded ContainerControl, the event will fire when your mouse moves over the embedded ContainerControl's boundaries. There are a few things you need to be aware of: The Handle property of a ContainerControl and the Handle property of controls of an ContainerControl are `Nil` until the Open event. All of the other properties can be manipulated before the Open event. A ContainerControl either has its own keyboard focus and menu handling, or it shares these elements with its containing `Window`. Which behavior is chosen depends on the state of the AllowFocus flag when the ContainerControl is embedded. When AllowFocus is `True`, the ContainerControl does not share focus with the containing `Window`. If a containing window has embedded that which share focus with it, those windows will get a first crack at handling it. If none handle it, the containing window will get a try. This applies to KeyDown and MenuCommands. It also affects how menu commands are enabled. Some properties are new to ContainerControls and relate to its behavior when embedded; these behave like the corresponding properties of the `Canvas` control. These include the following: LockLeft, LockTop, LockRight, LockBottom, Enabled, AutoDeactivate, HelpTag, UseFocusRing, AllowFocus, AllowTabs, Parent and Window. --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Miscellaneous issues Use the Open event for initialization instead of overriding the Constructor to allow all the controls to finish setting themselves up. The Moved, Resized, and Resizing events fire on embedded windows when the embedded window is moved or resized. The Show/Hide and the Visible property can be used to set the visibility of embedded windows. Nesting ContainerControls is allowed. However, you can't embed a ContainerControl such that the containing ContainerControl or a ContainerControl higher in the containing chain is another instance of the same ContainerControl; in other words, you can't recursively nest ContainerControls in other instances of themselves. Nested ContainerControl coordinates for controls and events are automatically transformed for you. You don't need to worry about them unless you are dealing with global coordinates as you would for the `MenuItem's` Popup method. ## Compatibility All project types on all supported operating systems. ## See also `Object` parent class; `Window` classes