pop-up-message-dialog

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-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.