From 948506cde1040303580b90dbf9adc910360716b2 Mon Sep 17 00:00:00 2001 From: Aire-One Date: Sat, 12 Jun 2021 14:38:18 +0200 Subject: [PATCH 1/4] doc(awful.key) Declarative constructor parameters --- lib/awful/key.lua | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/lib/awful/key.lua b/lib/awful/key.lua index 592bedde8..7b67e704c 100644 --- a/lib/awful/key.lua +++ b/lib/awful/key.lua @@ -216,11 +216,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. From 8085a508d16447e88476b39d9592a747c612dd86 Mon Sep 17 00:00:00 2001 From: Aire-One Date: Sat, 12 Jun 2021 15:14:20 +0200 Subject: [PATCH 2/4] add(awful.key) keygroup enum style table Replace the `awful.keygroup` property by an table that can be used as an enum to point to the `awful.keygroups` definitions. The previous field for `awful.keygroup` was empty (even no-existant), and was here only to appear in the documentation as a definition for the valid values to target keygroups. With this new enum style table, the user can easily refere to keygroups the same way we did for mouse buttons. --- lib/awful/key.lua | 41 ++++++++++++++++++++++++++--------------- 1 file changed, 26 insertions(+), 15 deletions(-) diff --git a/lib/awful/key.lua b/lib/awful/key.lua index 7b67e704c..7072ab883 100644 --- a/lib/awful/key.lua +++ b/lib/awful/key.lua @@ -24,21 +24,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 +84,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 From a3609146aab80800aebf35efe5d43aef314d0307 Mon Sep 17 00:00:00 2001 From: Aire-One Date: Sat, 12 Jun 2021 16:38:00 +0200 Subject: [PATCH 3/4] doc(awful.key) Improve module description --- lib/awful/key.lua | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/lib/awful/key.lua b/lib/awful/key.lua index 7072ab883..0e0b9ff13 100644 --- a/lib/awful/key.lua +++ b/lib/awful/key.lua @@ -1,6 +1,51 @@ --------------------------------------------------------------------------- --- 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: +-- +-- 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) +-- +-- This example shows how to define the same basic key object with the +-- declarative pattern: +-- +-- 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 +-- } +-- +-- 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. +-- +-- 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 +-- } +-- -- @author Julien Danjou <julien@danjou.info> -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2018 Emmanuel Lepage Vallee From 4188d1df1e7075b32c5db800b32ed93c9792ae4d Mon Sep 17 00:00:00 2001 From: Aire-One Date: Sun, 20 Jun 2021 20:02:51 +0200 Subject: [PATCH 4/4] doc: Move inline usage to example files --- lib/awful/key.lua | 30 ++----------------- .../awful/key/constructor/declarative.lua | 16 ++++++++++ .../text/awful/key/constructor/default.lua | 9 ++++++ .../text/awful/key/constructor/keygroup.lua | 21 +++++++++++++ 4 files changed, 49 insertions(+), 27 deletions(-) create mode 100644 tests/examples/text/awful/key/constructor/declarative.lua create mode 100644 tests/examples/text/awful/key/constructor/default.lua create mode 100644 tests/examples/text/awful/key/constructor/keygroup.lua diff --git a/lib/awful/key.lua b/lib/awful/key.lua index 0e0b9ff13..a5d49f38a 100644 --- a/lib/awful/key.lua +++ b/lib/awful/key.lua @@ -9,42 +9,18 @@ -- -- This example shows how to define a basic key object: -- --- 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_text_awful_key_constructor_default_EXAMPLE@ -- -- This example shows how to define the same basic key object with the -- declarative pattern: -- --- 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_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. -- --- 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_text_awful_key_constructor_keygroup_EXAMPLE@ -- -- @author Julien Danjou <julien@danjou.info> -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> 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 000000000..9ad5e20d9 --- /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 000000000..aafc5bc82 --- /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 000000000..0adce39c5 --- /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