2.2 Windowing Functions

► |  | GUI: Racket Graphics Toolkit

1 | Overview
2 | Reference
3 | Configuration
4 | Dynamic Loading
| Bibliography
| Index

▼ | 2 | Reference

2.1 | Windowing Classes
2.2 | Windowing Functions
2.3 | Drawing Classes
2.4 | Drawing Functions
2.5 | Editor Classes
2.6 | Editor Functions
2.7 | WXME Decoding

► | 2.2 | Windowing Functions

2.2.1 | Dialogs
2.2.2 | Eventspaces
2.2.3 | System Menus
2.2.4 | Miscellaneous

On this page:

2.2.1`` Dialogs
get-file
get-file-list
put-file
get-directory
message-box
message-box/ custom
message+ check-box
message+ check-box/ custom
get-text-from-user
get-choices-from-user
get-color-from-user
get-font-from-user
get-ps-setup-from-user
get-page-setup-from-user
can-get-page-setup-from-user?
2.2.2`` Eventspaces
make-eventspace
current-eventspace
eventspace?
event-dispatch-handler
check-for-break
get-top-level-windows
get-top-level-focus-window
get-top-level-edit-target-window
special-control-key
special-option-key
queue-callback
yield
sleep/ yield
eventspace-shutdown?
eventspace-handler-thread
2.2.3`` System Menus
current-eventspace-has-standard-menus?
current-eventspace-has-menu-root?
application-about-handler
application-preferences-handler
application-quit-handler
application-file-handler
2.2.4`` Miscellaneous
begin-busy-cursor
bell
end-busy-cursor
file-creator-and-type
find-graphical-system-path
get-default-shortcut-prefix
get-panel-background
get-resource
get-window-text-extent
graphical-read-eval-print-loop
textual-read-eval-print-loop
hide-cursor-until-moved
is-busy?
label->plain-label
make-gui-empty-namespace
make-gui-namespace
play-sound
send-event
send-message-to-window
system-position-ok-before-cancel?
the-clipboard
the-x-selection-clipboard
write-resource
label-string?
key-code-symbol?

top← prev up next →

#### 2.2`` Windowing Functions

2.2.1 Dialogs
2.2.2 Eventspaces
2.2.3 System Menus
2.2.4 Miscellaneous

##### 2.2.1`` Dialogs

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

( get-file | [ | message |  |  |  |
|  | parent |  |  |  |
|  | directory |  |  |  |
|  | filename |  |  |  |
|  | extension |  |  |  |
|  | style |  |  |  |
|  | filters]) |  | → |  | ( or/c path? false/c)

message : ( or/c string? false/c) = #f

| parent |  | : |  | ( or/c ( is-a?/c frame%) ( is-a?/c dialog%) false/c)
|  |  | = |  | #f

directory : ( or/c path-string? false/c) = #f
filename : ( or/c path-string? false/c) = #f
extension : ( or/c string? false/c) = #f
style : ( listof ( one-of/c 'packages 'enter-packages)) = null
filters : ( listof ( list/c string? string?)) = '(("Any" "*.*"))

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

Under Windows and X, 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.

See also path-dialog%.

( get-file-list | [ | message |  |  |  |
|  | parent |  |  |  |
|  | directory |  |  |  |
|  | filename |  |  |  |
|  | extension |  |  |  |
|  | style |  |  |  |
|  | filters]) |  | → |  | ( or/c ( listof path?) false/c)

message : ( or/c string? false/c) = #f

| parent |  | : |  | ( or/c ( is-a?/c frame%) ( is-a?/c dialog%) false/c)
|  |  | = |  | #f

directory : ( or/c path-string? false/c) = #f
filename : ( or/c path-string? false/c) = #f
extension : ( or/c string? false/c) = #f
style : null? = null
filters : ( listof ( list/c string? string?)) = '(("Any" "*.*"))

Like get-file, except that the user can select multiple files, and the result is either a list of file paths of #f.

( put-file | [ | message |  |  |  |
|  | parent |  |  |  |
|  | directory |  |  |  |
|  | filename |  |  |  |
|  | extension |  |  |  |
|  | style |  |  |  |
|  | filters]) |  | → |  | ( or/c path? false/c)

