446 lines
16 KiB
Racket
446 lines
16 KiB
Racket
#lang scribble/doc
|
|
@require["common.ss"]
|
|
@require[scribble/struct]
|
|
|
|
@define[(atable . l)
|
|
(make-table #f (map (lambda (i)
|
|
(map (lambda (e)
|
|
(make-flow (list (make-paragraph (list e)))))
|
|
i))
|
|
l))]
|
|
@define[(tline l r) (list (hspace 2) l (hspace 1) 'rarr (hspace 1) r)]
|
|
|
|
|
|
@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?]{
|
|
|
|
Changes the cursor to a watch cursor for all windows in the current eventspace.
|
|
Use
|
|
@scheme[end-busy-cursor] to revert the cursor back to its previous state. Calls to
|
|
@scheme[begin-busy-cursor] and
|
|
@scheme[end-busy-cursor] can be nested arbitrarily.
|
|
|
|
The cursor installed by
|
|
@scheme[begin-busy-cursor] overrides any window-specific cursors installed with
|
|
@method[window<%> set-cursor].
|
|
|
|
See also
|
|
@scheme[is-busy?].
|
|
|
|
|
|
|
|
}
|
|
|
|
@defproc[(end-busy-cursor)
|
|
void?]{
|
|
|
|
See
|
|
@scheme[begin-busy-cursor].
|
|
|
|
|
|
|
|
}
|
|
|
|
@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].
|
|
|
|
|
|
|
|
}
|
|
|
|
@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[(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 MrEd window is at the given coordinates, or if it
|
|
is covered by a non-MrEd window at (@scheme[x], @scheme[y]),
|
|
@scheme[#f] is returned.
|
|
|
|
|
|
|
|
}
|
|
|
|
@defproc[(get-resource [section string?]
|
|
[entry string?]
|
|
[value (box/c exact-integer?)]
|
|
[file (or/c path? false/c) #f])
|
|
boolean?]{
|
|
|
|
Gets a resource value from the resource database. The resource value
|
|
is keyed on the combination of @scheme[section] and @scheme[entry]. The
|
|
return value is @scheme[#t] is a value is found, @scheme[#f] if it is
|
|
not. The type of the value initially in the @scheme[value] box
|
|
determines the way that the resource is interpreted, and @scheme[value]
|
|
is filled with a new value of the same type if one is found.
|
|
|
|
If @scheme[file] is @scheme[#f], platform-specific resource files
|
|
are read, as determined by @scheme[find-graphical-system-path]
|
|
with @indexed-scheme['setup-file]. (Under X, when @scheme[file] is
|
|
@scheme[#f], the user's @filepath{.Xdefaults} file is also read, or the
|
|
file specified by the @filepath{XENVIRONMENT} environment variable.)
|
|
|
|
The format of a resource entry depends on the platform. Windows
|
|
resources use the standard @filepath{.ini} format. X and Mac OS X
|
|
resources use the standard X resource format, where each entry
|
|
consists of a @scheme[section].@scheme[entry] resource name, a colon, and
|
|
the resource value, terminated by a newline. Section and entry names are
|
|
case-sensitive.
|
|
|
|
@index['("registry")]{@index['("Windows registry")]{Under}} Windows, if
|
|
@scheme[section] is one of the following strings, then @scheme[file]
|
|
is ignored, and @scheme[entry] is used as a resource path:
|
|
|
|
@itemize{
|
|
|
|
@item{@indexed-scheme["HKEY_CLASSES_ROOT"]}
|
|
@item{@indexed-scheme["HKEY_CURRENT_CONFIG"]}
|
|
@item{@indexed-scheme["HKEY_CURRENT_USER"]}
|
|
@item{@indexed-scheme["HKEY_LOCAL_MACHINE"]}
|
|
@item{@indexed-scheme["HKEY_USERS"]}
|
|
|
|
}
|
|
|
|
In that case, the @scheme[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:
|
|
|
|
@schemeblock[
|
|
(let ([b (box "")])
|
|
(get-resource "HKEY_CLASSES_ROOT"
|
|
"htmlfile\\shell\\open\\command\\" b)
|
|
(unbox b))
|
|
]
|
|
|
|
See also @scheme[write-resource].}
|
|
|
|
|
|
@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 menmonics.
|
|
|
|
}
|
|
|
|
@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].}
|
|
|
|
}
|
|
|
|
|
|
|
|
}
|
|
|
|
@defproc[(graphical-read-eval-print-loop [eval-eventspace eventspace #f]
|
|
[redirect-ports? any/c @scheme[(not @scheme[eval-eventspace])]])
|
|
void?]{
|
|
|
|
Similar to MzScheme's @scheme[read-eval-print-loop], except that none of
|
|
@scheme[read-eval-print-loop]'s configuration parameters are used (such
|
|
as @scheme[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 @scheme[graphical-read-eval-print-loop]
|
|
window (i.e., the current eventspace when
|
|
@scheme[graphical-read-eval-print-loop] is called).
|
|
|
|
If no eventspace is provided, or if @scheme[#f] is provided, an
|
|
evaluation eventspace is created using @scheme[(make-eventspace)]
|
|
with a new custodian; the eventspace and its threads are be shut down
|
|
when the user closes the @scheme[graphical-read-eval-print-loop]
|
|
window. If an eventspace is provided, closing the window performs no
|
|
shut-down actions on eventspace.
|
|
|
|
When @scheme[redirect-ports?] is true, the following parameters are
|
|
initialized in the created eventspace's handler thread:
|
|
@itemize{
|
|
|
|
@item{@scheme[current-output-port] --- writes to the frame}
|
|
@item{@scheme[current-error-port] --- writes to the frame}
|
|
@item{@scheme[current-input-port] --- always returns @scheme[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
|
|
@scheme[current-text-keymap-initializer] parameter.
|
|
|
|
|
|
}
|
|
|
|
@defthing[the-clipboard (is-a?/c clipboard<%>)]{
|
|
|
|
See @scheme[clipboard<%>].
|
|
|
|
|
|
}
|
|
|
|
@defthing[the-x-selection-clipboard (is-a?/c clipboard<%>)]{
|
|
|
|
See @scheme[clipboard<%>].
|
|
|
|
|
|
}
|
|
|
|
@defproc[(get-window-text-extent [string string]
|
|
[font (is-a?/c font%)])
|
|
(values nonnegative-exact-integer?
|
|
nonnegative-exact-integer?)]{
|
|
|
|
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.
|
|
|
|
}
|
|
|
|
@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.
|
|
|
|
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)
|
|
(= 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])
|
|
any/c]{
|
|
|
|
Sends an AppleEvent or raises @scheme[exn:fail:unsupported].
|
|
|
|
The @scheme[receiver-bytes], @scheme[event-class-bytes], and
|
|
@scheme[event-id-bytes] arguments specify the signature of the
|
|
receiving application, the class of the AppleEvent, and the ID of
|
|
the AppleEvent.
|
|
|
|
The @scheme[direct-arg-v] value is converted (see below) and passed as
|
|
the main argument of the event; if @scheme[direct-argument-v] is
|
|
@|void-const|, no main argument is sent in the event. The
|
|
@scheme[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 MzScheme values can be converted to AppleEvent
|
|
values passed to the receiver:
|
|
|
|
@atable[
|
|
(tline @elem{@scheme[#t] or @scheme[#f]} @elem{Boolean})
|
|
(tline @elem{small integer} @elem{Long Integer})
|
|
(tline @elem{inexact real number} @elem{Double})
|
|
(tline @elem{string} @elem{Characters})
|
|
(tline @elem{list of convertible values} @elem{List of converted values})
|
|
(tline @scheme[#(file _pathname)] @elem{Alias (file exists) or FSSpec (does not exist)})
|
|
(tline @scheme[#(record (_typestring _v) ...)] @elem{Record of keyword-tagged values})
|
|
]
|
|
|
|
If other types of values are passed to @scheme[send-event] for
|
|
conversion, the @exnraise[exn:fail:unsupported].
|
|
|
|
The @scheme[send-event] procedure does not return until the receiver
|
|
of the AppleEvent replies. The result of @scheme[send-event] is the
|
|
reverse-converted reply value (see below), or the @exnraise[exn:fail]
|
|
if there is an error. If there is no error or return value,
|
|
@scheme[send-event] returns @|void-const|.
|
|
|
|
The following types of AppleEvent values can be reverse-converted into
|
|
a MzScheme value returned by @scheme[send-event]:
|
|
|
|
@atable[
|
|
(tline @elem{Boolean} @elem{@scheme[#t] or @scheme[#f]})
|
|
(tline @elem{Signed Integer} @elem{integer})
|
|
(tline @elem{Float, Double, or Extended} @elem{inexact real number})
|
|
(tline @elem{Characters} @elem{string})
|
|
(tline @elem{List of reverse-convertible values} @elem{list of reverse-converted values})
|
|
(tline @elem{Alias or FSSpec} @scheme[#(file _pathname)])
|
|
(tline @elem{Record of keyword-tagged values} @scheme[#(record (_typestring _v) ...)])
|
|
]
|
|
|
|
If the AppleEvent reply contains a value that cannot be
|
|
reverse-converted, the @exnraise[exn:fail].
|
|
|
|
}
|
|
|
|
@defproc[(make-namespace-with-mred [flag (one-of/c 'mred 'initial 'empty) 'mred])
|
|
namespace?]{
|
|
|
|
Like @scheme[make-namespace], but the @scheme[(lib "mred.ss"
|
|
"mred")] module of the current namespace is attached. In addition, by
|
|
default, the namespace is initialized by importing the @filepath{mred.ss}
|
|
module and MzLib's @indexed-file{class.ss} module into the
|
|
namespace's top-level environment.
|
|
|
|
|
|
The @scheme['initial] and @scheme['empty] flags control the namespace
|
|
creation in the same way as for @scheme[make-namespace], except that
|
|
the @filepath{mred.ss} module is attached to the created namespace (along
|
|
with the transitive closure of its imports). The @scheme['mred] flag
|
|
is like @scheme['initial], but also imports the @filepath{mred.ss} module
|
|
and MzLib's @indexed-file{class.ss} module into the namespace's
|
|
top-level environment.
|
|
|
|
}
|