Class WindowManagerTools

Class Documentation

class WindowManagerTools

This class provides compositor authors with facilities to query state info for and request changes to elements of the window management model (such as windows and outputs).

When a #WindowManagementPolicy is added to a miral::MirRunner via miral::add_window_manager_policy, the policy will receive an instance of miral::WindowManagerTools as the first parameter. Compositor authors are encouraged to use this class instance to handle and request changes from the underlying Mir server.

Public Functions

explicit WindowManagerTools(WindowManagerToolsImplementation *tools)

Constructs an instance of window manager tools from an implementation.

Compositor authors are not expected to construct this object themselves. Instead, they should use miral::add_window_manager_policy to create an instance of this class for them. For this reason, #miral::WindowManagerToolsImplementation is purposefully opaque.

WindowManagerTools(WindowManagerTools const&)
WindowManagerTools &operator=(WindowManagerTools const&)
~WindowManagerTools()
auto count_applications() const -> unsigned int

Returns the number of applications.

Returns:

the number of applications

void for_each_application(std::function<void(ApplicationInfo &info)> const &functor)

Execute a functor for each application.

Parameters:

functor – called for each application

auto find_application(std::function<bool(ApplicationInfo const &info)> const &predicate) -> Application

find an application meeting the predicate

Parameters:

  • predicate – the predicate

  • predicate – the predicate

Returns:

the application Find an application that meets the predicate.

Returns:

an application, or a null application if none is found

auto info_for(std::weak_ptr<mir::scene::Session> const &session) const -> ApplicationInfo&

Retrieve information about a session.

See also

miral::ApplicationInfo - info about the application

Parameters:

session – the application

Returns:

info about the application

Pre:

the session is valid (not null)

auto info_for(std::weak_ptr<mir::scene::Surface> const &surface) const -> WindowInfo&

Retrieve info about a window from the surface.

See also

miral::WindowInfo - info about the window

Parameters:

surface – the surface

Returns:

info about the window

Pre:

the session is valid (not null)

auto info_for(Window const &window) const -> WindowInfo&

Retrieve info about a window.

See also

miral::WindowInfo - info about the window

Parameters:

window – the window

Returns:

info about the window

Pre:

the session is valid (not null)

auto info_for_window_id(std::string const &id) const -> WindowInfo&

Retrieve info for a persistent surface id.

Deprecated:

’Persistent’ surface IDs were part of mirclient API

Parameters:

id – the persistent surface id

Throws:

  • invalid_argument – if the id is badly formatted

  • runtime_error – if the id doesn’t identify a current window

Returns:

the info

auto id_for_window(Window const &window) const -> std::string

Retrieve the persistent surface id for a window.

Deprecated:

’Persistent’ surface IDs were part of mirclient API

Parameters:

window – the window

Returns:

the persistent surface id

void ask_client_to_close(Window const &window)

Send a close request to the window.

Parameters:

window – the window

auto active_window() const -> Window

Retrieve the active window.

If no window is active, then this will be the default-constructed window.

Returns:

the active window

auto select_active_window(Window const &hint) -> Window

Select a new active window based on the hint.

Not all windows can become active - either because of their type or other state. But there will typically be an associated parent or child window that can become active.

Parameters:

hint – the window hint

Returns:

the new active window

void drag_active_window(mir::geometry::Displacement movement)

Drags the active window by the provided displacement.

Parameters:

movement – the displacement to move by

void drag_window(Window const &window, mir::geometry::Displacement movement)

Drag the provided window by the provided displacement.

Parameters:

  • window – the window to move

  • movement – the displacement to move by

void focus_next_application()

Make the next application in the focus order after the currently focused application active.

“Next” is defined as the next most-recently focused application.

void focus_prev_application()

Make the previous application in the focus order after the currently focused application active.

“Previous” is defined as the least-recently focused application.

void focus_next_within_application()

Focus the next window within the currently active application.

“Next” is defined as the next most-recently focused window.

void focus_prev_within_application()

Focus the previous window within the currently active application.

“Previous” is defined as the least-recently focused window.

