doc: Add more tag images.

lib/awful/tag.lua

@@ -715,6 +715,11 @@ end
 --
 -- @DOC_screen_mwfact_EXAMPLE@
 --
+-- When multiple columns are used, the master width remains the same, but
+-- the other columns split the remaining space among them:
+--
+-- @DOC_screen_mwfact2_EXAMPLE@
+--
 -- **Signal:**
 --
 -- * *property::mwfact* (deprecated)
@@ -726,6 +731,7 @@ end
 -- @see column_count
 -- @see master_fill_policy
 -- @see gap
+-- @see awful.tag.incmwfact
 
 function tag.object.set_master_width_factor(t, mwfact)
     if mwfact >= 0 and mwfact <= 1 then
@@ -1108,6 +1114,7 @@ end
 -- @property gap
 -- @param number The value has to be greater than zero.
 -- @see gap_single_client
+-- @see awful.tag.incgap
 
 function tag.object.set_gap(t, useless_gap)
     if useless_gap >= 0 then
@@ -1170,6 +1177,7 @@ end
 --
 -- @property gap_single_client
 -- @param boolean Enable gaps for a single client
+-- @see awful.tag.incgap
 
 function tag.object.set_gap_single_client(t, gap_single_client)
     tag.setproperty(t, "gap_single_client", gap_single_client == true)
@@ -1218,18 +1226,33 @@ end
 
 --- Set size fill policy for the master client(s).
 --
+-- Some multi-column layouts can be configured so that the space is
+-- redistributed when there is not enough clients to fill all columns.
+--
 -- ** Possible values**:
 --
 -- * *expand*: Take all the space
--- * *master_width_factor*: Only take the ratio defined by the
+-- * *master\_width\_factor*: Only take the ratio defined by the
 --   `master_width_factor`
 --
+-- This is the default behavior of the `tile.left` layout (*expand*):
+--
+-- @DOC_screen_mfpol2_EXAMPLE@
+--
+-- This is what happends when set to `master_width_factor`:
+--
+-- @DOC_screen_mfpol_EXAMPLE@
+--
+-- The remaining space that would have been used for the second column is
+-- redistributed on both side.
+--
 -- **Signal:**
 --
 -- * *property::master_fill_policy*
 --
 -- @property master_fill_policy
 -- @param string "expand" or "master_width_factor"
+-- @see awful.tag.togglemfpol
 
 function tag.object.get_master_fill_policy(t)
     return tag.getproperty(t, "master_fill_policy")
@@ -1299,6 +1322,7 @@ end
 --
 -- @property master_count
 -- @param integer nmaster Only positive values are accepted
+-- @see awful.tag.incnmaster
 
 function tag.object.set_master_count(t, nmaster)
     if nmaster >= 0 then
@@ -1366,12 +1390,16 @@ end
 
 --- Set the tag icon.
 --
+-- @DOC_wibox_awidget_taglist_icon_EXAMPLE@
+--
 -- **Signal:**
 --
 -- * *property::icon*
 --
 -- @property icon
 -- @tparam path|surface icon The icon
+-- @see awful.widget.taglist
+-- @see gears.surface
 
 -- accessors are implicit.
 
@@ -1406,6 +1434,8 @@ end
 
 --- Set the number of columns.
 --
+-- @DOC_sequences_tag_column_count_EXAMPLE@
+--
 -- **Signal:**
 --
 -- * *property::ncol* (deprecated)
@@ -1413,6 +1443,7 @@ end
 --
 -- @property column_count
 -- @tparam integer ncol Has to be greater than 1
+-- @see awful.tag.incncol
 
 function tag.object.set_column_count(t, ncol)
     if ncol >= 1 then

tests/examples/screen/mfpol.lua

