with-message-window

Arguments: (string-or-pixmap &key (owner (quote (screen *system*))) width height (horizontal-margin 24) (vertical-margin 24) (background-color (quote yellow)) (foreground-color (quote black)) (font (make-font-ex nil "Arial" 20 (quote (:bold)))) (border :black) class) &body body

This is a convenience utility macro that displays a simple message window while some activity is taking place, typically to tell the user to wait until the activity has finished. Unlike a modal dialog (see pop-up-modal-dialog and pop-up-message-dialog), the message window does not wait for the user to interactively respond to the message before proceeding. Instead, it simply displays the message window, then proceeds to run the macro body, and finally removes the message window automatically when the body has completed. It returns whatever the body returns. (Such a window is useful when a progam is performing an action that may take a user-noticeable amount of time.)

The required string-or-pixmap is either a string or a pixmap to display in the message box. A non-null value for this argument must be supplied.

The keyword arguments are:

• owner is the window or screen on which to display the message box. The message box will be centered within this owner. The default is value is the screen.
• width is either an integer specifying the pixel width of the message window, or else nil to default to a particular portion of the owner's width. The default value is nil. If the first argument is a pixmap rather than a string, then the width argument is ignored and the window width will instead be the width of the pixmap plus the specified horizontal margins.
• height is either an integer specifying the pixel height of the message window, or else nil to default to whatever height is necessary to contain the message string or pixmap, given the window's width, margins, and font that are determined beforehand. If the first argument is a pixmap rather than a string, then the height argument is ignored and the window height will instead be the height of the pixmap plus the specified vertical margins.
• horizontal-margin is the pixel width of blank space to leave between the left and right borders of the message window and the text or pixmap inside. The default is 24.
• vertical-margin is the pixel height of blank space to leave between the top and bottom borders of the message window and the text or pixmap inside. The default is 24.
• background-color is the color of the background of the message window. It is either an RGB color object (see make-rgb) or else nil to default to the system-background-color. The default is the value of the constant yellow.
• foreground-color is the color of the string that is drawn in the message window (unless a pixmap is specified instead). It is either an RGB color object (see make-rgb) or else nil to default to the system-foreground-color. The default is the value of the constant black.
• font is the font in which to draw the string (unless a pixmap is specified instead), or else nil to default to the font returned by proportional-font. The default is the relatively large font returned by (make-font-ex nil "Arial" 20 '(:bold)) (see make-font).
• border is the type of border that the message window will have. The default is :black to draw a thin border. See the border property of windows for other valid values.
• class is the name of the window class to use for the message window. If nil or unspecified, it defaults to message-window. To change the appearance of the window, an application could define a subclass of message-window with default-initargs for various properties, and then pass the name of that subclass to with-message-window.

with-message-window calls the function make-message-window to make the actual window. If you would like to display the message window at some time other than during the execution of a macro body, then you could call that function directly instead.

GTK note: on GTK platforms (Linux and Mac), the message window will no longer be there after selecting another application and then returning to this one (even when the code is still inside the macro body), due to X11 limitations. Typically it may be prudent to also display the message in a status bar, where it can still be seen in this case.

Here is a complete example for with-message-window. A window is displayed and lines are drawn in it. A message window is also displayed asking the user to wait while the lines are drawn. The drawing is slowed by calls to sleep (in order for the example to show the message window for a noticeable time).

(with-positions (first-position previous-position next-position)
  (let* ((width 300)(height 400)
         (dx 3)(dy 4)(resolution 8)
         (frame (make-window :frame
                  :class 'bitmap-window
                  :title "My Main Window"
                  :interior (make-box-relative 100 100 width height)))
         (pane (frame-child frame)))
    (nmake-position first-position (round width 2) height)
    (ncopy-position previous-position first-position)
    (with-message-window
        ("Please wait while this application draws a bunch of lines."
         :owner frame
         :width 200
         :font (make-font-ex nil "Arial" 17)
         :background-color green)
      (flet ((draw-mirrored-line
              (stream pos1 pos2 width)
              (with-positions (mpos1 mpos2)
                (draw-line stream pos1 pos2)
                (draw-line stream
                           (nmake-position mpos1
                             (- width (position-x pos1))
                             (position-y pos1))
                           (nmake-position mpos2
                             (- width (position-x pos2))
                             (position-y pos2))))))
        (dotimes (j 40)
          (sleep 0.1) ;; artificially slow this down
          (dotimes (k 4)
            (nmake-position next-position
              (+ (max (* resolution dx)
                      (min (- width (* resolution dx))
                           (position-x previous-position)))
                 (* resolution (- (random (1+ (* 2 dx))) dx)))
              (+ (max (* resolution dy)
                      (min (- height (* resolution dy))
                              (position-y previous-position)))
                 (* resolution (- (random (1+ (* 2 dy))) dy))))
            (draw-mirrored-line pane previous-position next-position width)
            (ncopy-position previous-position next-position)))
        (draw-mirrored-line pane next-position first-position width)))))

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
The object described on this page has been modified in the 8.2 release; see the Release Notes.
Created 2016.6.21.