Difference between revisions of "ContainerControl"

From Xojo Documentation

 
(One intermediate revision by one other user not shown)
Line 9: Line 9:
  
 
<dynamicTable id="Events" class="eventTable" super="Window" title="Events" exclude="CancelClose" columns="3" exclude="Maximize,Minimize,Restore">
 
<dynamicTable id="Events" class="eventTable" super="Window" title="Events" exclude="CancelClose" columns="3" exclude="Maximize,Minimize,Restore">
{{Event | name=GotFocus | description= GotFocus()&#x0D;Called when the ContainerControl gets focus.}}
+
{{Event | name=GotFocus | description= GotFocus()&#10;Called when the ContainerControl gets focus.}}
{{Event | name=LostFocus | description= LostFocus()&#x0D;Called when the ContainerControl loses focus.}}
+
{{Event | name=LostFocus | description= LostFocus()&#10;Called when the ContainerControl loses focus.}}
 
</dynamicTable>
 
</dynamicTable>
 
  
 
<dynamicTable id="Properties" super="Window" class="propertyTable" title="Properties" columns="3" exclude="CloseButton,FullScreenButton,MaximizeButton,MinimizeButton,MenuBar,MenuBarVisible,MaxHeight,MaxWidth,MinHeight,MinWidth,Resizeable,LiveResize,Composite,ImplicitInstance,FullScreen,Frame,Placement,Title,MacProcID">
 
<dynamicTable id="Properties" super="Window" class="propertyTable" title="Properties" columns="3" exclude="CloseButton,FullScreenButton,MaximizeButton,MinimizeButton,MenuBar,MenuBarVisible,MaxHeight,MaxWidth,MinHeight,MinWidth,Resizeable,LiveResize,Composite,ImplicitInstance,FullScreen,Frame,Placement,Title,MacProcID">
{{Property | name=AcceptFocus | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;If True, the ContainerControl can have the focus. }}
+
{{Property | name=AllowFocus | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;If True, the ContainerControl can have the focus. }}
{{Property | name=AcceptTabs | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;If True and AcceptFocus is True, then pressing Tab triggers the KeyDown event for processing. }}
+
{{Property | name=AllowFocusRing | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;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. }}
{{Property | name=AutoDeactivate | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;Determines whether the ContainerControl should be deactivated (on macOS) when the parent window is deactivated. }}
+
{{Property | name=AllowTabs | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;If True and AcceptFocus is True, then pressing Tab triggers the KeyDown event for processing. }}
{{Property | name=DoubleBuffer | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;Used on Windows to reduce flickering when scrolling. }}
+
{{Property | name=AllowAutoDeactivate | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;Determines whether the ContainerControl should be deactivated (on macOS) when the parent window is deactivated. }}
{{Property | name=Enabled | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;Determines if the ContainerControl should be enabled when the owning window is opened. }}
 
 
{{Property | name=HelpTag | type=String | platform=all | modifiedinversion=5.0 | description=( String)&nbsp;&nbsp;Text of help message displayed as a Windows or Linux "tip" or macOS help tag. }}
 
{{Property | name=HelpTag | type=String | platform=all | modifiedinversion=5.0 | description=( String)&nbsp;&nbsp;Text of help message displayed as a Windows or Linux "tip" or macOS help tag. }}
 +
{{Property | name=IsComposited | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;Used on Windows to reduce flickering when scrolling. }}
 +
{{Property | name=IsEnabled | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;Determines if the ContainerControl should be enabled when the owning window is opened.  }}
 +
{{Property | name=IsTransparent | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;If True, the background shows through to the ContainerControl; if False, the ContainerControl is opaque. }}
 
{{Property | name=LockBottom | type=Boolean | platform=all | modifiedinversion=2005r1 | description=( Boolean)&nbsp;&nbsp;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. }}
 
{{Property | name=LockBottom | type=Boolean | platform=all | modifiedinversion=2005r1 | description=( Boolean)&nbsp;&nbsp;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. }}
 
{{Property | name=LockLeft | type=Boolean | platform=all | modifiedinversion=2005r1, 2009r5 | description=( Boolean)&nbsp;&nbsp;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. }}
 
{{Property | name=LockLeft | type=Boolean | platform=all | modifiedinversion=2005r1, 2009r5 | description=( Boolean)&nbsp;&nbsp;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. }}
Line 26: Line 27:
 
{{Property | name=LockTop | type=Boolean | platform=all | modifiedinversion=2005r1, 2009r5 | description=( Boolean)&nbsp;&nbsp;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. }}
 
{{Property | name=LockTop | type=Boolean | platform=all | modifiedinversion=2005r1, 2009r5 | description=( Boolean)&nbsp;&nbsp;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. }}
 
{{Property | name=Parent | type=RectControl | platform=all | description=( RectControl)&nbsp;&nbsp;Gets the containing control, if any. }}
 
{{Property | name=Parent | type=RectControl | platform=all | description=( RectControl)&nbsp;&nbsp;Gets the containing control, if any. }}
{{Property | name=UseFocusRing | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;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. }}
 
 
{{Property | name=Window | type=Window | platform=all | description=( Window)&nbsp;&nbsp;Gets the containing window.  }}
 
{{Property | name=Window | type=Window | platform=all | description=( Window)&nbsp;&nbsp;Gets the containing window.  }}
{{Property | name=Transparent | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;If True, the background shows through to the ContainerControl; if False, the ContainerControl is opaque. }}
 
 
</dynamicTable>
 
</dynamicTable>
 
  
 
<dynamicTable id="Methods" super="Window" class="methodTable" title="Methods" columns="3" exclude="Show,ShowModal,ShowModalWithin,ShowWithin,Minimize,Maximize,Restore">
 
<dynamicTable id="Methods" super="Window" class="methodTable" title="Methods" columns="3" exclude="Show,ShowModal,ShowModalWithin,ShowWithin,Minimize,Maximize,Restore">
{{Method | name=EmbedWithin | params=ContainingWindow as [[WindowClass|Window]],  [left as [[Integer]]],  [top as [[Integer]]],  [width as [[Integer]]],  [height as [[Integer]]] | description=EmbedWithin(ContainingWindow as Window,  [left as Integer],  [top as Integer],  [width as Integer],  [height as Integer])&#x0D;Embeds the ContainerControl in a Window&#x0D;EmbedWithin(ContainerControl as RectControl,  [left as Integer],  [top as Integer], [width as Integer], [height as Integer])&#x0D;Embeds a ContainerControl in a ContainerControl }}
+
{{Method | name=EmbedWithin | params=ContainingWindow as [[WindowClass|Window]],  [left as [[Integer]]],  [top as [[Integer]]],  [width as [[Integer]]],  [height as [[Integer]]] | description=EmbedWithin(ContainingWindow as Window,  [left as Integer],  [top as Integer],  [width as Integer],  [height as Integer])&#10;Embeds the ContainerControl in a Window&#10;EmbedWithin(ContainerControl as RectControl,  [left as Integer],  [top as Integer], [width as Integer], [height as Integer])&#10;Embeds a ContainerControl in a ContainerControl }}
{{Method | name=EmbedWithinPanel | params=ContainingPanel as [[PagePanel]],  Page as [[Integer]],  left as [[Integer]]], [top as [[Integer]]], [width as [[Integer]]], [height as [[Integer]]] | description=EmbedWithinPanel(ContainingPanel as PagePanel,  Page as Integer,  left as Integer], [top as Integer], [width as Integer], [height as Integer])&#x0D;Embeds the ContainerControl on a page in the passed PagePanel or TabPanel.  }}
+
{{Method | name=EmbedWithinPanel | params=ContainingPanel as [[PagePanel]],  Page as [[Integer]],  left as [[Integer]]], [top as [[Integer]]], [width as [[Integer]]], [height as [[Integer]]] | description=EmbedWithinPanel(ContainingPanel as PagePanel,  Page as Integer,  left as Integer], [top as Integer], [width as Integer], [height as Integer])&#10;Embeds the ContainerControl on a page in the passed PagePanel or TabPanel.  }}
 
</dynamicTable>
 
</dynamicTable>
  
Line 49: Line 47:
  
 
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.
 
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.
 
 
<rbcode>
 
<rbcode>
 
ContainerControl1.EmbedWithin(Self, 50, 100)
 
ContainerControl1.EmbedWithin(Self, 50, 100)

Latest revision as of 17:08, 20 May 2019

Class (inherits from Object)

Used to embed a group of controls in a Window or in another control.

For web apps, see WebContainer.
Events
Activate DropObject MouseMove
CancelClose EnableMenuItems MouseUp
Close GotFocus MouseWheel
ConstructContextualMenu KeyDown Moved
ContentsChanged KeyUp Open
ContextualMenuAction LostFocus Paint
Deactivate MouseDown Resized
DragEnter MouseDrag Resizing
DragExit MouseEnter ScaleFactorChanged
DragOver MouseExit
Properties
AllowAutoDeactivate Handle fa-lock-32.png LockTop
AllowFocus HasBackColor MouseCursor
AllowFocusRing Height MouseX fa-lock-32.png
AllowTabs HelpTag MouseY fa-lock-32.png
BackColor IsComposited Parent
Backdrop IsEnabled ScaleFactor fa-lock-32.png
Bounds IsTransparent Top
ContentsChanged Left TrueWindow fa-lock-32.png
ControlCount fa-lock-32.png LockBottom Visible
DockItem fa-lock-32.png LockLeft Width
Focus LockRight Window
Methods
AcceptFileDrop Control Hide
AcceptPictureDrop DrawInto Invalidate
AcceptRawDataDrop EmbedWithin Refresh
AcceptTextDrop EmbedWithinPanel RefreshRect
BitmapForCaching FocusNext SetFocus
Close FocusPrevious UpdateNow

Notes

fa-exclamation-circle-32.png
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.
fa-exclamation-circle-32.png
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.

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 AcceptFocus flag when the ContainerControl is embedded. When AcceptFocus 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, AcceptFocus, AcceptTabs, Parent and Window.

Miscellaneous Issues

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.

See Also

Window classes