Obtains a file pathname from the user via the platform-specific
standard (modal) dialog, using parent as the parent window if
it is specified, and using message as a message at the top of
the dialog if it is not #f.

The result is #f if the user cancels the dialog, the selected
pathname otherwise. The returned pathname may or may not exist,
although the style of the dialog is directed towards selecting
existing files.

If directory is not #f, it is used as the starting
directory for the file selector (otherwise the starting directory is
chosen automatically in a platform-specific manner, usually based on
the current directory and the user’s interactions in previous calls
to get-file, put-file, etc.). If
filename is not #f, it is used as the default filename
when appropriate, and it should not contain a directory path
prefix.

Under Windows, if extension is not #f, the returned path
will use the extension if the user does not supply one; the
extension string should not contain a period. The extension is
ignored on other platforms.

The style list can contain 'common, a
platform-independent version of the dialog is used instead of a
native dialog. On Mac OS X, if the style list
contains 'packages, a user is allowed to select a package
directory, which is a directory with a special suffix (e.g.,
“.app”) that the Finder normally displays like a file. If the list
contains 'enter-packages, a user is allowed to select a file
within a package directory. If the list contains both
'packages and 'enter-packages, the former is ignored.

On Windows and Unix, filters determines a set of filters from
which the user can choose in the dialog. Each element of the
filters list contains two strings: a description of the filter
as seen by the user, and a filter pattern matched against file names.
Pattern strings can be a simple “glob” pattern, or a number of glob
patterns separated by a ; character.
On Unix, a "*.*" pattern is implicitly replaced with "*".
On Mac OS X, suffix names are extracted from all globs that match a
fixed suffix (e.g., two suffixes of "foo" and "bar"
are extracted from a "*.foo;*.bar;*.baz*" pattern), and files
that have any of these suffixes in any filter are selectable; a
"*.*" glob makes all files available for selection.

The dialog-mixin is applied to path-dialog% before
creating an instance of the class for this dialog.

Obtains a file pathname from the user via the platform-specific
standard (modal) dialog, using parent as the parent window if
it is specified, and using message as a message at the top of
the dialog if it is not #f.

The result is #f if the user cancels the dialog, the selected
pathname otherwise. The returned pathname may or may not exist,
although the style of the dialog is directed towards creating a new
file.

If directory is not #f, it is used as the starting
directory for the file selector (otherwise the starting directory is
chosen automatically in a platform-specific manner, usually based on
the current directory and the user’s interactions in previous calls
to get-file, put-file, etc.). If
filename is not #f, it is used as the default filename
when appropriate, and it should not contain a directory path
prefix.

On Windows, if extension is not #f, the returned path
will get a default extension if the user does not supply one. If
extension is the empty string, then the extension is derived
from the user’s filters choice if the corresponding pattern is
of the form (string-append"*."extension); if the pattern is
"*.*", then no default extension is added. Finally, if
extension is any string other than the empty string,
extension is used as the default extension when the user’s
filters choice has the pattern "*.*". Meanwhile, the
filters argument has the same format and auxiliary role as for
get-file. In particular, if the only pattern in filters
is (string-append"*."extension), then the result pathname is guaranteed
to have an extension mapping extension.

On Mac OS X 10.5 and later, if extension is not
#f or "", the returned path will get a default extension if the
user does not supply one. If filters contains as
"*.*" pattern, then the user can supply any extension that
is recognized by the system; otherwise, the extension on the returned
path will be either extension or other-extension
for any (string-append"*."other-extension) pattern in
filters. In particular, if the only pattern in
filters is empty or contains only (string-append"*."extension), then the result pathname is guaranteed to have an
extension mapping extension.

On Mac OS X versions before 10.5, the returned path will get a
default extension only if extension is not #f,
extension is not "", and
filters contains only (string-append"*."extension).

On Unix, extension is ignored, and filters is used
to filter the visible list of files as in get-file.

Obtains a directory pathname from the user via the platform-specific
standard (modal) dialog, using parent as the parent window if
it is specified.

