diff --git a/collects/launcher/doc.txt b/collects/launcher/doc.txt deleted file mode 100644 index 1d576cfaac..0000000000 --- a/collects/launcher/doc.txt +++ /dev/null @@ -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. diff --git a/collects/launcher/info.ss b/collects/launcher/info.ss index a1cff00eef..726c34eab3 100644 --- a/collects/launcher/info.ss +++ b/collects/launcher/info.ss @@ -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.")) diff --git a/collects/launcher/launcher-unit.ss b/collects/launcher/launcher-unit.ss index 72bbfbd98a..b0c361ce74 100644 --- a/collects/launcher/launcher-unit.ss +++ b/collects/launcher/launcher-unit.ss @@ -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) diff --git a/collects/launcher/launcher.ss b/collects/launcher/launcher.ss index 901b0488c5..fa8c066426 100644 --- a/collects/launcher/launcher.ss +++ b/collects/launcher/launcher.ss @@ -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") diff --git a/collects/scribble/html-render.ss b/collects/scribble/html-render.ss index a5313be720..c7ff729ca1 100644 --- a/collects/scribble/html-render.ss +++ b/collects/scribble/html-render.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 "\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 diff --git a/collects/scribblings/gui/miscwin-funcs.scrbl b/collects/scribblings/gui/miscwin-funcs.scrbl index c61aaeb466..4747eb3be7 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].} + diff --git a/collects/scribblings/mzc/exe-api.scrbl b/collects/scribblings/mzc/exe-api.scrbl index 28966eaf17..808efe58fd 100644 --- a/collects/scribblings/mzc/exe-api.scrbl +++ b/collects/scribblings/mzc/exe-api.scrbl @@ -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]) diff --git a/collects/scribblings/mzc/launcher.scrbl b/collects/scribblings/mzc/launcher.scrbl new file mode 100644 index 0000000000..8d4ca375b9 --- /dev/null +++ b/collects/scribblings/mzc/launcher.scrbl @@ -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^].} diff --git a/collects/scribblings/mzc/sa.scrbl b/collects/scribblings/mzc/sa.scrbl index bd60b08f8f..790e114487 100644 --- a/collects/scribblings/mzc/sa.scrbl +++ b/collects/scribblings/mzc/sa.scrbl @@ -15,3 +15,4 @@ machines. @include-section["exe.scrbl"] @include-section["dist.scrbl"] +@include-section["launcher.scrbl"]