Class

Window

Warning

This item was deprecated in version 2021r3. Please use DesktopWindow as a replacement.

Description

Any Window. A Window can be converted to a DesktopContainer by changing its Super Class to ContainerControl. However, you cannot change the default Window to a DesktopContainer.

Methods

Name

Parameters

Returns

Shared

AcceptFileDrop

FileType As String

AcceptPictureDrop

AcceptRawDataDrop

Type As String

AcceptTextDrop

BitmapForCaching

width As Integer, height As Integer

Picture

Close

Control

index As Integer

Control

Controls

Iterable

DrawInto

g As Graphics, x As Integer, y As Integer

FocusNext

FocusPrevious

Hide

Invalidate

[EraseBackground As Boolean]

Maximize

Minimize

Refresh

[EraseBackground As Boolean]

RefreshRect

X As Integer, Y As Integer, Width As Integer, Height As Integer, [EraseBackground As Boolean]

Restore

SetFocus

Show

ShowModal

ShowModalWithin

parentWindow As Window

ShowWithin

parentWindow As Window, [facing As Integer]

UpdateNow

Constants

The following class constants of the DragItem class can be used to specify the value of the Action parameter of the DragEnter, DragExit, and DragOver events.

Class Constant

Description

DragActionDefault

Default action.

DragActionCopy

Copy the dragged item.

DragActionMove

Move the dragged item.

DragActionLink

Link the dragged item.

Enumerations

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

Window.Types

Types

Specifies the type of window.

Value

Document

MovableModal

ModalDialog

Floating

PlainBox

ShadowedBox

Rounded

GlobalFloating

Sheet

ModelessDialog

Property descriptions

Window.Backdrop

Backdrop As Picture

Gets or sets the picture object that will be drawn in the Window's background.

You should not assign a new picture to the backdrop of the Window when being inside the paint event of that Window. This can lead into problems like the backdrop not being painted.

This example sets the backdrop to a jpg image that has been added to the Project. This is in the Open event.

Me.Backdrop = MyPicture

Window.BackgroundColor

BackgroundColor As Color

The background color for the object. The HasBackgroundColor property, must be set to True to have the BackgroundColor displayed.

This code sets the Window property and sets the value of the BackgroundColor property:

Me.HasBackgroundColor = True
Me.BackgroundColor = &c110034

Window.Bounds

Bounds As Rect

Use this property to Get/Set the true bounds of a Window (i.e. including frame/title decorations).

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

To get the bounds:

Var winBounds As Rect
winBounds = Self.Bounds
MessageBox("Left = " + winBounds.Left.ToString)

To set the bounds, do not modify the Bounds properly directly. This does not work because you will be modifying a temporary object. Instead set the bounds in your own Realbasic.Rect instance and assign that to bounds:

Var myBounds As New Rect
myBounds.Left = 100
myBounds.Top = 100
myBounds.Height = Self.Height
myBounds.Width = Self.Width
Self.Bounds = myBounds

Window.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
  MsgBox("The contents have changed!")
Else
  MsgBox("The ContentsChanged event has not fired.")
End If

Window.ControlCount

ControlCount As Integer

The number of controls in the Window.

This property is read-only.

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

MsgBox(Self.ControlCount.ToString)

Window.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 Window enumeration contains all potential values for this property.

Window.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 ClearRect property of the Graphics class 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.

Window.Focus

Focus As RectControl

Gets or sets the RectControl 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)

Window.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 Window to True to let the user enable the macOS full screen mode.

Window.Handle

Handle As Integer

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.

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

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

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

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

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

Window.Height

Height As Integer

The height of the content region of the Window in points.

Me.Height = 100

Window.ImplicitInstance

ImplicitInstance As Boolean

If True, an instance of the Window can be instantiated implicitly. Set ImplicitInstance in the Properties Inspector in the IDE.

For example, an implicit instance is instantiated by referring to one of its properties or by calling its Show method. That is, a statement such as:

Window2.Show

or

Window2.ShowModal

will instantiate the Window only if ImplicitInstance is True. The default is True. If False, you need to instantiate it explicitly via the New operator. That is, only a statement such as:

w = New Window2

will instantiate the Window.

If ImplicitInstance is False, statements such as:

Window2.Show

and references to any Window or control properties will produce an error.

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

Window.MaximumHeight

MaximumHeight As Integer

The maximum height (in points) to which the Window can be resized.

Window.MaximumWidth

MaximumWidth As Integer

The maximum width (in points) to which the Window can be resized.

Window.MenuBar

MenuBar As MenuBar

The menubar that is associated with the Window.

This is the MenuBar 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, Application 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 Application 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

Window.MinimumHeight