If directory is not #f, it is used on some platforms as
the starting directory for the directory selector (otherwise the
starting directory is chosen automatically in a platform-specific
manner, usually based on the current directory and the user’s
interactions in previous calls to get-file,
put-file, etc.).

The style argument is treated as for
get-file, except that only 'common or 'enter-packages can be
specified. The latter
matters only on Mac OS X, where 'enter-packages
enables the user to select package directory or a directory within a
package. A package is a directory with a special suffix (e.g.,
“.app”) that the Finder normally displays like a file.

The dialog-mixin is applied to path-dialog% before
creating an instance of the class for this dialog.

Displays a message to the user in a (modal) dialog, using
parent as the parent window if it is specified. The dialog’s
title is title. The message string can be arbitrarily
long, and can contain explicit linefeeds or carriage returns for
breaking lines.

The style must include exactly one of the following:

'ok — the dialog only has an OK button
and always returns 'ok.

'ok-cancel — the message dialog has
Cancel and OK buttons. If the user clicks
Cancel, the result is 'cancel, otherwise the
result is 'ok.

'yes-no — the message dialog has Yes and
No buttons. If the user clicks Yes, the result
is 'yes, otherwise the result is 'no. Note: instead
of a Yes/No dialog, best-practice GUI design is
to use message-box/custom and give the buttons meaningful
labels, so that the user does not have to read the message text
carefully to make a selection.

In addition, style can contain 'caution to make the
dialog use a caution icon instead of the application (or generic
“info”) icon, 'stop to make the dialog use a stop icon, or
'no-icon to suppress the icon. If style contains
multiple of 'caution, 'stop, and 'no-icon,
then 'no-icon takes precedence followed by 'stop.

The class that implements the dialog provides a get-message
method that takes no arguments and returns the text of the message as
a string. (The dialog is accessible through the
get-top-level-windows function.)

