<AWT Dev> [9] Review Request: 8027324 The spec for Toolkit.setDynamicLayout() and Toolkit.isDynamicLayoutActive() needs to be clarified

[Sergey Bylokhov]

On 22.03.16 20:26, Phil Race wrote:
>
> I don't see a problem with the words "has no effect".
>
> But I am apparently failing to understand the issue

I agree that this API is quite cryptic.

>
>  >The problem is that the method isDynamicLayoutActive() has no
>  >description what happens if the OS supports(or nonsupports) the
>  >feature, but the change of the state is not supported, which means
>  >that the value, which was set in setDynamicLayout() is ignored.
>  >Moreover this documentation states that isDynamicLayoutSet() is never
> ignored.
>
> My problem  maybe with what "the change of state is not supported"
> really means here. And state of what ?

The state of the current layout (dynamic or not).
Layout of Containers can be validated dynamically during resizing, or 
statically, after resizing is complete.

>
> setDynamicLayout() and isDynamicLayoutSet() do nothing more
> than set a flag, and return the value of that flag.

Correct.

>
> That flag is used to determine the behaviour of isDynamicLayoutActive()
> If it is set to "false" then isDynamicLayoutActive() will always return
> false,
> (regardless of what the underlying platform is doing)
> If it is set to "true" then isDynamicLayoutActive() will will consult
> the desktop property which is *supposed* to reflect the platform support
> and so should agree with what the desktop property says.

Nope, the isDynamicLayoutActive() always returns the current status.
It cannot return true if this feature is unsupported by the OS, but it 
can return true if the user sets the flag to false, but the OS cannot 
disable the feature.

>
> I presume the desktop property value is set once and never changes
> since it implies something about the capabilities of the system, regardless
> as to what it is actually doing right now.

Correct.

>
> I can infer all that from the existing documentation and everything
> you do in your test is what I would expect from that documentation.

The problem in the current documentation is that it states that 
isDynamicLayoutActive() unconditionally should take into account the 
flag. And in the same time the documentation of setDynamicLayout() 
states that it can be ignored in some environments.

>
>
> -phil.
>
> On 03/22/2016 08:31 AM, Sergey Bylokhov wrote:
>> On 22.03.16 10:35, Semyon Sadetsky wrote:
>>> 213      * by the underlying operating system and/or window manager).
>>> Note that on
>>>   214      * platforms where dynamic layout during resizing is not
>>> supported (or is
>>>   215      * always supported) by the OS/WM, ({@code
>>> isDynamicLayoutSet()}) property
>>>   216      * has no effect.
>>>
>>> Not sure that it is correct to talk about "effect" of a method that is
>>> not expected to change anything .
>>
>> It affects behavior of the isDynamicLayoutActive();
>>
>>> Usually it is told about effect of a
>>> change but the getter method is not the case.
>>> I might be wrong and this may have valid meaning in English.
>>
>> This is about the beginning of the statement:
>> =============================================
>>   * Returns whether dynamic layout of Containers on resize is currently
>>   * active (both set in program ({@code isDynamicLayoutSet()}), and
>> supported
>>   * by the underlying operating system and/or window manager). Note
>> that on
>>   * platforms where dynamic layout during resizing is not supported
>> (or is
>>   * always supported) by the OS/WM, ({@code isDynamicLayoutSet()})
>> property
>>   * has no effect.
>> =============================================
>> The method isDynamicLayoutActive() return true only if the dynamic
>> layout is supported by the system and isDynamicLayoutSet() return
>> true. But if dynamic layout during resizing is not supported (or is
>> always supported) then isDynamicLayoutSet() has no effect to this
>> method(isDynamicLayoutActive() where this documentation is placed).
>>
>> I can change "has no effect" to "will be ignored"
>>
>>>
>>> 50         t.setDynamicLayout(true);
>>>    51         if(!t.isDynamicLayoutSet()){
>>>    52             throw new RuntimeException("'true' expected but
>>> 'false' returned");
>>>    53         }
>>>
>>> The test fails in the reviewed scenario when setDynamicLayout(true) has
>>> no effect .
>>
>> It has no effect to the layout, the method isDynamicLayoutSet() is
>> always return the value which was set.
>>
>>>
>>>
>>>
>>> On 9/23/2015 10:01 PM, Sergey Bylokhov wrote:
>>>> Hello.
>>>> Please review the fix for jdk9.
>>>>
>>>> We have 3 methods and one desktop property to support
>>>> behavior during resize of the window:
>>>> - Property "awt.dynamicLayoutSupported" describe support of this
>>>> feature by the current OS.
>>>> - Method isDynamicLayoutActive() describe: is this feature currently
>>>> active or not.
>>>> - isDynamicLayoutSet/setDynamicLayout is a possibility to change the
>>>> current state of the feature.
>>>>
>>>> The problem is that the method isDynamicLayoutActive() has no
>>>> description what happens if the OS supports(or nonsupports) the
>>>> feature, but the change of the state is not supported, which means
>>>> that the value, which was set in setDynamicLayout() is ignored.
>>>> Moreover this documentation states that isDynamicLayoutSet() is never
>>>> ignored.
>>>>
>>>> Documentation is updated using the same description as in
>>>> setDynamicLayout(); The existed test is updated to cover this
>>>> situation.
>>>>
>>>> This bug causes a jck failure see JCK-7301760.
>>>> ccc request will be created after the technical review.
>>>>
>>>> Bug: https://bugs.openjdk.java.net/browse/JDK-8027324
>>>> Webrev can be found at:
>>>> http://cr.openjdk.java.net/~serb/8027324/webrev.00
>>>>
>>>
>>
>>
>


-- 
Best regards, Sergey.