From d5d74e44dee9c846bef74464f7c00506ff42d26a Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Tue, 6 Jul 2021 01:19:13 -0700 Subject: [PATCH] doc: Document the wibar module. --- lib/awful/wibar.lua | 32 +++++++- tests/examples/awful/wibar/align.lua | 54 +++++++++++++ tests/examples/awful/wibar/margins.lua | 99 ++++++++++++++++++++++++ tests/examples/awful/wibar/position.lua | 36 +++++++++ tests/examples/awful/wibar/position2.lua | 38 +++++++++ tests/examples/awful/wibar/stretch.lua | 40 ++++++++++ tests/examples/screen/wibar_workarea.lua | 35 +++++++++ 7 files changed, 333 insertions(+), 1 deletion(-) create mode 100644 tests/examples/awful/wibar/align.lua create mode 100644 tests/examples/awful/wibar/margins.lua create mode 100644 tests/examples/awful/wibar/position.lua create mode 100644 tests/examples/awful/wibar/position2.lua create mode 100644 tests/examples/awful/wibar/stretch.lua create mode 100644 tests/examples/screen/wibar_workarea.lua diff --git a/lib/awful/wibar.lua b/lib/awful/wibar.lua index 1db40cd72..b816b4832 100644 --- a/lib/awful/wibar.lua +++ b/lib/awful/wibar.lua @@ -1,11 +1,13 @@ --------------------------------------------------------------------------- ---- Wibox module for awful. +--- The main AwesomeWM "bar" module. +-- -- This module allows you to easily create wibox and attach them to the edge of -- a screen. -- --@DOC_awful_wibar_default_EXAMPLE@ -- -- You can even have vertical bars too. +-- --@DOC_awful_wibar_left_EXAMPLE@ -- -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> @@ -56,6 +58,9 @@ local align_map = { } --- If the wibar needs to be stretched to fill the screen. +-- +-- @DOC_awful_wibar_stretch_EXAMPLE@ +-- -- @property stretch -- @tparam boolean stretch -- @propbeautiful @@ -72,6 +77,8 @@ local align_map = { -- * right -- * centered -- +-- @DOC_awful_wibar_align_EXAMPLE@ +-- -- @property align -- @tparam string align -- @propbeautiful @@ -83,17 +90,26 @@ local align_map = { -- It can either be a table if `top`, `bottom`, `left`, `right` or a -- single number. -- +-- @DOC_awful_wibar_margins_EXAMPLE@ +-- -- @property margins -- @tparam number|table margins -- @propbeautiful -- @propemits true false --- If the wibar needs to be stretched to fill the screen. +-- -- @beautiful beautiful.wibar_stretch -- @tparam boolean stretch --- Allow or deny the tiled clients to cover the wibar. -- +-- In the example below, we can see that the first screen workarea +-- shrunk by the height of the wibar while the second screen is +-- unchanged. +-- +-- @DOC_screen_wibar_workarea_EXAMPLE@ +-- -- @property update_workarea -- @tparam[opt=true] boolean update_workarea -- @propemits true false @@ -102,6 +118,15 @@ local align_map = { --- If there is both vertical and horizontal wibar, give more space to vertical ones. -- +-- By default, if multiple wibars risk overlapping, it will be resolved +-- by giving more space to the horizontal one: +-- +-- ![wibar position](../images/AUTOGEN_awful_wibar_position.svg) +-- +-- If this variable is to to `true`, it will behave like: +-- +-- @DOC_awful_wibar_position2_EXAMPLE@ +-- -- @beautiful beautiful.wibar_favor_vertical -- @tparam[opt=false] boolean favor_vertical @@ -263,6 +288,8 @@ end -- * top -- * bottom -- +-- @DOC_awful_wibar_position_EXAMPLE@ +-- -- @property position -- @tparam string position Either "left", right", "top" or "bottom" -- @propemits true false @@ -502,6 +529,9 @@ end -- @tparam[opt=nil] table args -- @tparam string args.position The position. -- @tparam string args.stretch If the wibar need to be stretched to fill the screen. +-- @tparam boolean args.update_workarea Allow or deny the tiled clients to cover the wibar. +-- @tparam string args.align How to align non-stretched wibars. +-- @tparam table|number args.margins The wibar margins. --@DOC_wibox_constructor_COMMON@ -- @return The new wibar -- @constructorfct awful.wibar diff --git a/tests/examples/awful/wibar/align.lua b/tests/examples/awful/wibar/align.lua new file mode 100644 index 000000000..4381be485 --- /dev/null +++ b/tests/examples/awful/wibar/align.lua @@ -0,0 +1,54 @@ +--DOC_GEN_IMAGE +--DOC_HIDE_START +local awful = require("awful") +local wibox = require("wibox") + +screen._track_workarea = true +screen[1]._resize {width = 360, height = 60} +screen._add_screen {x = 0, width = 360, height = 64, y = 72} --DOC_HIDE +screen._add_screen {x = 0, width = 360, height = 64, y = 144} --DOC_HIDE +screen._add_screen {x = 372, width = 64, height = 210, y = 0} --DOC_HIDE +screen._add_screen {x = 444, width = 64, height = 210, y = 0} --DOC_HIDE +screen._add_screen {x = 516, width = 64, height = 210, y = 0} --DOC_HIDE + +--DOC_HIDE_END + +for s, align in ipairs { "left", "centered", "right" } do + awful.wibar { + position = "top", + screen = screen[s], + stretch = false, + width = 196, + align = align, + widget = { + text = align, + align = "center", + widget = wibox.widget.textbox + }, + } +end + +--DOC_NEWLINE + +for s, align in ipairs { "top", "centered", "bottom" } do + awful.wibar { + position = "left", + screen = screen[s+3], + stretch = false, + height = 128, + align = align, + widget = { + { + text = align, + align = "center", + widget = wibox.widget.textbox + }, + direction = "east", + widget = wibox.container.rotate + }, + } +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 + diff --git a/tests/examples/awful/wibar/margins.lua b/tests/examples/awful/wibar/margins.lua new file mode 100644 index 000000000..e49ca87b3 --- /dev/null +++ b/tests/examples/awful/wibar/margins.lua @@ -0,0 +1,99 @@ +--DOC_GEN_IMAGE +--DOC_HIDE_START +local awful = require("awful") +local wibox = require("wibox") +local beautiful = require("beautiful") + +screen._track_workarea = true +screen[1]._resize {width = 480, height = 128} +screen._add_screen {x = 0, width = 480, height = 128, y = 140} + +local t1 = awful.tag.add("1", { + screen = screen[1], + selected = true, + layout = awful.layout.suit.tile.right, + gap = 4 +}) + +local c1 = client.gen_fake {hide_first=true, screen = screen[2]} +c1:tags{t1} + +local t2 = awful.tag.add("1", { + screen = screen[2], + selected = true, + layout = awful.layout.suit.tile.right, + gap = 4 +}) + +local c2 = client.gen_fake {hide_first=true} +c2:tags{t2} + +for _, c in ipairs {c1, c2} do + local top_titlebar = awful.titlebar(c, { + size = 20, + bg_normal = beautiful.bg_highligh, + }) + top_titlebar : setup { + { -- Left + awful.titlebar.widget.iconwidget(c), + layout = wibox.layout.fixed.horizontal + }, + { -- Middle + { -- Title + align = "center", + widget = awful.titlebar.widget.titlewidget(c) + }, + 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 + } +end + +--DOC_HIDE_END + +awful.wibar { + position = "top", + screen = screen[1], + stretch = false, + width = 196, + margins = 24, + widget = { + align = "center", + text = "unform margins", + widget = wibox.widget.textbox + } +} + +--DOC_NEWLINE + +awful.wibar { + position = "top", + screen = screen[2], + stretch = false, + width = 196, + margins = { + top = 12, + bottom = 5 + }, + widget = { + align = "center", + text = "non unform margins", + widget = wibox.widget.textbox + } + +} + +awful.layout.arrange(screen[1]) --DOC_HIDE +awful.layout.arrange(screen[2]) --DOC_HIDE +c1:_hide_all() --DOC_HIDE +c2:_hide_all() --DOC_HIDE + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/awful/wibar/position.lua b/tests/examples/awful/wibar/position.lua new file mode 100644 index 000000000..f017b463b --- /dev/null +++ b/tests/examples/awful/wibar/position.lua @@ -0,0 +1,36 @@ +--DOC_GEN_IMAGE --DOC_NO_USAGE +--DOC_HIDE_START +local awful = require("awful") +local wibox = require("wibox") + +screen[1]._resize {width = 480, height = 196} +--DOC_HIDE_END + + local colors = { + top = "#ffff00", + bottom = "#ff00ff", + left = "#00ffff", + right = "#ffcc00" + } + + --DOC_NEWLINE + + for _, position in ipairs { "top", "bottom", "left", "right" } do + awful.wibar { + position = position, + bg = colors[position], + widget = { + { + text = position, + align = "center", + widget = wibox.widget.textbox + }, + direction = (position == "left" or position == "right") and + "east" or "north", + widget = wibox.container.rotate + }, + } + end + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 + diff --git a/tests/examples/awful/wibar/position2.lua b/tests/examples/awful/wibar/position2.lua new file mode 100644 index 000000000..7ee8df342 --- /dev/null +++ b/tests/examples/awful/wibar/position2.lua @@ -0,0 +1,38 @@ +--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_ALL +--DOC_HIDE_START +local awful = require("awful") +local wibox = require("wibox") +local beautiful = require("beautiful") + +screen[1]._resize {width = 480, height = 196} + + local colors = { + top = "#ffff00", + bottom = "#ff00ff", + left = "#00ffff", + right = "#ffcc00" + } + +--DOC_HIDE_END + beautiful.wibar_favor_vertical = true + --DOC_NEWLINE + + for _, position in ipairs { "top", "bottom", "left", "right" } do + awful.wibar { + position = position, + bg = colors[position], + widget = { + { + text = position, + align = "center", + widget = wibox.widget.textbox + }, + direction = (position == "left" or position == "right") and + "east" or "north", + widget = wibox.container.rotate + }, + } + end + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 + diff --git a/tests/examples/awful/wibar/stretch.lua b/tests/examples/awful/wibar/stretch.lua new file mode 100644 index 000000000..35b5c5f88 --- /dev/null +++ b/tests/examples/awful/wibar/stretch.lua @@ -0,0 +1,40 @@ +--DOC_GEN_IMAGE +--DOC_HIDE_START +local awful = require("awful") +local wibox = require("wibox") + +screen._track_workarea = true +screen[1]._resize {width = 480, height = 60} +screen._add_screen {x = 0, width = 480, height = 64, y = 72} --DOC_HIDE + +--DOC_HIDE_END + +awful.wibar { + position = "top", + screen = screen[1], + stretch = true, + width = 196, + widget = { + text = "stretched", + align = "center", + widget = wibox.widget.textbox + }, +} + +--DOC_NEWLINE + +awful.wibar { + position = "top", + screen = screen[2], + stretch = false, + width = 196, + widget = { + text = "not stretched", + align = "center", + widget = wibox.widget.textbox + }, +} + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 + diff --git a/tests/examples/screen/wibar_workarea.lua b/tests/examples/screen/wibar_workarea.lua new file mode 100644 index 000000000..8726e3356 --- /dev/null +++ b/tests/examples/screen/wibar_workarea.lua @@ -0,0 +1,35 @@ +--DOC_GEN_IMAGE + +screen[1]._resize {x = 0, width = 640, height = 480} --DOC_HIDE + +screen._add_screen {x = 820, width = 640, height = 480, y = -22} --DOC_HIDE + +local awful = { --DOC_HIDE + wibar = require("awful.wibar"), --DOC_HIDE + tag = require("awful.tag"), --DOC_HIDE + tag_layout = require("awful.layout.suit.tile") --DOC_HIDE +} --DOC_HIDE + +local screen1_wibar = awful.wibar { + position = "top", + update_workarea = true, + height = 24, + screen = screen[1], +} + +--DOC_NEWLINE + +local screen2_wibar = awful.wibar { + position = "top", + update_workarea = false, + height = 24, + screen = screen[2], +} + +return { --DOC_HIDE + factor = 2 , --DOC_HIDE + show_boxes = true, --DOC_HIDE + draw_wibars = {screen1_wibar, screen2_wibar}, --DOC_HIDE + display_screen_info = false, --DOC_HIDE + draw_struts = true, --DOC_HIDE +} --DOC_HIDE