Configuring wlmaker

Configuration file

wlmaker is highly configurable, and uses a human-readable configuration file in human-readable Property List format.

wlmaker will load try loading a configuration file from these locations:

• If a --config_file=<FILE> argument is provided, load <FILE>.
• Otherwise, from the configured lookup paths: _wlmaker_config_fname_ptrs

  static const char *_wlmaker_config_fname_ptrs[] = {
      "~/.wlmaker.plist",
      "/usr/share/wlmaker/wlmaker.plist",
      NULL  // Sentinel.
  };

• Otherwise, compiled-in setttings from etc/wlmaker.plist will be loaded.

The configuration file is a dictionary that may hold values for the following keys:

• Keyboard (required)
• Decoration (required)
• KeyBindings (required)
• HotCorner (required)
• ScreenLock (required)
• Outputs (required)

Keyboard

This dictionary configures the keyboard layout and properties.

• XkbRMLVO (required): A dictionary holding an XKB keyboard configuration.
  • Rules (required): Defines the XKB mapping.
  • Model: The name of the model of the keyboard hardware in use.
  • Layout: Identifier of the general layout.
  • Variant: Any minor variants on the general layout.
  • Options: Setof extra options to customize the standard layout.
• Repeat (required): A dictionary holding two values that define the initial holdback and repeat rate when holding a key pressed.
  • Delay (required): Delay before initiating repeats, in milliseconds.
  • Rate (required): Repeats per second, once Delay has expired.

Example:

Keyboard = {
    XkbRMLVO = {
        Rules = "evdev";
        Model = "pc105";
        Layout = "us";
        Variant = "intl";
        Options = "";
    };
    Repeat = {
        // Delay before initiating repeats, in milliseconds.
        Delay = 300;
        // Repeats per second.
        Rate = 25;
    };
};

Decoration

By default, Wayland clients (using the XDG Shell) will draw window decorations themselves. For clients that implement and obey the XDG decoration protocol, wlmaker can whether decorations are drawn by the server, ie. by wlmaker.

For X11 clients, wlmaker will add decorations if the client requests.

Permitted modes (see _wlmaker_config_decoration_desc):

• SuggestClient: Requests the client to draw decoration.
• SuggestServer: Requests wlmaker to add decorations.
• EnforceClient: wlmaker will refuse to draw decorations, even if the client requests.
• EnforceServer: wlmaker will add decorations, even if the client refuses.

Example:

// Configuration for XDG decoration protocol: Server or client-side?
Decoration = {
    Mode = SuggestServer;
};

KeyBindings

A dictionary, where each key and value define a binding of a key combination to a wlmaker action. The dictionary may be empty.

See _wlmaker_keybindings_modifiers for the supported modifiers.

See wlmaker_action_desc for the list of permitted actions.

Example:

KeyBindings = {
    "Ctrl+Alt+Logo+Q" = Quit;
    "Ctrl+Alt+Logo+L" = LockScreen;
    "Ctrl+Alt+Logo+T" = LaunchTerminal;
 
    "Ctrl+Alt+Logo+Left" = WorkspacePrevious;
    "Ctrl+Alt+Logo+Right" = WorkspaceNext;
 
    "Ctrl+Alt+Logo+Escape" = TaskNext;
    "Shift+Ctrl+Alt+Logo+Escape" = TaskPrevious;
 
    "Alt+Logo+Up" = WindowRaise;
    "Alt+Logo+Down" = WindowLower;
    "Ctrl+Alt+Logo+F" = WindowToggleFullscreen;
    "Ctrl+Alt+Logo+M" = WindowToggleMaximized;
 
    // TODO(kaeser@gubbe.ch): Swap with F12, to match Window Maker's behaviour.
    "Ctrl+Alt+Logo+R" = RootMenu;
 
    // TODO(kaeser@gubbe.ch): xkbcommon emits XF86Switch_VT_n for Fn only with
    // Ctrl+Alt presset. Means: Here, it should not need the modifiers to be
    // listed. Should determine how to handle that w/o modifiers.
    "Ctrl+Alt+XF86Switch_VT_1" = SwitchToVT1;
    "Ctrl+Alt+XF86Switch_VT_2" = SwitchToVT2;
    "Ctrl+Alt+XF86Switch_VT_3" = SwitchToVT3;
    "Ctrl+Alt+XF86Switch_VT_4" = SwitchToVT4;
    "Ctrl+Alt+XF86Switch_VT_5" = SwitchToVT5;
    "Ctrl+Alt+XF86Switch_VT_6" = SwitchToVT6;
    "Ctrl+Alt+XF86Switch_VT_7" = SwitchToVT7;
    "Ctrl+Alt+XF86Switch_VT_8" = SwitchToVT8;
    "Ctrl+Alt+XF86Switch_VT_9" = SwitchToVT9;
    "Ctrl+Alt+XF86Switch_VT_10" = SwitchToVT10;
    "Ctrl+Alt+XF86Switch_VT_11" = SwitchToVT11;
    "Ctrl+Alt+XF86Switch_VT_12" = SwitchToVT12;
};

HotCorner

