doc: Complete the widget documentation page.

This adds the `awful.widget` content along with some images.

docs/03-declarative-layout.md

@@ -34,7 +34,29 @@ configurable rules.
 
 @DOC_layout_WIDGET_LIST@
 
-### Other
+### Awful widgets
+
+This modules contains the higher level window manager widgets. Since most of them
+are used by the default config, here is how it maps:
+
+@DOC_awful_wibar_defaultwibar_EXAMPLE@
+
+@DOC_awidget_WIDGET_LIST@
+
+### Titlebar widgets
+
+The titlebar comes with some convinient default widgets. It simplify the most
+basic "Windows/macOS" like titlebars.
+
+@DOC_awful_titlebar_defaulttitlebar_EXAMPLE@
+
+Note that titlebars can also be added on
+each side. This is how "active" titlebars (click to resize) can be implemented.
+The default `rc.lua` does not add active borders:
+
+![](../images/client_geo.svg)
+
+### Notification widgets
 
 Notifications also have their own widgets.
 

docs/widget_lists.cmake

@@ -52,5 +52,6 @@ endfunction()
 generate_widget_list( "container" )
 generate_widget_list( "layout"    )
 generate_widget_list( "widget"    )
+generate_widget_list( "awidget"   )
 
 # vim: filetype=cmake:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80:foldmethod=marker

lib/awful/widget/button.lua

@@ -1,11 +1,7 @@
 ---------------------------------------------------------------------------
 -- A simple button widget.
 --
---    button.buttons = {
---        awful.button({}, 1, nil, function ()
---            print("Mouse was clicked")
---        end)
---    }
+-- @DOC_wibox_awidget_defaults_button_EXAMPLE@
 --
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Julien Danjou
@@ -18,6 +14,7 @@ local imagebox = require("wibox.widget.imagebox")
 local widget = require("wibox.widget.base")
 local surface = require("gears.surface")
 local cairo = require("lgi").cairo
+local gtable = require("gears.table")
 
 local button = { mt = {} }
 
@@ -25,10 +22,13 @@ local button = { mt = {} }
 -- a real button.
 --
 -- @constructorfct awful.widget.button
--- @param args Widget arguments. "image" is the image to display.
+-- @tparam table args Widget arguments.
+-- @tparam string args.image "image" is the image to display (mandatory).
+-- @tparam table args.buttons The buttons.
 -- @return A textbox widget configured as a button.
 function button.new(args)
-    if not args or not args.image then
+    args = args or {}
+    if not args.image then
         return widget.empty_widget()
     end
 
@@ -47,10 +47,14 @@ function button.new(args)
     end
     w:set_image(args.image)
 
-    w.buttons = {
+    local btns = gtable.clone(args.buttons or {}, false)
+
+    table.insert(btns,
         abutton({}, 1, function () orig_set_image(w, img_press) end,
                        function () orig_set_image(w, img_release) end)
-    }
+    )
+
+    w.buttons = btns
 
     w:connect_signal("mouse::leave", function(self) orig_set_image(self, img_release) end)
 

lib/awful/widget/watch.lua

@@ -24,6 +24,10 @@
 --
 -- ![Example screenshot](../images/awful_widget_watch.png)
 --
+-- Here is the most basic usage:
+--
+-- @DOC_wibox_awidget_defaults_watch_EXAMPLE@
+--
 -- @author Benjamin Petrenko
 -- @author Yauheni Kirylau
 -- @copyright 2015, 2016 Benjamin Petrenko, Yauheni Kirylau

tests/examples/awful/template.lua

@@ -39,6 +39,7 @@ if not rawget(screen, "no_outline") then
     for s in screen do
         cr:save()
         -- Draw the screen outline
+        if s._no_outline ~= true then
             cr:set_source(color("#00000044"))
             cr:set_line_width(1.5)
             cr:set_dash({10,4},1)
@@ -49,6 +50,7 @@ if not rawget(screen, "no_outline") then
             cr:set_source(color("#00000033"))
             cr:rectangle(s.workarea.x,s.workarea.y,s.workarea.width,s.workarea.height)
             cr:stroke()
+        end
 
         -- Draw the padding outline
         --TODO
@@ -67,7 +69,7 @@ local rect = {x1 = 0 ,y1 = 0 , x2 = 0 , y2 = 0}
 for _, obj in ipairs {drawin, client} do
     for _, d in ipairs(obj.get()) do
         local w = d.get_wibox and d:get_wibox() or d
-        if w and w.geometry then
+        if w and w.geometry and w.visible then
             local geo = w:geometry()
             rect.x1 = math.min(rect.x1, geo.x                                       )
             rect.y1 = math.min(rect.y1, geo.y                                       )
