awesomewm-mirrors
/
awesome
mirror of https://github.com/awesomeWM/awesome.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #3399 from sclu1034/feature/docs 

Various doc improvements nr. 4
This commit is contained in:
mergify[bot] 2021-08-03 01:12:11 +00:00 committed by GitHub
parent 832483dd60 0a68341c12
commit fcd5918bd9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 387 additions and 219 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

160
docs/common/cursor_c.ldoc
View File

@ -1,80 +1,80 @@
* <table class='widget_list' border=1>
* <tr><td>num_glyphs </td></tr>
* <tr><td>cursor </td></tr>
* <tr><td>arrow </td></tr>
* <tr><td>based_arrow_down </td></tr>
* <tr><td>based_arrow_up </td></tr>
* <tr><td>boat </td></tr>
* <tr><td>bogosity </td></tr>
* <tr><td>bottom_left_corner </td></tr>
* <tr><td>bottom_right_corner </td></tr>
* <tr><td>bottom_side </td></tr>
* <tr><td>bottom_tee </td></tr>
* <tr><td>box_spiral </td></tr>
* <tr><td>center_ptr </td></tr>
* <tr><td>circle </td></tr>
* <tr><td>clock </td></tr>
* <tr><td>coffee_mug </td></tr>
* <tr><td>cross </td></tr>
* <tr><td>cross_reverse </td></tr>
* <tr><td>crosshair </td></tr>
* <tr><td>diamond_cross </td></tr>
* <tr><td>dot </td></tr>
* <tr><td>dotbox </td></tr>
* <tr><td>double_arrow </td></tr>
* <tr><td>draft_large </td></tr>
* <tr><td>draft_small </td></tr>
* <tr><td>draped_box </td></tr>
* <tr><td>exchange </td></tr>
* <tr><td>fleur </td></tr>
* <tr><td>gobbler </td></tr>
* <tr><td>gumby </td></tr>
* <tr><td>hand </td></tr>
* <tr><td>hand </td></tr>
* <tr><td>heart </td></tr>
* <tr><td>icon </td></tr>
* <tr><td>iron_cross </td></tr>
* <tr><td>left_ptr </td></tr>
* <tr><td>left_side </td></tr>
* <tr><td>left_tee </td></tr>
* <tr><td>leftbutton </td></tr>
* <tr><td>ll_angle </td></tr>
* <tr><td>lr_angle </td></tr>
* <tr><td>man </td></tr>
* <tr><td>middlebutton </td></tr>
* <tr><td>mouse </td></tr>
* <tr><td>pencil </td></tr>
* <tr><td>pirate </td></tr>
* <tr><td>plus </td></tr>
* <tr><td>question_arrow </td></tr>
* <tr><td>right_ptr </td></tr>
* <tr><td>right_side </td></tr>
* <tr><td>right_tee </td></tr>
* <tr><td>rightbutton </td></tr>
* <tr><td>rtl_logo </td></tr>
* <tr><td>sailboat </td></tr>
* <tr><td>sb_down_arrow </td></tr>
* <tr><td>sb_h_double_arrow </td></tr>
* <tr><td>sb_left_arrow </td></tr>
* <tr><td>sb_right_arrow </td></tr>
* <tr><td>sb_up_arrow </td></tr>
* <tr><td>sb_v_double_arrow </td></tr>
* <tr><td>shuttle </td></tr>
* <tr><td>sizing </td></tr>
* <tr><td>spider </td></tr>
* <tr><td>spraycan </td></tr>
* <tr><td>star </td></tr>
* <tr><td>target </td></tr>
* <tr><td>tcross </td></tr>
* <tr><td>top_left_arrow </td></tr>
* <tr><td>top_left_corner </td></tr>
* <tr><td>top_right_corner </td></tr>
* <tr><td>top_side </td></tr>
* <tr><td>top_tee </td></tr>
* <tr><td>trek </td></tr>
* <tr><td>ul_angle </td></tr>
* <tr><td>umbrella </td></tr>
* <tr><td>ur_angle </td></tr>
* <tr><td>watch </td></tr>
* <tr><td>xterm </td></tr>
* </table>
<div class='flex-list'>
* <div>num_glyphs</div>
* <div>arrow</div>
* <div>based_arrow_down</div>
* <div>based_arrow_up</div>
* <div>boat</div>
* <div>bogosity</div>
* <div>bottom_left_corner</div>
* <div>bottom_right_corner</div>
* <div>bottom_side</div>
* <div>bottom_tee</div>
* <div>box_spiral</div>
* <div>center_ptr</div>
* <div>circle</div>
* <div>clock</div>
* <div>coffee_mug</div>
* <div>cross</div>
* <div>crosshair</div>
* <div>cross_reverse</div>
* <div>cursor</div>
* <div>diamond_cross</div>
* <div>dotbox</div>
* <div>dot</div>
* <div>double_arrow</div>
* <div>draft_large</div>
* <div>draft_small</div>
* <div>draped_box</div>
* <div>exchange</div>
* <div>fleur</div>
* <div>gobbler</div>
* <div>gumby</div>
* <div>hand</div>
* <div>hand</div>
* <div>heart</div>
* <div>icon</div>
* <div>iron_cross</div>
* <div>leftbutton</div>
* <div>left_ptr</div>
* <div>left_side</div>
* <div>left_tee</div>
* <div>ll_angle</div>
* <div>lr_angle</div>
* <div>man</div>
* <div>middlebutton</div>
* <div>mouse</div>
* <div>pencil</div>
* <div>pirate</div>
* <div>plus</div>
* <div>question_arrow</div>
* <div>rightbutton</div>
* <div>right_ptr</div>
* <div>right_side</div>
* <div>right_tee</div>
* <div>rtl_logo</div>
* <div>sailboat</div>
* <div>sb_down_arrow</div>
* <div>sb_h_double_arrow</div>
* <div>sb_left_arrow</div>
* <div>sb_right_arrow</div>
* <div>sb_up_arrow</div>
* <div>sb_v_double_arrow</div>
* <div>shuttle</div>
* <div>sizing</div>
* <div>spider</div>
* <div>spraycan</div>
* <div>star</div>
* <div>target</div>
* <div>tcross</div>
* <div>top_left_arrow</div>
* <div>top_left_corner</div>
* <div>top_right_corner</div>
* <div>top_side</div>
* <div>top_tee</div>
* <div>trek</div>
* <div>ul_angle</div>
* <div>umbrella</div>
* <div>ur_angle</div>
* <div>watch</div>
* <div>xterm</div>
* </div>

