Modalawesome makes it possible to create vi-like keybindings for the awesome window manager. It introduces a modal alternative to the standard awful.key keybindings and supports complex commands with motions and counts by making use of Lua patterns. Check out the demo to get an overall impression of what this is capable of.

Clone the repository and put it in the Lua search path for awesome (e.g. ~/.config/awesome).

git clone https://github.com/potamides/modalawesome

After that include the module at the top of the rc.lua file.

local modalawesome = require("modalawesome")

The goal of modalawesome is to allow for complete control over awesome with modal commands. To make that possible modalawesome is designed to replace the functionality of the client:keys (normally set through awful.rules) and root.keys keybinding tables usually found in an rc.lua file. Thus after setting up modalawesome these keybindings are redundant and can be safely removed, if desired.

Add modalawesome.init() to your rc.lua and restart awesome. Press r to enter launcher mode and h to launch a help window with all keybindings. However it is advisable to read this file beforehand.

Commands are realized as tables with three entries.

• description: a description to show in the popup widget with hotkeys help
• pattern: a table with Lua patterns, which the entered keys are matched against
• handler: a function which is called when a entered sequence fully matches the patterns

This concept can be best explained with an example. A command to focus another tag could look like this:

local command = {
  description = "focus tag by direction",
  pattern = {'%d*', '[fb]'},
  handler = function(mode, index, direction)
    index = index == '' and 1 or tonumber(index)

    if direction == 'f' then
      awful.tag.viewidx(index)
    else
      awful.tag.viewidx(-index)
    end
  end
}

Each pattern in the pattern table has its own argument in the handler function. Here the %d* pattern matches the relative index of the new tag and [fb] determines if a tag before or after the current tag should be focused. This means that e.g. the sequence 1b would move one tag backwards and 3000f would move three thousand tags forward. The first argument of the handler function (mode), which was not used in this example, can be used to switch modes.

Like vi, modalawesome supports multiple modes. A mode is realized as a table of commands. Each mode is associated with a name. Modes can be changed with the mode argument of the handler function. It provides two functions for that.

• mode.start(name): start the mode named name and activate its commands
• mode.stop(): stop the current mode and interact with the focused client, no commands are active

A basic configuration with multiple modes could look like this:

local modes = {
  mode1 = {
  	{
      description = "start mode2",
      pattern = {'v'},
      handler = function(mode)
      	mode.start("mode2")
      end
    }
  },
  mode2 = {
  	{
      description = "start mode1",
      pattern = {'v'},
      handler = function(mode)
      	mode.start("mode1")
      end
    },
    {
      description = "start insert mode",
      pattern = {'i'},
      handler = function(mode)
      	mode.stop()
      end
    }
  }
}

Modalawesome provides default modes and commands that are loosely based on the default keybindings of awesome. The modalawesome default controls serve as a good starting point for a customized configuration.

local modes = require("modalawesome.modes")

The default configuration provides three modes to control awesome. The tag mode is used to change tags and to interact with different clients on a tag. From it the launcher mode and the layout mode can be started. The purpose of the launcher mode is to launch various applications, processes and utility functions and the layout mode can be used to change various layout options of the current tag.

Modalawesome provides two textboxes with information about the current mode (modalawesome.active_mode) and the current entered key sequence (modalawesome.sequence). These textboxes could be placed in the wibar.

s.mywibox:setup {
  layout = wibox.layout.align.horizontal,
  { -- Left widgets
    layout = wibox.layout.fixed.horizontal,
    -- ...
    modalawesome.active_mode
  },
  -- ...
  { -- Right widgets
    layout = wibox.layout.fixed.horizontal,
    modalawesome.sequence,
    -- ...
  },
}

For configuration purposes modalawesome provides the init function. This function expects a table with settings. The following settings are available:

• modkey: the key which can be used to go back to the default mode (comparable to Esc in vi)
• default_mode: name of the base mode of modalawesome (comparable to Normal mode in vi)
• modes: a table with modes, the index of a mode should be its name
• stop_name: the text to show in the modalaweosme.active_mode textbox, when no mode is active
• keybindings: a table of awful.key style keybindings which are active in all modes

The default settings are defined as follows:

modalawesome.init{
  modkey       = "Mod4",
  default_mode = "tag",
  modes        = require("modalawesome.modes"),
  stop_name    = "client",
  keybindings  = {}
}

The keybindings table makes it possible to easily integrate media keys into modalawesome.

local keybindings = {
  {{}, "XF86MonBrightnessDown", function () awful.spawn("xbacklight -dec 10") end},
  {{}, "XF86MonBrightnessUp", function () awful.spawn("xbacklight -inc 10") end},
}

The mode argument of the handler function also exposes the internal keygrabber used by modelawesome. This can be used to temporarily stop keygrabbing if another keygrabber needs to be run.

handler = function(mode, ...)
  mode.grabber:stop()
  -- ...
  mode.grabber:start()
end