Merge pull request #3491 from Elv13/textbox_doc

Improve the textbox widget documentation.

.github/workflows/main.yml

@@ -126,7 +126,11 @@ jobs:
             xutils-dev \
             xvfb \
             zsh \
-            lua-discount
+            lua-discount \
+            fonts-noto-core \
+            fonts-dejavu-core \
+            fonts-roboto-unhinted \
+            fonts-open-sans
 
       - name: Install downloaded packages
         run: sudo dpkg -i /var/cache/apt/archives/*.deb

lib/wibox/container/background.lua

@@ -69,7 +69,7 @@ function background._use_fallback_algorithm()
                 cairo.Rectangle { x = 0, y = 0, width = mat.x0 + width, height = mat.y0 + height })
 
             local mask_cr = cairo.Context(mask)
-            mask_cr:translate(mat.x0, mat.y0)
+            mask_cr:set_matrix(mat)
 
             -- Clear the surface.
             mask_cr:set_operator(cairo.Operator.CLEAR)

lib/wibox/widget/textbox.lua

@@ -1,4 +1,5 @@
 ---------------------------------------------------------------------------
+-- A widget to display either plain or HTML text.
 --
 --@DOC_wibox_widget_defaults_textbox_EXAMPLE@
 --
@@ -177,11 +178,23 @@ function textbox:set_markup_silently(text)
     return true
 end
 
---- Set the text of the textbox (with
+--- Set the HTML text of the textbox.
--- [Pango markup](https://docs.gtk.org/Pango/pango_markup.html)).
+--
+-- The main difference between `text` and `markup` is that `markup` is
+-- able to render a small subset of HTML tags. See the
+-- [Pango markup](https://docs.gtk.org/Pango/pango_markup.html)) documentation
+-- to see what is and isn't valid in this property.
+--
+-- @DOC_wibox_widget_textbox_markup1_EXAMPLE@
+--
+-- The `wibox.widget.textbox` colors are usually set by wrapping into a
+-- `wibox.container.background` widget, but can also be done using the
+-- markup:
+--
+-- @DOC_wibox_widget_textbox_markup2_EXAMPLE@
 --
 -- @property markup
--- @tparam string text The text to set. This can contain pango markup (e.g.
+-- @tparam string markup The text to set. This can contain pango markup (e.g.
 --   `<b>bold</b>`). You can use `gears.string.escape` to escape
 --   parts of it.
 -- @propemits true false
@@ -198,7 +211,15 @@ function textbox:get_markup()
     return self._private.markup
 end
 
---- Set a textbox text.
+--- Set a textbox plain text.
+--
+-- This property renders the text as-is, it does not interpret it:
+--
+-- @DOC_wibox_widget_textbox_text1_EXAMPLE@
+--
+-- One exception are the control characters, which are interpreted:
+--
+-- @DOC_wibox_widget_textbox_text2_EXAMPLE@
 --
 -- @property text
 -- @tparam string text The text to display. Pango markup is ignored and shown
@@ -237,7 +258,7 @@ end
 --@DOC_wibox_widget_textbox_ellipsize_EXAMPLE@
 --
 -- @property ellipsize
--- @tparam string mode The ellipsize mode.
+-- @tparam[opt="end"] string mode The ellipsize mode.
 -- @propemits true false
 
 function textbox:set_ellipsize(mode)
@@ -261,8 +282,10 @@ end
 -- * **char**
 -- * **word_char**
 --
+-- @DOC_wibox_widget_textbox_wrap1_EXAMPLE@
+--
 -- @property wrap
--- @tparam string mode Where to wrap? After "word", "char" or "word_char".
+-- @tparam[opt="word_char"] string mode Where to wrap? After "word", "char" or "word_char".
 -- @propemits true false
 
 function textbox:set_wrap(mode)
@@ -286,8 +309,10 @@ end
 -- * **center**
 -- * **bottom**
 --
+--@DOC_wibox_widget_textbox_valign1_EXAMPLE@
+--
 -- @property valign
--- @tparam string mode Where should the textbox be drawn? "top", "center" or
+-- @tparam[opt="center"] string mode Where should the textbox be drawn? "top", "center" or
 --  "bottom".
 -- @propemits true false
 
@@ -312,8 +337,10 @@ end
 -- * **center**
 -- * **right**
 --
+--@DOC_wibox_widget_textbox_align1_EXAMPLE@
+--
 -- @property align
--- @tparam string mode Where should the textbox be drawn? "left", "center" or
+-- @tparam[opt="left"] string mode Where should the textbox be drawn? "left", "center" or
 --  "right".
 -- @propemits true false
 
@@ -363,10 +390,18 @@ end
 --
 -- In this case, the font could be `Sans 10` or `Sans Bold Italic 10`.
 --
+-- Here are examples of several font families:
+--
+--@DOC_wibox_widget_textbox_font1_EXAMPLE@
+--
+-- The font size is a number at the end of the font description string:
+--
+--@DOC_wibox_widget_textbox_font2_EXAMPLE@
+--
 -- @property font
--- @tparam string font The font description as string.
+-- @tparam[opt=beautiful.font] string font The font description as string.
 -- @propemits true false
--- @propbeautiful
+-- @usebeautiful beautiful.font The default font.
 
 function textbox:set_font(font)
     if font == self._private.font then return end
@@ -379,6 +414,10 @@ function textbox:set_font(font)
     self:emit_signal("property::font", font)
 end
 
+function textbox:get_font()
+    return self._private.font
+end
+
 --- Create a new textbox.
 --
 -- @tparam[opt=""] string text The textbox content

tests/examples/shims/beautiful.lua

@@ -50,7 +50,11 @@ module.progressbar_fg = module.bg_highlight
 
 local f = Pango.FontDescription.from_string("sans 8")
 
-function module.get_font()
+function module.get_font(font)
+    if font then
+        return Pango.FontDescription.from_string(font)
+    end
+
     return f
 end
 

tests/examples/wibox/layout/ratio/spacing_widget.lua

@@ -16,6 +16,7 @@ local w1 = wibox.widget {
 }
 
 l:add(w1) --DOC_HIDE
+--DOC_NEWLINE
 
 -- Use a standard declarative widget construct
 local w2 = wibox.widget {
@@ -32,6 +33,7 @@ local w2 = wibox.widget {
 }
 
 l:add(w2) --DOC_HIDE
+--DOC_NEWLINE
 
 -- Use composed widgets
 local w3 = wibox.widget {
@@ -51,6 +53,7 @@ local w3 = wibox.widget {
 }
 
 l:add(w3) --DOC_HIDE
+--DOC_NEWLINE
 
 -- Use negative spacing to create a powerline effect
 local w4 = wibox.widget {

tests/examples/wibox/widget/textbox/align1.lua

@@ -0,0 +1,43 @@
+--DOC_GEN_IMAGE --DOC_HIDE_START
+local l = ...
+local wibox = require("wibox")
+local beautiful = require("beautiful")
+
+local ret = wibox.layout.fixed.vertical()
+
+--DOC_HIDE_END
+for _, align in ipairs {"left", "center", "right"} do
+    local w = wibox.widget {
+        align  = align,
+        text   = "some text",
+        widget = wibox.widget.textbox,
+    }
+
+    --DOC_HIDE_START
+
+    ret:add(
+        wibox.widget {
+            markup = "Alignement: <b>" .. align .."</b>",
+            widget = wibox.widget.textbox
+        },
+        wibox.widget{
+            w,
+            margins =  1,
+            color = beautiful.bg_normal,
+            widget = wibox.container.margin,
+        },
+        {
+            forced_height = 10,
+            widget = wibox.widget.base.make_widget()
+        }
+    )
+    --DOC_HIDE_END
+end
+
+--DOC_HIDE_START
+
+l:add(ret)
+
+return 200, nil
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/wibox/widget/textbox/font1.lua

@@ -0,0 +1,61 @@
+--DOC_GEN_IMAGE --DOC_HIDE_START --DOC_NO_USAGE --DOC_GEN_OUTPUT
+local l = ...
+local wibox = require("wibox")
+local beautiful = require("beautiful")
+--DOC_HIDE_END
+   local pango = require("lgi").Pango
+--DOC_HIDE_START
+
+local ret = wibox.layout.fixed.vertical()
+
+--DOC_HIDE_END
+   local fonts = {
+       "sans",
+       "Roboto, Bold",
+       "DejaVu Sans, Oblique",
+       "Noto Mono, Regular"
+   }
+
+   --DOC_NEWLINE
+
+   for _, font in ipairs(fonts) do
+       local w = wibox.widget {
+           font   = font,
+           text   = "The quick brown fox jumps over the lazy dog!",
+           widget = wibox.widget.textbox,
+       }
+
+       --DOC_NEWLINE
+       -- Use the low level Pango API to validate the font was parsed properly.
+       local desc = pango.FontDescription.from_string(w.font)
+       print(w.font, desc:get_size(), desc:get_family(), desc:get_variant(), desc:get_style())
+
+    --DOC_HIDE_START
+
+    assert(w._private.font == font)
+
+    ret:add(
+        wibox.widget {
+            markup = "Font: <b>" .. font .."</b>",
+            widget = wibox.widget.textbox
+        },
+        wibox.widget{
+            w,
+            margins =  1,
+            color = beautiful.bg_normal,
+            forced_width = 500,
+            widget = wibox.container.margin,
+        },
+        {
+            forced_height = 10,
+            widget = wibox.widget.base.make_widget()
+        }
+    )
+    --DOC_HIDE_END
+   end
+
+--DOC_HIDE_START
+
+l:add(ret)
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/wibox/widget/textbox/font1.output.txt

@@ -0,0 +1,4 @@
+sans	0.0	sans	NORMAL	NORMAL
+Roboto, Bold	0.0	Roboto	NORMAL	NORMAL
+DejaVu Sans, Oblique	0.0	DejaVu Sans	NORMAL	OBLIQUE
+Noto Mono, Regular	0.0	Noto Mono	NORMAL	NORMAL

tests/examples/wibox/widget/textbox/font2.lua

@@ -0,0 +1,43 @@
+--DOC_GEN_IMAGE --DOC_HIDE_START --DOC_NO_USAGE
+local l = ...
+local wibox = require("wibox")
+local beautiful = require("beautiful")
+
+local ret = wibox.layout.fixed.vertical()
+
+--DOC_HIDE_END
+
+   for _, font in ipairs { "sans 8", "sans 10", "sans 12", "sans 14" } do
+       local w = wibox.widget {
+           font   = font,
+           text   = "The quick brown fox jumps over the lazy dog!",
+           widget = wibox.widget.textbox,
+       }
+
+    --DOC_HIDE_START
+
+    ret:add(
+        wibox.widget {
+            markup = "Font: <b>" .. font .."</b>",
+            widget = wibox.widget.textbox
+        },
+        wibox.widget{
+            w,
+            margins =  1,
+            color = beautiful.bg_normal,
+            forced_width = 500,
+            widget = wibox.container.margin,
+        },
+        {
+            forced_height = 10,
+            widget = wibox.widget.base.make_widget()
+        }
+    )
+    --DOC_HIDE_END
+   end
+
+--DOC_HIDE_START
+
+l:add(ret)
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/wibox/widget/textbox/markup1.lua

@@ -0,0 +1,20 @@
+--DOC_GEN_IMAGE --DOC_HIDE_START --DOC_NO_USAGE
+local l = ...
+local wibox = require("wibox")
+local beautiful = require("beautiful")
+
+--DOC_HIDE_END
+    local w = wibox.widget {
+        markup = "This is some <i>text</i>, <b>HTML tags</b> <u>WILL</u> work.",
+        widget = wibox.widget.textbox,
+    }
+--DOC_HIDE_START
+
+l:add(wibox.widget{
+    w,
+    margins =  1,
+    color = beautiful.bg_normal,
+    widget = wibox.container.margin,
+})
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/wibox/widget/textbox/markup2.lua

@@ -0,0 +1,21 @@
+--DOC_GEN_IMAGE --DOC_HIDE_START --DOC_NO_USAGE
+local l = ...
+local wibox = require("wibox")
+local beautiful = require("beautiful")
+
+--DOC_HIDE_END
+    local w = wibox.widget {
+        markup = "<span background='#ff0000' foreground='#0000ff'>Some</span>"..
+          " nice <span foreground='#00ff00'>colors!</span>",
+        widget = wibox.widget.textbox,
+    }
+--DOC_HIDE_START
+
+l:add(wibox.widget{
+    w,
+    margins =  1,
+    color = beautiful.bg_normal,
+    widget = wibox.container.margin,
+})
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/wibox/widget/textbox/text1.lua

@@ -0,0 +1,20 @@
+--DOC_GEN_IMAGE --DOC_HIDE_START --DOC_NO_USAGE
+local l = ...
+local wibox = require("wibox")
+local beautiful = require("beautiful")
+
+--DOC_HIDE_END
+    local w = wibox.widget {
+        text   = "This is some <i>text</i>, <b>HTML tags</b> will <u>NOT</u> work.",
+        widget = wibox.widget.textbox,
+    }
+--DOC_HIDE_START
+
+l:add(wibox.widget{
+    w,
+    margins =  1,
+    color = beautiful.bg_normal,
+    widget = wibox.container.margin,
+})
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/wibox/widget/textbox/text2.lua

@@ -0,0 +1,21 @@
+--DOC_GEN_IMAGE --DOC_HIDE_START --DOC_NO_USAGE
+local l = ...
+local wibox = require("wibox")
+local beautiful = require("beautiful")
+
+--DOC_HIDE_END
+    local w = wibox.widget {
+        text   = "This is some text\nover\nmultiple lines!",
+        widget = wibox.widget.textbox,
+    }
+--DOC_HIDE_START
+
+l:add(wibox.widget{
+    w,
+    margins =  1,
+    forced_height = 60,
+    color = beautiful.bg_normal,
+    widget = wibox.container.margin,
+})
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/wibox/widget/textbox/valign1.lua

@@ -0,0 +1,44 @@
+--DOC_GEN_IMAGE --DOC_HIDE_START
+local l = ...
+local wibox = require("wibox")
+local beautiful = require("beautiful")
+
+local ret = wibox.layout.fixed.vertical()
+
+--DOC_HIDE_END
+for _, valign in ipairs {"top", "center", "bottom"} do
+    local w = wibox.widget {
+        valign = valign,
+        text   = "some text",
+        widget = wibox.widget.textbox,
+        forced_height = 50, --DOC_HIDE
+    }
+
+    --DOC_HIDE_START
+
+    ret:add(
+        wibox.widget {
+            markup = "Alignement: <b>" .. valign .."</b>",
+            widget = wibox.widget.textbox
+        },
+        wibox.widget{
+            w,
+            margins =  1,
+            color = beautiful.bg_normal,
+            widget = wibox.container.margin,
+        },
+        {
+            forced_height = 10,
+            widget = wibox.widget.base.make_widget()
+        }
+    )
+    --DOC_HIDE_END
+end
+
+--DOC_HIDE_START
+
+l:add(ret)
+
+return 200, nil
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/wibox/widget/textbox/wrap1.lua

@@ -0,0 +1,42 @@
+--DOC_GEN_IMAGE --DOC_HIDE_START
+local l = ...
+local wibox = require("wibox")
+local beautiful = require("beautiful")
+
+local ret = wibox.layout.fixed.vertical()
+
+--DOC_HIDE_END
+for _, wrap in ipairs {"word", "char", "word_char"} do
+    local w = wibox.widget {
+        wrap   = wrap,
+        text   = "Notable dinausors: Tyrannosaurus-Rex, Triceratops, Velociraptor, Sauropods, Archaeopteryx.",
+        widget = wibox.widget.textbox,
+    }
+
+    --DOC_HIDE_START
+
+    ret:add(
+        wibox.widget {
+            markup = "Wrap: <b>" .. wrap .."</b>",
+            widget = wibox.widget.textbox
+        },
+        wibox.widget{
+            w,
+            margins       = 1,
+            color         = beautiful.bg_normal,
+            forced_width  = 85,
+            forced_height = 70,
+            widget        = wibox.container.margin,
+        },
+        {
+            forced_height = 10,
+            widget = wibox.widget.base.make_widget()
+        }
+    )
+    --DOC_HIDE_END
+end
+
+--DOC_HIDE_START
+
+l:add(ret)
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80