doc(w.l.align): Add module description

Signed-off-by: Lucas Schwiderski <lucas@lschwiderski.de>
This commit is contained in:
Lucas Schwiderski 2021-07-13 20:18:31 +02:00
parent 832483dd60
commit c1a3f02c88
No known key found for this signature in database
GPG Key ID: AA12679AAA6DF4D8
1 changed files with 64 additions and 30 deletions

View File

@ -1,6 +1,25 @@
--------------------------------------------------------------------------- ---------------------------------------------------------------------------
-- The `align` layout has three slots for child widgets. On its main axis, it
-- will use as much space as is available to it and distribute that to its child
-- widgets by stretching or shrinking them based on the chosen @{expand}
-- strategy.
-- On its secondary axis, the biggest child widget determines the size of the
-- layout, but smaller widgets will not be stretched to match it.
--
-- In its default configuration, the layout will give the first and third
-- widgets only the minimum space they ask for and it aligns them to the outer
-- edges. The remaining space between them is made available to the widget in
-- slot two.
--
-- This layout is most commonly used to split content into left/top, center and
-- right/bottom sections. As such, it is usually seen as the root layout in
-- @{awful.wibar}.
--
-- You may also fill just one or two of the widget slots, the @{expand} algorithm
-- will adjust accordingly.
-- --
--@DOC_wibox_layout_defaults_align_EXAMPLE@ --@DOC_wibox_layout_defaults_align_EXAMPLE@
--
-- @author Uli Schlachter -- @author Uli Schlachter
-- @copyright 2010 Uli Schlachter -- @copyright 2010 Uli Schlachter
-- @layoutmod wibox.layout.align -- @layoutmod wibox.layout.align
@ -140,8 +159,10 @@ function align:layout(context, width, height)
return result return result
end end
--- Set the layout's first widget. --- The widget in slot one.
-- This is the widget that is at the left/top --
-- This is the widget that is at the left/top.
--
-- @property first -- @property first
-- @tparam widget first -- @tparam widget first
-- @propemits true false -- @propemits true false
@ -155,7 +176,10 @@ function align:set_first(widget)
self:emit_signal("property::first", widget) self:emit_signal("property::first", widget)
end end
--- Set the layout's second widget. This is the centered one. --- The widget in slot two.
--
-- This is the centered one.
--
-- @property second -- @property second
-- @tparam widget second -- @tparam widget second
-- @propemits true false -- @propemits true false
@ -169,8 +193,10 @@ function align:set_second(widget)
self:emit_signal("property::second", widget) self:emit_signal("property::second", widget)
end end
--- Set the layout's third widget. --- The widget in slot three.
-- This is the widget that is at the right/bottom --
-- This is the widget that is at the right/bottom.
--
-- @property third -- @property third
-- @tparam widget third -- @tparam widget third
-- @propemits true false -- @propemits true false
@ -227,23 +253,27 @@ function align:fit(context, orig_width, orig_height)
return used_in_dir, used_in_other return used_in_dir, used_in_other
end end
--- Set the expand mode which determines how sub widgets expand to take up --- Set the expand mode, which determines how child widgets expand to take up
-- unused space. -- unused space.
-- --
-- The following values are valid: -- The following values are valid:
-- --
-- * "inside" - Default option. Size of outside widgets is determined using -- * `"inside"`: The widgets in slot one and three are set to their minimal
-- their fit function. Second, middle, or center widget expands to fill -- required size. The widget in slot two is then given the remaining space.
-- remaining space. -- This is the default behaviour.
-- * "outside" - Center widget is sized using its fit function and placed in -- * `"outside"`: The widget in slot two is set to its minimal required size and
-- the center of the allowed space. Outside widgets expand (or contract) to -- placed in the center of the space available to the layout. The other
-- fill remaining space on their side. -- widgets are then given the remaining space on either side.
-- * "none" - All widgets are sized using their fit function, drawn to only the -- If the center widget requires all available space, the outer widgets are
-- returned space, or remaining space, whichever is smaller. Center widget -- not drawn at all.
-- gets priority. -- * `"none"`: All widgets are given their minimal required size or the
-- remaining space, whichever is smaller. The center widget gets priority.
--
-- Attempting to set any other value than one of those three will fall back to
-- `"inside"`.
-- --
-- @property expand -- @property expand
-- @tparam[opt=inside] string mode How to use unused space. -- @tparam[opt="inside"] string mode How to use unused space.
function align:set_expand(mode) function align:set_expand(mode)
if mode == "none" or mode == "outside" then if mode == "none" or mode == "outside" then
@ -283,14 +313,16 @@ local function get_layout(dir, first, second, third)
return ret return ret
end end
--- Returns a new horizontal align layout. An align layout can display up to --- Returns a new horizontal align layout.
-- three widgets. The widget set via :set_left() is left-aligned. :set_right() --
-- sets a widget which will be right-aligned. The remaining space between those -- The three widget slots are aligned left, center and right.
-- two will be given to the widget set via :set_middle(). --
-- Additionally, this creates the aliases `set_left`, `set_middle` and
-- `set_right` to assign @{first}, @{second} and @{third} respectively.
-- @constructorfct wibox.layout.align.horizontal -- @constructorfct wibox.layout.align.horizontal
-- @tparam[opt] widget left Widget to be put to the left. -- @tparam[opt] widget left Widget to be put in slot one.
-- @tparam[opt] widget middle Widget to be put to the middle. -- @tparam[opt] widget middle Widget to be put in slot two.
-- @tparam[opt] widget right Widget to be put to the right. -- @tparam[opt] widget right Widget to be put in slot three.
function align.horizontal(left, middle, right) function align.horizontal(left, middle, right)
local ret = get_layout("x", left, middle, right) local ret = get_layout("x", left, middle, right)
@ -301,14 +333,16 @@ function align.horizontal(left, middle, right)
return ret return ret
end end
--- Returns a new vertical align layout. An align layout can display up to --- Returns a new vertical align layout.
-- three widgets. The widget set via :set_top() is top-aligned. :set_bottom() --
-- sets a widget which will be bottom-aligned. The remaining space between those -- The three widget slots are aligned top, center and bottom.
-- two will be given to the widget set via :set_middle(). --
-- Additionally, this creates the aliases `set_top`, `set_middle` and
-- `set_bottom` to assign @{first}, @{second} and @{third} respectively.
-- @constructorfct wibox.layout.align.vertical -- @constructorfct wibox.layout.align.vertical
-- @tparam[opt] widget top Widget to be put to the top. -- @tparam[opt] widget top Widget to be put in slot one.
-- @tparam[opt] widget middle Widget to be put to the middle. -- @tparam[opt] widget middle Widget to be put in slot two.
-- @tparam[opt] widget bottom Widget to be put to the right. -- @tparam[opt] widget bottom Widget to be put in slot three.
function align.vertical(top, middle, bottom) function align.vertical(top, middle, bottom)
local ret = get_layout("y", top, middle, bottom) local ret = get_layout("y", top, middle, bottom)