MinimumHeight As Integer

The minimum height to which the Window can be resized.

Window.MinimumWidth

MinimumWidth As Integer

The minimum width to which the Window can be resized.

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

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

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

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

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

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

Window.Title

Title As String

The text in the Window's Title bar.

Window.Top

Top As Integer

The distance (in pixels) between the top edge of the screen and the top edge of the content region of the Window.

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

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

Window.TrueWindow

TrueWindow As Window

Returns a reference to the actual enclosing Window.

This property is read-only.

TrueWindow walks up the Window hierarchy and finds the actual enclosing Window regardless of how deeply nested the RectControl or DesktopContainer hierarchy is.

RectControl also has a TrueWindow property.

Window.Type

Type As Integer

The Window type. Set the desired Type in the Inspector.

This property is read-only.

Use the Window enumeration to determine the value of this property.

The various frame types are covered in the Desktop Windows topic.

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

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

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

Window.AcceptPictureDrop

AcceptPictureDrop

Permits pictures to be dropped on the Window.

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

Window.AcceptTextDrop

AcceptTextDrop

Permits text to be dropped on the Window.

Window.BitmapForCaching

BitmapForCaching(width As Integer, height As Integer) As Picture

Returns a bitmap that is configured correctly for using as a cache for content to be drawn to this Window. This image supports Alpha Channels (not masked images).

Use this method instead of "New Picture" in order to get a Picture image that is suitable for HiDPI displays.

Raises exceptions in the following cases:

  • InvalidArgumentException if width, height, or scale are less than or equal to zero

  • OutOfMemoryException if the picture could not be allocated

If you need to support images with masks AND images that use alpha channels code like the following will let you handle both cases for HiDPI displays

Public Function BitmapForCaching(Extends g As Graphics, width As Integer = -1, height As Integer = -1, withMask As Boolean = False) As Picture
  #Pragma BackgroundTasks False
  If width = -1 Then width = g.Width
  If height = -1 Then height = g.Height

  If width <= 0 Then width = 1
  If height <= 0 Then height = 1

  #If TargetLinux Then
    If withMask Then
      Return New Picture(width, height, 32)
    Else
      Return New Picture(width, height)
    End If
  #Else
    Var pic As Picture
    If withMask Then
      pic = New Picture(width * g.ScaleX, height * g.ScaleY, 32)
    Else
      pic = New Picture(width * g.ScaleX, height * g.ScaleY)
    End If
    ' Set the resolutions
    pic.HorizontalResolution = 72 * g.ScaleX
    pic.VerticalResolution = 72 * g.ScaleY
    pic.Graphics.ClearRect(0, 0, pic.Width, pic.Height)

    ' Make sure the two graphics object scales match the reference graphics object
    Var gScaleX As Double = g.ScaleX
    Var gScaleY As Double = g.ScaleY
    pic.Graphics.ScaleX = gScaleX
    pic.Graphics.ScaleY = gScaleY
    If withMask Then
      pic.Mask.Graphics.ScaleX = gScaleX
      pic.Mask.Graphics.ScaleY = gScaleY
    End If
    Return pic
  #Endif
End Function

Window.Close

Close

Closes the Window. Once closed, a Window cannot be refreshed or redrawn. Calling Close triggers the CancelClose event.

Window.Control

Control(index As Integer) As Control

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

All controls on the Window are returned as a the Control 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 Action event of a PushButton and displays the name of the first control in Window:

MessageBox(Self.Control(0).Name)

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

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

Window.Controls

Controls As Iterable

Used to iterate through the controls on a Window.

All controls on the Window are returned as a the Control base type. You can use the IsA operator to check the specific type to see if the control is a PushButton, Label, etc.

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

For Each c As Control In Self.Controls
  If c IsA TextField Then
    TextField(c).Enabled = False
  End If
Next

Window.DrawInto

DrawInto(g As Graphics, x As Integer, y As Integer)

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

Window.FocusNext

FocusNext

Changes the focus to the next control in the Tab Order.

Window.FocusPrevious

FocusPrevious

Changes the focus to the previous control in the Tab Order.

Window.Hide

Hide

Makes the Window invisible.

Window.Invalidate

Invalidate([EraseBackground As Boolean])

Similar to RefreshRect, but causes the specified region of the Window to be marked dirty and to be redrawn when the Window contents need to be redrawn. The region to be redrawn is specified by the X, Y, Width, and Height parameters.

The following example refreshes the Window. EraseBackground defaults to True.

Self.Invalidate

Window.Maximize

Maximize

Maximizes the Window if it is not already maximized and calls the Maximize event handler. If the Window was already maximized when you call this method, then it is restored to its prior state and calls the Restore event handler.

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

