doc: Add a titlebar example

lib/awful/titlebar.lua

@@ -1,9 +1,15 @@
 ---------------------------------------------------------------------------
 --- Titlebars for awful.
+--**Create a titlebar:**
+--
+-- This example reproduces what the default `rc.lua` does. It shows how to
+-- handle the titlebars on a lower level.
+--
+-- @DOC_awful_titlebar_default_EXAMPLE@
 --
 -- @author Uli Schlachter
 -- @copyright 2012 Uli Schlachter
--- @module awful.titlebar
+-- @classmod awful.titlebar
 ---------------------------------------------------------------------------
 
 local error = error
@@ -447,8 +453,7 @@ local function get_titlebar_function(c, position)
     end
 end
 
---- Get a client's titlebar
--- @class function
+--- Get a client's titlebar.
 -- @tparam client c The client for which a titlebar is wanted.
 -- @tparam[opt={}] table args A table with extra arguments for the titlebar.
 -- @tparam[opt=font.height*1.5] number args.size The height of the titlebar.
@@ -461,7 +466,7 @@ end
 -- @tparam[opt=top] string args.fg_normal
 -- @tparam[opt=top] string args.fg_focus
 -- @tparam[opt=top] string args.font
--- @name titlebar
+-- @function awful.titlebar
 local function new(c, args)
     args = args or {}
     local position = args.position or "top"

tests/examples/awful/titlebar/default.lua

@@ -0,0 +1,60 @@
+--DOC_NO_USAGE
+local place = require("awful.placement") --DOC_HIDE
+local awful = { titlebar = require("awful.titlebar"), --DOC_HIDE
+                button   = require("awful.button"), --DOC_HIDE
+              } --DOC_HIDE
+local wibox = require("wibox") --DOC_HIDE
+local gears = {table = require("gears.table")} --DOC_HIDE
+
+local c = client.gen_fake {hide_first=true} --DOC_HIDE
+place.maximize(c, {honor_padding=true, honor_workarea=true}) --DOC_HIDE
+
+    -- Create a titlebar for the client.
+    -- By default, `awful.rules` will create one, but all it does is to call this
+    -- function.
+
+    local top_titlebar = awful.titlebar(c, {
+        height    = 20,
+        bg_normal = "#ff0000",
+    })
+
+    -- buttons for the titlebar
+    local buttons = gears.table.join(
+        awful.button({ }, 1, function()
+            client.focus = c
+            c:raise()
+            awful.mouse.client.move(c)
+        end),
+        awful.button({ }, 3, function()
+            client.focus = c
+            c:raise()
+            awful.mouse.client.resize(c)
+        end)
+    )
+
+    top_titlebar : setup {
+        { -- Left
+            awful.titlebar.widget.iconwidget(c),
+            buttons = buttons,
+            layout  = wibox.layout.fixed.horizontal
+        },
+        { -- Middle
+            { -- Title
+                align  = "center",
+                widget = awful.titlebar.widget.titlewidget(c)
+            },
+            buttons = buttons,
+            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
+    }
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80