auto window_to_select_application(const Application) const -> std::optional<Window>

Returns the window of the given application that should be selected.

Returns:

the window to select, or std::nullopt if none are found

auto can_select_window(Window const &window) const -> bool

Check if the provided window can be selected.

Remark

Since MirAL 5.0

Parameters:

window – the window

Returns:

true if the window can be selected, otherwise false

auto window_at(mir::geometry::Point cursor) const -> Window

Find the topmost window at the cursor.

Parameters:

cursor – a point

Returns:

the window under the cursor, or the default-constructed window if none exists

auto active_output() -> mir::geometry::Rectangle const

Find the area of the active output.

Returns:

the area of the active output

auto active_application_zone() const -> Zone

Find the active zone area.

Returns:

the active zone

void raise_tree(Window const &root)

Raise the provided window and its children to the top of the Z-order.

Parameters:

root – the window to raise

void swap_tree_order(Window const &first, Window const &second)

Swaps the position of the windows in regard to Z-order.

Parameters:

  • first – the first window

  • second – the second window

void send_tree_to_back(Window const &root)

Moves the window to the bottom of the Z order.

Parameters:

root – the window to send to the back of the Z order

void modify_window(WindowInfo &window_info, WindowSpecification const &modifications)

Modify the provided window with the provided modifications.

Parameters:

  • window_info – the window to modify

  • modifications – the modification sto make on the window

void modify_window(Window const &window, WindowSpecification const &modifications)

Modify the provided window with the provided modifications.

Parameters:

  • window – the window to modify

  • modifications – the modification sto make on the window

void place_and_size_for_state(WindowSpecification &modifications, WindowInfo const &window_info) const

Set a default size and position to reflect state change.

This method has no effect when WindowSpecification::state is unset.

Parameters:

  • modifications – modifications, with state() set

  • window_info – the window to modify

auto create_workspace() -> std::shared_ptr<Workspace>

Create a workspace.

Returns:

the created workspace

void add_tree_to_workspace(Window const &window, std::shared_ptr<Workspace> const &workspace)

Add the window to the workspace.

A window may be added to more than one workspace.

The #miral::Workspace is a purely associative contract. It is the job of the compositor author to define what this means for their particular use case. For example, the author may make it such that a particular workspace be “active” and only windows on the active workspace are shown.

Parameters:

  • window – the window

  • workspace – the workspace

void remove_tree_from_workspace(Window const &window, std::shared_ptr<Workspace> const &workspace)

Remove the window from the workspace.

Parameters:

  • window – the window

  • workspace – the workspace

void move_workspace_content_to_workspace(std::shared_ptr<Workspace> const &to_workspace, std::shared_ptr<Workspace> const &from_workspace)

Move the windows associated with one workspace to another.

Parameters:

  • to_workspace – the workspace to move windows to

  • from_workspace – the workspace to move windows from

void for_each_workspace_containing(Window const &window, std::function<void(std::shared_ptr<Workspace> const &workspace)> const &callback)

Invoke the callback for each workspace that contains the window.

Parameters:

  • window – the window

  • callback – called for each workspace that the window is a member of

Warning

It is unsafe to add or remove windows from workspace from the callback during enumeration.

void for_each_window_in_workspace(std::shared_ptr<Workspace> const &workspace, std::function<void(Window const &window)> const &callback)

Invoke the callback on each window contained in the workspace.

Parameters:

  • workspace – the workspace

  • callback – called for each window in the workspace

Warning

It is unsafe to add or remove windows from workspace from the callback during enumeration.

void invoke_under_lock(std::function<void()> const &callback)

Invoke the given callback under the lock.

This method allows threads that do not hold a lock on the model to acquire one and call any relevant member functions.

This should NOT be used by a thread that has called the miral::WindowManagementPolicy methods, as they already hold the lock.

Parameters:

callback – the method to call under lock

void move_cursor_to(mir::geometry::PointF point)

Move the cursor to the provided \point.

If the point is beyond the range of the outputs, the point is clamped to the output area.

Parameters:

point – to move the cursor to