Window.Minimize

Minimize

Minimizes the Window and calls the Minimize event handler.

Window.Refresh

Refresh([EraseBackground As Boolean])

Repaints the entire contents of the Window. If the optional parameter EraseBackground is True, the background will be erased prior to redrawing the Window. The default is True.

Window.RefreshRect

RefreshRect(X As Integer, Y As Integer, Width As Integer, Height As Integer, [EraseBackground As Boolean])

Repaints only the region of the Window specified by the parameters X, Y, Width, and Height. X and Y are the coordinates of the top, left corner of the rectangle and Width and Height its width and height. All are in pixels. If the optional parameter EraseBackground is True, the background will be erased prior to redrawing the area. The default is True.

Window.Restore

Restore

Restores a minimized or maximized Window to its previous size.

Window.SetFocus

SetFocus

Removes the focus from the control that currently has the focus, leaving no control with the focus.

On Windows, the app will continue to receive KeyDown events which it can accept by returning True from the KeyDown event.

On macOS, this method does not do anything. Use the ClearFocus method to remove focus from the control on the Window that has the focus.

On Linux, this method works the same as ClearFocus.

Use the SetFocus method of the RectControl class to set the focus to a particular control in the Window.

Window.Show

Show

Forces the Window to immediately become visible rather than wait until the application is idle. If ImplicitInstance is False, then you need to instantiate an instance using New before calling Show.

Calling Show immediately brings the Window to the front.

Window.ShowModal

ShowModal

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.

For Drawer or Sheet windows, you should use ShowModalWithin to specify the parent Window to which the Drawer or Sheet is attached. Using just ShowModal without specifying the parent may result in Drawers and Sheets being attached to a Window you do not expect.

Window.ShowModalWithin

ShowModalWithin(parentWindow As Window)

Displays the Window within the parentWindow in a modal state.

ShowModalWithin is designed to display Sheet windows within a specific parent (macOS only). If it is used to display a Document Window, it displays it as a non-modal dialog.

Window.ShowWithin

ShowWithin(parentWindow As Window, [facing As Integer])

Displays the Window within the parentWindow. If the Window is a Document Window, it is displayed in a modeless state and is equivalent to Show.

Used to display Sheet and Drawer windows on macOS within a specific parent. For sheet windows, it is displayed in a modal state. For a Drawer Window they are displayed in a modeless state. The optional facing parameter pertains to Drawer windows and indicates which side the drawer pops out of the side shown in the table below:

Value

Description

Default (determined by the system -- usually left),

0

Top

1

Bottom

2

Right

3

Left (same ordering as tab panels).

If you omit facing, the default value will be used.

Window.UpdateNow

UpdateNow

Flushes the back buffer on macOS windows. UpdateNow does not function unless ImplicitInstance is True. If ImplicitInstance is False, it will produce a compiler error.

Because macOS is double-buffered, drawing is accumulated before being shown on screen. You may want to flush the buffer manually after updating a progress bar, drawing the frame of an animation on a canvas, or other things of a similar nature. UpdateNow has no effect on Windows and Linux.

Event descriptions

Window.Activate

Activate

The Window is being activated.

In an app with multiple windows, the Activate event fires each time the Window becomes the frontmost. This includes when it opens. When the Window first opens, the Open event fires prior to the Activate event. Subsequent activations fire the Activate event but not the Open event.

Window.CancelClose

CancelClose(appQuitting As Boolean)

The Window is about to be closed by the user clicking the close button, by calling the Quit or Window methods.

When the app is quitting, CancelClose and Close are called as a pair for each open Window. Close will be called after CancelClose 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.

Window.Close

Close

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 Window event instead which is called before Window.

Window.ConstructContextualMenu

