4 Windowing Functions

4.1 Dialogs

These functions get input from the user and/or display messages.

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, 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. These patterns are not regular expressions and can only be used with a * wildcard character. For example, "*.jp*g;*.png". On Unix, a "*.*" pattern is implicitly replaced with "*". On Mac OS, 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.

See also path-dialog% for a richer interface.

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. The extension is derived from the user’s filters choice if the corresponding pattern is of the form (string-append "*." an-extension), and the first such pattern is used if the choice has multiple patterns. If the user’s choice has the pattern "*.*" and extension is the empty string, 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 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 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.

The style list is treated as for get-file.

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

See also path-dialog% for a richer interface.

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

See also path-dialog% for a richer interface.

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.

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.

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

Like message-box, except that

• the dialog contains a check box whose label is check-label;

• the result is two values: the message-box result, and a boolean indicating whether the box was checked; and

• style can contain 'checked to indicate that the check box should be initially checked.

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.

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.

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.

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.

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.2 Eventspaces

If suspend-to-kill? is not #f, then the eventspace’s handler thread is created using thread/suspend-to-kill. Otherwise, it is created using thread.

See Event Dispatching and Eventspaces for more information about eventspaces.

Changed in version 1.35 of package gui-lib: Added the suspend-to-kill? argument.

See Event Dispatching and Eventspaces for more information about eventspaces.

See Event Dispatching and Eventspaces for more information about eventspaces.

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.

If on? is provided as #f, key events are reported normally. 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 on? is provided as #f, key events are reported normally. This setting affects all windows and eventspaces.

If no argument is provided, the result is #t if Control plus Alt is currently treated as AltGr, #f otherwise.

Added in version 1.24 of package gui-lib.

A second (optional) boolean argument indicates whether the callback has a high or low priority in the event queue. See Event Dispatching and Eventspaces for information about the priority of events.

A handler procedure invoked by the system during a call to yield can itself call yield, creating an additional level of nested (but single-threaded) event handling.

See also sleep/yield.

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.

Evaluating (yield 'wait) is thus similar to (yield (current-eventspace)), except that it is sensitive to whether the current thread is a handler thread, instead of the value of the current-eventspace parameter.

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.

Always use (yield v) instead of a busy-wait loop.

Attempting to use certain methods of windows and timers in a shut-down eventspace also raises the exn:fail exception, but the get-top-level-window in area<%> and get-eventspace in top-level-window<%> methods work even after the area’s eventspace is shut down.

4.3 System Menus

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

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

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

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

On Mac OS, if an application is started without files, then the application-start-empty-handler procedure is called.

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

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

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

The default handler re-queues the handler event when the application start-empty handler is later changed. As a result, if an application sets both application-start-empty-handler and application-file-handler, then one or the other is eventually called.

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

4.4 Global Graphics

Normally, drawing is automatically flushed to the screen. Use flush-display sparingly to force updates to the screen when other actions depend on updating the display.

On Mac OS or Unix, the result can change at any time. See also display-changed in top-level-window<%>.

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

Changed in version 1.2 of package gui-lib: Added backing-scale support on Windows.

On Windows and Mac OS, the result can change at any time. See also display-changed in top-level-window<%>.

When the optional avoid-bars? argument is true, for monitor 0, 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). 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<%>.

See also Screen Resolution and Text Scaling.

On Windows and Mac OS, if the optional argument is true and monitor is 0, then the task bar, menu bar, and dock area are included in the result.

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

See also Screen Resolution and Text Scaling.

4.5 Fonts

On Mac OS, this font is slightly larger than normal-control-font. On Windows and Unix, it is the same size as normal-control-font.

On Windows, this font is the same size as normal-control-font, since the Windows control font is already relatively small. On Unix and Mac OS, this font is slightly smaller than normal-control-font.

On Mac OS, this font is slightly smaller than normal-control-font, and slightly larger than small-control-font. On Windows and Unix, it is the same size as normal-control-font.

4.6 Miscellaneous

The cursor installed by begin-busy-cursor overrides any window-specific cursors installed with set-cursor.

See also is-busy?.

Beware that certain kinds of windows behave badly when larger than 32,000 or so in either dimension on some platforms. Redraw of the window may be disabled or clipped, for example.

The get operation always returns #"????" and #"????" for Unix or Windows. The set operation has no effect on Unix or Windows.

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: ".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, 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.

See get-label-background-color for a closer approximation to a panel background.

See also get-label-foreground-color.

Added in version 1.38 of package gui-lib.

Comparing the results of get-label-foreground-color and get-label-background-color may be useful for detecting whether a platform’s current theme is “dark mode” versus “light mode.”

Added in version 1.38 of package gui-lib.

See also get-text-extent in dc<%>.

Expressions entered into the graphical read-eval-print loop can be evaluated in an eventspace (and thread) that is distinct from the one implementing the graphical-read-eval-print-loop window (i.e., the current eventspace when graphical-read-eval-print-loop is called).

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.