doc: Document the wibar module.

lib/awful/wibar.lua

@@ -1,11 +1,13 @@
 ---------------------------------------------------------------------------
---- Wibox module for awful.
+--- The main AwesomeWM "bar" module.
+--
 -- This module allows you to easily create wibox and attach them to the edge of
 -- a screen.
 --
 --@DOC_awful_wibar_default_EXAMPLE@
 --
 -- You can even have vertical bars too.
+--
 --@DOC_awful_wibar_left_EXAMPLE@
 --
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
@@ -56,6 +58,9 @@ local align_map = {
 }
 
 --- If the wibar needs to be stretched to fill the screen.
+--
+-- @DOC_awful_wibar_stretch_EXAMPLE@
+--
 -- @property stretch
 -- @tparam boolean stretch
 -- @propbeautiful
@@ -72,6 +77,8 @@ local align_map = {
 --  * right
 --  * centered
 --
+--  @DOC_awful_wibar_align_EXAMPLE@
+--
 -- @property align
 -- @tparam string align
 -- @propbeautiful
@@ -83,17 +90,26 @@ local align_map = {
 -- It can either be a table if `top`, `bottom`, `left`, `right` or a
 -- single number.
 --
+-- @DOC_awful_wibar_margins_EXAMPLE@
+--
 -- @property margins
 -- @tparam number|table margins
 -- @propbeautiful
 -- @propemits true false
 
 --- If the wibar needs to be stretched to fill the screen.
+--
 -- @beautiful beautiful.wibar_stretch
 -- @tparam boolean stretch
 
 --- Allow or deny the tiled clients to cover the wibar.
 --
+-- In the example below, we can see that the first screen workarea
+-- shrunk by the height of the wibar while the second screen is
+-- unchanged.
+--
+-- @DOC_screen_wibar_workarea_EXAMPLE@
+--
 -- @property update_workarea
 -- @tparam[opt=true] boolean update_workarea
 -- @propemits true false
@@ -102,6 +118,15 @@ local align_map = {
 
 --- If there is both vertical and horizontal wibar, give more space to vertical ones.
 --
+-- By default, if multiple wibars risk overlapping, it will be resolved
+-- by giving more space to the horizontal one:
+--
+-- ![wibar position](../images/AUTOGEN_awful_wibar_position.svg)
+--
+-- If this variable is to to `true`, it will behave like:
+--
+-- @DOC_awful_wibar_position2_EXAMPLE@
+--
 -- @beautiful beautiful.wibar_favor_vertical
 -- @tparam[opt=false] boolean favor_vertical
 
@@ -263,6 +288,8 @@ end
 -- * top
 -- * bottom
 --
+-- @DOC_awful_wibar_position_EXAMPLE@
+--
 -- @property position
 -- @tparam string position Either "left", right", "top" or "bottom"
 -- @propemits true false
@@ -502,6 +529,9 @@ end
 -- @tparam[opt=nil] table args
 -- @tparam string args.position The position.
 -- @tparam string args.stretch If the wibar need to be stretched to fill the screen.
+-- @tparam boolean args.update_workarea Allow or deny the tiled clients to cover the wibar.
+-- @tparam string args.align How to align non-stretched wibars.
+-- @tparam table|number args.margins The wibar margins.
 --@DOC_wibox_constructor_COMMON@
 -- @return The new wibar
 -- @constructorfct awful.wibar

tests/examples/awful/wibar/align.lua

@@ -0,0 +1,54 @@
+--DOC_GEN_IMAGE
+--DOC_HIDE_START
+local awful     = require("awful")
+local wibox     = require("wibox")
+
+screen._track_workarea = true
+screen[1]._resize {width = 360, height = 60}
+screen._add_screen {x = 0, width = 360, height = 64, y = 72} --DOC_HIDE
+screen._add_screen {x = 0, width = 360, height = 64, y = 144} --DOC_HIDE
+screen._add_screen {x = 372, width = 64, height = 210, y = 0} --DOC_HIDE
+screen._add_screen {x = 444, width = 64, height = 210, y = 0} --DOC_HIDE
+screen._add_screen {x = 516, width = 64, height = 210, y = 0} --DOC_HIDE
+
+--DOC_HIDE_END
+
+for s, align in ipairs { "left", "centered", "right" } do
+    awful.wibar {
+        position = "top",
+        screen   = screen[s],
+        stretch  = false,
+        width    = 196,
+        align    = align,
+        widget   = {
+            text   = align,
+            align  = "center",
+            widget = wibox.widget.textbox
+        },
+    }
+end
+
+--DOC_NEWLINE
+
+for s, align in ipairs { "top", "centered", "bottom" } do
+    awful.wibar {
+        position = "left",
+        screen   = screen[s+3],
+        stretch  = false,
+        height   = 128,
+        align    = align,
+        widget   = {
+            {
+                text   = align,
+                align  = "center",
+                widget = wibox.widget.textbox
+            },
+            direction = "east",
+            widget    = wibox.container.rotate
+        },
+    }
+end
+
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
+

tests/examples/awful/wibar/margins.lua

@@ -0,0 +1,99 @@
+--DOC_GEN_IMAGE
+--DOC_HIDE_START
+local awful     = require("awful")
+local wibox     = require("wibox")
+local beautiful = require("beautiful")
+
+screen._track_workarea = true
+screen[1]._resize {width = 480, height = 128}
+screen._add_screen {x = 0, width = 480, height = 128, y = 140}
+
+local t1 = awful.tag.add("1", {
+    screen   = screen[1],
+    selected = true,
+    layout   = awful.layout.suit.tile.right,
+    gap      = 4
+})
+
+local c1 = client.gen_fake {hide_first=true, screen = screen[2]}
+c1:tags{t1}
+
+local t2 = awful.tag.add("1", {
+    screen   = screen[2],
+    selected = true,
+    layout   = awful.layout.suit.tile.right,
+    gap      = 4
+})
+
+local c2 = client.gen_fake {hide_first=true}
+c2:tags{t2}
+
+for _, c in ipairs {c1, c2} do
+    local top_titlebar = awful.titlebar(c, {
+        size      = 20,
+        bg_normal =  beautiful.bg_highligh,
+    })
+    top_titlebar : setup {
+        { -- Left
+            awful.titlebar.widget.iconwidget(c),
+            layout  = wibox.layout.fixed.horizontal
+        },
+        { -- Middle
+            { -- Title
+                align  = "center",
+                widget = awful.titlebar.widget.titlewidget(c)
+            },
+            layout  = wibox.layout.flex.horizontal
+        },
+        { -- Right
+            awful.titlebar.widget.floatingbutton (c),
+            awful.titlebar.widget.maximizedbutton(c),
+            awful.titlebar.widget.stickybutton   (c),
+            awful.titlebar.widget.ontopbutton    (c),
+            awful.titlebar.widget.closebutton    (c),
+            layout = wibox.layout.fixed.horizontal()
+        },
+        layout = wibox.layout.align.horizontal
+    }
+end
+
+--DOC_HIDE_END
+
+awful.wibar {
+    position = "top",
+    screen   = screen[1],
+    stretch  = false,
+    width    = 196,
+    margins  = 24,
+    widget   = {
+        align  = "center",
+        text   = "unform margins",
+        widget = wibox.widget.textbox
+    }
+}
+
+--DOC_NEWLINE
+
+awful.wibar {
+    position = "top",
+    screen   = screen[2],
+    stretch  = false,
+    width    = 196,
+    margins = {
+        top    = 12,
+        bottom = 5
+    },
+    widget   = {
+        align  = "center",
+        text   = "non unform margins",
+        widget = wibox.widget.textbox
+    }
+
+}
+
+awful.layout.arrange(screen[1]) --DOC_HIDE
+awful.layout.arrange(screen[2]) --DOC_HIDE
+c1:_hide_all() --DOC_HIDE
+c2:_hide_all() --DOC_HIDE
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/awful/wibar/position.lua

@@ -0,0 +1,36 @@
+--DOC_GEN_IMAGE --DOC_NO_USAGE
+--DOC_HIDE_START
+local awful     = require("awful")
+local wibox     = require("wibox")
+
+screen[1]._resize {width = 480, height = 196}
+--DOC_HIDE_END
+
+   local colors = {
+       top    = "#ffff00",
+       bottom = "#ff00ff",
+       left   = "#00ffff",
+       right  = "#ffcc00"
+   }
+
+   --DOC_NEWLINE
+
+   for _, position in ipairs { "top", "bottom", "left", "right" } do
+       awful.wibar {
+           position = position,
+           bg       = colors[position],
+           widget   = {
+               {
+                   text   = position,
+                   align  = "center",
+                   widget = wibox.widget.textbox
+               },
+               direction = (position == "left" or position == "right") and
+                   "east" or "north",
+               widget    = wibox.container.rotate
+           },
+       }
+   end
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
+

tests/examples/awful/wibar/position2.lua

@@ -0,0 +1,38 @@
+--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_ALL
+--DOC_HIDE_START
+local awful     = require("awful")
+local wibox     = require("wibox")
+local beautiful = require("beautiful")
+
+screen[1]._resize {width = 480, height = 196}
+
+    local colors = {
+        top    = "#ffff00",
+        bottom = "#ff00ff",
+        left   = "#00ffff",
+        right  = "#ffcc00"
+    }
+
+--DOC_HIDE_END
+    beautiful.wibar_favor_vertical = true
+    --DOC_NEWLINE
+
+    for _, position in ipairs { "top", "bottom", "left", "right" } do
+        awful.wibar {
+            position = position,
+            bg       = colors[position],
+            widget   = {
+                {
+                    text   = position,
+                    align  = "center",
+                    widget = wibox.widget.textbox
+                },
+                direction = (position == "left" or position == "right") and
+                    "east" or "north",
+                widget    = wibox.container.rotate
+            },
+        }
+    end
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
+

tests/examples/awful/wibar/stretch.lua

@@ -0,0 +1,40 @@
+--DOC_GEN_IMAGE
+--DOC_HIDE_START
+local awful     = require("awful")
+local wibox     = require("wibox")
+
+screen._track_workarea = true
+screen[1]._resize {width = 480, height = 60}
+screen._add_screen {x = 0, width = 480, height = 64, y = 72} --DOC_HIDE
+
+--DOC_HIDE_END
+
+awful.wibar {
+    position = "top",
+    screen   = screen[1],
+    stretch  = true,
+    width    = 196,
+    widget   = {
+        text   = "stretched",
+        align  = "center",
+        widget = wibox.widget.textbox
+    },
+}
+
+--DOC_NEWLINE
+
+awful.wibar {
+    position = "top",
+    screen   = screen[2],
+    stretch  = false,
+    width    = 196,
+    widget   = {
+        text   = "not stretched",
+        align  = "center",
+        widget = wibox.widget.textbox
+    },
+}
+
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
+

tests/examples/screen/wibar_workarea.lua

@@ -0,0 +1,35 @@
+--DOC_GEN_IMAGE
+
+screen[1]._resize {x = 0, width = 640, height = 480} --DOC_HIDE
+
+screen._add_screen {x = 820, width = 640, height = 480, y = -22} --DOC_HIDE
+
+local awful = { --DOC_HIDE
+    wibar = require("awful.wibar"), --DOC_HIDE
+    tag = require("awful.tag"), --DOC_HIDE
+    tag_layout = require("awful.layout.suit.tile") --DOC_HIDE
+} --DOC_HIDE
+
+local screen1_wibar = awful.wibar {
+    position        = "top",
+    update_workarea = true,
+    height          = 24,
+    screen          = screen[1],
+}
+
+--DOC_NEWLINE
+
+local screen2_wibar = awful.wibar {
+    position        = "top",
+    update_workarea = false,
+    height          = 24,
+    screen          = screen[2],
+}
+
+return { --DOC_HIDE
+    factor                = 2   , --DOC_HIDE
+    show_boxes            = true, --DOC_HIDE
+    draw_wibars           = {screen1_wibar, screen2_wibar}, --DOC_HIDE
+    display_screen_info   = false, --DOC_HIDE
+    draw_struts           = true, --DOC_HIDE
+} --DOC_HIDE