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.

Methods

Name

Parameters

Returns

Shared

AcceptFileDrop

FileType As String

AcceptPictureDrop

AcceptRawDataDrop

Type As String

AcceptTextDrop

AddControl

control As DesktopUIControl

BitmapForCaching

width As Integer, height As Integer

Picture

Close

ControlAt

index As Integer

Object

Controls

Iterable

DrawInto

g As Graphics, x As Integer, y As Integer

FocusNext

FocusPrevious

Hide

Maximize

Minimize

Objects

Iterable

Refresh

immediately As Boolean = False

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

RemoveControl

control As DesktopUIControl

Restore

SetFocus

Show

parent As DesktopWindow = Nil

ShowModal

parent As DesktopWindow = Nil

ShowPopover

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

Enumerations

DesktopWindow.DisplaySides

DisplaySides

Specifies where the popover will display relative to the control its popping over.

Enum

Description

Bottom

Below the parent control.

Left

To the left of the parent control.

Top

Above the parent control.

Right

To the right of the parent control.

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 Integer

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 PushButton 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 PushButton, Label, etc.

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

MessageBox(Self.ControlAt(0).Name)

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

Var c As Object
For i As Integer = 0 To Self.ControlCount - 1
  c = Window.ControlAt(i)
  If c IsA DesktopTextField Then
    DesktopTextField(c).Enabled = False
  End If
Next

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)

Displays the window as a popover next to the parentControl based upon the parameters passed.

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.

Note

Behind the scenes, a popover is a window. Therefore once the user clicks away from it, the popover is closed by the OS and thus window used is Nil.

Important

On Linux, popovers require GTK 3.22 or later.

Event descriptions


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

Contextual menu example

The following example shows how to present and handle a contextual menu in a window using the ConstructContextualMenu and ContextualMenuItemSelected event handlers.

The following code in a ConstructContextualMenu event builds a simple contextual menu. The parameter base (a DesktopMenuItem) is passed in as a parameter and you add your contextual menu to it:

base.AddMenu(New DesktopMenuItem("Import"))
base.AddMenu(New DesktopMenuItem("Export"))
Return True  ' display the contextual menu

The following Select statement in the ContextualMenuAction event handler inspects the selected menu item, which is passed in as the selectedItem (a DesktopMenuItem) parameter.

Select Case selectedItem.Text
Case "Import"
  MessageBox("You chose Import")
Case "Export"
  MessageBox("You chose export")
End Select

Return True

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.