2.2 Windowing Functions
2.2.1 Dialogs
These functions get input from the user and/or display messages.
| |||||||||||||||||||||||||||||||||||||||||||||||||
| message : (or/c string? 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%.
| |||||||||||||||||||||||||||||||||||||||||||||||||
| message : (or/c string? 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.
| |||||||||||||||||||||||||||||||||||||||||||||||||
| message : (or/c string? 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%.
| ||||||||||||||||||||||||||||
| message : (or/c string? 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 | ||||||||||||
| ||||||||||||
|
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.)
| ||||||||||||||||||||||||||||||||
| → (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) | ||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||
| 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.)
| ||||||||||||||||||||
| → (one-of/c 'ok 'cancel 'yes 'no) | ||||||||||||||||||||
| title : label-string? | ||||||||||||||||||||
| message : string | ||||||||||||||||||||
| check-label : label-string? | ||||||||||||||||||||
| ||||||||||||||||||||
|
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.
| ||||||||||||||||||||||||||||||||||||
| → (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) | ||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||
| 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.
| |||||||||||||||||||||||||||||||||||
| title : string | |||||||||||||||||||||||||||||||||||
| message : (or/c string? false/c) | |||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||
| 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.
| ||||||||||||||||||||||||
| → (or/c (listof exact-nonnegative-integer?) |