@@ -177,7 +179,7 @@ end
 
 for _, d in ipairs(drawin.get()) do
     local w = d.get_wibox and d:get_wibox() or nil
-    if w then
+    if w and w.visible then
         local geo = w:geometry()
         total_area:add_at(w:to_widget(), {x = geo.x, y = geo.y})
     end

tests/examples/awful/titlebar/defaulttitlebar.lua

@@ -0,0 +1,144 @@
+--DOC_GEN_IMAGE
+--DOC_HIDE_ALL
+--DOC_NO_USAGE
+--DOC_NO_DASH
+require("_date")
+local gears     = require("gears")
+local wibox     = require("wibox")
+local beautiful = require("beautiful") --DOC_HIDE
+local look      = require("_default_look")
+
+local offset = 0
+
+screen[1]._resize {width = 640, height = 240, y=offset}
+screen[1]._no_outline = true
+look.mywibox.visible = false
+
+local c = client.gen_fake {hide_first=true}
+
+c:geometry {
+    x      = 205,
+    y      = 110,
+    height = 60,
+    width  = 230,
+}
+c._old_geo = {c:geometry()}
+c:set_label("A client (window)")
+
+require("gears.timer").run_delayed_calls_now()
+
+-- The titlebar
+c:emit_signal("request::titlebars", "rules", {})--DOC_HIDE
+
+local overlay_w = wibox {
+    bg = "#00000000",
+    visible = true,
+    ontop = true,
+    y=0,
+    x=0,
+    width  = screen[1].geometry.width,
+    height = screen[1].geometry.height+offset,
+}
+
+local canvas = wibox.layout.manual()
+canvas.forced_height = 170
+canvas.forced_width  = 640
+overlay_w:set_widget(canvas)
+
+local function create_info(text, x, y, width, height)
+    y = y + offset
+    canvas:add_at(wibox.widget {
+        {
+            {
+                text = text,
+                align = "center",
+                ellipsize = "none",
+                wrap = "word",
+                widget = wibox.widget.textbox
+            },
+            margins = 3,
+            widget = wibox.container.margin
+        },
+        forced_width  = width,
+        forced_height = height,
+        shape = gears.shape.rectangle,
+        border_width = 1,
+        border_color = beautiful.border_color,
+        bg = "#ffff0055",
+        widget = wibox.container.background
+    }, {x = x, y = y})
+end
+
+local function create_section(x1, y, x2, text)
+    canvas:add_at(wibox.widget {
+        fit = function()
+            return x2-x1+6, 10
+        end,
+        draw = function(_, _, cr)
+            cr:set_source_rgb(0.8, 0.6, 1)
+            cr:set_line_width(1)
+            cr:move_to(1.5, 0)
+            cr:line_to(1.5, 10)
+            cr:stroke()
+            cr:move_to(x2-x1-1.5, 0)
+            cr:line_to(x2-x1-1.5, 10)
+            cr:stroke()
+            cr:move_to(1.5, 5)
+            cr:line_to(x2-x1-1.5, 5)
+            cr:stroke()
+        end,
+        layout = wibox.widget.base.make_widget,
+    }, {x=x1, y=y})
+
+    canvas:add_at(wibox.widget {
+        text = text,
+        align = "center",
+        ellipsize = "none",
+        wrap = "word",
+        forced_width = x2-x1,
+        widget = wibox.widget.textbox
+    }, {x=x1, y=y-12})
+
+end
+
+local function create_line(x1, y1, x2, y2)
+    y1, y2 = y1 + offset, y2 + offset
+    return canvas:add_at(wibox.widget {
+        fit = function()
+            return x2-x1+6, y2-y1+6
+        end,
+        draw = function(_, _, cr)
+            cr:set_source_rgb(0,0,0)
+            cr:set_line_width(1)
+            cr:arc(1.5, 1.5, 1.5, 0, math.pi*2)
+            cr:arc(x2-x1+1.5, y2-y1+1.5, 1.5, 0, math.pi*2)
+            cr:fill()
+            cr:move_to(1.5,1.5)
+            cr:line_to(x2-x1+1.5, y2-y1+1.5)
+            cr:stroke()
+        end,
+        layout = wibox.widget.base.make_widget,
+    }, {x=x1, y=y1})
+end
+
+create_info("awful.titlebar.widget.iconwidget", 10, 110, 190, 17)
+create_info("awful.titlebar.widget.titlewidget", 90, 85, 190, 17)
+create_info("awful.titlebar.widget.floatingbutton", 150, 65, 205, 17)
+create_info("awful.titlebar.widget.maximizedbutton", 150, 45, 220, 17)
+create_info("awful.titlebar.widget.stickybutton", 200, 25, 195, 17)
+create_info("awful.titlebar.widget.ontopbutton", 390, 85, 200, 17)
+create_info("awful.titlebar.widget.closebutton", 445, 110, 190, 17)
+
+create_line(385, 40, 385, 109) -- sticky
+create_line(365, 60, 365, 109) -- maximize
+create_line(345, 80, 345, 109) -- floating
+create_line(405, 100, 405, 109) -- ontop
+create_line(195, 120, 203, 120) -- icon
+create_line(437, 120, 445, 120) -- close
+create_line(245, 100, 245, 109) -- title
+
+create_section(205, 185, 205+230, 'wibox.layout.align.horizontal')
+create_section(205, 200, 205+24, '')
+create_section(230, 200, 330, '')
+create_section(330, 200, 435, '')
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/awful/wibar/defaultwibar.lua