The message-box function can be called in a thread other
than the handler thread of the relevant eventspace (i.e., the eventspace of
parent, or the current eventspace if parent is #f), in which case the
current thread blocks while the dialog runs on the handler thread.

The dialog-mixin argument is applied to the class that implements the dialog
before the dialog is created.

Displays a message to the user in a (modal) dialog, using
parent as the parent window if it is specified. The dialog’s
title is title. The message string can be arbitrarily
long, and can contain explicit linefeeds or carriage returns for
breaking lines.

The dialog contains up to three buttons for the user to click. The
buttons have the labels button1-label,
button2-label, and button3-label, where #f for a
label indicates that the button should be hidden.

If the user clicks the button labelled button1-label, a 1
is returned, and so on for 2 and 3. If the user closes
the dialog some other way—which is only allowed when style
does not contain 'disallow-close—then the result is the
value of close-result. For example, the user can usually close
a dialog by typing an Escape. Often, 2 is an appropriate value
for close-result, especially when Button 2 is a Cancel
button.

If style does not include 'number-order, the order of
the buttons is platform-specific, and labels should be assigned to
the buttons based on their role:

Button 1 is the normal action, and it is usually the default
button. For example, if the dialog has an OK button, it is
this one. On Windows, this button is leftmost; on Unix and Mac OS
X, it is rightmost. (See also
system-position-ok-before-cancel?.) Use this button for
dialogs that contain only one button.

Button 2 is next to Button 1, and it often plays the role of
Cancel (even when the default action is to cancel, such as
when confirming a file replacement).

Button 3 tends to be separated from the other two (on
Mac OS X, it is left-aligned in the dialog). Use this button only
for three-button dialogs.

Despite the above guidelines, any combination of visible buttons is
allowed in the dialog.

If style includes 'number-order, then the buttons are
displayed in the dialog left-to-right with equal spacing between all
buttons, though aligned within the dialog (centered or right-aligned)
in a platform-specific manner. Use 'number-order sparingly.

The style list must contain exactly one of 'default=1,
'default=2, 'default=3, and 'no-default to
determine which button (if any) is the default. The default button is
“clicked” when the user types Return. If 'default=n
is supplied but button n has no label, then it is equivalent to
'no-default.

In addition, style can contain 'caution,
'stop, or 'no-icon to adjust the icon that appears
n the dialog, the same for message-box.

The class that implements the dialog provides a get-message
method that takes no arguments and returns the text of the message as
a string. (The dialog is accessible through the
get-top-level-windows function.)

The message-box/custom function can be called in a thread
other than the handler thread of the relevant eventspace (i.e., the eventspace of
parent, or the current eventspace if parent is #f), in which case the
current thread blocks while the dialog runs on the handler thread.

The dialog-mixin argument is applied to the class that implements the dialog
before the dialog is created.

Gets a text string from the user via a modal dialog, using
parent as the parent window, if it is specified. The dialog’s
title is title. The dialog’s text field is labelled with
message and initialized to init-val (but init-val
does not determine the size of the dialog).

The result is #f if the user cancels the dialog, the
user-provided string otherwise.

If style includes 'password, the dialog’s text field
draws each character of its content using a generic symbol, instead
of the actual character.

The validate function is called each time the text field changed,
with the contents of the text field. If it returns #f, the background
of the text is colored pink. If 'disallow-invalid is included in
style, the Ok button is disabled whenever the text
background is pink.

The dialog-mixin argument is applied to the class that implements the dialog
before the dialog is created.

Gets a list box selection from the user via a modal dialog, using
parent as the parent window if it is specified. The dialog’s
title is title. The dialog’s list box is labelled with
message and initialized by selecting the items in
init-choices.

The style must contain exactly one of 'single,
'multiple, or 'extended. The styles have
the same meaning as for creating a list-box% object. (For
the single-selection style, only the last selection in
init-choices matters.)

The result is #f if the user cancels the dialog, the
list of selections otherwise.

Lets the user select a color though the platform-specific
(modal) dialog, using parent as the parent window if it is
specified. The message string is displayed as a prompt in the
dialog if possible. If init-color is provided, the dialog is
initialized to the given color.

The result is #f if the user cancels the dialog, the selected
color otherwise.

If style contains 'alpha, then the user is present with
a field for filling in the alpha field of the resulting color% object.
If it does not, then the alpha component of init-color is ignored,
and the result always has alpha of 1.0.

Lets the user select a font though the platform-specific
(modal) dialog, using parent as the parent window if it is
specified. The message string is displayed as a prompt in the
dialog if possible. If init-font is provided, the dialog is
initialized to the given font.

The style argument is provided for future extensions. Currently, style must be the empty list.

The result is #f if the user cancels the dialog, the selected
font otherwise.

Lets the user select a PostScript configuration though a (modal)
dialog, using parent as the parent window if it is
specified. The message string is displayed as a prompt in the
dialog. If init-setup is provided, the dialog is initialized to
the given configuration, otherwise the current configuration from
current-ps-setup is used.

The style argument is provided for future extensions. Currently, style must be the empty list.

The result is #f if the user cancels the dialog, , a
ps-setup% object that encapsulates the selected PostScript
configuration otherwise.

The parent argument is used as the parent window for a dialog if
it is specified. The message string might be displayed as a
prompt in the dialog. If init-setup is provided, the dialog is
initialized to the given configuration, otherwise the current
configuration from
current-ps-setup is used.

The style argument is provided for future extensions. Currently, style must be the empty list.

The result is #f if the user cancels the dialog, a
ps-setup% object that encapsulates the selected
configuration otherwise.

4.2Eventspaces

Creates and returns a new eventspace value. The new eventspace is
created as a child of the current eventspace. The eventspace is used
by making it the current eventspace with the
current-eventspace parameter.

A parameter (see Parameters) that determines the current event
dispatch handler. The event dispatch handler is called by an
eventspace’s handler thread for every queue-based event to be
processed in the eventspace. The only argument to the handler is the
eventspace in which an event should be dispatched. The event dispatch
handler gives the programmer control over the timing of event
dispatching, but not the order in which events are dispatched within
a single eventspace.

An event dispatch handler must ultimately call the primitive event
dispatch handler. If an event dispatch handler returns without
calling the primitive handler, then the primitive handler is called
directly by the eventspace handler thread.

Produces a synchronizable event (see sync) that is ready when
a GUI event (mouse or keyboard action, update event, timer, queued
callback, etc.) is ready for dispatch in e. That is, the
result event is ready when (yield) for the eventspace
e would dispatch a GUI event. The synchronization result is
the eventspace e itself.

Inspects the event queue of the current eventspace, searching for a
Shift-Ctl-C (Unix, Windows) or Cmd-. (Mac OS X) key combination. Returns
#t if such an event was found (and the event is dequeued) or
#f otherwise.

Returns the top level window in the current eventspace that is visible
and most recently had the keyboard focus (or contains the window that
had the keyboard focus), or #f if there is no visible window
in the current eventspace.

Enables or disables special Control key handling (Mac OS X). When Control
is treated as a special key, the system’s key-mapper is called
without Control for keyboard translations. For some languages,
Control key presses must be seen by the system translation, so this
mode should be turned off, but the default is on.

If on? is provided and #f, Control is passed to the system
translation as normal. This setting affects all windows and
eventspaces.

If no argument is provided, the result is #t if Control is
currently treated specially, #f otherwise.

Enables or disables special Option key handling (Mac OS X). When
Option is treated as a special key, the system’s key-mapper is called
without Option for keyboard translations. By default, Option is not
special.

If on? is provided #f, Option is passed to the
system translation as normal. This setting affects all windows and
eventspaces.

If no argument is provided, the result is #t if Option is
currently treated specially, #f otherwise.

If no argument is provided, yield dispatches an unspecified
number of events, but only if the current thread is the current
eventspace’s handler thread (otherwise, there is no effect). The
result is #t if any events may have been handled,
#f otherwise.

If v is 'wait, and yield is called
in the handler thread of an eventspace, then yield starts
processing events in that eventspace until

no top-level windows in the eventspace are visible;

no timers in the eventspace are running;

no callbacks are queued in the eventspace; and

no menu-bar% has been created for the eventspace
with 'root (i.e., creating a 'root menu bar
prevents an eventspace from ever unblocking).

When called in a non-handler thread, yield returns
immediately. In either case, the result is #t.

If v is an event in Racket’s sense (not to be confused with
a GUI event), yield blocks on v in the same way as
sync, except that it may start a sync on v
multiple times (but it will complete a sync on v at
most one time). If the current thread is the current eventspace’s
handler thread, events are dispatched until a v sync
succeeds on an event boundary. For other threads, calling
yield with a Racket event is equivalent to calling
sync. In either case, the result is the same that of
sync; however, if a wrapper procedure is associated with
v via handle-evt, it is not called in tail position
with respect to the yield.

Returns #t if the given eventspace has been shut down by its
custodian, #f otherwise. Attempting to create a new window,
timer, or explicitly queued event in a shut-down eventspace raises
the exn:fail exception.

4.3System Menus

Returns #t for Mac OS X when the current eventspace is the
initial one, since that eventspace is the target for the standard
application menus. For any other system or eventspace, the result is
#f.

This procedure is intended for use in deciding whether to include a
Quit, About, and Preferences menu
item in a frame’s menu. On Mac OS X, the application
Quit menu triggers a call to a frame’s
on-exit method, the About menu item is controlled by
application-about-handler, and the
Preferences menu item is controlled by
application-preferences-handler.

Returns #t for Mac OS X when the current eventspace is the
initial one, since that eventspace can supply a menu bar to be active
when no frame is visible. For any other system or eventspace, the
result is #f.

This procedure is intended for use in deciding whether to create a
menu-bar% instance with 'root as its parent.

When the current eventspace is the initial eventspace, this
procedure retrieves or installs a thunk that is called when the
user selects the application About menu item on Mac OS
X. The thunk is always called in the initial eventspace’s
handler thread (as a callback).

The default handler displays a generic Racket dialog.

If the current eventspace is not the initial eventspace, this
procedure returns void (when called with zero arguments)
or has no effect (when called with a handler).

When the current eventspace is the initial eventspace, this procedure
retrieves or installs a procedure that is called on Mac OS X
and Windows when the application is running and user double-clicks an
application-handled file or drags a file onto the application’s
icon. The procedure is always called in the initial eventspace’s
handler thread (as a callback), and the argument is a filename.

The default handler queues a callback to the
on-drop-file method of the most-recently activated frame in the main eventspace (see
get-top-level-edit-target-window), if any such frame exists and if
drag-and-drop is enabled for that frame. Otherwise, it saves
the filename and re-queues the handler event when the application
file handler is later changed or when a frame becomes active.

On Windows, when the application is not running and user double-clicks an
application-handled file or drags a file onto the application’s icon,
the filename is provided as a command-line argument to the
application.

When the current eventspace is the initial eventspace, this procedure
retrieves or installs a thunk that is called when the user selects
the application Preferences menu item on Mac OS X. The
thunk is always called in the initial eventspace’s handler thread (as
a callback). If the handler is set to #f, the
Preferences item is disabled.

The default handler is #f.

If the current eventspace is not the initial eventspace, this
procedure returns void (when called with zero arguments)
or has no effect (when called with a handler).

When the current eventspace is the initial eventspace, this procedure
retrieves or installs a thunk that is called when the user requests
that the application quit (e.g., through the Quit menu
item on Mac OS X, or when shutting down the machine in Windows). The
thunk is always called in the initial eventspace’s handler thread (as
a callback). If the result of the thunk is #f, then the
operating system is explicitly notified that the application does not
intend to quit (on Windows).

The default handler queues a call to the
can-exit? method of the most
recently active frame in the initial eventspace (and then calls the
frame’s on-exit method if the
result is true). The result is #t if the eventspace is
left with no open frames after
on-exit returns, #f
otherwise.

If the current eventspace is not the initial eventspace, this
procedure returns void (when called with zero arguments)
or has no effect (when called with a handler).

When the current eventspace is the initial eventspace, this procedure
retrieves or installs a thunk that is called when the user starts
the application on Mac OS X without supplying any initial files (e.g.,
by double-clicking the application icon instead of double-clicking
files that are handled by the application).

Returns the number of pixels that correspond to one drawing unit on a
monitor. The result is normally 1.0, but it is 2.0
on Mac OS X in Retina display mode, and on Windows it can be a value
such as 1.25, 1.5, or 2.0 when the operating-system
scale for text is changed. See also Screen Resolution and Text Scaling.

When the optional argument is #f (the default), this function
returns the offset of monitor’s origin from the
top-left of the physical monitor. For monitor0, on Unix and Windows, the result is
always 0 and 0; on Mac OS X, the result is
0 and the height of the menu bar. To position a frame
at a given monitor’s top-left corner, use the negated results from
get-display-left-top-inset as the frame’s position.

When the optional avoid-bars? argument is true, for monitor0, get-display-left-top-inset function returns the
amount space at the left and top of the monitor that is occupied by
the task bar (Windows) or menu bar and dock (Mac OS X). On Unix, for
monitor 0, the result is always 0 and 0.
For monitors other than 0, avoid-bars? has no effect.

If monitor is not less than the current number of available
monitors (which can change at any time), the results are #f
and #f. See also display-changed in top-level-window<%>.

Finds a platform-specific (and possibly user- or machine-specific)
standard filename or directory. See also find-system-path.

The result depends on what, and a #f result is only
possible when what is 'x-display:

'init-file returns the ,path to the user-specific
initialization file (containing Racket code). The directory part of
the path is the same path as returned for 'init-dir by
Racket’s find-system-path. The file name is
platform-specific:

Unix and Mac OS X: ".gracketrc"

Windows: "gracketrc.rktl"

'x-display returns a “path” whose string identifies
the X11 display if specified by either the -display flag or the
DISPLAY environment variable when GRacket starts on Unix. For
other platforms, or when neither -display nor DISPLAY
was specified, the result is #f.

On Windows, the default is '(ctl). On Mac OS X, the
default is '(cmd). On Unix, the default is normally
'(ctl), but the default can be changed through the
'GRacket:defaultMenuPrefix
preference low-level preference (see
Preferences).

Historically, the result matched the color of
a panel% background, but panel% backgrounds can vary
on some platforms (e.g., when nested in a group-box-panel%),
so the result is no longer guaranteed to be related to a
panel%’s color.

Similar to read-eval-print-loop, except that none of
read-eval-print-loop’s configuration parameters are used (such
as current-read) and the interaction occurs in a GUI window
instead of using the current input and output ports.

If no eventspace is provided, or if #f is provided, an
evaluation eventspace is created using (make-eventspace)
with a new custodian; the eventspace and its threads are be shut down
when the user closes the graphical-read-eval-print-loop
window. If an eventspace is provided, closing the window performs no
shut-down actions on eventspace.

When redirect-ports? is true, the following parameters are
initialized in the created eventspace’s handler thread:

The current-prompt-read parameter is used in the current
thread to read input. The result is queued for evaluation and
printing in the created eventspace’s handler thread, which
uses current-eval and current-print. After printing
completes for an interaction result, the next expression in read in
the original thread, and so on.

If an exn:break exception is raised in the original thread
during reading, it aborts the current call to (current-read)
and a new one is started. If an exn:break exception is raised
in the original thread while waiting for an interaction to complete, a
break is sent (via break-thread) to the created eventspace’s
handler thread.

Strips shortcut ampersands from label, removes parenthesized
ampersand–character combinations along with any surrounding space,
and removes anything after a tab. Overall, it returns the label as it would
appear on a button on a platform without support for mnemonics.

Creates a bitmap that draws in a way that is the same as drawing to a
canvas in its default configuration.

In particular, on Mac OS X when the main monitor is in Retina display
mode, a drawing unit corresponds to two pixels, and the bitmap
internally contains four times as many pixels as requested by
width and height. On Windows, the backing scale
is similarly increased by adjusting the operating-system text scale.
See also get-display-backing-scale.

Plays a sound file. If async? is false, the function does not
return until the sound completes. Otherwise, it returns immediately.
The result is #t if the sound plays successfully, #f
otherwise.

On Windows, only ".wav" files are supported.

On Unix, the function invokes an external sound-playing program;
looking for a few known programs (aplay, play,
esdplay, sndfile-play, audioplay). In addition, a
play command can be defined through the 'GRacket:playcmd
preference
preference (see Preferences). The preference can hold a
program name, or a format string containing a single ~a
where the filename should be substituted—and used as a shell
command. (Don’t use ~s, since the string that is used
with the format string will be properly quoted and wrapped in double
quotes.) A plain command name is usually better since execution is
faster. The command’s output is discarded, unless it returns an
error code—in this case the last part of the error output is
shown.

On Mac OS X, Quicktime is used to play sounds; most sound
formats (.wav, .aiff, .mp3) are supported in recent versions of
Quicktime. In order to play .wav files, Quicktime 3.0 (compatible
with OS 7.5 and up) is required.

Registers a “blit” to occur when garbage collection starts and
ends. When garbage collection starts, on is drawn at
location x and y within canvas, if
canvas is shown. When garbage collection ends, the drawing
is reverted, possibly by drawing the off bitmap.

The background behind on is unspecified, so on
should be a solid image, and the canvas’s scale or scrolling is not
applied to the drawing. Only the portion of on within
w and h pixels is used; if on-x and
on-y are specified, they specify an offset within the bitmap
that is used for drawing, and off-x and off-y
similarly specify an offset within off.

The blit is automatically unregistered if canvas becomes
invisible and inaccessible. Multiple registrations can be installed
for the same canvas.

Finds the frontmost top-level window at
(x, y) in global coordinates. If a window is there,
this function calls the window’s on-message method, providing message as the method’s
argument; the result of the function call is the result returned by
the method. If no Racket window is at the given coordinates, or if it
is covered by a non-Racket window at (x, y),
#f is returned.

Returns #t if v is a string whose length is less than or equal to 200.

This predicate is typically used as the contract for strings that
appear in GUI objects. In some cases, such as the label in a button%
or menu-item% object, the character & is treated specially
to indicate that the following character is used in keyboard navigation. See
set-label in labelled-menu-item<%> for one such example.
In other cases, such as the label on a frame%, & is not
treated specially.