[PATCH weston 1/6] xdg-shell: define the present/present_from_event() requests

[Derek Foreman]

On 30/09/15 12:01 PM, Bill Spitzak wrote:
> 
> 
> On Tue, Sep 29, 2015 at 12:18 PM, Derek Foreman <derekf at osg.samsung.com
> <mailto:derekf at osg.samsung.com>> wrote:
> 
> 
>     > 2. Call the function "xdg_surface_raise". Because raising is exactly
>     > what the client expects. It does not mean that it *has* to raise the
>     > window. If you don't do this, lots of programmers are going to ask
>     where
>     > the raise function is, let's stop that from being added as another
>     call
>     > and get this right now into a single api.
> 
>     mumble mumble "descriptive not prescriptive", raise is an imperative.
> 
>     Then again "present" is too.  Not sure how far we want to bike shed this
>     one.  xdg_surface_indicate_activity?  heh.  getting a bit long to type.
> 
>     Either way, we're expected to present something to the user (either an
>     indication or the surface).  We're not necessarily going to raise
>     anything.  So raise may be more confusing.
> 
> 
> "raise" is a very likely possible result of this. There is a non-zero
> chance that the result of this message will be an action that a user and
> programmer will call "raise". Your complaint is like saying "we can't
> have this function be called 'set_color' because on a black and white
> screen it will produce a gray shade".

I think I actually did say something like that in a review of a patch
using FB_VISUAL_MONO10 to represent greyscale the other day, so I'm ok
with that.

> My main concern is that programmers are going to search for the word
> "raise" to figure out how to raise windows. They are not going to search
> for "present" or "indicate_activity" or any other bogus word. I suspect
> that if you don't name this "raise" then a function called "raise" will
> be added as an extension very soon, and probably break all your careful
> plans of allowing the compositor to do something other than raise.

Well, X calls similar functionality "UrgencyHint"...  That's actually
more descriptive than imperative.  The idea is that we let the
compositor know the surface needs attention, not that we tell it what to do.

Programmers shouldn't be trying to figure out how to raise a window
anyway, they should be searching for words like notify.  But if we put
the word "raise" prominently in the documentation, I guess google should
sort it out for them.  ;)

In any event, I dislike "present" less than I dislike "raise", so I'm
happy enough with the patch as presented.  You do raise a good point though.

I'm done.  Really.  Others can continue to fight about this if they so
choose, I've had my say.