| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |
Arguments: window-or-screen title prompt icon button1 &optional button2 button3 button4 &key topmost (initial-focus :default)
This function displays a dialog box with contents described next. At least one and as many as four buttons will appear on the dialog box. The system will wait until the user clicks on a button or hits ESC or ENTER. The number of the button clicked on is returned. Hitting ENTER is the same as choosing the button1 (so 1 is returned). Hitting ESC is the same as choosing the last true button.
window-or-screen must be either a window,
the screen, or nil
. If nil
, then the stream returned by selected-window-or-screen will be
used. If the value is a visible window, the dialog will then be
modal. When window-or-screen is the screen, you
might want to specify the topmost keyword
argument true (be sure to give values for the three optional
arguments, using nil
if you do not want
buttons to appear). The dialog will not be
modal. topmost true insures it remains visible.
title should be a string or nil
. icon should be an
icon (see cg-icons.htm) or nil
. prompt should be a
string or nil
. In each case, the value
nil
means the item is not displayed.
Each button argument should be a list, a
string or nil
. The string will be displayed
within the button so it should be short. "OK" and "Cancel" are typical
values. The value nil
indicates the button
should not be displayed. At least one button argument should be true.
If the value is a list, it should have two elements: a symbol or string that will appear in the button and a string, which should be a help message for the choice.
The length of prompt determines how it is displayed. A
multi-line-editable-text
widget (with a
vertical scroll bar if necessary) is used when message is too big to
fit into a static-text
widget.
When topmost is true, the utility dialog invoked by this function will be topmost while it is present. A topmost window is one that remains on top of all other non-topmost windows, even those in other applications. This feature is particularly useful for modal dialogs that need to alert the user even if they have switched to another application.
The initial-focus argument is passed to
pop-up-modal-dialog to
initially focus on a particular widget. Its possible values for this
dialog are :default
(for the leftmost button),
:cancel
(for the rightmost button), or
:button1
, :button2
,
:button3
, or :button4
(for a
button numbered from the left end), or :text
for
the widget that holds the message. If the specified button is not
currently included on the dialog, then the nearest one is used
instead. The default value is :default
.
The position of the dialog when displayed is controlled by position-utility-dialog.
To display a message window without waiting for an interactive response from the user, see with-message-window.
Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.
| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |