DesktopWindow

Class (inherits from Object)

New in 2021r3

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.

Enumerations

Locations

Types

Notes

Window constructors are called after the window and its controls are created, but before the Open 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.

Examples

This example sets the background color of the window to grey, provided the HasBackgroundColor property is set to True.

BackgroundColor = 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"

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.Add(New DesktopMenuItem("Import"))
base.Add(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.Value = "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.