modes - Luakit

# Luakit Documentation / Modules / modes

# Module `modes`

Default mode configuration for luakit

This module defines a core set of modes each luakit window can be in. Different modes recognize different keybindings.

## Functions

### modes.new_mode (name, desc, mode, replace)

Add a new mode table (optionally merges with original mode)

#### Parameters

- name
  Type: string
  The name of the mode.
- desc
  Type: string
  Optional
  The description of the mode.
- mode
  Type: table
  A table that defines the mode.
- replace
  Type: boolean
  Optional
  Default: `false`
  `true` if any existing mode with the same name should be replaced, and `false` if the pre-existing mode should be extended.

### modes.get_mode (name)

Get a mode by name.

#### Parameters

- name
  Type: string
  The name of the mode to retrieve.

#### Return Values

- table
  The mode table for the named mode.

### modes.get_modes ()

Get all modes.

#### Return Values

- table
  A clone of the full table of modes.

### modes.add_binds (mode, binds)

Add a set of binds to one or more modes. Any pre-existing binds with the same trigger will be removed automatically.

#### Example

The following code snippet will rebind `Control-c` to copy text selected with the mouse, and the default binding for `Control-c` will be removed.

    modes.add_binds("normal", {
        { "<Control-c>", "Copy selected text.", function ()
            luakit.selection.clipboard = luakit.selection.primary
        end},
    })

#### Bind format

Every item in the `binds` array must be a table that defines a single binding between a trigger and an action. Each entry must have the following form:

    { trigger, description, action, options }

- `trigger` is a string describing the combination of keys/modifiers/buttons that will trigger the associated action.
- `description` is an optional string. Any description will show up in the introspector.
- `action` is a function that will be called when the binding is activated, of type `bind_action_cb`.
- `options` is a table of bind-time options passed to the `action` callback.

#### Parameters

- mode
  Type: table or string
  The name of the mode, or an array of mode names.
- binds
  Type: table
  An array of binds to add to each of the named modes.

### modes.remove_binds (mode, binds)

Remove a set of binds from one or more modes.

#### Example

    -- Disable extra zooming commands
    modes.remove_binds("normal", { "zi", "zo", "zz" })

    -- Disable passthrough mode
    modes.remove_binds({"normal", "insert"}, { "<Control-z>" })

#### Parameters

- mode
  Type: table or string
  The name of the mode, or an array of mode names.
- binds
  Type: table
  An array of binds to remove from each of the named modes.

### modes.remap_binds (mode, binds)

Bind an existing key or command to a new binding.

#### Example

    -- Add an additional zooming command binding
    modes.remap_binds("normal", {
        { "<Control-=>", "zi", true },
    })

#### Bind format

Every item in the `binds` array must be a table that defines a single rebind from an existing trigger to a new one. Each entry must have the following form:

    { new, old, keep }

- `new` is a string describing the combination of keys/modifiers/buttons that will trigger the associated action.
- `old` is a string describing the previous trigger of the action.
- `keep` is an optional argument that determines whether the existing binding should remain. Defaults to `false` if not present.

#### Parameters

- mode
  Type: table or string
  The name of the mode, or an array of mode names.
- binds
  Type: table
  An array of binds to remap

### modes.add_cmds (mode, binds)

Add a set of commands to the built-in `command` mode.

#### Parameters

- mode
  Type: table or string
  The name of the mode, or an array of mode names.
- binds
  Type: table
  An raray of binds to add to each of the named modes.

## Callback Types

### bind_action_cb (w, opts, bind_opts)

Callback type for a bind action.

#### Parameters

- w
  Type: table
  The window table for the window on which the binding was activated.
- opts
  Type: table
  Combined table of bind-time and invocation-time options.
- bind_opts
  Type: table
  Table of invocation-time options.

#### Return Values

- boolean
  `false` if bind matching should be continued, as if this action were not bound. Any other value stops bind matching, which is usually what you want.

## Attribution

#### Copyright

- 2017 Aidan Holm
- 2010 Mason Larobina