Class WindowSpecification

Nested Relationships

Nested Types

Class Documentation

class WindowSpecification

The window specification class describes a request of changes to be made on a miral::Window.

Instances of this class may originate either from the client or the compositor itself. Typically, changes will be made from miral::WindowManagementPolicy and sent to miral::WindowManagerTools::modify_window to enact the changes.

The class itself consists of optional values. If a value is set, then a change on that value will occur. If the value is unset, then no change will happen.

See also

miral::WindowManagementPolicy - handles specifications from both the client and compositor

See also

miral::WindowManagerTools::modify_window - the method used to modify a window using a specification

Public Types

enum class InputReceptionMode

Describes the input reception mode.

Used by #WindowSpecification::input_mode.

Values:

enumerator normal
enumerator receives_all_input

Public Functions

WindowSpecification()

Construct a new window specification.

WindowSpecification(WindowSpecification const &that)

Construct a copy of the given specification.

Parameters:

that – to copy

WindowSpecification &operator=(WindowSpecification const &that)
WindowSpecification(mir::shell::SurfaceSpecification const &spec)

Construct a window specification from a surface specification.

For internal use only.

Parameters:

spec – the surface specification

~WindowSpecification()
std::optional<Point> const &top_left() const &

The top left corner of the window.

Returns:

the top left point

std::optional<Size> const &size() const &

The size of the window for window management purposes.

It may differ from the buffer size drawn by the client as it may include decorations and/or exclude drop-shadows

This value is not guaranteed to be honored by the client.

Returns:

the size

Note

If the WindowSpecification is applied using #WindowManagementTools::modify_client then value will be adjusted based on min_width(), #WindowInfo::max_width(), #WindowInfo::min_height(), #WindowInfo::max_height(), #WindowInfo::min_aspect(), #WindowInfo::max_aspect(), #WindowInfo::width_inc() and WindowInfo::height_inc(). Set these properties to their default values if they should be ignored. Note that the position of the window may also be adjusted if the new size violates the size constraints.

std::optional<std::string> const &name() const &

The name of the window.

Returns:

the name

std::optional<int> const &output_id() const &

The output id optionally associated with a fullscreen window.

See also

miral::Output - the class that holds this output id

Returns:

the output id

std::optional<MirWindowType> const &type() const &

The type of the window.

Returns:

the type

std::optional<MirWindowState> const &state() const &

The state of the window.

Returns:

the state

std::optional<MirOrientationMode> const &preferred_orientation() const &

The preferred orientation of the window.

This is often used when the buffer of the window is provided by the client to match the current orientation of the output.

Returns:

a the orientation.

std::optional<Rectangle> const &aux_rect() const &

Describes the auxiliary rectangle.

A window can be positioned relative to its parent window using four fields:

The child window is positioned so that the point defined by #window_placement_gravity on the child window aligns with the point defined by #aux_rect_placement_gravity on the parent window’s #aux_rect. The final position is offset by #aux_rect.

Returns:

the auxiliary rectangle

std::optional<MirPlacementHints> const &placement_hints() const &

The placement hint describes how child window placement should be adjusted they cannot be placed in the requested position.

Returns:

the placement hints

std::optional<MirPlacementGravity> const &window_placement_gravity() const &

Describes the placement gravity.

A window can be positioned relative to its parent window using four fields:

The child window is positioned so that the point defined by #window_placement_gravity on the child window aligns with the point defined by #aux_rect_placement_gravity on the parent window’s #aux_rect. The final position is offset by #aux_rect.

Returns:

the placement gravity

std::optional<MirPlacementGravity> const &aux_rect_placement_gravity() const &

Describes the auxiliary rectangle placement gravity.

A window can be positioned relative to its parent window using four fields:

The child window is positioned so that the point defined by #window_placement_gravity on the child window aligns with the point defined by #aux_rect_placement_gravity on the parent window’s #aux_rect. The final position is offset by #aux_rect.

Returns:

the auxiliary placement gravity

std::optional<Displacement> const &aux_rect_placement_offset() const &

Describes the auxiliary rectangle placement offset.

A window can be positioned relative to its parent window using four fields:

The child window is positioned so that the point defined by #window_placement_gravity on the child window aligns with the point defined by #aux_rect_placement_gravity on the parent window’s #aux_rect. The final position is offset by #aux_rect.

Returns:

the auxiliary placement gravity

std::optional<Width> const &min_width() const &

The minimum width of the window.

Returns:

the minimum width

std::optional<Height> const &min_height() const &

The minimum height of the window.

Returns:

the minimum height

std::optional<Width> const &max_width() const &

The maximum width of the window.

Returns:

the maximum width

std::optional<Height> const &max_height() const &

The maximum height of the window.

Returns:

a const reference to the maximum height

std::optional<DeltaX> const &width_inc() const &

The size increments of the window in the X direction.

This is used in cases such as a terminal that can only be resized character-by-character.

Wayland protocols do not support this property, so it generally will not be requested by clients.

Returns:

the width increment.

std::optional<DeltaY> const &height_inc() const &

The size increments of the window in the Y direction.

This is used in cases such as a terminal that can only be resized character-by-character.

Wayland protocols do not support this property, so it generally will not be requested by clients.

Returns:

the height increment

std::optional<AspectRatio> const &min_aspect() const &

The minimum aspect ratio.

Wayland protocols do not support this property, so it generally will not be requested by clients.

Returns:

the min aspect ratio

std::optional<AspectRatio> const &max_aspect() const &

The maximum aspect ratio.

Wayland protocols do not support this property, so it generally will not be requested by clients.

Returns:

the max aspect ratio

std::optional<std::weak_ptr<mir::scene::Surface>> const &parent() const &

The parent surface of the window.

Returns:

the pending parent surface

std::optional<std::vector<Rectangle>> const &input_shape() const &

The input shape of the window.

This is an area in world coordinates that describes the input region for the window.

Returns:

the list of rectangles that describes the input region

std::optional<InputReceptionMode> const &input_mode() const &

The input mode of the window.

Returns:

the input mode

std::optional<MirShellChrome> const &shell_chrome() const &

The shell chrome of the window.

This is currently unused.

Returns:

the shell chrome

std::optional<MirPointerConfinementState> const &confine_pointer() const &

The pointer confinement of the window.

Returns:

the pointer confinement

std::optional<std::shared_ptr<void>> const &userdata() const &

Custom userdata set on the window.

This payload is set by the compositor author. The author may use this to set any information that they would like associated with the window.

Returns:

the userdata

std::optional<Point> &top_left() &

The new position of the window frame.

Returns:

a reference to the top left point

std::optional<Size> &size() &

The size of the window for window management purposes.

It may differ from the buffer size drawn by the client as it may include decorations and/or exclude drop-shadows

This value is not guaranteed to be honored by the client.

Returns:

the size

Note

If the WindowSpecification is applied using #WindowManagementTools::modify_client then value will be adjusted based on min_width(), #WindowInfo::max_width(), #WindowInfo::min_height(), #WindowInfo::max_height(), #WindowInfo::min_aspect(), #WindowInfo::max_aspect(), #WindowInfo::width_inc() and WindowInfo::height_inc(). Set these properties to their default values if they should be ignored. Note that the position of the window may also be adjusted if the new size violates the size constraints.

std::optional<std::string> &name() &

The name of the window.

Returns:

the name of the window

std::optional<int> &output_id() &

The output id of the window.

See also

miral::Output - the class that holds this output id

Returns:

the output id

std::optional<MirWindowType> &type() &

The type of the window.

Returns:

the type of the window

std::optional<MirWindowState> &state() &

The state of the window.

Returns:

the state of the window

std::optional<MirOrientationMode> &preferred_orientation() &

The preferred orientation of the window.

This is often used when the buffer of the window is provided by the client to match the current orientation of the output.

Returns:

the orientation of the window.

std::optional<Rectangle> &aux_rect() &

Describes the auxiliary rectangle.

A window can be positioned relative to its parent window using four fields:

The child window is positioned so that the point defined by #window_placement_gravity on the child window aligns with the point defined by #aux_rect_placement_gravity on the parent window’s #aux_rect. The final position is offset by #aux_rect.

Returns:

the auxiliary rectangle

std::optional<MirPlacementHints> &placement_hints() &