message : ( or/c string? false/c) = #f

| parent |  | : |  | ( or/c ( is-a?/c frame%) ( is-a?/c dialog%) false/c)
|  |  | = |  | #f

directory : ( or/c path-string? false/c) = #f
filename : ( or/c path-string? false/c) = #f
extension : ( or/c string? false/c) = #f
style : ( listof ( one-of/c 'packages 'enter-packages)) = null
filters : ( listof ( list/c string? string?)) = '(("Any" "*.*"))

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.

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

Under Mac OS X 10.5 and later, if extension is not #f, 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.

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

The extension argument is ignored under X, and filters can be used to specify glob-patterns.

The style list is treated as for get-file.

See also path-dialog%.

( get-directory | [ | message |  |  |  |
|  | parent |  |  |  |
|  | directory |  |  |  |
|  | style]) |  | → |  | ( or/c path false/c)

message : ( or/c string? false/c) = #f

| parent |  | : |  | ( or/c ( is-a?/c frame%) ( is-a?/c dialog%) false/c)
|  |  | = |  | #f

directory : ( or/c path? false/c) = #f
style : ( listof ( one-of/c 'enter-packages)) = null

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

See also path-dialog%.

( message-box title message [parent style])
→ ( one-of/c 'ok 'cancel 'yes 'no)
title : label-string?
message : string

| parent |  | : |  | ( or/c ( is-a?/c frame%) ( is-a?/c dialog%) false/c)
|  |  | = |  | #f

| style |  | : |  | ( listof ( one-of/c 'ok 'ok-cancel 'yes-no 'caution 'stop))
|  |  | = |  | '(ok)

See also message-box/custom.

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. Alternately, it can contain 'stop to make the dialog use a stop icon. If style contains both 'caution and 'stop, then 'caution is ignored.

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

( message-box/custom |  | title |
|  | message |
|  | button1-label |
|  | button2-label |
|  | button3-label |
| [ | parent |
|  | style |
|  | close-result]) |

→ ( one-of/c 1 2 3 close-result)
title : label-string?
message : string
button1-label : ( or/c label-string? ( is-a?/c bitmap%) false/c)
button2-label : ( or/c label-string? ( is-a?/c bitmap%) false/c)
button3-label : ( or/c label-string? ( is-a?/c bitmap%) false/c)

| parent |  | : |  | ( or/c ( is-a?/c frame%) ( is-a?/c dialog%) false/c)
|  |  | = |  | #f

style

:

( listof ( one-of/c 'stop 'caution 'number-order
'disallow-close 'no-default
'default=1 'default=2 'default=3))

|  |  | = |  | '(no-default)

close-result : any/c = #f

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. Under Windows, this button is leftmost; under X 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 (under 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 to make the dialog use a caution icon instead of the application (or generic “info”) icon. Alternately, it can contain 'stop to make the dialog use a stop icon. If style contains both 'caution and 'stop, then 'caution is ignored.

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

( message+check-box |  | title |
|  | message |
|  | check-label |
| [ | parent |
|  | style]) |

→ ( one-of/c 'ok 'cancel 'yes 'no)
title : label-string?
message : string
check-label : label-string?

| parent |  | : |  | ( or/c ( is-a?/c frame%) ( is-a?/c dialog%) false/c)
|  |  | = |  | #f

style

:

( listof ( one-of/c 'ok 'ok-cancel 'yes-no
'caution 'stop 'checked))

=

'(ok)

See also message+check-box/custom.

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.

( message+check-box/custom |  | title |
|  | message |
|  | check-label |
|  | button1-label |
|  | button2-label |
|  | button3-label |
| [ | parent |
|  | style |
|  | close-result]) |

→ ( one-of/c 1 2 3 close-result)
title : label-string?
message : string
check-label : label-string?
button1-label : ( or/c label-string? ( is-a?/c bitmap%) false/c)
button2-label : ( or/c label-string? ( is-a?/c bitmap%) false/c)
button3-label : ( or/c label-string? ( is-a?/c bitmap%) false/c)

| parent |  | : |  | ( or/c ( is-a?/c frame%) ( is-a?/c dialog%) false/c)
|  |  | = |  | #f

style

:

( listof ( one-of/c 'stop 'caution 'number-order
'disallow-close 'no-default
'default=1 'default=2 'default=3))

|  |  | = |  | '(no-default)

close-result : any/c = #f

Like message-box/custom, 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.

( get-text-from-user |  | title |  |  |  |
|  | message |  |  |  |
| [ | parent |  |  |  |
|  | init-val |  |  |  |
|  | style]) |  | → |  | ( or/c string? false/c)

title : string
message : ( or/c string? false/c)

| parent |  | : |  | ( or/c ( is-a?/c frame%) ( is-a?/c dialog%) false/c)
|  |  | = |  | #f

init-val : string? = ""
style : ( listof ( one-of/c 'password)) = null

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.

( get-choices-from-user |  | title |
|  | message |
|  | choices |
| [ | parent |
|  | init-choices |
|  | style]) |

→ ( or/c ( listof exact-nonnegative-integer?) false/c)
title : string
message : ( or/c string? false/c)
choices : ( listof string?)

| parent |  | : |  | ( or/c ( is-a?/c frame%) ( is-a?/c dialog%) false/c)
|  |  | = |  | #f

init-choices : ( listof exact-nonnegative-integer?) = null

| style |  | : |  | ( listof ( one-of/c 'single 'multiple 'extended))
|  |  | = |  | '(single)

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.

( get-color-from-user | [ | message |
|  | parent |
|  | init-color |
|  | style]) |

→ ( or/c ( is-a?/c color%) false/c)
message : ( or/c string? false/c) = #f

| parent |  | : |  | ( or/c ( is-a?/c frame%) ( is-a?/c dialog%) false/c)
|  |  | = |  | #f

init-color : ( or/c ( is-a?/c color%) false/c) = #f
style : null? = null

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

( get-font-from-user | [ | message |  |  |  |
|  | parent |  |  |  |
|  | init-font |  |  |  |
|  | style]) |  | → |  | ( or/c ( is-a?/c font%) false/c)

message : ( or/c string? false/c) = #f

| parent |  | : |  | ( or/c ( is-a?/c frame%) ( is-a?/c dialog%) false/c)
|  |  | = |  | #f

init-font : ( or/c ( is-a?/c font%) false/c) = #f
style : null? = null

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.

( get-ps-setup-from-user | [ | message |
|  | parent |
|  | init-setup |
|  | style]) |

→ ( or/c ( is-a?/c ps-setup%) false/c)
message : ( or/c string? false/c) = #f

| parent |  | : |  | ( or/c ( is-a?/c frame%) ( is-a?/c dialog%) false/c)
|  |  | = |  | #f

init-setup : ( or/c ( is-a?/c ps-setup%) false/c) = #f
style : null? = null

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.

( get-page-setup-from-user | [ | message |
|  | parent |
|  | init-setup |
|  | style]) |

→ ( or/c ( is-a?/c ps-setup%) false/c)
message : ( or/c string? false/c) = #f

| parent |  | : |  | ( or/c ( is-a?/c frame%) ( is-a?/c dialog%) false/c)
|  |  | = |  | #f

init-setup : ( or/c ( is-a?/c ps-setup%) false/c) = #f
style : null? = null

Like get-ps-setup-from-user, but the dialog configures page layout for native printing with printer-dc%. A dialog is shown only if can-get-page-setup-from-user? returns #t, otherwise no dialog is shown and the result is #f.

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.

( can-get-page-setup-from-user?) → boolean?

Returns #t if the current platform (Mac OS X) supports a page-layout dialog for use with printer-dc% printing, and if the page-layout dialog is different from the print-job dialog that is automatically shown when a printer-dc% is created. Returns #f if no separate page-layout dialog is needed (Windows and Unix).

##### 2.2.2`` Eventspaces

( make-eventspace) → eventspace

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.

See Event Dispatching and Eventspaces for more information about eventspaces.

( current-eventspace) → eventspace?
( current-eventspace e) → void?
e : eventspace?

A parameter (see Parameters) that determines the current eventspace.

See Event Dispatching and Eventspaces for more information about eventspaces.

( eventspace? v) → boolean?
v : any/c

Returns #t if v is an eventspace value or #f otherwise.

See Event Dispatching and Eventspaces for more information about eventspaces.

( event-dispatch-handler) → ( eventspace? . -> . any)
( event-dispatch-handler handler) → void?
handler : ( eventspace? . -> . any)

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.

( check-for-break) → boolean?

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

( get-top-level-windows)
→ ( listof ( or/c ( is-a?/c frame%) ( is-a?/c dialog%)))

Returns a list of visible top-level frames and dialogs in the current eventspace.

( get-top-level-focus-window)
→ ( or/c ( is-a?/c frame%) ( is-a?/c dialog%) false/c)

Returns the top level window in the current eventspace that has the keyboard focus (or contains the window with the keyboard focus), or #f if no window in the current eventspace has the focus.

( get-top-level-edit-target-window)
→ ( or/c ( is-a?/c frame%) ( is-a?/c dialog%) false/c)

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.

( special-control-key on?) → void?
on? : any/c
( special-control-key) → boolean?

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.

( special-option-key on?) → void?
on? : any/c
( special-option-key) → boolean?

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.

( queue-callback callback [high-priority?]) → void?
callback : (-> any)
high-priority? : any/c = #t

Installs a procedure to be called via the current eventspace’s event queue. The procedure is called once in the same way and under the same restrictions that a callback is invoked to handle a method.

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.

( yield) → boolean?
( yield v) → any/c
v : ( or/c ( one-of/c 'wait) evt?)

Yields control to event dispatching. See Event Dispatching and Eventspaces for details.

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.

( sleep/yield secs) → void?
secs : ( and/c real? ( not/c negative?))

Blocks for at least the specified number of seconds, handling events meanwhile if the current thread is the current eventspace’s handler thread (otherwise, sleep/yield is equivalent to sleep).

( eventspace-shutdown? e) → boolean?
e : eventspace

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:misc exception.

Attempting to use certain methods of windows and timers in a shut-down eventspace also raises the exn:misc 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.

( eventspace-handler-thread e) → ( or/c thread false/c)
e : eventspace

Returns the handler thread of the given eventspace. If the handler thread has terminated (e.g., because the eventspace was shut down), the result is #f.

##### 2.2.3`` System Menus

( current-eventspace-has-standard-menus?) → boolean?

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

( current-eventspace-has-menu-root?) → boolean?

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.

( application-about-handler) → (-> any)
( application-about-handler handler-thunk) → void?
handler-thunk : (-> any)

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

( application-preferences-handler) → ( or/c (-> any) false/c)
( application-preferences-handler handler-thunk) → void?
handler-thunk : ( or/c (-> any) false/c)

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

( application-quit-handler) → (-> any)
( application-quit-handler handler-thunk) → void?
handler-thunk : (-> any)

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 in 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 (under 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).

( application-file-handler) → ( path? . -> . any)
( application-file-handler handler-proc) → void?
handler-proc : ( path? . -> . any)

When the current eventspace is the initial eventspace, this procedure retrieves or installs a procedure that is called under 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 drag-and-drop is enabled for that frame.

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.

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

##### 2.2.4`` Miscellaneous

( begin-busy-cursor) → void?

Changes the cursor to a watch cursor for all windows in the current eventspace. Use end-busy-cursor to revert the cursor back to its previous state. Calls to begin-busy-cursor and end-busy-cursor can be nested arbitrarily.

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

See also is-busy?.

( bell) → void?

Rings the system bell.

( end-busy-cursor) → void?

See begin-busy-cursor.

( file-creator-and-type |  | filename |  |  |  |
|  | creator-string |  |  |  |
|  | type-bytes) |  | → |  | void?

filename : path

creator-string

:

( lambda (s) ( and ( bytes? s)
(= 4 ( bytes-length s))))

type-bytes

:

( lambda (s) ( and ( bytes? s)
(= 4 ( bytes-length s))))

( file-creator-and-type filename)

→

( lambda (s) ( and ( bytes? s)
(= 4 ( bytes-length s))))

( lambda (s) ( and ( bytes? s)
(= 4 ( bytes-length s))))

filename : path

Gets or sets the creator and type of a file in Mac OS X.

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

( find-graphical-system-path what) → ( or/c path? false/c)
what : ( one-of/c 'init-file 'setup-file 'x-display)

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: "racketrc.rktl"

- 'setup-file returns the path to the file containing resources used by get-resource; obsolete.

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

( get-default-shortcut-prefix)
→ ( listof ( one-of/c 'alt 'cmd 'meta 'ctl 'shift 'option))

Returns an immutable list specifying the default prefix for menu shortcuts. See also get-shortcut-prefix in selectable-menu-item<%>.

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

( get-panel-background) → ( is-a?/c color%)

Returns the background color of a panel (usually some shade of gray) for the current platform.

( get-resource section entry value [file]) → boolean?
section : string?
entry : string?
value : ( box/c ( or/c string? exact-integer?))
file : ( or/c path? false/c) = #f

Gets a resource value from the resource database. The resource value is keyed on the combination of section and entry. The return value is #t if a value is found, #f if it is not. The type of the value initially in the value box determines the way that the resource is interpreted, and value is filled with a new value of the same type if one is found.

If file is #f, platform-specific resource files are read, as determined by find-graphical-system-path with 'setup-file. (Under X, when file is #f, the user’s ".Xdefaults" file is also read, or the file specified by the "XENVIRONMENT" environment variable.)

The format of a resource entry depends on the platform. Windows resources use the standard ".ini" format. X and Mac OS X resources use the standard X resource format, where each entry consists of a section.entry resource name, a colon, and the resource value, terminated by a newline. Section and entry names are case-sensitive.

Under Windows, if section is one of the following strings, then file is ignored, and entry is used as a resource path:

- "HKEY_CLASSES_ROOT"

- "HKEY_CURRENT_CONFIG"

- "HKEY_CURRENT_USER"

- "HKEY_LOCAL_MACHINE"

- "HKEY_USERS"

In that case, the entry argument is parsed as a resource entry path, followed by a backslash, followed by a value name. To get the “default” value for an entry, use the empty name. For example, the following expression gets a command line for starting a browser:

( let ([b ( box "")])
( get-resource "HKEY_CLASSES_ROOT"
"htmlfile\\shell\\open\\command\\" b)
( unbox b))

See also write-resource.

( get-window-text-extent |  | string |  |  |  |
|  | font |  |  |  |

[

combine?])

→

exact-nonnegative-integer?
exact-nonnegative-integer?

string : string
font : ( is-a?/c font%)
combine? : any/c = #f

Returns the pixel size of a string drawn as a window’s label or value when drawn with the given font. The optional combine? argument is as for get-text-extent in dc<%>.

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

( graphical-read-eval-print-loop | [ | eval-eventspace |  |  |  |
|  | redirect-ports?]) |  | → |  | void?

eval-eventspace : eventspace = #f
redirect-ports? : any/c = ( not eval-eventspace)

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.

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.

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

- current-output-port – writes to the frame

- current-error-port – writes to the frame

- current-input-port – always returns eof

The keymap for the read-eval-print loop’s editor is initialized by calling the current keymap initializer procedure, which is determined by the current-text-keymap-initializer parameter.

( textual-read-eval-print-loop) → void?

Similar to read-eval-print-loop, except that evaluation uses a newly created eventspace.

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.

( hide-cursor-until-moved) → void?

Hides the cursor until the user moves the mouse or clicks the mouse button. (For some platforms, the cursor is not hidden if it is over a window in a different eventspace or application.)

( is-busy?) → boolean?

Returns #t if a busy cursor has been installed with begin-busy-cursor and not removed with end-busy-cursor.

( label->plain-label label) → string?
label : string

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.

( make-gui-empty-namespace) → namespace?

Like make-base-empty-namespace, but with racket/class and racket/gui/base also attached to the result namespace.

( make-gui-namespace) → namespace?

Like make-base-namespace, but with racket/class and racket/gui/base also required into the top-level environment of the result namespace.

( play-sound filename async?) → boolean?
filename : path-string?
async? : any/c

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.

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

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

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

( send-event |  | receiver-bytes |  |  |  |
|  | event-class-bytes |  |  |  |
|  | event-id-bytes |  |  |  |
| [ | direct-arg-v |  |  |  |
|  | argument-list]) |  | → |  | any/c

receiver-bytes

:

( lambda (s) ( and ( bytes? s)
(= 4 ( bytes-length s))))

event-class-bytes

:

( lambda (s) ( and ( bytes? s)
(= 4 ( bytes-length s))))

event-id-bytes

:

( lambda (s) ( and ( bytes? s)
(= 4 ( bytes-length s))))

direct-arg-v : any/c = ( void)
argument-list : list? = null

Sends an AppleEvent or raises exn:fail:unsupported.

The receiver-bytes, event-class-bytes, and event-id-bytes arguments specify the signature of the receiving application, the class of the AppleEvent, and the ID of the AppleEvent.

The direct-arg-v value is converted (see below) and passed as the main argument of the event; if direct-argument-v is #<void>, no main argument is sent in the event. The argument-list argument is a list of two-element lists containing a typestring and value; each typestring is used ad the keyword name of an AppleEvent argument for the associated converted value.

The following types of Racket values can be converted to AppleEvent values passed to the receiver:

| #t or #f |  | → |  | Boolean
| small integer |  | → |  | Long Integer
| inexact real number |  | → |  | Double
| string |  | → |  | Characters
| list of convertible values |  | → |  | List of converted values
| #(file pathname) |  | → |  | Alias (file exists) or FSSpec (does not exist)
| #(record (typestring v) ...) |  | → |  | Record of keyword-tagged values

If other types of values are passed to send-event for conversion, the exn:fail:unsupported exception is raised.

The send-event procedure does not return until the receiver of the AppleEvent replies. The result of send-event is the reverse-converted reply value (see below), or the exn:fail exception is raised if there is an error. If there is no error or return value, send-event returns #<void>.

The following types of AppleEvent values can be reverse-converted into a Racket value returned by send-event:

| Boolean |  | → |  | #t or #f
| Signed Integer |  | → |  | integer
| Float, Double, or Extended |  | → |  | inexact real number
| Characters |  | → |  | string
| List of reverse-convertible values |  | → |  | list of reverse-converted values
| Alias or FSSpec |  | → |  | #(file pathname)
| Record of keyword-tagged values |  | → |  | #(record (typestring v) ...)

If the AppleEvent reply contains a value that cannot be reverse-converted, the exn:fail exception is raised.

( send-message-to-window x y message) → any/c
x : ( integer-in -10000 10000)
y : ( integer-in -10000 10000)
message : any/c

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.

( system-position-ok-before-cancel?) → boolean?

Returns #t under Windows – indicating that a dialog with OK and Cancel buttons should place the OK button on to left of the Cancel button – and returns #f under Mac OS X and X.

the-clipboard : ( is-a?/c clipboard<%>)

See clipboard<%>.

the-x-selection-clipboard : ( is-a?/c clipboard<%>)

See clipboard<%>.

( write-resource section entry value [file]) → boolean?
section : string?
entry : string?
value : ( or/c string? exact-integer?)
file : ( or/c path-string? false/c) = #f

Writes a resource value to the specified resource database. The resource value is keyed on the combination of section and entry, with the same special handling of entry for under Windows as for get-resource.

If file is #f, the platform-specific resource database is read, as determined by find-graphical-system-path with 'setup-file.

The return value is #t if the write succeeds, #f otherwise. (A failure indicates that the resource file cannot be written.)

If value is an integer outside a platform-specific range, an exn:fail:contract exception is raised.

See also get-resource.

( label-string? v) → boolean?
v : any/c

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

( key-code-symbol? v) → boolean?
v : any/c

Returns #t if the argument is a symbol that can be returned by key-event%’s method get-key-code.
top← prev up next →