@@ -0,0 +1,53 @@
+--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_ALL
+
+screen[1]._resize {x = 0, width = 640, height = 480}
+
+
+local awful = {
+    wibar = require("awful.wibar"),
+    tag = require("awful.tag"),
+    tag_layout = require("awful.layout.suit.tile")
+}
+
+function awful.spawn(_, args)
+    local c = client.gen_fake{}
+    c:tags({args.tag})
+    assert(#c:tags() == 1)
+    assert(c:tags()[1] == args.tag)
+end
+
+screen[1].padding = {
+    left   = 40,
+    right  = 40,
+    top    = 20,
+    bottom = 20,
+}
+
+local wibar = awful.wibar {
+    position = "top",
+    height   = 24,
+}
+
+awful.tag.add("1", {
+    screen              = screen[1],
+    selected            = true,
+    layout              = awful.tag_layout.right,
+    gap                 = 5,
+    master_width_factor = 0.66,
+    master_fill_policy  = "master_width_factor"
+})
+
+local clients = {
+    ['Single client'] = client.gen_fake{},
+}
+for _,c in ipairs(clients) do
+    c:tags{"1"}
+end
+
+return {
+    factor                = 2    ,
+    show_boxes            = true,
+    draw_wibar            = wibar,
+    draw_clients          = clients,
+    display_screen_info   = false,
+}

tests/examples/screen/mfpol2.lua

@@ -0,0 +1,53 @@
+--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_ALL
+
+screen[1]._resize {x = 0, width = 640, height = 480}
+
+
+local awful = {
+    wibar = require("awful.wibar"),
+    tag = require("awful.tag"),
+    tag_layout = require("awful.layout.suit.tile")
+}
+
+function awful.spawn(_, args)
+    local c = client.gen_fake{}
+    c:tags({args.tag})
+    assert(#c:tags() == 1)
+    assert(c:tags()[1] == args.tag)
+end
+
+screen[1].padding = {
+    left   = 40,
+    right  = 40,
+    top    = 20,
+    bottom = 20,
+}
+
+local wibar = awful.wibar {
+    position = "top",
+    height   = 24,
+}
+
+awful.tag.add("1", {
+    screen              = screen[1],
+    selected            = true,
+    layout              = awful.tag_layout.right,
+    gap                 = 5,
+    master_width_factor = 0.66,
+    master_fill_policy  = "expand"
+})
+
+local clients = {
+    ['Single client'] = client.gen_fake{},
+}
+for _,c in ipairs(clients) do
+    c:tags{"1"}
+end
+
+return {
+    factor                = 2    ,
+    show_boxes            = true,
+    draw_wibar            = wibar,
+    draw_clients          = clients,
+    display_screen_info   = false,
+}

tests/examples/screen/mwfact2.lua

@@ -0,0 +1,58 @@
+--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_ALL
+
+screen[1]._resize {x = 0, width = 640, height = 480}
+
+
+local awful = {
+    wibar = require("awful.wibar"),
+    tag = require("awful.tag"),
+    tag_layout = require("awful.layout.suit.tile")
+}
+
+function awful.spawn(_, args)
+    local c = client.gen_fake{}
+    c:tags({args.tag})
+    assert(#c:tags() == 1)
+    assert(c:tags()[1] == args.tag)
+end
+
+screen[1].padding = {
+    left   = 40,
+    right  = 40,
+    top    = 20,
+    bottom = 20,
+}
+
+local wibar = awful.wibar {
+    position = "top",
+    height   = 24,
+}
+
+awful.tag.add("1", {
+    screen              = screen[1],
+    selected            = true,
+    layout              = awful.tag_layout.right,
+    gap                 = 5,
+    master_width_factor = 0.6,
+    column_count        = 2
+})
+
+local clients = {
+    ['master #1 (60%)'] = client.gen_fake{},
+    ['#1 (20%)'] = client.gen_fake{},
+    ['#2 (20%)'] = client.gen_fake{},
+    ['#3 (20%)'] = client.gen_fake{},
+    ['#4 (20%)'] = client.gen_fake{}
+}
+for _,c in ipairs(clients) do
+    c:tags{"1"}
+end
+
+return {
+    factor                = 2    ,
+    show_boxes            = true,
+    draw_wibar            = wibar,
+    draw_clients          = clients,
+    display_screen_info   = false,
+    draw_mwfact           = true,
+}

tests/examples/sequences/tag/column_count.lua

@@ -0,0 +1,57 @@
+ --DOC_GEN_IMAGE --DOC --DOC_NO_USAGE
+local module = ... --DOC_HIDE
+local awful = {tag = require("awful.tag"), layout = require("awful.layout") } --DOC_HIDE
+screen[1]._resize {x = 0, width = 128, height = 96} --DOC_HIDE
+
+
+function awful.spawn(_, args) --DOC_HIDE
+    local c = client.gen_fake{} --DOC_HIDE
+    c:tags({args.tag}) --DOC_HIDE
+    assert(#c:tags() == 1) --DOC_HIDE
+    assert(c:tags()[1] == args.tag) --DOC_HIDE
+end --DOC_HIDE
+
+module.add_event("Create differing column count tags", function() --DOC_HIDE
+    -- Create a tag with column count of 1 and tag with count of 2
+    awful.tag.add("1 column", {
+        screen   = screen[1],
+        layout   = awful.layout.suit.tile,
+        column_count = 1,
+    })
+
+--DOC_NEWLINE
+
+    awful.tag.add("2 columns", {
+        screen   = screen[1],
+        layout   = awful.layout.suit.tile,
+        column_count = 2,
+    })
+
+--DOC_NEWLINE
+
+    awful.tag.add("3 columns", {
+        screen   = screen[1],
+        layout   = awful.layout.suit.tile,
+        column_count = 3,
+    })
+
+
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+--DOC_NEWLINE
+
+module.add_event("Add some clients", function() --DOC_HIDE
+    -- Add some clients.
+    for _, t in ipairs(screen[1].tags) do
+        for _ = 1, 6 do
+            awful.spawn("xterm", {tag = t})
+        end
+        assert(#t:clients() == 6) --DOC_HIDE
+    end
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+module.execute {show_empty = true} --DOC_HIDE

tests/examples/wibox/awidget/taglist/icon.lua

@@ -0,0 +1,56 @@
+--DOC_GEN_IMAGE --DOC_HIDE
+local parent = ... --DOC_NO_USAGE --DOC_HIDE
+local awful = { --DOC_HIDE
+    tag = require("awful.tag"), --DOC_HIDE
+    layout = require("awful.layout"), --DOC_HIDE
+    placement = require("awful.placement"), --DOC_HIDE
+    widget = {taglist = require("awful.widget.taglist")} --DOC_HIDE
+} --DOC_HIDE
+local wibox = require("wibox") --DOC_HIDE
+local beautiful = require("beautiful") --DOC_HIDE
+
+local s = screen[1] --DOC_HIDE
+local taglist_buttons = nil -- To make luacheck shut up --DOC_HIDE
+
+local tags = {} --DOC_HIDE
+
+table.insert(tags, --DOC_HIDE
+    awful.tag.add("one", {})
+) --DOC_HIDE
+
+--DOC_NEWLINE
+
+table.insert(tags, --DOC_HIDE
+    awful.tag.add("two", {
+        icon = beautiful.awesome_icon
+    })
+) --DOC_HIDE
+
+--DOC_NEWLINE
+
+table.insert(tags, --DOC_HIDE
+    awful.tag.add("three", {})
+) --DOC_HIDE
+
+--DOC_NEWLINE
+
+for i=1, 3 do tags[i].selected = false end --DOC_HIDE
+tags[2].selected = true --DOC_HIDE
+
+--DOC_HIDE add some clients to some tags
+local c = client.gen_fake {x = 80, y = 55, width=75, height=50} --DOC_HIDE
+local c2 = client.gen_fake {x = 80, y = 55, width=75, height=50} --DOC_HIDE
+c:tags(tags[3]) --DOC_HIDE
+c2:tags(tags[1]) --DOC_HIDE
+
+s.mytaglist = awful.widget.taglist { --DOC_HIDE
+    screen  = s, --DOC_HIDE
+    filter  = awful.widget.taglist.filter.all, --DOC_HIDE
+    buttons = taglist_buttons --DOC_HIDE
+} --DOC_HIDE
+
+s.mytaglist.forced_width = 100 --DOC_HIDE
+s.mytaglist.forced_height = 18 --DOC_HIDE
+s.mytaglist._do_taglist_update_now() --DOC_HIDE
+
+parent:add(wibox.widget.background(s.mytaglist, beautiful.bg_normal)) --DOC_HIDE