#lang scribble/doc @(require "common.ss" 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[(begin-busy-cursor) void?]{ Changes the cursor to a watch cursor for all windows in the current eventspace. Use @racket[end-busy-cursor] to revert the cursor back to its previous state. Calls to @racket[begin-busy-cursor] and @racket[end-busy-cursor] can be nested arbitrarily. The cursor installed by @racket[begin-busy-cursor] overrides any window-specific cursors installed with @method[window<%> set-cursor]. See also @racket[is-busy?]. } @defproc[(bell) void?]{ Rings the system bell. } @defproc[(end-busy-cursor) void?]{ See @racket[begin-busy-cursor]. } @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 @racket[#"????"] and @racket[#"????"] 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 'x-display)]) (or/c path? #f)]{ Finds a platform-specific (and possibly user- or machine-specific) standard filename or directory. See also @racket[find-system-path]. The result depends on @racket[what], and a @racket[#f] result is only possible when @racket[what] is @racket['x-display]: @itemize[ @item{@racket['init-file] returns the ,path to the user-specific initialization file (containing Racket code). The directory part of the path is the same path as returned for @racket['init-dir] by Racket's @racket[find-system-path]. The file name is platform-specific: @itemize[ @item{@|AllUnix|: @indexed-file{.gracketrc}} @item{Windows: @indexed-file{gracketrc.rktl}} ]} @item{@racket['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 GRacket starts under X. For other platforms, or when neither @Flag{display} nor @envvar{DISPLAY} was specified, the result is @racket[#f].} ] } @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 @racket['(ctl)]. Under Mac OS X, the default is @racket['(cmd)]. Under X, the default is normally @racket['(ctl)], but the default can be changed through the @Resource{defaultMenuPrefix} low-level preference (see @|mrprefsdiscuss|).} @defproc[(get-panel-background) (is-a?/c color%)]{ Returns a shade of gray. Historically, the result matched the color of a @racket[panel%] background, but @racket[panel%] backgrounds can vary on some platforms (e.g., when nested in a @racket[group-box-panel%]), so the result is no longer guaranteed to be related to a @racket[panel%]'s color. } @defproc[(get-highlight-background-color) (is-a?/c color%)]{ Returns the color that is drawn behind selected text.} @defproc[(get-highlight-text-color) (or/c (is-a?/c color%) #f)]{ Returns the color that is used to draw selected text or @racket[#f] if selected text is drawn with its usual color.} @defproc[(get-window-text-extent [string string] [font (is-a?/c font%)] [combine? any/c #f]) (values exact-nonnegative-integer? exact-nonnegative-integer?)]{ Returns the pixel size of a string drawn as a window's label or value when drawn with the given font. The optional @racket[combine?] argument is as for @xmethod[dc<%> get-text-extent]. See also @xmethod[dc<%> get-text-extent]. } @defproc[(graphical-read-eval-print-loop [eval-eventspace eventspace #f] [redirect-ports? any/c (not eval-eventspace)]) void?]{ Similar to @racket[read-eval-print-loop], except that none of @racket[read-eval-print-loop]'s configuration parameters are used (such as @racket[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 @racket[graphical-read-eval-print-loop] window (i.e., the current eventspace when @racket[graphical-read-eval-print-loop] is called). If no eventspace is provided, or if @racket[#f] is provided, an evaluation eventspace is created using @racket[(make-eventspace)] with a new custodian; the eventspace and its threads are be shut down when the user closes the @racket[graphical-read-eval-print-loop] window. If an eventspace is provided, closing the window performs no shut-down actions on eventspace. When @racket[redirect-ports?] is true, the following parameters are initialized in the created eventspace's handler thread: @itemize[ @item{@racket[current-output-port] --- writes to the frame} @item{@racket[current-error-port] --- writes to the frame} @item{@racket[current-input-port] --- always returns @racket[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 @racket[current-text-keymap-initializer] parameter. } @defproc[(textual-read-eval-print-loop) void?]{ Similar to @racket[read-eval-print-loop], except that evaluation uses a newly created eventspace like @racket[graphical-read-eval-print-loop]. The @racket[current-prompt-read] parameter is used in the current thread to read input. The result is queued for evaluation and printing in the created eventspace's @tech{handler thread}, which uses @racket[current-eval] and @racket[current-print]. After printing completes for an interaction result, the next expression in read in the original thread, and so on. If an @racket[exn:break] exception is raised in the original thread during reading, it aborts the current call to @racket[(current-read)] and a new one is started. If an @racket[exn:break] exception is raised in the original thread while waiting for an interaction to complete, a break is sent (via @racket[break-thread]) to the created eventspace's @tech{handler thread}.} @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[(is-busy?) boolean?]{ Returns @racket[#t] if a busy cursor has been installed with @racket[begin-busy-cursor] and not removed with @racket[end-busy-cursor]. } @defproc[(label->plain-label [label string]) string?]{ Strips shortcut ampersands from @racket[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[(make-gl-bitmap [width exact-positive-integer?] [height exact-positive-integer?] [config (is-a?/c gl-config%)]) (is-a/c? bitmap%)]{ Creates a bitmap that supports both normal @racket[dc<%>] drawing an OpenGL drawing through a context returned by @xmethod[dc<%> get-gl-context]. For @racket[dc<%>] drawing, an OpenGL-supporting bitmap draws like a bitmap frmo @racket[make-screen-bitmap] on some platforms, while it draws like a bitmap instantiated directly from @racket[bitmap%] on other platforms.} @defproc[(make-gui-empty-namespace) namespace?]{ Like @racket[make-base-empty-namespace], but with @racketmodname[racket/class] and @racketmodname[racket/gui/base] also attached to the result namespace.} @defproc[(make-gui-namespace) namespace?]{ Like @racket[make-base-namespace], but with @racketmodname[racket/class] and @racketmodname[racket/gui/base] also required into the top-level environment of the result namespace.} @defproc[(make-screen-bitmap [width exact-positive-integer?] [height exact-positive-integer?]) (is-a/c? bitmap%)]{ Creates a bitmap that draws in a way that is the same as drawing to a canvas in its default configuration. A normal @racket[bitmap%] draws in a more platform-independent way and may use fewer constrained resources, particularly under Windows.} @defproc[(play-sound [filename path-string?] [async? any/c]) boolean?]{ Plays a sound file. If @racket[async?] is false, the function does not return until the sound completes. Otherwise, it returns immediately. The result is @racket[#t] if the sound plays successfully, @racket[#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[(register-collecting-blit [canvas (is-a?/c canvas%)] [x real?] [y real?] [w (and/c real? (not/c negative?))] [h (and/c real? (not/c negative?))] [on (is-a?/c bitmap%)] [off (is-a?/c bitmap%)] [on-x real? 0] [on-y real? 0] [off-x real? 0] [off-y real? 0]) void?]{ Registers a ``blit'' to occur when garbage collection starts and ends. When garbage collection starts, @racket[on] is drawn at location @racket[x] and @racket[y] within @racket[canvas], if @racket[canvas] is shown. When garbage collection ends, the drawing is reverted, possibly by drawing the @racket[off] bitmap. The background behind @racket[on] is unspecified, so @racket[on] should be a solid image, and the canvas's scale or scrolling is not applied to the drawing. Only the portion of @racket[on] within @racket[w] and @racket[h] pixels is used; if @racket[on-x] and @racket[on-y] are specified, they specify an offset within the bitmap that is used for drawing, and @racket[off-x] and @racket[off-y] similarly specify an offset within @racket[off]. The blit is automatically unregistered if @scheme[canvas] becomes invisible and inaccessible. Multiple registrations can be installed for the same @scheme[canvas]. See also @scheme[unregister-collecting-blit].} @defproc[(unregister-collecting-blit [canvas (is-a?/c canvas%)]) void?]{ Unregisters all blit requests installed for @racket[canvas] with @scheme[register-collecting-blit].} @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 (@racket[x], @racket[y]) in global coordinates. If a window is there, this function calls the window's @method[top-level-window<%> on-message] method, providing @racket[message] as the method's argument; the result of the function call is the result returned by the method. If no Racket window is at the given coordinates, or if it is covered by a non-Racket window at (@racket[x], @racket[y]), @racket[#f] is returned. } @defproc[(system-position-ok-before-cancel?) boolean?]{ Returns @racket[#t] under Windows---indicating that a dialog with @onscreen{OK} and @onscreen{Cancel} buttons should place the @onscreen{OK} button on to left of the @onscreen{Cancel} button---and returns @racket[#f] under Mac OS X and X.} @defthing[the-clipboard (is-a?/c clipboard<%>)]{ See @racket[clipboard<%>]. } @defthing[the-x-selection-clipboard (is-a?/c clipboard<%>)]{ See @racket[clipboard<%>]. } @defproc[(label-string? [v any/c]) boolean?]{ Returns @racket[#t] if @racket[v] is a string whose length is less than or equal to @racket[200]. This predicate is typically used as the contract for strings that appear in GUI objects. In some cases, such as the label in a @racket[button%] or @racket[menu-item%] object, the character @litchar{&} is treated specially to indicate that the following character is used in keyboard navigation. See @xmethod[labelled-menu-item<%> set-label] for one such example. In other cases, such as the label on a @racket[frame%], @litchar{&} is not treated specially. } @defproc[(key-code-symbol? [v any/c]) boolean?]{ Returns @racket[#t] if the argument is a symbol that can be returned by @racket[@key-event%]'s method @method[key-event% get-key-code]. }