Merge pull request #2123 from Elv13/doc_tests_and_notif_p2_3

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"
@@ -513,6 +518,9 @@ local function new(c, args)
     -- Handle declarative/recursive widget container
     ret.setup = base.widget.setup
 
+    c._private = c._private or {}
+    c._private.titlebars = bars
+
     return ret
 end
 

lib/gears/surface.lua

@@ -51,7 +51,13 @@ function surface.load_uncached_silently(_surface, default)
         if not pixbuf then
             return get_default(default), tostring(err)
         end
-        _surface = capi.awesome.pixbuf_to_surface(pixbuf._native)
+        _surface = capi.awesome.pixbuf_to_surface(pixbuf._native, _surface)
+
+        -- The shims implement load_image() to return a surface directly,
+        -- instead of a lightuserdatum.
+        if cairo.Surface:is_type_of(_surface) then
+            return _surface
+        end
     end
     -- Everything else gets forced into a surface
     return cairo.Surface(_surface, true)

luaa.c

@@ -284,6 +284,7 @@ luaA_sync(lua_State *L)
 /** Translate a GdkPixbuf to a cairo image surface..
  *
  * @param pixbuf The pixbuf as a light user datum.
+ * @param path The pixbuf origin path
  * @return A cairo surface as light user datum.
  * @function pixbuf_to_surface
  */

tests/examples/awful/template.lua

@@ -94,7 +94,7 @@ local function client_widget(c, col, label)
     local l = wibox.layout.align.vertical()
     l.fill_space = true
 
-    local tbs = c.titlebars or {}
+    local tbs = c._private and c._private.titlebars or {}
 
     local map = {
         top    = "set_first",

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

tests/examples/shims/awesome.lua

@@ -1,6 +1,4 @@
 local lgi       = require("lgi")
-local GdkPixbuf = lgi.GdkPixbuf
-local Gdk       = lgi.Gdk
 local gears_obj = require("gears.object")
 
 -- Emulate the C API classes. They differ from C API objects as connect_signal
@@ -48,27 +46,10 @@ awesome.startup = true
 function awesome.register_xproperty()
 end
 
-local init, surfaces = false, {}
+awesome.load_image = lgi.cairo.ImageSurface.create_from_png
 
-function awesome.load_image(file)
-    if not init then
-        Gdk.init{}
-        init = true
-    end
-
-    local _, width, height = GdkPixbuf.Pixbuf.get_file_info(file)
-
-    local pixbuf = GdkPixbuf.Pixbuf.new_from_file_at_size(file, width, height)
-
-    if not pixbuf then
-        return nil, "Could not load "..file
-    end
-
-    local s = Gdk.cairo_surface_create_from_pixbuf( pixbuf, 1, nil )
-
-    table.insert(surfaces, s)
-
-    return s._native, not s and "Could not load surface from "..file or nil, s
+function awesome.pixbuf_to_surface(_, path)
+    return awesome.load_image(path)
 end
 
 -- Always show deprecated messages