Class WindowManagementPolicy

Inheritance Relationships

Derived Types

Class Documentation

class WindowManagementPolicy

An interface that defines the window management policy for the compositor.

Compositor authors may implement this interface to provide custom behavior in response to events in the compositor. For example, the author may override WindowManagementPolicy::advise_new_window to perform some action when a new window becomes available.

Instances of this class are often used in conjunction with miral::add_window_manager_policy.

Methods that are prefixed with “advise_*” are notifications that originate from the compositor. The policy need only implement these methods when it requires these notifications to manage its internal state.

Methods that are prefixed with “handle_*” are requests that originate from the client applications. The policy is expected to take some action in response to these requests.

See also

miral::add_window_manager_policy - provides a way to add a window management policy to the server

See also

miral::WindowManagerOptions - provides a way to add and control multiple window management policies for the server

See also

miral::MinimalWindowManager - an implementation of the WindowManagementPolicy that serves as a strong foundation for a floating window manager

See also

miral::WindowManagerTools - tools provided to the policy via miral::add_window_manager_policy

Subclassed by miral::CanonicalWindowManagerPolicy, miral::MinimalWindowManager

notification of changes to the current application zones

An application zone is the area a maximized application will fill.

There is often (but not necessarily) one zone per output. The areas normal applications windows should avoid (such as the areas covered by panels) will not be part of an application zone

virtual void advise_application_zone_create(Zone const &application_zone)

Notification that an application zone has been created.

An application zone defines the area in which normal applications should be placed. For example, an application zone may take up an entire output except for the areas covered by panels or task bars.

An application zone is often created per output, but this does not have to be the case.

Parameters:

application_zone – the new application zone

virtual void advise_application_zone_update(Zone const &updated, Zone const &original)

Notification that an application zone has been updated.

Parameters:

  • updated – the new application zone

  • original – the old application zone

virtual void advise_application_zone_delete(Zone const &application_zone)

Notification that an application zone has been removed.

Parameters:

application_zone – the removed zone

virtual ~WindowManagementPolicy()
WindowManagementPolicy() = default
WindowManagementPolicy(WindowManagementPolicy const&) = delete
WindowManagementPolicy &operator=(WindowManagementPolicy const&) = delete

Public Functions

virtual void advise_begin()

First notification of a group of related handle_..., confirm_... and advise_... calls.

virtual void advise_end()

Final notification of a group of related handle_..., confirm_... and advise_... calls.

virtual auto place_new_window(ApplicationInfo const &app_info, WindowSpecification const &requested_specification) -> WindowSpecification = 0

Given the app_info and requested_specification, this method returns a new miral::WindowSpecification that defines how the new window should be placed.

This method is called before advise_new_window.

Parameters:

  • app_info – the application requesting a new window

  • requested_specification – the requested specification with a default position and size

Returns:

the customized placement

virtual void handle_window_ready(WindowInfo &window_info) = 0

Notification that the first buffer for this window has been posted.

Parameters:

window_info – the window that posted the buffer

virtual void handle_modify_window(WindowInfo &window_info, WindowSpecification const &modifications) = 0

Request from the client that the window given by window_info should be modified with the modification.

The compositor author should use miral::WindowManagerTools::modify_window to make the appropriate changes. The compositor may choose to honor, change, or ignore any of the requested modifications.

See also

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

Parameters:

  • window_info – the window

  • modifications – the requested changes

virtual void handle_raise_window(WindowInfo &window_info) = 0

Request from the client to raise the window.

The compositor author may use miral::WindowManagerTools::raise_tree in response, or they may choose to do anything else.

See also

miral::WindowManagerTools::raise_tree - the method used to raise a window

Parameters:

window_info – the window

virtual auto confirm_placement_on_display(WindowInfo const &window_info, MirWindowState new_state, Rectangle const &new_placement) -> Rectangle = 0

Confirm and optionally adjust the placement of a window on the display.

This is called when placing a fullscreen, maximized, horizontally maximized, and vertically maximized window to allow adjustment for decorations.

If the author wishes to do nothing in response, they may simply return new_placement.

Parameters:

  • window_info – the window

  • new_state – the new state

  • new_placement – the suggested placement

Returns:

the final placement

