From 2523be99d49f171c2891accb401c9f04ff6468f3 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Mon, 19 Dec 2016 20:39:40 -0500 Subject: [PATCH 1/6] doc: Add how to add tags It's a common question --- objects/tag.c | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/objects/tag.c b/objects/tag.c index 7fa467b3c..cd171617c 100644 --- a/objects/tag.c +++ b/objects/tag.c @@ -26,6 +26,34 @@ * * ![Client geometry](../images/tag_props.svg) * + * **Creating tags**: + * + * The default config initializes tags like this: + * + * awful.tag( + * { "1", "2", "3", "4", "5", "6", "7", "8", "9" }, + * s, + * awful.layout.layouts[1] + * ) + * + * If you wish to have tags with different properties, then `awful.tag.add` is + * a better choice: + * + * awful.tag.add("First tag", { + * icon = "/path/to/icon1.png", + * layout = awful.layout.suit.tile, + * master_fill_policy = "master_width_factor", + * gap_single_client = true, + * gap = 15, + * screen = s, + * } + * + * awful.tag.add("Second tag", { + * icon = "/path/to/icon2.png", + * layout = awful.layout.suit.max, + * screen = s, + * } + * * Some signal names are starting with a dot. These dots are artefacts from * the documentation generation, you get the real signal name by * removing the starting dot. From 4dd30c29dbf344e6881e813a82e05afef542ca6f Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Mon, 19 Dec 2016 20:40:14 -0500 Subject: [PATCH 2/6] doc: Add common ways to access the tags --- objects/tag.c | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/objects/tag.c b/objects/tag.c index cd171617c..722886ca2 100644 --- a/objects/tag.c +++ b/objects/tag.c @@ -54,6 +54,43 @@ * screen = s, * } * + * **Accessing tags**: + * + * To access the "current tags", use + * + * local tags = awful.screen.focused().selected_tags + * + * See: `awful.screen.focused` + * + * See: `screen.selected_tags` + * + * To ignore the corner case where multiple tags are selected: + * + * local t = awful.screen.focused().selected_tag + * + * See: `screen.selected_tag` + * + * To get all tags for the focused screen: + * + * local tags = awful.screen.focused().tags + * + * See: `screen.tags` + * + * To get all tags: + * + * local tags = root.tags() + * + * To get the current tag of the focused client: + * + * local t = client.focus and client.focus.first_tag or nil + * + * See: `client.focus` + * See: `client.first_tag` + * + * To get a tag from its name: + * + * local t = awful.tag.find_by_name(awful.screen.focused(), "name") + * * Some signal names are starting with a dot. These dots are artefacts from * the documentation generation, you get the real signal name by * removing the starting dot. From 2fe4e683554acc3022fa453e37acfdee6315801d Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Mon, 19 Dec 2016 23:42:24 -0500 Subject: [PATCH 3/6] doc: Add keybinding documentation --- docs/05-awesomerc.md.lua | 60 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 58 insertions(+), 2 deletions(-) diff --git a/docs/05-awesomerc.md.lua b/docs/05-awesomerc.md.lua index 139dfb817..d21c119c1 100644 --- a/docs/05-awesomerc.md.lua +++ b/docs/05-awesomerc.md.lua @@ -113,12 +113,68 @@ sections.DOC_ROOT_BUTTONS = [[ sections.DOC_GLOBAL_KEYBINDINGS = [[ -   + + This section stores the global keybindings. A global keybinding is a shortcut + that will be executed when the key is pressed. It is different from + client keybindings. A client keybinding + only works when a client is focused while a global one works all the time. + + Each keybinding is stored in an `awful.key` object. When creating such an + object, you need to provide a list of modifiers, a key or keycode, a callback + function and extra metadata used for the `awful.hotkeys_popup` widget. + + Common modifiers are: + + + + + + + + + + +
NameDescription
Mod4Also called Super, Windows and Command ⌘
Mod1Usually called Alt on PCs and Option on Macs
ShiftBoth left and right shift keys
ControlAlso called CTRL on some keyboards
+ + Note that both `Mod2` and `Lock` are ignored by default. If you wish to + use them, add `awful.key.ignore_modifiers = {}` to your `rc.lua`. `Mod3`, + `Mod5` are usually not bound in most leyboard layouts. There is an X11 utility + called `xmodmap` to bind them. See + [the ARCH Linux Wiki](https://wiki.archlinux.org/index.php/xmodmap) for more + information. + + The key or keycode is usually the same as the keyboard key, for example: + + * "a" + * "Return" + * "Shift_R" + + Each key also has a code. This code depends on the exact keyboard layout. It + can be obtained by reading the terminal output of the `xev` command. A keycode + based keybinding will look like `#123` where 123 is the keycode. + + The callback has to be a function. Note that a function isn't the same as a + function call. If you use, for example, `awful.tag.viewtoggle()` as the + callback, you store the **result** of the function. If you wish to use that + function as a callback, just use `awful.tag.viewtoggle`. The same applies to + methods. If you have to add parameters to the callback, wrap them in another + function. For the toggle example, this would be + `function() awful.tag.viewtoggle(mouse.screen.tags[1]) end`. + + Note that global keybinding callbacks have no argument. If you wish to act on + the current `client`, use the client keybindings + table. ]] sections.DOC_CLIENT_KEYBINDINGS = [[ -   + + + A client keybinding is a shortcut that will get the currently focused client + as its first callback argument. For example, to toggle a property, the callback + will look like `function(c) c.sticky = not c.sticky end`. For more information + about the keybinding syntax, see the + global keybindings section. ]] From 66a948699265745188c73fbb88067ce6076d7d77 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Mon, 19 Dec 2016 20:40:34 -0500 Subject: [PATCH 4/6] doc: Add optional shortcuts to manage tags --- objects/tag.c | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/objects/tag.c b/objects/tag.c index 722886ca2..45624d7b0 100644 --- a/objects/tag.c +++ b/objects/tag.c @@ -91,6 +91,83 @@ * * local t = awful.tag.find_by_name(awful.screen.focused(), "name") * + * **Common shortcuts**: + * + * Here is a few useful shortcuts not part of the default `rc.lua`. Add these + * functions above `-- {{{ Key bindings`: + * + * Delete the current tag + * + * local function delete_tag() + * local t = awful.screen.focused().selected_tag + * if not t then return end + * t:delete() + * end + * + * Create a new tag at the end of the list + * + * local function add_tag() + * awful.tag.add("NewTag",{screen= awful.screen.focused() }):view_only() + * end + * + * Rename the current tag + * + * local function rename_tag() + * awful.prompt.run { + * prompt = "New tag name: ", + * textbox = awful.screen.focused().mypromptbox.widget, + * exe_callback = function(new_name) + * if not new_name or #new_name == 0 then return end + * + * local t = awful.screen.focused().selected_tag + * if t then + * t.name = new_name + * end + * end + * } + * end + * + * Move the focused client to a new tag + * + * local function move_to_new_tag() + * local c = client.focus + * if not c then return end + * + * local t = awful.tag.add(c.class,{screen= c.screen }) + * c:tags({t}) + * t:view_only() + * end + * + * Copy the current tag at the end of the list + * + * local function copy_tag() + * local t = awful.screen.focused().selected_tag + * if not t then return end + * + * local clients = t:clients() + * local t2 = awful.tag.add(t.name, awful.tag.getdata(t)) + * t2:clients(clients) + * t2:view_only() + * end + * + * And, in the `globalkeys` table: + * + * awful.key({ modkey, }, "a", add_tag, + * {description = "add a tag", group = "tag"}), + * awful.key({ modkey, "Shift" }, "a", delete_tag, + * {description = "delete the current tag", group = "tag"}), + * awful.key({ modkey, "Control" }, "a", move_to_new_tag, + * {description = "add a tag with the focused client", group = "tag"}), + * awful.key({ modkey, "Mod1" }, "a", copy_tag, + * {description = "create a copy of the current tag", group = "tag"}), + * awful.key({ modkey, "Shift" }, "r", rename_tag, + * {description = "rename the current tag", group = "tag"}), + * + * See the + * + * global keybindings + * for more information about the keybindings. + * * Some signal names are starting with a dot. These dots are artefacts from * the documentation generation, you get the real signal name by * removing the starting dot. From 2b462cb2e35f42271843cb98f9bfd6206d5258b0 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Mon, 19 Dec 2016 20:49:04 -0500 Subject: [PATCH 5/6] doc: Document the tag `master_fill_policy` --- lib/awful/tag.lua | 14 +++++++++++++- tests/test-awful-layout.lua | 4 ++-- 2 files changed, 15 insertions(+), 3 deletions(-) diff --git a/lib/awful/tag.lua b/lib/awful/tag.lua index 254c10014..dbf3a6071 100644 --- a/lib/awful/tag.lua +++ b/lib/awful/tag.lua @@ -889,7 +889,13 @@ function tag.getgap(t, numclients) return tag.object.get_gap(t or ascreen.focused().selected_tag) end ---- The default fill policy +--- The default fill policy. +-- +-- ** Possible values**: +-- +-- * *expand*: Take all the space +-- * *master_width_factor*: Only take the ratio defined by the +-- `master_width_factor` -- -- @beautiful beautiful.master_fill_policy -- @param string (default: "expand") @@ -897,6 +903,12 @@ end --- Set size fill policy for the master client(s). -- +-- ** Possible values**: +-- +-- * *expand*: Take all the space +-- * *master_width_factor*: Only take the ratio defined by the +-- `master_width_factor` +-- -- **Signal:** -- -- * *property::master_fill_policy* diff --git a/tests/test-awful-layout.lua b/tests/test-awful-layout.lua index bc8ced7d9..cac28935b 100644 --- a/tests/test-awful-layout.lua +++ b/tests/test-awful-layout.lua @@ -76,8 +76,8 @@ local common_steps = { return true end, function() - t.master_fill_policy = t.master_fill_policy == "mwfact" and - "expand" or "mwfact" + t.master_fill_policy = t.master_fill_policy == "master_width_factor" and + "expand" or "master_width_factor" return true end, From a93084947a1533878ee9d406113aabfaeb361cda Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Mon, 19 Dec 2016 21:23:54 -0500 Subject: [PATCH 6/6] doc: Add a virtual screen example --- objects/screen.c | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/objects/screen.c b/objects/screen.c index 78112385c..93ce2288f 100644 --- a/objects/screen.c +++ b/objects/screen.c @@ -1112,6 +1112,17 @@ luaA_screen_count(lua_State *L) } /** Add a fake screen. + * + * To vertically split the first screen in 2 equal parts, use: + * + * local geo = screen[1].geometry + * local new_width = math.ceil(geo.width/2) + * local new_width2 = geo.width - new_width + * screen[1]:fake_resize(geo.x, geo.y, new_width, geo.height) + * screen.fake_add(geo.x + new_width, geo.y, new_width2, geo.height) + * + * Both virtual screens will have their own taglist and wibars. + * * @tparam integer x X-coordinate for screen. * @tparam integer y Y-coordinate for screen. * @tparam integer width width for screen.