f1e13a7921
Closes PR 11599 This is an API change relative to gr1, but it seems sensible, and it makes enter and leave events more reliable and easier to implement.
122 lines
4.6 KiB
Racket
122 lines
4.6 KiB
Racket
#lang scribble/doc
|
|
@(require "common.ss")
|
|
|
|
@defclass/title[dialog% object% (top-level-window<%>)]{
|
|
|
|
A dialog is a top-level window that is @defterm{modal}: while the
|
|
dialog is shown, key and mouse press/release events are disabled for
|
|
all other top-level windows in the dialog's eventspace.
|
|
|
|
@defconstructor[([label label-string?]
|
|
[parent (or/c (is-a?/c frame%) (is-a?/c dialog%) false/c) #f]
|
|
[width (or/c (integer-in 0 10000) false/c) #f]
|
|
[height (or/c (integer-in 0 10000) false/c) #f]
|
|
[x (or/c (integer-in 0 10000) false/c) #f]
|
|
[y (or/c (integer-in 0 10000) false/c) #f]
|
|
[style (listof (one-of/c 'no-caption 'resize-border
|
|
'no-sheet 'close-button))
|
|
null]
|
|
[enabled any/c #t]
|
|
[border (integer-in 0 1000) 0]
|
|
[spacing (integer-in 0 1000) 0]
|
|
[alignment (list/c (one-of/c 'left 'center 'right)
|
|
(one-of/c 'top 'center 'bottom))
|
|
'(center top)]
|
|
[min-width (integer-in 0 10000) _graphical-minimum-width]
|
|
[min-height (integer-in 0 10000) _graphical-minimum-height]
|
|
[stretchable-width any/c #t]
|
|
[stretchable-height any/c #t])]{
|
|
|
|
The @scheme[label] string is used as the dialog's title in its
|
|
title bar. If the dialog's label is changed (see
|
|
@method[window<%> set-label]), the title bar is updated.
|
|
|
|
The @scheme[parent] argument can be @scheme[#f] or an existing
|
|
frame. Under Windows, if @scheme[parent] is an existing frame, the
|
|
new dialog is always on top of its parent. Under Windows and X, a
|
|
dialog is iconized when its parent is iconized.
|
|
|
|
If @scheme[parent] is @scheme[#f], then the eventspace for the new
|
|
dialog is the current eventspace, as determined by
|
|
@scheme[current-eventspace]. Otherwise, @scheme[parent]'s eventspace
|
|
is the new dialog's eventspace.
|
|
|
|
If the @scheme[width] or @scheme[height] argument is not @scheme[#f],
|
|
it specifies an initial size for the dialog (in pixels) assuming that
|
|
it is larger than the minimum size, otherwise the minimum size is
|
|
used. Under Windows and Mac OS X (and with some X window managers)
|
|
dialogs are not resizeable.
|
|
|
|
If the @scheme[x] or @scheme[y] argument is not @scheme[#f], it
|
|
specifies an initial location for the dialog. Otherwise, if no
|
|
location is set before the dialog is shown, it is centered (with
|
|
respect @scheme[parent] if not @scheme[#f], the screen otherwise).
|
|
|
|
The @scheme[style] flags adjust the appearance of the dialog on some
|
|
platforms:
|
|
|
|
@itemize[
|
|
|
|
@item{@scheme['no-caption] --- omits the title bar for the dialog
|
|
(Windows)}
|
|
|
|
@item{@scheme['resize-border] --- adds a resizeable border
|
|
around the window (Windows) or grow box in the bottom right corner
|
|
(Mac OS X)}
|
|
|
|
@item{@scheme['no-sheet] --- uses a movable window for the dialog,
|
|
even if a parent window is provided (Mac OS X)}
|
|
|
|
@item{@scheme['close-button] --- include a close button in the
|
|
dialog's title bar, which would not normally be included (Mac OS X)}
|
|
|
|
]
|
|
|
|
Even if the dialog is not shown, a few notification events may be
|
|
queued for the dialog on creation. Consequently, the new dialog's
|
|
resources (e.g., memory) cannot be reclaimed until some events are
|
|
handled, or the dialog's eventspace is shut down.
|
|
|
|
@WindowKWs[@scheme[enabled]] @AreaContKWs[] @AreaKWs[]
|
|
}
|
|
|
|
@defmethod[#:mode override
|
|
(on-subwindow-char [receiver (is-a?/c window<%>)]
|
|
[event (is-a?/c key-event%)])
|
|
boolean?]{
|
|
|
|
Returns the result of
|
|
|
|
@schemeblock[
|
|
(or (send this #,(:: top-level-window<%> on-system-menu-char) event)
|
|
(send this #,(:: top-level-window<%> on-traverse-char) event))
|
|
]
|
|
|
|
}
|
|
|
|
@defmethod[#:mode override
|
|
(show [show? any/c])
|
|
void?]{
|
|
|
|
If @scheme[show?] is true, the dialog is shown and all frames (and other
|
|
dialogs) in the eventspace become disabled until the dialog is
|
|
closed. If @scheme[show?] is false, the dialog is hidden and other
|
|
frames and dialogs are re-enabled (unless a different, pre-existing
|
|
dialog is still shown).
|
|
|
|
If @scheme[show?] is true, the method does not immediately return. Instead,
|
|
it loops with @scheme[yield] until the dialog is found to be hidden
|
|
between calls to @scheme[yield]. An internal semaphore is used with
|
|
@scheme[yield] to avoid a busy-wait, and to ensure that the @scheme[show]
|
|
method returns as soon as possible after the dialog is hidden.
|
|
|
|
}
|
|
|
|
@defmethod[(show-without-yield)
|
|
void?]{
|
|
|
|
Like @racket[(send @#,this-obj[] @#,method[dialog% show] #t)], but returns
|
|
immediately instead of @racket[yield]ing.}
|
|
|
|
}
|