API REVIEW request for RT-19783: Provide an option to allow modal windows to be blocking

[Kevin Rushforth]

JIRA:  http://javafx-jira.kenai.com/browse/RT-19783

We have had several requests for a way to block the caller while a 
(modal) dialog is shown. The show() method on a Stage is specified to 
return to the caller immediately regardless of the modality of a stage. 
This is a good semantic for many applications, but complicates the logic 
for other applications which don't want to proceed until the dialog is 
dismissed. It is also needed internally to implement an Alert class (see 
RT-12643 <http://javafx-jira.kenai.com/browse/RT-12643> for example). 
Swing dialog, for example, JOptionPane, work by blocking the caller 
until the dialog is dismissed meaning that Swing application programmers 
are already familiar with that model.

Our proposal for JavaFX 2.2 is to add a new method on Stage, 
showAndWait(), which will block the caller until the stage is hidden. 
Note that while this is primarily useful for modal Stages, there is 
nothing in the API that restricts it to such.

The proposed method and javadoc are described in the JIRA 
<http://javafx-jira.kenai.com/browse/RT-19783?focusedCommentId=110277&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-110277>, 
but since it is so short, I will also list it here:

        /**
         * Show the stage and wait for it to be closed before returning to the
         * caller. This must be called on the FX Application thread. The stage
         * must not already be visible prior to calling this method. This must not
         * be called on the primary stage.
         *
         * @throws IllegalStateException if this method is called on a thread
         *     other than the JavaFX Application Thread.
         * @throws IllegalStateException if this method is called on the
         *     primary stage.
         * @throws IllegalStateException if this stage is already showing.
         */
        public void showAndWait();


-- Kevin