From c689af64d5c3f7f59834dece8803d6996a8b3ced Mon Sep 17 00:00:00 2001
From: Lucas Schwiderski <lucas@lschwiderski.de>
Date: Sat, 31 Jul 2021 14:48:33 +0200
Subject: [PATCH] doc(w.w.textbox): Improve ellipsize documentation

The list of possible values was missing one. Additionally, this adds an
example to visualize the available options.

Signed-off-by: Lucas Schwiderski <lucas@lschwiderski.de>
---
 lib/wibox/widget/textbox.lua                  | 17 ++++--
 .../wibox/widget/textbox/ellipsize.lua        | 59 +++++++++++++++++++
 2 files changed, 70 insertions(+), 6 deletions(-)
 create mode 100644 tests/examples/wibox/widget/textbox/ellipsize.lua

diff --git a/lib/wibox/widget/textbox.lua b/lib/wibox/widget/textbox.lua
index b4019381f..f51810879 100644
--- a/lib/wibox/widget/textbox.lua
+++ b/lib/wibox/widget/textbox.lua
@@ -222,17 +222,22 @@ function textbox:get_text()
     return self._private.layout.text
 end
 
---- Set a textbox ellipsize mode.
+--- Set the text ellipsize mode.
 --
 -- Valid values are:
 --
--- * **start**
--- * **middle**
--- * **end**
+-- * `"start"`
+-- * `"middle"`
+-- * `"end"`
+-- * `"none"`
+--
+-- See Pango for additional details:
+-- [Layout.set_ellipsize](https://docs.gtk.org/Pango/method.Layout.set_ellipsize.html)
+--
+--@DOC_wibox_widget_textbox_ellipsize_EXAMPLE@
 --
 -- @property ellipsize
--- @tparam string mode Where should long lines be shortened? "start", "middle"
---  or "end".
+-- @tparam string mode The ellipsize mode.
 -- @propemits true false
 
 function textbox:set_ellipsize(mode)
diff --git a/tests/examples/wibox/widget/textbox/ellipsize.lua b/tests/examples/wibox/widget/textbox/ellipsize.lua
new file mode 100644
index 000000000..f684a59e9
--- /dev/null
+++ b/tests/examples/wibox/widget/textbox/ellipsize.lua
@@ -0,0 +1,59 @@
+--DOC_GEN_IMAGE --DOC_HIDE
+
+--DOC_HIDE_START
+local parent = ...
+local wibox  = require("wibox")
+
+local widget = function(inner)
+    return wibox.widget {
+        {
+            {
+                inner,
+                margins = 5,
+                widget = wibox.container.margin,
+            },
+            border_width = 2,
+            widget = wibox.container.background,
+        },
+        strategy = "max",
+        height = 25,
+        widget = wibox.container.constraint,
+    }
+end
+
+local widgets = {
+--DOC_HIDE_END
+
+widget{
+    text = "This is a very long text, that cannot be displayed fully.",
+    ellipsize = "start",
+    widget = wibox.widget.textbox,
+},
+
+widget{
+    text = "This is a very long text, that cannot be displayed fully.",
+    ellipsize = "end",
+    widget = wibox.widget.textbox,
+},
+
+widget{
+    text = "This is a very long text, that cannot be displayed fully.",
+    ellipsize = "middle",
+    widget = wibox.widget.textbox,
+},
+
+widget{
+    text = "This is a very long text, that cannot be displayed fully.",
+    ellipsize = "none",
+    valign = "top",
+    widget = wibox.widget.textbox,
+}
+
+--DOC_HIDE_START
+}
+
+parent:set_children(widgets)
+
+return parent:fit({ dpi = 96 }, 150, 200)
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80