Aire-One
/
awesome
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge pull request #3491 from Elv13/textbox_doc 

Improve the textbox widget documentation.
This commit is contained in:
Emmanuel Lepage Vallée 2021-11-03 12:40:39 -07:00 committed by GitHub
parent 50b9b10437 1fa0204d80
commit d95934d209
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
15 changed files with 382 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
.github/workflows/main.yml vendored
View File

@ -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

2
lib/wibox/container/background.lua
View File

@ -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)

59
lib/wibox/widget/textbox.lua
View File

@ -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
-- [Pango markup](https://docs.gtk.org/Pango/pango_markup.html)).
--- Set the HTML text of the textbox.
--
-- 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

6
tests/examples/shims/beautiful.lua
View File

@ -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

3
tests/examples/wibox/layout/ratio/spacing_widget.lua
View File

@ -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 {

43
tests/examples/wibox/widget/textbox/align1.lua Normal file
View File

@ -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

61
tests/examples/wibox/widget/textbox/font1.lua Normal file
View File

@ -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

4
tests/examples/wibox/widget/textbox/font1.output.txt Normal file
View File

@ -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

43
tests/examples/wibox/widget/textbox/font2.lua Normal file
View File

@ -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

20
tests/examples/wibox/widget/textbox/markup1.lua Normal file
View File

@ -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

21
tests/examples/wibox/widget/textbox/markup2.lua Normal file
View File

@ -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

20
tests/examples/wibox/widget/textbox/text1.lua Normal file
View File

@ -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

21
tests/examples/wibox/widget/textbox/text2.lua Normal file
View File

@ -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

44
tests/examples/wibox/widget/textbox/valign1.lua Normal file
View File

@ -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

42
tests/examples/wibox/widget/textbox/wrap1.lua Normal file
View File

@ -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