Class
DesktopWindow
Description
A distinct area of the user interface consisting of a frame and body that lets the user view and interact with content in an app.
Properties
Name |
Type |
Read-Only |
Shared |
---|---|---|---|
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
Methods
Name |
Parameters |
Returns |
Shared |
---|---|---|---|
FileType As String |
|||
Type As String |
|||
control As DesktopUIControl |
|||
index As Integer |
|||
x As Integer, y As Integer, width As Integer, height As Integer, immediately As Boolean = False |
|||
control As DesktopUIControl |
|||
parent As DesktopWindow = Nil |
|||
parent As DesktopWindow = Nil |
|||
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 |
Events
Name |
Parameters |
Returns |
---|---|---|
appQuitting As Boolean |
||
Base As DesktopMenuItem, x As Integer, y As Integer |
||
selectedItem As DesktopMenuItem |
||
Obj As DragItem, Action As DragItem.Types |
||
Obj As DragItem, Action As DragItem.Types |
||
x As Integer, y As Integer, Obj As DragItem, Action As DragItem.Types |
||
Obj As DragItem, Action As DragItem.Types |
||
Key As String |
||
Key As String |
||
X As Integer, Y As Integer, DeltaX As Integer, DeltaY As Integer |
||
Enumerations
DesktopWindow.DisplaySides
DisplaySides
Specifies where the popover will display relative to the control its popping over.
Enum |
Description |
---|---|
Bottom |
Below the parent control. |
Left |
To the left of the parent control. |
Top |
Above the parent control. |
Right |
To the right of the parent control. |
DesktopWindow.Locations
Locations
Specifies where the window will open.
Enum |
Description |
---|---|
Default |
The default placement based upon the OS. Often this is Staggered. |
ParentWindow |
Over the parent window if it opens another window. |
MainScreen |
On the primary or main screen on a multi-screen setup. |
ParentWindowScreen |
On the same screen as the parent window in a multi-screen setup. |
Staggered |
New windows open slightly offset to the top and left from previously opened windows. |
DesktopWindow.Types
Types
Specifies the type of window.
Value |
---|
Document |
MovableModal |
ModalDialog |
Floating |
PlainBox |
ShadowedBox |
Rounded |
GlobalFloating |
Sheet |
ModelessDialog |
Property descriptions
DesktopWindow.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 Opening event.
Me.Backdrop = MyPicture
DesktopWindow.BackgroundColor
BackgroundColor As ColorGroup
The background color for the object. The HasBackgroundColor property, must be set to True to have the BackgroundColor displayed.
This code sets the HasBackgroundColor property and sets the value of the BackgroundColor property:
Me.HasBackgroundColor = True
Me.BackgroundColor = &c110034
DesktopWindow.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 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
DesktopWindow.Changed
Changed As Boolean
Indicates whether the window has been modified. The ContentsChanged event fires when the value of this property has changed. On macOS, the window's Close button displays a dot when Changed is True.
This example is in the ContentsChanged event of the control.
If Me.Changed Then
MessageBox("The contents have changed!")
Else
MessageBox("The ContentsChanged event has not fired.")
End If
DesktopWindow.ControlCount
ControlCount As Integer
The number of controls in the window.
This property is read-only.
The following example is in the Pressed event of a DesktopButton. It displays the number of controls in the Window:
MessageBox(Self.ControlCount.ToString)
DesktopWindow.DefaultLocation
DefaultLocation As Locations
If it's a Document window, this property represents the window's location at which the window will initially be placed when it opens.
The Locations enumeration contains all potential values for this property.
DesktopWindow.DockItem
DockItem As DockItem
Enables you to access the DockItem class to manipulate the dock item associated with the window (macOS only).
This property is read-only.
The DockItem class has two methods, UpdateNow and ResetIcon, and one property, Graphics. Use the methods of the Graphics class to modify the appearance of the icon. (The Graphics property may be Nil; it is non-Nil only when a macOS window has been minimized to the dock.) The ResetIcon method resets the icon to its original state (default appearance). Since a macOS icon is intended to be scaled automatically, you should design it as a 512 x512 pixel icon and include smaller sizes. Call the UpdateNow method to redraw the icon. You can also use the Graphics.ClearRectangle method to start over form a blank icon. Anything you can do with a Graphics object you are able to do with the Dock's Graphics object (like drawing in a picture or using a Shape 2D). The Dockitem property of the DesktopApplication class enables you to control the DockItem for the whole application.
DesktopWindow.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)
DesktopWindow.FullScreen
FullScreen As Boolean
When set to True, the window resizes itself to cover the entire screen.
The values of the Left, Top, Width, and Height properties are adjusted to reflect the window's new position. They cannot be changed as long as FullScreen is True. If MenuBarVisible is set to True, the top of the window will be partially covered by the menu bar in macOS. In the case of multiple monitors, the window resizes to fit the monitor which contains the greatest portion of the window.
FullScreen defaults to False.
On macOS, you can instead set HasFullScreenButton to True to let the user enable the macOS full screen mode.
DesktopWindow.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.
DesktopWindow.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
DesktopWindow.HasCloseButton
HasCloseButton As Boolean
If True, the window will include a Close button in its Title Bar.
This property is read-only.
On macOS, if the ContentsChanged property is True, then the close button will display a dot, which is used to indicate there are unsaved changes in the window.
MacOS does not display close buttons on Movable Modal windows.
DesktopWindow.HasFullScreenButton
HasFullScreenButton As Boolean
When set to True, the window control to enable macOS full screen mode is displayed.
This property is read-only.
This property can only be changed at design-time.
Clicking the control enables the macOS native full screen mode. This property has no effect on Windows or Linux.
In order to test if the user is running in the native full screen mode you should check both full screen properties:
If Self.HasFullScreenButton And Self.FullScreen Then
' User is in native full screen mode
End If
When HasFullScreenButton is False, setting FullScreen to True cause the Window to fill the screen although not using the native full screen mode so the behavior will be different.
Starting with macOS 10.11 (El Capitan), the Maximize button is treated as a full screen button. You do not have to specifically set HasFullScreenButton to True. In order for the user to maximize a window rather than put it into Full Screen Mode, they should Option-Click on the Maximize button or double-click the title bar.
DesktopWindow.HasMaximizeButton
HasMaximizeButton As Boolean
If True, the window has an enabled Maximize button in its Title bar.
This property is read-only.
You can only change this setting while in the Window Layout Editor.
Starting with macOS 10.11 (El Capitan), the Maximize button is treated as a full screen button. You do not have to specifically set HasFullScreenButton to True. In order for the user to maximize a window rather than put it into Full Screen Mode, they should Option-Click on the Maximize button or double-click the title bar.
DesktopWindow.HasMinimizeButton
HasMinimizeButton As Boolean
If True, the window has a Minimize button in its Title bar. The default is True.
This property is read-only.
You can only change this setting while in the Window Layout Editor.
DesktopWindow.Height
Height As Integer
The height of the content region of the window in points.
Me.Height = 100
DesktopWindow.ImplicitInstance
ImplicitInstance As Boolean
When True, an instance of this window will be opened automatically upon application launch.
This is a design-time-only property and thus is not accessible via code.
DesktopWindow.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
DesktopWindow.MaximumHeight
MaximumHeight As Integer
The maximum height (in points) to which the window can be resized.
DesktopWindow.MaximumWidth
MaximumWidth As Integer
The maximum width (in points) to which the window can be resized.
DesktopWindow.MenuBar
MenuBar As DesktopMenuBar
The menubar that is associated with the window.
This is the DesktopMenuBar to use with the window. Typically this is the MenuBar that was added to the project by default, but it can be any MenuBar in your project.
When the window is active, this MenuBar is displayed.
On macOS, if no MenuBar is assigned to the window, DesktopApplication.MenuBar is used. To hide the MenuBar, set the MenuBar property to None (in the Inspector) or Nil (in code) for both the window and the Application.
On Microsoft Windows and Linux, a window can have a MenuBar just below its title bar. The MenuBar assigned to the window is used as the window MenuBar. If the window does not have a MenuBar specified (i.e. it is set to None in the Inspector or Nil in code), then the window will not display a MenuBar.
Note
For MDI applications, the MDI window uses DesktopApplication.MenuBar as its MenuBar. Individual document windows cannot have a MenuBar (a Windows limitation). However, floating windows can have a MenuBar and these windows use the MenuBar specified in the window.
This code in a DesktopButton Pressed event toggles the MenuBar on and off:
If Self.MenuBar <> Nil Then
#If TargetMacOS Then
App.MenuBar = Nil
#Endif
Self.MenuBar = Nil
Else
#If TargetMacOS Then
App.MenuBar = MainMenuBar
#Endif
Self.MenuBar = MainMenuBar
End If
DesktopWindow.MinimumHeight
MinimumHeight As Integer
The minimum height to which the window can be resized.
DesktopWindow.MinimumWidth
MinimumWidth As Integer
The minimum width to which the window can be resized.
DesktopWindow.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
DesktopWindow.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.
DesktopWindow.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.
DesktopWindow.Resizeable
Resizeable As Boolean
If True, the window is resizeable. The default is True.
This property is read-only.
You can only change this setting while in the Window Layout Editor.
DesktopWindow.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.
DesktopWindow.SystemUIVisible
SystemUIVisible As Boolean
When set to False, hides system-wide UI, such as the Dock on macOS or the Start menu and taskbar on Windows. Defaults to True.
The behavior of this properties varies by OS. This is the behavior on current OS's (macOS Mojave, Windows 10, Linux Mint):
Mac: When False (or OFF), the Dock and main menu bar are hidden when the window is frontmost.
Windows: When False (or OFF), the taskbar (including "Start" button) is hidden, regardless of whether your app is frontmost.
Linux Mint: When False (or OFF), the window menu bar is hidden (other distributions may have different behavior).
DesktopWindow.Title
Title As String
The text in the window's Title bar.
DesktopWindow.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.AvailableTop to get the topmost position after the menu bar and then use Bounds to position the window.
DesktopWindow.Type
Type As Types
The window type. Set the desired Type in the Inspector.
This property is read-only.
Use the Types enumeration to determine the value of this property.
The various frame types are covered in the Desktop Windows topic.
DesktopWindow.Visible
Visible As Boolean
Controls the visibility of the window.
If True, the window will be visible when it is opened. After it is opened, setting Visible to False is equivalent to calling the Hide method. Or, if the window not initially shown, setting Visible to True is equivalent to calling the Show method.
DesktopWindow.Width
Width As Integer
The width of the content region of the window.
The left and right window frames are taken into account.
Method descriptions
DesktopWindow.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.
DesktopWindow.AcceptPictureDrop
AcceptPictureDrop
Permits pictures to be dropped on the window.
DesktopWindow.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'.
DesktopWindow.AcceptTextDrop
AcceptTextDrop
Permits text to be dropped on the window.
DesktopWindow.AddControl
AddControl(control As DesktopUIControl)
Adds the control passed to the layout.
To remove a control, call its Close method.
Warning
Controls created dynamically (to be added to the window) 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.
DesktopWindow.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
' 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
DesktopWindow.Close
Close
Closes the window. Once closed, a window cannot be refreshed or redrawn. Calling Close triggers the CancelClosing event.
DesktopWindow.ControlAt
ControlAt(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 DesktopButton, DesktopLabel, 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
Note
The order in which controls are indexed is based on their layering on the window. You can change this in the Layout Editor using the Order Front, Order Forward, Order Back, and Order Backwards buttons. If you need the tab order, use the TabIndex property.
DesktopWindow.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.
Note
This does not include non-control object instances. For that, use the Objects method.
Note
The iterator returns an Object rather than a DesktopControl. This allows it to return DesktopContainers for example that are not DesktopControls.
Loop through all the controls on a Window and disable only the textfields:
For Each c As Object In Self.Controls
If c IsA DesktopTextField Then
DesktopTextField(c).Enabled = False
End If
Next
DesktopWindow.DrawInto
DrawInto(g As Graphics, x As Integer, y As Integer)
Draws the contents of the window into g at the coordinates specified by the x and y parameters passed.
DesktopWindow.FocusNext
FocusNext
Changes the focus to the next control in the Tab Order.
DesktopWindow.FocusPrevious
FocusPrevious
Changes the focus to the previous control in the Tab Order.
DesktopWindow.Hide
Hide
Makes the window invisible.
DesktopWindow.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.
DesktopWindow.Minimize
Minimize
Minimizes the window and calls the Minimize event handler.
DesktopWindow.Objects
Objects As Iterable
Allows you to iterate through all the non-control object instances on the window.
Note
This does not include controls. For that, use the Controls method.
DesktopWindow.Refresh
Refresh(immediately As Boolean = False)
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.
DesktopWindow.RemoveControl
RemoveControl(control As DesktopUIControl)
Removes the control from the DesktopWindow.
DesktopWindow.Restore
Restore
Restores a minimized or maximized window to its previous size.
DesktopWindow.SetFocus
SetFocus
Sets the focus to the window, leaving no control with the focus. If the window is in the process of closing, SetFocus will do nothing.
Use the SetFocus method of the DesktopUIControl class to set the focus to a particular control in the window.
DesktopWindow.Show
Show(parent As DesktopWindow = Nil)
Forces the window to immediately become visible rather than wait until the application is idle.
Passing the optional parent parameter allows you to specify the parent window and thus show a sheet-style window non-modally on macOS.
Calling Show immediately brings the window to the front.
DesktopWindow.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.
DesktopWindow.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 window 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.
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.
To make sure your popover displays in front of any global floating windows, set the Type property to GlobalFloating.
This example from a button's Pressed event displays the window named MyPopover below (the default) the button:
Var c As New MyPopover
c.ShowPopover(Me)
Important
The ability to detach a popover is only supported on macOS.
Important
On Linux, popovers require GTK 3.22 or later.
Important
On Windows, ShowPopover does not support window types ModalDialog, MoveableModal and SheetWindow. An UnsupportedOperationException will be raised.
Event descriptions
DesktopWindow.Activated
Activated
The window has been activated.
In an app with multiple windows, the Activated event fires each time the window becomes the frontmost. This includes when it opens. When the window first opens, the Opening event fires prior to the Activated event. Subsequent activations fire the Activated event but not the Opening event.
DesktopWindow.CancelClosing
CancelClosing(appQuitting As Boolean) As Boolean
The window is about to be closed by the user clicking the close button, by calling the Quit or Close methods.
When the app is quitting, CancelClosing and Closing are called as a pair for each open window. Closing will be called after CancelClosing executes, assuming that the close wasn't canceled by the user.
Return True to prevent the window (and in the case of the Quit method, other open windows) from closing. The parameter appQuitting is True when the window is being closed because the whole app is quitting and False when only the window is being closed.
DesktopWindow.Closing
Closing
The Window is about to close. You cannot cancel the closing at this time. If you need to decide or interact with the user to make sure that the Window should be closed, use CancelClosing event instead which is called before Closing.
DesktopWindow.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.AddMenu(New DesktopMenuItem("Test 1" ))
base.AddMenu(New DesktopMenuItem("Test 2"))
base.AddMenu(New DesktopMenuItem("Test 3"))
' Add a Separator
base.AddMenu(New DesktopMenuItem(MenuItem.TextSeparator))
' Add a sub menu
Var submenu As New DesktopMenuItem("SubMenu")
submenu.AddMenu(New DesktopMenuItem("SubMenu Test 1"))
submenu.AddMenu(New DesktopMenuItem("SubMenu Test 2"))
submenu.AddMenu(New DesktopMenuItem("SubMenu Test 3"))
base.AddMenu(submenu)
Return True
DesktopWindow.ContentsChanged
ContentsChanged
Fires when the value of the Changed property has changed. Changing the value of the Changed property triggers this event.
DesktopWindow.ContextualMenuItemSelected
ContextualMenuItemSelected(selectedItem As DesktopMenuItem) As Boolean
Fires when a contextual DesktopMenuItem selectedItem 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 Text 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.AddMenu(New DesktopMenuItem("Import"))
base.AddMenu(New DesktopMenuItem("Export"))
Return True ' display the contextual menu
The following Select statement in the ContextualMenuItemSelected event handler inspects the selected menu item, which is passed in as the selectedItem as DesktopMenuItem parameter.
Select Case selectedItem.Text
Case "Import"
MessageBox("You chose Import")
Case "Export"
MessageBox("You chose export")
End Select
Return True
DesktopWindow.Deactivated
Deactivated
The window has been deactivated. For example, a window belonging to another app has been activated.
DesktopWindow.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).
DesktopWindow.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).
DesktopWindow.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).
DesktopWindow.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).
DesktopWindow.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)
DesktopWindow.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.
DesktopWindow.Maximized
Maximized
The window has been maximized.
This event handler is called when the window is maximized.
This can occur when the user selects one of the window buttons or menu commands for the action. The event handler may also be called using one of the following methods, depending on the state of the window:
DesktopWindow.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.
DesktopWindow.Minimized
Minimized
The window has been minimized.
This event is called when the Minimize method is called or when the user choose to minimize the window using the window buttons or menu item.
A minimized window is still returned by the DesktopApplication.WindowAt method and it is possible that it is the front-most (0 position) window.
DesktopWindow.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.
DesktopWindow.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.
DesktopWindow.MouseEnter
MouseEnter
The user has moved the mouse inside the window from a location outside the window.
DesktopWindow.MouseExit
MouseExit
The user has moved the mouse outside the window from a location inside the window.
DesktopWindow.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.
DesktopWindow.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.
DesktopWindow.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.
DesktopWindow.Moved
Moved
The window has been moved by the user or by code that changes the window's Left or Top properties.
DesktopWindow.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.
DesktopWindow.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.
DesktopWindow.Resized
Resized
The window has been resized by the user or by code that changes the window's Width or Height properties.
DesktopWindow.Resizing
Resizing
The user is in the process of resizing the window.
Resizing executes regardless of whether the LiveResize property is True. Note: The Top, Left, Width and Height properties have already been adjusted to account for sizing at this point if LiveResize is on, but the controls haven't drawn themselves. You could, for example, use a Boolean property to indicate whether a DesktopCanvas control should redraw in its Paint event.
DesktopWindow.Restored
Restored
The window has been restored to its prior state from either being minimized or maximized.
This event handler is called when the window is restored from a prior state.
This can occur when the user selects one of the window buttons or menu commands for the action. The event handler may also be called using one of the following methods, depending on the state of the window:
DesktopWindow.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
Window constructors are called after the window and its controls are created, but before the Opening events are called. If you are initializing Window properties, you should do so using the Opening event handler rather than the Constructor. Using the Constructor could result in property changes you make being overwritten by the built-in Window initializations.
Converting windows to containers
A window can be converted to a DesktopContainer by changing its Super Class to DesktopContainer. However, you cannot change the default window to a DesktopContainer.
Understanding sheet windows
A Sheet Window is the official name for a type of macOS window that is modal to a parent window. On other platforms, they behave as an ordinary movable modal dialog box.
A Sheet window can be displayed by passing a reference to the parent window when calling the ShowModal method. If SheetWindow is defined as a Sheet window and MainWindow is a Document window, then the statement:
SheetWindow.ShowModal(Self)
will show the Sheet window using the calling window (in this case, MainWindow) as the Parent window.
You can also use your own instance like this:
Var sw As New SheetWindow
sw.ShowModal(Self)
Custom cursors
The MouseCursor property controls the appearance of the pointer when it is over the window, provided the MouseCursor property of the DesktopApplication class is Nil. If you also want the pointer to change to another shape when it is over a control within the window, you must either assign the new value to the Window's MouseCursor property or temporarily set the window's MouseCursor property to Nil and the control's MouseCursor property to the desired cursor. See the section on the MouseCursor class for an example.
You can assign a MouseCursor using the library of cursors in the Cursors module.
The resizing event handler
This example resizes three TextFields on the form in the Resizing event.The three TextFields are aligned horizontally. As the user stretches or shrinks the window, the TextFields' widths change proportionally.
Var availableSpace As Integer
Var field1Size, field2Size, field3Size As Integer
' subtract 40 pixels for the space between the
' three fields and on left and right side of the window
availableSpace = Me.Width - 40
' calculate the size of each field based on a percentage
field1Size = availableSpace * 0.6 ' 60 percent
field2Size = availableSpace * 0.3 ' 30 percent
field3Size = availableSpace * 0.1 ' 10 percent
' Set the field widths
TextField1.Width = field1Size
TextField2.Width = field2Size
TextField3.Width = field3Size
' reposition the fields based on the new sizes
TextField2.Left = TextField1.Left + TextField1.Width + 10
TextField3.Left = TextField2.Left + TextField2.Width + 10
DrawInto example
This example draws the contents of a window into a Graphics object. For example, add a second window to a new project (Window2) and set its Visible property to False. Add a variety of controls to Window2. In the Paint event of Window1, use this code to draw the second window into the first window:
Window2.DrawInto(g, 0, 0)
The contents of Window2 are drawn into Window1.
Accessing controls and properties in other windows
When changing a window property from another window, there are two possible approaches you can take. If you have only one instance of the window you need to reference, you can use the window's object name as a reference. For example, if you had a window called window1 that had a DesktopTextField called TextField1 and you wanted to assign the value "Fred" to the text property of that TextField, you would using the following syntax:
Window1.TextField1.Text = "Fred"
If you have multiple instances of the same window class open at the same time, then a reference to the target window must be included as in this example where a new window is opened and its window title changed. "anotherWindow" is a window class in the Project.
Var w As AnotherWindow
w = New AnotherWindow
w.Title = "Your Results"
Handling drag and drop
For an explanation of handling drag and drop, see the DesktopUIControl class and the DragItem class.
Sample code
This example sets the background color of the window to grey, provided the HasBackgroundColor property is set to True.
BackgroundColor = Color.RGB(80, 80, 80)
This example increases the width of the window by 20 pixels.
Width = Width + 20
This example changes the title of the window.
Title = "Document 1"
Compatibility
Desktop projects on all supported operating systems.
See also
Object parent class; DesktopApplication.WindowAt function; MessageDialog class.