miracle-wm/USERGUIDE.md

This user manual will keep up to date with the current state of the project. Please note that the information in here is likely to change with future release.

Built-in Key Commands

• meta + enter: Open new terminal
• meta + h: Switch current lane to horizontal layout mode
• meta + v: Switch current lane to vertical layout mode
• meta + shift + up: Move selected window up in the tree
• meta + shift + down: Move selected window down in the tree
• meta + shift + left: Move selected window left in the tree
• meta + shift + right: Move selected window right in the tree
• meta + up: Select the window above the currently selected window
• meta + down: Select the window below the currently selected window
• meta + left: Select the window to the left of the currently selected window
• meta + right: Select the window to the right of the currently selected window
• meta + r: Toggle resize mode on the active node
  • meta + left: Resize to the left
  • meta + right: Resize to the right
  • meta + up: Resize upward
  • meta + down: Resize downward
• meta + shift + q: Quit the selected application
• meta + shift + e: Close the compositor
• meta + f: Toggle fullscreen on the window
• meta + [0-9]: Move to workspace n
• meta + shift + [0-9]: Move active window to workspace n

Pointer Behavior

• Hovering over a window will select the window
• Windows may be minimized, maximized, or removed using the toolbar icons
• Window CANNOT be resized or moved with the pointer

Configuration File

Location

The configuration file will be written blank the first time that you start the compositor. The file is named miracle-wm.yaml and it is written to your config directory, most likely at ~/.config/miracle-wm.yaml.

Types

First, let's define some reoccurring data types in the configuration file:

// Represents a modifier to be used in conjunction with another key press (e.g. Ctrl + Alt + Delete; Ctrl and Alt would be modifiers)
typedef ModifierKey =
  "alt" | "alt_left" | "alt_right" | "shift" | "shift_left" | "shift_right" | "sym" | "function" | "ctrl"
  | "ctrl_left" | "ctrl_right" | "meta" | "meta_left" | "meta_right" | "caps_lock" | "num_lock" | "scroll_lock"
  | "primary"; // "primary" means that the action should take whatever is defined by the action_key

// Represents an internal action that the user can override
struct DefaultActionOverride
{
  // Name of the action to override
  name: "terminal" | "request_vertical" | "request_horizontal" | "toggle_resize" | "move_up" | "move_down"
    | "move_left" | "move_right" | "select_up" | "select_down" | "select_left" | "select_right" 
    | "quit_active_window" | "quit_compositor" | "fullscreen" | "select_workspace_1" | "select_workspace_2"
    | "select_workspace_3" | "select_workspace_4" | "select_workspace_5" | "select_workspace_6"
    | "select_workspace_7" | "select_workspace_8" | "select_workspace_9" | "select_workspace_0"
    | "move_to_workspace_1" | "move_to_workspace_2" | "move_to_workspace_3" | "move_to_workspace_4"
    | "move_to_workspace_5" | "move_to_workspace_6" | "move_to_workspace_7" | "move_to_workspace_8"
    | "move_to_workspace_9" | "move_to_workspace_0"
    
  action: "up" | "down" | "repeat" | "modifiers"; // Action will fire based on this key event
  modifiers: Modifier[]; // Modifiers required for the action to trigger
  
  // Name of the keycode that the action should respond to.
  // See https://github.com/torvalds/linux/blob/master/include/uapi/linux/input-event-codes.h
  // for the list of available keycodes (e.g. KEY_ENTER, KEY_Z, etc.)
  key: KeyCodeName;
};

// Represents a custom action that a user can bind to a key combination
struct CustomAction
{
  command: string // Action to execute
  action: "up" | "down" | "repeat" | "modifiers"; // Action will fire based on this key event
  modifiers: Modifier[]; // Modifiers required for the action to trigger
  // Name of the keycode that the action should respond to.
  // See https://github.com/torvalds/linux/blob/master/include/uapi/linux/input-event-codes.h
  // for the list of available keycodes (e.g. KEY_ENTER, KEY_Z, etc.)
  key: KeyCodeName;
};

// Represents an app that will be executed at startup
struct StartupApp
{
  command: string;
  restart_on_death: bool; // If true the application will restart whenever it dies
};

Definition

With those types defined, the following table defines the allowed key/value pairs:

Key	Default	Type	Description
action_key	meta	Modifier	The default key that is used to initate any action.
default_action_overrides	[]	DefaultActionOverride[]	A list overrides to apply to built-in actions. Actions may be overridden more than once and will respond to multiple key combinations as a result. Defining at least one override disables the default action defined in Default Key Commands
custom_actions	[]	CustomAction[]	A list of custom applications that I user can execute. These actions always have precedence over built-in actions.
gap_size_x	10	int	Size of the gaps in pixels horizontally between windows
gap_size_y	10	int	Size of the gaps in pixels vertically between windows
startup_apps	[]	StartupApp[]	List of applications to be started when the compositor starts

Example

action_key: alt           # Set the primary action key to alt
default_action_overrides:
  - name: terminal        # Override the "terminal" keybind to execute with "Ctrl + Shift + Enter"
    action: down
    modifiers:
      - ctrl
      - shift
    key: KEY_ENTER

custom_actions:           # Set meta + D to open wofi
  - command: wofi --show=drun
    action: down
    modifiers:
      - primary
    key: KEY_D

gap_size_x: 20
gap_size_y: 20
startup_apps:
  - command: waybar
    restart_on_death: true
  - command: swaybg -i /path/to/my/image
    restart_on_death: true