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

[Kevin Rushforth]

The "modality" attribute on a stage is described thusly:

    *Modality*

    A stage has one of the following modalities:

        * |Modality.NONE| - a stage that does not block any other window.
        * |Modality.WINDOW_MODAL| - a stage that blocks input events
          from being delivered to all windows from its owner (parent) to
          its root. Its root is the closest ancestor window without an
          owner.
        * |Modality.APPLICATION_MODAL| - a stage that blocks input
          events from being delivered to all windows from the same
          application, except for those from its child hierarchy.

    When a window is blocked by a modal stage its Z-order relative to
    its ancestors is preserved, and it receives no input events and no
    window activation events, but continues to animate and render
    normally. Note that showing a modal stage does not block the calling
    thread. The |show()| method returns immediately regardless of the
    modality. The modality must be initialized before the stage is made
    visible.


So yes, we use the term "blocking" to describe what the modal window 
does to the other windows.

Btw, the proposed change to add show and wait will modify the last 
paragraph of the above to say:

    Note that showing a modal stage does not necessarily block the
    caller. The  show() method returns immediately regardless of the
    modality.  Use the showAndWait() method if you need to block until
    the modal stage is closed.


So we use the term "modal" to describe whether or not the dialog blocks 
input and window activation events from being delivered to other 
windows. I realize that in my description of this I also use "blocking" 
to describe what the showAndWait method does, which is, that the method 
waits (that is does not return) until the stage in question is closed, 
thus blocking the flow of execution of the caller.

I hope this clears it up, but if not, let me know.

-- Kevin


Jeff McDonald wrote:
> Hmmmm ... maybe we're talking semantics here. What does Modality mean in
> JavaFX? What does "blocking" mean in a JavaFX?
>
> Cheers,
> Jeff
>
> On Tue, Apr 10, 2012 at 5:21 PM, Kevin Rushforth <kevin.rushforth at oracle.com
>   
>> wrote:
>>     
>
>   
>> **
>> The problem with showAsModal is that this method is independent of the
>> modality attribute on Stage, so the name would be confusing.
>>
>> You can have a modal window (a window whose modality is
>> Modality.WINDOW_MODAL or Modality.APPLICATION_MODAL), without having it
>> block the caller. Conversely, you can have a non-modal window
>> (Modality.NONE) that blocks if you call this method.
>>
>> I am open to a better name for this method, but I don't think it should
>> have modal in the name.
>>
>> -- Kevin
>>
>>
>>
>> Jeff McDonald wrote:
>>
>> Just my 2 cents ... showAsModal or showModal sounds better. When I see
>> showAndWait my first question before I read the docs is "what am I waiting
>> for?"  showAsModal or showModal  seem more self-documenting than
>> showAndWait.
>>
>>  Cheers,
>> Jeff
>>
>> On Tue, Apr 10, 2012 at 2:45 PM, Richard Bair <richard.bair at oracle.com>wrote:
>>
>>     
>>> Looks good to me, if nobody objects by tomorrow I'll mark this as
>>> approved.
>>>
>>> Richard
>>>
>>> On Apr 10, 2012, at 1:43 PM, Kevin Rushforth wrote:
>>>
>>>       
>>>> 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 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, 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
>>>>
>>>>         
>>>