Arguments: dialog &key stream initial-focus
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). 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 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 :parent initarg and passing a true value as the :overlapped initarg (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.)
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-completionflag-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.
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.
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.