This dictionary configures which action is triggered when the mouse pointer enters and stays at the specified corner for TriggerDelay milliseconds. It must have the following items:

• TriggerDelay: Delay for the pointer residing in a corner before triggering the corresponding Enter event.
• TopLeftEnter, TopRightEnter, BottomLeftEnter, BottomRightEnter: Sets the action (wlmaker_action_desc) to trigger when entering the corner.
• TopLeftLeave, TopRightLeave, BottomLeftLeave, BottomRightLeave: Sets the action (wlmaker_action_desc) to trigger when entering the corner.

Note: As of wlmaker 0.5, the corners are relative to the total layout. They may not be reachable when using multiple outputs that don't have the same resolution.

Example:

HotCorner = {
    // Delay for the pointer occupying a corner before triggering 'Enter'.
    TriggerDelay = 500;
    // For each corner 'TopLeft', 'TopRight', 'BottomLeft' and 'BottomRight'
    // there are 'Enter' and 'Leave' events that can be bound to an action.
    TopLeftEnter = LockScreen;
    TopLeftLeave = None;
    TopRightEnter = InhibitLockBegin;
    TopRightLeave = InhibitLockEnd;
    BottomLeftEnter = None;
    BottomLeftLeave = None;
    BottomRightEnter = None;
    BottomRightLeave = None;
};

ScreenLock

Configures the timeout and command for locking the screen. It must have the following keys:

• IdleSeconds: Number of seconds of inactivity before executing Command.
• Command: Defines the command that will be executed after IdleSeconds.

The LockScreen action is wired to execute Command of ScreenLock.

Example:

ScreenLock = {
    IdleSeconds = 300;
    Command = "/usr/bin/swaylock";
};

Autostart

An array of strings, each denoting an executable that will be executed once wlmaker has started.

Example:

// Optional array: Commands to start once wlmaker is running.
Autostart = (
    "/usr/bin/foot"
);

Outputs

Using the Outputs array, wlmaker will configure and combine monitors into a multi-monitor setup as configured. When an output (monitor) is detected, wlmaker will first see if the output is found in State. Otherwise, it will scan the Outputs array for an entry that matches Name, Manufacturer, Model and Serial. Once found, it checks Enabled whether that output should be used. If so, the settings from Scale, Transformation, Position and Mode will be applied.

wlmaker supports the wlr output management protocol for dynamically modifying the output device configuration. There are third-party tools (wlr-randr, wldisplays, ...) to dynamically set output propertis.

• Optional Enabled: A boolean value, specifies whether that output should be used (Yes) or not (No). Defaults to Yes.
• Optional Scale: A fractional number, specifies the scaling factor to apply for contents on that output. Defaults to 1.0.
• Optional Transformation: Defines whether the monitor's contents should be rotated and/or flipped. Permitted values:

  static const bspl_enum_desc_t _wlmbe_output_transformation_desc[] = {
      BSPL_ENUM("Normal", WL_OUTPUT_TRANSFORM_NORMAL),
      BSPL_ENUM("Rotate90", WL_OUTPUT_TRANSFORM_90),
      BSPL_ENUM("Rotate180", WL_OUTPUT_TRANSFORM_180),
      BSPL_ENUM("Rotate270", WL_OUTPUT_TRANSFORM_270),
      BSPL_ENUM("Flip", WL_OUTPUT_TRANSFORM_FLIPPED),
      BSPL_ENUM("FlipAndRotate90", WL_OUTPUT_TRANSFORM_FLIPPED_90),
      BSPL_ENUM("FlipAndRotate180", WL_OUTPUT_TRANSFORM_FLIPPED_180),
      BSPL_ENUM("FlipAndRotate270", WL_OUTPUT_TRANSFORM_FLIPPED_270),
      BSPL_ENUM_SENTINEL(),
  };

  Defaults to Normal.
• Optional Position: Defines the position of the output's top left corner. Defaults to "0,0".
• Optional Mode: A string of the format <WIDTH>x<HEIGHT>[@<RATE>], denoting a resolution of WIDTH x HEIGHT, optionally with explicitly specified refresh rate <RATE> in Hz.

Example:

Outputs = (
    // The "Eizo EV2785" monitor on the DisplayPort connection: Configure
    // for a resolution of 1920x1080 (at any supported refresh rate), scale
    // with a factor of 2.0, and place it's top-left corner at (0, 0).
    {
        Manufacturer = "Eizo*";
        Model = "EV2785";
        Name = "DP-*";
        Position = "0,0";
        // Note: Mode applies before scaling: The effective resolution
        // visible to clients becomes 1920x1080.
        Mode = "3840x2160@59.997";
        Scale = 2.0;
        Transformation = Normal;
    },
    // Any output at HDMI will also be placed at 0,0; mirroring the "Eizo".
    {
        Name = "HDMI-*";
        Position = "0,0";
        Scale = 1.0;
        Transformation = Normal;
    },
    // Any further monitor will be automatically placed; to the right of
    // above setup.
    {
        Name = "*";
        Scale = 1.0;
        Transformation = Normal;
    },
);

That example will configure any added output to use Normal transformation with a scale of 1.0.