Class DisplayConfiguration

• Defined in File display_configuration.h

Nested Relationships

Nested Types

• Class DisplayConfiguration::Node

Class Documentation

class DisplayConfiguration

Enables loading the display configuration from a file.

The display configuration file name is provided by miral::MirRunner::display_config_file. Mir searches for this file in each of the following directories in order, per the XDG Base Directory Specification:

1. $XDG_CONFIG_HOME or $HOME/.config 2.$XDG_CONFIG_DIRS`

Once a file is found, the remaining directories are not searched.

If no file is found, a default display configuration will be written to either $XDG_CONFIG_HOME or $HOME/.config. Please see this default file for more information about content expected from this project.

Mir will continue to monitor the configuration file as it runs.

Additionally, the selected layout of the file may be overridden using a corresponding file: miral::MirRunner::display_config_file() + “-layout”, which will also be monitored.

Public Functions

explicit DisplayConfiguration(MirRunner const &mir_runner)

Construct the display configuration.

The configuration file will be loaded from the provided mir runner via miral::MirRunner::display_config_file.

The configuration is loaded by #DisplayConfiguration::operator()(mir::Server&).

Parameters:

mir_runner – the mir runner

auto layout_option() -> ConfigurationOption

Create a --display-layout configuration option.

Note that this must be provided to miral::MirRunner::run_with in order to work.

Returns:

a new configuration option

void select_layout(std::string const &layout)

Select a layout from the configuration.

If the layout is not present in the configuration, the ‘default’ layout is applied.

Parameters:

layout – the desired layout

auto list_layouts() -> std::vector<std::string>

List the valid layouts from the configuration file.

Returns:

the list of valid layouts

void add_output_attribute(std::string const &key)

Enable a custom output attribute in the configuration file.

The value of this attribute will be made available through #miral::UserDisplayConfigurationOutput::custom_attribute at the key.

The value in the YAML file is expected to be a string.

Parameters:

key – the key to enable

auto layout_userdata(std::string const &key) const -> std::optional<std::any const>

Retrieve the user data associated with the active layout for the provided key.

Callers should provide this user data via miral::DisplayConfiguration::layout_userdata_builder.

Remark

Since MirAL 5.3

Parameters:

key – the key to retrieve

Returns:

Arbitrary userdata, if any

void layout_userdata_builder(std::string const &key, std::function<std::any(Node const &value)> const &builder) const

Enable a custom layout attribute in the configuration file.

The caller must provide the key of this custom attribute in addition to a builder function that will be used to build the custom payload that is associated with the layout. This function is provided with the raw details of the node at the provided key.

The function can return any piece of data. This data may later be retrieved via miral::DisplayConfiguration::layout_userdata.

Remark

Since MirAL 5.3

See also

miral::DisplayConfiguration::Node - the node provided as a parameter to the builder

Parameters:

• key – the key for the data

• builder – a builder function that takes the content of the node at the key as a parameter and returns an arbitrary payload

void operator()(mir::Server &server) const

~DisplayConfiguration()

DisplayConfiguration(DisplayConfiguration const&)

auto operator=(DisplayConfiguration const&) -> DisplayConfiguration&

class Node

A class providing access to an arbitrary piece of data from the miral::DisplayConfiguration.

This is specifically useful when a user wants to extend the basic display configuration with some sort of custom payload (e.g. a user may want to extend the layout configuration with information describing the position and size of specific applications).

Remark

Since MirAL 5.3

Public Types

enum class Type

Values:

enumerator integer

enumerator string

enumerator sequence

enumerator map

enumerator unknown

Public Functions

auto type() const -> Type

The type of the node.

Once resolved, the user can call the appropriate methods on the object. For example, if the type is Type::string, users can safely call as_string.

Returns:

the node type

auto as_string() const -> std::string

Returns the content of the node as a std::string.

If the node does not have a type of Type::string, this will cause a fatal error.

Returns:

the node as a string

auto as_int() const -> int

If the node does not have a type of Type::integer, this will cause a fatal error.

Returns:

the node as an integer

void for_each(std::function<void(Node const&)> const &f) const

Iterate over the children of this node.

If the node does not have a type of Type::sequence, this will cause a fatal error.

Parameters:

f – function to all on each child node

auto has(std::string const &key) const -> bool

Check if the node has a value at the given key.

If the node does not have a type of Type::map, this will cause a fatal error.

Parameters:

key – the key to check for existence

Returns:

true if the key exists, otherwise false

auto at(std::string const &key) const -> std::optional<Node>

Get the node at the given key.

If the node does not have a type of Type::map, this will cause a fatal error.

Parameters:

key – the key to get

Returns:

the node at the key, or std::nullopt if none exists

Node(Node&&) noexcept

Node &operator=(Node&&) noexcept

Node(Node const&) = delete

Node &operator=(Node const&) = delete

~Node()