Merge pull request #1279 from Elv13/tag_doc

Tag & keybindings doc

docs/05-awesomerc.md.lua

@@ -113,12 +113,68 @@ sections.DOC_ROOT_BUTTONS = [[
 
 
 sections.DOC_GLOBAL_KEYBINDINGS = [[
-  
+ <a id="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
+ <a href="#client_keybindings">client keybindings</a>. 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:
+
+ <table class='widget_list' border=1>
+  <tr style='font-weight: bold;'>
+   <th align='center'>Name</th>
+   <th align='center'>Description</th>
+  </tr>
+  <tr><td>Mod4</td><td>Also called Super, Windows and Command ⌘</td></tr>
+  <tr><td>Mod1</td><td>Usually called Alt on PCs and Option on Macs</td></tr>
+  <tr><td>Shift</td><td>Both left and right shift keys</td></tr>
+  <tr><td>Control</td><td>Also called CTRL on some keyboards</td></tr>
+ </table>
+
+ 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 <a href="#client_keybindings">client keybindings</a>
+ table.
 ]]
 
 
 sections.DOC_CLIENT_KEYBINDINGS = [[
- &nbsp;
+ <a id="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
+ <a href="#global_keybindings">global keybindings</a> section.
 ]]
 
 

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*

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.

objects/tag.c

@@ -26,6 +26,148 @@
  *
  * ![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,
+ *    }
+ *
+ * **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")
+ *
+ * **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
+ * <a href="../documentation/05-awesomerc.md.html#global_keybindings">
+ *   global keybindings
+ * </a> 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.

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,