[PATCH wayland-protocols 0/7] xdg-shell: Tooltips revisited and xdg_positioner

[Jonas Ådahl]

On Thu, Apr 14, 2016 at 04:28:11PM +0800, Jonas Ådahl wrote:
> Hi,
> 
> This is the continuation of the previous patch series meaning to split up
> xdg_surface into different per-role interfaces, while making it possible to map
> more types of surfaces. It enables using xdg_shell to create tooltips and other
> non-grabbing popups, as well as introduces a declarative system for enabling
> clients to position its child surfaces (such as menus and popovers) within the
> "work area" of the compositor.
> 
> Regarding the new popup interface, it should make it possible to use popups for
> both grabbing popup chains such as menus with sub menus, as well as tooltips
> and non-grabbing popups. The one-popup-chain rule still exists, but one can now
> have multiple popups on the same surface. For example it is possible to a
> non-grabbing pop over surface, while still showing tooltips on the toplevel
> surface.
> 
> One currently unsolved stacking related issue is how to avoid newly created
> popups being stacked above previous ones. For example a tooltip on a menu item
> will stacked under a sub menu surface if the sub menu is created after the
> tooltip.
> 
> The new positioning API is meant to provide a declarative high level
> description of how the compositor should try to position the child surface if
> it would overflow outside of some compositor specific "work area" (in the
> protocol referred to as "constrained"). With this it should be possible to
> describe most if not all common menu positioning semantics out there, with the
> possibility to adding more rules later.
> 
> With the new API, a client will perform the following operations to map a menu
> that is to be expanded right of and below some user interface element (such as
> button), flips vertically to the other side of the button if doesn't fit below,
> and slides along the x-axis if it would end up outside of the left or right
> screen edge:
> 
>  toplevel_xdg_surface = xdg_surface of the toplevel surface
>  button_rect = surface window geometry relative rectangle of the button widget
>  menu_window_rect = window geometry of the menu surface
> 
>  /* Create base interfaces. */
>  menu_wl_surface = wl_compositor.create_surface()
>  menu_xdg_surface = xdg_shell.get_xdg_surface(menu_wl_surface)
> 
>  /* Set up positioning description. */
>  menu_xdg_positioner = xdg_shell.create_positioner()
>  menu_xdg_positioner.set_anchor_rect(button_rect)
>  menu_xdg_positioner.set_gravity(gravity_bottom|gravity_right)
>  menu_xdg_positioner.set_anchor(anchor_bottom|anchor_right)
>  menu_xdg_positioner.set_constrain_action(slide_x|flip_y)
> 
>  /* Make it a popup. */
>  menu_xdg_popup = xdg_surface.get_popup(menu_xdg_surface,
>                                         toplevel_xdg_surface,
>                                         menu_xdg_positioner)
>  menu_xdg_positioner.destroy()
> 
>  /* Set up initial required state. */
>  menu_xdg_surface.set_window_geometry(menu_window_rect)
>  menu_xdg_popup.grab(seat, serial)
> 
>  /* Commit intial state (note now content is attached!). */
>  menu_wl_surface.commit()

Obviously "now" here is a typo, and should be "no". *no* content is
attached at this stage. (Thanks Pekka for pointing this out)


Jonas

> 
>  ... compositor will given the window geometry and parent surface compute a
>      resulting position. ....
> 
>  *** received from the compositor: menu_xdg_popup.configure(x, y),
>                                    menu_xdg_surface.configure(serial)
> 
>  menu_wl_surface.attach(buffer_with_menu_content_drawn_into_it)
>  menu_wl_surface.commit()
> 
>  .. compositor will map the surface at the previously computer position
> 
> The currently unsolved problems with the positioning API is whether it is
> within scope to provide wl_subsurface like parent-child state synchronization
> capabilities, whether a popup can ever be moved once it has been initially
> positioned, and whether to allow the client to move the popup after it has been
> positioned (by setting new positioners).
> 
> Moving could easily be added in a later revision, but parent-child state
> synchronization and whether the compositor is allowed move the popup after it
> was initially positioned are probably questions that should be answered up
> front.
> 
> 
> Jonas
> 
> 
> 
> Jonas Ådahl (7):
>   xdg-shell: Turn xdg_surface into a generic base interface
>   xdg-shell: Put xdg_shell events after requests
>   xdg-shell: Add error codes for invalid surface state
>   xdg-shell: Improve error enum formatting some
>   xdg-shell: Make get_popup take a xdg_surface instead of wl_surface
>   xdg-shell: Make xdg_popup non-grabbing by default
>   xdg-shell: Introduce xdg_positioner
> 
>  unstable/xdg-shell/xdg-shell-unstable-v6.xml | 586 ++++++++++++++++++++-------
>  1 file changed, 437 insertions(+), 149 deletions(-)
> 
> -- 
> 2.4.3
>