@@ -0,0 +1,139 @@
+--DOC_GEN_IMAGE
+--DOC_HIDE_ALL
+--DOC_NO_USAGE
+--DOC_NO_DASH
+require("_date")
+local gears     = require("gears")
+local wibox     = require("wibox")
+local beautiful = require("beautiful") --DOC_HIDE
+local look      = require("_default_look")
+
+local offset = 60
+
+screen[1]._resize {width = 640, height = 140, y=offset}
+screen[1]._no_outline = true
+
+-- This example is used to show the various type of wibox awesome provides
+-- and mimic the default config look
+
+look.mypromptbox.text = "Run:"
+
+require("gears.timer").run_delayed_calls_now()
+-- The titlebar
+
+local overlay_w = wibox {
+    bg = "#00000000",
+    visible = true,
+    ontop = true,
+    y=0,
+    x=0,
+    width  = screen[1].geometry.width,
+    height = screen[1].geometry.height+offset,
+}
+
+local canvas = wibox.layout.manual()
+canvas.forced_height = 170
+canvas.forced_width  = 640
+overlay_w:set_widget(canvas)
+
+local function create_info(text, x, y, width, height)
+    y = y + offset
+    canvas:add_at(wibox.widget {
+        {
+            {
+                text = text,
+                align = "center",
+                ellipsize = "none",
+                wrap = "word",
+                widget = wibox.widget.textbox
+            },
+            margins = 3,
+            widget = wibox.container.margin
+        },
+        forced_width  = width,
+        forced_height = height,
+        shape = gears.shape.rectangle,
+        border_width = 1,
+        border_color = beautiful.border_color,
+        bg = "#ffff0055",
+        widget = wibox.container.background
+    }, {x = x, y = y})
+end
+
+local function create_section(x1, y, x2, text)
+    canvas:add_at(wibox.widget {
+        fit = function()
+            return x2-x1+6, 10
+        end,
+        draw = function(_, _, cr)
+            cr:set_source_rgb(0.8, 0.6, 1)
+            cr:set_line_width(1)
+            cr:move_to(1.5, 0)
+            cr:line_to(1.5, 10)
+            cr:stroke()
+            cr:move_to(x2-x1-1.5, 0)
+            cr:line_to(x2-x1-1.5, 10)
+            cr:stroke()
+            cr:move_to(1.5, 5)
+            cr:line_to(x2-x1-1.5, 5)
+            cr:stroke()
+        end,
+        layout = wibox.widget.base.make_widget,
+    }, {x=x1, y=y})
+
+    canvas:add_at(wibox.widget {
+        text = text,
+        align = "center",
+        ellipsize = "none",
+        wrap = "word",
+        forced_width = x2-x1,
+        widget = wibox.widget.textbox
+    }, {x=x1, y=y-12})
+
+end
+
+local function create_line(x1, y1, x2, y2)
+    y1, y2 = y1 + offset, y2 + offset
+    return canvas:add_at(wibox.widget {
+        fit = function()
+            return x2-x1+6, y2-y1+6
+        end,
+        draw = function(_, _, cr)
+            cr:set_source_rgb(0,0,0)
+            cr:set_line_width(1)
+            cr:arc(1.5, 1.5, 1.5, 0, math.pi*2)
+            cr:arc(x2-x1+1.5, y2-y1+1.5, 1.5, 0, math.pi*2)
+            cr:fill()
+            cr:move_to(1.5,1.5)
+            cr:line_to(x2-x1+1.5, y2-y1+1.5)
+            cr:stroke()
+        end,
+        layout = wibox.widget.base.make_widget,
+    }, {x=x1, y=y1})
+end
+
+create_info("awful.widget.launcher", 0, 40, 135, 17)
+create_info("awful.widget.prompt", 145, 15, 127, 17)
+create_info("awful.widget.taglist", 15, 15, 120, 17)
+create_info("awful.widget.tasklist", 240, 40, 130, 17)
+create_info("wibox.widget.systray", 380, 40, 130, 17)
+create_info("awful.widget.keyboardlayout", 315, 15, 170, 17)
+create_info("wibox.widget.textclock", 480, 60, 140, 17)
+create_info("awful.widget.layoutbox", 490, 80, 150, 17)
+
+create_line(5, 10, 5, 40) --launcher
+create_line(75, 10, 75, 15) --taglist
+create_line(150, 10, 150, 15) -- prompt
+create_line(305, 10, 305, 40) -- tasklist
+create_line(480, 10, 480, 15) -- keyboard
+create_line(600, 5, 600, 60)  --textclock
+create_line(630, 5, 630, 80) -- layoutbox
+create_line(500, 5, 500, 40) -- systray
+
+create_section(0, 10, 640, 'wibox.layout.align.horizontal')
+create_section(0, 30, 160, 'align first section (left)')
+create_section(0, 50, 160, 'wibox.layout.fixed.horizontal')
+create_section(165, 30, 460, 'align second section (middle)')
+create_section(465, 30, 640, 'align third section (right)')
+create_section(465, 50, 640, 'wibox.layout.fixed.horizontal')
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/shims/awesome.lua