46
docs/common/fixed.ldoc
View File

@ -1,24 +1,25 @@
--- Set a widget at a specific index, replace the current one.
--- Set a widget at a specific index, replacing the current one.
--
-- @tparam number index A widget or a widget index
-- @tparam widget widget2 The widget to take the place of the first one
-- @treturn boolean If the operation is successful
-- @tparam widget widget2 The widget to replace the previous one with
-- @treturn boolean Returns `true` if the widget was replaced successfully,
-- `false` otherwise.
-- @method set
-- @emits widget::replaced
-- @emitstparam widget::replaced widget self The layout.
-- @emitstparam widget::replaced widget widget index The inserted widget.
-- @emitstparam widget::replaced widget widget The inserted widget.
-- @emitstparam widget::replaced widget previous The previous widget.
-- @emitstparam widget::replaced number index The replaced index.
-- @interface layout
--- Replace the first instance of `widget` in the layout with `widget2`.
--
-- **Signal:** widget::replaced The argument is the new widget and the old one
-- and the index.
-- @tparam widget widget The widget to replace
-- @tparam widget widget2 The widget to replace `widget` with
-- @tparam[opt=false] boolean recursive Dig in all compatible layouts to find the widget.
-- @treturn boolean If the operation is successful
-- @tparam[opt=false] boolean recursive Recurse into all compatible layouts to
-- find the widget.
-- @treturn boolean Returns `true` if the widget was replaced successfully,
-- `false` otherwise.
-- @method replace_widget
-- @emits widget::replaced
-- @emitstparam widget::replaced widget self The layout.
@ -31,35 +32,44 @@
--
-- @tparam number index1 The first widget index
-- @tparam number index2 The second widget index
-- @treturn boolean If the operation is successful
-- @treturn boolean Returns `true` if the widget was replaced successfully,
-- `false` otherwise.
-- @method swap
-- @emits widget::swapped
-- @emitstparam widget::swapped widget self The layout.
-- @emitstparam widget::swapped widget widget1 index The first widget.
-- @emitstparam widget::swapped widget widget2 index The second widget.
-- @emitstparam widget::swapped widget widget1 The first widget.
-- @emitstparam widget::swapped widget widget2 The second widget.
-- @emitstparam widget::swapped number index1 The first index.
-- @emitstparam widget::swapped number index1 The second index.
-- @interface layout
--- Swap 2 widgets in a layout.
-- If widget1 is present multiple time, only the first instance is swapped
-- **Signal:** widget::swapped The arguments are both widgets and both (new) indexes.
-- if the layouts not the same, then only `widget::replaced` will be emitted.
--
-- If `widget1` is present multiple time, only the first instance is swapped.
--
-- Calls `set` internally, so the signal `widget::replaced` is emitted for both
-- widgets as well.
--
-- @tparam widget widget1 The first widget
-- @tparam widget widget2 The second widget
-- @tparam[opt=false] boolean recursive Dig in all compatible layouts to find the widget.
-- @treturn boolean If the operation is successful
-- @tparam[opt=false] boolean recursive Recurse into all compatible layouts to
-- find the widget.
-- @treturn boolean Returns `true` if the widget was replaced successfully,
-- `false` otherwise.
-- @method swap_widgets
-- @emits widget::swapped
-- @emitstparam widget::swapped widget self The layout.
-- @emitstparam widget::swapped widget widget1 index The first widget.
-- @emitstparam widget::swapped widget widget2 index The second widget.
-- @emitstparam widget::swapped widget widget1 The first widget.
-- @emitstparam widget::swapped widget widget2 The second widget.
-- @emitstparam widget::swapped number index1 The first index.
-- @emitstparam widget::swapped number index1 The second index.
-- @interface layout
-- @see set
--- Reset the layout. This removes all widgets from the layout.
-- @method reset
-- @emits widget::reset
-- @emitstparam widget::reset widget self The layout.
-- @interface layout
-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