virtual bool handle_keyboard_event(MirKeyboardEvent const *event) = 0

Handle a keyboard event originating from the user.

Parameters:

event – the keyboard event

Returns:

true if the policy consumed the event, otherwise false

virtual bool handle_touch_event(MirTouchEvent const *event) = 0

Handle a touch event originating from the user.

Parameters:

event – the touch event

Returns:

true if the policy consumed the event, otherwise false

virtual bool handle_pointer_event(MirPointerEvent const *event) = 0

Handle a pointer event originating from the user.

Parameters:

event – the pointer event

Returns:

true if the policy consumed the event, otherwise false

virtual void advise_new_app(ApplicationInfo &application)

Notification that a new application has connected.

Parameters:

application – the application

virtual void advise_delete_app(ApplicationInfo const &application)

Notification that an application has disconnected.

Parameters:

application – the application

virtual void advise_new_window(WindowInfo const &window_info)

Notification that a window has been created.

Parameters:

window_info – the window

virtual void advise_focus_lost(WindowInfo const &window_info)

Notification that a window has lost focus.

Parameters:

window_info – the window

virtual void advise_focus_gained(WindowInfo const &window_info)

Notification that a window has gained focus.

Parameters:

window_info – the window

virtual void advise_state_change(WindowInfo const &window_info, MirWindowState state)

Notification that a window is about to change state.

Parameters:

  • window_info – the window

  • state – the new state

virtual void advise_move_to(WindowInfo const &window_info, Point top_left)

Notification that a window is about to move.

Parameters:

  • window_info – the window

  • top_left – the new position

virtual void advise_resize(WindowInfo const &window_info, Size const &new_size)

Notification that a window is about to resize.

Parameters:

  • window_info – the window

  • new_size – the new size

virtual void advise_delete_window(WindowInfo const &window_info)

Notification that a window is about to be destroyed.

Parameters:

window_info – the window

virtual void advise_raise(std::vector<Window> const &windows)

Notification that the provided windows are being raised to the top.

These windows are ordered with parents before children and form a single tree rooted at the first element.

Parameters:

windows – the windows being raised

Note

The relative Z-order of these windows will be maintained, they will be raised en bloc.

virtual void advise_adding_to_workspace(std::shared_ptr<Workspace> const &workspace, std::vector<Window> const &windows)

Notification that windows are being added to a workspace.

These windows are ordered with parents before children, and form a single tree rooted at the first element.

See also

miral::WindowManagerTools::add_tree_to_workspace - called to add windows to a workspace

Parameters:

  • workspace – the workspace

  • windows – the windows

virtual void advise_removing_from_workspace(std::shared_ptr<Workspace> const &workspace, std::vector<Window> const &windows)

Notification that windows are being removed from a workspace.

These windows are ordered with parents before children, and form a single tree rooted at the first element.

See also

miral::WindowManagerTools::remove_tree_from_workspace - called to remove windows from a workspace

Parameters:

  • workspace – the workspace

  • windows – the windows

virtual void handle_request_move(WindowInfo &window_info, MirInputEvent const *input_event) = 0

Request from the client to initiate a move.

Parameters:

  • window_info – the window

  • input_event – the input event causing the movement request

virtual void handle_request_resize(WindowInfo &window_info, MirInputEvent const *input_event, MirResizeEdge edge) = 0

Request from a client to initiate a resize.

See also

MirResizeEdge - edge resize options

Parameters:

  • window_info – the window

  • input_event – the input event causing the resize request

  • edge – the edge being resized

virtual void advise_output_create(Output const &output)

Notification that an output has been created.

Parameters:

output – the new output

virtual void advise_output_update(Output const &updated, Output const &original)

Notification that an output has had one or more of its properties changed.

Parameters:

  • updated – the updated output

  • original – the old output

virtual void advise_output_delete(Output const &output)

Notification that an output has been removed.

Parameters:

output – the deleted output

virtual auto confirm_inherited_move(WindowInfo const &window_info, Displacement movement) -> Rectangle = 0

When a parent window is moved, this method will be called for each child window so that the compositor can optionally adjust the target position.

A default implementation is to simply add the displacement to the current positon of the window.

Parameters:

  • window_info – the window

  • movement – the movement of the parent

Returns:

the confirmed placement of the window