@@ -82,6 +82,8 @@ function awesome.xrdb_get_value()
     return nil
 end
 
+function awesome.spawn() end
+
 -- Always show deprecated messages
 awesome.version   = "v9999"
 awesome.api_level = 9999

tests/examples/wibox/awidget/defaults/button.lua

@@ -0,0 +1,22 @@
+--DOC_GEN_IMAGE --DOC_HEADER --DOC_HIDE
+local parent = ... --DOC_NO_USAGE --DOC_HIDE
+local awful = {--DOC_HIDE
+    button = require("awful.button"), --DOC_HIDE
+    widget = {button = require("awful.widget.button")} --DOC_HIDE
+}--DOC_HIDE
+local beautiful = require("beautiful") --DOC_HIDE
+
+    local button = --DOC_HIDE
+    awful.widget.button {
+        image   = beautiful.awesome_icon,
+        buttons = {
+            awful.button({}, 1, nil, function ()
+                print("Mouse was clicked")
+            end)
+        }
+    }
+
+button.forced_height = 24 --DOC_HIDE
+button.forced_width = 24 --DOC_HIDE
+
+parent:add(button) --DOC_HIDE

tests/examples/wibox/awidget/defaults/clienticon.lua

@@ -0,0 +1,22 @@
+--DOC_GEN_IMAGE --DOC_HEADER --DOC_HIDE
+local parent = ... --DOC_NO_USAGE --DOC_HIDE
+local awful = {--DOC_HIDE
+    button = require("awful.button"), --DOC_HIDE
+    widget = {button = require("awful.widget.button")} --DOC_HIDE
+}--DOC_HIDE
+local beautiful = require("beautiful") --DOC_HIDE
+
+    local button = --DOC_HIDE
+    awful.widget.button {
+        image   = beautiful.awesome_icon,
+        buttons = {
+            awful.button({}, 1, nil, function ()
+                print("Mouse was clicked")
+            end)
+        }
+    }
+
+button.forced_height = 24 --DOC_HIDE
+button.forced_width = 24 --DOC_HIDE
+
+parent:add(button) --DOC_HIDE

tests/examples/wibox/awidget/defaults/keyboardlayout.lua

@@ -0,0 +1,13 @@
+--DOC_GEN_IMAGE --DOC_HIDE
+local parent = ... --DOC_HIDE
+local wibox  = require("wibox") --DOC_HIDE
+
+parent:add( --DOC_HIDE
+
+wibox.widget{
+    markup = "US",
+    widget = wibox.widget.textbox
+}
+
+) --DOC_HIDE
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/wibox/awidget/defaults/launcher.lua

@@ -0,0 +1,20 @@
+--DOC_GEN_IMAGE --DOC_HEADER --DOC_HIDE --DOC_HIDE_ALL
+local parent = ... --DOC_NO_USAGE --DOC_HIDE
+local awful = {--DOC_HIDE
+    widget = {launcher = require("awful.widget.launcher")} --DOC_HIDE
+}--DOC_HIDE
+local beautiful = require("beautiful") --DOC_HIDE
+
+    local mymainmenu = {}
+
+    local mylauncher = --DOC_HIDE
+    awful.widget.launcher {
+        image = beautiful.awesome_icon,
+        menu  = mymainmenu
+    }
+
+assert(mylauncher)
+mylauncher.forced_height = 24 --DOC_HIDE
+mylauncher.forced_width = 24 --DOC_HIDE
+
+parent:add(mylauncher) --DOC_HIDE

