MacroPackage: cgToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 9.0
Unrevised from 8.2 to 9.0.
8.2 version

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:

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-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.2 page.
Created 2012.5.30.

ToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 9.0
Unrevised from 8.2 to 9.0.
8.2 version