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

Control

index As Integer

Object

Controls

Iterable

DrawInto

g As Graphics, x As Integer, y As Integer

EmbedWithin

ContainingWindow As DesktopWindow, [left As Integer, top As Integer, width As Integer, height As Integer]

containingControl As DesktopUIControl, [left As Integer, top As Integer, width As Integer, height As Integer]

EmbedWithinPanel

ContainingPanel As DesktopPagePanel, Page As Integer, [left As Integer, top As Integer, width As Integer, height As Integer]

FocusNext

FocusPrevious

Hide

Maximize

Minimize

Refresh

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

Restore

SetFocus

Show

ShowModal

parent As DesktopWindow = Nil

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 window's background.

You should not assign a new picture to the backdrop of the window when being inside the paint event of that window. 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 Open 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 DesktopWindow 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 window (i.e. including frame/title decorations).

On Linux the Left/Top bounds exclude the decorations due to the way window decorations are handled there.

To get the bounds:

Var winBounds As Rect
winBounds = Self.Bounds
MessageBox("Left = " + winBounds.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 Realbasic.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 window.

This property is read-only.

The following example is in the Action event of a DesktopButton. It displays the number of controls in the Window:

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 window 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 window. Use this instead of the deprecated MacWindowPtr and WinHWND.

This property is read-only.

When interfacing with Cocoa APIs using Declares Window.Handle always gives a NSWindow or NSPanel.

DesktopContainer.HasBackgroundColor

HasBackgroundColor As Boolean

If True, the background color of the window 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 window.

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 screen and the left edge of the content area of the window.

The left frame of the window is taken into account.

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 window and the DesktopApplication class's MouseCursor property is Nil.

If the DesktopApplication class MouseCursor is not Nil, non-Nil MouseCursors belonging to any windows or Controls are ignored. If the window'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 window.

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 window.

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 window.

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 Window.

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 window.

The Top value refers to the topmost part of the window content region, which is the area starting below the Window Title Bar.

Setting Top = 0 moves the top of the windows content area to the top of the screen. On macOS, this puts the window behind the main menu bar that appears at the top of the screen. To position a window directly below the main menu bar, you should use DesktopDisplay to get the topmost position after the menu bar and then use DesktopWindow to position the window.

DesktopContainer.Transparent

Transparent As Boolean

If True, the background shows through to the DesktopContainer; if False, the DesktkopContainer 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 window.

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 window.

DesktopContainer.AcceptRawDataDrop

AcceptRawDataDrop(Type As String)

Permits data (of the type specified) to be dropped on the window. 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 window.

DesktopContainer.AddControl

AddControl(control As DesktopUIControl)

Adds the control passed to the layout.

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 Window. 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
    pic.Graphics.ClearRectangle(0, 0, pic.Width, pic.Height)

    // 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 window. Once closed, a window cannot be refreshed or redrawn. Calling Close triggers the CancelClosing event.

DesktopContainer.Control

Control(index As Integer) As Object

The zero-based way to lookup controls in the window.

All controls on the window 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 PushButton, Label, etc.

This example is in the Pressed event of a DesktopButton and displays the name of the first control in Window:

MessageBox(Self.ControlAt(0).Name)

Loop through all the controls on a Window and disable only the TextFields:

Var c As Object
For i As Integer = 0 To Self.ControlCount - 1
  c = Window.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 window.

All controls on the window 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 Window and disable only the textfields:

For Each c As DesktopControl 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)

Draws the contents of the window into the specified Graphics context.

DesktopContainer.EmbedWithin

EmbedWithin(ContainingWindow As DesktopWindow, [left As Integer, top As Integer, width As Integer, height As Integer])

Embeds the DesktopContainer in the specified Container control.

DesktopContainer.EmbedWithin

EmbedWithin(containingControl As DesktopUIControl, [left As Integer, top As Integer, width As Integer, height As Integer])

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, top As Integer, width As Integer, height As Integer])

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 window invisible.

DesktopContainer.Maximize

Maximize

Maximizes the window if it is not already maximized and calls the Maximized event. If the window was already maximized when you call this method, then it is restored to its prior state and calls the Restored event.

If the window is not visible when Maximize is called, it becomes visible.

DesktopContainer.Minimize

Minimize

Minimizes the window and calls the Minimize event handler.

DesktopContainer.Refresh

Refresh(x As Integer, y As Integer, width As Integer, height As Integer, immediately As Boolean = False)

Redraws the entire window passed the next time the OS redraws the window or immediately if True is passed.

DesktopContainer.Restore

Restore

Restores a minimized or maximized window to its previous size.

DesktopContainer.SetFocus

SetFocus

Sets the focus to the window, 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.Show

Show

Forces the window to immediately become visible rather than wait until the application is idle.

Calling Show immediately brings the window to the front.

DesktopContainer.ShowModal

ShowModal(parent As DesktopWindow = Nil)

Displays the window and causes the current method to stop executing until the window closes or becomes invisible.

If the window is a Document window it is shown as a normal Document window. It becomes the frontmost window but it is not modal. You must use a modal window Frame type to force the window into a modal state.

If a parentWindow is passed, the window being displayed will be modal to the parent window on macOS.

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 window.

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 DesktopWindow. 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 DesktopWindow.

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 DesktopWindow.

The coordinates x and y are relative to the DesktopWindow. 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 window.

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 window. For example, The tab key is never sent to any control. It is instead handled by the window itself. If the window has no controls that can receive the focus, any keys that are pressed will generate KeyDown events for the window. 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 window 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 window. 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 window 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 window 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 window 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 window and moved (dragged) at the location local to the window passed in to x, y. The user has moved the mouse inside the window (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 window 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 window from a location outside the window.

DesktopContainer.MouseExit

MouseExit

The user has moved the mouse outside the window from a location inside the window.

DesktopContainer.MouseMove

MouseMove(X As Integer, Y As Integer)

The user has moved the mouse inside the window.

This event handler receives parameters that indicate where the mouse is in local window coordinates. The mouse has moved within the window 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 window 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 window is opening but hasn't been displayed yet. Controls also receive Opening events. A window 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.

After the window opens and becomes the active window, the Activated event is called.

DesktopContainer.Paint

Paint(g As Graphics, areas() As Rect)

Some portion of the window needs to be redrawn either because the window 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 window. Graphics objects have their own methods for drawing graphics.

DesktopContainer.ScaleFactorChanged

ScaleFactorChanged

The backing store scale factor has changed for this Window 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.

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.

Compatibility

Desktop projects on all supported operating systems.

See also

DesktopWindow parent class; DesktopWindow classes