3.50 top-level-window<%>

► |  | The Racket Graphical Interface Toolkit

1 | Windowing
2 | Widget Gallery
3 | Windowing Classes
4 | Windowing Functions
5 | Editors
6 | Snip and Style Classes
7 | Editor Classes
8 | Editor Functions
9 | WXME Decoding
10 | Preferences
11 | Dynamic Loading
12 | Startup Actions
13 | Init Libraries
14 | Platform Dependencies
| Index

▼ | 3 | Windowing Classes

3.1 | area<%>
3.2 | area-container<%>
3.3 | area-container-window<%>
3.4 | button%
3.5 | canvas<%>
3.6 | canvas%
3.7 | check-box%
3.8 | checkable-menu-item%
3.9 | choice%
3.10 | clipboard-client%
3.11 | clipboard<%>
3.12 | combo-field%
3.13 | control<%>
3.14 | column-control-event%
3.15 | control-event%
3.16 | cursor%
3.17 | dialog%
3.18 | event%
3.19 | frame%
3.20 | gauge%
3.21 | group-box-panel%
3.22 | grow-box-spacer-pane%
3.23 | horizontal-pane%
3.24 | horizontal-panel%
3.25 | key-event%
3.26 | labelled-menu-item<%>
3.27 | list-box%
3.28 | list-control<%>
3.29 | menu%
3.30 | menu-bar%
3.31 | menu-item<%>
3.32 | menu-item%
3.33 | menu-item-container<%>
3.34 | message%
3.35 | mouse-event%
3.36 | pane%
3.37 | panel%
3.38 | popup-menu%
3.39 | printer-dc%
3.40 | radio-box%
3.41 | selectable-menu-item<%>
3.42 | separator-menu-item%
3.43 | scroll-event%
3.44 | slider%
3.45 | subarea<%>
3.46 | subwindow<%>
3.47 | tab-panel%
3.48 | text-field%
3.49 | timer%
3.50 | top-level-window<%>
3.51 | vertical-pane%
3.52 | vertical-panel%
3.53 | window<%>

On this page:

can-close?
can-exit?
center
get-edit-target-object
get-edit-target-window
get-eventspace
get-focus-object
get-focus-window
move
on-activate
on-close
on-exit
on-message
display-changed
on-traverse-char
on-system-menu-char
resize
set-icon
show

Inherited methods:
from window<%>
accept-drop-files
client->screen
enable
focus
get-client-handle
get-client-size
get-cursor
get-handle
get-height
get-label
get-plain-label
get-size
get-width
get-x
get-y
has-focus?
is-enabled?
is-shown?
on-drop-file
on-focus
on-move
on-size
on-subwindow-char
on-subwindow-event
on-subwindow-focus
on-superwindow-activate
on-superwindow-enable
on-superwindow-show
popup-menu
refresh
screen->client
set-cursor
set-label
warp-pointer
wheel-event-mode
from area<%>
get-graphical-min-size
get-parent
get-top-level-window
min-height
min-width
stretchable-height
stretchable-width
from area-container<%>
add-child
after-new-child
begin-container-sequence
border
change-children
container-flow-modified
container-size
delete-child
end-container-sequence
get-alignment
get-children
place-children
reflow-container
set-alignment
spacing

top contents ← prev up next →

interface top-level-window<%> : interface?
implements: | area-container-window<%>

A top-level window is either a frame% or dialog% object.

> method (send a-top-level-window can-close?) → boolean?

Refine this method with augment.
Called just before the window might be closed (e.g., by the window manager). If #f is returned, the window is not closed, otherwise on-close is called and the window is closed (i.e., the window is hidden, like calling show with #f).

This method is not called by show.

> method (send a-top-level-window can-exit?) → boolean?

Specification: Called before on-exit to check whether an exit is allowed. See on-exit for more information.

Default implementation: Calls can-close? and returns the result.

