Client API philosophy

Tue Nov 11 02:12:20 UTC 2014

On Tue, Nov 11, 2014 at 12:48 PM, Daniel van Vugt 
<daniel.van.vugt at canonical.com> wrote:
> On the second issue of client API design, it's useful to point out 
> why the menu example is not a good argument:
> 
> 1. Depending on your shell, and its current mode, a "menu" might not 
> have a relative position dictated by the window position, but get 
> moved/modified elsewhere on the screen. Think about phones where long 
> menus/combos get converted to a wheel/widget in the centre of the 
> screen (mostly phones).

Oh, absolutely. It's fine for the shell to interpret the requested 
coordinates as appropriate for the form-factor. Indeed, we fully expect 
*desktop* shells to interpret the coordinates as appropriate (for 
example, if the requested surface would be mostly offscreen if (x,y) 
were interpreted as its top-left coordinate).

> 
> 2. Relative position is useful to other window types too. For example 
> the decorations-next design of title bars, but also embedded GL 
> windows or accelerated video in a browser. So with multiple features 
> requiring relative placement, you propose each new feature gets a new 
> client function, which is mostly redundant with the others? That's 
> crazy for three reasons:
>   (a) Redundancy in the API is unwanted effort, particularly for 
> maintenance. It scales poorly.

The APIs are really simple - I'm perfectly happy if they're all 
implemented in terms of integer surface parameters!

And the maintenance effort is traded off between more distinct API 
entry points and easier state validation; if you can't atomically set 
all the necessary attributes on a surface then the surface must 
transition through an invalid state.

If your client API prototypes require all the relevant state to be 
provided up-front it's much easier to verify correctness.

> 
>   (b) Each function, by its name, is tied to a window type (e.g. 
> "menu") and so could easily become deprecated as desired 
> types/functionality changes.
>   (c) Your proposed API that ties a "menu" to (x,y) now has 
> unused/ignored parameters in phone (or other) shells that ignore the 
> (x,y) for menus (see #1 above).

Equally, if you *don't* have (x,y) for the menu your client is now tied 
exclusively to the phone and will mysteriously die if you try it on a 
desktop.

The semantic for menus may well be “this pops up a surface associated 
with <rectangle> when appropriate”. That's perfectly fine.

> 
> On 11/11/14 09:33, Daniel van Vugt wrote:
>> We are actually in violent agreement on "policy" and conflating two
>> different issues. So please, let's separate them :)
>> 
>> It is indeed up to the server/shell to dictate policy, particularly 
>> as
>> it can and will vary between shells/modes of a shell. Anything 
>> invalid
>> is returned as an error to the client API, or in the form of a
>> non-blocking API:
>> 
>>    1. asynchronous set feature A = B
>>    2. optional wait and get feature A, and check it was changed to B 
>> or
>> something else dictated by shell policy.
>> 
>> What we must not do is try to enforce policy via client function
>> prototype design. Because policy changes not just between shells, but
>> even between modes of a shell (e.g. we aim to unify Unity8 desktop 
>> with
>> touch I think).
>> 
>> The confusion here is coming from some people thinking that a 
>> flexible
>> API prevents strong enforcement of policy. It does not.
>> 
>> P.S. "menus" are explicitly not a window type right now (as copied 
>> from
>> the WM design docs). So it's possibly assuming too much to mention 
>> the
>> the word "menu" in the client API. Although we possibly could - 
>> rename
>> popover?
>> 
>> 
>> On 10/11/14 17:58, Alan Griffiths wrote:
>>> On 10/11/14 03:31, Daniel van Vugt wrote:
>>>> 
>>>> Sounds like a response to one of my merge proposals. So please put
>>>> arguments in the code reviews...
>>> 
>>> There's a good reason to discuss this outside of a specific code 
>>> review:
>>> we need to agree the "big picture".
>>> 
>>> There is an apparent disagreement about the approach to window
>>> management policy and that affects the review of any and all MPs in 
>>> this
>>> area.
>>> 
>>> I've always understood the intent to be that Mir enables shells (in
>>> general and specifically unity8) to implement policies about how 
>>> things
>>> should be presented. It is far easier for a shell to provide a 
>>> policy
>>> around, say "menus" if it is asked to "show a menu" than if it is 
>>> asked
>>> for a window, then asked to "parent" it, then asked to position it, 
>>> etc.
>>> With this approach there is never any point at which the server 
>>> knows
>>> what the client intends.
>>> 
>>> If we intend to push the presentation policy out to the client 
>>> toolkits
>>> then they will provide inconsistent (a.k.a. incorrect) policy
>>> implementations. (Especially if, as we should hope, there are 
>>> multiple
>>> shells written using the Mir library that implement policies
>>> differently.)
>>> 
>>> 
>>> 
>> 
> 
> --
> Mir-devel mailing list
> Mir-devel at lists.ubuntu.com
> Modify settings or unsubscribe at: 
> https://lists.ubuntu.com/mailman/listinfo/mir-devel