From 42a86efa5088faf333378cd6d628dee0980fe5d2 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 9 Aug 2020 23:34:37 -0700 Subject: [PATCH] doc: Document some of the `tag` properties. --- lib/awful/tag.lua | 25 ++++++++- .../screen/gap_single_client_false.lua | 42 ++++++++++++++ .../screen/gap_single_client_true.lua | 42 ++++++++++++++ tests/examples/screen/gaps.lua | 43 +++++++++++++++ tests/examples/screen/gaps2.lua | 43 +++++++++++++++ tests/examples/screen/mwfact.lua | 55 +++++++++++++++++++ 6 files changed, 249 insertions(+), 1 deletion(-) create mode 100644 tests/examples/screen/gap_single_client_false.lua create mode 100644 tests/examples/screen/gap_single_client_true.lua create mode 100644 tests/examples/screen/gaps.lua create mode 100644 tests/examples/screen/gaps2.lua create mode 100644 tests/examples/screen/mwfact.lua diff --git a/lib/awful/tag.lua b/lib/awful/tag.lua index 2e3c3f1b..94bd600d 100644 --- a/lib/awful/tag.lua +++ b/lib/awful/tag.lua @@ -713,6 +713,8 @@ end -- See the layout suit documentation for information about how the master width -- factor is used. -- +-- @DOC_screen_mwfact_EXAMPLE@ +-- -- **Signal:** -- -- * *property::mwfact* (deprecated) @@ -1088,9 +1090,17 @@ end --- The gap (spacing, also called `useless_gap`) between clients. -- --- This property allow to waste space on the screen in the name of style, +-- This property allows to waste space on the screen in the name of style, -- unicorns and readability. -- +-- In this example, the value of `gap` is set to 20: +-- +-- @DOC_screen_gaps_EXAMPLE@ +-- +-- Compared to setting to the (very high) value of 50: +-- +-- @DOC_screen_gaps2_EXAMPLE@ +-- -- **Signal:** -- -- * *property::useless_gap* @@ -1141,6 +1151,19 @@ end --- Enable gaps for a single client. -- +-- If the gaps are used purely for readability when multiple +-- clients are tiled, then it may make sense to disable it +-- when there is only a single client (to recover that space). +-- In that case, set `gap_single_client` to `false`. +-- +-- Default (with a 20px gap): +-- +-- @DOC_screen_gap_single_client_true_EXAMPLE@ +-- +-- when set to false: +-- +-- @DOC_screen_gap_single_client_false_EXAMPLE@ +-- -- **Signal:** -- -- * *property::gap\_single\_client* diff --git a/tests/examples/screen/gap_single_client_false.lua b/tests/examples/screen/gap_single_client_false.lua new file mode 100644 index 00000000..fd09a79e --- /dev/null +++ b/tests/examples/screen/gap_single_client_false.lua @@ -0,0 +1,42 @@ +--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_ALL + +screen[1]._resize {x = 0, width = 640, height = 480} + +local awful = { + wibar = require("awful.wibar"), + tag = require("awful.tag"), + tag_layout = require("awful.layout.suit.tile") +} + +screen[1].padding = { + left = 40, + right = 40, + top = 20, + bottom = 20, +} + +local wibar = awful.wibar { + position = "top", + height = 24, +} + +awful.tag.add("1", { + screen = screen[1], + selected = true, + layout = awful.tag_layout.right, + gap = 20, + gap_single_client = false, +}) + +local clients = { + ['client #1'] = client.gen_fake{}, +} + +return { + factor = 2 , + show_boxes = true, + draw_wibar = wibar, + draw_clients = clients, + display_screen_info = false, + draw_gaps = true, +} diff --git a/tests/examples/screen/gap_single_client_true.lua b/tests/examples/screen/gap_single_client_true.lua new file mode 100644 index 00000000..53a75434 --- /dev/null +++ b/tests/examples/screen/gap_single_client_true.lua @@ -0,0 +1,42 @@ +--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_ALL + +screen[1]._resize {x = 0, width = 640, height = 480} + +local awful = { + wibar = require("awful.wibar"), + tag = require("awful.tag"), + tag_layout = require("awful.layout.suit.tile") +} + +screen[1].padding = { + left = 40, + right = 40, + top = 20, + bottom = 20, +} + +local wibar = awful.wibar { + position = "top", + height = 24, +} + +awful.tag.add("1", { + screen = screen[1], + selected = true, + layout = awful.tag_layout.right, + gap = 20, + gap_single_client = true, -- its the default +}) + +local clients = { + ['client #1'] = client.gen_fake{}, +} + +return { + factor = 2 , + show_boxes = true, + draw_wibar = wibar, + draw_clients = clients, + display_screen_info = false, + draw_gaps = true, +} diff --git a/tests/examples/screen/gaps.lua b/tests/examples/screen/gaps.lua new file mode 100644 index 00000000..d8f358ca --- /dev/null +++ b/tests/examples/screen/gaps.lua @@ -0,0 +1,43 @@ +--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_ALL + +screen[1]._resize {x = 0, width = 640, height = 480} + +local awful = { + wibar = require("awful.wibar"), + tag = require("awful.tag"), + tag_layout = require("awful.layout.suit.tile") +} + +screen[1].padding = { + left = 40, + right = 40, + top = 20, + bottom = 20, +} + +local wibar = awful.wibar { + position = "top", + height = 24, +} + +awful.tag.add("1", { + screen = screen[1], + selected = true, + layout = awful.tag_layout.right, + gap = 20 +}) + +local clients = { + ['client #1'] = client.gen_fake{}, + ['client #2'] = client.gen_fake{}, + ['client #3'] = client.gen_fake{} +} + +return { + factor = 2 , + show_boxes = true, + draw_wibar = wibar, + draw_clients = clients, + display_screen_info = false, + draw_gaps = true, +} diff --git a/tests/examples/screen/gaps2.lua b/tests/examples/screen/gaps2.lua new file mode 100644 index 00000000..544c5833 --- /dev/null +++ b/tests/examples/screen/gaps2.lua @@ -0,0 +1,43 @@ +--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_ALL + +screen[1]._resize {x = 0, width = 640, height = 480} + +local awful = { + wibar = require("awful.wibar"), + tag = require("awful.tag"), + tag_layout = require("awful.layout.suit.tile") +} + +screen[1].padding = { + left = 40, + right = 40, + top = 20, + bottom = 20, +} + +local wibar = awful.wibar { + position = "top", + height = 24, +} + +awful.tag.add("1", { + screen = screen[1], + selected = true, + layout = awful.tag_layout.right, + gap = 50 +}) + +local clients = { + ['client #1'] = client.gen_fake{}, + ['client #2'] = client.gen_fake{}, + ['client #3'] = client.gen_fake{} +} + +return { + factor = 2 , + show_boxes = true, + draw_wibar = wibar, + draw_clients = clients, + display_screen_info = false, + draw_gaps = true, +} diff --git a/tests/examples/screen/mwfact.lua b/tests/examples/screen/mwfact.lua new file mode 100644 index 00000000..10767a4e --- /dev/null +++ b/tests/examples/screen/mwfact.lua @@ -0,0 +1,55 @@ +--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_ALL + +screen[1]._resize {x = 0, width = 640, height = 480} + + +local awful = { + wibar = require("awful.wibar"), + tag = require("awful.tag"), + tag_layout = require("awful.layout.suit.tile") +} + +function awful.spawn(_, args) + local c = client.gen_fake{} + c:tags({args.tag}) + assert(#c:tags() == 1) + assert(c:tags()[1] == args.tag) +end + +screen[1].padding = { + left = 40, + right = 40, + top = 20, + bottom = 20, +} + +local wibar = awful.wibar { + position = "top", + height = 24, +} + +awful.tag.add("1", { + screen = screen[1], + selected = true, + layout = awful.tag_layout.right, + gap = 5, + master_width_factor = 0.66 +}) + +local clients = { + ['master #1 (66%)'] = client.gen_fake{}, + ['slave #1 (33%)'] = client.gen_fake{}, + ['slave #2 (33%)'] = client.gen_fake{} +} +for _,c in ipairs(clients) do + c:tags{"1"} +end + +return { + factor = 2 , + show_boxes = true, + draw_wibar = wibar, + draw_clients = clients, + display_screen_info = false, + draw_mwfact = true, +}