17
docs/ldoc.css
View File

@ -257,6 +257,23 @@ table th, table td {
border-bottom-width: 1px;
}
.flex-list {
display: flex;
flex-wrap: wrap;
}
.flex-list > div {
flex-grow: 1;
/* Use base width based on font size
to make sure text fits when zooming */
width: 9em;
text-align: center;
padding: 10px;
margin: 5px;
border: 1px solid rgb(193, 204, 228);
}
#about {
padding: 15px;
padding-left: 16em;

94
lib/wibox/layout/align.lua
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@
--
-- @author Uli Schlachter
-- @copyright 2010 Uli Schlachter
-- @layoutmod wibox.layout.align
@ -140,8 +159,10 @@ function align:layout(context, width, height)
return result
end
--- Set the layout's first widget.
-- This is the widget that is at the left/top
--- The widget in slot one.
--
-- This is the widget that is at the left/top.
--
-- @property first
-- @tparam widget first
-- @propemits true false
@ -155,7 +176,10 @@ function align:set_first(widget)
self:emit_signal("property::first", widget)
end
--- Set the layout's second widget. This is the centered one.
--- The widget in slot two.
--
-- This is the centered one.
--
-- @property second
-- @tparam widget second
-- @propemits true false
@ -169,8 +193,10 @@ function align:set_second(widget)
self:emit_signal("property::second", widget)
end
--- Set the layout's third widget.
-- This is the widget that is at the right/bottom
--- The widget in slot three.
--
-- This is the widget that is at the right/bottom.
--
-- @property third
-- @tparam widget third
-- @propemits true false
@ -227,23 +253,27 @@ function align:fit(context, orig_width, orig_height)
return used_in_dir, used_in_other
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.
--
-- The following values are valid:
--
-- * "inside" - Default option. Size of outside widgets is determined using
-- their fit function. Second, middle, or center widget expands to fill
-- remaining space.
-- * "outside" - Center widget is sized using its fit function and placed in
-- the center of the allowed space. Outside widgets expand (or contract) to
-- fill remaining space on their side.
-- * "none" - All widgets are sized using their fit function, drawn to only the
-- returned space, or remaining space, whichever is smaller. Center widget
-- gets priority.
-- * `"inside"`: The widgets in slot one and three are set to their minimal
-- required size. The widget in slot two is then given the remaining space.
-- This is the default behaviour.
-- * `"outside"`: The widget in slot two is set to its minimal required size and
-- placed in the center of the space available to the layout. The other
-- widgets are then given the remaining space on either side.
-- If the center widget requires all available space, the outer widgets are
-- not drawn at all.
-- * `"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
-- @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)
if mode == "none" or mode == "outside" then
@ -283,14 +313,16 @@ local function get_layout(dir, first, second, third)
return ret
end
--- Returns a new horizontal align layout. An align layout can display up to
-- 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
-- two will be given to the widget set via :set_middle().
--- Returns a new horizontal align layout.
--
-- The three widget slots are aligned left, center and right.
--
-- Additionally, this creates the aliases `set_left`, `set_middle` and
-- `set_right` to assign @{first}, @{second} and @{third} respectively.
-- @constructorfct wibox.layout.align.horizontal
-- @tparam[opt] widget left Widget to be put to the left.
-- @tparam[opt] widget middle Widget to be put to the middle.
-- @tparam[opt] widget right Widget to be put to the right.
-- @tparam[opt] widget left Widget to be put in slot one.
-- @tparam[opt] widget middle Widget to be put in slot two.
-- @tparam[opt] widget right Widget to be put in slot three.
function align.horizontal(left, middle, right)
local ret = get_layout("x", left, middle, right)
@ -301,14 +333,16 @@ function align.horizontal(left, middle, right)
return ret
end
--- Returns a new vertical align layout. An align layout can display up to
-- 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
-- two will be given to the widget set via :set_middle().
--- Returns a new vertical align layout.
--
-- The three widget slots are aligned top, center and bottom.
--
-- Additionally, this creates the aliases `set_top`, `set_middle` and
-- `set_bottom` to assign @{first}, @{second} and @{third} respectively.
-- @constructorfct wibox.layout.align.vertical
-- @tparam[opt] widget top Widget to be put to the top.
-- @tparam[opt] widget middle Widget to be put to the middle.
-- @tparam[opt] widget bottom Widget to be put to the right.
-- @tparam[opt] widget top Widget to be put in slot one.
-- @tparam[opt] widget middle Widget to be put in slot two.
-- @tparam[opt] widget bottom Widget to be put in slot three.
function align.vertical(top, middle, bottom)
local ret = get_layout("y", top, middle, bottom)

63
lib/wibox/layout/fixed.lua
View File

@ -1,6 +1,22 @@
---------------------------------------------------------------------------
-- A `fixed` layout may be initialized with any number of child widgets, and
-- during runtime widgets may be added and removed dynamically.
--
-- On the main axis, child widgets are given a fixed size of exactly as much
-- space as they ask for. The layout will then resize according to the sum of
-- all child widgets. If the space available to the layout is not enough to
-- include all child widgets, the excessive ones are not drawn at all.
--
-- Additionally, the layout allows adding empty spacing or even placing a custom
-- spacing widget between the child widget.
--
-- On its secondary axis, the layout's size is determined by the largest child
-- widget. Smaller child widgets are then placed with the same size.
-- Therefore, child widgets may ignore their `forced_width` or `forced_height`
-- properties for vertical and horizontal layouts respectively.
--
--@DOC_wibox_layout_defaults_fixed_EXAMPLE@
--
-- @author Uli Schlachter
-- @copyright 2010 Uli Schlachter
-- @layoutmod wibox.layout.fixed
@ -32,7 +48,7 @@ function fixed:layout(context, width, height)
spacing_widget = spacing ~= 0 and self._private.spacing_widget or nil
for k, v in pairs(self._private.widgets) do
for index, widget in pairs(self._private.widgets) do
local w, h, local_spacing = width - x, height - y, spacing
-- Some widget might be zero sized either because this is their
@ -43,8 +59,8 @@ function fixed:layout(context, width, height)
local zero = false
if is_y then
if k ~= widgets_nr or not self._private.fill_space then
h = select(2, base.fit_widget(self, context, v, w, h))
if index ~= widgets_nr or not self._private.fill_space then
h = select(2, base.fit_widget(self, context, widget, w, h))
zero = h == 0
end
@ -65,8 +81,8 @@ function fixed:layout(context, width, height)
end
end
else
if k ~= widgets_nr or not self._private.fill_space then
w = select(1, base.fit_widget(self, context, v, w, h))
if index ~= widgets_nr or not self._private.fill_space then
w = select(1, base.fit_widget(self, context, widget, w, h))
zero = w == 0
end
@ -94,16 +110,19 @@ function fixed:layout(context, width, height)
-- Place widget, even if it has zero width/height. Otherwise
-- any layout change for zero-sized widget would become invisible.
table.insert(result, base.place_widget_at(v, x, y, w, h))
table.insert(result, base.place_widget_at(widget, x, y, w, h))
x = is_x and x + w + local_spacing or x
y = is_y and y + h + local_spacing or y
-- Add the spacing widget (if needed)
if k < widgets_nr and spacing_widget then
if index < widgets_nr and spacing_widget then
table.insert(result, base.place_widget_at(
spacing_widget, is_x and (x - spoffset) or x, is_y and (y - spoffset) or y,
is_x and abspace or w, is_y and abspace or h
spacing_widget,
is_x and (x - spoffset) or x,
is_y and (y - spoffset) or y,
is_x and abspace or w,
is_y and abspace or h
))
end
end
@ -266,9 +285,13 @@ function fixed:set(index, widget2)
return true
end
--- The widget used to fill the spacing between the layout elements.
--- A widget to insert as a separator between child widgets.
--
-- By default, no widget is used.
-- If this property is a valid widget and `spacing` is greater than `0`, a
-- copy of this widget is inserted between each child widget, with its size in
-- the layout's main direction determined by `spacing`.
--
-- By default no widget is used and any `spacing` is applied as an empty offset.
--
--@DOC_wibox_layout_fixed_spacing_widget_EXAMPLE@
--
@ -406,29 +429,25 @@ local function get_layout(dir, widget1, ...)
return ret
end
--- Returns a new horizontal fixed layout. Each widget will get as much space as it
-- asks for and each widget will be drawn next to its neighboring widget.
-- Widgets can be added via :add() or as arguments to this function.
-- Note that widgets ignore `forced_height`. They will use the preferred/minimum width
-- on the horizontal axis, and a stretched height on the vertical axis.
--- Creates and returns a new horizontal fixed layout.
--
-- @tparam widget ... Widgets that should be added to the layout.
-- @constructorfct wibox.layout.fixed.horizontal
function fixed.horizontal(...)
return get_layout("x", ...)
end
--- Returns a new vertical fixed layout. Each widget will get as much space as it
-- asks for and each widget will be drawn next to its neighboring widget.
-- Widgets can be added via :add() or as arguments to this function.
-- Note that widgets ignore `forced_width`. They will use the preferred/minimum height
-- on the vertical axis, and a stretched width on the horizontal axis.
--- Creates and returns a new vertical fixed layout.
--
-- @tparam widget ... Widgets that should be added to the layout.
-- @constructorfct wibox.layout.fixed.vertical
function fixed.vertical(...)
return get_layout("y", ...)
end
--- Add spacing between each layout widgets.
--- The amount of space inserted between the child widgets.
--
-- If a `spacing_widget` is defined, this value is used for its size.
--
--@DOC_wibox_layout_fixed_spacing_EXAMPLE@
--

42
lib/wibox/layout/flex.lua
View File

@ -1,4 +1,19 @@
---------------------------------------------------------------------------
-- A `flex` layout may be initialized with any number of child widgets, and
-- during runtime widgets may be added and removed dynamically.
--
-- On the main axis, the layout will divide the available space evenly between
-- all child widgets, without any regard to how much space these widgets might
-- be asking for.
--
-- Just like @{wibox.layout.fixed}, `flex` allows adding spacing between the
-- widgets, either as an ofset via @{spacing} or with a
-- @{spacing_widget}.
--
-- On its secondary axis, the layout's size is determined by the largest child
-- widget. Smaller child widgets are then placed with the same size.
-- Therefore, child widgets may ignore their `forced_width` or `forced_height`
-- properties for vertical and horizontal layouts respectively.
--
--@DOC_wibox_layout_defaults_flex_EXAMPLE@
-- @author Uli Schlachter
@ -56,14 +71,18 @@ local flex = {}
-- @treturn boolean If the operation is successful
-- @method insert
-- @emits widget::inserted
-- @emitstparam widget::inserted widget self The fixed layout.
-- @emitstparam widget::inserted widget widget index The inserted widget.
-- @emitstparam widget::inserted widget self The layout.
-- @emitstparam widget::inserted widget widget The inserted widget.
-- @emitstparam widget::inserted number count The widget count.
-- @interface layout
--- The widget used to fill the spacing between the layout elements.
--- A widget to insert as a separator between child widgets.
--
-- By default, no widget is used.
-- If this property is a valid widget and @{spacing} is greater than `0`, a
-- copy of this widget is inserted between each child widget, with its size in
-- the layout's main direction determined by @{spacing}.
--
-- By default no widget is used and any @{spacing} is applied as an empty offset.
--
--@DOC_wibox_layout_flex_spacing_widget_EXAMPLE@
--
@ -72,13 +91,16 @@ local flex = {}
-- @propemits true false
-- @interface layout
--- Add spacing between each layout widgets.
--- The amount of space inserted between the child widgets.
--
-- If a @{spacing_widget} is defined, this value is used for its size.
--
--@DOC_wibox_layout_flex_spacing_EXAMPLE@
--
-- @property spacing
-- @tparam number spacing Spacing between widgets.
-- @propemits true false
-- @interface layout
function flex:layout(_, width, height)
local result = {}
@ -195,10 +217,7 @@ local function get_layout(dir, widget1, ...)
return ret
end
--- Returns a new horizontal flex layout.
--
-- A flex layout shares the available space.
-- equally among all widgets. Widgets can be added via `:add(widget)`.
--- Creates and returns a new horizontal flex layout.
--
-- @tparam widget ... Widgets that should be added to the layout.
-- @constructorfct wibox.layout.flex.horizontal
@ -206,10 +225,7 @@ function flex.horizontal(...)
return get_layout("horizontal", ...)
end
--- Returns a new vertical flex layout.
--
-- A flex layout shares the available space
-- equally among all widgets. Widgets can be added via `:add(widget)`.
--- Creates and returns a new vertical flex layout.
--
-- @tparam widget ... Widgets that should be added to the layout.
-- @constructorfct wibox.layout.flex.vertical

90
lib/wibox/widget/imagebox.lua
View File

@ -1,20 +1,20 @@
---------------------------------------------------------------------------
-- A widget to display image.
-- A widget to display an image.
--
-- The `wibox.widget.imagebox` is part of the Awesome WM's wiboxes system
-- The `wibox.widget.imagebox` is part of the Awesome WM's widget system
-- (see @{03-declarative-layout.md}).
--
-- This widget displays an image. The image can be a file,
-- a cairo image surface, or an rsvg handle object (see the
-- [image property](#image)).
--
-- Use a `wibox.widget.imagebox`
-- Examples using a `wibox.widget.imagebox`:
-- ---
--
-- @DOC_wibox_widget_defaults_imagebox_EXAMPLE@
--
-- Alternatively, you can declare the `imagebox` widget using the
-- declarative pattern (Both codes are strictly equivalent):
-- declarative pattern (both variants are strictly equivalent):
--
-- @DOC_wibox_widget_declarative-pattern_imagebox_EXAMPLE@
--
@ -219,15 +219,14 @@ end
--
-- It can can be any of the following:
--
-- * A `string` : Interpreted as the path to an image file,
-- * A cairo image surface : Directly used as is,
-- * An rsvg handle object : Directly used as is,
-- * `nil` : Unset the image.
-- * A `string`: Interpreted as a path to an image file
-- * A cairo image surface: Directly used as-is
-- * A librsvg handle object: Directly used as-is
-- * `nil`: Unset the image.
--
-- @property image
-- @tparam image image The image to render.
-- @propemits false false
-- @see set_image
--- Set the `imagebox` image.
--
@ -281,8 +280,9 @@ function imagebox:set_image(image)
end
--- Set a clip shape for this imagebox.
-- A clip shape define an area where the content is displayed and one where it
-- is trimmed.
--
-- A clip shape defines an area and dimension to which the content should be
-- trimmed.
--
-- @DOC_wibox_widget_imagebox_clip_shape_EXAMPLE@
--
@ -290,13 +290,13 @@ end
-- @tparam function|gears.shape clip_shape A `gears.shape` compatible shape function.
-- @propemits true false
-- @see gears.shape
-- @see set_clip_shape
--- Set a clip shape for this imagebox.
-- A clip shape define an area where the content is displayed and one where it
-- is trimmed.
--
-- Any other parameters will be passed to the clip shape function.
-- A clip shape defines an area and dimensions to which the content should be
-- trimmed.
--
-- Additional parameters will be passed to the clip shape function.
--
-- @tparam function|gears.shape clip_shape A `gears_shape` compatible shape function.
-- @method set_clip_shape
@ -330,35 +330,38 @@ end
--- Set the horizontal fit policy.
--
-- Values are:
-- Valid values are:
--
-- * **auto**: Honor the `resize` varible and preserve the aspect ratio (default).
-- * **none**: Do not resize at all.
-- * **fit**: Resize to the widget width.
-- * `"auto"`: Honor the `resize` variable and preserve the aspect ratio.
-- This is the default behaviour.
-- * `"none"`: Do not resize at all.
-- * `"fit"`: Resize to the widget width.
--
-- Here is the result for a 22x32 image:
--
-- @DOC_wibox_widget_imagebox_horizontal_fit_policy_EXAMPLE@
--
-- @property horizontal_fit_policy
-- @tparam[opt=auto] string horizontal_fit_policy
-- @propemits true false
-- @see vertical_fit_policy
-- @see resize
-- @property horizontal_fit_policy
-- @tparam[opt="auto"] string horizontal_fit_policy
-- @propemits true false
-- @see vertical_fit_policy
-- @see resize
--- Set the vertical fit policy.
-- Values are:
--
-- * **auto**: Honor the `resize` varible and preserve the aspect ratio (default).
-- * **none**: Do not resize at all.
-- * **fit**: Resize to the widget height.
-- Valid values are:
--
-- * `"auto"`: Honor the `resize` varible and preserve the aspect ratio.
-- This is the default behaviour.
-- * `"none"`: Do not resize at all.
-- * `"fit"`: Resize to the widget height.
--
-- Here is the result for a 32x22 image:
--
-- @DOC_wibox_widget_imagebox_vertical_fit_policy_EXAMPLE@
--
-- @property vertical_fit_policy
-- @tparam[opt=auto] string horizontal_fit_policy
-- @tparam[opt="auto"] string horizontal_fit_policy
-- @propemits true false
-- @see horizontal_fit_policy
-- @see resize
@ -368,14 +371,14 @@ end
--
-- Possible values are:
--
-- * *top*
-- * *center* (default)
-- * *bottom*
-- * `"top"`
-- * `"center"` (default)
-- * `"bottom"`
--
-- @DOC_wibox_widget_imagebox_valign_EXAMPLE@
--
-- @property valign
-- @tparam string avlign
-- @tparam[opt="center"] string valign
-- @propemits true false
-- @see wibox.container.place
-- @see halign
@ -384,14 +387,14 @@ end
--
-- Possible values are:
--
-- * *left*
-- * *center* (default)
-- * *right*
-- * `"left"`
-- * `"center"` (default)
-- * `"right"`
--
-- @DOC_wibox_widget_imagebox_halign_EXAMPLE@
--
-- @property halign
-- @tparam string halign
-- @tparam[opt="center"] string halign
-- @propemits true false
-- @see wibox.container.place
-- @see valign
@ -399,8 +402,9 @@ end
--- The maximum scaling factor.
--
-- If an image is scaled too much, it gets very blurry. This
-- property allows to limit the scaling. Use the `valign` and
-- `halign` to control how the image will be aligned.
-- property allows to limit the scaling.
-- Use the properties `valign` and `halign` to control how the image will be
-- aligned.
--
-- In the example below, the original size is 22x22
--
@ -432,13 +436,15 @@ end
-- <tr><td>bilinear</td><td>Linear interpolation in two dimensions</td></tr>
--</table>
--
-- The image used in the example below has a resolution of 32x22 and is intentionally
-- blocky to highlight the difference. It is zoomed by a factor of 3.
-- The image used in the example below has a resolution of 32x22 and is
-- intentionally blocky to highlight the difference.
-- It is zoomed by a factor of 3.
--
-- @DOC_wibox_widget_imagebox_scaling_quality_EXAMPLE@
--
-- @property scaling_quality
-- @tparam string scaling_quality Either `fast`, `good`, `best`, `nearest` or `bilinear`.
-- @tparam string scaling_quality Either `"fast"`, `"good"`, `"best"`,
-- `"nearest"` or `"bilinear"`.
-- @propemits true false
-- @see resize
-- @see horizontal_fit_policy

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

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

2
mousegrabber.c
View File

@ -82,7 +82,7 @@ mousegrabber_handleevent(lua_State *L, int x, int y, uint16_t mask)
* The function is called with one argument:
* a table containing modifiers pointer coordinates.
*
* The list of valid cusrors are:
* The list of valid cursors is:
*
*@DOC_cursor_c_COMMON@
*

16
tests/examples/wibox/container/defaults/radialprogressbar.lua
View File

@ -1,6 +1,6 @@
--DOC_HIDE_ALL
--DOC_HIDE_START
--DOC_GEN_IMAGE
local wibox = require("wibox")
local wibox = require("wibox")
return {
text = "Before",
@ -9,6 +9,7 @@ return {
widget = wibox.widget.textbox,
},
{
--DOC_HIDE_END
{
{
text = "After",
@ -16,13 +17,14 @@ return {
valign = "center",
widget = wibox.widget.textbox,
},
value = 0.5,
max_value = 1,
min_value = 0,
widget = wibox.container.radialprogressbar
value = 0.5,
max_value = 1,
min_value = 0,
widget = wibox.container.radialprogressbar
},
--DOC_HIDE_START
margins = 5,
layout = wibox.container.margin
}
--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

59
tests/examples/wibox/widget/textbox/ellipsize.lua Normal file
View File

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