diff --git a/lib/awful/key.lua b/lib/awful/key.lua index 592bedde..a5d49f38 100644 --- a/lib/awful/key.lua +++ b/lib/awful/key.lua @@ -1,6 +1,27 @@ --------------------------------------------------------------------------- --- Create easily new key objects ignoring certain modifiers. -- +-- A key object can be used by @{awful.keyboard} and @{client} to define +-- keybindings. +-- +-- Use awful.key to define a keybinding +-- --- +-- +-- This example shows how to define a basic key object: +-- +-- @DOC_text_awful_key_constructor_default_EXAMPLE@ +-- +-- This example shows how to define the same basic key object with the +-- declarative pattern: +-- +-- @DOC_text_awful_key_constructor_declarative_EXAMPLE@ +-- +-- This second example of a key definition uses the numrow keygroup. In this +-- example, we define a key object, that select the tag to show according to +-- the key index from the numrow. +-- +-- @DOC_text_awful_key_constructor_keygroup_EXAMPLE@ +-- -- @author Julien Danjou <julien@danjou.info> -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2018 Emmanuel Lepage Vallee @@ -24,21 +45,6 @@ local gobject = require("gears.object") -- @property key -- @param string ---- A group of keys. --- --- The valid keygroups are: --- --- * **numrow**: The row above the letters in the US PC-105/PC-104 keyboards --- and its derivative. This is usually the number 1-9 followed by 0. --- * **arrows**: The Left/Right/Top/Bottom keys usually located right of the --- spacebar. --- * **fkeys**: The keys F1 through F12 located at the topmost row of any --- keyboard, plus F13 through F35 on specialist keyboards. --- * **numpad**: The number keys on the keypad to the right of the letters and --- the arrow keys. Not present in every keyboard. --- --- @property keygroup - --- The table of modifier keys. -- -- A modifier, such as `Control` are a predetermined set of keys that can be @@ -99,6 +105,32 @@ local key = { mt = {}, hotkeys = {} } local reverse_map = setmetatable({}, {__mode="k"}) +--- The keygroups names. +-- +-- It can be used instead of keygroup names. +-- +-- Values associated to each property of this table are string: +-- +-- - **NUMROW** = `"numrow"`: The row above the letters in the US PC-105/PC-104 keyboards and +-- its derivative. This is usually the number 1-9 followed by 0. +-- +-- - **ARROWS** = `"arrows"`: The Left/Right/Top/Bottom keys usually located right of the +-- spacebar. +-- +-- - **FKEYS** = `"fkeys"`: The keys F1 through F12 located at the topmost row of any +-- keyboard, plus F13 through F35 on specialist keyboards. +-- +-- - **NUMPAD** = `"numpad"`: The number keys on the keypad to the right of the letters and +-- the arrow keys. Not present in every keyboard. +-- +-- @table keygroup +key.keygroup = { + NUMROW = 'numrow', -- The number row. + ARROWS = 'arrows', -- The directionnal arrows. + FKEYS = 'fkeys', -- The function keys. + NUMPAD = 'numpad', -- The numpad keys. +} + function key:set_key(k) for _, v in ipairs(self) do v.key = k @@ -216,11 +248,13 @@ end -- -- @constructorfct2 awful.key -- @tparam table args --- @tparam function args.key The key to trigger an event. It can be the character --- itself of `#+keycode` (**mandatory**). --- @tparam function args.modifiers A list of modifier keys. Valid modifiers are: --- `Any`, `Mod1`, Mod2`, `Mod3`, `Mod4`, `Mod5`, `Shift`, `Lock` and `Control`. --- This argument is (**mandatory**). +-- @tparam string args.key The key to trigger an event. It can be the character +-- itself of `#+keycode`. +-- @tparam[opt] string args.keygroup The keygroup to trigger an event. This +-- parameter must be used as a replacement for the `key` parameter. See +-- @{awful.key.keygroup}. +-- @tparam table args.modifiers A list of modifier keys. Valid modifiers are: +-- `Any`, `Mod1`, Mod2`, `Mod3`, `Mod4`, `Mod5`, `Shift`, `Lock` and `Control`. -- @tparam function args.on_press Callback for when the key is pressed. -- @tparam function args.on_release Callback for when the key is released. diff --git a/tests/examples/text/awful/key/constructor/declarative.lua b/tests/examples/text/awful/key/constructor/declarative.lua new file mode 100644 index 00000000..9ad5e20d --- /dev/null +++ b/tests/examples/text/awful/key/constructor/declarative.lua @@ -0,0 +1,16 @@ +--DOC_NO_USAGE + +local awful = require("awful") --DOC_HIDE + + awful.key { + modifiers = { "Mod4", "Shift" }, + key = 'a', + on_press = function () + print("The `Mod4` + `Shift` + `a` combo is pressed") + end, + on_release = function () + print("The `Mod4` + `Shift` + `a` combo is released") + end + } + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/text/awful/key/constructor/default.lua b/tests/examples/text/awful/key/constructor/default.lua new file mode 100644 index 00000000..aafc5bc8 --- /dev/null +++ b/tests/examples/text/awful/key/constructor/default.lua @@ -0,0 +1,9 @@ +--DOC_NO_USAGE + +local awful = require("awful") --DOC_HIDE + + awful.key({ "Mod4", "Shift" }, "a", + function () print("The `Mod4` + `Shift` + `a` combo is pressed") end, + function () print("The `Mod4` + `Shift` + `a` combo is released") end) + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/text/awful/key/constructor/keygroup.lua b/tests/examples/text/awful/key/constructor/keygroup.lua new file mode 100644 index 00000000..0adce39c --- /dev/null +++ b/tests/examples/text/awful/key/constructor/keygroup.lua @@ -0,0 +1,21 @@ +--DOC_NO_USAGE + +local awful = require("awful") --DOC_HIDE + +-- luacheck: ignore unused variable show_tag_by_numrow_index --DOC_HIDE + local show_tag_by_numrow_index = awful.key { + modifiers = { "Mod4" }, + keygroup = awful.key.keygroup.NUMROW, + description = "only view tag", + group = "tag", + on_press = function (index) + local screen = awful.screen.focused() + local tag = screen.tags[index] + + if tag then + tag:view_only() + end + end + } + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80