---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
` or container.
>
> Setting Top = 0 moves the top of the container's content area to the top of the parent window or container.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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:
>
> ``` xojo
> Me.Transparent = False
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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:
>
> ``` xojo
> Me.Visible = False
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
DesktopContainer.Width
**Width** As `Integer`
> The width (in points) of the control.
>
> The following example resizes the control:
>
> ``` xojo
> Me.Width = 200
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
DesktopContainer.AcceptPictureDrop
**AcceptPictureDrop**
> Permits pictures to be dropped on the container.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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'.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
DesktopContainer.AcceptTextDrop
**AcceptTextDrop**
> Permits text to be dropped on the container.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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.
>
>
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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
>
> ``` xojo
> 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
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
DesktopContainer.Close
**Close**
> Closes the container. Once closed, a container cannot be refreshed or redrawn. Calling Close triggers the CancelClosing event.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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:
>
> ``` xojo
> MessageBox(Self.ControlAt(0).Name)
> ```
>
> Loop through all the controls on a container and disable only the TextFields:
>
> ``` xojo
> 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
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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.
>
>
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
DesktopContainer.DrawInto
**DrawInto**(g As `Graphics`, x As `Integer`, y As `Integer`)
>
>
>
>
> Note
>
>
>
> DrawInto will only work if the container is on a window.
>
>
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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 DesktopWindow.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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 DesktopUIControl.
>
> This code is in the Pressed event of a button and add a DesktopContainer to a window:
>
> ``` xojo
> 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.
>
> ``` xojo
> ' Add the container
> MyContainer = New TestContainer
> MyContainer.EmbedWithin(Self, 10, 100, 300, 400)
> ```
>
> Elsewhere you can remove the container:
>
> ``` xojo
> MyContainer.Close
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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:
>
> ``` xojo
> MainTab.AddPanel("New Tab")
> Var tabNum As Integer
> tabNum = MainTab.PanelCount - 1
>
> Var cc As New MyContainer
> cc.EmbedWithinPanel(MainTab, tabNum)
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
DesktopContainer.FocusNext
**FocusNext**
> Changes the focus to the next control in the Tab Order.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
DesktopContainer.FocusPrevious
**FocusPrevious**
> Changes the focus to the previous control in the Tab Order.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
DesktopContainer.Hide
**Hide**
> Makes the container invisible.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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.
>
>
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
DesktopContainer.Refresh
**Refresh**(immediately As `Boolean` = `False`)
> Redraws the portion specified of the contents of the control the next time the OS redraws the control or immediately if `True` is passed.
>
> If you are calling this so frequently that you experience a slowdown in your code, pass `True` for the immediately parameter.
>
> Calling this method causes the Render event to fire.
>
> Refresh the entire area immediately:
>
> ``` xojo
> Me.Refresh(True)
> ```
>
> Refresh a portion of the area the next time the OS redraws the control:
>
> ``` xojo
> Me.Refresh(100, 150, 200, 300)
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
**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.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
DesktopContainer.RemoveControl
**RemoveControl**(control As `DesktopUIControl`)
> Removes the *control* from the DesktopContainer.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
DesktopContainer.ShowPopover
**ShowPopover**(parentControl As `DesktopUIControl`, displaySide As `DesktopWindow.DisplaySides` = `DesktopWindow.DisplaySides`.Bottom, detachable As `Boolean` = `True`, animated As `Boolean` = `True`, x As `Integer` = -1, y As `Integer` = -1)
> Displays the container as a popover next to the *parentControl* based upon the parameters passed. When provided, the optional *x* and *y* values passed display the popover at that offset relative to the upper-left corner of the parent control.
>
> 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:
>
> ``` xojo
> 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.
>
>
forsearch
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.
>
> ``` xojo
> ' 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
> ```
forsearch
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.
>
> ``` xojo
> 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.
>
> ``` xojo
> Select Case HitItem.Text
> Case "Import"
> MessageBox("You chose Import")
> Case "Export"
> MessageBox("You chose export")
> End Select
>
> Return True
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
DesktopContainer.Closing
**Closing**
> The container is about to close. You cannot cancel the closing at this time.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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).
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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).
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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).
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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).
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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:
>
> ``` xojo
> 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:
>
> ``` xojo
> g.DrawPicture(MyPicture, XScroll, YScroll)
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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.
forsearch
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.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
DesktopContainer.MouseEnter
**MouseEnter**
> The user has moved the mouse inside the container from a location outside the container.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
DesktopContainer.MouseExit
**MouseExit**
> The user has moved the mouse outside the container from a location inside the container.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
DesktopContainer.Resized
**Resized**
> The container has been resized by the user or by code that changes the container's Width or Height properties.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
DesktopContainer.Resizing
**Resizing**
> The user is in the process of resizing the container.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
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.
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.
``` xojo
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
| | |
|-----------------------|---------|
| **Project Types** | Desktop |
| **Operating Systems** | All |
`DesktopWindow` parent class