The placement hint describes how windows with type mir_window_type_menu, mir_window_type_satellite or mir_window_type_tip should be adjusted when their placement would cause them to extend beyond their current output.

Returns:

the placement hints

std::optional<MirPlacementGravity> &window_placement_gravity() &

Describes the placement gravity.

A window can be positioned relative to its parent window using four fields:

The child window is positioned so that the point defined by #window_placement_gravity on the child window aligns with the point defined by #aux_rect_placement_gravity on the parent window’s #aux_rect. The final position is offset by #aux_rect.

Returns:

the placement gravity

std::optional<MirPlacementGravity> &aux_rect_placement_gravity() &

Describes the auxiliary rectangle placement gravity.

A window can be positioned relative to its parent window using four fields:

The child window is positioned so that the point defined by #window_placement_gravity on the child window aligns with the point defined by #aux_rect_placement_gravity on the parent window’s #aux_rect. The final position is offset by #aux_rect.

Returns:

the auxiliary placement gravity

std::optional<Displacement> &aux_rect_placement_offset() &

Describes the auxiliary rectangle placement offset.

A window can be positioned relative to its parent window using four fields:

The child window is positioned so that the point defined by #window_placement_gravity on the child window aligns with the point defined by #aux_rect_placement_gravity on the parent window’s #aux_rect. The final position is offset by #aux_rect.

Returns:

the auxiliary placement gravity

std::optional<Width> &min_width() &

The minimum width of the window.

Returns:

the minimum width

std::optional<Height> &min_height() &

The minimum height of the window.

Returns:

the minimum height

std::optional<Width> &max_width() &

The maximum width of the window.

Returns:

the maximum width

std::optional<Height> &max_height() &

The maximum height of the window.

Returns:

a reference to the maximum height

std::optional<DeltaX> &width_inc() &

The size increments of the window in the X direction.

This is used in cases such as a terminal that can only be resized character-by-character.

Wayland protocols do not support this property, so it generally will not be requested by clients.

Returns:

the width increment

std::optional<DeltaY> &height_inc() &

The size increments of the window in the Y direction.

This is used in cases such as a terminal that can only be resized character-by-character.

Wayland protocols do not support this property, so it generally will not be requested by clients.

Returns:

the height increment

std::optional<AspectRatio> &min_aspect() &

The minimum aspect ratio.

Wayland protocols do not support this property, so it generally will not be requested by clients.

Returns:

the min aspect ratio

std::optional<AspectRatio> &max_aspect() &

The maximum aspect ratio.

Wayland protocols do not support this property, so it generally will not be requested by clients.

Returns:

the max aspect ratio

std::optional<std::weak_ptr<mir::scene::Surface>> &parent() &

The parent of this window.

Returns:

the parent of this window

std::optional<std::vector<Rectangle>> &input_shape() &

The input shape of the window.

This is an area in world coordinates that describes the input region for the window.

Returns:

the list of rectangles that describes the input region

std::optional<InputReceptionMode> &input_mode() &

The input mode of the window.

Returns:

the input mode

std::optional<MirShellChrome> &shell_chrome() &

The shell chrome of the window.

This is currently unused.

Returns:

the shell chrome

std::optional<MirPointerConfinementState> &confine_pointer() &

The pointer confinement of the window.

Returns:

the pointer confinement

std::optional<std::shared_ptr<void>> &userdata() &

Custom userdata set on the window.

This payload is set by the compositor author. The author may use this to set any information that they would like associated with the window.

Returns:

the userdata

std::optional<MirDepthLayer> const &depth_layer() const &

The depth layer of a child window is updated with the depth layer of its parent, but can be overridden.

Returns:

the depth layer

std::optional<MirDepthLayer> &depth_layer() &

The depth layer of a child window is updated with the depth layer of its parent, but can be overridden.

Returns:

the depth layer

std::optional<MirPlacementGravity> const &attached_edges() const &

The set of window edges that are attached to edges of the output.

If attached to perpendicular edges, it is attached to the corner where the two edges intersect If attached to oposite edges (eg left and right), it is stretched across the output in that direction If all edges are specified, it takes up the entire output

Returns:

the edges

std::optional<MirPlacementGravity> &attached_edges() &

The set of window edges that are attached to edges of the output.

