Class
DesktopContainer
Properties
Name |
Type |
Read-Only |
Shared |
---|---|---|---|
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
Methods
Name |
Parameters |
Returns |
Shared |
---|---|---|---|
FileType As String |
|||
Type As String |
|||
control As DesktopUIControl |
|||
index As Integer |
|||
containingWindow As DesktopWindow, left As Integer = 0, top As Integer = 0, width As Integer = -1, height As Integer = -1 |
|||
containingControl As DesktopUIControl, left As Integer = 0, top As Integer = 0, width As Integer = -1, height As Integer = -1 |
|||
containingPanel As DesktopPagePanel, page As Integer, left As Integer = 0, top As Integer = 0, width As Integer = -1, height As Integer = -1 |
|||
x As Integer, y As Integer, width As Integer, height As Integer, immediately As Boolean = False |
|||
control As DesktopUIControl |
|||
parentControl As DesktopUIControl, displaySide As DesktopWindow.DisplaySides = DesktopWindow.DisplaySides.Bottom, detachable As Boolean = True, animated As Boolean = True |
Events
Name |
Parameters |
Returns |
---|---|---|
Base As DesktopMenuItem, x As Integer, y As Integer |
||
HitItem As DesktopMenuItem |
||
Obj As DragItem, Action As DragItem.Types |
||
Obj As DragItem, Action As DragItem.Types |
||
x As Integer, y As Integer, Obj As DragItem, Action As DragItem.Types |
||
Obj As DragItem, Action As DragItem.Types |
||
Key As String |
||
Key As String |
||
X As Integer, Y As Integer, DeltaX As Integer, DeltaY As Integer |
||
Enumerations
DesktopWindow.DisplaySides
DisplaySides
Specifies where the popover will display relative to the control its popping over.
Enum |
Description |
---|---|
Bottom |
Below the parent control. |
Left |
To the left of the parent control. |
Top |
Above the parent control. |
Right |
To the right of the parent control. |
Property descriptions
DesktopContainer.AllowAutoDeactivate
AllowAutoDeactivate As Boolean
Determines whether the container should be deactivated (on macOS) when the parent window is deactivated.
This example turns AllowAutoDeactivate off.
MyDesktopContainer.AllowAutoDeactivate = False
DesktopContainer.AllowFocus
AllowFocus As Boolean
If True, the container will be included in the Tab order and can accept the focus.
This code enables the AllowFocus property. It is in the Opening event of the container.
Me.AllowFocus = True
DesktopContainer.AllowFocusRing
AllowFocusRing As Boolean
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.
DesktopContainer.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 FocusLost event and selects the next object in the DesktopWindow that can accept the focus.
DesktopContainer.Backdrop
Backdrop As Picture
Gets or sets the picture object that will be drawn in the container's background.
You should not assign a new picture to the backdrop of the container when being inside the paint event of that container. This can lead into problems like the backdrop not being painted.
This example sets the backdrop to a jpg image that has been added to the Project. This is in the Opening event.
Me.Backdrop = MyPicture
DesktopContainer.BackgroundColor
BackgroundColor As ColorGroup
The background color for the object. The HasBackgroundColor property, must be set to True to have the BackgroundColor displayed.
This code sets the HasBackgroundColor property and sets the value of the BackgroundColor property:
Me.HasBackgroundColor = True
Me.BackgroundColor = &c110034
DesktopContainer.Bounds
Bounds As Rect
Use this property to Get/Set the true bounds of a container.
To get the bounds:
Var containerBounds As Rect
containerBounds = Self.Bounds
MessageBox("Left = " + containerBounds.Left.ToString)
To set the bounds, do not modify the Bounds properly directly. This does not work because you will be modifying a temporary object. Instead set the bounds in your own Rect instance and assign that to bounds:
Var myBounds As New Rect
myBounds.Left = 100
myBounds.Top = 100
myBounds.Height = Self.Height
myBounds.Width = Self.Width
Self.Bounds = myBounds
DesktopContainer.Composited
Composited As Boolean
When True, reduces flickering on Windows when the DesktopContainer is scrolled. Has no effect on macOS or Linux.
DesktopContainer.ControlCount
ControlCount As Integer
The number of controls in the container.
This property is read-only.
The following example is in the Pressed event of a DesktopButton. It displays the number of controls in the container:
MessageBox(Self.ControlCount.ToString)
DesktopContainer.Enabled
Enabled As Boolean
Determines if the DesktopContainer should be enabled when the owning window is opened. The default is True.
The following example disables the DesktopContainer.
MyDesktopContainer.Enabled=False
DesktopContainer.Focus
Focus As DesktopUIControl
Gets or sets the DesktopUIControl in the container that has the focus. If no control has the focus, this property is Nil.
The following example reports on the control in the DesktopContainer that has the focus.
MessageBox(ContainerControl11.Focus.Name)
DesktopContainer.Handle
Handle As Ptr
Returns a handle to the container.
This property is read-only.
When interfacing with Cocoa APIs using Declares Container.Handle always gives a NSWindow or NSPanel.
DesktopContainer.HasBackgroundColor
HasBackgroundColor As Boolean
If True, the background color of the container is set to the value of the BackgroundColor property.
This property must be set in order for the value of the BackgroundColor property to be applied to the container.
This example sets the HasBackgroundColor property and sets the value of the BackgroundColor property.
Me.HasBackgroundColor = True
Me.BackgroundColor = &c110034
DesktopContainer.Height
Height As Integer
The height (in points) of the control.
This example sets the height of the control to 100:
Me.Height = 100
DesktopContainer.Left
Left As Integer
The distance (in points) between the left edge of the parent container or window and the left edge of the content area of the container.
Me.Left = 50
DesktopContainer.LockBottom
LockBottom As Boolean
Determines whether the bottom edge of the DesktopContainer should stay at a set distance from the bottom edge of the parent control, if there is one, or the owning DesktopWindow.
Me.LockBottom = True
DesktopContainer.LockLeft
LockLeft As Boolean
Determines whether the left edge of the DesktopContainer should stay at a set distance from the left edge of the parent control, if there is one, or the owning DesktopWindow.
DesktopContainer.LockRight
LockRight As Boolean
Determines whether the right edge of the DesktopContainer should stay at a set distance from the right edge of the parent control, if there is one, or the owning DesktopWindow.
Me.LockRight = True
DesktopContainer.LockTop
LockTop As Boolean
Determines whether the top edge of the DesktopContainer should stay at a set distance from the top edge of the parent control, if there is one, or the owning DesktopWindow.
Me.LockTop = True
DesktopContainer.MouseCursor
MouseCursor As MouseCursor
The cursor to be displayed while the mouse is within the container and the DesktopApplication class's MouseCursor property is Nil.
If the DesktopApplication class MouseCursor is not Nil, non-Nil MouseCursors belonging to any windows, containers or Controls are ignored. If the container's MouseCursor property is not Nil, the MouseCursor properties of any Controls are ignored. You can use the cursors in the Cursors module to set the MouseCursor for the container.
This line sets the default cursor to the finger pointer.
Me.MouseCursor = System.Cursors.FingerPointer
DesktopContainer.MouseX
MouseX As Integer
The X coordinate of the mouse (points). Measured from the top-left corner of the container.
This property is read-only.
DesktopContainer.MouseY
MouseY As Integer
The Y coordinate of the mouse (points). Measured from the top-left corner of the container.
This property is read-only.
DesktopContainer.PanelIndex
PanelIndex As Integer
If the container has been placed on a DesktopTabPanel or DesktopPagePanel control, this is the panel (page/tab) that the container is on.
The first panel is numbered zero. If the container has been placed on a panel of a DesktopTabPanel or DesktopPagePanel control, it returns the panel number. If the container is not on a DesktopPagePanel or DesktopTabPanel, it returns -1. If you change the PanelIndex to a nonexistent panel, the control will disappear until you give it a PanelIndex value that corresponds to a panel that exists.
If you are looking to change the currently selected panel (page/tab), use DesktopPagePanel.
This code (in the container's Opening event) displays the panel index of the container:
MessageBox(Me.PanelIndex.ToString)
DesktopContainer.Parent
Parent As Object
The containing control, if any.
This property is read-only.
DesktopContainer.ScaleFactor
ScaleFactor As Double
The scale factor used when converting user space coordinates to backing store coordinates for this container.
This property is read-only.
DesktopContainer.TabIndex
TabIndex As Integer
The DesktopContainer's position in the Tab Order.
On macOS, only controls controls where you enter data from the keyboard typically get the focus. In order to manually set focus to controls that don't allow keyboard entry, go to System Preferences, click on the Keyboard icon then on the Shortcuts tab and then check the Use keyboard navigation to move focus between controls checkbox.
This example sets the Container's TabIndex.
Me.TabIndex = 2
DesktopContainer.Tooltip
Tooltip As String
Text of help message displayed as a Windows or Linux "tip" or macOS help tag.
Me.Tooltip = "This is a tooltip."
DesktopContainer.Top
Top As Integer
The distance (in pixels) between the top edge of the screen and the top edge of the content region of the parent window or container.
Setting Top = 0 moves the top of the container's content area to the top of the parent window or container.
DesktopContainer.Transparent
Transparent As Boolean
If True, the background shows through to the DesktopContainer; if False, the DesktopContainer is opaque. The default is True.
DesktopContainers 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 DesktopContainer flickers less on Windows, is more optimized on macOS, and on Linux child controls on DesktopContainer are clipped properly.
This example turns Transparent off:
Me.Transparent = False
DesktopContainer.Visible
Visible As Boolean
Determines whether the control is visible when its owning window is opened. The default is True: the control is visible.
The following code makes the control invisible:
Me.Visible = False
DesktopContainer.Width
Width As Integer
The width (in points) of the control.
The following example resizes the control:
Me.Width = 200
DesktopContainer.Window
Window As DesktopWindow
Returns a reference to the actual enclosing window.
This property is read-only.
Window walks up the window hierarchy and finds the actual enclosing window regardless of how deeply nested the DesktopUIControl or DesktopContainer hierarchy is.
DesktopControl also has a Window property.
Method descriptions
DesktopContainer.AcceptFileDrop
AcceptFileDrop(FileType As String)
Permits documents of type FileType to be dropped on the container.
FileType must be a file type you specified via the FileType class or the File Type Sets Editor. It works correctly even if you have multiple file types defined with the same File type code, and you don't specifically call AcceptFileDrop for the first such type.
DesktopContainer.AcceptPictureDrop
AcceptPictureDrop
Permits pictures to be dropped on the container.
DesktopContainer.AcceptRawDataDrop
AcceptRawDataDrop(Type As String)
Permits data (of the type specified) to be dropped on the container. Type is a four-character resource code, e.g., 'snd ' or 'TEXT', or a UTI such as 'public.data' or 'public.jpeg'.
DesktopContainer.AcceptTextDrop
AcceptTextDrop
Permits text to be dropped on the container.
DesktopContainer.AddControl
AddControl(control As DesktopUIControl)
Adds the control passed to the layout.
Warning
Controls created dynamically (to be added to the container) will not have the default values controls are given when created in the Layout Editor. You will need to supply all default values. For example, with a DesktopListBox, if your code doesn't specify the DefaultRowHeight, it will be zero, which means the rows will not appear.
DesktopContainer.BitmapForCaching
BitmapForCaching(width As Integer, height As Integer) As Picture
Returns a bitmap that is configured correctly for using as a cache for content to be drawn to this container. This image supports Alpha Channels (not masked images).
Use this method instead of "New Picture" in order to get a Picture image that is suitable for HiDPI displays.
Raises exceptions in the following cases:
InvalidArgumentException if width, height, or scale are less than or equal to zero
OutOfMemoryException if the picture could not be allocated
If you need to support images with masks AND images that use alpha channels code like the following will let you handle both cases for HiDPI displays
Public Function BitmapForCaching(Extends g As Graphics, width As Integer = -1, height As Integer = -1, withMask As Boolean = False) As Picture
#Pragma BackgroundTasks False
If width = -1 Then width = g.Width
If height = -1 Then height = g.Height
If width <= 0 Then width = 1
If height <= 0 Then height = 1
#If TargetLinux Then
If withMask Then
Return New Picture(width, height, 32)
Else
Return New Picture(width, height)
End If
#Else
Var pic As Picture
If withMask Then
pic = New Picture(width * g.ScaleX, height * g.ScaleY, 32)
Else
pic = New Picture(width * g.ScaleX, height * g.ScaleY)
End If
' Set the resolutions
pic.HorizontalResolution = 72 * g.ScaleX
pic.VerticalResolution = 72 * g.ScaleY
' Make sure the two graphics object scales match the reference graphics object
Var gScaleX As Double = g.ScaleX
Var gScaleY As Double = g.ScaleY
pic.Graphics.ScaleX = gScaleX
pic.Graphics.ScaleY = gScaleY
If withMask Then
pic.Mask.Graphics.ScaleX = gScaleX
pic.Mask.Graphics.ScaleY = gScaleY
End If
Return pic
#Endif
End Function
DesktopContainer.Close
Close
Closes the container. Once closed, a container cannot be refreshed or redrawn. Calling Close triggers the CancelClosing event.
DesktopContainer.ControlAt
ControlAt(index As Integer) As Object
The zero-based way to lookup controls in the container.
All controls on the container are returned as an Object base type. You can use the IsA operator to check the specific type to see if the control is a DesktopButton, DesktopLabel, etc.
This example is in the Pressed event of a DesktopButton and displays the name of the first control in container:
MessageBox(Self.ControlAt(0).Name)
Loop through all the controls on a container and disable only the TextFields:
Var c As Object
For i As Integer = 0 To Self.ControlCount - 1
c = Self.ControlAt(i)
If c IsA DesktopTextField Then
DesktopTextField(c).Enabled = False
End If
Next
DesktopContainer.Controls
Controls As Iterable
Used to iterate through the controls on a container.
Note
This does not include non-control object instances. For that, use the Objects method.
All controls on the container are returned as a the DesktopControl base type. You can use the IsA operator to check the specific type to see if the control is a button, label, etc.
Loop through all the controls on a container and disable only the textfields:
For Each c As Object In Self.Controls
If c IsA DesktopTextField Then
DesktopTextField(c).Enabled = False
End If
Next
DesktopContainer.DrawInto
DrawInto(g As Graphics, x As Integer, y As Integer)
Note
DrawInto will only work if the container is on a window.
Draws the contents of the container into the specified Graphics context.
DesktopContainer.EmbedWithin
EmbedWithin(containingWindow As DesktopWindow, left As Integer = 0, top As Integer = 0, width As Integer = -1, height As Integer = -1)
Embeds the DesktopContainer in the specified Container control.
DesktopContainer.EmbedWithin
EmbedWithin(containingControl As DesktopUIControl, left As Integer = 0, top As Integer = 0, width As Integer = -1, height As Integer = -1)
Embeds the DesktopContainer in the specified Container control.
This code is in the Pressed event of a button and add a DesktopContainer to a window:
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.
' Add the container
MyContainer = New TestContainer
MyContainer.EmbedWithin(Self, 10, 100, 300, 400)
Elsewhere you can remove the container:
MyContainer.Close
DesktopContainer.EmbedWithinPanel
EmbedWithinPanel(containingPanel As DesktopPagePanel, page As Integer, left As Integer = 0, top As Integer = 0, width As Integer = -1, height As Integer = -1)
Embeds the DesktopContainer on a page in the passed DesktopPagePanel or DesktopTabPanel.
An instance of a DesktopContainer can only be embedded into one page.
The DesktopContainer is embedded on the passed page and the containing control is the parent of the DesktopContainer. 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 DesktopContainer 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 DesktopContainer.
This example adds a new tab to a DesktopTabPanel and then add a DesktopContainer to it:
MainTab.AddPanel("New Tab")
Var tabNum As Integer
tabNum = MainTab.PanelCount - 1
Var cc As New MyContainer
cc.EmbedWithinPanel(MainTab, tabNum)
DesktopContainer.FocusNext
FocusNext
Changes the focus to the next control in the Tab Order.
DesktopContainer.FocusPrevious
FocusPrevious
Changes the focus to the previous control in the Tab Order.
DesktopContainer.Hide
Hide
Makes the container invisible.
DesktopContainer.Objects
Objects As Iterable
Allows you to iterate through all the non-control object instances on the container.
Note
This does not include controls. For that, use the Controls method.
DesktopContainer.Refresh
Refresh(x As Integer, y As Integer, width As Integer, height As Integer, immediately As Boolean = False)
Redraws the area passed the next time the OS redraws the container or immediately if True is passed.
DesktopContainer.RemoveControl
RemoveControl(control As DesktopUIControl)
Removes the control from the DesktopContainer.
DesktopContainer.SetFocus
SetFocus
Sets the focus to the container, leaving no control with the focus.
Use the SetFocus method of the DesktopUIControl class to set the focus to a particular control in the window.
DesktopContainer.ShowPopover
ShowPopover(parentControl As DesktopUIControl, displaySide As DesktopWindow.DisplaySides = DesktopWindow.DisplaySides.Bottom, detachable As Boolean = True, animated As Boolean = True)
Displays the container as a popover next to the parentControl based upon the parameters passed.
The animated parameter is supported for Linux and macOS only.
This example from a button's Pressed event displays the container named MyPopover below (the default) the button:
Var c As New MyPopover
c.ShowPopover(Me)
Important
The ability to detach a popover is only supported on macOS.
Note
Behind the scenes, a popover is a window. Therefore once the user clicks away from it, the popover is closed by the OS and thus window used is Nil.
Important
On Linux, popovers require GTK 3.22 or later.
Event descriptions
DesktopContainer.ConstructContextualMenu
ConstructContextualMenu(Base As DesktopMenuItem, x As Integer, y As Integer) As Boolean
Fires whenever it is appropriate to display a contextual menu for the container.
This is the recommended way to handle contextual menus because this event figures out whether the user has requested the contextual menu, regardless of how he did it. Returns a Boolean. Base is analogous to the menu bar for the contextual menu. Any items you add to Base will be shown as menu items. If you return False, the event is passed up the parent hierarchy. If you return True, the contextual menu is displayed. The parameters x and y are the mouse locations. If the event was fired because of a non-mouse event, then x and y are both set to -1. See the example of a contextual menu in the examples for the DesktopUIControl class.
The following ConstructContextualMenu event handler builds a menu with three menu items plus a submenu with three additional menu items.
' Add some items
base.Add(New DesktopMenuItem("Test 1" )
base.Add(New DesktopMenuItem("Test 2"))
base.Add(New DesktopMenuItem("Test 3"))
' Add a Separator
base.Add(New DesktopMenuItem(MenuItem.TextSeparator))
' Add a sub menu
Var submenu As New DesktopMenuItem("SubMenu")
submenu.Add(New DesktopMenuItem("SubMenu Test 1"))
submenu.Add(New DesktopMenuItem("SubMenu Test 2"))
submenu.Add(New DesktopMenuItem("SubMenu Test 3"))
base.Add(submenu)
' Add a Separator
base.Add(New DesktopMenuItem(MenuItem.TextSeparator))
' Add an item that's on a menu bar so that you can see you don't
' have to handle every item returned.
base.Add(UntitledItem)
#If TargetMacOS Then
' because of how quitting the app is handled on macOS you cannot add the FileQuit item on macOS
#Else
base.Add(FileQuit)
#Endif
Return True
DesktopContainer.ContextualMenuItemSelected
ContextualMenuItemSelected(HitItem As DesktopMenuItem) As Boolean
Fires when a contextual DesktopMenuItem HitItem was selected but the MenuItemSelected event and the MenuHandler for the DesktopMenuItem did not handle the menu selection.
This event gives you a chance to handle the menu selection by inspecting the menuitem's Value or Tag properties to see which item was selected. Use this in conjunction with ConstructContextualMenu if you have not specified the MenuItemSelected event or the Menu Handler for the items on the contextual menu.
The following code in a ConstructContextualMenu event builds a simple contextual menu. The parameter Base as DesktopMenuItem is passed in as a parameter.
base.Add(New DesktopMenuItem("Import"))
base.Add(New DesktopMenuItem("Export"))
Return True ' display the contextual menu
The following Select Case statement in the ContextualMenuItemSelected event handler inspects the selected menu item, which is passed in as the HitItem as DesktopMenuItem parameter.
Select Case HitItem.Text
Case "Import"
MessageBox("You chose Import")
Case "Export"
MessageBox("You chose export")
End Select
Return True
DesktopContainer.DragEnter
DragEnter(Obj As DragItem, Action As DragItem.Types) As Boolean
Fired when the DragItem enters the container. Return True from this event to prevent the drop from occurring.
The Action parameter specifies the type drag action (default, copy, move or link).
DesktopContainer.DragExit
DragExit(Obj As DragItem, Action As DragItem.Types)
Fires when the DragItem exits the container.
The Action parameter specifies the type of drag action (default, copy, move or link).
DesktopContainer.DragOver
DragOver(x As Integer, y As Integer, Obj As DragItem, Action As DragItem.Types) As Boolean
Fires when the DragItem is over the container.
The coordinates x and y are relative to the Container. Returns a Boolean. Return True from this event to prevent the drop from occurring.
The Action parameter specifies the type of drag action (default, copy, move or link).
DesktopContainer.DropObject
DropObject(Obj As DragItem, Action As DragItem.Types)
The item represented by Obj has been dropped on the container.
The Action parameter specifies the type of drag action (default, copy, move or link).
DesktopContainer.FocusLost
FocusLost
Called when the DesktopContainer has lost the focus.
The AllowFocus property must be set to True in order for this event to be called.
DesktopContainer.FocusReceived
FocusReceived
Called when the DesktopContainer gets focus.
The AllowFocus property must be set to True in order for this event to be called.
DesktopContainer.KeyDown
KeyDown(Key As String) As Boolean
The passed Key has been pressed and not handled by an object in the container. For example, The tab key is never sent to any control. It is instead handled by the container itself. If the container has no controls that can receive the focus, any keys that are pressed will generate KeyDown events for the window or parent container. This event handler is passed a parameter that tells you which key was pressed. Returns a Boolean. Returning True means that no further processing is to be done with the Key, although the KeyUp event is still called.
The following example scrolls a picture. The picture has been added to the project. The properties XScroll and YScroll have been added to the container to hold the amounts the picture has been scrolled.
A convenient way to scroll a picture is with the four arrow keys. To do this, you place code in the KeyDown event handler of the container. This event receives each keystroke. Your code can test whether any of the arrow keys have been pressed and then take the appropriate action. For example, this code in the KeyDown event of the container scrolls the picture 8 pixels at a time:
Select Case Key.Asc
Case 31 ' down arrow
YScroll = YScroll - 8
Canvas1.Scroll(0, -8)
Return True
Case 29 ' Right arrow
XScroll = XScroll - 8
Canvas1.Scroll(-8, 0)
Return True
Case 30 ' up arrow
YScroll = YScroll + 8
Canvas1.Scroll(0, 8)
Return True
Case 28 ' Left arrow
XScroll = XScroll + 8
Canvas1.Scroll(8, 0)
Return True
End Select
The Paint event of the Canvas has the line of code that draws the picture:
g.DrawPicture(MyPicture, XScroll, YScroll)
DesktopContainer.KeyUp
KeyUp(Key As String)
Fires when the passed Key is released and no other object on the container has captured the event. It is not guaranteed to be the same key that received the KeyDown event.
DesktopContainer.MenuBarSelected
MenuBarSelected
The user has clicked in the menu bar or pressed a keyboard shortcut assigned to one of the menu items.
Use this event handler to determine whether conditions are right to enable the menu items.
DesktopContainer.MouseDown
MouseDown(X As Integer, Y As Integer) As Boolean
The mouse button has been pressed inside the container at the x, y local coordinates passed. Return True if you are going to handle the mouseDown.
DesktopContainer.MouseDrag
MouseDrag(X As Integer, Y As Integer)
The mouse button was pressed inside the container and moved (dragged) at the location local to the container passed in to x, y. The user has moved the mouse inside the container (but not over a control) while the mouse button is held down. This event handler receives parameters that indicate where the mouse is in local container coordinates. This event will not occur unless you return True in the MouseDown event.
DesktopContainer.MouseEnter
MouseEnter
The user has moved the mouse inside the container from a location outside the container.
DesktopContainer.MouseExit
MouseExit
The user has moved the mouse outside the container from a location inside the container.
DesktopContainer.MouseMove
MouseMove(X As Integer, Y As Integer)
The user has moved the mouse inside the container.
This event handler receives parameters that indicate where the mouse is in local container coordinates. The mouse has moved within the container to the x, y local coordinates passed.
DesktopContainer.MouseUp
MouseUp(X As Integer, Y As Integer)
The mouse button has been released. This event will not occur unless you return True in the MouseDown event handler. The idea behind this is that if the mouse was never down, it can't be up. This event handler receives parameters x and y that indicate where the mouse was released in local container coordinates.
DesktopContainer.MouseWheel
MouseWheel(X As Integer, Y As Integer, DeltaX As Integer, DeltaY As Integer) As Boolean
The mouse wheel has been moved.
The parameters X and Y are the mouse coordinates relative to the control that has received the event. The parameters DeltaX and DeltaY hold the number of scroll lines the wheel has been moved horizontally and vertically, as defined by the operating system. DeltaX is positive when the user scrolls right and negative when scrolling to the left. DeltaY is positive when the user scrolls down and negative when scrolling up. Returns a Boolean. Return True to prevent the event from propagating further.
DesktopContainer.Opening
Opening
The container is opening but hasn't been displayed yet. Controls also receive Opening events. A container receives its Opening event after all of the controls have received their Opening events.
You should use the Opening event instead of the Constructor for initialization.
DesktopContainer.Paint
Paint(g As Graphics, areas() As Rect)
Some portion of the container needs to be redrawn either because the container is opening or it has been exposed when a window in front of it was moved or closed. This event handler receives a Graphics object as a parameter that represents the graphics that will be drawn in the container. Graphics objects have their own methods for drawing graphics.
DesktopContainer.ScaleFactorChanged
ScaleFactorChanged
The backing store scale factor has changed for this container and the application should invalidate any cached bitmaps or other relevant state.
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.
While DesktopContainer is a subclass of DesktopWindow, it should be thought of as a hybrid between DesktopWindow and DesktopUIControl. 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.
Note
At compile time, for historical reasons an underscore (_) is added to the name of any DesktopContainer instance. Be aware of this should you be using Introspection to check the name of a DesktopContainer instance.
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 containers when the window in which they are embedded is moved or resized.
The Show/Hide and the Visible property can be used to set the visibility of an embedded container.
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.
Compatibility
Desktop projects on all supported operating systems.
See also
DesktopWindow parent class