Generic Function

Package: common-graphics

Arguments: stream title prompt icon button1 &optional button2 button3 button4&key topmost

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.

stream must be a stream. title should be a string or nil. icon should be an icon 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 position of the dialog when displayed is controlled by position-utility-dialog.

Common Graphics and IDE documentation is described in About Common Graphics and IDE documentation in cgide.htm.

The documentation is described in introduction.htm and the index is in index.htm.

Copyright (c) 1998-2000, Franz Inc. Berkeley, CA., USA. All rights reserved.

Created 2000.10.5.