Difference between revisions of "DesktopContainer"

From Xojo Documentation

(Created page with "N/A")
 
Line 1: Line 1:
N/A
+
{{ClassBox
 +
| super=[[DesktopWindow]]
 +
| platform=all
 +
| scope=global
 +
| newinversion=2021r3
 +
}}
 +
{{Description
 +
| text=Used to embed a group of controls in a [[DesktopWindow|Window]] or in another [[DesktopUIControl|control]].}}
 +
 
 +
<dynamicTable id="Events" class="eventTable" super="DesktopWindow" title="Events" columns="3" exclude="Activated,ContentsChanged,Deactivated,CancelClosing,Maximized,Minimized,Moved,Resized,Resizing,Restored">
 +
{{Event | name=FocusLost  | description=FocusLost()&#10;The container no longer has the focus.}}
 +
{{Event | name=FocusReceived  | description=FocusReceived()&#10;The container has received the focus.}}
 +
</dynamicTable>
 +
 
 +
<dynamicTable id="Properties" super="DesktopWindow" class="propertyTable" title="Properties" columns="3" exclude="Changed,DockItem,HasCloseButton,HasFullScreenButton,HasMaximizeButton,HasMinimizeButton,MenuBar,SystemUIVisible,MaximumHeight,MaximumWidth,MinimumHeight,MinimumWidth,Resizeable,LiveResize,FullScreen,Type,DefaultLocation,Title">
 +
{{Property | name=AllowAutoDeactivate | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;Determines whether the Container should be deactivated (on macOS) when the parent window is deactivated. }}
 +
{{Property | name=AllowFocus | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;If True, the Container can have the focus. }}
 +
{{Property | name=AllowFocusRing | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;If True, the Container 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=AllowTabs | type=Boolean | platform=all | description=(Boolean)&nbsp;&nbsp;If True and AllowFocus is True, then pressing Tab triggers the KeyDown event for processing. }}
 +
{{Property | name=Composited | type=Boolean | platform=all | description=(Boolean)&nbsp;&nbsp;Used on Windows to reduce flickering when scrolling. }}
 +
{{Property | name=Enabled | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;Determines if the Container should be enabled when the owning window is opened.  }}
 +
{{Property | name=LockBottom | type=Boolean | platform=all | description=(Boolean)&nbsp;&nbsp;Determines whether the bottom edge of the Container 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 | description=(Boolean)&nbsp;&nbsp;Determines whether the left edge of the Container should stay at a set distance from the left edge of the parent control, if there is one, or the owning window. }}
 +
{{Property | name=LockRight | type=Boolean | platform=all | description=(Boolean)&nbsp;&nbsp;Determines whether the right edge of the Container should stay at a set distance from the right edge of the parent control, if there is one, or the owning window. }}
 +
{{Property | name=LockTop | type=Boolean | platform=all | description=(Boolean)&nbsp;&nbsp;Determines whether the top edge of the Container should stay at a set distance from the top edge of the parent control, if there is one, or the owning window. }}
 +
{{Property | name=PanelIndex | type=Integer | platform=all | description=(Integer)&nbsp;&nbsp;Used to get or set the panel of a TabPanel or PagePanel on which the control has been placed. }}
 +
{{Property | name=Parent | type=Object | platform=all | description=(Object)&nbsp;&nbsp;Gets the containing control, if any. }}
 +
{{Property | name=TabIndex | type=Integer | platform=all | description=(Integer)&nbsp;&nbsp;The container's position in the Tab Order.}}
 +
{{Property | name=Tooltip | type=String | platform=all | description=(String)&nbsp;&nbsp;Text of help message displayed as a Windows or Linux "tip" or macOS help tag. }}
 +
{{Property | name=Transparent | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;If True, the background shows through to the Container; if False, the ContainerControl is opaque. }}
 +
{{Property | name=Window | type=Window | platform=all | description=( Window)&nbsp;&nbsp;The window upon which the container is placed.}}
 +
</dynamicTable>
 +
 
 +
<dynamicTable id="Methods" super="DesktopWindow" class="methodTable" title="Methods" columns="3" exclude="Show,ShowModal,ShowModalWithin,ShowWithin,Minimize,Maximize,Restore">
 +
{{Method | name=EmbedWithin | params=ContainingWindow as [[DesktopWindow]],  [left as [[Integer]]],  [top as [[Integer]]],  [width as [[Integer]]],  [height as [[Integer]]] | description=EmbedWithin(ContainingWindow as [[DesktopWindow]],  [left as Integer],  [top as Integer],  [width as Integer],  [height as Integer])&#10;Embeds the Container in a Window&#10;EmbedWithin(containingControl as DesktopUIControl,  [left as Integer],  [top as Integer], [width as Integer], [height as Integer])&#10;Embeds a Container in another Container. }}
 +
{{Method | name=EmbedWithinPanel | params=ContainingPanel as [[DesktopPagePanel]],  Page as [[Integer]],  left as [[Integer]]], [top as [[Integer]]], [width as [[Integer]]], [height as [[Integer]]] | description=EmbedWithinPanel(ContainingPanel as DesktopPagePanel,  Page as Integer,  left as Integer], [top as Integer], [width as Integer], [height as Integer])&#10;Embeds the Container on a page in the passed PagePanel or TabPanel.  }}
 +
</dynamicTable>
 +
 
 +
==Notes==
 +
{{Warning | In the Layout Editor, do not layer other controls onto Containers that have been added to a Window layout. Controls added this way are not part of the Container and will not display properly. Instead, add your controls directly to the Container in its layout.}}
 +
 
 +
{{Warning | Containers can not be part of a Control Set.}}
 +
 
 +
'''DesktopContainer''' is not a [[DesktopUIControl]] (despite its name), nor is it a [[DesktopWindow]]. It is a separate class that is similar to [[DesktopUIControl]] and to [[DesktopWindow]], providing many of the same events, properties, and methods. Like a [[DesktopWindow]], a '''DesktopContainer''' can encapsulate related [[DesktopUIControl|Controls]] (and other '''DesktopContainers''') in a self-contained, reusable class. Like a [[DesktopUIControl]], a '''DesktopContainer''' can be added to a [[DesktopWindow]], a [[DesktopTabPanel]], a [[DesktopPagePanel]], or to another '''DesktopContainer'''.
 +
 
 +
You can embed a '''DesktopContainer''' in a [[DesktopWindow]] or '''DesktopContainer''' in either the IDE or via code. Multiple levels of embedding are supported.
 +
 
 +
To add the '''DesktopContainer''' to a window via code, use either the EmbedWithin or EmbedWithinPanel methods. Use EmbedWithin to embed the '''DesktopContainer''' in either a window or a control, depending on whether the first parameter is a [[DesktopWindow]] or a [[DesktopUIControl|control]]. For the special case of embedding within a [[DesktopPagePanel]] or a [[DesktopTabPanel]], use EmbedWithinPanel instead. It allows you to pass the page number on which the '''DesktopContainer''' will be embedded. To remove the container, use the Close method.
 +
 
 +
The following statement embeds a '''DesktopContainer''' at so that its top left corner is 50 points from the left side of the window and 100 points from the top.
 +
<rbcode>
 +
Container1.EmbedWithin(Self, 50, 100)
 +
</rbcode>
 +
 
 +
When the project is run, the controls in the '''DesktopContainer''' appear in the default window, Window1. Use the same approach to embed the '''DesktopContainer''' in a control other than a [[DesktopPagePanel]] or [[DesktopTabPanel]]; for the latter types of controls, use EmbedWithinPanel and pass the name of the control and the desired panel number.
 +
 
 +
DesktopContainers have multiple uses, You can:
 +
 
 +
Organize groups of controls into reusable interface components,<br>
 +
Create custom controls made up of several constituent controls,<br>
 +
Increase encapsulation of complex window layouts,<br>
 +
Create dynamic layouts.
 +
 
 +
For the most part, '''DesktopContainers''' act as you would expect. For example, if you put code in the MouseMove event of an embedded '''DesktopContainer''', the event will fire when your mouse moves over the embedded '''DesktopContainer''''s boundaries. There are a few things you need to be aware of:
 +
 
 +
The Handle property of a '''DesktopContainer''' and the Handle property of controls of an '''DesktopContainer''' are [[Nil]] until the Opening event. All of the other properties can be manipulated before the Opening event.
 +
 
 +
A '''DesktopContainer''' either has its own keyboard focus and menu handling, or it shares these elements with its containing [[DesktopWindow]]. Which behavior is chosen depends on the state of the AllowFocus flag when the '''DesktopContainer''' is embedded. When AllowFocus is [[True]], the '''DesktopContainer''' does not share focus with the containing [[DesktopWindow]]. 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 '''DesktopContainers''' and relate to its behavior when embedded; these behave like the corresponding properties of the [[DesktopCanvas]] control. These include the following: LockLeft, LockTop, LockRight, LockBottom, Enabled, AutoDeactivate, HelpTag, UseFocusRing, AllowFocus, AllowTabs, Parent and Window.
 +
 
 +
===Miscellaneous Issues===
 +
Use the Opening 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 DesktopContainers is allowed. However, you can't embed a '''DesktopContainer''' such that the containing '''DesktopContainer''' or a '''DesktopContainer''' higher in the containing chain is another instance of the same '''DesktopContainer'''; in other words, you can't recursively nest DesktopContainers in other instances of themselves.
 +
 
 +
Nested DesktopContainer 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 [[DesktopMenuItem|DesktopMenuItem's]] Popup method.
 +
 
 +
==See Also==
 +
[[DesktopWindow]] classes
 +
 
 +
[[Category:Desktop]]
 +
[[Category:Desktop UI]]

Revision as of 19:11, 23 July 2021

Class (inherits from DesktopWindow)


New in 2021r3

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

Events
Closing FocusReceived MouseMove
ConstructContextualMenu KeyDown MouseUp
ContextualMenuItemSelected KeyUp MouseWheel
DragEnter MenuBarSelected Opening
DragExit MouseDown Paint
DragOver MouseDrag ScaleFactorChanged
DropObject MouseEnter
FocusLost MouseExit
Properties
AllowAutoDeactivate Handle fa-lock-32.png PanelIndex
AllowFocus HasBackgroundColor Parent
AllowFocusRing Height ScaleFactor fa-lock-32.png
AllowTabs Left TabIndex
Backdrop LockBottom Tooltip
BackgroundColor LockLeft Top
Bounds LockRight Transparent
Composited LockTop Visible
ControlCount fa-lock-32.png MouseCursor Width
Enabled MouseX fa-lock-32.png Window
Focus MouseY fa-lock-32.png
Methods
AcceptFileDrop Close FocusNext
AcceptPictureDrop Control FocusPrevious
AcceptRawDataDrop Controls Hide
AcceptTextDrop DrawInto Refresh
AddControl EmbedWithin SetFocus
BitmapForCaching EmbedWithinPanel

Notes

fa-exclamation-circle-32.png
In the Layout Editor, do not layer other controls onto Containers that have been added to a Window layout. Controls added this way are not part of the Container and will not display properly. Instead, add your controls directly to the Container in its layout.
fa-exclamation-circle-32.png
Containers can not be part of a Control Set.

DesktopContainer is not a DesktopUIControl (despite its name), nor is it a DesktopWindow. It is a separate class that is similar to DesktopUIControl and to DesktopWindow, providing many of the same events, properties, and methods. Like a DesktopWindow, a DesktopContainer can encapsulate related Controls (and other DesktopContainers) in a self-contained, reusable class. Like a DesktopUIControl, a DesktopContainer can be added to a DesktopWindow, a DesktopTabPanel, a DesktopPagePanel, or to another DesktopContainer.

You can embed a DesktopContainer in a DesktopWindow or DesktopContainer in either the IDE or via code. Multiple levels of embedding are supported.

To add the DesktopContainer to a window via code, use either the EmbedWithin or EmbedWithinPanel methods. Use EmbedWithin to embed the DesktopContainer in either a window or a control, depending on whether the first parameter is a DesktopWindow or a control. For the special case of embedding within a DesktopPagePanel or a DesktopTabPanel, use EmbedWithinPanel instead. It allows you to pass the page number on which the DesktopContainer will be embedded. To remove the container, use the Close method.

The following statement embeds a DesktopContainer at so that its top left corner is 50 points from the left side of the window and 100 points from the top.

Container1.EmbedWithin(Self, 50, 100)

When the project is run, the controls in the DesktopContainer appear in the default window, Window1. Use the same approach to embed the DesktopContainer in a control other than a DesktopPagePanel or DesktopTabPanel; for the latter types of controls, use EmbedWithinPanel and pass the name of the control and the desired panel number.

DesktopContainers 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, DesktopContainers act as you would expect. For example, if you put code in the MouseMove event of an embedded DesktopContainer, the event will fire when your mouse moves over the embedded DesktopContainer's boundaries. There are a few things you need to be aware of:

The Handle property of a DesktopContainer and the Handle property of controls of an DesktopContainer are Nil until the Opening event. All of the other properties can be manipulated before the Opening event.

A DesktopContainer either has its own keyboard focus and menu handling, or it shares these elements with its containing DesktopWindow. Which behavior is chosen depends on the state of the AllowFocus flag when the DesktopContainer is embedded. When AllowFocus is True, the DesktopContainer does not share focus with the containing DesktopWindow. 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 DesktopContainers and relate to its behavior when embedded; these behave like the corresponding properties of the DesktopCanvas control. These include the following: LockLeft, LockTop, LockRight, LockBottom, Enabled, AutoDeactivate, HelpTag, UseFocusRing, AllowFocus, AllowTabs, Parent and Window.

Miscellaneous Issues

Use the Opening 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 DesktopContainers is allowed. However, you can't embed a DesktopContainer such that the containing DesktopContainer or a DesktopContainer higher in the containing chain is another instance of the same DesktopContainer; in other words, you can't recursively nest DesktopContainers in other instances of themselves.

Nested DesktopContainer 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 DesktopMenuItem's Popup method.

See Also

DesktopWindow classes