Introducing the Miral API

The main() program

The main() program from miral-shell looks like this:

* Copyright © Canonical Ltd.
* This program is free software: you can redistribute it and/or modify
* under the terms of the GNU General Public License version 2 or 3 as
* published by the Free Software Foundation.
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* GNU General Public License for more details.
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
#include "spinner/splash.h"
#include <miral/runner.h>
#include <miral/keymap.h>
#include <xkbcommon/xkbcommon-keysyms.h>
int main(int argc, char const* argv[])
using namespace miral;
using namespace miral::toolkit;
std::function<void()> shutdown_hook{[]{}};
SpinnerSplash spinner;
WindowManagerOptions window_managers
add_window_manager_policy<FloatingWindowManagerPolicy>("floating", spinner, launcher, shutdown_hook),
add_window_manager_policy<TilingWindowManagerPolicy>("tiling", spinner, launcher),
MirRunner runner{argc, argv};
runner.add_stop_callback([&] { shutdown_hook(); });
ExternalClientLauncher external_client_launcher;
std::string terminal_cmd{"miral-terminal"};
auto const quit_on_ctrl_alt_bksp = [&](MirEvent const* event)
return false;
MirInputEvent const* input_event = mir_event_get_input_event(event);
return false;
MirKeyboardEvent const* kev = mir_input_event_get_keyboard_event(input_event);
return false;
return false;
case XKB_KEY_BackSpace:
return true;
case XKB_KEY_t:
case XKB_KEY_T:
return false;
case XKB_KEY_x:
case XKB_KEY_X:
return false;
return false;
Keymap config_keymap;
auto run_startup_apps = [&](std::string const& apps)
for (auto i = begin(apps); i != end(apps); )
auto const j = find(i, end(apps), ':');
external_client_launcher.launch(std::vector<std::string>{std::string{i, j}});
if ((i = j) != end(apps)) ++i;
return runner.run_with(
ConfigurationOption{run_startup_apps, "startup-apps", "Colon separated list of startup apps", ""},
pre_init(ConfigurationOption{[&](std::string const& typeface) { ::wallpaper::font_file(typeface); },
"shell-wallpaper-font", "font file to use for wallpaper", ::wallpaper::font_file()}),
ConfigurationOption{[&](std::string const& cmd) { terminal_cmd = cmd; },
"shell-terminal-emulator", "terminal emulator to use", terminal_cmd}
struct MirEvent MirEvent
Definition: append_event_filter.h:23
Definition: splash.h:23
Definition: append_event_filter.h:30
Add a user configuration option to Mir's option handling. By default the callback will be invoked fol...
Definition: configuration_option.h:40
Load an X-cursor theme, either the supplied default, or through the –cursor-theme config option.
Definition: cursor_theme.h:28
Definition: external_client.h:31
auto launch(std::vector< std::string > const &command_line) const -> pid_t
Launch with client environment configured for Wayland. If X11 is enabled, then DISPLAY will also be s...
auto launch_using_x11(std::vector< std::string > const &command_line) const -> pid_t
If X11 is enabled, then launch with client environment configured for X11. For the occasions it is de...
Definition: internal_client.h:58
Load a keymap.
Definition: keymap.h:29
Runner for applying initialization options to Mir.
Definition: runner.h:41
void add_stop_callback(std::function< void()> const &stop_callback)
Add a callback to be invoked when the server is about to stop, If multiple callbacks are added they w...
Wrapper for running an internal Mir client at startup.
Definition: internal_client.h:38
Enable configuration of the Wayland extensions enabled at runtime.
Definition: wayland_extensions.h:47
Definition: window_management_options.h:52
Add a user configuration option for X11 support.
Definition: x11_support.h:29
@ mir_input_event_type_key
Definition: enums.h:46
@ mir_event_type_input
Definition: enums.h:38
@ mir_keyboard_action_down
Definition: enums.h:86
@ mir_input_event_modifier_ctrl
Definition: enums.h:67
@ mir_input_event_modifier_alt
Definition: enums.h:59
unsigned int MirInputEventModifiers
Definition: enums.h:77
int main(int argc, char const *argv[])
Definition: kiosk_main.cpp:83
Definition: toolkit_event.h:40
MirKeyboardEvent const * mir_input_event_get_keyboard_event(MirInputEvent const *event)
Retrieve the MirKeyboardEvent associated with a given input event.
MirInputEvent const * mir_event_get_input_event(MirEvent const *event)
Retrieve the MirInputEvent associated with a MirEvent of type mir_event_type_input.
MirInputEventType mir_input_event_get_type(MirInputEvent const *event)
Retrieve the type of an input event.
MirKeyboardAction mir_keyboard_event_action(MirKeyboardEvent const *event)
Retrieve the action which triggered a given key event.
xkb_keysym_t mir_keyboard_event_keysym(MirKeyboardEvent const *event)
Retrieve the xkb mapped keysym associated with the key acted on.
MirEventType mir_event_get_type(MirEvent const *event)
Retrieves the type of a MirEvent.
MirInputEventModifiers mir_keyboard_event_modifiers(MirKeyboardEvent const *event)
Retrieve the modifier keys pressed when the key action occured.
Mir Abstraction Layer.
Definition: runner.h:35
void display_configuration_options(mir::Server &server)
Enable the display configuration options.
auto pre_init(ConfigurationOption const &clo) -> ConfigurationOption
Update the option to be called back before Mir initialization starts.
void font_file(std::string const &font_file)
Definition: wallpaper_config.cpp:85

This shell is providing FloatingWindowManagerPolicy, TilingWindowManagerPolicy and SpinnerSplash. The rest is from MirAL.

If you look for the corresponding code in lp:qtmir and lp:mir you’ll find it less clear, more verbose and scattered over multiple files.

A shell has to provide a window management policy (miral-shell provides two: FloatingWindowManagerPolicy and TilingWindowManagerPolicy). A window management policy needs to implement the miral::WindowManagementPolicy interface for handling a set of window management events.

The way these events are handled determines the behaviour of the shell.

The miral::WindowManagerTools interface provides the principle methods for a window management policy to control Mir.

Copyright © 2012-2023 Canonical Ltd.
Generated on Tue 2 May 10:01:24 UTC 2023
This documentation is licensed under the GPL version 2 or 3.