From 6921dc9f4cc87a9c31ae0b294b4385272a7a68cc Mon Sep 17 00:00:00 2001
From: Emmanuel Lepage Vallee <elv1313@gmail.com>
Date: Sun, 2 Jul 2017 10:56:53 -0400
Subject: [PATCH] doc: Add a titlebar example

---
 lib/awful/titlebar.lua                    | 13 +++--
 tests/examples/awful/titlebar/default.lua | 60 +++++++++++++++++++++++
 2 files changed, 69 insertions(+), 4 deletions(-)
 create mode 100644 tests/examples/awful/titlebar/default.lua

diff --git a/lib/awful/titlebar.lua b/lib/awful/titlebar.lua
index 0be553d4..969b4076 100644
--- a/lib/awful/titlebar.lua
+++ b/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"
diff --git a/tests/examples/awful/titlebar/default.lua b/tests/examples/awful/titlebar/default.lua
new file mode 100644
index 00000000..b82cba68
--- /dev/null
+++ b/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