> method (send a-top-level-window center [direction]) → void?
> direction : (or/c 'horizontal 'vertical 'both) = 'both

Centers the window on the screen if it has no parent. If it has a parent, the window is centered with respect to its parent’s location.

If direction is 'horizontal, the window is centered horizontally. If direction is 'vertical, the window is centered vertically. If direction is 'both, the window is centered in both directions.

> method (send a-top-level-window get-edit-target-object)
> → (or/c (or/c (is-a?/c window<%>) (is-a?/c editor<%>)) #f)

Like get-edit-target-window, but if an editor canvas had the focus and it also displays an editor, the editor is returned instead of the canvas. Further, if the editor’s focus is delegated to an embedded editor, the embedded editor is returned.

See also get-focus-object.

> method (send a-top-level-window get-edit-target-window)
> → (or/c (is-a?/c window<%>) #f)

Returns the window that most recently had the keyboard focus, either the top-level window or one of its currently-shown children. If neither the window nor any of its currently-shown children has even owned the keyboard focus, #f is returned.

See also get-focus-window and get-edit-target-object.

> method (send a-top-level-window get-eventspace) → eventspace?

Returns the window’s eventspace.

> method (send a-top-level-window get-focus-object)
> → (or/c (or/c (is-a?/c window<%>) (is-a?/c editor<%>)) #f)

Like get-focus-window, but if an editor canvas has the focus and it also displays an editor, the editor is returned instead of the canvas. Further, if the editor’s focus is delegated to an embedded editor, the embedded editor is returned.

See also get-edit-target-object.

> method (send a-top-level-window get-focus-window)
> → (or/c (is-a?/c window<%>) #f)

Returns the window that has the keyboard focus, either the top-level window or one of its children. If neither the window nor any of its children has the focus, #f is returned.

See also get-edit-target-window and get-focus-object.

> method (send a-top-level-window move x y) → void?
> x : position-integer?
> y : position-integer?

Moves the window to the given position on the screen.

A window’s position can be changed by the user dragging the window, and such changes do not go through this method; use on-move to monitor position changes.

> method (send a-top-level-window on-activate active?) → void?
> active? : any/c

Called when a window is activated or deactivated. A top-level window is activated when the keyboard focus moves from outside the window to the window or one of its children. It is deactivated when the focus moves back out of the window. On Mac OS, a child of a floating frames can have the focus instead of a child of the active non-floating frame; in other words, floating frames act as an extension of the active non-frame for keyboard focus.

The method’s argument is #t when the window is activated, #f when it is deactivated.

> method (send a-top-level-window on-close) → void?

Refine this method with augment.
Called just before the window is closed (e.g., by the window manager). This method is not called by show.

See also can-close?.

> method (send a-top-level-window on-exit) → void?

Specification: Called by the default application quit handler (as determined by the application-quit-handler parameter) when the operating system requests that the application shut down (e.g., when the Quit menu item is selected in the main application menu on Mac OS). In that case, this method is called for the most recently active top-level window in the initial eventspace, but only if the window’s can-exit? method first returns true.

Default implementation: Calls on-close and then show to hide the window.

> method (send a-top-level-window on-message message) → any/c
> message : any/c

Specification: A generic message method, usually called by send-message-to-window.

If the method is invoked by send-message-to-window, then it is invoked in the thread where send-message-to-window was called (which is possibly not the handler thread of the window’s eventspace).

Default implementation: Returns #<void>.

> method (send a-top-level-window display-changed) → any/c

Specification: Called when the displays configuration changes.

To determine the new monitor configuration, use get-display-count, get-display-size, get-display-left-top-inset, and get-display-backing-scale.

Note that this method may be invoked multiple times for a single logical change to the monitors.

Default implementation: Returns #<void>.

> method (send a-top-level-window on-traverse-char event) → boolean?
> event : (is-a?/c key-event%)

Specification: Attempts to handle the given keyboard event as a navigation event, such as a Tab key event that moves the keyboard focus. If the event is handled, #t is returned, otherwise #f is returned.

Default implementation: The following rules determine, in order, whether and how event is handled:

- If the window that currently owns the focus specifically handles the event, then #f is returned. The following describes window types and the keyboard events they specifically handle:

  - editor-canvas% — tab-exit is disabled (see allow-tab-exit): all keyboard events, except alphanumeric key events when the Meta (Unix) or Alt (Windows) key is pressed; when tab-exit is enabled: all keyboard events except Tab, Enter, Escape, and alphanumeric Meta/Alt events.

  - canvas% — when tab-focus is disabled (see accept-tab-focus): all keyboard events, except alphanumeric key events when the Meta (Unix) or Alt (Windows) key is pressed; when tab-focus is enabled: no key events

  - text-field%, 'single style — arrow key events and alphanumeric key events when the Meta (Unix) or Alt (Windows) key is not pressed (and all alphanumeric events on Mac OS)

  - text-field%, 'multiple style — all keyboard events, except alphanumeric key events when the Meta (Unix) or Alt (Windows) key is pressed

  - choice% — arrow key events and alphanumeric key events when the Meta (Unix) or Alt (Windows) key is not pressed

  - list-box% — arrow key events and alphanumeric key events when the Meta (Unix) or Alt (Windows) key is not pressed

- If event is a Tab or arrow key event, the keyboard focus is moved within the window and #t is returned. Across platforms, the types of windows that accept the keyboard focus via navigation may vary, but text-field% windows always accept the focus, and message%, gauge%, and panel% windows never accept the focus.

- If event is a Space key event and the window that currently owns the focus is a button%, check-box%, or radio-box% object, the event is handled in the same way as a click on the control and #t is returned.

- If event is an Enter key event and the current top-level window contains a border button, the button’s callback is invoked and #t is returned. (The 'border style for a button% object indicates to the user that pressing Enter is the same as clicking the button.) If the window does not contain a border button, #t is returned if the window with the current focus is not a text field or editor canvas.

- In a dialog, if event is an Escape key event, the event is handled the same as a click on the dialog’s close box (i.e., the dialog’s can-close? and on-close methods are called, and the dialog is hidden) and #t is returned.

- If event is an alphanumeric key event and the current top-level window contains a control with a mnemonic matching the key (which is installed via a label that contains &; see get-label for more information), then the keyboard focus is moved to the matching control. Furthermore, if the matching control is a button%, check-box%, or radio-box% button, the keyboard event is handled in the same way as a click on the control.

- Otherwise, #f is returned.

> method (send a-top-level-window on-system-menu-char event) → boolean?
> event : (is-a?/c key-event%)

Checks whether the given event pops open the system menu in the top-left corner of the window (Windows only). If the window’s system menu is opened, #t is returned, otherwise #f is returned.

> > method
> > (send a-top-level-window resize |  | width |  |  |  |
> > |  | height) |  | → |  | void?
> width : dimension-integer?
> height : dimension-integer?

Sets the size of the window (in pixels), but only if the given size is larger than the window’s minimum size.

A window’s size can be changed by the user, and such changes do not go through this method; use on-size to monitor size changes.

> > method
> > (send a-top-level-window set-icon |  | icon |  |  |  |
> > | [ | mask |  |  |  |
> > |  | which]) |  | → |  | void?
> icon : (is-a?/c bitmap%)
> mask : (is-a?/c bitmap%) = #f
> which : (or/c 'small 'large 'both) = 'both

Sets the large or small icon bitmap for the window. Future changes to the bitmap do not affect the window’s icon.

The icon is used in a platform-specific way:

- Windows — the small icon is used for the window’s icon (in the top-left) and in the task bar, and the large icon is used for the Alt-Tab task switcher.

- Mac OS — both icons are ignored.

- Unix — many window managers use the small icon in the same way as Windows, and others use the small icon when iconifying the frame; the large icon is ignored.

The bitmap for either icon can be any size, but most platforms scale the small bitmap to 16 by 16 pixels and the large bitmap to 32 by 32 pixels.

If a mask bitmap is not provided, then the entire (rectangular) bitmap is used as an icon.

If a mask bitmap is provided, the mask must be monochrome. In the mask bitmap, use black pixels to indicate the icon’s region and use white pixels outside the icon’s region. In the icon bitmap, use black pixels for the region outside the icon.

> method (send a-top-level-window show show) → void?
> show : any/c

If the window is already shown, it is moved front of other top-level windows. If the window is iconized (frames only), it is deiconized.

See also show in window<%>.
top contents ← prev up next →