If attached to perpendicular edges, it is attached to the corner where the two edges intersect If attached to oposite edges (eg left and right), it is stretched across the output in that direction If all edges are specified, it takes up the entire output

Returns:

the edges

std::optional<std::optional<mir::geometry::Rectangle>> const &exclusive_rect() const &

The area over which the window should not be occluded.

This is only meaningful for windows attached to an edge. If the outer optional is unset (the default), the window’s exclusive rect is not changed by this spec If the outer optional is set but the inner is not, the window’s exclusive rect is cleared

Returns:

the exclusive rectangle

std::optional<std::optional<mir::geometry::Rectangle>> &exclusive_rect() &

The area over which the window should not be occluded.

This is only meaningful for windows attached to an edge. If the outer optional is unset (the default), the window’s exclusive rect is not changed by this spec If the outer optional is set but the inner is not, the window’s exclusive rect is cleared

Returns:

the exclusive rectangle

std::optional<bool> const &ignore_exclusion_zones() const &

Decides whether this window should ignore the exclusion zones set by other windows.

This is only meaningful for windows attached to an edge.

Returns:

the flag

std::optional<bool> &ignore_exclusion_zones() &

Decides whether this window should ignore the exclusion zones set by other windows.

This is only meaningful for windows attached to an edge.

Returns:

the flag

std::optional<std::string> const &application_id() const &

The D-bus service name and basename of the app’s .desktop file.

See https://specifications.freedesktop.org/desktop-entry-spec/

Returns:

the application id

std::optional<std::string> &application_id() &

The D-bus service name and basename of the app’s .desktop file.

See https://specifications.freedesktop.org/desktop-entry-spec/

Returns:

the application id

std::optional<bool> const &server_side_decorated() const &

If this window should have server-side decorations provided by Mir Currently, Mir only respects this value during surface construction.

Returns:

the flag

std::optional<bool> &server_side_decorated() &

If this window should have server-side decorations provided by Mir Currently, Mir only respects this value during surface construction.

Returns:

the flag

std::optional<MirFocusMode> const &focus_mode() const &

Describes how the window should gain and lose focus.

Returns:

the focus mode

std::optional<MirFocusMode> &focus_mode() &

Describes how the window should gain and lose focus.

Returns:

the focus mode

std::optional<bool> const &visible_on_lock_screen() const &

If this surface should be shown while the compositor is locked.

Returns:

the flag

std::optional<bool> &visible_on_lock_screen() &

If this surface should be shown while the compositor is locked.

Returns:

the flag

std::optional<mir::Flags<MirTiledEdge>> const &tiled_edges() const &

Describes which edges are touching part of the tiling grid.

Remark

Since MirAL 5.3

Returns:

the tiled edges

std::optional<mir::Flags<MirTiledEdge>> &tiled_edges() &

Describes which edges are touching part of the tiling grid.

Remark

Since MirAL 5.3

Returns:

the tiled edges

std::optional<float> &alpha() &

The alpha of the window.

This value is between [0, 1].

Remark

Since MirAL 5.7

Returns:

the alpha

std::optional<float> const &alpha() const &

The alpha of the window.

This value is between [0, 1].

Remark

Since MirAL 5.7

Returns:

the alpha

std::optional<Size> &parent_size() &

The expected size of the parent window for constrained popup placement.

Set when the compositor should use a specific parent geometry (rather than the current parent geometry) to constrain the popup placement. This is used when repositioning a popup in response to a parent resize.

Remark

Since MirAL 5.8

Returns:

the expected parent size

std::optional<Size> const &parent_size() const &

The expected size of the parent window for constrained popup placement.

Set when the compositor should use a specific parent geometry (rather than the current parent geometry) to constrain the popup placement. This is used when repositioning a popup in response to a parent resize.

Remark

Since MirAL 5.8

Returns:

the expected parent size

mir::shell::SurfaceSpecification to_surface_specification() const

Create a [mir::shell::SurfaceSpecification] from this window spec.

Remark

Since MirAL 5.3

Returns:

a surface specification

struct AspectRatio

Describes the aspect ratio.

Used by #WindowSpecification::min_aspect and #WindowSpecification::max_aspect.

Public Functions

bool operator==(AspectRatio const&) const = default

Public Members

unsigned width
unsigned height