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