Class WaylandExtensions

Nested Relationships

Nested Types

Class Documentation

class WaylandExtensions

Enable configuration of the Wayland extensions enabled at runtime.

This adds the command line options ‘—wayland-extensions’, ‘—add-wayland-extensions’, ‘—drop-wayland-extensions’ and the corresponding MIR_SERVER_* environment variables and config file options.

  • The server can add support for additional extensions

  • The server can specify the configuration defaults

  • Mir’s option handling allows the defaults to be overridden

    Remark

    Since MirAL 2.4

Unnamed Group

static char const *const zwlr_layer_shell_v1

Supported wayland extensions that are not enabled by default.

These can be passed into WaylandExtensions::enable() to turn them on. Enables shell components such as panels, notifications and lock screens. It is recommended to use this in conjunction with conditionally_enable() as malicious clients could potentially use this protocol to steal input focus or otherwise bother the user.

Remark

Since MirAL 2.6

static char const *const zxdg_output_manager_v1

Allows clients to retrieve additional information about outputs.

Remark

Since MirAL 2.6

static char const *const zwlr_foreign_toplevel_manager_v1

Allows a client to get information and gain control over all toplevels of all clients Useful for taskbars and app switchers Could allow a client to extract information about other programs the user is running.

Remark

Since MirAL 3.1

static char const *const zwp_virtual_keyboard_manager_v1

Allows clients to act as a virtual keyboard, useful for on-screen keyboards. Clients are not required to display anything to send keyboard events using this extension, so malicious clients could use it to take actions without user input.

Remark

Since MirAL 3.4

static const char *const zwp_input_method_v1

Allows clients (such as on-screen keyboards) to intercept physical key events and act as a source of text input for other clients. Input methods are not required to display anything to use this extension, so malicious clients could use it to intercept keys events or take actions without user input.

Remark

Since MirAL 3.10

static const char *const zwp_input_panel_v1

Allows clients to display a surface as an input panel surface. The input panel surface is shown when a text input is active and hidden otherwise. The panel itself can either be attached to the edge of the screen or set to float near the active input. This is often used in conjunction with zwp_input_method_v1.

Remark

Since MirAL 3.10

static char const *const zwp_input_method_manager_v2

Allows clients (such as on-screen keyboards) to intercept physical key events and act as a source of text input for other clients. Input methods are not required to display anything to use this extension, so malicious clients could use it to intercept keys events or take actions without user input.

Remark

Since MirAL 3.4

static char const *const zwlr_screencopy_manager_v1

Allows clients to take screenshots and record the screen. Only enable for clients that are trusted to view all displayed content, including windows of other apps.

Remark

Since MirAL 3.5

static char const *const zwlr_virtual_pointer_manager_v1

Allows clients to act as a virtual pointer, useful for remote control and automation. Clients are not required to display anything to send pointer events using this extension, so malicious clients could use it to take actions without user input.

Remark

Since MirAL 3.6

static char const *const ext_session_lock_manager_v1

Allows clients to act as a screen lock.

Remark

Since MirAL 3.6

void add_extension(Builder const &builder)

Add a bespoke Wayland extension both to “supported” and “enabled by default”.

Remark

Since MirAL 2.5

void add_extension_disabled_by_default(Builder const &builder)

Add a bespoke Wayland extension both to “supported” but not “enabled by default”.

Remark

Since MirAL 2.5

auto enable(std::string name) -> WaylandExtensions&

Enable a Wayland extension by default. The user can still disable it with the drop-wayland-extensions or wayland-extensions options. The extension can be forced to be enabled regardless of user options with conditionally_enable().

Remark

Since MirAL 2.6

auto disable(std::string name) -> WaylandExtensions&

Disable a Wayland extension by default. The user can still enable it with the add-wayland-extensions or wayland-extensions options. The extension can be forced to be disabled regardless of user options with conditionally_enable().

Remark

Since MirAL 2.6

auto conditionally_enable(std::string name, EnableCallback const &callback) -> WaylandExtensions&

Enable a Wayland extension only when the callback returns true. The callback can use info.user_preference() to respect the extension options the user provided, it is not required. Unlike enable() and disable(), conditionally_enable() can override the user options. The callback may be called multiple times for a each client/extension pair (for example, once each time a client creates or destroys a wl_registry). All client processing will be blocked while the callback is being executed. To minimise the impact on client responsiveness users may want to cache the result of any expensive checks made in the callback.

Remark

Since MirAL 3.4

static auto recommended() -> std::set<std::string>

The set of Wayland extensions that Mir recommends. Also the set that is enabled by default upon construction of a WaylandExtensions object.

Remark

Since MirAL 2.6

static auto supported() -> std::set<std::string>

The set of Wayland extensions that core Mir supports. Does not include bespoke extensions A superset of recommended()

Remark

Since MirAL 2.6

Public Types

using Filter = std::function<bool(Application const &app, char const *protocol)>

Remark

Since MirAL 2.5

using EnableCallback = std::function<bool(EnableInfo const &info)>

Remark

Since MirAL 3.4

Public Functions

WaylandExtensions()

Default to enabling the extensions recommended by Mir.

void operator()(mir::Server &server) const
~WaylandExtensions()
WaylandExtensions(WaylandExtensions const&)
auto operator=(WaylandExtensions const&) -> WaylandExtensions&
auto all_supported() const -> std::set<std::string>

All Wayland extensions supported. This includes both the supported() provided by Mir and any extensions that have been added using add_extension().

Remark

Since MirAL 3.0

struct Builder

A Builder creates and registers an extension protocol.

Remark

Since MirAL 2.5

Public Members

std::string name

Name of the protocol extension’s Wayland global.

std::function< std::shared_ptr< void >Context const  *context)> build

Functor that creates and registers an extension protocol.

Param context:

giving access to:

  • the wl_display (so that, for example, the extension can be registered); and,

  • allowing server initiated code to be executed on the Wayland mainloop.

Return:

a shared pointer to the implementation. (Mir will manage the lifetime)

class Context

Context information useful for implementing Wayland extensions.

Remark

Since MirAL 2.5

Public Functions

virtual auto display() const -> wl_display* = 0
virtual void run_on_wayland_mainloop(std::function<void()> &&work) const = 0

Protected Functions

Context() = default
virtual ~Context() = default
Context(Context const&) = delete
Context &operator=(Context const&) = delete
class EnableInfo

Information that can be used to determine if to enable a conditionally enabled extension.

Remark

Since MirAL 3.4

Public Functions

auto app() const -> Application const&

The application that is being given access to this extension.

auto name() const -> const char*

The name of the extension/global, always the same as given to conditionally_enable()

auto user_preference() const -> std::optional<bool>

If the user has enabled or disabled this extension one of the wayland extension Mir options.