diff --git a/collects/scribblings/gui/miscwin-funcs.scrbl b/collects/scribblings/gui/miscwin-funcs.scrbl index c61aaeb4..4747eb3b 100644 --- a/collects/scribblings/gui/miscwin-funcs.scrbl +++ b/collects/scribblings/gui/miscwin-funcs.scrbl @@ -13,49 +13,6 @@ @title{Miscellaneous} -@defproc[(bell) - void?]{ - -Rings the system bell. - - - -} - -@defproc[(play-sound [filename path-string?] - [async? any/c]) - boolean?]{ - -Plays a sound file. If @scheme[async?] is false, the function does not - return until the sound completes. Otherwise, it returns immediately. - The result is @scheme[#t] if the sound plays successfully, @scheme[#f] - otherwise. - -Under Windows, only @filepath{.wav} files are supported. - -Under X, the function invokes an external sound-playing program; - looking for a few known programs (@exec{aplay}, @exec{play}, - @exec{esdplay}, @exec{sndfile-play}, @exec{audioplay}). In addition, a - play command can be defined through the @ResourceFirst{playcmd} - preference (see @|mrprefsdiscuss|). The preference can hold a - program name, or a format string containing a single @litchar{~a} - where the filename should be substituted---and used as a shell - command. (Don't use @litchar{~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. - - - -} - @defproc[(begin-busy-cursor) void?]{ @@ -74,6 +31,15 @@ See also +} + +@defproc[(bell) + void?]{ + +Rings the system bell. + + + } @defproc[(end-busy-cursor) @@ -86,49 +52,87 @@ See } -@defproc[(is-busy?) - boolean?]{ +@defproc*[([(file-creator-and-type [filename path] + [creator-string (lambda (s) (and (bytes? s) + (= 4 (bytes-length s))))] + [type-bytes (lambda (s) (and (bytes? s) + (= 4 (bytes-length s))))]) + void?] + [(file-creator-and-type [filename path]) + (values (lambda (s) (and (bytes? s) + (= 4 (bytes-length s)))) + (lambda (s) (and (bytes? s) + (= 4 (bytes-length s)))))])]{ -Returns @scheme[#t] if a busy cursor has been installed with -@scheme[begin-busy-cursor] and not removed with -@scheme[end-busy-cursor]. +Gets or sets the creator and type of a file in Mac OS X. + +The get operation always returns @scheme[#"????"] and @scheme[#"????"] for + Unix or Windows. The set operation has no effect under Unix or + Windows. +} + +@defproc[(find-graphical-system-path [what (one-of/c 'init-file 'setup-file 'x-display)]) + (or/c path? false/c)]{ + +Finds a platform-specific (and possibly user- or machine-specific) + standard filename or directory. See also @scheme[find-system-path]. + +The result depends on @scheme[what], and a @scheme[#f] result is only + possible when @scheme[what] is @scheme['x-display]: + +@itemize{ + + @item{@scheme['init-file] returns the path to the user-specific + initialization file (containing Scheme code). The directory part of + the path is the same path as returned for @scheme['init-dir] by + MzScheme's @scheme[find-system-path]. The file name is + platform-specific: + @itemize{ + + @item{@|AllUnix|: @indexed-file{.mredrc}} + @item{Windows: @indexed-file{mredrc.ss}} + + }} + + @item{@scheme['setup-file] returns the path to the file + containing resources used by @scheme[get-resource]; obsolete.} + + @item{@scheme['x-display] returns a ``path'' whose string identifies + the X display if specified by either the @Flag{display} flag or the + @envvar{DISPLAY} environment variable when MrEd starts under X. For + other platforms, or when neither @Flag{display} nor @envvar{DISPLAY} + was specified, the result is @scheme[#f].} + +} } -@defproc[(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.) +@defproc[(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 +@xmethod[selectable-menu-item<%> get-shortcut-prefix]. +Under Windows, the default is @scheme['(ctl)]. Under Mac OS X, the +default is @scheme['(cmd)]. Under X, the default is normally +@scheme['(ctl)], but the default can be changed through the +@Resource{defaultMenuPrefix} low-level preference (see +@|mrprefsdiscuss|).} +@defproc[(get-panel-background) + (is-a?/c color%)]{ -} - -@defproc[(send-message-to-window [x (integer-in -10000 10000)] - [y (integer-in -10000 10000)] - [message any/c]) - any/c]{ - -@index['("drag-and-drop")]{Finds} the frontmost top-level window at - (@scheme[x], @scheme[y]) in global coordinates. If a window is there, - this function calls the window's @method[top-level-window<%> - on-message] method, providing @scheme[message] as the method's - argument; the result of the function call is the result returned by - the method. If no Scheme window is at the given coordinates, or if it - is covered by a non-Scheme window at (@scheme[x], @scheme[y]), - @scheme[#f] is returned. - - +Returns the background color of a panel (usually some shade of gray) + for the current platform. } @defproc[(get-resource [section string?] [entry string?] - [value (box/c exact-integer?)] + [value (box/c (or/c string? exact-integer?))] [file (or/c path? false/c) #f]) boolean?]{ @@ -180,91 +184,15 @@ following expression gets a command line for starting a browser: See also @scheme[write-resource].} +@defproc[(get-window-text-extent [string string] + [font (is-a?/c font%)]) + (values nonnegative-exact-integer? + nonnegative-exact-integer?)]{ -@defproc[(label->plain-label [label string]) - string]{ - -Strips shortcut ampersands from @scheme[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. - -} - -@defproc[(write-resource [section string?] - [entry string?] - [value (or/c string? exact-integer?)] - [file (or/c path-string? false/c) #f]) - boolean?]{ - -Writes a resource value to the specified resource database. The - resource value is keyed on the combination of @scheme[section] and - @scheme[entry], with the same special handling of @scheme[entry] for - under Windows as for @scheme[get-resource]. - -If @scheme[file] is @scheme[#f], the platform-specific resource - database is read, as determined by - @scheme[find-graphical-system-path] with - @indexed-scheme['setup-file]. - -The return value is @scheme[#t] if the write succeeds, @scheme[#f] - otherwise. (A failure indicates that the resource file cannot be - written.) - -If @scheme[value] is an integer outside a platform-specific range, - @|MismatchExn|. - -See also @scheme[get-resource].} - - -@defproc[(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 -@xmethod[selectable-menu-item<%> get-shortcut-prefix]. - -Under Windows, the default is @scheme['(ctl)]. Under Mac OS X, the -default is @scheme['(cmd)]. Under X, the default is normally -@scheme['(ctl)], but the default can be changed through the -@Resource{defaultMenuPrefix} low-level preference (see -@|mrprefsdiscuss|).} - -@defproc[(find-graphical-system-path [what (one-of/c 'init-file 'setup-file 'x-display)]) - (or/c path? false/c)]{ - -Finds a platform-specific (and possibly user- or machine-specific) - standard filename or directory. See also @scheme[find-system-path]. - -The result depends on @scheme[what], and a @scheme[#f] result is only - possible when @scheme[what] is @scheme['x-display]: - -@itemize{ - - @item{@scheme['init-file] returns the path to the user-specific - initialization file (containing Scheme code). The directory part of - the path is the same path as returned for @scheme['init-dir] by - MzScheme's @scheme[find-system-path]. The file name is - platform-specific: - @itemize{ - - @item{@|AllUnix|: @indexed-file{.mredrc}} - @item{Windows: @indexed-file{mredrc.ss}} - - }} - - @item{@scheme['setup-file] returns the path to the file - containing resources used by @scheme[get-resource]; obsolete.} - - @item{@scheme['x-display] returns a ``path'' whose string identifies - the X display if specified by either the @Flag{display} flag or the - @envvar{DISPLAY} environment variable when MrEd starts under X. For - other platforms, or when neither @Flag{display} nor @envvar{DISPLAY} - was specified, the result is @scheme[#f].} - -} - - +Returns the pixel size of a string drawn as a window's label or value +when drawn with the given font. +See also @method[dc<%> get-text-extent]. } @defproc[(graphical-read-eval-print-loop [eval-eventspace eventspace #f] @@ -307,58 +235,89 @@ The keymap for the read-eval-print loop's editor is initialized by } -@defthing[the-clipboard (is-a?/c clipboard<%>)]{ +@defproc[(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.) -See @scheme[clipboard<%>]. } -@defthing[the-x-selection-clipboard (is-a?/c clipboard<%>)]{ +@defproc[(is-busy?) + boolean?]{ + +Returns @scheme[#t] if a busy cursor has been installed with +@scheme[begin-busy-cursor] and not removed with +@scheme[end-busy-cursor]. -See @scheme[clipboard<%>]. } -@defproc[(get-window-text-extent [string string] - [font (is-a?/c font%)]) - (values nonnegative-exact-integer? - nonnegative-exact-integer?)]{ +@defproc[(label->plain-label [label string]) + string]{ -Returns the pixel size of a string drawn as a window's label or value -when drawn with the given font. - -See also @method[dc<%> get-text-extent]. -} - -@defproc[(get-panel-background) - (is-a?/c color%)]{ - -Returns the background color of a panel (usually some shade of gray) - for the current platform. +Strips shortcut ampersands from @scheme[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. } -@defproc*[([(file-creator-and-type [filename path] - [creator-string (lambda (s) (and (bytes? s) - (= 4 (bytes-length s))))] - [type-bytes (lambda (s) (and (bytes? s) - (= 4 (bytes-length s))))]) - void?] - [(file-creator-and-type [filename path]) - (values (lambda (s) (and (bytes? s) - (= 4 (bytes-length s)))) - (lambda (s) (and (bytes? s) - (= 4 (bytes-length s)))))])]{ -Gets or sets the creator and type of a file in Mac OS X. +@defproc[(make-gui-empty-namespace) + namespace?]{ + +Like @scheme[make-base-empty-namespace], but with +@scheme[scheme/class] and @schememodname[scheme/gui/base] also +attached to the result namespace.} + +@defproc[(make-gui-namespace) + namespace?]{ + +Like @scheme[make-base-namespace], but with @scheme[scheme/class] and +@schememodname[scheme/gui/base] also required into the top-level +environment of the result namespace.} + + +@defproc[(play-sound [filename path-string?] + [async? any/c]) + boolean?]{ + +Plays a sound file. If @scheme[async?] is false, the function does not + return until the sound completes. Otherwise, it returns immediately. + The result is @scheme[#t] if the sound plays successfully, @scheme[#f] + otherwise. + +Under Windows, only @filepath{.wav} files are supported. + +Under X, the function invokes an external sound-playing program; + looking for a few known programs (@exec{aplay}, @exec{play}, + @exec{esdplay}, @exec{sndfile-play}, @exec{audioplay}). In addition, a + play command can be defined through the @ResourceFirst{playcmd} + preference (see @|mrprefsdiscuss|). The preference can hold a + program name, or a format string containing a single @litchar{~a} + where the filename should be substituted---and used as a shell + command. (Don't use @litchar{~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. + + -The get operation always returns @scheme[#"????"] and @scheme[#"????"] for - Unix or Windows. The set operation has no effect under Unix or - Windows. } + @defproc[(send-event [receiver-bytes (lambda (s) (and (bytes? s) (= 4 (bytes-length s))))] [event-class-bytes (lambda (s) (and (bytes? s) @@ -424,16 +383,60 @@ If the AppleEvent reply contains a value that cannot be } -@defproc[(make-gui-empty-namespace) - namespace?]{ +@defproc[(send-message-to-window [x (integer-in -10000 10000)] + [y (integer-in -10000 10000)] + [message any/c]) + any/c]{ -Like @scheme[make-base-empty-namespace], but with -@scheme[scheme/class] and @schememodname[scheme/gui/base] also -attached to the result namespace.} +@index['("drag-and-drop")]{Finds} the frontmost top-level window at + (@scheme[x], @scheme[y]) in global coordinates. If a window is there, + this function calls the window's @method[top-level-window<%> + on-message] method, providing @scheme[message] as the method's + argument; the result of the function call is the result returned by + the method. If no Scheme window is at the given coordinates, or if it + is covered by a non-Scheme window at (@scheme[x], @scheme[y]), + @scheme[#f] is returned. -@defproc[(make-gui-namespace) - namespace?]{ -Like @scheme[make-base-namespace], but with @scheme[scheme/class] and -@schememodname[scheme/gui/base] also required into the top-level -environment of the result namespace.} + +} + +@defthing[the-clipboard (is-a?/c clipboard<%>)]{ + +See @scheme[clipboard<%>]. + + +} + +@defthing[the-x-selection-clipboard (is-a?/c clipboard<%>)]{ + +See @scheme[clipboard<%>]. + + +} + +@defproc[(write-resource [section string?] + [entry string?] + [value (or/c string? exact-integer?)] + [file (or/c path-string? false/c) #f]) + boolean?]{ + +Writes a resource value to the specified resource database. The + resource value is keyed on the combination of @scheme[section] and + @scheme[entry], with the same special handling of @scheme[entry] for + under Windows as for @scheme[get-resource]. + +If @scheme[file] is @scheme[#f], the platform-specific resource + database is read, as determined by + @scheme[find-graphical-system-path] with + @indexed-scheme['setup-file]. + +The return value is @scheme[#t] if the write succeeds, @scheme[#f] + otherwise. (A failure indicates that the resource file cannot be + written.) + +If @scheme[value] is an integer outside a platform-specific range, + @|MismatchExn|. + +See also @scheme[get-resource].} +