tests/examples/wibox/awidget/defaults/layoutbox.lua

@@ -0,0 +1,14 @@
+--DOC_GEN_IMAGE --DOC_HEADER --DOC_HIDE
+local parent = ... --DOC_NO_USAGE --DOC_HIDE
+local awful = {--DOC_HIDE
+    layout = require("awful.layout"), --DOC_HIDE
+    widget = {layoutbox = require("awful.widget.layoutbox")} --DOC_HIDE
+}--DOC_HIDE
+
+    local button = --DOC_HIDE
+    awful.widget.layoutbox {screen = 1}
+
+button.forced_height = 24 --DOC_HIDE
+button.forced_width = 24 --DOC_HIDE
+
+parent:add(button) --DOC_HIDE

tests/examples/wibox/awidget/defaults/layoutlist.lua

@@ -0,0 +1,31 @@
+--DOC_GEN_IMAGE --DOC_HEADER --DOC_HIDE
+local parent = ... --DOC_NO_USAGE --DOC_HIDE
+local awful = {--DOC_HIDE
+    widget = {layoutlist = require("awful.widget.layoutlist")}, --DOC_HIDE
+    layout = require("awful.layout") --DOC_HIDE
+}--DOC_HIDE
+local wibox = require("wibox") --DOC_HIDE
+
+local ll = --DOC_HIDE
+
+        awful.widget.layoutlist {
+            base_layout = wibox.layout.fixed.horizontal,
+            style = {
+                disable_name = true,
+                spacing      = 3,
+            },
+            source = function() return {
+                awful.layout.suit.floating,
+                awful.layout.suit.tile,
+                awful.layout.suit.tile.left,
+                awful.layout.suit.tile.bottom,
+                awful.layout.suit.tile.top,
+            } end,
+            screen      = 1,
+        }
+
+ll.forced_height = 24 --DOC_HIDE
+ll.forced_width = 100 --DOC_HIDE
+parent:add(ll) --DOC_HIDE
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

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

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

tests/examples/wibox/awidget/defaults/tasklist.lua

@@ -0,0 +1,32 @@
+--DOC_GEN_IMAGE --DOC_HIDE_ALL
+local parent = ... --DOC_NO_USAGE
+local awful = {
+    tag = require("awful.tag"),
+    placement = require("awful.placement"),
+    widget = {tasklist = require("awful.widget.tasklist")}
+}
+local beautiful = require("beautiful")
+
+local s = screen[1]
+local tasklist_buttons = nil -- To make luacheck shut up
+
+local t_real = awful.tag.add("Test", {screen=screen[1]})
+
+for i=1, 3 do
+    local c = client.gen_fake {x = 80, y = 55, width=75, height=50}
+    c:tags{t_real}
+    c.icon = beautiful.awesome_icon
+    c.name = " Client "..i.."  "
+end
+
+    s.mytasklist = awful.widget.tasklist {
+        screen   = s,
+        filter   = awful.widget.tasklist.filter.currenttags,
+        buttons  = tasklist_buttons,
+    }
+
+s.mytasklist.forced_width = 200
+s.mytasklist.forced_height = 18
+s.mytasklist._do_tasklist_update_now()
+
+parent:add( s.mytasklist)

tests/examples/wibox/awidget/defaults/watch.lua

@@ -0,0 +1,18 @@
+--DOC_HIDE DOC_GEN_IMAGE --DOC_HEADER
+local parent = ... --DOC_NO_USAGE --DOC_HIDE
+local awful = {--DOC_HIDE
+    button = require("awful.button"), --DOC_HIDE
+    widget = {watch = require("awful.widget.watch")} --DOC_HIDE
+}--DOC_HIDE
+local aspawn = require("awful.spawn") --DOC_HIDE
+aspawn.easy_async = function(_, cb)--DOC_HIDE
+    cb("Hello world!", "", nil, 0)--DOC_HIDE
+end--DOC_HIDE
+aspawn.with_line_callback = function() end --DOC_HIDE
+
+    local watch = --DOC_HIDE
+    awful.widget.watch('bash -c "echo Hello world! | grep Hello"', 15)
+
+watch.forced_height = 24 --DOC_HIDE
+
+parent:add(watch) --DOC_HIDE