⌨️ modalisa 🎨

modalisa is a hybrid modal keymap framework for AwesomeWM. It combines the best of both traditional and modal input modes while also providing a visually appealing interface.

Traditional input modes in tiling window managers often require complex keymaps that involve pressing multiple modifiers simultaneously due to limited keyspace. Additionally, users have to rely on their memory or unpractical cheatsheets as there are no key suggestions while typing. On the other hand, modal input modes allow for easy entry of key sequences but can become cumbersome when repeating actions. Users either have to repeat the entire sequence or specify a count beforehand, making the process inefficient.

modalisa addresses these shortcomings by providing a flexible hybrid approach. It keeps track of modifier states to provide distinct input modes that can be tailored to the user's needs for each key and at every stage of the sequence individually. It allows for traditional keybinds for common operations that can be repeated by holding down the modifier, while also enabling users to tap the modifier (like a leader key) to enter modal mode followed by a key sequence for less common commands. This flexibility makes it possible to transition into a more modal-esque keymap gradually without having to relearn most of the AwesomeWM controls.

In addition, modalisa comes with a preconfigured default keymap that includes improved default AwesomeWM controls (and a lot more) to provide a starting point and to give an overview about the possibilities using this framework.

Which Key Hints	AwesomeWM Controls	System Controls
Client Labels	Mouse Menu	File Picker

✨ Features

• 🪄 Unique input modes
• 💥 Which key hints with mouse support
• 🌳 Keymap trees with property inheritance
• 💄 UI building blocks (prompt, echo, labels)
• 🌐 Define options for every key individually
• 🪟 Preconfigured AwesomeWM and system keymap
• 🧙 Use vim syntax to define key sequences
• ♿ Easy and intuitive configuration
• 📡 Highly extensible and customizable (200+ parameters)

💡 Example

{
    ["t"] = { desc = "tag", opts = { mode = "hybrid", hints = { enabled = true } } },
    -- opts are inherited from predecessor t
    ["t<Tab>"] = {
        desc = "view last tag",
        fn = function(opts)
            awful.tag.history.restore()
        end,
    },
    ["tD"] = {
        desc = "delete current tag",
        opts = { hints = { placement = "centered" } },
        cond = function()
            return awful.screen.focused().selected_tag.index > 1
        end,
        fn = function(opts)
            local dynamic_menu = {
                y = {
                    desc = function()
                        return "yes, delete tag " .. awful.screen.focused().selected_tag.index
                    end,
                    highlight = { bg = "#FF0000", desc = { bold = true } },
                    function(opts)
                        awful.screen.focused().selected_tag:delete()
                    end,
                },
                n = { desc = "no, cancel delete" },
            }
            return dynamic_menu
        end,
    },
}

⚠️ Warning

modalisa is in early development and breaking changes might occur.

📋 Requirements

• awesome-git
• nerd-font (optional)

📦 Installation

1. Clone the repo:

git clone https://github.com/intrntbrn/modalisa ~/.config/awesome/modalisa

2. Import and configure the module in rc.lua:

-- NOTE:
-- modalisa is designed to be used in conjunction with a modifier as the leader
-- key (e.g. Super_L), but this prevents all current keybinds utilizing
-- that modifier from functioning.
require("modalisa").setup({
    -- root_keys = { "<M-a>" }, -- "Mod4" + "a"
    root_keys = { "<Super_L>" }, -- or "<Alt_L>"
    back_keys = { "<BackSpace>" },
    stop_keys = { "<Escape>" },
    mode = "hybrid",
    include_default_keys = true,
    -- try the auto-generated theme first
    theme = {
        -- fg = "#eceffc",
        -- bg = "#24283B",
        -- grey = "#959cbc",
        -- border = "#444A73",
        -- accent = "#82AAFF",
    },
})

Create Your Own Keymap

1. Copy the default keymap keys.lua as modalisa_keys.lua into the home AwesomeWM directory:

cp ~/.config/awesome/modalisa/keys.lua ~/.config/awesome/modalisa_keys.lua

2. Disable the default keymap by setting include_default_keys = false during setup.

3. Edit the copy. Restart AwesomeWM for the changes to take effect.

You can retrieve keynames by running the command

awesome-client "awesome.emit_signal('modalisa::showkey')"

from the terminal. Press any key combination to show the respective keyname.

⚙️ Configuration

Most configuration options can be explored interactively by pressing i on the default keymap.

📖 Documentation

🌲Tree

Keymaps are organized and represented using hierarchical tree structures. Each key is stored as a node in the tree. When a character is input, the tree is traversed to find the corresponding key. If a node has been found and there are no possible successors (leaf), the key's function is executed. Users can also use a specific key (by default, BackSpace) to go back a level in the tree.

The tree structure implements property inheritance, which means that options (opts) defined at a higher level in the tree will be inherited by the successor keys, unless overridden. This provides a convenient way to define common options for groups of keys without repeating them for each individual key.

By default, the keymap is stored in the root tree, which is accessed by pressing the keybind defined in root_keys during setup. However, it is possible to create additional trees if needed.

✨ Modes

Please note that the exact behaviour is also dependent on other config parameters. When stop_on_unknown_key is active and an unknown key has been input, operation will stop regardless of the current mode. Operation will also always stop when a timeout (no valid input within a timeframe) occurs. The keys itself can also override the behaviour by explicitly setting a continue flag.

🔑 Key

Keys can be configured by using the following properties:

🖌️ Custom UI

One of the design principles is to fully isolate core functionality from UI. Every UI building block (echo, prompt, label) can be disabled individually allowing users to build custom versions by solely implementing signal handlers.

To implement custom UI please refer to the sourcecode.

📡 API

Todo.

💡 More Examples