325 lines
10 KiB
Racket
325 lines
10 KiB
Racket
#lang scribble/doc
|
|
@(require "common.ss")
|
|
|
|
@definterface/title[top-level-window<%> (area-container-window<%>)]{
|
|
|
|
A top-level window is either a @scheme[frame%] or @scheme[dialog%]
|
|
object.
|
|
|
|
@defmethod[#:mode pubment
|
|
(can-close?)
|
|
boolean?]{
|
|
|
|
Called just before the window might be closed (e.g., by the window
|
|
manager). If @scheme[#f] is returned, the window is not\/ closed,
|
|
otherwise @method[top-level-window<%> on-close] is called and the
|
|
window is closed (i.e., the window is hidden, like calling
|
|
@method[window<%> show] with @scheme[#f]).
|
|
|
|
This method is @italic{not} called by @method[window<%> show].
|
|
}
|
|
|
|
@defmethod[(can-exit?)
|
|
boolean?]{
|
|
@methspec{
|
|
|
|
Called before @method[top-level-window<%> on-exit] to check whether an
|
|
exit is allowed. See @method[top-level-window<%> on-exit] for more
|
|
information.
|
|
|
|
}
|
|
@methimpl{
|
|
|
|
Calls @method[top-level-window<%> can-close?] and returns the result.
|
|
|
|
}}
|
|
|
|
@defmethod[(center [direction (one-of/c 'horizontal 'vertical 'both) 'both])
|
|
void?]{
|
|
|
|
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 @scheme[direction] is @scheme['horizontal], the window is centered
|
|
horizontally. If @scheme[direction] is @scheme['vertical], the
|
|
window is centered vertically. If @scheme[direction] is
|
|
@scheme['both], the window is centered in both directions.
|
|
|
|
}
|
|
|
|
@defmethod[(get-edit-target-object)
|
|
(or/c (or/c (is-a?/c window<%>) (is-a?/c editor<%>)) false/c)]{
|
|
|
|
@index['("keyboard focus" "last active")]{Like}
|
|
@method[top-level-window<%> 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 @method[top-level-window<%> get-focus-object].
|
|
|
|
}
|
|
|
|
@defmethod[(get-edit-target-window)
|
|
(or/c (is-a?/c window<%>) false/c)]{
|
|
|
|
@index['("keyboard focus" "last active")]{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,
|
|
@scheme[#f] is returned.
|
|
|
|
See also @method[top-level-window<%> get-focus-window] and
|
|
@method[top-level-window<%> get-edit-target-object].
|
|
|
|
}
|
|
|
|
@defmethod[(get-eventspace)
|
|
eventspace]{
|
|
Returns the window's eventspace.
|
|
|
|
}
|
|
|
|
@defmethod[(get-focus-object)
|
|
(or/c (or/c (is-a?/c window<%>) (is-a?/c editor<%>)) false/c)]{
|
|
|
|
@index["keyboard focus"]{Like} @method[top-level-window<%>
|
|
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 @method[top-level-window<%> get-edit-target-object].
|
|
|
|
}
|
|
|
|
@defmethod[(get-focus-window)
|
|
(or/c (is-a?/c window<%>) false/c)]{
|
|
|
|
@index["keyboard focus"]{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, @scheme[#f] is
|
|
returned.
|
|
|
|
See also @method[top-level-window<%> get-edit-target-window] and
|
|
@method[top-level-window<%> get-focus-object].
|
|
|
|
}
|
|
|
|
|
|
@defmethod[(move [x (integer-in -10000 10000)]
|
|
[y (integer-in -10000 10000)])
|
|
void?]{
|
|
|
|
Moves the window to the given position on the screen.
|
|
|
|
@MonitorMethod[@elem{A window's position} @elem{the user dragging the window} @elem{@method[window<%> on-move]} @elem{position}]
|
|
|
|
}
|
|
|
|
|
|
@defmethod[(on-activate [active? any/c])
|
|
void?]{
|
|
|
|
Called when a window is @defterm{activated} or
|
|
@defterm{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. Under Mac OS X, 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 @scheme[#t] when the window is activated,
|
|
@scheme[#f] when it is deactivated.
|
|
|
|
}
|
|
|
|
@defmethod[#:mode pubment
|
|
(on-close)
|
|
void?]{
|
|
|
|
Called just before the window is closed (e.g., by the window manager).
|
|
This method is @italic{not} called by @method[window<%> show].
|
|
|
|
See also
|
|
@method[top-level-window<%> can-close?].
|
|
|
|
}
|
|
|
|
@defmethod[(on-exit)
|
|
void?]{
|
|
|
|
@methspec{
|
|
|
|
Called by the default application quit handler (as determined by the
|
|
@scheme[application-quit-handler] parameter) when the operating
|
|
system requests that the application shut down (e.g., when the
|
|
@onscreen{Quit} menu item is selected in the main application menu
|
|
under Mac OS X). 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 @method[top-level-window<%> can-exit?] method first
|
|
returns true.
|
|
|
|
}
|
|
@methimpl{
|
|
|
|
Calls
|
|
@method[top-level-window<%> on-close] and then
|
|
@method[top-level-window<%> show] to hide the window.
|
|
|
|
|
|
|
|
}}
|
|
|
|
@defmethod[(on-message [message any/c])
|
|
any/c]{
|
|
@methspec{
|
|
|
|
@index["drag-and-drop"]{A} generic message method, usually called by
|
|
@scheme[send-message-to-window].
|
|
|
|
If the method is invoked by @scheme[send-message-to-window], then it
|
|
is invoked in the thread where @scheme[send-message-to-window] was
|
|
called (which is possibly @italic{not} the handler thread of the
|
|
window's eventspace).
|
|
|
|
}
|
|
@methimpl{
|
|
|
|
Returns @|void-const|.
|
|
|
|
}}
|
|
|
|
|
|
@defmethod[(on-traverse-char [event (is-a?/c key-event%)])
|
|
boolean?]{
|
|
|
|
@methspec{
|
|
|
|
@index['("keyboard focus" "navigation")]{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, @scheme[#t] is
|
|
returned, otherwise @scheme[#f] is returned.
|
|
|
|
}
|
|
@methimpl{
|
|
|
|
The following rules determine, in order, whether and how @scheme[event]
|
|
is handled:
|
|
|
|
@itemize{
|
|
|
|
@item{
|
|
If the window that currently owns the focus specifically handles the
|
|
event, then @scheme[#f] is returned. The following describes window
|
|
types and the keyboard events they specifically handle:
|
|
@itemize{
|
|
|
|
@item{@scheme[editor-canvas%] --- tab-exit is disabled (see
|
|
@method[editor-canvas% allow-tab-exit]): all keyboard events, except alphanumeric key events when the Meta
|
|
(X) or Alt (Windows) key is pressed; when tab-exit is enabled:
|
|
all keyboard events except Tab, Enter, Escape, and alphanumeric
|
|
Meta/Alt events.}
|
|
|
|
@item{@scheme[canvas%] --- when tab-focus is disabled (see
|
|
@method[canvas% accept-tab-focus]): all keyboard events, except alphanumeric key events when the Meta
|
|
(X) or Alt (Windows) key is pressed; when tab-focus is enabled:
|
|
no key events}
|
|
|
|
@item{@scheme[text-field%], @scheme['single] style --- arrow key
|
|
events and alphanumeric key events when the Meta (X) or Alt
|
|
(Windows) key is not pressed (and all alphanumeric events under
|
|
Mac OS X)}
|
|
|
|
@item{@scheme[text-field%], @scheme['multiple] style --- all
|
|
keyboard events, except alphanumeric key events when the Meta (X) or
|
|
Alt (Windows) key is pressed}
|
|
|
|
@item{@scheme[choice%] --- arrow key events and alphanumeric key
|
|
events when the Meta (X) or Alt (Windows) key is not pressed}
|
|
|
|
@item{@scheme[list-box%] --- arrow key events and alphanumeric key
|
|
events when the Meta (X) or Alt (Windows) key is not pressed}
|
|
|
|
}}
|
|
|
|
@item{
|
|
If @scheme[event] is a Tab or arrow key event, the keyboard focus is
|
|
moved within the window and @scheme[#t] is returned. Across platforms,
|
|
the types of windows that accept the keyboard focus via navigation
|
|
may vary, but @scheme[text-field%] windows always accept the focus,
|
|
and @scheme[message%], @scheme[gauge%], and @scheme[panel%]
|
|
windows never accept the focus.}
|
|
|
|
@item{
|
|
If @scheme[event] is a Space key event and the window that currently
|
|
owns the focus is a @scheme[button%], @scheme[check-box%], or
|
|
@scheme[radio-box%] object, the event is handled in the same way as
|
|
a click on the control and @scheme[#t] is returned.}
|
|
|
|
@item{
|
|
If @scheme[event] is an Enter key event and the current top-level window
|
|
contains a border button, the button's callback is invoked and
|
|
@scheme[#t] is returned. (The @scheme['border] style for a
|
|
@scheme[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, @scheme[#t] is returned if the window with the current
|
|
focus is not a text field or editor canvas.}
|
|
|
|
@item{
|
|
In a dialog, if @scheme[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
|
|
@method[top-level-window<%> can-close?] and
|
|
@method[top-level-window<%> on-close] methods are called, and the dialog is hidden) and @scheme[#t] is
|
|
returned.}
|
|
|
|
@item{
|
|
If @scheme[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
|
|
@method[window<%> get-label] for more information), then the
|
|
keyboard focus is moved to the matching control. Furthermore, if the
|
|
matching control is a @scheme[button%], @scheme[check-box%], or
|
|
@scheme[radio-box%] button, the keyboard event is handled in the
|
|
same way as a click on the control.}
|
|
|
|
@item{
|
|
Otherwise, @scheme[#f] is returned.}
|
|
|
|
}
|
|
}}
|
|
|
|
@defmethod[(on-system-menu-char [event (is-a?/c key-event%)])
|
|
boolean?]{
|
|
|
|
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, @scheme[#t] is returned, otherwise @scheme[#f] is
|
|
returned.
|
|
|
|
}
|
|
|
|
@defmethod[(resize [width (integer-in 0 10000)]
|
|
[height (integer-in 0 10000)])
|
|
void?]{
|
|
|
|
Sets the size of the window (in pixels), but only if the given size is
|
|
larger than the window's minimum size.
|
|
|
|
@MonitorMethod[@elem{A window's size} @elem{the user} @elem{@method[window<%> on-size]} @elem{size}]
|
|
|
|
}
|
|
|
|
@defmethod[(show [show any/c])
|
|
void?]{
|
|
|
|
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 @xmethod[window<%> show].
|
|
|
|
}}
|
|
|