ConstructContextualMenu(Base As MenuItem, 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 RectControl class.

The following ConstructContextualMenu event handler builds a menu with three menu items plus a submenu with three additional menu items.

' Add some items
base.Add(New MenuItem("Test 1" )
base.Add(New MenuItem("Test 2"))
base.Add(New MenuItem("Test 3"))

' Add a Separator
base.Add(New MenuItem(MenuItem.TextSeparator))

' Add a sub menu
Var submenu As New MenuItem("SubMenu")
submenu.Add(New MenuItem("SubMenu Test 1"))
submenu.Add(New MenuItem("SubMenu Test 2"))
submenu.Add(New MenuItem("SubMenu Test 3"))
base.Add(submenu)

' Add a Separator
base.Add(New MenuItem(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 Mac OS you cannot add the FileQuit item on OS X
#Else
  base.Add(FileQuit)
#Endif

Return True

Window.ContentsChanged

ContentsChanged

Fires when the value of the Changed property has changed. Changing the value of the Changed property triggers this event.

Window.ContextualMenuAction

ContextualMenuAction(HitItem As MenuItem) As Boolean

Fires when a contextual menuitem HitItem was selected but the Action event and the MenuHandler for the menuitem 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 Action 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 MenuItem is passed in as a parameter.

base.Add(New MenuItem("Import"))
base.Add(New MenuItem("Export"))
Return True  ' display the contextual menu

The following Select Case statement in the ContextualMenuAction event handler inspects the selected menu item, which is passed in as the HitItem as MenuItem parameter.

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

Return True

Window.Deactivate

Deactivate

The Window is being deactivated. For example, a Window belonging to another app is being activated.

Window.DragEnter

DragEnter(Obj As DragItem, Action As Integer) As Boolean

Fired when the DragItem enters the Window. Return True from this event to prevent the drop from occurring.

The Action parameter specifies the drag action. It can take the following class constants of the DragItem class:

Class Constant

DragActionDefault

DragActionCopy

DragActionMove

DragActionLink

For example, the expression “DragItem.DragActionDefault” specifies the default drag action.

Window.DragExit

DragExit(Obj As DragItem, Action As Integer)

Fires when the DragItem exits the Window.

The Action parameter specifies the drag action. It can take the following class constants of the DragItem class:

Class Constant

DragActionDefault

DragActionCopy

DragActionMove

DragActionLink

Window.DragOver

DragOver(x As Integer, y As Integer, Obj As DragItem, Action As Integer) As Boolean

Fires when the DragItem is over the Window.

The coordinates x and y are relative to the Window. Returns a Boolean. Return True from this event to prevent the drop from occurring.

The Action parameter specifies the drag action. It can take the following class constants of the DragItem class:

Class Constant

DragActionDefault

DragActionCopy

DragActionMove

DragActionLink

Window.DropObject

DropObject(Obj As DragItem, Action As Integer)

The item represented by Obj has been dropped on the Window.

The Action parameter specifies the drag action. It can take the following class constants of the DragItem class:

Class Constant

DragActionDefault

DragActionCopy

DragActionMove

DragActionLink

Window.EnableMenuItems

EnableMenuItems

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.

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

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

Window.Maximize

Maximize

The window has been 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:

Window.Minimize

Minimize

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 Window method and it is possible that it is the front-most (0 position) window.

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

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

Window.MouseEnter

MouseEnter

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

Window.MouseExit

MouseExit

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

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

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

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

Window.Moved

Moved

The Window has been moved by the user or by code that changes the Window's Left or Top properties.

Window.Open

Open

The Window is about to open but hasn't been displayed yet. Controls also receive Open events. A Window receives its Open event after all of the controls have received their Open events.

You should use the Open event instead of the Constructor for initialization.

After the Window opens and becomes the active Window, the Activate event is called.

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

Window.Resized

Resized

The Window has been resized by the user or by code that changes the Window's Width or Height properties.

Window.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 Canvas control should redraw in its Paint event.

Window.Restore

Restore

The window is being 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:

Window.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 Open events are called. If you are initializing Window properties, you should do so using the Open event handler rather than the Constructor. Using the Constructor could result in property changes you make being overwritten by the built-in Window initializations.

Understanding sheet windows

A "Sheet Window" is the official name for drop-down dialog boxes that were introduced with macOS, where they often used in place of modal dialog boxes. Sheet windows behave as such only on OS X. On other platforms, they behave as ordinary movable modal dialog boxes.

A Sheet Window behaves like a Modal dialog Window, except that the animation makes it appear to drop down from the parent Window's Title bar. It can't be moved from that position and it puts the user interface in a modal state. The user must respond to the choices presented in the Sheet Window.

A Sheet Window can be displayed by calling the ShowModalWithin method. If SheetWindow is defined as a Sheet Window and MainWindow is a Document Window, then the statement:

SheetWindow.ShowModalWithin(Self)

will show the Sheet Window using the calling Window (in this case, MainWindow) as the Parent Window.

Note that the above works because SheetWindow has its ImplicitInstance property set to True.

You can also use your own instance like this:

Var sw As New SheetWindow
sw.ShowModalWithin(Self)

Custom cursors

The MouseCursor property controls the appearance of the pointer when it is over the Window, provided the MouseCursor property of the Application 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.

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"

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

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

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

base.Add(New MenuItem("Import"))
base.Add(New MenuItem("Export"))
Return True  ' display the contextual menu

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

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

Return True

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.

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 TextField 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"

Compatibility

All project types on all supported operating systems.

See also

Object parent class; Window function; MessageDialog class.