pop-up-modal-dialog

Arguments: dialog &key stream initial-focus bring-thread-to-front

Exposes and selects a dialog in a modal way, where the user must interact with and exit that dialog before proceeding with anything else.

Specifically, the modal dialog will be displayed indefinitely until some user action causes the call to pop-up-modal-dialog to return.

While the modal dialog is present, all mouse events are disabled on stream as well as on all of the child and owned windows of stream (except for the modal dialog itself and no windows are disabled if streamis the screen). This is done to force the user to complete a response to the modal dialog before continuing to interact with the rest of the application. The dialog can be said to be "modal with respect to stream ". Typically stream should be a top-level window, to establish modality with respect to its whole window hierarchy. stream can be the screen, which is the value returned by (screen *system*). See screen and *system*. stream defaults to the uppermost parent of the modal dialog, as returned by calling top-level-window on the dialog.

If an application includes multiple top-level windows and it is unsatisfactory for modal dialogs to be modal with respect to only one of the top-level windows, then an invisible window can be added to the application that serves as the owner of all of the top-level windows, and that invisible owner window can be passed as the stream argument to pop-up-modal-dialog to achieve modality with respect to the entire set of the top-level windows. To make an invisible window, simply call make-window, passing :state :shrunk as one of the initargs. To create a top-level owned window on the invisible window, call make-window again, passing the invisible window as the :owner initarg and passing the :child-p initarg as nil (which makes an owned window rather than a child window).

initial-focus may be one of the controls on the dialog, in which case that control will have the keyboard focus when the dialog appears. (This parameter exists because it does not work to call set-focus on the control before the dialog is exposed, and it is too late to call set-focus once pop-up-modal-dialog has been called to expose the dialog.)

If bring-thread-to-front is true, then set-foreground-window is called on the dialog to bring its application to the front if it was not in front already. This may be useful for a particularly important modal dialog to ensure that the user sees it. This call to set-foreground-window is always done if the owner of the dialog is the screen.

A call to pop-up-modal-dialog will return only in these cases:

• The value of a control is changed by the user, resulting in the on-change event-handler for the control returning a true second value. The control is returned from pop-up-modal-dialog.
• flag-modal-completion is called on the dialog. The optional value argument to flag-modal-completion is returned from pop-up-modal-dialog.
• The user clicks a default-button or a cancel-button on the dialog, and the button has its default on-change event handler of return-t-from-pop-up-dialog or return-nil-from-pop-up-dialog. (Each of these functions actually just calls flag-modal-completion, returning t and nil respectively.)
• user-close is called on the dialog. (This happens when the user interactively closes the window in one of the built-in ways such as by clicking the close icon on the dialog's frame or pressing alt-F4.) In this case, pop-up-modal-dialog may still not exit if there is a cancel-button on the dialog whose on-change event handler fails to exit the call by one of the other means. This functionality is implemented as a user-close   :around method on basic-pane; this method generally should not be overridden.
• The lisp process that called pop-up-modal-dialog throws to pop-up-dialog. The value thrown will be returned by pop-up-modal-dialog. This is a more drastic option that is not recommended unless it turns out to be necessary for some unforeseen reason.

Copyright (c) 1998-2002, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 6.2. This page has had moderate revisions compared to the 6.1 page.
Created 2002.2.26.