Class WindowSpecification¶

Defined in File window_specification.h

Nested Relationships¶

Nested Types¶

Struct WindowSpecification::AspectRatio

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 speficiation.

Parameters:: that – to copy

auto operator=(WindowSpecification const &that) -> WindowSpecification&¶

WindowSpecification(mir::shell::SurfaceSpecification const &spec)¶

Construct a window specification from a surface specification.

For internal use only.

Parameters:: spec – the surface specification

~WindowSpecification()¶

auto top_left() const -> mir::optional_value<Point> const&¶

The top left corner of the window.

Returns:: the top left point

auto size() const -> mir::optional_value<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.

auto name() const -> mir::optional_value<std::string> const&¶

The name of the window.

Returns:: the name

auto output_id() const -> mir::optional_value<int> 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

auto type() const -> mir::optional_value<MirWindowType> const&¶

The type of the window.

Returns:: the type

auto state() const -> mir::optional_value<MirWindowState> const&¶

The state of the window.

Returns:: the state

auto preferred_orientation() const -> mir::optional_value<MirOrientationMode> 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.

auto aux_rect() const -> mir::optional_value<Rectangle> const&¶

Describes the auxiliary rectangle.

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

#aux_rect specifies a reference rectangle on the parent window.
#aux_rect_placement_gravity defines a specific point on #aux_rect.
#aux_rect_placement_offset: an offset on #aux_rect relative to #aux_rect
#window_placement_gravity defines a point on the child window.

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

auto placement_hints() const -> mir::optional_value<MirPlacementHints> const&¶

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

Returns:: the placement hints

auto window_placement_gravity() const -> mir::optional_value<MirPlacementGravity> const&¶

Describes the placement gravity.

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

#aux_rect specifies a reference rectangle on the parent window.
#aux_rect_placement_gravity defines a specific point on #aux_rect.
#aux_rect_placement_offset: an offset on #aux_rect relative to #aux_rect
#window_placement_gravity defines a point on the child window.

Returns:: the placement gravity

auto aux_rect_placement_gravity() const -> mir::optional_value<MirPlacementGravity> const&¶

Describes the auxiliary rectangle placement gravity.

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

#aux_rect specifies a reference rectangle on the parent window.
#aux_rect_placement_gravity defines a specific point on #aux_rect.
#aux_rect_placement_offset: an offset on #aux_rect relative to #aux_rect
#window_placement_gravity defines a point on the child window.

Returns:: the auxiliary placement gravity

auto aux_rect_placement_offset() const -> mir::optional_value<Displacement> const&¶

Describes the auxiliary rectangle placement offset.

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

#aux_rect specifies a reference rectangle on the parent window.
#aux_rect_placement_gravity defines a specific point on #aux_rect.
#aux_rect_placement_offset: an offset on #aux_rect relative to #aux_rect
#window_placement_gravity defines a point on the child window.

Returns:: the auxiliary placement gravity

auto min_width() const -> mir::optional_value<Width> const&¶

The minimum width of the window.

Returns:: the minimum width

auto min_height() const -> mir::optional_value<Height> const&¶

The minimum height of the window.

Returns:: the minimum height

auto max_width() const -> mir::optional_value<Width> const&¶

The maximum width of the window.

Returns:: the maximum width

auto max_height() const -> mir::optional_value<Height> const&¶

The maximum height of the window.

Returns:: a const refence to the maximum height

auto width_inc() const -> mir::optional_value<DeltaX> 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.

auto height_inc() const -> mir::optional_value<DeltaY> 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

auto min_aspect() const -> mir::optional_value<AspectRatio> 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

auto max_aspect() const -> mir::optional_value<AspectRatio> 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

auto parent() const -> mir::optional_value<std::weak_ptr<mir::scene::Surface>> const&¶

The parent surface of the window.

Returns:: the pending parent surface

auto input_shape() const -> mir::optional_value<std::vector<Rectangle>> 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

auto input_mode() const -> mir::optional_value<InputReceptionMode> const&¶

The input mode of the window.

Returns:: the input mode

auto shell_chrome() const -> mir::optional_value<MirShellChrome> const&¶

The shell chrome of the window.

This is currently unused.

Returns:: the shell chrome

auto confine_pointer() const -> mir::optional_value<MirPointerConfinementState> const&¶

The pointer confinement of the window.

Returns:: the pointer confinement

auto userdata() const -> mir::optional_value<std::shared_ptr<void>> 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

auto top_left() -> mir::optional_value<Point>&¶

The new position of the window frame.

Returns:: a reference to the top left point

auto size() -> mir::optional_value<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

auto name() -> mir::optional_value<std::string>&¶

The name of the window.

Returns:: the name of the window

auto output_id() -> mir::optional_value<int>&¶

The output id of the window.

See also

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

Returns:: the output id

auto type() -> mir::optional_value<MirWindowType>&¶

The type of the window.

Returns:: the type of the window

auto state() -> mir::optional_value<MirWindowState>&¶

The state of the window.

Returns:: the state of the window

auto preferred_orientation() -> mir::optional_value<MirOrientationMode>&¶

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.

auto aux_rect() -> mir::optional_value<Rectangle>&¶

Describes the auxiliary rectangle.

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

