Class

DesktopContainer


Description

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

Methods

Name

Parameters

Returns

Shared

AcceptFileDrop

FileType As String

AcceptPictureDrop

AcceptRawDataDrop

Type As String

AcceptTextDrop

AddControl

control As DesktopUIControl

BitmapForCaching

width As Integer, height As Integer

Picture

Close

ControlAt

index As Integer

Object

Controls

Iterable

DrawInto

g As Graphics, x As Integer, y As Integer

EmbedWithin

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

EmbedWithinPanel

containingPanel As DesktopPagePanel, page As Integer, left As Integer = 0, top As Integer = 0, width As Integer = -1, height As Integer = -1

FocusNext

FocusPrevious

Hide

Objects

Iterable

Refresh

x As Integer, y As Integer, width As Integer, height As Integer, immediately As Boolean = False

RemoveControl

control As DesktopUIControl

SetFocus

ShowPopover

parentControl As DesktopUIControl, displaySide As DesktopWindow.DisplaySides = DesktopWindow.DisplaySides.Bottom, detachable As Boolean = True, animated As Boolean = True

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