Merge pull request #3364 from Aire-One/fix/awful.key-constructor

[doc] awful.key contructor and general improvements

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
+-- @tparam string args.key The key to trigger an event. It can be the character
---  itself of `#+keycode` (**mandatory**).
+--   itself of `#+keycode`.
--- @tparam function args.modifiers A list of modifier keys.  Valid modifiers are:
+-- @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`.
---  This argument is (**mandatory**).
 -- @tparam function args.on_press Callback for when the key is pressed.
 -- @tparam function args.on_release Callback for when the key is released.
 

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

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

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