334 lines
10 KiB
Lua
334 lines
10 KiB
Lua
-- -*- coding: utf-8 -*-
|
|
--------------------------------------------------------------------------------
|
|
-- @author Nicolas Berthier <nberthier@gmail.com>
|
|
-- @copyright 2010 Nicolas Berthier
|
|
--------------------------------------------------------------------------------
|
|
--
|
|
-- This is a module for defining keychains à la emacs in awesome. I was also
|
|
-- inspired by ion3 behavior when designing it.
|
|
--
|
|
-- Remarks:
|
|
--
|
|
-- - This module does not handle `release' key bindings, but is it useful for
|
|
-- keychains?
|
|
--
|
|
-- - It has not been tested with multiple screens yet.
|
|
--
|
|
-- - There might (... must) be incompatibilities with the shifty module. Also,
|
|
-- defining global and per-client keychains with the same prefix is not
|
|
-- allowed (or leads to unspecified behaviors... --- in practice: the
|
|
-- per-client ones are ignored). However, I do think separation of per-client
|
|
-- and global keys is a bad idea if client keys do not have a higher priority
|
|
-- than the global ones...
|
|
--
|
|
-- Example usage: see `rc.lua' file.
|
|
--
|
|
--------------------------------------------------------------------------------
|
|
|
|
--{{{ Grab environment (mostly aliases)
|
|
local setmetatable = setmetatable
|
|
local ipairs = ipairs
|
|
local type = type
|
|
local pairs = pairs
|
|
local string = string
|
|
local print = print
|
|
local error = error
|
|
local io = io
|
|
|
|
local capi = capi
|
|
local client = client
|
|
local awesome = awesome
|
|
local root = root
|
|
|
|
local akey = require ("awful.key")
|
|
local join = awful.util.table.join
|
|
local clone = awful.util.table.clone
|
|
--}}}
|
|
|
|
module ("keychain")
|
|
|
|
-- Privata data: we use weak keys in order to allow collection of private data
|
|
-- if keys (clients) are collected (i.e., no longer used, after having been
|
|
-- killed for instance)
|
|
local data = setmetatable ({}, { __mode = 'k' })
|
|
|
|
--{{{ Functional Tuples
|
|
-- see http://lua-users.org/wiki/FunctionalTuples for details
|
|
|
|
--- Creates a keystroke representation to fill the `escape' table configuration
|
|
--- property.
|
|
-- @param m Modifiers table.
|
|
-- @param k The key itself.
|
|
-- @return A keystroke representation (only for the escape sequence, for now?).
|
|
function keystroke (m, k)
|
|
if type (m) ~= "table" then
|
|
error ("Keystroke modifiers must be given a table (got a "..
|
|
type (m)..")")
|
|
end
|
|
if type (k) ~= "string" then
|
|
error ("Keystroke key must be given a string (got a "..
|
|
type (m)..")")
|
|
end
|
|
return function (fn) return fn (m, k) end
|
|
end
|
|
|
|
-- keystroke accessors
|
|
local function ks_mod (_m, _k) return _m end
|
|
local function ks_key (_m, _k) return _k end
|
|
|
|
-- ---
|
|
|
|
--- Creates a final keychain binding to fill the keychain binding tables,
|
|
--- meaning that the given function will be executed at the end of the keychain.
|
|
-- @param m Modifiers table.
|
|
-- @param k The key.
|
|
-- @param cont The function to be bound to the given keys.
|
|
-- @return A "final" key binding.
|
|
function key (m, k, cont)
|
|
if type (cont) ~= "function" then
|
|
error ("Final binding must be given a function (got a "..
|
|
type (cont)..")")
|
|
end
|
|
return function (fn) return fn (keystroke (m, k), cont, true) end
|
|
end
|
|
|
|
--- Creates an intermediate (prefix) keychain binding.
|
|
-- @param m Modifiers table.
|
|
-- @param k The key.
|
|
-- @param sub The subchain description table to be bound to the given keys.
|
|
-- @return An "intermediate" key binding.
|
|
function subchain (m, k, sub)
|
|
if type (sub) ~= "table" then
|
|
error ("Subchain binding must be given a table (got a "..
|
|
type (sub)..")")
|
|
end
|
|
return function (fn) return fn (keystroke (m, k), sub, false) end
|
|
end
|
|
|
|
-- key/subchain binding accessors
|
|
local function binding_ks (ks, cont, leaf) return ks end
|
|
local function binding_cont (ks, cont, leaf) return cont end
|
|
local function binding_leaf (ks, cont, leaf) return leaf end
|
|
|
|
--- Creates an intermediate keychain if sub is a table, or a final key binding
|
|
--- otherwise (and then sub must be a function).
|
|
-- @param m Modifiers table.
|
|
-- @param k The key.
|
|
-- @param sub Either the subchain description table, or the function, to be
|
|
-- bound to the given keys.
|
|
function sub (m, k, sub)
|
|
if type (sub) == "table" then
|
|
return subchain (m, k, sub)
|
|
else
|
|
return key (m, k, sub)
|
|
end
|
|
end
|
|
|
|
--}}}
|
|
|
|
--{{{ Default values
|
|
|
|
--- Default escape sequences (S-g is inspired by emacs...)
|
|
local escape_keystrokes = {
|
|
keystroke ( { }, "Escape" ),
|
|
keystroke ( { "Mod4" }, "g" ),
|
|
}
|
|
|
|
--}}}
|
|
|
|
--{{{ Key table management facilities
|
|
|
|
local function set_keys (c, k)
|
|
if c == root then root.keys (k) else c:keys (k) end
|
|
end
|
|
|
|
local function keys_of (c)
|
|
if c == root then return root.keys () else return c:keys () end
|
|
end
|
|
|
|
--}}}
|
|
|
|
--{{{ Signal emission helper
|
|
|
|
local function notif (sig, w, ...)
|
|
if w ~= root then
|
|
client.emit_signal (sig, w, ...)
|
|
else -- we use global signals otherwise
|
|
awesome.emit_signal (sig, ...)
|
|
end
|
|
end
|
|
|
|
--}}}
|
|
|
|
--{{{ Client/Root-related state management
|
|
|
|
local function init_client_state_maybe (w)
|
|
if data[w] == nil then
|
|
local d = { }
|
|
d.keys = keys_of (w) -- save client keys
|
|
data[w] = d -- register client
|
|
notif ("keychain::enter", w)
|
|
end
|
|
end
|
|
|
|
local function restore_client_state (c)
|
|
local w = c or root
|
|
local d = data[w]
|
|
-- XXX: Turns out that `d' can be nil already here, in case the keyboard has
|
|
-- been grabbed since the previous call to this funtion... (that also seems
|
|
-- to be called again upon release…)
|
|
if d then
|
|
set_keys (w, d.keys) -- restore client keys
|
|
data[w] = nil -- unregister client
|
|
end
|
|
end
|
|
|
|
local function leave (c)
|
|
local w = c or root
|
|
|
|
-- Destroy notifier structures if needed
|
|
if data[w] then -- XXX: necessary test?
|
|
notif ("keychain::leave", w)
|
|
end
|
|
end
|
|
|
|
-- force disposal of resources when clients are killed
|
|
client.add_signal ("unmanage", leave)
|
|
|
|
--}}}
|
|
|
|
--{{{ Key binding tree access helpers
|
|
|
|
local function make_on_entering (m, k, subchain) return
|
|
function (c)
|
|
local w = c or root
|
|
|
|
-- Register and initialize client state, if not already in a keychain
|
|
init_client_state_maybe (w)
|
|
|
|
-- Update notifier text, and trigger its drawing if necessary
|
|
notif ("keychain::append", w, m, k)
|
|
|
|
-- Setup subchain
|
|
set_keys (w, subchain)
|
|
end
|
|
end
|
|
|
|
local function on_leaving (c)
|
|
-- Trigger disposal routine
|
|
leave (c)
|
|
|
|
-- Restore initial key mapping of client
|
|
restore_client_state (c)
|
|
end
|
|
|
|
--}}}
|
|
|
|
--{{{ Configuration
|
|
|
|
-- Flag to detect late initialization error
|
|
local already_used = false
|
|
|
|
-- Escape binding table built once upon initialization
|
|
local escape_bindings = { }
|
|
|
|
--- Fills the escape bindings table with actual `awful.key' elements triggering
|
|
--- execution of `on_leaving'.
|
|
local function init_escape_bindings ()
|
|
escape_bindings = { }
|
|
for _, e in ipairs (escape_keystrokes) do
|
|
escape_bindings = join (escape_bindings,
|
|
akey (e (ks_mod), e (ks_key), on_leaving))
|
|
end
|
|
end
|
|
|
|
-- Call it once upon module loading to initialize escape_bindings (in case
|
|
-- `init' is not called).
|
|
init_escape_bindings ()
|
|
|
|
|
|
--- Initializes the keychain module, with given properties; to be called before
|
|
--- ANY other function of this module.
|
|
-- Configurations fields include:
|
|
--
|
|
-- `escapes': A table of keystrokes (@see keychain.keystroke) escaping keychains
|
|
-- (defaults are `Mod4-g' and `Escape').
|
|
--
|
|
-- @param c The table of properties.
|
|
function init (c)
|
|
local c = c or { }
|
|
|
|
if already_used then
|
|
-- heum... just signal the error: "print" or "error"?
|
|
return print ("E: keychain: Call to `init' AFTER having bound keys!")
|
|
end
|
|
|
|
escape_keystrokes = c.escapes and c.escapes or escape_keystrokes
|
|
|
|
-- Now, fill the escape bindings table again with actual `awful.key'
|
|
-- elements triggering `on_leaving' executions, in case escape keys has
|
|
-- changed.
|
|
init_escape_bindings ()
|
|
end
|
|
|
|
--}}}
|
|
|
|
--{{{ Keychain creation
|
|
|
|
--- Creates a new keychain binding.
|
|
-- @param m Modifiers table.
|
|
-- @param k The key.
|
|
-- @param chains A table of keychains, describing either final bindings (see
|
|
-- key constructor) or subchains (see subchain constructor). If arg is not a
|
|
-- table, then `awful.key' is called directly with the arguments.
|
|
-- @return A key binding for the `awful.key' module.
|
|
-- @see awful.key
|
|
function new (m, k, chains)
|
|
|
|
-- If the argument is a function, then we need to return an actual awful.key
|
|
-- directly.
|
|
if type (chains) ~= "table" then
|
|
return akey (m, k, chains)
|
|
end
|
|
|
|
-- This table will contain the keys to be mapped upon <m, k> keystroke. It
|
|
-- initially contains the escape bindings, so that one can still rebind them
|
|
-- differently in `chains'.
|
|
local subchain = clone (escape_bindings)
|
|
|
|
already_used = true -- subsequent init avoidance flag...
|
|
|
|
-- For each entry of the given chains, add a corresponding `awful.key'
|
|
-- element in the subchain
|
|
for _, e in ipairs (chains) do
|
|
local ks = e (binding_ks)
|
|
if e (binding_leaf) then
|
|
-- We encountered a leaf in the chains.
|
|
local function on_leaf (c) on_leaving (c); e (binding_cont) (c) end
|
|
subchain = join (subchain, akey (ks (ks_mod), ks (ks_key), on_leaf))
|
|
else
|
|
-- Recursively call subchain creation. "Funny" detail: I think there
|
|
-- is no way of creating ill-structured keychain descriptors that
|
|
-- would produce infinite recursive calls here, since we control
|
|
-- their creation with functional tuples, that cannot lead to cyclic
|
|
-- structures...
|
|
local subch = new (ks (ks_mod), ks (ks_key), e (binding_cont))
|
|
subchain = join (subchain, subch)
|
|
end
|
|
end
|
|
|
|
-- Then return an actual `awful.key', triggering the `on_entering' routine
|
|
return akey (m, k, make_on_entering (m, k, subchain))
|
|
end
|
|
--}}}
|
|
|
|
-- Setup `__call' entry in module's metatable so that we can create new prefix
|
|
-- binding using `keychain (m, k, ...)' directly.
|
|
setmetatable (_M, { __call = function (_, ...) return new (...) end })
|
|
|
|
-- Local variables:
|
|
-- indent-tabs-mode: nil
|
|
-- fill-column: 80
|
|
-- lua-indent-level: 4
|
|
-- End:
|
|
-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:encoding=utf-8:textwidth=80
|