launcher scribblings and other doc fixes
svn: r8469
This commit is contained in:
Matthew Flatt
parent
7ed3d17dba
commit
99818355f7
|
|
@ -1,187 +0,0 @@
|
|||
|
||||
The _launcher.ss_ library in the "launcher" collection provides the
|
||||
following procedures.
|
||||
|
||||
The _launcher-sig.ss_ library provides `launcher^', which includes
|
||||
the same procedures.
|
||||
|
||||
The _launcher-unit.ss_ library provides `launcher@', which imports
|
||||
`dynext:compile^' and `dynext:link^', and exports `launcher^'.
|
||||
|
||||
===== Launcher creation ========================================
|
||||
|
||||
> (make-mred-launcher args dest [aux]) - Creates the launcher
|
||||
`dest'. The `dest' executable (for the current OS platform) will
|
||||
start MrEd with the command-line arguments specified as strings in
|
||||
the list `args'. Extra arguments passed to the launcher at run-time
|
||||
will be appended (modulo special X flag handling, as described
|
||||
below) to this list and passed on to MrEd. If `dest' exists
|
||||
already (as a file or directory), it is replaced.
|
||||
|
||||
`make-mred-launcher' transforms `args' as necessary to avoid
|
||||
mutations caused by passing the strings through the
|
||||
platform-specific launching mechanism (e.g, as /bin/sh arguments),
|
||||
so the strings in `flags' arrive to MrEd intact.
|
||||
|
||||
The optional `aux' argument is an association list for
|
||||
platform-specific options (i.e., it is a list of pairs where the
|
||||
first element of the pair is a key symbol and the second element is
|
||||
the value for that key). See `create-embedding-executable' (from the
|
||||
"compiler" collection) for a list that applies to Windows launchers
|
||||
and Mac OS X MrEd launchers; the following additional associations
|
||||
apply to launchers:
|
||||
|
||||
_'independent?_ (Windows) - a boolean; #t creates an old-style
|
||||
launcher that is independent of the MzScheme or MrEd
|
||||
binary, like "Setup PLT.exe"; no other `aux'
|
||||
associations are used for an old-style launcher
|
||||
|
||||
-'exe-name_ (Mac OS X, MrEd 'script[-3m,-cgc] variant) - provides the
|
||||
base name for a '3m/'cgc variant launcher, which the
|
||||
script will call (ignoring `args'); if this name is not
|
||||
provided, the script will go through the MrEd executable
|
||||
|
||||
_'relative?_ (all) - a boolean, where #t means that the generate
|
||||
shell script should launch the executable through a
|
||||
relative path
|
||||
|
||||
See also `build-aux-from-path' below. The default `aux' is `null'.
|
||||
|
||||
For Unix/X, the script created by `make-mred-launcher' detects and
|
||||
handles X flags specially when they appear as the initial arguments
|
||||
to the script. Instead of appending these arguments to the end of
|
||||
`args', they are spliced in after any X Windows flags already
|
||||
listed listed in `args'. The remaining arguments (i.e., all script
|
||||
flags and arguments after the last X Windows flag or argument) are
|
||||
then appended after the spliced `args'.
|
||||
|
||||
For Mac OS Classic, the creation of launchers requires the
|
||||
(one-time) use of an extension, starter-setup.so. This extension
|
||||
is distributed with DrScheme bundles, and can also be built
|
||||
automatically from the source if necessary (and if the user has a
|
||||
copy of Codewarrior 5). The creation of launchers on 68k platforms
|
||||
is significantly more fragile than on PPC platforms. In
|
||||
particular, any launcher created on a 68k platform (or using a 68k
|
||||
binary) must be invoked at least once while that launcher is in the
|
||||
same folder as the MrEd copy it is to be linked to. Note also that
|
||||
once created, these launchers are bound in a truly tenacious way to
|
||||
MrEd; short of deleting MrEd entirely, it's nearly impossible to
|
||||
disconnect them.
|
||||
|
||||
> (make-mzscheme-launcher args dest [aux]) - Same as
|
||||
`make-mred-launcher', but for starting MzScheme. (No special Unix/X
|
||||
handling.)
|
||||
|
||||
|
||||
> (make-mred-program-launcher file collection dest) - Calls
|
||||
`make-mred-launcher' with arguments that start the MrEd program
|
||||
implemented by `collection': (list "-mvL-" file collection).
|
||||
The aux argument is generated by stripping the suffix from `file',
|
||||
adding it to the path of `collection', and passing the result to
|
||||
`build-aux-from-path'.
|
||||
|
||||
> (make-mzscheme-program-launcher file collection dest) - Calls
|
||||
`make-mzscheme-launcher' with arguments that start the MzScheme
|
||||
program implemented by `file' in `collection': (list "-mvL-" file
|
||||
collection). The aux argument is generated by stripping the suffix
|
||||
from `file', adding it to the path of `collection', and passing the
|
||||
result to `build-aux-from-path'.
|
||||
|
||||
|
||||
> (install-mred-program-launcher file collection name) - Calls
|
||||
`make-mred-launcher' with the destination returned by
|
||||
(mred-program-launcher-path name); the `file' and `collection'
|
||||
arguments are passed on to `make-mred-launcher'.
|
||||
|
||||
> (install-mzscheme-program-launcher file collection name) - Calls
|
||||
`make-mzscheme-launcher' with the destination returned by
|
||||
(mzscheme-program-launcher-path name); the `file' and `collection'
|
||||
arguments are passed on to `make-mzscheme-launcher'.
|
||||
|
||||
===== Launcher paths and platform conventions ============================
|
||||
|
||||
> (mred-program-launcher-path name) returns a pathname for an executable
|
||||
in the current PLT home directory called `name'. For Windows, the
|
||||
".exe" suffix is automatically appended to `name'. For Unix, `name'
|
||||
is changed to lowercase, whitespace is changed to `-', and the path
|
||||
includes the bin subdirectory of the PLT home directory. For Mac OS
|
||||
X, the ".app" suffix is appended to `name'.
|
||||
|
||||
> (mzscheme-program-launcher-path name) returns the same pathname as
|
||||
(mred-program-launcher-path name) for Unix, Windows, and Mac OS Classic.
|
||||
For Mac OS X, the result is the same as for Unix.
|
||||
|
||||
|
||||
> (mred-launcher-is-directory?) - Returns #t if MrEd launchers for the
|
||||
current platform are directories from the user's perspective.
|
||||
|
||||
> (mzscheme-launcher-is-directory?) - Returns #t if MzScheme launchers
|
||||
for the current platform are directories from the user's perspective.
|
||||
|
||||
|
||||
> (mred-launcher-is-actually-directory?) - Returns #t if MrEd
|
||||
launchers for the current platform are implemented as directories.
|
||||
|
||||
> (mzscheme-launcher-is-actually-directory?) - Returns #t if MzScheme
|
||||
launchers for the current platform are implemented as directories.
|
||||
|
||||
|
||||
> (mred-launcher-add-suffix path) - Returns a path with a suitable
|
||||
executable suffix added, if it's not present already.
|
||||
|
||||
> (mzscheme-launcher-add-suffix path) - Like
|
||||
`mred-launcher-add-suffix', but for MzScheme launchers.
|
||||
|
||||
|
||||
> (mred-launcher-put-file-extension+style+filters) - Returns three
|
||||
values suitable for use as the `extension', `style', and `filters'
|
||||
arguments to `put-file', respectively. If MrEd launchers for this
|
||||
platform are directories from the user perspective, the `style'
|
||||
result is suitable for use with `get-directory', and the `extension'
|
||||
result may be a string indicating a required extension for the
|
||||
directory name (e.g., "app" for Mac OS X).
|
||||
|
||||
> (mzscheme-launcher-put-file-extension+style+filters) - Like
|
||||
`mred-launcher-get-file-extension+style+filters', but for MzScheme
|
||||
launchers.
|
||||
|
||||
===== Miscellaneous ========================================
|
||||
|
||||
> (mred-launcher-up-to-date? dest [aux]) - Returns #t if the
|
||||
launcher `dest' does not need to be updated, assuming
|
||||
that `dest' is a launcher and its arguments have not changed.
|
||||
|
||||
> (mzscheme-launcher-up-to-date? dest [aux]) - Analogous to
|
||||
`mred-launcher-up-to-date?'.
|
||||
|
||||
|
||||
> (build-aux-from-path path) - Creates an `aux' association list
|
||||
by a suffix to the path, such as ".icns", and checking whether
|
||||
such a file exists. The recognized suffixes are as follows:
|
||||
|
||||
* .icns => 'icns file
|
||||
* .ico => 'ico file
|
||||
* .lch => 'independent? as #t (file content is ignored)
|
||||
* .creator => 'creator as initial 4-characters in the file
|
||||
* .filetypes => 'file-types as read content (a single S-expr),
|
||||
and 'resource-files as a list constructed by
|
||||
finding "CFBundleTypeIconFile" entries in
|
||||
'file-types
|
||||
|
||||
> (current-launcher-variant [symbol]) - Gets or sets a symbol
|
||||
parameter that indicates a variant of MzScheme or MrEd to use for
|
||||
launcher creation and for generating launcher names. The default is
|
||||
the result of `(system-type 'gc)'. For Unix platforms, the
|
||||
possibilities are 'cgc and '3m. For Mac OS X, the 'script-3m and
|
||||
'script-cgc variants are also available for MrEd.
|
||||
|
||||
> (available-mred-variants) - Returns a list of symbols corresponding
|
||||
to available variants of MrEd. The list normally includes at least
|
||||
one of '3m or 'cgc --- whichever is the result of `(system-type
|
||||
'gc)' --- and may include the other, as well as 'script-3m and/or
|
||||
'script-cgc under Mac OS X.
|
||||
|
||||
> (available-mzscheme-variants) - Returns a list of symbols
|
||||
corresponding to available variants of MrEd. The list normally
|
||||
includes at least one of '3m or 'cgc --- whichever is the result of
|
||||
`(system-type 'gc)' --- and may include the other.
|
||||
|
|
@ -1,6 +1,5 @@
|
|||
(module info setup/infotab
|
||||
(define name "Launcher")
|
||||
(define doc.txt "doc.txt")
|
||||
(define blurb
|
||||
(list "Lets you run your program as a stand-alone program, "
|
||||
"with out starting up DrScheme first."))
|
||||
|
|
|
|||
|
|
@ -4,8 +4,6 @@
|
|||
(require scheme/path
|
||||
scheme/file
|
||||
|
||||
(lib "compile-sig.ss" "dynext")
|
||||
(lib "link-sig.ss" "dynext")
|
||||
(lib "embed.ss" "compiler")
|
||||
(lib "dirs.ss" "setup")
|
||||
(lib "variant.ss" "setup")
|
||||
|
|
@ -14,8 +12,7 @@
|
|||
|
||||
(lib "winutf16.ss" "compiler" "private"))
|
||||
|
||||
(import (prefix c: dynext:compile^)
|
||||
(prefix l: dynext:link^))
|
||||
(import)
|
||||
(export launcher^)
|
||||
|
||||
(define current-launcher-variant
|
||||
|
|
@ -588,14 +585,14 @@
|
|||
(cons 'resource-files icon-files))))))))))))))
|
||||
|
||||
(define (make-mred-program-launcher file collection dest)
|
||||
(make-mred-launcher (list "-mqvL" file collection "--")
|
||||
(make-mred-launcher (list "-l-" (string-append collection "/" file))
|
||||
dest
|
||||
(build-aux-from-path
|
||||
(build-path (collection-path collection)
|
||||
(strip-suffix file)))))
|
||||
|
||||
(define (make-mzscheme-program-launcher file collection dest)
|
||||
(make-mzscheme-launcher (list "-mqvL" file collection "--")
|
||||
(make-mzscheme-launcher (list "-l-" (string-append collection "/" file))
|
||||
dest
|
||||
(build-aux-from-path
|
||||
(build-path (collection-path collection)
|
||||
|
|
|
|||
|
|
@ -2,11 +2,6 @@
|
|||
(module launcher mzscheme
|
||||
(require (lib "unit.ss"))
|
||||
|
||||
(require (lib "compile-sig.ss" "dynext")
|
||||
(lib "compile.ss" "dynext")
|
||||
(lib "link-sig.ss" "dynext")
|
||||
(lib "link.ss" "dynext"))
|
||||
|
||||
(require "launcher-sig.ss"
|
||||
"launcher-unit.ss")
|
||||
|
||||
|
|
|
|||
|
|
@ -334,9 +334,9 @@
|
|||
(div ((class "maincolumn"))
|
||||
(div ((class "main"))
|
||||
,@(render-version d ri)
|
||||
,@(navigation d ri)
|
||||
,@(navigation d ri #f)
|
||||
,@(render-part d ri)
|
||||
,@(navigation d ri)))))])
|
||||
,@(navigation d ri #t)))))])
|
||||
(unless css-path
|
||||
(install-file scribble-css))
|
||||
(printf "<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.0 Transitional//EN\" \"http://www.w3.org/TR/html4/loose.dtd\">\n")
|
||||
|
|
@ -370,7 +370,7 @@
|
|||
|
||||
(define/public (derive-filename d) "bad.html")
|
||||
|
||||
(define/private (navigation d ri)
|
||||
(define/private (navigation d ri pre-space?)
|
||||
(let ([parent (part-parent d ri)])
|
||||
(let*-values ([(prev next) (find-siblings d ri)]
|
||||
[(prev) (if prev
|
||||
|
|
@ -408,7 +408,8 @@
|
|||
(not index)
|
||||
(not up-path))
|
||||
null
|
||||
`((div ([class "navleft"])
|
||||
`(,@(if pre-space? '((p nbsp)) null)
|
||||
(div ([class "navleft"])
|
||||
,@(render-content
|
||||
(append
|
||||
(list
|
||||
|
|
|
|||
|
|
@ -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].}
|
||||
|
||||
|
|
|
|||
|
|
@ -345,11 +345,12 @@ Mac OS X when @scheme[mred?] is @scheme[#t], @scheme[#f] otherwise.}
|
|||
|
||||
Returns three values suitable for use as the @scheme[extension],
|
||||
@scheme[style], and @scheme[filters] arguments to @scheme[put-file],
|
||||
respectively. If MzScheme/MrEd launchers for this platform are
|
||||
directories, the @scheme[style] result is suitable for use with
|
||||
@scheme[get-directory], and the @scheme[extension] result may be a
|
||||
string indicating a required extension for the directory name (e.g.,
|
||||
@scheme["app"] for Mac OS X). }
|
||||
respectively.
|
||||
|
||||
If MzScheme/MrEd launchers for the current platform were directories
|
||||
form the user's perspective, the @scheme[style] result is suitable for
|
||||
use with @scheme[get-directory], and the @scheme[extension] result may
|
||||
be a string indicating a required extension for the directory name. }
|
||||
|
||||
|
||||
@defproc[(embedding-executable-add-suffix [path path-string?] [mred? any/c])
|
||||
|
|
|
|||
310
collects/scribblings/mzc/launcher.scrbl
Normal file
310
collects/scribblings/mzc/launcher.scrbl
Normal file
|
|
@ -0,0 +1,310 @@
|
|||
#lang scribble/doc
|
||||
@(require scribble/manual
|
||||
"common.ss"
|
||||
(for-label scheme/base
|
||||
scheme/unit
|
||||
scheme/contract
|
||||
launcher/launcher
|
||||
launcher/launcher-sig
|
||||
launcher/launcher-unit
|
||||
compiler/embed
|
||||
scheme/gui/base))
|
||||
|
||||
@title[#:tag "launcher"]{Installation-Specific Launchers for Scheme Code}
|
||||
|
||||
@defmodule[launcher/launcher]
|
||||
|
||||
The @schememodname[launcher/launcher] library provides functions for
|
||||
creating @defterm{launchers}, which are similar to stand-alone
|
||||
executables, but sometimes smaller because they depend permanently on
|
||||
the local PLT Scheme installation. In the case of Unix, in particular,
|
||||
a launcher is simply a shell script. The @|mzc| tool provides no
|
||||
direct support for creating launchers.
|
||||
|
||||
@section{Creating Launchers}
|
||||
|
||||
@defproc[(make-mred-launcher [args (listof string?)]
|
||||
[dest path-string?]
|
||||
[aux (listof (cons/c symbol? any/c)) null])
|
||||
void?]{
|
||||
|
||||
Creates the launcher @scheme[dest], which starts MrEd with the
|
||||
command-line arguments specified as strings in @scheme[args]. Extra
|
||||
arguments passed to the launcher at run-time are be appended (modulo
|
||||
special Unix/X flag handling, as described below) to this list and
|
||||
passed on to MrEd. If @scheme[dest] exists already, as either a file
|
||||
or directory, it is replaced.
|
||||
|
||||
The optional @scheme[aux] argument is an association list for
|
||||
platform-specific options (i.e., it is a list of pairs where the first
|
||||
element of the pair is a key symbol and the second element is the
|
||||
value for that key). See @scheme[create-embedding-executable] for a
|
||||
list that applies to both stand-alone executables and launchers under
|
||||
Windows and Mac OS X MrEd; the following additional associations apply
|
||||
to launchers:
|
||||
|
||||
@itemize{
|
||||
|
||||
@item{@scheme['independent?] (Windows) --- a boolean; @scheme[#t]
|
||||
creates an old-style launcher that is independent of the
|
||||
MzScheme or MrEd binary, like @exec{setup-plt.exe}. No other
|
||||
@scheme[aux] associations are used for an old-style launcher.}
|
||||
|
||||
@item{@scheme['exe-name] (Mac OS X, @scheme['script-3m] or
|
||||
@scheme['script-cgc] variant) --- provides the base name for a
|
||||
@scheme['3m]-/@scheme['cgc]-variant launcher, which the script
|
||||
will call ignoring @scheme[args]. If this name is not provided,
|
||||
the script will goes through the MrEd executable as usual.}
|
||||
|
||||
@item{@scheme['relative?] (all platforms) --- a boolean, where
|
||||
@scheme[#t] means that the generated launcher should find the
|
||||
base MrEd executable through a relative path.}
|
||||
|
||||
}
|
||||
|
||||
See also @scheme[build-aux-from-path].
|
||||
|
||||
For Unix/X, the script created by @scheme[make-mred-launcher] detects
|
||||
and handles X Windows flags specially when they appear as the initial
|
||||
arguments to the script. Instead of appending these arguments to the
|
||||
end of @scheme[args], they are spliced in after any X Windows flags
|
||||
already listed listed in @scheme[args]. The remaining arguments (i.e.,
|
||||
all script flags and arguments after the last X Windows flag or
|
||||
argument) are then appended after the spliced @scheme[args].}
|
||||
|
||||
|
||||
@defproc[(make-mzscheme-launcher [args (listof string?)]
|
||||
[dest path-string?]
|
||||
[aux (listof (cons/c symbol? any/c)) null])
|
||||
void?]{
|
||||
|
||||
Like @scheme[make-mred-launcher], but for starting MzScheme. Under Mac
|
||||
OS X, the @scheme['exe-name] @scheme[aux] association is ignored.}
|
||||
|
||||
|
||||
@defproc[(make-mred-program-launcher [file string?]
|
||||
[collection string?]
|
||||
[dest path-string?])
|
||||
void?]{
|
||||
|
||||
Calls @scheme[make-mred-launcher] with arguments that start the MrEd
|
||||
program implemented by @scheme[file] in @scheme[collection]:
|
||||
@scheme[(list "-l-" (string-append collection "/" file))]. The
|
||||
@scheme[_aux] argument to @scheme[make-mred-launcher] is generated by
|
||||
stripping the suffix (if any) from @scheme[file], adding it to the
|
||||
path of @scheme[collection], and passing the result to
|
||||
@scheme[build-aux-from-path].}
|
||||
|
||||
|
||||
@defproc[(make-mzscheme-program-launcher [file string?]
|
||||
[collection string?]
|
||||
[dest path-string?])
|
||||
void?]{
|
||||
|
||||
Like @scheme[make-mred-program-launcher], but for
|
||||
@scheme[make-mzscheme-launcher].}
|
||||
|
||||
|
||||
@defproc[(install-mred-program-launcher [file string?]
|
||||
[collection string?]
|
||||
[name string?])
|
||||
void?]{
|
||||
|
||||
Same as
|
||||
|
||||
@schemeblock[
|
||||
(make-mred-program-launcher
|
||||
file collection
|
||||
(mred-program-launcher-path name))
|
||||
]}
|
||||
|
||||
@defproc[(install-mzscheme-program-launcher [file string?]
|
||||
[collection string?]
|
||||
[name string?])
|
||||
void?]{
|
||||
|
||||
Same as
|
||||
|
||||
@schemeblock[
|
||||
(make-mzscheme-program-launcher
|
||||
file collection
|
||||
(mzscheme-program-launcher-path name))
|
||||
]}
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
|
||||
@section{Launcher Path and Platform Conventions}
|
||||
|
||||
@defproc[(mred-program-launcher-path [name string?]) path?]{
|
||||
|
||||
Returns a pathname for an executable in the PLT Scheme installation
|
||||
called something like @scheme[name]. For Windows, the @filepath{.exe}
|
||||
suffix is automatically appended to @scheme[name]. For Unix,
|
||||
@scheme[name] is changed to lowercase, whitespace is changed to
|
||||
@litchar{-}, and the path includes the @filepath{bin} subdirectory of
|
||||
the PLT Scheme installation. For Mac OS X, the @filepath{.app} suffix
|
||||
is appended to @scheme[name].}
|
||||
|
||||
|
||||
@defproc[(mzscheme-program-launcher-path [name string?]) path?]{
|
||||
|
||||
Returns the same path as @scheme[(mred-program-launcher-path name)]
|
||||
for Unix and Windows. For Mac OS X, the result is the same as for
|
||||
Unix.}
|
||||
|
||||
|
||||
@defproc[(mred-launcher-is-directory?) boolean?]{
|
||||
|
||||
Returns @scheme[#t] if MrEd launchers for the current platform are
|
||||
directories from the user's perspective. For all currently supported
|
||||
platforms, the result is @scheme[#f].}
|
||||
|
||||
|
||||
@defproc[(mzscheme-launcher-is-directory?) boolean?]{
|
||||
|
||||
Like @scheme[mred-launcher-is-directory?], but for MzScheme
|
||||
launchers.}
|
||||
|
||||
|
||||
@defproc[(mred-launcher-is-actually-directory?) boolean?]{
|
||||
|
||||
Returns @scheme[#t] if MrEd launchers for the current platform are
|
||||
implemented as directories from the filesystem's perspective. The
|
||||
result is @scheme[#t] for Mac OS X, @scheme[#f] for all other
|
||||
platforms.}
|
||||
|
||||
|
||||
@defproc[(mzscheme-launcher-is-actually-directory?) boolean?]{
|
||||
|
||||
Like @scheme[mred-launcher-is-actuall-directory?], but for MzScheme
|
||||
launchers. The result is @scheme[#f] for all platforms.}
|
||||
|
||||
|
||||
@defproc[(mred-launcher-add-suffix [path-string? path]) path?]{
|
||||
|
||||
Returns a path with a suitable executable suffix added, if it's not
|
||||
present already.}
|
||||
|
||||
@defproc[(mzscheme-launcher-add-suffix [path-string? path]) path?]{
|
||||
|
||||
Like @scheme[mred-launcher-add-suffix], but for MzScheme launchers.}
|
||||
|
||||
|
||||
@defproc[(mred-launcher-put-file-extension+style+filters)
|
||||
(values (or/c string? false/c)
|
||||
(listof (one-of/c 'packages 'enter-packages))
|
||||
(listof (list/c string? string?)))]{
|
||||
|
||||
Returns three values suitable for use as the @scheme[extension],
|
||||
@scheme[style], and @scheme[filters] arguments to @scheme[put-file],
|
||||
respectively.
|
||||
|
||||
If MrEd launchers for the current platform were directories form the
|
||||
user's perspective, the @scheme[style] result is suitable for use with
|
||||
@scheme[get-directory], and the @scheme[extension] result may be a
|
||||
string indicating a required extension for the directory name. }
|
||||
|
||||
|
||||
@defproc[(mzscheme-launcher-put-file-extension+style+filters)
|
||||
(values (or/c string? false/c)
|
||||
(listof (one-of/c 'packages 'enter-packages))
|
||||
(listof (list/c string? string?)))]{
|
||||
|
||||
Like @scheme[mred-launcher-get-file-extension+style+filters], but for
|
||||
MzScheme launchers.}
|
||||
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
|
||||
@section{Launcher Configuration}
|
||||
|
||||
@defproc[(mred-launcher-up-to-date? [dest path-string?]
|
||||
[aux (listof (cons/c symbol? any/c))])
|
||||
boolean?]{
|
||||
|
||||
Returns @scheme[#t] if the MrEd launcher @scheme[dest] does not need
|
||||
to be updated, assuming that @scheme[dest] is a launcher and its
|
||||
arguments have not changed.}
|
||||
|
||||
@defproc[(mzscheme-launcher-up-to-date? [dest path-string?]
|
||||
[aux (listof (cons/c symbol? any/c))])
|
||||
boolean?]{
|
||||
|
||||
Analogous to @scheme[mred-launcher-up-to-date?], but for a MzScheme
|
||||
launcher.}
|
||||
|
||||
@defproc[(build-aux-from-path [path path-string?])
|
||||
(listof (cons/c symbol? any/c))]{
|
||||
|
||||
Creates an association list suitable for use with
|
||||
@scheme[make-mred-launcher] or @scheme[create-embedding-executable].
|
||||
It builds associations by adding to @scheme[path] suffixes, such as
|
||||
@filepath{.icns}, and checking whether such a file exists.
|
||||
|
||||
The recognized suffixes are as follows:
|
||||
|
||||
@itemize{
|
||||
|
||||
@item{@filepath{.icns} @'rarr @scheme['icns] file for use under Mac
|
||||
OS X}
|
||||
|
||||
@item{@filepath{.ico} @'rarr @scheme['ico] file for use under
|
||||
Windows}
|
||||
|
||||
@item{@filepath{.lch} @'rarr @scheme['independent?] as @scheme[#t]
|
||||
(the file content is ignored) for use under Windows}
|
||||
|
||||
@item{@filepath{.creator} @'rarr @scheme['creator] as the initial
|
||||
four characters in the file for use under Mac OS X}
|
||||
|
||||
@item{@filepath{.filetypes} @'rarr @scheme['file-types] as
|
||||
@scheme[read] content (a single S-expression), and
|
||||
@scheme['resource-files] as a list constructed by finding
|
||||
@scheme["CFBundleTypeIconFile"] entries in
|
||||
@scheme['file-types]; for use under Mac OS X}
|
||||
|
||||
}}
|
||||
|
||||
@defparam[current-launcher-variant variant symbol?]{
|
||||
|
||||
A parameter that indicates a variant of MzScheme or MrEd to use for
|
||||
launcher creation and for generating launcher names. The default is
|
||||
the result of @scheme[(system-type 'gc)]. Under Unix and Windows, the
|
||||
possibilities are @scheme['cgc] and @scheme['3m]. Under Mac OS X, the
|
||||
@scheme['script-3m] and @scheme['script-cgc] variants are also
|
||||
available for MrEd launchers.}
|
||||
|
||||
@defproc[(available-mred-variants) (listof symbol?)]{
|
||||
|
||||
Returns a list of symbols corresponding to available variants of MrEd
|
||||
in the current PLT Scheme installation. The list normally includes at
|
||||
least one of @scheme['3m] or @scheme['cgc]--- whichever is the result
|
||||
of @scheme[(system-type 'gc)]---and may include the other, as well as
|
||||
@scheme['script-3m] and/or @scheme['script-cgc] under Mac OS X.}
|
||||
|
||||
@defproc[(available-mzscheme-variants) (listof symbol?)]{
|
||||
|
||||
Returns a list of symbols corresponding to available variants of
|
||||
MzScheme in the current PLT Scheme installation. The list normally
|
||||
includes at least one of @scheme['3m] or @scheme['cgc]---whichever is
|
||||
the result of @scheme[(system-type 'gc)]---and may include the other.}
|
||||
|
||||
@; ----------------------------------------
|
||||
|
||||
@section{Launcher Creation Signature}
|
||||
|
||||
@defmodule[launcher/launcher-sig]
|
||||
|
||||
@defsignature/splice[launcher^ ()]{
|
||||
|
||||
Includes the identifiers provided by @schememodname[launcher/launcher].}
|
||||
|
||||
@; ----------------------------------------
|
||||
|
||||
@section{Launcher Creation Unit}
|
||||
|
||||
@defmodule[launcher/launcher-unit]
|
||||
|
||||
@defthing[launcher@ unit?]{
|
||||
|
||||
A unit that imports nothing and exports @scheme[launcher^].}
|
||||
|
|
@ -15,3 +15,4 @@ machines.
|
|||
|
||||
@include-section["exe.scrbl"]
|
||||
@include-section["dist.scrbl"]
|
||||
@include-section["launcher.scrbl"]
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user