#aux_rect specifies a reference rectangle on the parent window.
#aux_rect_placement_gravity defines a specific point on #aux_rect.
#aux_rect_placement_offset: an offset on #aux_rect relative to #aux_rect
#window_placement_gravity defines a point on the child window.

Returns:: the auxiliary rectangle

auto placement_hints() -> mir::optional_value<MirPlacementHints>&¶

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

auto window_placement_gravity() -> mir::optional_value<MirPlacementGravity>&¶

Describes the placement gravity.

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

#aux_rect specifies a reference rectangle on the parent window.
#aux_rect_placement_gravity defines a specific point on #aux_rect.
#aux_rect_placement_offset: an offset on #aux_rect relative to #aux_rect
#window_placement_gravity defines a point on the child window.

Returns:: the placement gravity

auto aux_rect_placement_gravity() -> mir::optional_value<MirPlacementGravity>&¶

Describes the auxiliary rectangle placement gravity.

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

#aux_rect specifies a reference rectangle on the parent window.
#aux_rect_placement_gravity defines a specific point on #aux_rect.
#aux_rect_placement_offset: an offset on #aux_rect relative to #aux_rect
#window_placement_gravity defines a point on the child window.

Returns:: the auxiliary placement gravity

auto aux_rect_placement_offset() -> mir::optional_value<Displacement>&¶

Describes the auxiliary rectangle placement offset.

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

#aux_rect specifies a reference rectangle on the parent window.
#aux_rect_placement_gravity defines a specific point on #aux_rect.
#aux_rect_placement_offset: an offset on #aux_rect relative to #aux_rect
#window_placement_gravity defines a point on the child window.

Returns:: the auxiliary placement gravity

auto min_width() -> mir::optional_value<Width>&¶

The minimum width of the window.

Returns:: the minimum width

auto min_height() -> mir::optional_value<Height>&¶

The minimum height of the window.

Returns:: the minimum height

auto max_width() -> mir::optional_value<Width>&¶

The maximum width of the window.

Returns:: the maximum width

auto max_height() -> mir::optional_value<Height>&¶

The maximum height of the window.

Returns:: a refence to the maximum height

auto width_inc() -> mir::optional_value<DeltaX>&¶

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

auto height_inc() -> mir::optional_value<DeltaY>&¶

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

auto min_aspect() -> mir::optional_value<AspectRatio>&¶

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

auto max_aspect() -> mir::optional_value<AspectRatio>&¶

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

auto parent() -> mir::optional_value<std::weak_ptr<mir::scene::Surface>>&¶

The parent of this window.

Returns:: the parent of this window

auto input_shape() -> mir::optional_value<std::vector<Rectangle>>&¶

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

auto input_mode() -> mir::optional_value<InputReceptionMode>&¶

The input mode of the window.

Returns:: the input mode

auto shell_chrome() -> mir::optional_value<MirShellChrome>&¶

The shell chrome of the window.

This is currently unused.

Returns:: the shell chrome

auto confine_pointer() -> mir::optional_value<MirPointerConfinementState>&¶

The pointer confinement of the window.

Returns:: the pointer confinement

auto userdata() -> mir::optional_value<std::shared_ptr<void>>&¶

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

auto depth_layer() const -> mir::optional_value<MirDepthLayer> 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

auto depth_layer() -> mir::optional_value<MirDepthLayer>&¶

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

Returns:: the depth layer

auto attached_edges() const -> mir::optional_value<MirPlacementGravity> 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

auto attached_edges() -> mir::optional_value<MirPlacementGravity>&¶

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

Returns:: the edges

auto exclusive_rect() const -> mir::optional_value<mir::optional_value<mir::geometry::Rectangle>> 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

auto exclusive_rect() -> mir::optional_value<mir::optional_value<mir::geometry::Rectangle>>&¶

The area over which the window should not be occluded.

Returns:: the exclusive rectangle

auto ignore_exclusion_zones() const -> mir::optional_value<bool> 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

auto ignore_exclusion_zones() -> mir::optional_value<bool>&¶

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

auto application_id() const -> mir::optional_value<std::string> 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

auto application_id() -> mir::optional_value<std::string>&¶

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

auto server_side_decorated() const -> mir::optional_value<bool> const&¶

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

Returns:: the flag

auto server_side_decorated() -> mir::optional_value<bool>&¶

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

Returns:: the flag

auto focus_mode() const -> mir::optional_value<MirFocusMode> const&¶

Describes how the window should gain and lose focus.

Returns:: the focus mode

auto focus_mode() -> mir::optional_value<MirFocusMode>&¶

Describes how the window should gain and lose focus.

Returns:: the focus mode

auto visible_on_lock_screen() const -> mir::optional_value<bool> const&¶

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

Returns:: the flag

auto visible_on_lock_screen() -> mir::optional_value<bool>&¶

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

Returns:: the flag

auto tiled_edges() const -> mir::optional_value<mir::Flags<MirTiledEdge>> const&¶

Describes which edges are touching part of the tiling grid.

Remark

Since MirAL 5.3

Returns:: the tiled edges

auto tiled_edges() -> mir::optional_value<mir::Flags<MirTiledEdge>>&¶

Describes which edges are touching part of the tiling grid.

Remark

Since MirAL 5.3

Returns:: the tiled edges

auto to_surface_specification() const -> mir::shell::SurfaceSpecification¶

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 Members

unsigned width¶

unsigned height¶