Mir Shell

Create a mir_regular_surface_v1 archetype for the given surface. This assigns the archetype of regular_surface to the wl_surface, or raises a protocol error if another archetype is already assigned and the transition is disallowed.

The previous archetype's role object becomes inert; the client should destroy the previous archetype role object. Any further calls to the previous archetype role object are a protocol error.

Create a mir_floating_regular_surface_v1 archetype for the given surface. This assigns the archetype of floating_regular to the wl_surface, or raises a protocol error if another archetype is already assigned and the transition is disallowed.

The previous archetype's role object becomes inert; the client should destroy the previous archetype role object. Any further calls to the previous archetype role object are a protocol error.

A floating regular surface is "always on top" of other application windows and will not be docked.

Create a mir_dialog_surface_v1 archetype for the given surface. This assigns the archetype of dialog_surface to the wl_surface, or raises a protocol error if another archetype is already assigned and the transition is disallowed.

The previous archetype's role object becomes inert; the client should destroy the previous archetype role object. Any further calls to the previous archetype role object are a protocol error.

A dialog is usually used to communicate information that must be explicitly acknowledged or responded to (for example, to report an error), or to get specific information about something requested in a parent window (for example, a Print dialog) or from a shell function (for example, to confirm shutdown).

A dialog should have a parent whenever relevant. It may, however, be parentless.

If a dialog has a parent, it is modal to the parent and any satellites the parent has. This means: (1) A user should be able to move, resize, or hide an open dialog’s parent, but not close it or interact with its contents; and move, resize, or close the parent’s satellites if any, but not interact with their contents. (2) Whenever the parent is minimized or otherwise hidden, the dialog should be minimized or hidden too. (3) Any attempt to give input focus to the parent should focus the dialog instead. Therefore, the dialog and all of its ancestors should be presented as a single entity in any window switcher.

Partly because of that last behavior, a window should only ever have one dialog child at a time. If an app tries to open a second dialog child, The compositor should close the previous one first.

Create a mir_satellite_surface_v1 archetype for the given surface. This assigns the archetype of satellite_surface to the wl_surface, or raises a protocol error if another archetype is already assigned and the transition is disallowed.

The previous archetype's role object becomes inert; the client should destroy the previous archetype role object. Any further calls to the previous archetype role object are a protocol error.

A satellite is an accessory to a regular, floating regular, or dialog window. It always has a parent window, and typically it provides easy access to functions in its parent: for example, a toolbox, formatting palette, or Find/Change window.

To reduce clutter when a satellite’s parent is not being used, a satellite should be present on screen only when any of its parents is active (for example, when a dialog or another satellite of its parent has input focus). Otherwise, subject to a delay to allow reparenting, it should not be present — not merely invisible or minimized, and not closed, but not present until its parent becomes active again (or an active window becomes its parent).

To avoid flicker from briefly-appearing dialogs, whenever a satellite’s parent has a child dialog, the satellite should remain present. But like the parent window itself, it should not receive input as long as the dialog is open.

Create a positioner object. A positioner object is used to position surfaces relative to some parent surface. See the interface description and xdg_surface.get_popup for details.

This request indicates that the client will not use the mir_shell object any more. Objects that have been created through this instance are not affected.

This request destroys the mir surface archetype and disassociates it from the surface.

This request destroys the mir surface archetype and disassociates it from the surface.

This request destroys the mir surface archetype and disassociates it from the surface.

Reposition an already-mapped satellite. The satellite will be placed given the details in the passed mir_positioner object, and a mir_satellite_surface_v1.repositioned followed by wl_surface.configure will be emitted in response. Any parameters set by the previous positioner will be discarded.

The passed token will be sent in the corresponding xdg_satellite.repositioned event. The new satellite position will not take effect until the corresponding configure event is acknowledged by the client. See xdg_satellite.repositioned for details. The token itself is opaque, and has no other special meaning.

If multiple reposition requests are sent, the compositor may skip all but the last one.

If the satellite is repositioned in response to a configure event for its parent, the client should send an mir_positioner.set_parent_configure and possibly an mir_positioner.set_parent_size request to allow the compositor to properly constrain the satellite.

If the satellite is repositioned together with a parent that is being resized, but not in response to a configure event, the client should send an mir_positioner.set_parent_size request.

This request destroys the mir surface archetype and disassociates it from the surface.

The repositioned event is sent as part of a satellite configuration sequence, together with mir_satellite_surface_v1.configure and lastly wl_surface.configure to notify the completion of a reposition request.

The repositioned event is to notify about the completion of a mir_satellite_surface_v1.reposition request. The token argument is the token passed in the xdg_satellite.reposition request.

Immediately after this event is emitted, mir_satellite_surface_v1.configure and wl_surface.configure will be sent with the updated size and position, as well as a new configure serial.

The client should optionally update the content of the satellite, but must acknowledge the new satellite configuration for the new position to take effect. See mir_satellite_surface_v1.ack_configure for details.

Notify the compositor that the mir_positioner will no longer be used.

Set the size of the surface that is to be positioned with the positioner object. The size is in surface-local coordinates and corresponds to the window geometry. See xdg_surface.set_window_geometry.

If a zero or negative size is set the invalid_input error is raised.

Specify the anchor rectangle within the parent surface that the child surface will be placed relative to. The rectangle is relative to the window geometry as defined by xdg_surface.set_window_geometry of the parent surface.

When the mir_positioner object is used to position a child surface, the anchor rectangle may not extend outside the window geometry of the positioned child's parent surface.

If a negative size is set the invalid_input error is raised.

Defines the anchor point for the anchor rectangle. The specified anchor is used derive an anchor point that the child surface will be positioned relative to. If a corner anchor is set (e.g. 'top_left' or 'bottom_right'), the anchor point will be at the specified corner; otherwise, the derived anchor point will be centered on the specified edge, or in the center of the anchor rectangle if no edge is specified.

Defines in what direction a surface should be positioned, relative to the anchor point of the parent surface. If a corner gravity is specified (e.g. 'bottom_right' or 'top_left'), then the child surface will be placed towards the specified gravity; otherwise, the child surface will be centered over the anchor point on any axis that had no gravity specified. If the gravity is not in the ‘gravity’ enum, an invalid_input error is raised.

Specify how the window should be positioned if the originally intended position caused the surface to be constrained, meaning at least partially outside positioning boundaries set by the compositor. The adjustment is set by constructing a bitmask describing the adjustment to be made when the surface is constrained on that axis.

If no bit for one axis is set, the compositor will assume that the child surface should not change its position on that axis when constrained.

If more than one bit for one axis is set, the order of how adjustments are applied is specified in the corresponding adjustment descriptions.

The default adjustment is none.

Specify the surface position offset relative to the position of the anchor on the anchor rectangle and the anchor on the surface. For example if the anchor of the anchor rectangle is at (x, y), the surface has the gravity bottom_right, and the offset is (ox, oy), the calculated surface position will be (x + ox, y + oy). The offset position of the surface is the one used for constraint testing. See set_constraint_adjustment.

The constraint adjustment value define ways the compositor will adjust the position of the surface, if the unadjusted position would result in the surface being partly constrained.

Whether a surface is considered 'constrained' is left to the compositor to determine. For example, the surface may be partly outside the compositor's defined 'work area', thus necessitating the child surface's position be adjusted until it is entirely inside the work area.

The adjustments can be combined, according to a defined precedence: 1) Flip, 2) Slide, 3) Resize.