modalawesome

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.

Installation

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")

This project requires awesome 4.3+ and Lua 5.1+. Older versions may
also work but are untested.

Usage

The goal of modalawesome is to enable complete control over awesome with modal
commands. To make that possible modalawesome covers the same scope
as the keybindings set through the
client:keys
(normally applied with
awful.rules) and
root.keys tables
usually found in an rc.lua file. Thus after setting up modalawesome the
standard keybindings are redundant and can be safely removed, if desired.

Quickstart

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

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 item in the pattern table has its own argument in the handler
function. Here %d* 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 focus the previous tag and 3000f
would move the focus 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.

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
    }
  }
}

Default Configuration

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.

Indicators

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,
    -- ...
  },
}

Initialization

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},
}

Advanced

Access Internal Keygrabber

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

Explicit Modifier Keys

In many cases it’s not necessary to explicitly specify the modifiers to use in
a pattern, instead it’s sufficient to specify the corresponding symbol
directly.

local pattern = {"S"} -- matches "Shift-s"

However this doesn’t work with special keys like Tab or modifiers like
Control. For these cases you can use a slightly extended pattern syntax. Each
item in the pattern table for which explicit modifier matching is desired
should be replaced with a table with the modifiers as first elements and the
corresponding item as the last. Supported modifiers are Shift, Control,
Mod1 and Mod4.

local pattern = {{"Control", "w"}, "[hjkl]"} -- matches "Control-w [hjkl]"

local pattern = {{"Control", "Shift", "Tab"}} -- matches "Control-Shift-Tab"

Common Keybindings

In some scenarios it might be desirable to add a lot of common keybindings to
multiple modes (e.g. to make some commands accessible everywhere through a
leader key). It might be tedious to add these bindings to all modes manually
and it would also potentially clutter the hotkeys widget. For this use case
modalawesome honors the merge key in mode tables:

local modes = {
  tag      = { --[[ ... ]] },
  launcher = { --[[ ... ]] },
  layout   = { --[[ ... ]] },
  common   = { merge=true, --[[ ... ]] }
}

In this example all keybindings in common would be merged with the tag,
launcher and layout modes, however the hotkeys widget would still show
these bindings grouped under the common mode. For more fine-grained control
over merging the value of the merge key could also be a table with mode
names.