diff --git a/CMakeLists.txt b/CMakeLists.txt index 370f611d4..c05a7fbc9 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -292,7 +292,7 @@ if(GENERATE_DOC) configure_file(${SOURCE_DIR}/docs/ldoc.ltp ${BUILD_DIR}/docs COPYONLY) add_custom_target(ldoc ALL - DEPENDS ${BUILD_DIR}/doc/index.html + DEPENDS ${BUILD_DIR}/doc/index.html DOC_EXAMPLES_PPOSTPROCESS_CLEANUP ) if (STRICT_TESTS) diff --git a/build-utils/check_for_invalid_requires.lua b/build-utils/check_for_invalid_requires.lua index 1c9cd29c7..d0adad300 100755 --- a/build-utils/check_for_invalid_requires.lua +++ b/build-utils/check_for_invalid_requires.lua @@ -62,7 +62,10 @@ local allowed_deps = { naughty = true, }, -- TODO: Get rid of these - ["gears.surface"] = { ["wibox.hierarchy"] = true }, + ["gears.surface"] = { + ["wibox.hierarchy"] = true, + beautiful = true, + }, } -- Turn "foo.bar.baz" into "foo.bar". Returns nil if there is nothing more to diff --git a/dbus.c b/dbus.c index f339fcddc..97069858c 100644 --- a/dbus.c +++ b/dbus.c @@ -19,7 +19,14 @@ * */ -/** awesome D-Bus API +/** A deprecated low-level D-Bus API **DO NOT USE**. + * + * `lgi.GDBus` is always better. This module will eventually be removed. + * If it ever breaks due to an upstream API change, it wont be fixed. + * + * It still exists for compatibility reasons since some user have used it + * in the past. + * * @author Julien Danjou <julien@danjou.info> * @copyright 2008-2009 Julien Danjou * @module dbus @@ -798,10 +805,10 @@ luaA_dbus_disconnect_signal(lua_State *L) * @param path A string with the dbus path. * @param interface A string with the dbus interface. * @param method A string with the dbus method name. - * @param type_1st_arg type of 1st argument - * @param value_1st_arg value of 1st argument - * @param type_2nd_arg type of 2nd argument - * @param value_2nd_arg value of 2nd argument + * @param type_1st_arg Type of 1st argument + * @param value_1st_arg Value of 1st argument + * @param type_2nd_arg Type of 2nd argument + * @param value_2nd_arg Value of 2nd argument * ... etc * @function emit_signal */ diff --git a/docs/05-awesomerc.md.lua b/docs/05-awesomerc.md.lua index 50965a470..d49fee9cb 100644 --- a/docs/05-awesomerc.md.lua +++ b/docs/05-awesomerc.md.lua @@ -324,6 +324,8 @@ rc_lua:close() table.insert(output_script, "-- @script rc.lua") +table.insert(output_script, "-- @usebeautiful beautiful.awesome_icon") +table.insert(output_script, "-- @usebeautiful beautiful.wallpaper") rc_script = assert(io.open(rc_script, "w")) rc_script:write(table.concat(output_script, "\n")) diff --git a/docs/89-NEWS.md b/docs/89-NEWS.md index 18d315cb1..4e19739fe 100644 --- a/docs/89-NEWS.md +++ b/docs/89-NEWS.md @@ -76,6 +76,10 @@ This document was last updated at commit v4.3-197-g9085ed631. old behavior, use `awful.rules.rules = {}; awful.rules.rules = my_new_rules`. * `client:relative_move()` now default `nil` values to zero. The previous behavior made no sense. + * The tasklist and taglist widgets are no longer directly an instance of + it's main layout. Use the `base_layout` property to access the layout. + This allows to replace the layout at runtime. The previous behavior + was undocumented. # Awesome window manager framework version 4.3 changes diff --git a/docs/common/client_theme.ldoc b/docs/common/client_theme.ldoc index 672b41b37..f62085619 100644 --- a/docs/common/client_theme.ldoc +++ b/docs/common/client_theme.ldoc @@ -344,6 +344,21 @@ * @see request::border */ +/** + * The client border width for the fullscreen clients. + * + * This is the fallback if the more stateful version, like + * `beautiful.border_width_fullscreen_urgent` isn't set. + * + * @beautiful beautiful.border_width_fullscreen + * @param integer + * @see request::border + * @see beautiful.border_width_fullscreen_active + * @see beautiful.border_width_fullscreen_normal + * @see beautiful.border_width_fullscreen_urgent + * @see beautiful.border_width_fullscreen_new + */ + /** * The client opacity for the normal clients. * @@ -391,7 +406,6 @@ * * @beautiful beautiful.opacity_floating_normal * @param[opt=1] number - * @see request::border */ /** @@ -424,6 +438,21 @@ * @see request::border */ +/** + * The client opacity for the floating clients. + * + * A number between 0 and 1. This is the fallback if the more stateful + * variables, like `beautiful.opacity_floating_new` are not set. + * + * @beautiful beautiful.opacity_floating + * @param[opt=1] number + * @see request::border + * @see beautiful.opacity_floating_normal + * @see beautiful.opacity_floating_active + * @see beautiful.opacity_floating_urgent + * @see beautiful.opacity_floating_new + */ + /** * The client opacity for the normal maximized clients. * @@ -431,7 +460,6 @@ * * @beautiful beautiful.opacity_maximized_normal * @param[opt=1] number - * @see request::border */ /** @@ -463,6 +491,22 @@ * @param[opt=1] number * @see request::border */ + +/** + * The client opacity for the maximized clients. + * + * A number between 0 and 1. This is the fallback if a more stateful + * variable, like `beautiful.opacity_maximized_urgent`, isn't set. + * + * @beautiful beautiful.opacity_maximized + * @param[opt=1] number + * @see request::border + * @see beautiful.opacity_maximized_normal + * @see beautiful.opacity_maximized_active + * @see beautiful.opacity_maximized_urgent + * @see beautiful.opacity_maximized_new + */ + /** * The client opacity for the normal fullscreen clients. * @@ -470,7 +514,6 @@ * * @beautiful beautiful.opacity_fullscreen_normal * @param[opt=1] number - * @see request::border */ /** @@ -503,4 +546,21 @@ * @see request::border */ +/** + * The client opacity for the fullscreen clients. + * + * A number between 0 and 1. This is the fallback if the variables + * for more stateful versions, like `beautiful.opacity_fullscreen_urgent`, + * are not set. + * + * @beautiful beautiful.opacity_fullscreen + * @param[opt=1] number + * @see request::border + * @see beautiful.opacity_fullscreen_new + * @see beautiful.opacity_fullscreen_urgent + * @see beautiful.opacity_fullscreen_active + * @see beautiful.opacity_fullscreen_normal + */ + + /* diff --git a/docs/common/cobject.ldoc b/docs/common/cobject.ldoc index b8bf3d6f2..f449d4752 100644 --- a/docs/common/cobject.ldoc +++ b/docs/common/cobject.ldoc @@ -1,9 +1,11 @@ */ /** Disconnect from a signal. + * * @tparam string name The name of the signal. * @tparam function func The callback that should be disconnected. * @staticfct disconnect_signal + * @noreturn */ /** Emit a signal. @@ -13,12 +15,14 @@ * function receives the object as first argument and then any extra * arguments that are given to emit_signal(). * @staticfct emit_signal + * @noreturn */ /** Connect to a signal. * @tparam string name The name of the signal. * @tparam function func The callback to call when the signal is emitted. * @staticfct connect_signal + * @noreturn */ /* diff --git a/docs/common/fixed.ldoc b/docs/common/fixed.ldoc index 359fd2ad7..365b161f9 100644 --- a/docs/common/fixed.ldoc +++ b/docs/common/fixed.ldoc @@ -68,6 +68,7 @@ --- Reset the layout. This removes all widgets from the layout. -- @method reset +-- @noreturn -- @emits widget::reset -- @emitstparam widget::reset widget self The layout. -- @interface layout diff --git a/docs/common/notification_rules_index.ldoc b/docs/common/notification_rules_index.ldoc index 35fc30f79..1387c2fdb 100644 --- a/docs/common/notification_rules_index.ldoc +++ b/docs/common/notification_rules_index.ldoc @@ -37,6 +37,7 @@ -- auto\_reset\_timeoutIf the timeout needs to be reset when a property changes -- ignore\_suspend -- clientsA list of clients associated with this notification +-- max\_widthThe maximum popup width -- app\_nameThe application name specified by the notification -- widget\_templateThe widget template used to represent the notification -- diff --git a/docs/common/object.ldoc b/docs/common/object.ldoc index ed21bedac..8eb477e1c 100644 --- a/docs/common/object.ldoc +++ b/docs/common/object.ldoc @@ -3,6 +3,8 @@ -- @tparam string name The name of the signal. -- @tparam function func The callback that should be disconnected. -- @method disconnect_signal +-- @treturn boolean `true` when the function was disconnected or `false` if it +-- wasn't found. -- @baseclass gears.object --- Emit a signal. @@ -12,12 +14,14 @@ -- function receives the object as first argument and then any extra -- arguments that are given to emit_signal(). -- @method emit_signal +-- @noreturn -- @baseclass gears.object --- Connect to a signal. -- @tparam string name The name of the signal. -- @tparam function func The callback to call when the signal is emitted. -- @method connect_signal +-- @noreturn -- @baseclass gears.object --- Connect to a signal weakly. @@ -31,4 +35,5 @@ -- @tparam string name The name of the signal. -- @tparam function func The callback to call when the signal is emitted. -- @method weak_connect_signal +-- @noreturn -- @baseclass gears.object diff --git a/docs/common/signals.ldoc b/docs/common/signals.ldoc index 2c636169b..b8f1a9439 100644 --- a/docs/common/signals.ldoc +++ b/docs/common/signals.ldoc @@ -10,7 +10,8 @@ -- -- @tparam string name The name of the signal -- @tparam function func The function to attach --- @function naughty.connect_signal +-- @noreturn +-- @staticfct naughty.connect_signal -- @usage naughty.connect_signal("added", function(notif) -- -- do something -- end) @@ -18,10 +19,11 @@ --- Emit a module signal. -- @tparam string name The signal name. -- @param ... The signal callback arguments --- @function naughty.emit_signal +-- @noreturn +-- @staticfct naughty.emit_signal --- Disconnect a signal from a source. -- @tparam string name The name of the signal -- @tparam function func The attached function --- @function naughty.disconnect_signal +-- @staticfct naughty.disconnect_signal -- @treturn boolean If the disconnection was successful diff --git a/docs/common/wibox.ldoc b/docs/common/wibox.ldoc index dc46c6ea8..ea9d40f7c 100644 --- a/docs/common/wibox.ldoc +++ b/docs/common/wibox.ldoc @@ -2,7 +2,9 @@ -- -- @baseclass wibox -- @property border_width --- @param integer +-- @tparam[opt=0] integer border_width +-- @propertyunit pixel +-- @negativeallowed false -- @propemits false false --- Border color. @@ -25,21 +27,22 @@ -- -- @baseclass wibox -- @property border_color --- @param string +-- @tparam[opt=beautiful.fg_normal] string border_color -- @propemits false false --- On top of other windows. -- -- @baseclass wibox -- @property ontop --- @param boolean +-- @tparam[opt=false] boolean ontop -- @propemits false false --- The mouse cursor. -- -- @baseclass wibox -- @property cursor --- @param string +-- @tparam[opt=nil] string|nil cursor +-- @propertytype nil Do not change the mouse cursor. -- @see mouse -- @propemits false false @@ -47,21 +50,23 @@ -- -- @baseclass wibox -- @property visible --- @param boolean +-- @tparam[opt=false] boolean visible -- @propemits false false --- The opacity of the wibox, between 0 and 1. -- -- @baseclass wibox -- @property opacity --- @tparam number opacity (between 0 and 1) +-- @tparam[opt=true] number opacity +-- @rangestart 0.0 +-- @rangestop 1.0 -- @propemits false false --- The window type (desktop, normal, dock, ...). -- -- @baseclass wibox -- @property type --- @param string +-- @tparam[opt=""] string type -- @see client.type -- @propemits false false @@ -69,38 +74,49 @@ -- -- @baseclass wibox -- @property x --- @param integer +-- @tparam[opt=0] integer x +-- @propertyunit pixel +-- @negativeallowed true -- @propemits false false --- The y coordinates. -- -- @baseclass wibox -- @property y --- @param integer +-- @tparam[opt=0] integer y +-- @propertyunit pixel +-- @negativeallowed true -- @propemits false false --- The width of the wibox. -- -- @baseclass wibox -- @property width --- @param width +-- @tparam[opt=1] integer width +-- @propertyunit pixel +-- @rangestart 1 +-- @negativeallowed false -- @propemits false false --- The height of the wibox. -- -- @baseclass wibox -- @property height --- @param height +-- @tparam[opt=1] integer height +-- @propertyunit pixel +-- @rangestart 1 +-- @negativeallowed false -- @propemits false false --- The wibox screen. -- -- @baseclass wibox -- @property screen --- @param screen +-- @tparam screen screen +-- @propertydefault The screen which contains `0x0`. -- @propemits true false ---- The wibox's `drawable`. +-- The wibox's `drawable`. -- -- @baseclass wibox -- @property drawable @@ -110,14 +126,15 @@ --- The widget that the `wibox` displays. -- @baseclass wibox -- @property widget --- @param widget +-- @tparam[opt=nil] widget|nil widget -- @propemits true false --- The X window id. -- -- @baseclass wibox -- @property window --- @param string +-- @tparam string window +-- @propertydefault Autogenerated. -- @see client.window -- @propemits false false @@ -129,7 +146,8 @@ -- -- @baseclass wibox -- @property shape_bounding --- @param surface._native +-- @tparam surface._native shape_bounding +-- @propertydefault Fill all pixels. -- @propemits false false -- @see shape @@ -140,7 +158,8 @@ -- -- @baseclass wibox -- @property shape_clip --- @param surface._native +-- @tparam surface._native shape_clip +-- @propertydefault Fill all pixels. -- @propemits false false -- @see shape @@ -152,7 +171,8 @@ -- -- @baseclass wibox -- @property shape_input --- @param surface._native +-- @tparam surface._native shape_input +-- @propertydefault Fill all pixels. -- @propemits false false -- @see input_passthrough @@ -160,7 +180,7 @@ -- -- @baseclass wibox -- @property shape --- @tparam gears.shape shape +-- @tparam[opt=gears.shape.rectangle] shape shape -- @propemits true false -- @see gears.shape @@ -174,7 +194,7 @@ -- -- @baseclass wibox -- @property input_passthrough --- @param[opt=false] boolean +-- @tparam[opt=false] boolean input_passthrough -- @see shape_input -- @propemits true false @@ -182,15 +202,17 @@ -- -- @baseclass wibox -- @property buttons --- @param buttons_table A table of buttons objects, or nothing. +-- @tparam[opt={}] table buttons A table of buttons objects, or nothing. +-- @tablerowtype A list of `awful.button`s. -- @propemits false false --- Get or set wibox geometry. That's the same as accessing or setting the x, -- y, width or height properties of a wibox. -- -- @baseclass wibox --- @param A table with coordinates to modify. --- @return A table with wibox coordinates and geometry. +-- @tparam[opt=nil] table|nil geo A table with coordinates to modify. If +-- nothing is specified, it only returns the current geometry. +-- @treturn table A table with wibox coordinates and geometry. -- @method geometry -- @emits property::geometry When the geometry change. -- @emitstparam property::geometry table geo The geometry table. @@ -205,36 +227,18 @@ -- the side of the screen). -- -- @baseclass wibox --- @param strut A table with new strut, or nothing -- @return The wibox strut in a table. -- @method struts +-- @tparam table struts A table with new strut, or nothing. -- @see client.struts -- @emits property::struts ---- The default background color. --- --- The background color can be transparent. If there is a --- compositing manager such as compton, then it will be --- real transparency and may include blur (provided by the --- compositor). When there is no compositor, it will take --- a picture of the wallpaper and blend it. --- --- @baseclass wibox --- @beautiful beautiful.bg_normal --- @param color --- @see bg - ---- The default foreground (text) color. --- @baseclass wibox --- @beautiful beautiful.fg_normal --- @param color --- @see fg - --- Set a declarative widget hierarchy description. -- See [The declarative layout system](../documentation/03-declarative-layout.md.html) -- @param args An array containing the widgets disposition -- @baseclass wibox -- @method setup +-- @noreturn --- The background of the wibox. -- @@ -246,8 +250,8 @@ -- -- @baseclass wibox -- @property bg --- @tparam c The background to use. This must either be a cairo pattern object, --- nil or a string that gears.color() understands. +-- @tparam[opt=beautiful.bg_normal] color bg The background to use. This +-- must either be a cairo pattern object, nil or a string that gears.color() understands. -- @see gears.color -- @propemits true false -- @usebeautiful beautiful.bg_normal The default (fallback) bg color. @@ -257,18 +261,17 @@ -- If `image` is a function, it will be called with `(context, cr, width, height)` -- as arguments. Any other arguments passed to this method will be appended. -- --- @tparam gears.suface|string|function image A background image or a function. -- @baseclass wibox -- @property bgimage +-- @tparam[opt=nil] image|nil bgimage -- @see gears.surface -- @propemits true false --- The foreground (text) of the wibox. --- @tparam color c The foreground to use. This must either be a cairo pattern object, --- nil or a string that gears.color() understands. +-- -- @baseclass wibox -- @property fg --- @param color +-- @tparam[opt=beautiful.fg_normal] color fg -- @see gears.color -- @propemits true false -- @usebeautiful beautiful.fg_normal The default (fallback) fg color. diff --git a/docs/common/widget.ldoc b/docs/common/widget.ldoc index 36e994d5f..7330059b6 100644 --- a/docs/common/widget.ldoc +++ b/docs/common/widget.ldoc @@ -11,41 +11,58 @@ --- Get or set the children elements. -- @property children --- @tparam table children The children. +-- @tparam table children +-- @tablerowtype A list of `widget`s. -- @baseclass wibox.widget +-- @see all_children --- Get all direct and indirect children widgets. -- This will scan all containers recursively to find widgets -- Warning: This method it prone to stack overflow id the widget, or any of its -- children, contain (directly or indirectly) itself. -- @property all_children --- @tparam table children The children. +-- @tparam table all_children +-- @tablerowtype A list of `widget`s. -- @baseclass wibox.widget +-- @see children --- Set a declarative widget hierarchy description. -- See [The declarative layout system](../documentation/03-declarative-layout.md.html) --- @param args An array containing the widgets disposition +-- @tparam table args An array containing the widgets disposition -- @method setup +-- @noreturn -- @baseclass wibox.widget --- Force a widget height. -- @property forced_height --- @tparam number|nil height The height (`nil` for automatic) +-- @tparam number|nil forced_height +-- @propertytype nil Let the layout decide the height. Usually using the widget +-- native height. +-- @propertytype number Enforce a number of pixels. +-- @negativeallowed false -- @baseclass wibox.widget +-- @see forced_width --- Force a widget width. -- @property forced_width --- @tparam number|nil width The width (`nil` for automatic) +-- @tparam number|nil forced_width +-- @propertytype nil Let the layout decide the width. Usually using the widget +-- native width. +-- @propertytype number Enforce a number of pixels. +-- @negativeallowed false -- @baseclass wibox.widget +-- @see forced_height --- The widget opacity (transparency). -- @property opacity --- @tparam[opt=1] number opacity The opacity (between 0 and 1) +-- @tparam[opt=1] number opacity. +-- @rangestart 0.0 +-- @rangestop 1.0 -- @baseclass wibox.widget --- The widget visibility. -- @property visible --- @param boolean +-- @tparam[opt=true] boolean visible -- @baseclass wibox.widget --- The widget buttons. @@ -53,13 +70,15 @@ -- The table contains a list of `awful.button` objects. -- -- @property buttons --- @param table +-- @tparam[opt={}] table buttons -- @see awful.button +-- @tablerowtype A list of `awful.button`. -- @baseclass wibox.widget --- Add a new `awful.button` to this widget. -- @tparam awful.button button The button to add. -- @method add_button +-- @noreturn -- @baseclass wibox.widget --- Emit a signal and ensure all parent widgets in the hierarchies also @@ -69,6 +88,7 @@ -- @param ... Other arguments -- @baseclass wibox.widget -- @method emit_signal_recursive +-- @noreturn --- When the layout (size) change. -- This signal is emitted when the previous results of `:layout()` and `:fit()` @@ -96,7 +116,7 @@ -- @tparam number button The button number. -- @tparam table mods The modifiers (mod4, mod1 (alt), Control, Shift) -- @tparam table find_widgets_result The entry from the result of --- @{wibox.drawable:find_widgets} for the position that the mouse hit. +-- @{wibox:find_widgets} for the position that the mouse hit. -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing -- the widget. -- @tparam widget find_widgets_result.widget The widget being displayed. @@ -127,7 +147,7 @@ -- @tparam number button The button number. -- @tparam table mods The modifiers (mod4, mod1 (alt), Control, Shift) -- @tparam table find_widgets_result The entry from the result of --- @{wibox.drawable:find_widgets} for the position that the mouse hit. +-- @{wibox:find_widgets} for the position that the mouse hit. -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing -- the widget. -- @tparam widget find_widgets_result.widget The widget being displayed. @@ -152,7 +172,7 @@ -- @signal mouse::enter -- @tparam table self The current object instance itself. -- @tparam table find_widgets_result The entry from the result of --- @{wibox.drawable:find_widgets} for the position that the mouse hit. +-- @{wibox:find_widgets} for the position that the mouse hit. -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing -- the widget. -- @tparam widget find_widgets_result.widget The widget being displayed. @@ -177,7 +197,7 @@ -- @signal mouse::leave -- @tparam table self The current object instance itself. -- @tparam table find_widgets_result The entry from the result of --- @{wibox.drawable:find_widgets} for the position that the mouse hit. +-- @{wibox:find_widgets} for the position that the mouse hit. -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing -- the widget. -- @tparam widget find_widgets_result.widget The widget being displayed. diff --git a/docs/config.ld b/docs/config.ld index 2e51ce765..8ab55afe1 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -1,24 +1,27 @@ local args = ... +local ldoc = nil +-- luacheck: globals new_type -- Configuration file for ldoc -project='awesome' -title='awesome API documentation' -description='API documentation for awesome, a highly configurable X window manager (version @AWESOME_VERSION@).' +project='awesome' -- luacheck: globals project +title='awesome API documentation' -- luacheck: globals title +description='API documentation for awesome, a highly configurable X window manager (version @AWESOME_VERSION@).' -- luacheck: globals description --- More on it: https://github.com/stevedonovan/LDoc/blob/master/doc/doc.md#markdown-support -format='discount' -dir='../doc' +format='discount' -- luacheck: globals format +dir='../doc' -- luacheck: globals dir -- Make the docs prettier -pretty='lua' -style=true -template=true -backtick_references=true -merge=true -use_markdown_titles=true -wrap=true +pretty='lua' -- luacheck: globals pretty +style=true -- luacheck: globals style +template=true -- luacheck: globals template +backtick_references=true -- luacheck: globals backtick_references +merge=true -- luacheck: globals merge +use_markdown_titles=true -- luacheck: globals use_markdown_titles +wrap=true -- luacheck: globals wrap + + -- luacheck: globals full_description full_description = [[ Welcome to the documentation for the Awesome window manager. Below you find an overview of the individual parts which links to the full documentation. @@ -31,23 +34,25 @@ should be useful for you. ### Default configuration components name: -
+
+ +
### Guides
-
- @{07-my-first-awesome.md|Getting started} - @{90-FAQ.md|FAQ} - @{01-readme.md|Read Me} - @{89-NEWS.md|NEWS} -
-
- @{03-declarative-layout.md|The widget system} - @{09-options.md|Startup options} - @{05-awesomerc.md|The default rc.lua} - @{08-client-layout-system.md|Window management} -
+
+ @{07-my-first-awesome.md|Getting started} + @{90-FAQ.md|FAQ} + @{01-readme.md|Read Me} + @{89-NEWS.md|NEWS} +
+
+ @{03-declarative-layout.md|The widget system} + @{09-options.md|Startup options} + @{05-awesomerc.md|The default rc.lua} + @{08-client-layout-system.md|Window management} +
## Major libraries @@ -90,50 +95,903 @@ topics={ '89-NEWS.md', } +-- Rather han copy paste this hundreds of time, unify these special type +-- descriptions. +local type_fallback_description = { + image = { + "string Interpreted as a path to an image file." , + "string A valid SVG content." , + "cairo A cairo image surface: Directly used as-is." , + "librsvg A librsvg handle object: Directly used as-is." , + "nil Unset the image." , + }, + color = { + "string An hexadecimal color code, such as `\"#ff0000\"` for red." , + "string A color name, such as `\"red\"`." , + "table A [gradient table](../theme_related_libraries/gears.color.html)." , + "cairo.pattern Any valid [Cairo pattern](https://cairographics.org/manual/cairo-cairo-pattern-t.html)." , + "cairo.pattern A texture build from an image by [gears.color.create\\_png\\_pattern](../theme_related_libraries/gears.color.html#create_png_pattern)" , + }, + shape = { + "gears.shape Like `gears.shape.circle`", + "function This can be used for custom shapes or to set parameters of existing shapes.", + }, + screen = { + "screen A valid screen object such as retured by `awful.screen.focused()` or `mouse.screen`.", + "integer A screen global id. Avoid using this since they are unsorted.", + "string The `\"primary\"` value is also valid.", + }, + font = { + "string A Pango [font description](../widgets/wibox.widget.textbox.html#font).", + "string An [XFT string](https://wiki.archlinux.org/title/X_Logical_Font_Description), such as `\"-*-dejavu sans mono-medium-r-normal--*-80-*-*-*-*-iso10646-1\"`.", + + }, + template = { + "table A table containing a widget tree definition. WARNING: This is really a table".. + " and **NOT** a widget object. Use the `widget = come.class.here` to define the ".. + " topmost class rather than construct an instance." + }, + placement = { + "function A custom callback to generate *and set* the geometry.", + "placement Any of the `awful.placement` function or constructs." + } +} + +-- Document the "common" function prototypes. Some common types, such as +-- the client layouts, the shapes and placements are just glorified functions. +local callback_fallback_description = { + shape = { + {"functionparam", "cairo.context", "cr", "A [Cairo context](https://cairographics.org/manual/cairo-cairo-t.html)"}, + {"functionparam", "number", "width", "The area width."}, + {"functionparam", "number", "height", "The area height."}, + }, + placement = { + {"functionreturn", "table", "A table with an `x`, `y`, `width` and `height` keys."}, + {"functionparam", "object", "obj", "Any object with a `geometry` property or method."}, + {"functionparam", "table", "args", "The `placement` arguments. See `awful.placement` for a complete list."}, + }, +} + +-- Try to use a single name for common types. For example, mixing `color` and +-- `gears.color` (which is *not* a type) is confusing. It also allows the +-- type description to be auto-generated from `type_fallback_description`. +local type_name_linting = { + ["gears.color"] = "color", + ["gears.shape"] = "shape", + ["wibox.widget"] = "widget", + ["gears.surface"] = "image", + ["surface"] = "image", + ["awful.placement"] = "placement", + ["double"] = "number", + ["float"] = "number", + ["bool"] = "boolean", +} + +local metadata_tags = { + "propertyunit", "rangestart", "rangestop", "negativeallowed", +} + +local databases, named_tags, item_id, is_init = {}, {}, 1, false +local all_theme_vars, delayed_collect = nil, {} + +local function collect_item_common(tab, mod, item) + tab[item.name] = tab[item.name] or {} + + local var = tab[item.name] + var[mod.name] = var[mod.name] or {} + var[mod.name][#var[mod.name] + 1] = item +end + +--- Add another custom tag **value** to an existing item. +-- @tparam string tag_data The raw/unparsed string for the +-- tag. It will be parsed like any other tags. +local function add_custom_tag_common(item, tag_name, meta_tag, tag_data) + item.tags = item.tags or {} + + item.tags[tag_name] = item.tags[tag_name] or {} + + item.tags[tag_name][#item.tags[tag_name] + 1] = tag_data + + if meta_tag.collect_callback then + delayed_collect[#delayed_collect+1] = {item, item.module, tag_name, tag_data} + end +end + +-- Wrap the global `new_type` to allow us to extend what types can do, the +-- same is done below for custom tags. +local function create_type(args) + new_type(args.name, args.title, args.project_level, args.subfield_title) + + databases[args.name] = databases[args.name] or {} + databases[args.name].collect = args.collect_callback + databases[args.name].finish = args.finish_callback + + return args +end + +-- Add the @usebeautiful from the optional/default value. +local function auto_add_usebeautiful(item) + local vars, var_names = {}, {} + + -- Datamine the default values to autogenerate the @usebeautiful. + for parm in ldoc.modules.iter(item.params) do + for p in ldoc.modules.iter(item:subparam(parm)) do + local def = item:default_of_param(p) + + if def and def ~= true then + for var in def:gmatch("beautiful[.][a-z_]+") do + if not var_names[var] then + vars[#vars+1] = var + end + var_names[var] = true + end + end + end + end + + for _, var in ipairs(vars) do + named_tags.usebeautiful:add_to_item(item, var) + end +end + +-- Handle both manually specified callback prototypes and common ones. +local function parse_properties_function_metadata(item, types) + local raw_input = item.tags["functionnoparam"] and {} or item.tags["functionparam"] + local raw_output = item.tags["functionnoreturn"] and {} or item.tags["functionreturn"] + local fallback, input, output = true, {}, {} + + for _, arg in ipairs(raw_input or {}) do + input[#input+1] = item.parsed_tags["functionparam"][arg] + fallback = false + end + + for _, ret in ipairs(raw_output or {}) do + output[#output+1] = item.parsed_tags["functionreturn"][ret] + fallback = false + end + + local has_in = #input > 0 or item.tags["functionnoparam"] ~= nil + local has_out = #output > 0 or item.tags["functionnoreturn"] ~= nil + + if fallback then + for type in pairs(types) do + if callback_fallback_description[type] then + for _, row in ipairs(callback_fallback_description[type]) do + local dest = row[1] == "functionparam" and input or output + + dest[#dest+1] = { + description = row[#row], + type = row[2] and {value = row[2]}, + name = row[3] and {value = row[3]}, + } + end + + -- Assume the fallback is correct. + has_out, has_in = true, true + break + end + end + end + + return { + input = input, + output = output, + has_input = has_in, + has_output = has_out, + } +end + -- The first stereotype are the constructors. -new_type("constructorfct", "Constructors", false, "Parameters") -new_type("constructorfct2", "ldoc_skip", false, "Parameters") +create_type { + name = "constructorfct", + title = "Constructors", + project_level = false, + subfield_title = "Parameters", + collect_callback = auto_add_usebeautiful, +} + +-- Some constructors like `awful.key` have both a named parameter +-- syntax and a multiple function parameter syntax. +create_type { + name = "constructorfct2", + title = "ldoc_skip", + project_level = false, + subfield_title = "Parameters", +} + -- Hack to get the functions on top of the signals and properties -new_type("function", "Functions", false, "Parameters") +create_type { + name = "function", + title = "Functions", + project_level = false, + subfield_title = "Parameters", +} + -- For "classes", use an explicit type for static functions. This allows -- @function and its implicit cousin to be banned in the CI. -new_type("staticfct", "Static module functions", false, "Parameters") +create_type { + name = "staticfct", + title = "Static module functions", + project_level = false, + subfield_title = "Parameters", +} + -- Documentation for objects properties -new_type("property", "Object properties", false, "Type constraints") +create_type { + name = "property", + title = "Object properties", + project_level = false, + subfield_title = "Type constraints", + collect_callback = auto_add_usebeautiful, + finish_callback = function(item) + -- All properties need to have a type. Otherwise they don't render + -- properly. Also, because typed properties are kind of the point of + -- switching to ldoc in the first place. + if (not item.params) or not item.params[1] then + print( + "WARNING: The ".. item.name .." property from "..item.module.name.." is missing it's type." + ) + return + end + + local _, sublist = item:subparam(item.params[1]) + local type = item:type_of_param(item.params[1]) + + -- Force people to use @tparam because it is easier to lint and allows + -- multiple types. + if (not type) or type == "" then + print( + "WARNING: Property ".. item.name .." from "..item.module.name.." either ".. + " doesn't have a type or uses @param instead of @tparam. @tparam is required".. + " because it allows multi-type and better default value handling." + ) + end + + if type_name_linting[type] then + print( + "WARNING: Property ".. item.name .." from "..item.module.name.. + " type is `"..type.."`, please use `"..type_name_linting[type].."`." + ) + end + + -- One of the repeated problem we have is the first word of the + -- description being removed because it is used as the property name. + -- This "rule" might be stupid, but it prevents it from accidentally + -- happening again. + if item.params[1] ~= item.name:match("[.]?("..item.params[1]..")$") then + print( + "WARNING: Property ".. item.name .." from "..item.module.name.." @tparam name".. + " doesn't match the property name. For linting purpose, please fix this." + ) + end + + local def = item:default_of_param(item.params[1]) + + -- Check the default value for obvious mistakes. + if def then + -- Detect the blatant missing quote marks for string. This is important + -- to differentiate variables from string literals. + if type == "string" and def:sub(1,1) ~= '"' and def:sub(-1) ~= '"' and not def:find(".") then + print( + "WARNING: Property ".. item.name .." from "..item.module.name.. + " is a string, but the default value is not quoted." + ) + end + + -- If the default value is `nil`, then the property must be nullable. + if def == "nil" and not type:find("nil") then + print( + "WARNING: Property ".. item.name .." from "..item.module.name.. + " default value is `nil`, but the type doesn't allow it" + ) + end + + if type == "boolean" and (not (def == "true" or def == "false")) and (not def:find(".")) then + print( + "WARNING: Property ".. item.name .." from "..item.module.name.. + " is a boolean, but is neither `true`, `false` or an alias" + ) + end + + item:add_metadata("Default value", ("%s"):format(def)) + else + -- Properties should have a default value. If they don't or if the + -- default depends on the context, then `opt=nil` should be used to + -- mute this warning. + local auto_opt = nil + + -- Extract the default value from other metadata. + if item.tags["propbeautiful"] and item.tags["propbeautiful"][1] then + auto_opt = "beautiful."..(item.module.name.."_"..item.name):gsub("[.]", "_") + elseif item.tags["usebeautiful"] and item.tags["usebeautiful"][1] then + auto_opt = item.tags["usebeautiful"][1]:match("[^ ]+") + end + + -- This adds a default value. It works for LDoc 1.4.5, but is a + -- private API and might break in the future. + if item.tags["propertydefault"] and item.tags["propertydefault"][1] then + item:add_metadata( + "Default value", + ldoc.markup(item.tags["propertydefault"][1]) + ) + elseif auto_opt then + local mods = item.modifiers[item.parameter] + + if mods then + mods[item.params[1]].opt = auto_opt + end + + item:add_metadata("Default value", ("%s"):format(auto_opt)) + elseif not sublist then + -- The default could not be determined automatically, it requires + -- an explicit `opt=`. + print( + "WARNING: Property", item.name .." from "..item.module.name, + "doesn't have a default value. Add `[opt=value]` to the @tparam" + ) + end + end + + local prop_types, prop_type_names, fallback_callback = {}, {}, false + + -- Type validation. + do + -- Handle the case where a property has multiple types. + local metatypes, table_args = {}, {} + local prop_has_nil, prop_has_obj = false, false + + -- Make a copy of the table to avoid recursion. + for _, t in ipairs(item.tags["propertytype"] or {}) do + metatypes[#metatypes+1] = t + end + + for t in item:type_of_param(item.params[1]):gmatch('[^|]+') do + if type_name_linting[t] then + print( + "WARNING: Property", item.name .." from "..item.module.name.. + " type is '"..t.."'. Please use `"..type_name_linting[t].."'" + ) + end + + if not prop_type_names[t] then + prop_types[#prop_types+1] = t + end + prop_type_names[t] = true + fallback_callback = fallback_callback or callback_fallback_description[t] + prop_has_nil = prop_has_nil or t == "nil" + prop_has_obj = prop_has_obj or (t:find('.') and not t:sub(1,5) == "gears") + end + + if item.tags["propbeautiful"] + and item.tags["propbeautiful"][1] + and not prop_type_names["nil"] then + print( + "WARNING: Property", item.name .." from "..item.module.name.. + " uses `@propbeautiful`, yet, doesn't have `nil` as a type." + ) + end + + if #item.params == 0 then + print( + "WARNING: Property", item.name .." from "..item.module.name.. + " is missing it's `@tparam` section. Please add it." + ) + elseif #item.params > 1 then + for i=2, #item.params do + local splitted = {} + + for part in item.params[i]:gmatch("[^.]+") do + splitted[#splitted+1] = part + end + + if #splitted == 1 then + print( + "WARNING: Property", item.name .." from "..item.module.name.. + " has a `@tparam` named \""..item.params[i].."\". The only".. + " valid name is \"..item.name\"" + ) + else + print( + "WARNING: Property", item.name .." from "..item.module.name.. + " has a `@tparam` named \""..item.params[i].."\". This is".. + " not valid. It should be `@tparam[opt=...] "..item.name.. + ". " + ) + end + end + end + + -- Some properties are table with fixed keys. + local param,sublist = item:subparam(item.params[1]) + if sublist then + for _, sub_param in pairs(param) do + local splitted = {} + + for part in sub_param:gmatch("[^.]+") do + splitted[#splitted+1] = part + end + + -- The first part should match the property name. If it doesn't, + -- then it's unclear what it is. + if splitted[1] ~= item.name then + print( + "WARNING: Property", item.name .." from "..item.module.name.. + " has additional @tparams with unclear meaning. Please".. + " use `@tparam[opt=...] type property_name.subparam Desc...`" + ) + else + local rebuilt_name = "" + + for i=2, #splitted do + rebuilt_name = rebuilt_name .. ((#rebuilt_name > 0) and "." or "") .. splitted[i] + end + + table_args[#table_args+1] = { + name = rebuilt_name, + default = item:default_of_param(sub_param), + type = item:type_of_param(sub_param), + description = item.params.map[sub_param], + } + end + end + end + + if prop_has_obj and not prop_has_nil then + print( + "WARNING: Property", item.name .." from "..item.module.name.. + " has an object type, however it doesn't define the behavior".. + " or `nil` (or lack `@nonnullable`)" + ) + end + + local type_map = {} + + for _, typeinfo in ipairs(metatypes) do + local parsed = item.parsed_tags["propertytype"][typeinfo] + type_map[parsed.typename.value] = type_map[parsed.typename.value] or {} + type_map[parsed.typename.value][#type_map[parsed.typename.value]+1] = parsed + end + + local warnings = {} + + -- Check if every possible type is described. + for _, t in ipairs(prop_types) do + if not type_map[t] then + -- Auto add description for common types. + if type_fallback_description[t] then + for _, entry in ipairs(type_fallback_description[t]) do + metatypes[#metatypes+1] = entry + named_tags.propertytype:add_to_item(item, entry) + type_map[t] = type_map[t] or {} + type_map[t][#type_map[t]+1] = entry + end + elseif #prop_types > 1 then + local warn = "WARNING: Property", item.name .." from "..item.module.name.. + " has the undescribed object type \""..t.."\", please add".. + " one (or more) `@propertytype "..t.." ` tag." + warnings[t] = warnings[t] or {} + warnings[t][#warnings[t]+1] = warn + end + end + end + + -- Autofill the meaning of `nil` when there is a fallback `beautiful` + -- variable. + if prop_type_names["nil"] + and (not type_map["nil"]) + and item.tags["propbeautiful"] + and item.tags["propbeautiful"][1] then + local modname = item.module.name:gmatch("[^.]+$")() + local fallback = "beautiful."..(modname.."_"..item.name):gsub("[.]", "_") + local entry = "nil Fallback to the current value of `"..fallback.."`." + named_tags.propertytype:add_to_item(item, entry) + metatypes[#metatypes+1] = entry + + warnings["nil"] = nil + end + + for _, warn in ipairs(warnings) do + print(warn) + end + + local mt_by_type = {} + + -- Add the metatype section + if #metatypes > 0 then + local mt = item:add_metadata("Type description") + + for _, typeinfo in ipairs(metatypes) do + local parsed = item.parsed_tags["propertytype"][typeinfo] + local tmt = mt:add_metadata( + ""..parsed.typename.value.."", + ldoc.markup(parsed.description) + ) + mt_by_type[parsed.typename.value] = mt_by_type[parsed.typename.value] or {} + mt_by_type[parsed.typename.value][#mt_by_type[parsed.typename.value]+1] = tmt + end + end + + if #table_args > 0 then + local mt = mt_by_type["table"] and mt_by_type["table"][1] or item:add_metadata("Table keys") + for _, key in ipairs(table_args) do + mt:add_metadata( + key.name, + ldoc.markup(key.description), + key.type + ) + end + end + + -- Add the function callback parameters section. + if prop_type_names["function"] or fallback_callback then + local fp = (mt_by_type["function"] and mt_by_type["function"][1] or item):add_metadata("Function prototype") + + local prototype = parse_properties_function_metadata(item, prop_type_names) + + if not prototype.has_input then + print( + "WARNING: Property ".. item.name .." from "..item.module.name.. + " needs either `@functionparam` or `@functionnoparam` if there".. + " is none." + ) + elseif #prototype.input == 0 then + fp:add_metadata("Parameters:", "The function has no parameters") + else + local fparams = fp:add_metadata("Parameters") + for _, parsed in ipairs(prototype.input) do + if (not parsed.name) or (not parsed.type) then + print( + "WARNING: Property ".. item.name .." from "..item.module.name.. + " has a `@functionparam` improperly formatted. The format is ".. + "` [description]`." + ) + else + fparams:add_metadata( + parsed.name.value, + ldoc.markup(parsed.description), + parsed.type.value + ) + end + end + end + + args = item.tags["functionnoreturn"] and {} or item.tags["functionreturn"] + + if not prototype.has_output then + print( + "WARNING: Property ".. item.name .." from "..item.module.name.. + " needs either `@functionreturn` or `@functionnoreturn` if there".. + " is none." + ) + elseif #prototype.output == 0 then + fp:add_metadata("Return", "The function returns nothing.") + elseif #prototype.output == 1 then + fp:add_metadata("Return", ldoc.markup(prototype.output[1].description), prototype.output[1].type.value) + else + local md = fp:add_metadata("Return") + for _, parsed in ipairs(prototype.output) do + md:add_metadata( + "", + ldoc.markup(parsed.description), + parsed.type.value + ) + end + end + end + + -- Handle the case where the table is a list. + if #prop_types == 1 and prop_types[1] == "table" + and #(item.tags["tablerowtype"] or {}) == 0 + and #table_args == 0 then + print( + "WARNING: Property ".. item.name .." from "..item.module.name.. + " needs either `@tablerowtype` or additional `@tparam`." + ) + elseif #(item.tags["tablerowtype"] or {}) > 0 then + local mt = item:add_metadata("Table content", ldoc.markup(item.tags["tablerowtype"][1])) + + for _, key in ipairs(item.tags["tablerowkey"] or {}) do + local parsed = item.parsed_tags["tablerowkey"][key] + local type, val, desc = parsed.type.value, parsed.name.value, parsed.description + mt:add_metadata(""..val.."", ldoc.markup(desc), type) + end + end + end + + -- Allow the template to be shorter by using a for-loop. + local has_start, has_allow_negative = false, false + for _, mt in ipairs(metadata_tags) do + local tag_desc = named_tags[mt] + + if item.tags[mt] and item.tags[mt][1] then + has_start = has_start or mt == "rangestart" + has_allow_negative = has_allow_negative or mt == "negativeallowed" + local title = tag_desc.title or mt + item:add_metadata(title, ldoc.markup(item.tags[mt][1])) + end + end + + if (prop_type_names["number"] or prop_type_names["integer"]) and not (has_start or has_allow_negative) then + print( + "WARNING: Property", item.name .." from "..item.module.name.. + " has numeric type, please add either `@rangestart` or `@negativeallowed false`." + ) + end + + local tdesc = item.params.map[item.params[1]] and item.params.map[item.params[1]] or "" + + -- Auto add the description for "simple" boolean. + if #prop_types == 1 and prop_types[1] == "boolean" and tdesc == "" then + tdesc = "`true` or `false`." + end + + -- Handle custom type description and string "enum". + if #(item.tags["propertyvalue"] or {}) > 0 or tdesc ~= "" then + + local mt = item:add_metadata("Valid values", ldoc.markup(tdesc)) + + local values, found_default = item.tags["propertyvalue"] or {}, false + + for _, enum_val in ipairs(values) do + local parsed = item.parsed_tags["propertyvalue"][enum_val] + local val, desc = parsed.value.value, parsed.description + + if val:sub(1,1) ~= '"' or val:sub(#val,#val) ~= '"' then + print( + "WARNING: Value `"..val.."` from property ".. item.name + .." from module "..item.module.name.. "should be a quoted string." + ) + end + + found_default = found_default or val == def + + mt:add_metadata(""..val.."", ldoc.markup(desc)) + end + + if def and #values > 0 and def:sub(1,9) ~= "beautiful" and not found_default then + print( + "WARNING: Property ".. item.name .." from "..item.module.name.. + " has some `@propertyvalue`, but the default value is not among them." + ) + end + end + + -- @return is not displayed for properties, something important + -- might have been written there, so it's better to block it + if item.tags["return"] or item.tags["treturn"] then + print( + "WARNING: Property ".. item.name .." from "..item.module.name.. + " has a `@return`, it is not rendered. Remove it." + ) + end + end +} + -- Documentation for objects deprecated properties -new_type("deprecatedproperty", "Deprecated object properties", false, "Type constraints") +create_type { + name = "deprecatedproperty", + title = "Deprecated object properties", + project_level = false, + subfield_title = "Type constraints", +} + +-- Documentation for objects deprecated methods +create_type { + name = "deprecatedmethod", + title = "Deprecated object methods", + project_level = false, + subfield_title = "Parameters", +} + -- Use a custom type for the methods to bypass the faulty ldoc built-in detection. -- (yes, the space after Methods *is* on purpose to avoid clashing with ldoc -- internal "methods" concept) -new_type("method", "Object methods ", false, "Parameters") --- New type for signals -new_type("signal", "Signals", false, "Arguments") +create_type { + name = "method", + title = "Object methods ", + project_level = false, + subfield_title = "Parameters", +} + +-- New type for signals. +local all_signals +all_signals = create_type { + name = "signal", + title = "Signals", + project_level = false, + subfield_title = "Arguments", + collection = {}, + collect_callback = function(item, mod) + collect_item_common(all_signals.collection, mod, item) + end, +} + -- Deprecated signals. -new_type("deprecatedsignal", "Deprecated signals", false, "Arguments") +create_type { + name = "deprecatedsignal", + title = "Deprecated signals", + project_level = false, + subfield_title = "Arguments", +} + -- New type for signals connections -new_type("signalhandler", "Request handlers", false, "Arguments") +create_type { + name = "signalhandler", + title = "Request handlers", + project_level = false, + subfield_title = "Arguments", +} + -- Allow objects to define a set of beautiful properties affecting them -new_type("beautiful", "Theme variables", false, "Type constraints") +all_theme_vars = create_type { + name = "beautiful", + title = "Theme variables", + project_level = false, + subfield_title = "Type constraints", + collection = {}, + collect_callback = function(item, mod) + if item.name:sub(1,4) ~= "beau" then + -- This would be a bug. + if item.name:match("[.]") then + print("WANRING: A beautiful variable is called `", item.name, "`. This name is invalid.") + end + + -- This happens because the `ldoc` messes with the name. All variables + if item.module.name == "beautiful" then + item.name = "beautiful." .. item.name + else + print( + "WARNING: All theme variable need a `beautiful.` prefix. It appears", + item.name, + " lacks it" + ) + end + end + + collect_item_common(all_theme_vars.collection, mod, item) + + -- Those are global variables, there can be only one per name. + if all_theme_vars.collection[item.name] then + local mod = pairs(all_theme_vars.collection[item.name])(all_theme_vars.collection[item.name]) + + if mod ~= item.module.name then + print("ERROR: "..item.name, "from", item.module.name, "is already defined in module ", mod) + end + end + end, + finish_callback = function(item) + if not item.tags["beautiful_used_by"] then + -- Every variable should be consumed by something. Better "park" some + -- variable in the constructors than leave them disconnected from the + -- global model. + print("WARNING: ", item.name, "is not used by anything, add @usebeautiful or @propbeautiful") + else + local prop, mn = nil, item.module.name:match("[.]?([^.]+)$") + -- If there is a property with the corresponding name and it doesn't + -- mention the `beautiful` variable, that's nearly always a bug. + for kind, items in item.module.kinds() do + if kind == "Object properties" then + for k in items do + for k2,v2 in k do + if item.name:match("[.]"..mn.."_"..k2.name.."$") then + prop = k2 + break + end + if prop then break end + end + break + end + end + end + + if prop then + local mention = false + + if prop.tags.propbeautiful then mention = true end + + if (not mention) and prop:default_of_param(prop.params[1]) == item.name then + mention = true + end + + for _, v in ipairs((not mention) and prop.tags.usebeautiful or {}) do + local parsed = prop.parsed_tags.usebeautiful[v] + if parsed.name.value == item.name then + mention = true + break + end + end + + if not mention then + print( + "WARNING: `"..item.name.. "` from `"..item.module.name.."` ".. + "seems to match a property called `"..prop.name.."`. However, ".. + "there is no mention of this `beautiful` ".. + "variable in its documentation. Please add `@propbeautiful` or ".. + "`[opt="..item.module.name.."]" + ) + end + end + end + end +} + -- Put deprecated methods in their own section -new_type("deprecated", "Deprecated functions", false, "Parameters") +create_type { + name = "deprecated", + title = "Deprecated functions", + project_level = false, + subfield_title = "Parameters", +} + -- For the legacy stateless layout related functions -new_type("legacylayout", "Layout related functions", false, "Parameters") +create_type { + name = "legacylayout", + title = "Layout related functions", + project_level = false, + subfield_title = "Parameters", +} + -- Have a category for the client layouts -new_type("clientlayout", "Client layouts", false, "Parameters") +create_type { + name = "clientlayout", + title = "Client layouts", + project_level = false, + subfield_title = "Parameters", +} + -- Source functions for the taglist/tasklist/layoutlist -new_type("sourcefunction", "List source functions", false) +create_type { + name = "sourcefunction", + title = "List source functions", + project_level = false, +} + -- Document some callback prototypes -new_type("callback", "Callback functions prototype", false, "Parameters") +create_type { + name = "callback", + title = "Callback functions prototype", + project_level = false, + subfield_title = "Parameters", +} + -- gears.matcher / awful.rules sources -new_type("rulesources", "Rule sources", false, "Parameters") +create_type { + name = "rulesources", + title = "Rule sources", + project_level = false, + subfield_title = "Parameters", +} + -- gears.matcher / awful.rules rule components -new_type("rulecomponent", "Rule components", false, "Type") +create_type { + name = "rulecomponent", + title = "Rule components", + project_level = false, + subfield_title = "Type", +} + -- Filter functions for the taglist/tasklist/layoutlist -new_type("filterfunction", "List filters", false) +create_type { + name = "filterfunction", + title = "List filters", + project_level = false, +} + -- Extra client properties available only in awful.rules/spawn constructs -new_type("clientruleproperty", "Extra properties available in the rules", false, "Type") +create_type { + name = "clientruleproperty", + title = "Extra properties available in the rules", + project_level = false, + subfield_title = "Type", +} + -- Extra *matching* properties for rules. -new_type("matchingproperty", "Extra matching properties used in rules", false, "Type") +create_type { + name = "matchingproperty", + title = "Extra matching properties used in rules", + project_level = false, + subfield_title = "Type", +} -- Simulate the default "params" parser format, except the optional "[]" section -- needs a space. @@ -220,16 +1078,18 @@ local function default_format_callback(self, params, _, md) end -- Generate a format function. -local function default_format(self, callback) +local function default_format(self, callback, name) return function(raw, item, md) - return (callback or default_format_callback)( - self, parse_custom_tags(raw, self.params or {}), item, md - ) + local p = name and item.parsed_tags and item.parsed_tags[name] and item.parsed_tags[name][raw] + + if not p then + p = parse_custom_tags(raw, self.params or {}) + end + + return (callback or default_format_callback)(self, p, item, md) end end -local named_tags, item_id = {}, 1 - -- Add a new @something which can be used in any types. -- @tparam table args -- @tparam string args.name The name. @@ -246,9 +1106,28 @@ add_custom_tag = function(args) custom_tags = custom_tags or {} + databases[name] = databases[name] or {} + databases[name].collect = args.collect_callback + local f = args.format - args.format = default_format(args, f) + args.format = default_format(args, f, name) + + function args:add_to_item(item, tag_value) + add_custom_tag_common(item, name, args, tag_value) + + local parsed = parse_custom_tags(tag_value, args.params or {}) + + if parsed then + item.parsed_tags = item.parsed_tags or {} + item.parsed_tags[name] = item.parsed_tags[name] or {} + item.parsed_tags[name][tag_value] = parsed + end + + item.has_show_more = item.has_show_more or (not args.hidden) + + return parsed + end custom_tags[#custom_tags+1] = args named_tags[name] = args @@ -284,7 +1163,17 @@ add_custom_tag { { name = "name" } - } + }, + collect_callback = function(item, mod, tag, value) + local parsed = parse_custom_tags(value, named_tags.emits.params) + + all_signals.collection[parsed.name.value] = all_signals.collection[parsed.name.value] or {} + + local var = all_signals.collection[parsed.name.value] + + var[mod.name] = var[mod.name] or {} + var[mod.name][#var[mod.name] + 1] = item + end } -- Avoid repetitive boilerplate code for property signals. @@ -345,7 +1234,25 @@ add_custom_tag { name = "name", markdown = true, } - } + }, + collect_callback = function(item, mod, tag, value) + local params = parse_custom_tags(value, named_tags.usebeautiful.params) + + if all_theme_vars.collection[params.name.value] then + local sig_mods = all_theme_vars.collection[params.name.value] + local _, themed_items = pairs(sig_mods)(sig_mods) + local themed_item = themed_items[1] + + named_tags.beautiful_used_by:add_to_item(themed_item, item.name.." "..item.summary) + + -- Auto fill the description if its empty. + if (not params.description) or params.description == "" then + params.description = themed_item.summary + end + else + print("WARNING: Could not find theme variable", params.name.value) + end + end } -- For all properties which have a standard `@beautiful` variable for them @@ -376,6 +1283,18 @@ add_custom_tag { end return ret + end, + finish_callback = function(item, raw, params, modules) + local modname = item.module.name:gmatch("[^.]+$")() + local name = "beautiful."..(modname.."_"..item.name):gsub("[.]", "_") + + if all_theme_vars.collection[name] then + local sig_mods = all_theme_vars.collection[name] + local _, themed_items = pairs(sig_mods)(sig_mods) + local themed_item = themed_items[1] + + named_tags.beautiful_used_by:add_to_item(themed_item, item.name.." "..item.summary) + end end } @@ -472,7 +1391,6 @@ add_custom_tag { add_custom_tag { name = "hidden", hidden = true, - auto_subtags = false } -- Mark the item as readonly. @@ -483,6 +1401,212 @@ add_custom_tag { hidden = true, auto_subtags = false } + +-- Forces every method and function to have either `@treturn` or `@noreturn`. +-- This avoids the many case where the return value was forgotten. +add_custom_tag { + name = "noreturn", + hidden = true, + auto_subtags = false +} + +-- When a property cannot be `nil` or a function/method cannot return `nil`. +add_custom_tag { + name = "nonnullable", + hidden = true, + auto_subtags = false +} + +-- When properties are integers, the value usually has a meaning, like the PID, +-- apoint or a pixel. +add_custom_tag { + name = "propertyunit", + title = "Unit", + hidden = true, + auto_subtags = false +} + +-- Some string properties are de-facto enums. Only a small set of value is valid. +-- This tag provides a consistent rendering for such properties. +add_custom_tag { + name = "propertyvalue", + hidden = true, + auto_subtags = false, + params = { + { name = "value" }, + }, +} + +-- Some defaults are not values. They are either algorithms, chains od fallbacks +-- or somehow inherited. `ldoc` `opt` can only parse single "words", thus a new +-- tag is needed for textual description of the default value. +add_custom_tag { + name = "propertydefault", + hidden = true, + auto_subtags = false, +} + +-- Some properties have multiple possible types. Some also might support multiple +-- "logical type" for the same datatype. For example `string` can be a path or +-- some CSS/SVG or an integer have different meaning for positive vs. +-- negative/zeroed. +-- +-- This tag helps document those nuances. +add_custom_tag { + name = "propertytype", + hidden = true, + auto_subtags = false, + params = { + { name = "typename" }, + }, +} + +-- Some values, mostly bytes, have a minimum and maximum value. +add_custom_tag { + name = "rangestart", + title = "Minimum value", + hidden = true, + auto_subtags = false +} +add_custom_tag { + name = "rangestop", + title = "Maximum value", + hidden = true, + auto_subtags = false +} +add_custom_tag { + name = "negativeallowed", + title = "Negative allowed", + hidden = true, + auto_subtags = false, + params = { + { name = "allowed" }, + }, +} + +-- A lot of properties have the `table` value. Lua tables can be anything from +-- "struct" to list to objects. For lists, then the type of the row needs to +-- be specified. +add_custom_tag { + name = "tablerowtype", + title = "Table content", + hidden = true, + auto_subtags = false, +} +add_custom_tag { + name = "tablerowkey", + title = "Row keys", + hidden = true, + auto_subtags = false, + params = { + { name = "type" }, + { name = "name" }, + }, +} + +-- When a `@property` takes a `function` value, then the function arguments +-- much be provided. If there is none, then `@functionnoparam` must be explicitly +-- specified. Same for the return value(s). +add_custom_tag { + name = "functionnoparam", + hidden = true, + auto_subtags = false, +} +add_custom_tag { + name = "functionparam", + hidden = true, + auto_subtags = false, + params = { + { name = "type" }, + { name = "name" }, + }, +} +add_custom_tag { + name = "functionnoreturn", + hidden = true, + auto_subtags = false, +} +add_custom_tag { + name = "functionreturn", + hidden = true, + auto_subtags = false, + params = { + { name = "type" }, + }, +} + +add_custom_tag { + name = "signalhandler", + hidden = false, + title = "Request handler", + auto_subtags = false, + params = { + { name = "source" }, + }, + format = function(self, params, item, md) + return ldoc.markup("`"..params.source.value.."`") .. " " .. params.description + end +} + +add_custom_tag { + name = "beautiful_used_by", + hidden = false, + title = "Used by", + auto_subtags = false, + params = { + { name = "source" }, + }, + format = function(self, params, item, md) + return ldoc.markup("`"..params.source.value.."`") .. " " .. params.description + end +} + +-- Auto generate some code for replacing request handlers. +add_custom_tag { + name = "sourcesignal", + title = "Source signal", + hidden = false, + params = { + { name = "class" }, + { name = "signal" }, + }, + format = function(self, params, item, md) + return ldoc.markup("`"..params.signal.value.."` from the `"..params.class.value.."` module.").. + " This code allows to disconnect this handler and implement your own:" + end, + finish_callback = function(item, raw, params, modules) + if all_signals.collection[params.signal.value] then + local sig_mods = all_signals.collection[params.signal.value] + local _, signal_items = pairs(sig_mods)(sig_mods) + local signal_item = signal_items[1] + + -- Auto generate some code. + local code = "-- Disconnect the original handler.\n" + code = code .. signal_item.module.name .. ".disconnect_signal('".. params.signal.value .."', "..item.name..")\n\n" + code = code .. "-- Connect a custom handler.\n" + code = code .. signal_item.module.name .. ".connect_signal('".. params.signal.value .."', function(" + + + if signal_item.type == "signal" then + for idx, parm in ipairs(signal_item.params) do + code = code .. parm .. (idx == #signal_item.params and "" or ", ") + end + + code = code .. ")\n -- code here\nend)" + + named_tags.signalhandler:add_to_item(signal_item, item.name.." "..item.summary) + end + + item.tag_extra_data = item.tag_extra_data or {} + item.tag_extra_data["sourcesignal"] = item.tag_extra_data["sourcesignal"] or {} + item.tag_extra_data["sourcesignal"][raw] = item.tag_extra_data["sourcesignal"][raw] or {} + item.tag_extra_data["sourcesignal"][raw].usage = ldoc.prettify(code) + + item.has_show_more = true + end + end +} + -- More fitting section names kind_names={topic='Documentation', module='Libraries', script='Sample files'} @@ -510,7 +1634,6 @@ file = { '../selection.c', '../spawn.c', '../xkb.c', - '../common/luaobject.c', '../objects/client.c', '../objects/drawable.c', '../objects/screen.c', @@ -569,6 +1692,7 @@ file = { '../lib/wibox/layout/rotate.lua', '../lib/wibox/layout/scroll.lua', '../lib/wibox/widget/background.lua', + '../lib/wibox/drawable.lua', } } @@ -581,26 +1705,65 @@ local function wrap_modname(str, item) end local named_args = { - [ "(args)" ] = true, - [ "([args])" ] = true, - [ "([args=nil])" ] = true, - [ "([args={}])" ] = true + [ "(args)" ] = true, + [ "([args])" ] = true, + [ "([args=nil])" ] = true, + [ "([args={}])" ] = true, + [ '(args)' ] = true, +} + +-- Some values come from external sources, we can't enforce the naming conventions +-- on them. So far, they are all keyboard related. +local param_name_whitelist = { + Mod2 = true, Lock = true, Control = true, Mod1 = true, ISO_Level3_Shift = true, + Mod4 = true, Insert = true, Delete = true, Next = true, Prior = true, Left = true, + Up = true, Right = true, Down = true, KP_End = true, KP_Down = true, + KP_Next = true, KP_Left = true, KP_Begin = true, KP_Right = true, + KP_Home = true, KP_Up = true, KP_Prior = true, KP_Insert = true, KP_Delete = true, + KP_Divide = true, KP_Multiply = true, KP_Subtract = true, KP_Add = true, + KP_Enter = true, Escape = true, Tab = true, space = true, Return = true, + XF86MonBrightnessUp = true, XF86MonBrightnessDown = true, + XF86AudioRaiseVolume = true, XF86AudioLowerVolume = true, XF86AudioMute = true, + XF86AudioPlay = true, XF86AudioPrev = true, XF86AudioNext = true, XF86AudioStop = true, } -- Sections which are hidden by default, but visible when clicked. local summarize = { - emits = {index = 1, title = "signal" , count = true }, - propemits = {index = 2, title = "signal" , count = true }, - usebeautiful = {index = 3, title = "theme variable" , count = true }, - propbeautiful = {index = 4, title = "theme variable" , count = true }, - request = {index = 5, title = "permission" , count = true }, - classsignal = {index = 6, title = "Class level only", count = false}, + is_deprecated = {index = 1, title = "deprecated" , count = false}, + emits = {index = 2, title = "signal" , count = true }, + propemits = {index = 3, title = "signal" , count = true }, + usebeautiful = {index = 4, title = "theme variable" , count = true }, + propbeautiful = {index = 5, title = "theme variable" , count = true }, + request = {index = 6, title = "permission" , count = true }, + classsignal = {index = 7, title = "Class level only", count = false}, + readonly = {index = 8, title = "read only" , count = false}, } local delimiter_for_tag = { usebeautiful = { "table class='widget_list' border=1", "table", "tr", "tr", {"Theme variable", "Usage"}}, propbeautiful = { "table class='widget_list' border=1", "table", "tr", "tr", {"Theme variable", "Usage"}}, request = { "table class='widget_list' border=1", "table", "tr", "tr", {"Class", "Permission", "Context", "Default", "Description"}}, + sourcesignal = { "div", "div", "span", "span" } +} + +--- If the title is short and descritive, there is no point to bloat it. +-- +-- That test is mostly to catch empty or lazy description (such as the module +-- name and nothing else). +local short_title_whitelist = { + [ "rc.lua" ] = true, + [ "naughty.action" ] = true, + [ "naughty.layout.box" ] = true, + [ "naughty.widget.title" ] = true, + [ "theme.lua" ] = true, + [ "wibox.container.margin" ] = true, + [ "wibox.container.arcchart"] = true, + [ "wibox.widget.checkbox" ] = true, + [ "wibox.widget.imagebox" ] = true, + [ "wibox.widget.separator" ] = true, + [ "wibox.widget.progressbar"] = true, + [ "naughty" ] = true, + [ "xproperties" ] = true, } -- Use the first word of the subtag content to map it to its tag. @@ -630,7 +1793,7 @@ local function generate_summary(item) end end - local ret, has_show_more = {}, false + local ret, has_show_more = {}, item.has_show_more or false for k, v in ipairs(tgs) do if v.count > 0 then @@ -643,9 +1806,6 @@ local function generate_summary(item) has_show_more = v.showcount or has_show_more end end - if item.tags.readonly then - ret[#ret+1] = {title = "read only"} - end item.extra_summary = #ret > 0 and ret or nil item.has_show_more = has_show_more @@ -664,7 +1824,7 @@ local function init_custom_types(item) -- Give each item an unique identifier so the JavaScript can locate them. item.uid, item_id = item_id, item_id + 1 - item.delims, item.auto_usage, item.auto_params = {}, {}, {} + item.delims, item.auto_usage, item.auto_params, item.metadata = {}, {}, {}, {} local to_rm = {} @@ -716,22 +1876,42 @@ local function init_custom_types(item) -- Allow the template to fetch the right sub-tags. function item.get_auto_params(tag, value) + local extra = (item.tag_extra_data and item.tag_extra_data[tag] and item.tag_extra_data[tag][value]) or {} + -- Makes auto-generated subtags easier to implement. if item.auto_params[tag.."tparam_override"] then - return item.auto_params[tag.."tparam_override"], named_tags[tag.."tparam"] + return item.auto_params[tag.."tparam_override"], named_tags[tag.."tparam"], extra end - if not item.auto_params[tag.."tparam"] then return nil, nil end + local parsed = nil - local parsed = parse_custom_tags(value, named_tags[tag].params) + if item.parsed_tags and item.parsed_tags[tag] and item.parsed_tags[tag][value] then + parsed = item.parsed_tags[tag][value] + end + + if not item.auto_params[tag.."tparam"] then return nil, nil, extra end if parsed.name and item.auto_params[tag.."tparam"][parsed.name.value] then - return item.auto_params[tag.."tparam"][parsed.name.value], named_tags[tag.."tparam"] + return item.auto_params[tag.."tparam"][parsed.name.value], named_tags[tag.."tparam"], extra end - return nil, nil + return nil, nil, extra end + -- Recursive way to annotate property-like objects. + local amt + amt = function(self, title, description, datatype) + self.metadata[#self.metadata+1] = { + title = title, + datatype = datatype, + description = description, + metadata = {}, + add_metadata = amt + } + return self.metadata[#self.metadata] + end + item.add_metadata = amt + item.is_init = true end @@ -741,6 +1921,7 @@ local function wrap_args(item) -- Display named args with `{}` and ordered args with `()` if named_args[item.args] then + item.is_named_call = true return "{[args]}" end @@ -776,8 +1957,7 @@ local function pipe_to_or(s) end -- Parse the magic parameters to type in something the template eats. -local function sanitize_type(item, ldoc) - +local function sanitize_type(item) for parm in ldoc.modules.iter(item.params) do local t = item:type_of_param(parm) @@ -806,9 +1986,37 @@ local function sanitize_type(item, ldoc) item.display_type = "N/A" end +-- Detect error prone markdown formatting. +local function detect_markdown_footguns(string) + for line in string:gmatch("[^\n]*") do + if line:sub(1,4) ~= " " then + local is_tick = false + + -- Detect unquoted code with 2 underscores. They will render as italic, + -- which is definitively not wanted. Add "`" to fix. + for part in line:gmatch("[^`]*") do + if not is_tick then + local count = 0 + + for under in part:gmatch("[^\\]_") do + count = count + 1 + end + + if count > 1 then + return false + end + end + + is_tick = not is_tick + end + end + end + + return true +end -- Add parentheses when there is alternative return types. -local function generate_return_tuple(item, group, ldoc) +local function generate_return_tuple(item, group) local tuple = {} for r in group:iter() do @@ -839,7 +2047,7 @@ local function generate_return_tuple(item, group, ldoc) end -- Create a return type string. -local function sanitize_return_type(item, ldoc) +local function sanitize_return_type(item) local groups = item.retgroups @@ -861,11 +2069,184 @@ local function sanitize_return_type(item, ldoc) end item.display_type = item.display_type .. "" + elseif not item.tags["noreturn"] then + print( + "WARNING:", item.name, "from", item.module.name, + "doesn't have a return value or @noreturn" + ) end item.compact_signature = true end +-- Traverse the entire doc and reverse-map the links between our custom +-- tags and the content it is pointing toward. From that, we add some +-- "consumers"/"providers" tables to each (relevant) item. +local function global_init(_ldoc) + ldoc = _ldoc + + if is_init then return end + is_init = true + + local module_by_name = {} + + -- First pass, gather the providers. + for _, mod in ipairs(ldoc.modules) do + module_by_name[mod.name] = mod + + if mod.type ~= "topic" and ((not mod.summary) or mod.summary == "" or mod.summary:lower():sub(1,8) == "awesome") then + print("WARNING: Each module needs a good summary as its first line", mod.name, "doesn't") + end + + local sum_count = 0 + + for line in (mod.summary or ""):gmatch("[^\n]*") do + sum_count = sum_count + 1 + end + + if sum_count > 1 and #mod.summary > 120 then + print("WARNING:", mod.name, "summary has to be only 1 line.") + end + + if mod.summary and #mod.summary < 30 and not short_title_whitelist[mod.name] then + print("WARNING:", mod.name, "summary is too short.") + end + + for tag, values in pairs(mod.tags) do + for _, value in ipairs(values.gmatch and {values} or values) do + -- Collect instances of some types. + if databases[tag] and databases[tag].collect then + delayed_collect[#delayed_collect+1] = {mod, mod, tag, value} + end + end + end + + for kind, items in mod.kinds() do + for item in items() do + -- Decorate the item with our customizations. + init_custom_types(item) + + -- print(item.description) + + if item.summary and not detect_markdown_footguns(item.summary) then + print( + "WARNING: "..item.name.." from "..item.module.name.." seems to have".. + " ambiguous markdown in its summary, probably underscores. Please either".. + " use '`' or HTML." + ) + end + + -- Collect instances of some types. + if databases[item.type] and databases[item.type].collect then + databases[item.type].collect(item, mod) + end + + for tag, values in pairs(item.tags) do + for _, value in ipairs(values.gmatch and {values} or values) do + -- Collect instances of some types. + if databases[tag] and databases[tag].collect then + delayed_collect[#delayed_collect+1] = {item, mod, tag, value} + end + end + end + + -- Lint the parameters too. + for parm in ldoc.modules.iter(item.params) do + local first = parm:match("^[ ]*(.)") + + -- If the first letter of a parameter is capital, the type is probably missing. + -- That's what happen if you rename @param to @tparam without actually adding the type. + if first and first ~= first:lower() and parm:upper() ~= parm and not param_name_whitelist[parm] then + print( + "ERROR: Parameter "..parm.." from ".. item.name .. " ".. item.module.name.. + " starts with a capital letter. This is forbidden." + ) + end + + for p in ldoc.modules.iter(item:subparam(parm)) do + local desc = item.params.map[p] + + if not detect_markdown_footguns(desc) then + print( + "WARNING: Always use '`' to encapsulate code in the parameters." .. + p .. " from " .. item.name .. " " .. item.module.name .. " contains " .. + "some ambiguous markup. If this is a false positive, use HTML." + ) + end + + -- It *sometime* works, but is at risk if being interpreted as code by markdown. + if desc:match("^ [ ]+") then + print( + "WARNING: ", item.name, "from", item.module.name, "has a parameter description ".. + "with leading spaces. This will not render correctly", "'"..desc.."'" + ) + end + + first = desc:match("^[ ]*([a-z])") + + if first and first ~= first:upper() then + print("WARNING: Sentences starts with a capital letter. Please fix", item.module.name, item.name) + end + + --TODO convert @propbeautiful to @usebeautiful and lint them + --TODO check the module summary. + end + end + end + end + end + + -- Second pass, collect the custom tags. This is delayed because + -- the tags depend on the items. Not all items have been processed if + -- this was called during the first pass. Also, collect callbacks can + -- themselves create more delayed_collect entries recursively. + for _, to_collect in ipairs(delayed_collect) do + databases[to_collect[3]].collect(to_collect[1], to_collect[2], to_collect[3], to_collect[4]) + end + + -- Third pass, parse every custom tags and fill the consumers tables. + for _, mod in ipairs(ldoc.modules) do + for kind, items in mod.kinds() do + for item in items() do + for tag_name, values in pairs(item.tags) do + for _, tag in ipairs(values.gmatch and {values} or values) do + local parsed = named_tags[tag_name] + and named_tags[tag_name].params + and parse_custom_tags(tag, named_tags[tag_name].params) + + -- Allow the tags to, ie, auto-generate some extra content. + if named_tags[tag_name] and named_tags[tag_name].finish_callback then + named_tags[tag_name].finish_callback(item, tag, parsed, module_by_name) + end + + -- Save the parsed content to be used in get_auto_params. + if parsed then + item.parsed_tags = item.parsed_tags or {} + item.parsed_tags[tag_name] = item.parsed_tags[tag_name] or {} + item.parsed_tags[tag_name][tag] = parsed + end + end + end + + -- Mostly for linting. + if databases[item.type] and databases[item.type].finish then + databases[item.type].finish(item, mod, module_by_name) + end + end + end + end +end + +-- Work around the fact that tag/awful.tag client/awful.client pages +-- are merged. +local function compare_module_name(input, module) + for _, mod in ipairs { module, "awful."..module } do + if input:sub(1, #mod) == mod then return true end + end + + return false +end + local no_prefix = { property = true, signal = true, @@ -889,6 +2270,8 @@ local add_mod = { staticfct = true, deprecated = true, field = true, + signalhandler = true, + table = true, } -- Add the arguments. @@ -896,6 +2279,9 @@ local add_args = { constructorfct = true, constructorfct2 = true, staticfct = true, + signalhandler = true, + callback = true, + deprecated = true, } -- Add a type column to the summary and type field in the description. @@ -911,31 +2297,59 @@ local display_type = { -- Add the `-> ret_type` annotation. local display_return_type = { - method = true, - staticfct = true, + method = true, + deprecatedmethod = true, + staticfct = true, } -- Show return values. local show_return = { - ["function"] = true, - constructorfct = true, - constructorfct2 = true, - legacylayout = true, - staticfct = true, - method = true, - deprecated = true, + ["function"] = true, + constructorfct = true, + constructorfct2 = true, + legacylayout = true, + staticfct = true, + method = true, + deprecated = true, + deprecatedmethod = true, } -- The different type of deprecation. local is_deprecated = { deprecated = true, deprecatedproperty = true, + deprecatedmethod = true, deprecatedsignal = true, } custom_display_name_handler = function(item, default_handler) + item.global_init = global_init + + if is_deprecated[item.type] then + item.tags.is_deprecated = {true} + end + init_custom_types(item) + -- Do not use the default handler. It encodes the parameters using + -- the optchain convention. Not everybody is confortable with this. + -- It is also unreadable. + item.args = "" + + if item.params then + item.args = "(" + for key, line in ipairs(item.params) do + local name, comment = item:split_param(line) + local def = item:default_of_param(line) + if def then + item.args = item.args .. '' .. name .. "" .. (key < #item.params and ", " or "") + else + item.args = item.args .. name .. (key < #item.params and ", " or "") + end + end + item.args = item.args .. ")" + end + local ret = default_handler(item) -- Edit the input so the template is notified. @@ -968,18 +2382,16 @@ custom_display_name_handler = function(item, default_handler) -- have "just" `bar`. Given we use constructors from metatables, we have no -- choice but to use the full function name. It also makes copy/paste easier. if add_mod[item.type] then + local is_field = item.type == "field" or item.type == "tfield" + if (not ret:find(".", 1, true)) and (not ret:find(":", 1, true)) then ret = item.module.name .. "." .. ret - elseif item.type == "field" and ret:sub(1, #item.module.name) ~= item.module.name then + elseif is_field and not compare_module_name(ret, item.module.name) then ret = item.module.name .. "." .. ret end end - if is_deprecated[item.type] then - return ret .. " [deprecated]" - end - - if item.type == "method" then + if item.type:match("method") then ret = render_methods(item) end diff --git a/docs/images/client_geo.svg b/docs/images/client_geo.svg index 34c970a2b..88da6ae53 100644 --- a/docs/images/client_geo.svg +++ b/docs/images/client_geo.svg @@ -67,11 +67,11 @@ inkscape:connector-curvature="0" id="path6072" d="m 58.889889,0.75 402.388891,0 0,238.5 -402.388891,0 z" - style="fill:none;stroke:#000000;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:10, 4;stroke-dashoffset:1;stroke-opacity:0.26666703" + class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:10, 4;stroke-dashoffset:1;stroke-opacity:0.26666703" sodipodi:nodetypes="ccccc" /> Top titlebar Left titlebar Right titlebar Shape clip outline @@ -353,27 +353,27 @@ inkscape:connector-curvature="0" id="path6355" d="m 445.91815,214.03874 3.33912,0 0,8.64241 -3.33912,0" - style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80000001px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:0.80000001px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:0.80000001px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:0.50971645;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> + class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:0.87379962;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> + class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> + class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> + class=".svg_fill" style="opacity:1;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" /> + class=".svg_fill" style="opacity:1;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" /> + class=".svg_fill" style="opacity:1;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" /> + class=".svg_fill" style="opacity:1;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" /> + class=".svg_fill" style="opacity:1;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" /> diff --git a/docs/images/progressbar.svg b/docs/images/progressbar.svg index ade0797ef..ac8ef2d0f 100644 --- a/docs/images/progressbar.svg +++ b/docs/images/progressbar.svg @@ -76,115 +76,115 @@ style="fill:#a800ff;fill-opacity:0.49019602;fill-rule:nonzero;stroke:#ffff00;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-opacity:1" /> margins.left paddings.right margins.bottom paddings.left color background_color border_color bar_border_width paddings.top margins.right border_width + class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:10, 4;stroke-dashoffset:1;stroke-opacity:0.26666703" /> + class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:10, 4;stroke-dashoffset:1;stroke-opacity:0.2" /> @@ -90,21 +90,21 @@ inkscape:connector-curvature="0" id="path7597" d="m 427.60318,224.3777 10.21376,0 0,15.32064 -10.14227,0" - style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.20000005;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.20000005;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" sodipodi:nodetypes="cccc" /> + class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.36000001;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> Gaps + class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.20000005;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> + class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.20000005;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> Screen area + + + + + + + + + + + + + image/svg+xml + + + + + + + + + diff --git a/docs/ldoc.css b/docs/ldoc.css index 9857bcfb2..9576dc0f9 100644 --- a/docs/ldoc.css +++ b/docs/ldoc.css @@ -25,22 +25,43 @@ hr { tt { font-family: monospace; } + span.parameter { font-family: monospace; font-weight: bold; color: rgb(99, 115, 131); } -span.parameter:after { - content:":"; + +span.optional_param { + font-style: italic; + color: rgb(143, 166, 230); } -span.types:before { - content:"("; + +.types { + white-space: pre; } -span.types:after { - content:")"; + +td span.types { + flex-flow: nowrap; + display: inline-flex; + width: 100%; } + +td span.inline_types { + color: #a4c7ff; + flex-flow: nowrap; + width: 100%; +} + .type { - font-weight: bold; font-style:italic + flex-basis: auto; + font-weight: bold; + font-style:italic; + pointer-events: none; + text-decoration: none; + color: #008fee; + text-align: center; + flex-grow: 1; } p.name { @@ -51,7 +72,12 @@ kbd, p code, ol code, ul code, -dd > code { +dd > code, +td code, +span.default_value, +.see_also_description code, +.important_box code +{ background-color: #eaedf587; padding-left: 3px; padding-right: 3px; @@ -64,15 +90,39 @@ dd > code { margin-right: 5px; } +#main { + display: flex; +} + #navigation { - float: left; + --sidebar-width: 14em; + --sidebar-toggle-width: 24px; + background-color: white; border-right: 1px solid #d3dbec; border-bottom: 1px solid #d3dbec; - width: 14em; - vertical-align: top; + width: var(--sidebar-width); overflow: visible; + + margin-left: calc(-1 * var(--sidebar-width) + var(--sidebar-toggle-width)); + transition: margin-left 0.2s ease-out; +} + +#navigation.open { + margin-left: 0; +} + +@media (hover: hover) { + #navigation:hover { + margin-left: 0; + } +} + +@media all and (min-width: 768px) { + #navigation { + margin-left: 0; + } } #navigation br { @@ -99,6 +149,10 @@ dd > code { margin-bottom: 0px; } +#content { + overflow: hidden; +} + #content h1 { background-color: #2c3e67; color: white; @@ -133,6 +187,7 @@ dd > code { margin-left: 15px; margin-bottom: 5px; border-bottom: solid 1px #bcd; + font-weight: normal; } #content h4 { @@ -141,11 +196,11 @@ dd > code { border-bottom: solid 1px #bcd; } -#content pre { +#content pre, .auto_genenerated_code { margin: 15px; } -pre { +pre, .auto_genenerated_code { background-color: rgb(50, 55, 68); color: white; border-radius: 3px; @@ -185,10 +240,6 @@ table.index td { margin: 0px 3px 0px -1em; } -#content { - margin-left: 14em; -} - #content p { padding-left: 15px; padding-right: 15px; @@ -209,6 +260,56 @@ table th, table td { padding: 2px; } +.important_box { + padding-left: 40px; + min-height: 32px; + max-width: 640px; + vertical-align: middle; + background-image: url("images/warning_icon.svg"); + background-size: 32px 32px; + background-repeat: no-repeat; + background-position: left center; + margin-top: 15px; + margin-bottom: 5px; + margin-left: 10px; +} + +.see_also, .see_also td, .see_also th { + border-style: hidden !important; + padding-left: 5pt; + padding-right: 5pt; +} + +.see_also tr td:nth-of-type(1) { + display: list-item; + list-style-type: disc; + list-style-position: inside; +} + +.see_also tr:hover { + background-color: #f7fbff; +} + +.see_also tr th { + color: rgb(168, 168, 168); + padding-top: 15px; + padding-bottom: 4px; + font-weight: normal; + text-decoration: none; + font-style:italic; + font-size: 85%; +} + +.see_also_description { + max-width: 640px; +} + +.see_also_sublist td:nth-of-type(1) { + margin-left: 10px; + padding-left: 15px; + border-left: 1px solid rgb(200, 200, 200) !important; +} + .widget_list td { padding-top: 10px; padding-bottom: 10px; @@ -280,12 +381,17 @@ table th, table td { #about { padding: 15px; - padding-left: 16em; background-color: white; border-top: 1px solid #d3dbec; border-bottom: 1px solid #d3dbec; } +@media all and (min-width: 768px) { + #about { + padding-left: calc(14em + 15px); + } +} + table.module_list, table.function_list { border-width: 1px; border-style: solid; @@ -301,26 +407,22 @@ table.module_list td, table.function_list td { padding-bottom: 5px; } table.module_list td.name, table.function_list td.name { - background-color: white; min-width: 200px; border-left-width: 0px; border-right-width: 0px; } table.module_list td.summary, table.function_list td.summary { - background-color: white; width: 100%; border-left-width: 0px; border-right: none; } table.function_list td.shortname { - background-color: white; border-left-width: 0px; border-right-width: 0px; } table.function_list td.inheritance { - background-color: white; border-right-width: 0px; border-left-width: 0px; color: #a4c7ff; @@ -337,8 +439,15 @@ span.inheritance { font-weight: normal; } +span.not_applicable { + color: rgb(200, 200, 200); + font-style:italic; + font-size: 85%; + text-align: center; + display: block; +} + .summarytype { - background-color: white; color: #a4c7ff; font-size: 85%; border-left: none; @@ -346,14 +455,18 @@ span.inheritance { text-align: right; } -span.chips--readonly { +span.chips { border: 1px solid #9db9f3; border-radius: 25px; - padding: 1px 3px; - font-size: 70%; + padding-left: 5pt; + padding-right: 5pt; + padding-top: 1pt; + padding-bottom: 1pt; + font-size: 85%; color: #9db9f3; background-color: #FFF; margin-left: 10px; + vertical-align: middle; } table.function_list .function_args /*.function_modname*/ { @@ -382,7 +495,6 @@ table.function_list .function_named_args { } table.function_list td.baseclass { - background-color: white; color: #a4c7ff; min-width: 200px; border-left: none; @@ -417,7 +529,7 @@ dl.function dd { margin-bottom: 15px; } -#content dl.function dd h3 { +#content dl.function dd h3, .see_also i { margin-top: 0px; margin-left: 0px; padding-left: 0px; @@ -538,6 +650,8 @@ pre .url { color: #272fc2; text-decoration: underline; } /* Inheritance diagram */ .inheritance .inheritance__level { list-style: none; + padding-top: 0px; + padding-left: 30px; } .inheritance .inheritance__level--root { @@ -563,3 +677,81 @@ pre .url { color: #272fc2; text-decoration: underline; } .extra-header__section { flex-grow: 1; } + +.summary_row { + background-color: white; +} + +.summary_row:hover { + background-color: #f7fbff; +} + +/* CSS for beautiful.fg_normal */ +.svg_stroke, .svg_fill { + color: black; +} + +#content > .components-relationship { + margin-left: 15px; + margin-right: 15px; +} + +.components-relationship--diagrams { + display: flex; + flex-direction: column; +} + +.components-relationship--diagram { + flex-grow: 1; + flex-basis: 100%; +} + +.components-relationship--diagram > table { + margin: 0; + width: 100%; +} + +.components-relationship--diagram + .components-relationship--diagram { + margin-top: 15px; +} + +/* on wide displays, put both diagrams next to each other */ +@media all and (min-width: 1100px) { + .components-relationship--diagrams { + flex-direction: row; + } + + .components-relationship--diagram { + flex-grow: 1; + flex-basis: 50%; + } + + .components-relationship--diagram + .components-relationship--diagram { + margin-top: 0; + margin-left: 15px; + } +} + +.components-relationship--legend { + color: #00000044; + margin-top: 15px; +} + +.img-object { + max-width: 100%; + padding: 5px; +} + +.copy-link { + font-size: 9px; + padding: 2px; + border-radius: 9px; + vertical-align: middle; + text-decoration: none; +} +.copy-link--success { + background-color: green; +} +.copy-link--failure { + background-color: red; +} diff --git a/docs/ldoc.ltp b/docs/ldoc.ltp index 2c518e306..e7cf8b4ec 100644 --- a/docs/ldoc.ltp +++ b/docs/ldoc.ltp @@ -24,25 +24,27 @@
- -
- -
-
-
- -
# local no_spaces = ldoc.no_spaces # local use_li = ldoc.use_li # local display_name = ldoc.display_name # local iter = ldoc.modules.iter -# local function un_cmake(s) return s:gsub(";", ";"):gsub(""", '"') end +# local function un_cmake(s) return s:gsub(";", ";"):gsub(""", '"'):gsub('&#34', '"') end # local function M(txt,item) return ldoc.markup(txt and un_cmake(txt) or nil,item,ldoc.plain) end # local nowrap = ldoc.wrap and '' or 'nowrap' # local html_space = function(s) return s:gsub(" ", "%%20") end # local no_underscores = function(s) return s:gsub("_", " ") end +# local get_item = function(mod, name) for item in iter(mod.items) do if item.name == name then return item end end; return name == "" and mod or nil end + +# -- Poke a hole to allow config.ld code to have a global initialization. +# for m in iter(ldoc.modules) do +# if #m.items > 0 then +# display_name(m.items[1]) +# m.items[1].global_init(ldoc) +# break +# end +# end # --------- modules hierarchy ------------- # local hierarchy = {} @@ -74,7 +76,7 @@ # local myitems = {} # for item in items() do # myitems[#myitems + 1] = item -# end +# end # all_module_kinds[#all_module_kinds + 1] = { kind = kind, items = myitems } # end # local filtered_kinds = { "Constructors", "Static module functions", @@ -121,7 +123,6 @@ + + + diff --git a/lib/awful/button.lua b/lib/awful/button.lua index cf3bf1c7d..b9d506359 100644 --- a/lib/awful/button.lua +++ b/lib/awful/button.lua @@ -70,41 +70,51 @@ button.names = { -- Please note that Awesome ignores the status of "Lock" and "Mod2" (Num Lock). -- -- @property modifiers +-- @tparam[opt={}] table modifiers +-- @tablerowtype A list of modifier names in no specific order. --- The mouse button identifier. -- -- ![Mouse buttons](../images/mouse.svg) -- -- @property button --- @param integer +-- @tparam integer button +-- @propertydefault Set in the constructor. +-- @propertyunit X11 mouse button codes. +-- @negativeallowed false --- The button description. -- -- @property description --- @param string +-- @tparam[opt=""] string description --- The button name. -- -- @property name --- @param string +-- @tparam[opt=""] string name --- The button group. -- -- @property group --- @param string +-- @tparam[opt=""] string group --- The callback when this button is pressed. -- -- @property on_press --- @param function +-- @tparam[opt=nil] function|nil on_press +-- @functionnoparam +-- @functionnoreturn --- The callback when this button is released. -- -- @property on_release --- @param function +-- @tparam[opt=nil] function|nil on_release +-- @functionnoparam +-- @functionnoreturn --- Execute this mousebinding. --- @method :trigger +-- @method trigger +-- @noreturn function button:set_button(b) for _, v in ipairs(self) do @@ -237,7 +247,7 @@ local obj_mt = { -- -- @constructorfct awful.button -- @tparam table mod A list of modifier keys. Valid modifiers are: --- `Any`, `Mod1`, Mod2`, `Mod3`, `Mod4`, `Mod5`, `Shift`, `Lock` and `Control`. +-- `Any`, `Mod1`, `Mod2`, `Mod3`, `Mod4`, `Mod5`, `Shift`, `Lock` and `Control`. -- This argument is (**mandatory**). -- @tparam number button The mouse button (it is recommended to use the -- `awful.button.names` constants. @@ -250,7 +260,7 @@ local obj_mt = { -- @constructorfct2 awful.button -- @tparam table args -- @tparam table args.modifiers A list of modifier keys. Valid modifiers are: --- `Any`, `Mod1`, Mod2`, `Mod3`, `Mod4`, `Mod5`, `Shift`, `Lock` and `Control`. +-- `Any`, `Mod1`, `Mod2`, `Mod3`, `Mod4`, `Mod5`, `Shift`, `Lock` and `Control`. -- This argument is (**mandatory**). -- @tparam number args.button The mouse button (it is recommended to use the -- `awful.button.names` constants. diff --git a/lib/awful/client.lua b/lib/awful/client.lua index 3d2336a7c..b1d5478b5 100644 --- a/lib/awful/client.lua +++ b/lib/awful/client.lua @@ -157,7 +157,7 @@ client.focus = require("awful.client.focus") -- -- @deprecated awful.client.jumpto -- @see client.jump_to --- @tparam client c the client to jump to +-- @tparam client c The client to jump to -- @tparam bool|function merge If true then merge tags (select the client's -- first tag additionally) when the client is not visible. -- If it is a function, it will be called with the client and its first @@ -174,10 +174,11 @@ end -- @DOC_sequences_client_jump_to1_EXAMPLE@ -- -- @method jump_to --- @tparam bool|function merge If true then merge tags (select the client's +-- @tparam[opt] bool|function merge If true then merge tags (select the client's -- first tag additionally) when the client is not visible. -- If it is a function, it will be called with the client and its first -- tag as arguments. +-- @noreturn -- @request client activate client.jumpto granted When a client is activated -- because `c:jump_to()` is called. -- @see activate @@ -212,7 +213,7 @@ end -- -- @deprecated awful.client.visible -- @see screen.clients --- @tparam[opt] integer|screen s The screen, or nil for all screens. +-- @tparam[opt] nil|integer|screen s The screen, or nil for all screens. -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom) -- @treturn table A table with all visible clients. function client.visible(s, stacked) @@ -230,7 +231,7 @@ end -- -- @deprecated awful.client.tiled -- @see screen.tiled_clients --- @tparam integer|screen s The screen, or nil for all screens. +-- @tparam nil|integer|screen s The screen, or nil for all screens. -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom) -- @treturn table A table with all visible and tiled clients. function client.tiled(s, stacked) @@ -253,8 +254,8 @@ end -- If no client is passed, the focused client will be used. -- -- @staticfct awful.client.next --- @tparam int i The index. Use 1 to get the next, -1 to get the previous. --- @tparam[opt] client sel The client. +-- @tparam int i The index. Use `1` to get the next, `-1` to get the previous. +-- @tparam[opt=client.focus] client sel The client. -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom) -- @treturn[opt] client|nil A client, or nil if no client is available. -- @see client.get @@ -296,8 +297,9 @@ end -- -- @staticfct awful.client.swap.bydirection -- @tparam string dir The direction, can be either "up", "down", "left" or "right". --- @tparam[opt=focused] client c The client. +-- @tparam[opt="focused"] client c The client. -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom) +-- @noreturn -- @see swap -- @see swapped -- @see awful.client.swap.global_bydirection @@ -328,7 +330,8 @@ end -- -- @staticfct awful.client.swap.global_bydirection -- @tparam string dir The direction, can be either "up", "down", "left" or "right". --- @tparam[opt] client sel The client. +-- @tparam[opt=client.focus] client sel The client. +-- @noreturn -- @request client activate client.swap.global_bydirection granted When a client -- could be activated because `awful.client.swap.global_bydirection` was called. -- @see swap @@ -370,13 +373,15 @@ end -- @DOC_sequences_client_swap_byidx1_EXAMPLE@ -- -- @staticfct awful.client.swap.byidx --- @tparam integer i The index. --- @tparam[opt] client c The client, otherwise focused one is used. +-- @tparam integer i The index. Use `1` to get the next, `-1` to get the previous. +-- @tparam[opt=client.focus] client c The client, otherwise focused one is used. +-- @noreturn -- @see swap -- @see swapped -- @see awful.client.swap.bydirection -- @see awful.client.swap.global_bydirection -- @see awful.client.cycle +-- @see awful.client.next function client.swap.byidx(i, c) local sel = c or capi.client.focus local target = client.next(i, sel) @@ -393,9 +398,10 @@ end -- @DOC_sequences_client_cycle1_EXAMPLE@ -- -- @staticfct awful.client.cycle --- @tparam boolean clockwise True to cycle clients clockwise. --- @tparam[opt] screen s The screen where to cycle clients. +-- @tparam[opt=false] boolean clockwise True to cycle clients clockwise. +-- @tparam[opt=awful.screen.focused()] screen s The screen where to cycle clients. -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom) +-- @noreturn -- @see swap -- @see swapped -- @see awful.client.swap.bydirection @@ -423,6 +429,7 @@ end -- -- @method append_keybinding -- @tparam awful.key key The key. +-- @noreturn -- @see remove_keybinding -- @see append_mousebinding -- @see remove_mousebinding @@ -430,17 +437,20 @@ end --- Remove a keybinding. -- -- @method remove_keybinding +-- @noreturn -- @tparam awful.key key The key. --- Append a mousebinding. -- -- @method append_mousebinding -- @tparam awful.button button The button. +-- @noreturn --- Remove a mousebinding. -- -- @method remove_mousebinding -- @tparam awful.button button The button. +-- @noreturn --- Get the master window. -- @@ -475,6 +485,7 @@ end -- @DOC_sequences_client_to_primary_EXAMPLE@ -- -- @method to_primary_section +-- @noreturn -- @see swap -- @see to_secondary_section function client.object:to_primary_section() @@ -493,6 +504,7 @@ end -- @DOC_sequences_client_to_secondary_EXAMPLE@ -- -- @method to_secondary_section +-- @noreturn -- @see swap -- @see to_primary_section @@ -510,7 +522,7 @@ end -- @tparam integer y The relative y coordinate. -- @tparam integer w The relative width. -- @tparam integer h The relative height. --- @tparam[opt] client c The client, otherwise focused one is used. +-- @tparam[opt=client.focus] client c The client, otherwise focused one is used. -- @see client.relative_move function client.moveresize(x, y, w, h, c) gdebug.deprecate("Use c:relative_move(x, y, w, h) instead of awful.client.moveresize", {deprecated_in=4}) @@ -522,11 +534,17 @@ end -- @DOC_sequences_client_relative_move1_EXAMPLE@ -- -- @method relative_move +-- @tparam[opt=0] integer x The relative x coordinate. +-- @tparam[opt=0] integer y The relative y coordinate. +-- @tparam[opt=0] integer w The relative width. +-- @tparam[opt=0] integer h The relative height. +-- @noreturn -- @see geometry --- @tparam[opt=0] number x The relative x coordinate. --- @tparam[opt=0] number y The relative y coordinate. --- @tparam[opt=0] number w The relative width. --- @tparam[opt=0] number h The relative height. +-- @see x +-- @see y +-- @see width +-- @see height +-- @see floating function client.object.relative_move(self, x, y, w, h) local geometry = self:geometry() geometry['x'] = geometry['x'] + (x or 0) @@ -552,6 +570,7 @@ end -- -- @method move_to_tag -- @tparam tag target The tag to move the client to. +-- @noreturn -- @request client activate client.movetotag granted When a client could be -- activated because `c:move_to_tag()` was called. -- @see tags @@ -571,7 +590,7 @@ end -- -- @deprecated awful.client.toggletag -- @tparam tag target The tag to toggle. --- @tparam[opt] client c The client to toggle, otherwise the focused one is used. +-- @tparam[opt=client.focus] client c The client to toggle, otherwise the focused one is used. -- @see client.toggle_tag -- @see tags function client.toggletag(target, c) @@ -585,6 +604,7 @@ end -- -- @method toggle_tag -- @tparam tag target The tag to move the client to. +-- @noreturn -- @see tags function client.object.toggle_tag(self, target) -- Check that tag and client screen are identical @@ -610,7 +630,7 @@ end --- Move a client to a screen. Default is next screen, cycling. -- @deprecated awful.client.movetoscreen --- @tparam client c The client to move. +-- @tparam[opt=client.focus] client c The client to move. -- @tparam screen s The screen, default to current + 1. -- @see screen -- @see client.move_to_screen @@ -625,6 +645,7 @@ end -- -- @method move_to_screen -- @tparam[opt=c.screen.index+1] screen s The screen, default to current + 1. +-- @noreturn -- @see screen -- @see request::activate -- @request client activate client.movetoscreen granted When a client could be @@ -676,6 +697,7 @@ end -- @DOC_sequences_client_to_selected_tags1_EXAMPLE@ -- -- @method to_selected_tags +-- @noreturn -- @see screen.selected_tags function client.object.to_selected_tags(self) local tags = {} @@ -709,7 +731,7 @@ end --- If a client is marked or not. -- -- @property marked --- @tparam boolean marked +-- @tparam[opt=false] boolean marked -- @emits marked (for legacy reasons, use `property::marked`) -- @emits unmarker (for legacy reasons, use `property::marked`) -- @emits property::marked @@ -791,16 +813,27 @@ end -- Floating client are not handled by tiling layouts. -- @deprecated awful.client.floating.set -- @tparam client c A client. --- @tparam boolean s True or false. +-- @tparam boolean s `true` is the client is to become floating or `false`. function client.floating.set(c, s) gdebug.deprecate("Use c.floating = true instead of awful.client.floating.set", {deprecated_in=4}) client.object.set_floating(c, s) end -- Set a client floating state, overriding auto-detection. --- Floating client are not handled by tiling layouts. +-- +-- Floating client are not handled by tiling layouts. They can be +-- moved around and resized freely unless other restriction, such as `maximized` +-- or the `size_hints` restrict their geometry. +-- +-- An easy way to position floating clients is to use the `awful.placement` +-- module. +-- -- @tparam client c A client. --- @tparam boolan s True or false. +-- @tparam boolean floating. +-- @see is_immobilized_vertical +-- @see is_immobilized_horizontal +-- @see is_fixed +-- @see size_hints function client.object.set_floating(c, s) c = c or capi.client.focus if c and client.property.get(c, "floating") ~= s then @@ -838,7 +871,7 @@ capi.client.connect_signal("property::geometry", store_floating_geometry) --- Return if a client has a fixed size or not. -- This function is deprecated, use `c.is_fixed` --- @tparam client c The client. +-- @tparam[opt=client.focus] client c The client. -- @deprecated awful.client.isfixed -- @see is_fixed -- @see size_hints_honor @@ -850,8 +883,10 @@ end --- Return if a client has a fixed size or not. -- +-- Fixed size means it cannot be resized. +-- -- @property is_fixed --- @tparam[opt=false] boolean is_fixed The fixed size state +-- @tparam[opt=false] boolean is_fixed -- @propemits false false -- @readonly -- @see size_hints @@ -874,10 +909,10 @@ end --- Is the client immobilized horizontally? -- -- Does the client have a fixed horizontal position and width, i.e. is it --- fullscreen, maximized, or horizontally maximized? +-- `fullscreen`, `maximized`, or `maximized_horizontal`? -- -- @property immobilized_horizontal --- @tparam[opt=false] boolean immobilized_horizontal The immobilized state +-- @tparam[opt=false] boolean immobilized_horizontal -- @readonly -- @see maximized -- @see maximized_horizontal @@ -893,7 +928,7 @@ end -- fullscreen, maximized, or vertically maximized? -- -- @property immobilized_vertical --- @tparam[opt=false] boolean immobilized_vertical The immobilized state +-- @tparam[opt=false] boolean immobilized_vertical -- @readonly -- @see maximized -- @see maximized_vertical @@ -926,7 +961,7 @@ end -- @DOC_sequences_client_floating1_EXAMPLE@ -- -- @property floating --- @tparam boolean floating The floating state. +-- @tparam[opt=false] boolean floating -- @request client border floating granted When a border update is required -- because the client focus status changed. -- @request client border active granted When a client becomes active and is not @@ -1014,7 +1049,8 @@ end -- @DOC_sequences_client_x1_EXAMPLE@ -- -- @property x --- @tparam integer x +-- @tparam[opt=c:geometry().x] integer x +-- @negativeallowed true -- @emits property::geometry -- @emitstparam property::geometry table geo The -- geometry (with `x`, `y`, `width`, `height`). @@ -1032,7 +1068,8 @@ end -- @DOC_sequences_client_y1_EXAMPLE@ -- -- @property y --- @tparam integer y +-- @tparam[opt=c:geometry().y] integer y +-- @negativeallowed true -- @emits property::geometry -- @emitstparam property::geometry table geo The -- geometry (with `x`, `y`, `width`, `height`). @@ -1046,7 +1083,8 @@ end -- @DOC_sequences_client_width1_EXAMPLE@ -- -- @property width --- @tparam integer width +-- @tparam[opt=c:geometry().width] integer width +-- @rangestart 1 -- @emits property::geometry -- @emitstparam property::geometry table geo The -- geometry (with `x`, `y`, `width`, `height`). @@ -1060,7 +1098,8 @@ end -- @DOC_sequences_client_height1_EXAMPLE@ -- -- @property height --- @tparam integer height +-- @tparam[opt=c:geometry().height] integer height +-- @rangestart 1 -- @emits property::geometry -- @emitstparam property::geometry table geo The -- geometry (with `x`, `y`, `width`, `height`). @@ -1136,7 +1175,7 @@ end -- @DOC_screen_wfact4_EXAMPLE@ -- -- @legacylayout awful.client.idx --- @tparam client c the client +-- @tparam client c The client -- @treturn table data A table with "col", "idx" and "num" keys. -- @treturn integer data.col The column number. -- @treturn integer data.idx Index of the client in the column. @@ -1207,8 +1246,8 @@ end -- @DOC_screen_wfact3_EXAMPLE@ -- -- @legacylayout awful.client.setwfact --- @tparam number wfact the window factor value --- @tparam client c the client +-- @tparam number wfact The window factor value +-- @tparam client c The client -- @emits property::windowfact Emitted on the c.first_tag object. -- @see tag.master_width_factor function client.setwfact(wfact, c) @@ -1274,7 +1313,7 @@ end -- @tparam number add Amount to increase/decrease the client's window factor by. -- Should be between `-current_window_factor` and something close to -- infinite. Normalisation then ensures that the sum of all factors is 1. --- @tparam client c the client. +-- @tparam[opt=client.focus] client c The client. -- @emits property::windowfact function client.incwfact(add, c) c = c or capi.client.focus @@ -1314,7 +1353,7 @@ end -- default. -- -- @property dockable --- @tparam boolean dockable The dockable state +-- @tparam[opt=false] boolean dockable -- @propemits false false -- @see struts @@ -1353,7 +1392,7 @@ end -- interprets it as the client (not) wanting a titlebar. -- -- @property requests_no_titlebar --- @tparam boolean requests_no_titlebar Whether the client +-- @tparam[opt=false] boolean requests_no_titlebar Whether the client -- requests not to get a titlebar. -- @propemits false false @@ -1427,6 +1466,7 @@ end -- @tparam string prop The property name. -- @tparam string kind The type (used for register_xproperty). -- One of "string", "number" or "boolean". +-- @noreturn function client.property.persist(prop, kind) local xprop = "awful.client.property." .. prop capi.awesome.register_xproperty(xprop, kind) @@ -1445,11 +1485,11 @@ end -- Starting from the client in focus or the given index, all clients that match -- a given criteria. -- --- @tparam function filter a function that returns true to indicate a positive match. --- @tparam integer start what index to start iterating from. Defaults to using the +-- @tparam function filter A function that returns true to indicate a positive match. +-- @tparam integer start What index to start iterating from. Defaults to using the -- index of the currently focused client. --- @tparam screen s which screen to use. nil means all screens. --- +-- @tparam[opt=nil] screen s Which screen to use. nil means all screens. +-- @treturn function A Lua iterator (to use in a `for` loop). -- @staticfct awful.client.iterate -- @usage -- un-minimize all urxvt instances -- local urxvt = function (c) @@ -1470,8 +1510,8 @@ end -- If multiple clients match the given condition then the next one is -- focused. -- --- @tparam string cmd the command to execute --- @tparam function matcher a function that returns true to indicate a matching client +-- @tparam string cmd The command to execute +-- @tparam function matcher A function that returns true to indicate a matching client -- @tparam bool|function merge If true then merge tags (select the client's -- first tag additionally) when the client is not visible. -- If it is a function, it will be called with the client as argument. @@ -1594,7 +1634,7 @@ end, true, true, "keybinding") -- @DOC_awful_client_shape1_EXAMPLE@ -- -- @property shape --- @tparam gears.shape A gears.shape compatible function. +-- @tparam[opt=gears.shape.rectangle] shape shape A gears.shape compatible function. -- @propemits true false -- @see gears.shape function client.object.set_shape(self, shape) @@ -1640,7 +1680,7 @@ end -- -- @method activate -- @tparam table args --- @tparam[opt=other] string args.context Why was this activate called? +-- @tparam[opt="other"] string args.context Why was this activate called? -- @tparam[opt=true] boolean args.raise Raise the client to the top of its layer -- and unminimize it (if needed). -- @tparam[opt=false] boolean args.force Force the activation even for unfocusable @@ -1649,6 +1689,9 @@ end -- @tparam[opt=false] boolean args.switch_to_tag -- @tparam[opt=false] boolean args.action Once activated, perform an action. -- @tparam[opt=false] boolean args.toggle_minimization +-- @noreturn +-- @request client activate args.context granted Will use the context defined in +-- `args.context`. -- @see awful.permissions.add_activate_filter -- @see awful.permissions.activate -- @see request::activate @@ -1693,6 +1736,7 @@ end -- @method grant -- @tparam string permission The permission name (just the name, no `request::`). -- @tparam string context The reason why this permission is requested. +-- @noreturn -- @see awful.permissions --- Deny a permission for a client. @@ -1700,6 +1744,7 @@ end -- @method deny -- @tparam string permission The permission name (just the name, no `request::`). -- @tparam string context The reason why this permission is requested. +-- @noreturn -- @see awful.permissions pcommon.setup_grant(client.object, "client") @@ -1755,7 +1800,7 @@ pcommon.setup_grant(client.object, "client") -- end) -- -- @property active --- @tparam boolean active +-- @tparam[opt=true] boolean active -- @request client border active granted When a client becomes active. -- @request client border inactive granted When a client stop being active. -- @readonly @@ -1792,6 +1837,7 @@ end) --- Emitted when a client need to get a titlebar. -- @signal request::titlebars +-- @tparam client c The client. -- @tparam[opt=nil] string content The context (like "rules") -- @tparam[opt=nil] table hints Some hints. -- @classsignal @@ -1815,6 +1861,7 @@ end) -- * **floating**: When the floating or maximization state changes. -- -- @signal request::border +-- @tparam client c The client. -- @tparam string context The context. -- @tparam table hints The hints. -- @classsignal @@ -1828,6 +1875,7 @@ end) -- @tparam bool|function merge If true then merge tags (select the client's -- first tag additionally) when the client is not visible. -- If it is a function, it will be called with the client as argument. +-- @noreturn -- Add clients during startup to focus history. -- This used to happen through permissions.activate, but that only handles visible diff --git a/lib/awful/completion.lua b/lib/awful/completion.lua index f374c9094..a23590cce 100644 --- a/lib/awful/completion.lua +++ b/lib/awful/completion.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Completion module. +--- Helper utilities for bash-like completion lists. -- -- This module store a set of function using shell to complete commands name. -- @@ -31,7 +31,8 @@ local bashcomp_src = "@SYSCONFDIR@/bash_completion" --- Enable programmable bash completion in awful.completion.bash at the price of -- a slight overhead. --- @param src The bash completion source file, /etc/bash_completion by default. +-- @tparam string src The bash completion source file, `/etc/bash_completion` by default. +-- @noreturn -- @staticfct awful.completion.bashcomp_load function completion.bashcomp_load(src) if src then bashcomp_src = src end @@ -189,11 +190,13 @@ end --- Run a generic completion. -- For this function to run properly the awful.completion.keyword table should -- be fed up with all keywords. The completion is run against these keywords. --- @param text The current text the user had typed yet. --- @param cur_pos The current cursor position. --- @param ncomp The number of yet requested completion using current text. --- @param keywords The keywords table uised for completion. --- @return The new match, the new cursor position, the table of all matches. +-- @tparam string text The current text the user had typed yet. +-- @tparam number cur_pos The current cursor position. +-- @tparam number ncomp The number of yet requested completion using current text. +-- @tparam table keywords The keywords table uised for completion. +-- @treturn string The new match. +-- @treturn number The new cursor position. +-- @treturn table The table of all matches. -- @staticfct awful.completion.generic function completion.generic(text, cur_pos, ncomp, keywords) -- luacheck: no unused args -- The keywords table may be empty diff --git a/lib/awful/hotkeys_popup/init.lua b/lib/awful/hotkeys_popup/init.lua index 8aaa75445..058bae128 100644 --- a/lib/awful/hotkeys_popup/init.lua +++ b/lib/awful/hotkeys_popup/init.lua @@ -10,7 +10,7 @@ local hotkeys_popup = { widget = require("awful.hotkeys_popup.widget"), } ---- This is the same as awful.hotkeys_popup.widget.show_help. +--- This is the same as `awful.hotkeys_popup.widget.show_help`. -- -- example usage: -- @@ -25,6 +25,7 @@ local hotkeys_popup = { -- @tparam[opt=true] boolean show_args.show_awesome_keys Show AwesomeWM hotkeys. -- When set to `false` only app-specific hotkeys will be shown. -- @staticfct awful.hotkeys_popup.show_help +-- @noreturn -- @see awful.hotkeys_popup.widget.show_help hotkeys_popup.show_help = hotkeys_popup.widget.show_help diff --git a/lib/awful/hotkeys_popup/widget.lua b/lib/awful/hotkeys_popup/widget.lua index 8d1254130..20fb3d77b 100644 --- a/lib/awful/hotkeys_popup/widget.lua +++ b/lib/awful/hotkeys_popup/widget.lua @@ -74,6 +74,7 @@ local gtable = require("gears.table") local gstring = require("gears.string") local wibox = require("wibox") local beautiful = require("beautiful") +local rgba = require("gears.color").to_rgba_string local dpi = beautiful.xresources.apply_dpi local matcher = require("gears.matcher")() @@ -86,11 +87,11 @@ function markup.font(font, text) end -- Set the foreground. function markup.fg(color, text) - return '' .. tostring(text) .. '' + return '' .. tostring(text) .. '' end -- Set the background. function markup.bg(color, text) - return '' .. tostring(text) .. '' + return '' .. tostring(text) .. '' end local function join_plus_sort(modifiers) @@ -124,8 +125,51 @@ widget.hide_without_description = true widget.merge_duplicates = true --- Labels used for displaying human-readable keynames. --- @tfield table widget.labels --- @param table +-- @tfield table awful.hotkeys_popup.widget.labels +-- @tfield[opt="Ctrl"] string Control +-- @tfield[opt="Alt"] string Mod1 +-- @tfield[opt="Alt Gr"] string ISO_Level3_Shift +-- @tfield[opt="Super"] string Mod4 +-- @tfield[opt="Ins"] string Insert +-- @tfield[opt="Del"] string Delete +-- @tfield[opt="PgDn"] string Next +-- @tfield[opt="PgUp"] string Prior +-- @tfield[opt="←"] string Left +-- @tfield[opt="↑"] string Up +-- @tfield[opt="→"] string Right +-- @tfield[opt="↓"] string Down +-- @tfield[opt="Num1"] string KP_End +-- @tfield[opt="Num2"] string KP_Down +-- @tfield[opt="Num3"] string KP_Next +-- @tfield[opt="Num4"] string KP_Left +-- @tfield[opt="Num5"] string KP_Begin +-- @tfield[opt="Num6"] string KP_Right +-- @tfield[opt="Num7"] string KP_Home +-- @tfield[opt="Num8"] string KP_Up +-- @tfield[opt="Num9"] string KP_Prior +-- @tfield[opt="Num0"] string KP_Insert +-- @tfield[opt="Num."] string KP_Delete +-- @tfield[opt="Num/"] string KP_Divide +-- @tfield[opt="Num*"] string KP_Multiply +-- @tfield[opt="Num-"] string KP_Subtract +-- @tfield[opt="Num+"] string KP_Add +-- @tfield[opt="NumEnter"] string KP_Enter +-- @tfield[opt="Esc"] string Escape +-- @tfield[opt="Tab"] string Tab +-- @tfield[opt="Space"] string space +-- @tfield[opt="Enter"] string Return +-- @tfield[opt="´"] string dead_acute +-- @tfield[opt="^"] string dead_circumflex +-- @tfield[opt="`"] string dead_grave +-- @tfield[opt="🔆+"] string XF86MonBrightnessUp +-- @tfield[opt="🔅-"] string XF86MonBrightnessDown +-- @tfield[opt="🕩+"] string XF86AudioRaiseVolume +-- @tfield[opt="🕩-"] string XF86AudioLowerVolume +-- @tfield[opt="🔇"] string XF86AudioMute +-- @tfield[opt="⏯"] string XF86AudioPlay +-- @tfield[opt="⏮"] string XF86AudioPrev +-- @tfield[opt="⏭"] string XF86AudioNext +-- @tfield[opt="⏹"] string XF86AudioStop widget.labels = { Control = "Ctrl", Mod1 = "Alt", @@ -248,6 +292,21 @@ widget.labels = { -- @tparam[opt] table args.group_rules Rules for showing 3rd-party hotkeys. @see `awful.hotkeys_popup.keys.vim`. -- @return Widget instance. -- @constructorfct awful.widget.hotkeys_popup.widget.new +-- @usebeautiful beautiful.hotkeys_fg +-- @usebeautiful beautiful.hotkeys_bg +-- @usebeautiful beautiful.hotkeys_border_width +-- @usebeautiful beautiful.hotkeys_border_color +-- @usebeautiful beautiful.hotkeys_shape +-- @usebeautiful beautiful.hotkeys_modifiers_fg +-- @usebeautiful beautiful.hotkeys_label_bg +-- @usebeautiful beautiful.hotkeys_label_fg +-- @usebeautiful beautiful.hotkeys_font +-- @usebeautiful beautiful.hotkeys_description_font +-- @usebeautiful beautiful.hotkeys_group_margin +-- @usebeautiful beautiful.bg_normal Fallback. +-- @usebeautiful beautiful.fg_normal Fallback. +-- @usebeautiful beautiful.fg_minimize Fallback. +-- @usebeautiful beautiful.border_width Fallback. function widget.new(args) args = args or {} local widget_instance = { @@ -669,11 +728,13 @@ function widget.new(args) --- Show popup with hotkeys help. - -- @tparam[opt] client c Client. - -- @tparam[opt] screen s Screen. - -- @tparam[opt] table show_args Additional arguments. + -- @tparam[opt=client.focus] client c Client. + -- @tparam[opt=c.screen] screen s Screen. + -- @tparam[opt={}] table show_args Additional arguments. -- @tparam[opt=true] boolean show_args.show_awesome_keys Show AwesomeWM hotkeys. -- When set to `false` only app-specific hotkeys will be shown. + -- @treturn awful.keygrabber The keybrabber used to detect when the key is + -- released. -- @method show_help function widget_instance:show_help(c, s, show_args) show_args = show_args or {} @@ -734,6 +795,7 @@ function widget.new(args) --- Add hotkey descriptions for third-party applications. -- @tparam table hotkeys Table with bindings, -- see `awful.hotkeys_popup.key.vim` as an example. + -- @noreturn -- @method add_hotkeys function widget_instance:add_hotkeys(hotkeys) for group, bindings in pairs(hotkeys) do @@ -754,9 +816,10 @@ function widget.new(args) end --- Add hotkey group rules for third-party applications. - -- @tparam string group hotkeys group name, - -- @tparam table data rule data for the group + -- @tparam string group Hotkeys group name, + -- @tparam table data Rule data for the group -- see `awful.hotkeys_popup.key.vim` as an example. + -- @noreturn -- @method add_group_rules function widget_instance:add_group_rules(group, data) self.group_rules[group] = data @@ -778,6 +841,8 @@ end -- @tparam[opt] table args Additional arguments. -- @tparam[opt=true] boolean args.show_awesome_keys Show AwesomeWM hotkeys. -- When set to `false` only app-specific hotkeys will be shown. +-- @treturn awful.keygrabber The keybrabber used to detect when the key is +-- released. -- @staticfct awful.hotkeys_popup.widget.show_help function widget.show_help(...) return get_default_widget():show_help(...) @@ -787,19 +852,21 @@ end -- (default widget instance will be used). -- @tparam table hotkeys Table with bindings, -- see `awful.hotkeys_popup.key.vim` as an example. +-- @noreturn -- @staticfct awful.hotkeys_popup.widget.add_hotkeys function widget.add_hotkeys(...) - return get_default_widget():add_hotkeys(...) + get_default_widget():add_hotkeys(...) end --- Add hotkey group rules for third-party applications -- (default widget instance will be used). --- @tparam string group rule group name, --- @tparam table data rule data for the group +-- @tparam string group Rule group name, +-- @tparam table data Rule data for the group -- see `awful.hotkeys_popup.key.vim` as an example. +-- @noreturn -- @staticfct awful.hotkeys_popup.widget.add_group_rules function widget.add_group_rules(group, data) - return get_default_widget():add_group_rules(group, data) + get_default_widget():add_group_rules(group, data) end return widget diff --git a/lib/awful/key.lua b/lib/awful/key.lua index ec111ce52..1fc4b17cc 100644 --- a/lib/awful/key.lua +++ b/lib/awful/key.lua @@ -43,7 +43,8 @@ local gobject = require("gears.object") -- keycode such as `#65`. -- -- @property key --- @param string +-- @tparam string key +-- @propertydefault Set in the constructor. --- The table of modifier keys. -- @@ -68,38 +69,43 @@ local gobject = require("gears.object") -- Please note that Awesome ignores the status of "Lock" and "Mod2" (Num Lock). -- -- @property modifiers --- @tparam table modifiers +-- @tparam[opt={}] table modifiers +-- @tablerowtype A list of modifier names in no specific order. --- The description of the function run from a key binding. -- -- This is used, for example, by `awful.hotkeys_popup`. -- -- @property description --- @param string +-- @tparam[opt=""] string description --- The key name. -- -- This can be useful when searching for keybindings by keywords. -- -- @property name --- @param string +-- @tparam[opt=""] string name --- The key group bound to a function in a key binding. -- -- This is used, for example, by `awful.hotkeys_popup`. -- -- @property group --- @param string +-- @tparam[opt=""] string group --- The callback when this key is pressed. -- -- @property on_press --- @param function +-- @tparam[opt=nil] function|nil on_press +-- @functionnoparam +-- @functionnoreturn --- The callback when this key is released. -- -- @property on_release --- @param function +-- @tparam[opt=nil] function|nil on_release +-- @functionnoparam +-- @functionnoreturn local key = { mt = {}, hotkeys = {} } @@ -159,7 +165,8 @@ end --- Execute this keybinding. -- --- @method :trigger +-- @method trigger +-- @noreturn function key:trigger() local data = reverse_map[self] @@ -432,10 +439,10 @@ function key.new(args, keycode, press, release, data) end --- Compare a key object with modifiers and key. --- @param _key The key object. --- @param pressed_mod The modifiers to compare with. --- @param pressed_key The key to compare with. --- @staticfct awful.key.match +-- @tparam table pressed_mod The modifiers to compare with. +-- @tparam string pressed_key The key to compare with. +-- @treturn boolean If the key and modifier match. +-- @method match function key.match(self, pressed_mod, pressed_key) -- First, compare key. if pressed_key ~= self.key then return false end diff --git a/lib/awful/keyboard.lua b/lib/awful/keyboard.lua index ea49ba6bb..3ca61dc1f 100644 --- a/lib/awful/keyboard.lua +++ b/lib/awful/keyboard.lua @@ -46,6 +46,7 @@ capi.awesome.connect_signal("xkb::map_changed", function() conversion = nil end) -- @tparam table modifiers A modified table. Valid modifiers are: `Any`, `Mod1`, -- `Mod2`, `Mod3`, `Mod4`, `Mod5`, `Shift`, `Lock` and `Control`. -- @tparam string key The key. +-- @noreturn -- @staticfct awful.keyboard.emulate_key_combination function module.emulate_key_combination(modifiers, key) local modmap = generate_conversion_map() @@ -90,6 +91,7 @@ end -- -- @staticfct awful.keyboard.append_global_keybinding -- @tparam awful.key key The key object. +-- @noreturn -- @see awful.key -- @see awful.keyboard.append_global_keybindings -- @see awful.keyboard.remove_global_keybinding @@ -107,6 +109,7 @@ end -- @tparam table keys A table of `awful.key` objects. Optionally, it can have -- a `group` entry. If set, the `group` property will be set on all `awful.keys` -- objects. +-- @noreturn -- @see awful.key -- @see awful.keyboard.append_global_keybinding -- @see awful.keyboard.remove_global_keybinding @@ -131,6 +134,7 @@ end -- -- @staticfct awful.keyboard.remove_global_keybinding -- @tparam awful.key key The key object. +-- @noreturn -- @see awful.key -- @see awful.keyboard.append_global_keybinding @@ -145,6 +149,7 @@ local default_keys = {} -- -- @staticfct awful.keyboard.append_client_keybinding -- @tparam awful.key key The key. +-- @noreturn -- @emits client_keybinding::added -- @emitstparam client_keybinding::added awful.key key The key. -- @see awful.key @@ -164,6 +169,7 @@ end -- -- @staticfct awful.keyboard.append_client_keybindings -- @tparam table keys A table containing `awful.key` objects. +-- @noreturn -- @emits client_keybinding::added -- @emitstparam client_keybinding::added awful.key key The key. -- @see awful.key diff --git a/lib/awful/keygrabber.lua b/lib/awful/keygrabber.lua index e457f53c4..f7e04e00d 100644 --- a/lib/awful/keygrabber.lua +++ b/lib/awful/keygrabber.lua @@ -296,7 +296,10 @@ end -- @DOC_text_awful_keygrabber_timeout_EXAMPLE@ -- -- @property timeout --- @param number +-- @tparam[opt=nil] number|nil timeout +-- @propertyunit second +-- @negativeallowed false +-- @propertytype nil No timeout. -- @see gears.timer -- @see timeout_callback @@ -313,26 +316,23 @@ end -- -- It can also be a table containing many keys (as values). -- --- @DOC_text_awful_keygrabber_stop_keys_EXAMPLE@ --- --- @DOC_text_awful_keygrabber_stop_key_EXAMPLE@ --- -- Please note that modkeys are not accepted as `stop_key`s. You have to use -- their corresponding key names such as `Control_L`. -- -- @property stop_key --- @param[opt=nil] string|table stop_key +-- @tparam[opt=nil] string|table|nil stop_key +-- @propertyunit nil No stop key. +-- @propertyunit string A single stop key. +-- @propertyunit table One or more stop key(s). +-- @tablerowtype A list of key names, such as `"Control"` or `"a"`. -- @see stop_event --- The event on which the keygrabbing will be terminated. -- --- the valid values are: --- --- * "press" (default) --- * "release" --- -- @property stop_event --- @param string +-- @tparam[opt="press"] string stop_event +-- @propertyvalue "press" When the keyboard key is first pressed. +-- @propertyvalue "release" When the keyboard key is released. -- @see stop_key --- Whether or not to execute the key press/release callbacks when keybindings are called. @@ -344,14 +344,14 @@ end -- By default, keybindings block those callbacks from being executed. -- -- @property mask_event_callback --- @param[opt=true] boolean +-- @tparam[opt=true] boolean mask_event_callback -- @see keybindings -- @see keyreleased_callback -- @see keypressed_callback --- Do not call the callbacks on modifier keys (like `Control` or `Mod4`) events. -- @property mask_modkeys --- @param[opt=false] boolean +-- @tparam[opt=false] boolean mask_modkeys -- @see mask_event_callback --- Export all keygrabber keybindings as root (global) keybindings. @@ -365,7 +365,7 @@ end -- have a single instance. -- -- @property export_keybindings --- @param[opt=false] boolean +-- @tparam[opt=false] boolean export_keybindings --- The root (global) keybinding to start this keygrabber. -- @@ -376,7 +376,8 @@ end -- @DOC_text_awful_keygrabber_root_keybindings_EXAMPLE@ -- -- @property root_keybindings --- @param table +-- @tparam[opt={}] table root_keybindings +-- @tablerowtype A list of `awful.key` objects. -- @see export_keybindings -- @see keybindings @@ -385,7 +386,8 @@ end -- This property contains a table of `awful.key` objects. -- -- @property keybindings --- @param table +-- @tparam[opt={}] table keybindings +-- @tablerowtype A list of `awful.key` objects. -- @see export_keybindings -- @see root_keybindings -- @see awful.key @@ -402,7 +404,10 @@ end -- @DOC_text_awful_keygrabber_allowed_keys_EXAMPLE@ -- -- @property allowed_keys --- @tparam[opt=nil] table|nil allowed_keys The list of keys. +-- @tparam[opt=nil] table|nil allowed_keys +-- @propertytype nil All keys are allowed. +-- @propertytype table Only some keys are allowed. +-- @tablerowtype A list of key names, such as `"Control"` or `"a"`. --- The sequence of keys recorded since the start of the keygrabber. -- @@ -415,7 +420,7 @@ end -- @DOC_text_awful_keygrabber_autostart_EXAMPLE@ -- -- @property sequence --- @param string +-- @tparam[opt=""] string sequence -- --- The current (running) instance of this keygrabber. @@ -500,6 +505,7 @@ end -- @method stop -- @tparam string|nil stop_key Override the key passed to `stop_callback` **DEPRECATED** -- @tparam tale|nil Override the modifiers passed to `stop_callback` **DEPRECATED** +-- @noreturn -- @emits stopped -- @emits property::current_instance function keygrabber:stop(stop_key, stop_mods) @@ -535,6 +541,7 @@ end -- @method add_keybinding -- @tparam awful.key key The key. -- @tparam string description.group The keybinding group +-- @noreturn function keygrabber:add_keybinding(key, keycode, callback, description) local mods = not key._is_awful_key and key or nil @@ -652,7 +659,7 @@ end -- -- @callback keypressed_callback -- @tparam table self The current transaction object. --- @tparam table mod The current modifiers (like "Control" or "Shift"). +-- @tparam table mod The current modifiers (like `"Control"` or `"Shift"`). -- @tparam string key The key name. -- @tparam string event The event ("press" or "release"). -- @usage local function my_keypressed_cb(self, mod, key, command) @@ -666,7 +673,7 @@ end -- end -- @callback keyreleased_callback -- @tparam table self The current transaction object. --- @tparam table mod The current modifiers (like "Control" or "Shift"). +-- @tparam table mod The current modifiers (like `"Control"` or `"Shift"`). -- @tparam string key The key name. -- @tparam string event The event ("press" or "release") @@ -698,7 +705,7 @@ end -- @tparam[opt=false] boolean args.export_keybindings Create root (global) keybindings. -- @tparam[opt=false] boolean args.autostart Start the grabbing immediately -- @tparam[opt=false] boolean args.mask_modkeys Do not call the callbacks on --- modifier keys (like `Control` or `Mod4`) events. +-- modifier keys (like `"Control"` or `"Mod4"`) events. -- @constructorfct awful.keygrabber function keygrab.run_with_keybindings(args) args = args or {} @@ -852,6 +859,7 @@ local signals = {} -- @staticfct awful.keygrabber.connect_signal -- @tparam string name The signal name. -- @tparam function callback The callback. +-- @noreturn function keygrab.connect_signal(name, callback) signals[name] = signals[name] or {} @@ -865,6 +873,7 @@ end -- @staticfct awful.keygrabber.disconnect_signal -- @tparam string name The signal name. -- @tparam function callback The callback. +-- @noreturn function keygrab.disconnect_signal(name, callback) signals[name] = signals[name] or {} @@ -885,6 +894,7 @@ end -- @staticfct awful.keygrabber.emit_signal -- @tparam string name The signal name. -- @param ... Other arguments for the callbacks. +-- @noreturn function keygrab.emit_signal(name, ...) signals[name] = signals[name] or {} diff --git a/lib/awful/layout/init.lua b/lib/awful/layout/init.lua index fc8af8ec9..d66be87bd 100644 --- a/lib/awful/layout/init.lua +++ b/lib/awful/layout/init.lua @@ -1,5 +1,29 @@ --------------------------------------------------------------------------- ---- Layout module for awful. +--- Deterministically lay the clients in a screen workarea. +-- +-- The `awful.layout` module contains many sub-modules. Each of them contain +-- one or more layout. `awful.layout` offers static layouts rather than +-- tree based like other WMs. The layout have a small number of configuration +-- variables: +-- +-- * `master_width_factor`: The ratio between the main (master) section of the +-- layout and a sub-section. For example, in the `tile.left` layout, the main +-- (master) part contains `master_count` clients and the secondary part contains +-- all other clients. +-- * `master_count`: The number of clients which belong to the main (master) area. +-- * `column_count`: The number of columns to store the clients in the secondary +-- area. +-- * `master_fill_policy`: When the number of clients is below `master_count`, +-- how is the remaining space used. +-- * `gaps`: The empty space between the clients. +-- * `gap_single_client`: Same as gap, but when there is a single client. Gaps +-- are often useful as a visual cue to know where a client starts and ends. +-- This makes no sense when there is only one. +-- +-- Not all layouts make use of all variables. Having such an overloaded meaning +-- to a small set of variable is useful to attach those values to keybindings +-- without having special logic for each layouts. AwesomeWM keybindings are not +-- modal, so such "limitation" actually improves usability. -- -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008 Julien Danjou @@ -85,7 +109,7 @@ local arrange_lock = false local delayed_arrange = {} --- Get the current layout. --- @param screen The screen. +-- @tparam screen screen The screen. -- @return The layout function. -- @staticfct awful.layout.get function layout.get(screen) @@ -98,9 +122,10 @@ function layout.get(screen) end --- Change the layout of the current tag. --- @param i Relative index. --- @param s The screen. --- @param[opt] layouts A table of layouts. +-- @tparam integer i Relative index. +-- @tparam screen s The screen. +-- @tparam[opt=s.selected_tag.layouts] table layouts A table of layouts. +-- @noreturn -- @staticfct awful.layout.inc function layout.inc(i, s, layouts) if type(i) == "table" then @@ -147,6 +172,7 @@ end --- Set the layout function of the current tag. -- @tparam layout|function l Layout object or function. -- @tparam[opt=mouse.screen.selected_tag] tag t The tag to modify. +-- @noreturn -- @staticfct awful.layout.set function layout.set(l, t) t = t or capi.mouse.screen.selected_tag @@ -208,7 +234,8 @@ function layout.parameters(t, screen) end --- Arrange a screen using its current layout. --- @param screen The screen to arrange. +-- @tparam screen screen The screen to arrange. +-- @noreturn -- @staticfct awful.layout.arrange function layout.arrange(screen) screen = get_screen(screen) @@ -251,6 +278,7 @@ end -- -- @staticfct awful.layout.append_default_layout -- @tparam layout to_add A valid tag layout. +-- @noreturn -- @see awful.layout.layouts function layout.append_default_layout(to_add) rawset(default_layouts, #default_layouts+1, to_add) @@ -287,6 +315,7 @@ end -- -- @staticfct awful.layout.append_default_layouts -- @tparam table layouts A table of valid tag layout. +-- @noreturn -- @see awful.layout.layouts function layout.append_default_layouts(layouts) for _, l in ipairs(layouts) do diff --git a/lib/awful/layout/suit/corner.lua b/lib/awful/layout/suit/corner.lua index be6e82002..60029b35e 100644 --- a/lib/awful/layout/suit/corner.lua +++ b/lib/awful/layout/suit/corner.lua @@ -171,6 +171,7 @@ end -- Display master client in a corner of the screen, and slaves in one -- column and one row around the master. -- @clientlayout awful.layout.suit.corner.nw +-- @usebeautiful beautiful.layout_cornernw corner.nw = { name = "cornernw", arrange = function (p) return do_corner(p, "NW") end, @@ -181,6 +182,7 @@ corner.nw = { -- Display master client in a corner of the screen, and slaves in one -- column and one row around the master. -- @clientlayout awful.layout.suit.corner.ne +-- @usebeautiful beautiful.layout_cornerne corner.ne = { name = "cornerne", arrange = function (p) return do_corner(p, "NE") end, @@ -191,6 +193,7 @@ corner.ne = { -- Display master client in a corner of the screen, and slaves in one -- column and one row around the master. -- @clientlayout awful.layout.suit.corner.sw +-- @usebeautiful beautiful.layout_cornersw corner.sw = { name = "cornersw", arrange = function (p) return do_corner(p, "SW") end, @@ -201,6 +204,7 @@ corner.sw = { -- Display master client in a corner of the screen, and slaves in one -- column and one row around the master. -- @clientlayout awful.layout.suit.corner.se +-- @usebeautiful beautiful.layout_cornerse corner.se = { name = "cornerse", arrange = function (p) return do_corner(p, "SE") end, diff --git a/lib/awful/layout/suit/fair.lua b/lib/awful/layout/suit/fair.lua index 6930a09e7..c01c4a153 100644 --- a/lib/awful/layout/suit/fair.lua +++ b/lib/awful/layout/suit/fair.lua @@ -107,10 +107,12 @@ end --- The fair layout. -- Try to give all clients the same size. -- @clientlayout awful.layout.suit.fair +-- @usebeautiful beautiful.layout_fairv --- The horizontal fair layout. -- Try to give all clients the same size. -- @clientlayout awful.layout.suit.fair.horizontal +-- @usebeautiful beautiful.layout_fairh return fair diff --git a/lib/awful/layout/suit/floating.lua b/lib/awful/layout/suit/floating.lua index f3a9a9b7e..e65ccfa92 100644 --- a/lib/awful/layout/suit/floating.lua +++ b/lib/awful/layout/suit/floating.lua @@ -114,6 +114,7 @@ end --- The floating layout. -- @clientlayout awful.layout.suit.floating +-- @usebeautiful beautiful.layout_floating floating.name = "floating" diff --git a/lib/awful/layout/suit/magnifier.lua b/lib/awful/layout/suit/magnifier.lua index c2c56883d..23acddcf3 100644 --- a/lib/awful/layout/suit/magnifier.lua +++ b/lib/awful/layout/suit/magnifier.lua @@ -143,6 +143,7 @@ end --- The magnifier layout. -- @clientlayout awful.layout.suit.magnifier +-- @usebeautiful beautiful.layout_magnifier magnifier.name = "magnifier" diff --git a/lib/awful/layout/suit/max.lua b/lib/awful/layout/suit/max.lua index 731c7a8ea..1d27856ca 100644 --- a/lib/awful/layout/suit/max.lua +++ b/lib/awful/layout/suit/max.lua @@ -43,6 +43,7 @@ end --- Maximized layout. -- @clientlayout awful.layout.suit.max +-- @usebeautiful beautiful.layout_max max.name = "max" function max.arrange(p) return fmax(p, false) @@ -53,6 +54,7 @@ end --- Fullscreen layout. -- @clientlayout awful.layout.suit.max.fullscreen +-- @usebeautiful beautiful.layout_fullscreen max.fullscreen = {} max.fullscreen.name = "fullscreen" max.fullscreen.skip_gap = max.skip_gap diff --git a/lib/awful/layout/suit/spiral.lua b/lib/awful/layout/suit/spiral.lua index 629d9828a..fe608dfa2 100644 --- a/lib/awful/layout/suit/spiral.lua +++ b/lib/awful/layout/suit/spiral.lua @@ -71,6 +71,7 @@ end --- Dwindle layout. -- @clientlayout awful.layout.suit.spiral.dwindle +-- @usebeautiful beautiful.layout_dwindle spiral.dwindle = {} spiral.dwindle.name = "dwindle" function spiral.dwindle.arrange(p) @@ -79,6 +80,7 @@ end --- Spiral layout. -- @clientlayout awful.layout.suit.spiral.name +-- @usebeautiful beautiful.layout_spiral spiral.name = "spiral" function spiral.arrange(p) return do_spiral(p, true) diff --git a/lib/awful/layout/suit/tile.lua b/lib/awful/layout/suit/tile.lua index 4609a0579..85922c8b9 100644 --- a/lib/awful/layout/suit/tile.lua +++ b/lib/awful/layout/suit/tile.lua @@ -312,6 +312,7 @@ end --- The main tile algo, on the right. -- @param screen The screen number to tile. -- @clientlayout awful.layout.suit.tile.right +-- @usebeautiful beautiful.layout_tile tile.right = {} tile.right.name = "tile" tile.right.arrange = do_tile @@ -323,6 +324,7 @@ end --- The main tile algo, on the left. -- @param screen The screen number to tile. -- @clientlayout awful.layout.suit.tile.left +-- @usebeautiful beautiful.layout_tileleft tile.left = {} tile.left.name = "tileleft" tile.left.skip_gap = tile.skip_gap @@ -336,6 +338,7 @@ end --- The main tile algo, on the bottom. -- @param screen The screen number to tile. -- @clientlayout awful.layout.suit.tile.bottom +-- @usebeautiful beautiful.layout_tilebottom tile.bottom = {} tile.bottom.name = "tilebottom" tile.bottom.skip_gap = tile.skip_gap @@ -349,6 +352,7 @@ end --- The main tile algo, on the top. -- @param screen The screen number to tile. -- @clientlayout awful.layout.suit.tile.top +-- @usebeautiful beautiful.layout_tiletop tile.top = {} tile.top.name = "tiletop" tile.top.skip_gap = tile.skip_gap diff --git a/lib/awful/menu.lua b/lib/awful/menu.lua index 4e87ee232..474b74320 100644 --- a/lib/awful/menu.lua +++ b/lib/awful/menu.lua @@ -1,5 +1,5 @@ -------------------------------------------------------------------------------- ---- A menu for awful. +--- Create context menus, optionally with sub-menus. -- -- @author Damien Leone <damien.leone@gmail.com> -- @author Julien Danjou <julien@danjou.info> @@ -93,7 +93,7 @@ end -- @param color -- @see gears.color ---- The default sub-menu indicator if no menu_submenu_icon is provided. +--- The default sub-menu indicator if no `menu_submenu_icon` is provided. -- @beautiful beautiful.menu_submenu -- @tparam[opt="▶"] string menu_submenu The sub-menu text. -- @see beautiful.menu_submenu_icon @@ -357,8 +357,10 @@ end --- Show a menu. --- @param args The arguments --- @param args.coords Menu position defaulting to mouse.coords() +-- @tparam[opt={}] table args The arguments +-- @tparam[opt=mouse.coords] table args.coords The menu position. A table with +-- `x` and `y` as keys and position (in pixels) as values. +-- @noreturn -- @method show function menu:show(args) args = args or {} @@ -374,6 +376,7 @@ end --- Hide a menu popup. -- @method hide +-- @noreturn function menu:hide() -- Remove items from screen for i = 1, #self.items do @@ -390,8 +393,10 @@ function menu:hide() end --- Toggle menu visibility. --- @param args The arguments --- @param args.coords Menu position {x,y} +-- @tparam table args The arguments. +-- @tparam[opt=mouse.coords] table args.coords The menu position. A table with +-- `x` and `y` as keys and position (in pixels) as values. +-- @noreturn -- @method toggle function menu:toggle(args) if self.wibox.visible then @@ -403,6 +408,7 @@ end --- Update menu content. -- @method update +-- @noreturn function menu:update() if self.wibox.visible then self:show({ coords = { x = self.x, y = self.y } }) @@ -413,16 +419,18 @@ end --- Get the elder parent so for example when you kill -- it, it will destroy the whole family. -- @method get_root +-- @treturn awful.menu The root menu. function menu:get_root() return self.parent and menu.get_root(self.parent) or self end --- Add a new menu entry. -- args.* params needed for the menu entry constructor. --- @param args The item params --- @param args.new (Default: awful.menu.entry) The menu entry constructor. --- @param[opt] args.theme The menu entry theme. --- @param[opt] index The index where the new entry will inserted. +-- @tparam table args The item params. +-- @tparam[opt=awful.menu.entry] function args.new The menu entry constructor. +-- @tparam[opt] table args.theme The menu entry theme. +-- @tparam[opt] number index The index where the new entry will inserted. +-- @treturn table|nil The new item. -- @method add function menu:add(args, index) if not args then return end @@ -479,7 +487,8 @@ function menu:add(args, index) end --- Delete menu entry at given position. --- @param num The position in the table of the menu entry to be deleted; can be also the menu entry itself. +-- @tparam table|number num The index in the table of the menu entry to be deleted; can be also the menu entry itself. +-- @noreturn -- @method delete function menu:delete(num) if type(num) == "table" then @@ -580,8 +589,8 @@ end --- Default awful.menu.entry constructor. -- @param parent The parent menu (TODO: This is apparently unused) --- @param args the item params --- @return table with 'widget', 'cmd', 'akey' and all the properties the user wants to change +-- @param args The item params +-- @return table With 'widget', 'cmd', 'akey' and all the properties the user wants to change -- @constructorfct awful.menu.entry function menu.entry(parent, args) -- luacheck: no unused args args = args or {} @@ -673,14 +682,24 @@ end -------------------------------------------------------------------------------- --- Create a menu popup. --- @param args Table containing the menu information. --- --- * Key items: Table containing the displayed items. Each element is a table by default (when element 'new' is --- awful.menu.entry) containing: item name, triggered action (submenu table or function), item icon (optional). --- * Keys theme.[fg|bg]_[focus|normal], theme.border_color, theme.border_width, theme.submenu_icon, theme.height --- and theme.width override the default display for your menu and/or of your menu entry, each of them are optional. --- * Key auto_expand controls the submenu auto expand behaviour by setting it to true (default) or false. -- +-- @tparam table args Table containing the menu information. +-- @tparam[opt=true] boolean args.auto_expand Controls the submenu auto expand behaviour. +-- @tparam table args.items Table containing the displayed items. Each element is a +-- table by default (when element 'new' is awful.menu.entry) containing: item +-- name, triggered action (submenu table or function), item icon (optional). +-- @tparam table args.theme +-- @tparam[opt=beautiful.menu_fg_normal] color args.theme.fg_normal +-- @tparam[opt=beautiful.menu_bg_normal] color args.theme.bg_normal +-- @tparam[opt=beautiful.menu_fg_focus] color args.theme.fg_focus +-- @tparam[opt=beautiful.menu_bg_focus] color args.theme.bg_focus +-- @tparam[opt=beautiful.menu_border_color] color args.theme.border +-- @tparam[opt=beautiful.menu_border_width] integer args.theme.border_width +-- @tparam[opt=beautiful.menu_height] integer args.theme.height +-- @tparam[opt=beautiful.menu_width] integer args.theme.width +-- @tparam[opt=beautiful.menu_font] string args.theme.font +-- @tparam[opt=beautiful.menu_submenu_icon] gears.surface|string args.theme.submenu_icon +-- @tparam[opt=beautiful.menu_submenu] string args.theme.submenu -- @param parent Specify the parent menu if we want to open a submenu, this value should never be set by the user. -- @constructorfct awful.menu -- @usage -- The following function builds and shows a menu of clients that match diff --git a/lib/awful/mouse/client.lua b/lib/awful/mouse/client.lua index d6191b723..3a495b86b 100644 --- a/lib/awful/mouse/client.lua +++ b/lib/awful/mouse/client.lua @@ -13,9 +13,9 @@ local module = {} --- Move a client. -- @staticfct awful.mouse.client.move --- @param c The client to move, or the focused one if nil. +-- @tparam client c The client to move, or the focused one if nil. -- @param snap The pixel to snap clients. --- @param finished_cb Deprecated, do not use. +-- @noreturn -- @request client geometry mouse.move granted When `awful.mouse.client.move` is -- called. function module.move(c, snap, finished_cb) --luacheck: no unused args @@ -69,8 +69,8 @@ end --- Get a client corner coordinates. -- @deprecated awful.mouse.client.corner -- @tparam[opt=client.focus] client c The client to get corner from, focused one by default. --- @tparam string corner The corner to use: auto, top_left, top_right, bottom_left, --- bottom_right, left, right, top bottom. Default is auto, and auto find the +-- @tparam string corner The corner to use: `auto`, `top_left`, `top_right`, `bottom_left`, +-- `bottom_right`, `left`, `right`, `top` or `bottom`. Default is `auto`. `auto` finds the -- nearest corner. -- @treturn string The corner name -- @treturn number x The horizontal position diff --git a/lib/awful/mouse/init.lua b/lib/awful/mouse/init.lua index 0411e3434..b67d1f8eb 100644 --- a/lib/awful/mouse/init.lua +++ b/lib/awful/mouse/init.lua @@ -35,12 +35,12 @@ mouse.wibox = {} -- -- @DOC_screen_client_snap_EXAMPLE@ -- --- @tfield integer snap.default_distance +-- @tfield integer awful.mouse.snap.default_distance -- @tparam[opt=8] integer default_distance -- @see awful.mouse.snap --- The default distance before activating screen edge snap. --- @tfield integer snap.aerosnap_distance +-- @tfield integer awful.mouse.snap.aerosnap_distance -- @tparam[opt=16] integer aerosnap_distance -- @see awful.mouse.snap @@ -48,15 +48,15 @@ mouse.wibox = {} -- --@DOC_awful_placement_aero_snap_EXAMPLE@ -- --- @tfield[opt=true] boolean snap.edge_enabled +-- @tfield[opt=true] boolean awful.mouse.snap.edge_enabled -- @tparam boolean edge_enabled --- Enable client to client snapping. --- @tfield[opt=true] boolean snap.client_enabled +-- @tfield[opt=true] boolean awful.mouse.snap.client_enabled -- @tparam boolean client_enabled --- Enable changing tag when a client is dragged to the edge of the screen. --- @tfield[opt=false] boolean drag_to_tag.enabled +-- @tfield[opt=false] boolean awful.mouse.drag_to_tag.enabled -- @tparam boolean enabled --- The snap outline background color. @@ -65,7 +65,7 @@ mouse.wibox = {} --- The snap outline width. -- @beautiful beautiful.snap_border_width --- @param integer +-- @tparam integer snap_border_width --- The snap outline shape. -- @beautiful beautiful.snap_shape @@ -75,9 +75,17 @@ mouse.wibox = {} -- @beautiful beautiful.snapper_gap -- @tparam[opt=0] number snapper_gap +--- The resize cursor name. +-- @beautiful beautiful.cursor_mouse_resize +-- @tparam[opt="cross"] string cursor + +--- The move cursor name. +-- @beautiful beautiful.cursor_mouse_move +-- @tparam[opt="fleur"] string cursor + --- Get the client object under the pointer. -- @deprecated awful.mouse.client_under_pointer --- @return The client object under the pointer, if one can be found. +-- @treturn client|nil The client object under the pointer, if one can be found. -- @see current_client function mouse.client_under_pointer() gdebug.deprecate("Use mouse.current_client instead of awful.mouse.client_under_pointer()", {deprecated_in=4}) @@ -108,7 +116,8 @@ end, "mouse.resize") --- Get the client currently under the mouse cursor. -- @property current_client --- @tparam client|nil The client +-- @tparam[opt=nil] client|nil current_client +-- @propertytype nil When the mouse cursor is not over a client. function mouse.object.get_current_client() local obj = capi.mouse.object_under_pointer() @@ -119,7 +128,8 @@ end --- Get the wibox currently under the mouse cursor. -- @property current_wibox --- @tparam wibox|nil The wibox +-- @tparam[opt=nil] wibox|nil current_wibox +-- @propertytype nil When the mouse cursor is not over a wibox. function mouse.object.get_current_wibox() local obj = capi.mouse.object_under_pointer() @@ -131,10 +141,10 @@ end --- Get the widgets currently under the mouse cursor. -- -- @property current_widgets --- @tparam nil|table list The widget list --- @treturn table The list of widgets.The first element is the biggest --- container while the last is the topmost widget. The table contains *x*, *y*, --- *width*, *height* and *widget*. +-- @tparam[opt=nil] nil|table current_widgets +-- @tablerowtype table The list of `wibox.widget`s. The first element is the biggest +-- container while the last is the topmost widget. +-- @propertytype nil When the mouse cursor is not over any widget. function mouse.object.get_current_widgets() local w = mouse.object.get_current_wibox() @@ -156,8 +166,8 @@ end --- Get the topmost widget currently under the mouse cursor. -- @property current_widget --- @tparam widget|nil widget The widget --- @treturn ?widget The widget +-- @tparam[opt=nil] widget|nil current_widget +-- @propertytype nil When the mouse cursor is not over a widget. -- @see current_widget_geometry function mouse.object.get_current_widget() @@ -170,7 +180,13 @@ end --- Get the current widget geometry. -- @property current_widget_geometry --- @tparam ?table The geometry. +-- @tparam[opt=nil] table|nil current_widget_geometry +-- @tparam number current_widget_geometry.x +-- @tparam number current_widget_geometry.y +-- @tparam number current_widget_geometry.width +-- @tparam number current_widget_geometry.height +-- @propertytype nil When there is no current widgets. +-- @propertytype table -- @see current_widget function mouse.object.get_current_widget_geometry() @@ -181,7 +197,13 @@ end --- Get the current widget geometries. -- @property current_widget_geometries --- @tparam ?table A list of geometry tables. +-- @tparam[opt=nil] table|nil current_widget_geometries A list of geometry tables. +-- @propertytype nil When there is no widgets. +-- @propertytype table A list of geometry tables. +-- @tablerowkey x integer +-- @tablerowkey y integer +-- @tablerowkey width integer +-- @tablerowkey height integer -- @see current_widgets function mouse.object.get_current_widget_geometries() @@ -193,6 +215,7 @@ end --- Move the wibox under the cursor. -- @staticfct awful.mouse.wibox.move -- @tparam wibox w The wibox to move, or none to use that under the pointer +-- @noreturn -- @request wibox geometry mouse.move granted Requests to move the wibox. function mouse.wibox.move(w) w = w or mouse.current_wibox @@ -222,15 +245,15 @@ end --- True if the left mouse button is pressed. -- @property is_left_mouse_button_pressed --- @param boolean +-- @tparam[opt=false] boolean is_left_mouse_button_pressed --- True if the right mouse button is pressed. -- @property is_right_mouse_button_pressed --- @param boolean +-- @tparam[opt=false] boolean is_right_mouse_button_pressed --- True if the middle mouse button is pressed. -- @property is_middle_mouse_button_pressed --- @param boolean +-- @tparam[opt=false] boolean is_middle_mouse_button_pressed --- Add an `awful.button` based mousebinding to the global set. -- @@ -240,6 +263,7 @@ end -- -- @staticfct awful.mouse.append_global_mousebinding -- @tparam awful.button button The button object. +-- @noreturn -- @see awful.button function mouse.append_global_mousebinding(button) @@ -252,9 +276,11 @@ end -- no focused client. If your intent is too add a mousebinding which acts on -- the focused client do **not** use this -- +-- @staticfct awful.mouse.append_global_mousebindings -- @tparam table buttons A table of `awful.button` objects. Optionally, it can have -- a `group` entry. If set, the `group` property will be set on all `awful.buttons` -- objects. +-- @noreturn -- @see awful.button function mouse.append_global_mousebindings(buttons) @@ -277,6 +303,7 @@ end -- -- @staticfct awful.mouse.remove_global_mousebinding -- @tparam awful.button button The button object. +-- @noreturn -- @see awful.button function mouse.remove_global_mousebinding(button) @@ -289,6 +316,7 @@ local default_buttons = {} -- -- @staticfct awful.mouse.append_client_mousebinding -- @tparam awful.button button The button. +-- @noreturn -- @emits client_mousebinding::added -- @emitstparam client_mousebinding::added awful.button button The button. -- @see awful.button @@ -308,6 +336,7 @@ end -- -- @staticfct awful.mouse.append_client_mousebindings -- @tparam table buttons A table containing `awful.button` objects. +-- @noreturn -- @see awful.button -- @see awful.keyboard.append_client_keybinding -- @see awful.mouse.append_client_mousebinding @@ -387,11 +416,13 @@ end) -- @tparam[opt=nil] integer coords_table.y The mouse vertical position -- @tparam[opt=false] boolean silent Disable mouse::enter or mouse::leave events that -- could be triggered by the pointer when moving. --- @treturn integer table.x The horizontal position --- @treturn integer table.y The vertical position --- @treturn table table.buttons Table containing the status of buttons, e.g. field [1] is true --- when button 1 is pressed. +-- @treturn table The coords. It contains the `x`, `y` and `buttons` keys. +-- `buttons` contains the button number as key and a boolean as value (if it is +-- pressed). -- @staticfct mouse.coords +-- @see is_left_mouse_button_pressed +-- @see is_right_mouse_button_pressed +-- @see is_middle_mouse_button_pressed capi.client.connect_signal("scanning", function() capi.client.emit_signal("request::default_mousebindings", "startup") diff --git a/lib/awful/mouse/resize.lua b/lib/awful/mouse/resize.lua index 7d6b7e349..e1ca82281 100644 --- a/lib/awful/mouse/resize.lua +++ b/lib/awful/mouse/resize.lua @@ -33,14 +33,6 @@ local cursors = { ["mouse.resize_bottom_right"] = "bottom_right_corner", } ---- The resize cursor name. --- @beautiful beautiful.cursor_mouse_resize --- @tparam[opt=cross] string cursor - ---- The move cursor name. --- @beautiful beautiful.cursor_mouse_move --- @tparam[opt=fleur] string cursor - --- Set the resize mode. -- The available modes are: -- @@ -60,7 +52,7 @@ end -- This callback will be executed before the mouse grabbing starts. -- @function awful.mouse.resize.add_enter_callback -- @tparam function cb The callback (or nil) --- @tparam[default=other] string context The callback context +-- @tparam[opt="other"] string context The callback context function module.add_enter_callback(cb, context) context = context or "other" callbacks.enter[context] = callbacks.enter[context] or {} @@ -72,7 +64,7 @@ end -- applying the operation. -- @function awful.mouse.resize.add_move_callback -- @tparam function cb The callback (or nil) --- @tparam[default=other] string context The callback context +-- @tparam[opt="other"] string context The callback context function module.add_move_callback(cb, context) context = context or "other" callbacks.move[context] = callbacks.move[context] or {} @@ -83,7 +75,7 @@ end -- This callback is executed just before the `mousegrabber` stop -- @function awful.mouse.resize.add_leave_callback -- @tparam function cb The callback (or nil) --- @tparam[default=other] string context The callback context +-- @tparam[opt="other"] string context The callback context function module.add_leave_callback(cb, context) context = context or "other" callbacks.leave[context] = callbacks.leave[context] or {} @@ -101,9 +93,11 @@ end -- -- @function awful.mouse.resize -- @tparam client client A client. --- @tparam[default=mouse.resize] string context The resizing context. +-- @tparam[opt=mouse.resize] string context The resizing context. -- @tparam[opt={}] table args A set of `awful.placement` arguments. -- @request wibox geometry mouse.resize granted Requests to resize the wibox. +-- @usebeautiful beautiful.cursor_mouse_move +-- @usebeautiful beautiful.cursor_mouse_resize local function handler(_, client, context, args) --luacheck: no unused_args args = args or {} context = context or "mouse.resize" diff --git a/lib/awful/mouse/snap.lua b/lib/awful/mouse/snap.lua index 592bc3b4a..0b7a05fad 100644 --- a/lib/awful/mouse/snap.lua +++ b/lib/awful/mouse/snap.lua @@ -191,13 +191,19 @@ local function snap_inside(g, sg, snap) end --- Snap a client to the closest client or screen edge. +-- -- @function awful.mouse.snap --- @param c The client to snap. --- @param snap The pixel to snap clients. --- @param x The client x coordinate. --- @param y The client y coordinate. --- @param fixed_x True if the client isn't allowed to move in the x direction. --- @param fixed_y True if the client isn't allowed to move in the y direction. +-- @tparam[opt=client.focus] client c The client to snap. +-- @tparam integer snap The pixel to snap clients. +-- @tparam integer x The client x coordinate. +-- @tparam integer y The client y coordinate. +-- @tparam boolean fixed_x True if the client isn't allowed to move in the x direction. +-- @tparam boolean fixed_y True if the client isn't allowed to move in the y direction. +-- @treturn table The new geometry. +-- @usebeautiful beautiful.snap_bg +-- @usebeautiful beautiful.snap_border_width +-- @usebeautiful beautiful.snap_shape +-- @usebeautiful beautiful.snapper_gap function module.snap(c, snap, x, y, fixed_x, fixed_y) snap = snap or module.default_distance c = c or capi.client.focus diff --git a/lib/awful/permissions/init.lua b/lib/awful/permissions/init.lua index 64673d3f7..9c5be3a79 100644 --- a/lib/awful/permissions/init.lua +++ b/lib/awful/permissions/init.lua @@ -1,5 +1,19 @@ --------------------------------------------------------------------------- ---- Implements EWMH requests handling. +--- Default implementation of the various requests handers. +-- +-- AwesomeWM has many `request::` signals across the core APIs. They help +-- decouple the default behavior from the core API. The request handlers +-- can be disconnected and replaced by module or `rc.lua` to alter +-- AwesomeWM behavior. +-- +-- This module provides the default implementation of those request handlers. +-- Beside some legacy signals, most request handlers have a main object, a +-- named context and a table containing any low-level hints the core code is +-- aware of. Each default handler implement a context based filter mechanism. +-- This filter is called the "permissions". It allows requests to be denied. +-- For example, if a tiled client asks to be resized or moved, the permission +-- and deny it. In the documentation, many objects and properties have a +-- "permissions" section you can display by clicking "show more". -- -- @author Julien Danjou <julien@danjou.info> -- @copyright 2009 Julien Danjou @@ -38,18 +52,18 @@ local permissions = { -- @beautiful beautiful.maximized_hide_border -- @tparam[opt=false] boolean maximized_hide_border ---- The list of all registered generic request::activate (focus stealing) +--- The list of all registered generic `request::activate` (focus stealing) -- filters. If a filter is added to only one context, it will be in -- `permissions.contextual_activate_filters`["context_name"]. --- @table[opt={}] generic_activate_filters +-- @table[opt={}] awful.permissions.generic_activate_filters -- @see permissions.activate -- @see permissions.add_activate_filter -- @see permissions.remove_activate_filter ---- The list of all registered contextual request::activate (focus stealing) +--- The list of all registered contextual `request::activate` (focus stealing) -- filters. If a filter is added to only one context, it will be in -- `permissions.generic_activate_filters`. --- @table[opt={}] contextual_activate_filters +-- @table[opt={}] awful.permissions.contextual_activate_filters -- @see permissions.activate -- @see permissions.add_activate_filter -- @see permissions.remove_activate_filter @@ -143,12 +157,13 @@ end -- @tparam client c A client to use -- @tparam string context The context where this signal was used. -- @tparam[opt] table hints A table with additional hints: --- @tparam[opt=false] boolean hints.raise should the client be unminimized +-- @tparam[opt=false] boolean hints.raise Should the client be unminimized -- and raised? --- @tparam[opt=false] boolean hints.switch_to_tag should the client's first tag +-- @tparam[opt=false] boolean hints.switch_to_tag Should the client's first tag -- be selected if none of the client's tags are selected? -- @tparam[opt=false] boolean hints.switch_to_tags Select all tags associated -- with the client. +-- @sourcesignal client request::activate function permissions.activate(c, context, hints) -- luacheck: no unused args if not pcommon.check(c, "client", "activate", context) then return end @@ -226,6 +241,7 @@ end -- -- @tparam function f The callback -- @tparam[opt] string context The `request::activate` context +-- @noreturn -- @see generic_activate_filters -- @see contextual_activate_filters -- @see remove_activate_filter @@ -288,8 +304,10 @@ end -- -- @signalhandler awful.permissions.tag -- @tparam client c A client to tag --- @tparam[opt] tag|boolean t A tag to use. If true, then the client is made sticky. --- @tparam[opt={}] table hints Extra information +-- @tparam[opt] tag|boolean t A tag to use. If `true`, then the client is made `sticky`. +-- @tparam[opt={}] table hints Extra information. +-- @tparam[opt=nil] nil|string hints.reason Why the tag is being changed. +-- @sourcesignal client request::tag function permissions.tag(c, t, hints) --luacheck: no unused -- There is nothing to do if not t and #get_valid_tags(c, c.screen) > 0 then return end @@ -316,6 +334,7 @@ end -- @signalhandler awful.permissions.urgent -- @tparam client c A client -- @tparam boolean urgent If the client should be urgent +-- @sourcesignal client request::urgent function permissions.urgent(c, urgent) if c ~= client.focus and not aclient.property.get(c,"ignore_urgent") then c.urgent = urgent @@ -338,6 +357,11 @@ local context_mapper = { -- @tparam client c The client -- @tparam string context The context -- @tparam[opt={}] table hints The hints to pass to the handler +-- @tparam[opt=true] boolean hints.store_geometry Create a memento of the +-- previous geometry in case it has to be restored. +-- @tparam[opt=true] boolean hints.honor_workarea Avoid overlapping the `wibar`s +-- or other desktop decoration when applying the geometry. +-- @sourcesignal client request::geometry function permissions.geometry(c, context, hints) if not pcommon.check(c, "client", "geometry", context) then return end @@ -407,6 +431,11 @@ end -- @tparam wibox w The wibox. -- @tparam string context The context -- @tparam[opt={}] table hints The hints to pass to the handler +-- @tparam[opt] integer hints.x The horizontal position. +-- @tparam[opt] integer hints.y The vertical position. +-- @tparam[opt] integer hints.width The wibox width. +-- @tparam[opt] integer hints.height The wibox height. +-- @sourcesignal client request::geometry function permissions.wibox_geometry(w, context, hints) if not pcommon.check(w, "wibox", "geometry", context) then return end @@ -416,14 +445,17 @@ end --- Merge the 2 requests sent by clients wanting to be maximized. -- -- The X clients set 2 flags (atoms) when they want to be maximized. This caused --- 2 request::geometry to be sent. This code gives some time for them to arrive +-- 2 `request::geometry` to be sent. This code gives some time for them to arrive -- and send a new `request::geometry` (through the property change) with the -- combined state. -- -- @signalhandler awful.permissions.merge_maximization -- @tparam client c The client -- @tparam string context The context --- @tparam[opt={}] table hints The hints to pass to the handler +-- @tparam[opt={}] table hints The hints to pass to the handler. +-- @tparam[opt=false] boolean hints.toggle Toggle the maximization state rather +-- than set it to `true`. +-- @sourcesignal client request::geometry function permissions.merge_maximization(c, context, hints) if not pcommon.check(c, "client", "geometry", context) then return end @@ -506,7 +538,12 @@ end -- @signalhandler awful.permissions.client_geometry_requests -- @tparam client c The client -- @tparam string context The context --- @tparam[opt={}] table hints The hints to pass to the handler +-- @tparam[opt={}] table hints The hints to pass to the handler. +-- @tparam[opt] integer hints.x The horizontal position. +-- @tparam[opt] integer hints.y The vertical position. +-- @tparam[opt] integer hints.width The client width. +-- @tparam[opt] integer hints.height The client height. +-- @sourcesignal client request::geometry function permissions.client_geometry_requests(c, context, hints) if not pcommon.check(c, "client", "geometry", context) then return end @@ -539,13 +576,16 @@ end, "mouse_enter") -- -- To replace this handler with your own, use: -- --- client.disconnect_signal("request::border", awful.ewmh.update_border) +-- client.disconnect_signal("request::border", awful.permisions.update_border) -- -- The default implementation chooses from dozens beautiful theme variables -- depending if the client is tiled, floating, maximized and then from its state -- (urgent, new, active, normal) -- -- @signalhandler awful.permissions.update_border +-- @tparam client c The client. +-- @tparam string context Why is the border changed. +-- @sourcesignal client request::border -- @usebeautiful beautiful.border_color_marked -- @usebeautiful beautiful.border_color_active -- @usebeautiful beautiful.border_color_normal @@ -604,6 +644,8 @@ end, "mouse_enter") -- @usebeautiful beautiful.opacity_normal -- @usebeautiful beautiful.opacity_new -- @usebeautiful beautiful.opacity_urgent +-- @see client.border_width +-- @see client.border_color function permissions.update_border(c, context) if not pcommon.check(c, "client", "border", context) then return end @@ -729,6 +771,12 @@ local activate_context_map = { -- * history : *autofocus.check_focus* -- -- @signalhandler awful.permissions.autoactivate +-- @tparam client c The client. +-- @tparam string context Why is the client auto-activated. +-- @tparam[opt={}] table hints Extra arguments. +-- @sourcesignal client request::activated +-- @see activate +-- @see client:activate function permissions.autoactivate(c, context, args) if not pcommon.check(c, "client", "autoactivate", context) then return end diff --git a/lib/awful/popup.lua b/lib/awful/popup.lua index 22d8d76ee..71ca6a6a1 100644 --- a/lib/awful/popup.lua +++ b/lib/awful/popup.lua @@ -145,13 +145,6 @@ local popup = {} -- parent menu. If there is no space on the right, it tries on the left and so -- on. -- --- Valid directions are: --- --- * left --- * right --- * top --- * bottom --- -- The basic use case for this method is to give it a parent wibox: -- -- @DOC_awful_popup_position1_EXAMPLE@ @@ -162,8 +155,16 @@ local popup = {} -- @DOC_awful_popup_position2_EXAMPLE@ -- -- @property preferred_positions --- @tparam table|string preferred_positions A position name or an ordered --- table of positions +-- @tparam table|string preferred_positions +-- @propertydefault `{ "right", "left", "top", "bottom" }` +-- @propertytype string A single position with no fallback. It will be used +-- even if it doesn't fit. +-- @propertytype table A list of possible positions. The first one to fit will be +-- used. +-- @propertyvalue "left" +-- @propertyvalue "right" +-- @propertyvalue "top" +-- @propertyvalue "bottom" -- @see awful.placement.next_to -- @see awful.popup.preferred_anchors -- @propemits true false @@ -176,12 +177,6 @@ end --- Set the preferred popup anchors relative to the parent. -- --- The possible values are: --- --- * front --- * middle --- * back --- -- For details information, see the `awful.placement.next_to` documentation. -- -- In this example, it is possible to see the effect of having a fallback @@ -190,8 +185,14 @@ end -- @DOC_awful_popup_anchors_EXAMPLE@ -- -- @property preferred_anchors --- @tparam table|string preferred_anchors Either a single anchor name or a table +-- @tparam[opt="back"] table|string preferred_anchors -- ordered by priority. +-- @propertytype string A single anchor value with no fallback. +-- @propertytype table A list of possible anchor, the first one has the higher +-- priority, but will fallback if it doesn't fit. +-- @propertyvalue "front" +-- @propertyvalue "middle" +-- @propertyvalue "back" -- @propemits true false -- @see awful.placement.next_to -- @see awful.popup.preferred_positions @@ -210,7 +211,14 @@ end -- isn't enough space, it can also be one of the fallback. -- -- @property current_position --- @tparam string current_position Either "left", "right", "top" or "bottom" +-- @tparam string current_position +-- @propertydefault This depends on where the popup was displayed. +-- @propertyvalue "left" +-- @propertyvalue "right" +-- @propertyvalue "top" +-- @propertyvalue "bottom" +-- @readonly +-- @see awful.popup.preferred_positions function popup:get_current_position() return self._private.current_position @@ -224,7 +232,13 @@ end -- opposite direction from the anchor. -- -- @property current_anchor --- @tparam string current_anchor Either "front", "middle", "back" +-- @tparam string current_anchor +-- @propertydefault This depends on where the popup was displayed. +-- @propertyvalue "front" +-- @propertyvalue "middle" +-- @propertyvalue "back" +-- @readonly +-- @see awful.popup.preferred_anchors function popup:get_current_anchor() return self._private.current_anchor @@ -264,6 +278,7 @@ end -- @tparam widget widget The widget -- @tparam[opt=1] number button The button index -- @method bind_to_widget +-- @noreturn function popup:bind_to_widget(widget, button) if not self._private.button_for_widget then self._private.button_for_widget = {} @@ -274,8 +289,10 @@ function popup:bind_to_widget(widget, button) end --- Unbind the popup from a widget button. --- @tparam widget widget The widget +-- @tparam widget widget +-- @propertytype widget A widget or declarative widget construct. -- @method unbind_to_widget +-- @noreturn function popup:unbind_to_widget(widget) widget:disconnect_signal("button::press", self._private.show_fct) end @@ -296,25 +313,33 @@ end --- The popup minimum width. -- -- @property minimum_width --- @tparam[opt=1] number minimum_width The minimum width. +-- @tparam[opt=1] integer minimum_width +-- @propertyunit pixel +-- @rangestart 1 -- @propemits true false --- The popup minimum height. -- -- @property minimum_height --- @tparam[opt=1] number minimum_height The minimum height. +-- @tparam[opt=1] integer minimum_height +-- @propertyunit pixel +-- @rangestart 1 -- @propemits true false --- The popup maximum width. -- -- @property maximum_width --- @tparam[opt=1] number maximum_width The maximum width. +-- @tparam[opt=1] integer maximum_width +-- @propertyunit pixel +-- @rangestart 1 -- @propemits true false --- The popup maximum height. -- -- @property maximum_height --- @tparam[opt=1] number maximum_height The maximum height. +-- @tparam[opt=1] integer maximum_height +-- @propertyunit pixel +-- @rangestart 1 -- @propemits true false for _, orientation in ipairs {"_width", "_height"} do @@ -338,9 +363,13 @@ end -- -- @DOC_awful_popup_position3_EXAMPLE@ -- @property offset --- @tparam table|number offset An integer value or a `{x=, y=}` table. --- @tparam[opt=offset] number offset.x The horizontal distance. --- @tparam[opt=offset] number offset.y The vertical distance. +-- @tparam[opt=0] table|integer offset +-- @tparam[opt=0] integer offset.x The horizontal offset. +-- @tparam[opt=0] integer offset.y The vertical offset. +-- @propertytype integer A value for both `x` and `y` simultaneously. +-- @propertytype table Specify values for `x` and `y` individually. +-- @negativeallowed true +-- @propertyunit pixel -- @propemits true false function popup:set_offset(offset) @@ -367,10 +396,10 @@ end --- Set the placement function. -- --- @tparam[opt=next_to] function|string|boolean The placement function or name --- (or false to disable placement) -- @property placement --- @param function +-- @tparam[opt=awful.placement.next_to] placement|string|boolean placement +-- @propertytype boolean Use `false` to disable automatic placement. +-- @propertytype string The name of an `awful.placement` function, like `"next_to"`. -- @propemits true false -- @see awful.placement @@ -494,6 +523,4 @@ local function create_popup(_, args) return w end ---@DOC_wibox_COMMON@ - return setmetatable(module, {__call = create_popup}) diff --git a/lib/awful/prompt.lua b/lib/awful/prompt.lua index d559ca70e..52b4f34e8 100644 --- a/lib/awful/prompt.lua +++ b/lib/awful/prompt.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Prompt module for awful. +--- Convert a `wibox.widget.textbox` into an input prompt. -- -- **Keyboard navigation**: -- @@ -444,23 +444,24 @@ end -- return command -- end} -- } --- @param textbox The textbox to use for the prompt. [**DEPRECATED**] --- @param exe_callback The callback function to call with command as argument +-- @tparam wibox.widget.textbox textbox The textbox to use for the prompt. [**DEPRECATED**] +-- @tparam[opt] function|nil exe_callback The callback function to call with command as argument -- when finished. [**DEPRECATED**] --- @param completion_callback The callback function to call to get completion. +-- @tparam[opt] function completion_callback The callback function to call to get completion. -- [**DEPRECATED**] --- @param[opt] history_path File path where the history should be +-- @tparam[opt] string history_path File path where the history should be -- saved, set nil to disable history [**DEPRECATED**] --- @param[opt] history_max Set the maximum entries in history +-- @tparam[opt] number history_max Set the maximum entries in history -- file, 50 by default [**DEPRECATED**] --- @param[opt] done_callback The callback function to always call +-- @tparam[opt] function done_callback The callback function to always call -- without arguments, regardless of whether the prompt was cancelled. -- [**DEPRECATED**] --- @param[opt] changed_callback The callback function to call +-- @tparam[opt] function changed_callback The callback function to call -- with command as argument when a command was changed. [**DEPRECATED**] --- @param[opt] keypressed_callback The callback function to call +-- @tparam[opt] function keypressed_callback The callback function to call -- with mod table, key and command as arguments when a key was pressed. -- [**DEPRECATED**] +-- @noreturn -- @see gears.color -- @staticfct awful.prompt.run function prompt.run(args, textbox, exe_callback, completion_callback, diff --git a/lib/awful/screen.lua b/lib/awful/screen.lua index a73675828..e846cda61 100644 --- a/lib/awful/screen.lua +++ b/lib/awful/screen.lua @@ -49,10 +49,10 @@ end --- Get the square distance between a `screen` and a point. -- @deprecated awful.screen.getdistance_sq --- @param s Screen --- @param x X coordinate of point --- @param y Y coordinate of point --- @return The squared distance of the screen to the provided point. +-- @tparam screen s Screen +-- @tparam integer x X coordinate of point +-- @tparam integer y Y coordinate of point +-- @treturn number The squared distance of the screen to the provided point. -- @see screen.get_square_distance function screen.getdistance_sq(s, x, y) gdebug.deprecate("Use s:get_square_distance(x, y) instead of awful.screen.getdistance_sq", {deprecated_in=4}) @@ -90,7 +90,8 @@ end -- This moves the mouse pointer to the last known position on the new screen, -- or keeps its position relative to the current focused screen. -- @staticfct awful.screen.focus --- @tparam screen _screen Screen number (defaults / falls back to mouse.screen). +-- @tparam screen screen Screen number (defaults / falls back to mouse.screen). +-- @treturn screen The newly focused screen. -- @request client activate screen.focus granted The most recent focused client -- for this screen should be re-activated. function screen.focus(_screen) @@ -126,6 +127,8 @@ function screen.focus(_screen) if c then c:emit_signal("request::activate", "screen.focus", {raise=false}) end + + return _screen end --- Get the next screen in a specific direction. @@ -134,8 +137,8 @@ end -- the specified direction. -- -- @method get_next_in_direction --- @param self Screen. --- @param dir The direction, can be either "up", "down", "left" or "right". +-- @tparam string dir The direction, can be either "up", "down", "left" or "right". +-- @treturn screen The next screen. function screen.object.get_next_in_direction(self, dir) local sel = get_screen(self) if not sel then @@ -156,7 +159,8 @@ end -- or keeps its position relative to the current focused screen. -- @staticfct awful.screen.focus_bydirection -- @tparam string dir The direction, can be either "up", "down", "left" or "right". --- @tparam screen s Screen. +-- @tparam[opt=awful.screen.focused()] screen s Screen. +-- @treturn screen The next screen. function screen.focus_bydirection(dir, s) local sel = get_screen(s or screen.focused()) local target = sel:get_next_in_direction(dir) @@ -174,6 +178,7 @@ end -- @staticfct awful.screen.focus_relative -- @tparam int offset Value to add to the current focused screen index. 1 to -- focus the next one, -1 to focus the previous one. +-- @treturn screen The newly focusd screen. function screen.focus_relative(offset) return screen.focus(gmath.cycle(capi.screen.count(), screen.focused().index + offset)) @@ -193,6 +198,8 @@ end -- @tparam number tiling_area.y -- @tparam number tiling_area.width -- @tparam number tiling_area.height +-- @propertydefault This is the `workarea` substracted with the `padding` area. +-- @propertyunit pixel -- @readonly -- @see padding -- @see get_bounding_geometry @@ -209,8 +216,13 @@ end -- Reading this property returns a screenshot of the physical -- (Xinerama) screen as a cairo surface. -- +-- Use `gears.surface(c.content)` to convert the raw content into a static image. +-- -- @property content --- @tparam gears.surface content +-- @tparam raw_surface content +-- @propertydefault The client raw pixels at the time the property is called. +-- If there is no compositing manager running, it might be black. +-- @see gears.surface -- @readonly function screen.object.get_content(s) @@ -228,8 +240,8 @@ end --- Get or set the screen padding. -- -- @deprecated awful.screen.padding --- @param s The screen object to change the padding on --- @param[opt=nil] padding The padding, a table with 'top', 'left', 'right' and/or +-- @tparam screen s The screen object to change the padding on. +-- @tparam[opt=nil] table|integer|nil padding The padding, a table with 'top', 'left', 'right' and/or -- 'bottom' or a number value to apply set the same padding on all sides. Can be -- nil if you only want to retrieve padding -- @treturn table A table with left, right, top and bottom number values. @@ -246,18 +258,19 @@ end -- -- This adds a "buffer" section on each side of the screen. -- --- **Signal:** --- --- * *property::padding* --- -- @DOC_screen_padding_EXAMPLE@ -- -- @property padding --- @param table --- @tfield integer table.left The padding on the left. --- @tfield integer table.right The padding on the right. --- @tfield integer table.top The padding on the top. --- @tfield integer table.bottom The padding on the bottom. +-- @tparam[opt=0] table|number padding +-- @tparam[opt=0] integer padding.left The padding on the left. +-- @tparam[opt=0] integer padding.right The padding on the right. +-- @tparam[opt=0] integer padding.top The padding on the top. +-- @tparam[opt=0] integer padding.bottom The padding on the bottom. +-- @negativeallowed false +-- @propertyunit pixel +-- @propertytype number A single value for each sides. +-- @propertytype table A different value for each sides. +-- @propemits true false -- @usebeautiful beautiful.maximized_honor_padding Honor the screen padding when maximizing. function screen.object.get_padding(self) @@ -299,18 +312,18 @@ end -- -- do something -- end -- --- **Signal:** --- --- * *property::outputs* --- -- @property outputs --- @param table --- @tfield table table.name A table with the screen name as key (like `eDP1` on a laptop) --- @tfield integer table.mm_width The screen physical width. --- @tfield integer table.mm_height The screen physical height. --- @tfield integer table.name The output name. --- @tfield integer table.viewport_id The identifier of the viewport this output +-- @tparam table outputs +-- @tablerowtype A key-value table with the output name as key and a table of +-- metadata as value. +-- @tablerowkey integer mm_width The screen physical width. +-- @tablerowkey integer mm_height The screen physical height. +-- @tablerowkey string name The output name. +-- @tablerowkey string viewport_id The identifier of the viewport this output -- corresponds to. +-- @propertydefault This may or may not be populated if the screen are based on +-- an actual physical screen. For fake screen, this property content is undefined. +-- @propemits true false -- @readonly function screen.object.get_outputs(s) @@ -379,7 +392,7 @@ end -- -- This method computes the different variants of the "usable" screen geometry. -- --- @staticfct screen.get_bounding_geometry +-- @method screen.get_bounding_geometry -- @tparam[opt={}] table args The arguments -- @tparam[opt=false] boolean args.honor_padding Whether to honor the screen's padding. -- @tparam[opt=false] boolean args.honor_workarea Whether to honor the screen's workarea. @@ -439,7 +452,8 @@ end -- default. -- -- @property clients --- @param table The clients list, ordered from top to bottom. +-- @tparam[opt={}] table clients The clients list, ordered from top to bottom. +-- @tablerowtype A list of `client` objects. -- @see all_clients -- @see hidden_clients -- @see client.get @@ -467,7 +481,8 @@ end -- This includes minimized clients and clients on hidden tags. -- -- @property hidden_clients --- @param table The clients list, ordered from top to bottom. +-- @tparam[opt={}] table hidden_clients The clients list, ordered from top to bottom. +-- @tablerowtype A list of `client` objects. -- @see clients -- @see all_clients -- @see client.get @@ -486,7 +501,8 @@ end --- All clients assigned to the screen. -- -- @property all_clients --- @param table The clients list, ordered from top to bottom. +-- @tparam[opt={}] table all_clients The clients list, ordered from top to bottom. +-- @tablerowtype A list of `client` objects. -- @see clients -- @see hidden_clients -- @see client.get @@ -513,7 +529,8 @@ end -- @DOC_screen_tiled_clients_EXAMPLE@ -- -- @property tiled_clients --- @param table The clients list, ordered from top to bottom. +-- @tparam[opt={}] table tiled_clients The clients list, ordered from top to bottom. +-- @tablerowtype A list of `client` objects. --- Get tiled clients for the screen. -- @@ -541,6 +558,7 @@ end -- @staticfct awful.screen.connect_for_each_screen -- @tparam function func The function to call. -- @tparam screen func.screen The screen. +-- @noreturn function screen.connect_for_each_screen(func) for s in capi.screen do func(s) @@ -548,9 +566,10 @@ function screen.connect_for_each_screen(func) capi.screen.connect_signal("added", func) end ---- Undo the effect of connect_for_each_screen. +--- Undo the effect of `awful.screen.connect_for_each_screen`. -- @staticfct awful.screen.disconnect_for_each_screen -- @tparam function func The function that should no longer be called. +-- @noreturn function screen.disconnect_for_each_screen(func) capi.screen.disconnect_signal("added", func) end @@ -561,8 +580,8 @@ end -- `awful.tag.new` or `t:delete()` to alter this list. -- -- @property tags --- @param table --- @treturn table A table with all available tags. +-- @tparam[opt={}] table tags +-- @tablerowtype A table with all available tags. -- @readonly function screen.object.get_tags(s, unordered) @@ -585,8 +604,8 @@ end --- A list of all selected tags on the screen. -- @property selected_tags --- @param table --- @treturn table A table with all selected tags. +-- @tparam[opt={}] table selected_tags +-- @tablerowtype A table with all selected tags. -- @readonly -- @see tag.selected -- @see client.to_selected_tags @@ -605,8 +624,7 @@ end --- The first selected tag. -- @property selected_tag --- @param tag --- @treturn ?tag The first selected tag or nil. +-- @tparam[opt=nil] tag|nil selected_tag -- @readonly -- @see tag.selected -- @see selected_tags @@ -651,10 +669,14 @@ end -- -- @DOC_awful_screen_split2_EXAMPLE@ -- --- @tparam[opt] table ratios The different ratios to split into. If none is --- provided, it is split in half. +-- @tparam[opt={50﹐50}] table ratios The different ratios to split into. If none +-- is provided, it is split in half. -- @tparam[opt] string mode Either "vertical" or "horizontal". If none is -- specified, it will split along the longest axis. +-- @treturn table A table with the screen objects. The first value is the +-- original screen object (`s`) and the following one(s) are the new screen +-- objects. The values are ordered from left to right or top to bottom depending +-- on the value of `mode`. -- @method split function screen.object.split(s, ratios, mode, _geo) s = get_screen(s) @@ -736,6 +758,7 @@ end -- defaulting to 96. -- -- @tparam boolean enabled Enable or disable automatic DPI support. +-- @noreturn -- @staticfct awful.screen.set_auto_dpi_enabled function screen.set_auto_dpi_enabled(enabled) for s in capi.screen do @@ -753,16 +776,24 @@ end -- screen is duplicated on a projector). -- -- @property dpi --- @param number the DPI value. +-- @tparam[opt=96] number dpi +-- @propertyunit pixel\_per\_inch +-- @negativeallowed false --- The lowest density DPI from all of the (physical) outputs. -- @property minimum_dpi --- @param number the DPI value. +-- @tparam number minimum_dpi +-- @propertyunit pixel\_per\_inch +-- @propertydefault This is extracted from `outputs`. +-- @negativeallowed false -- @readonly --- The highest density DPI from all of the (physical) outputs. -- @property maximum_dpi --- @param number the DPI value. +-- @tparam number maximum_dpi +-- @propertydefault This is extracted from `outputs`. +-- @propertyunit pixel\_per\_inch +-- @negativeallowed false -- @readonly --- The preferred DPI from all of the (physical) outputs. @@ -771,28 +802,42 @@ end -- the lowest of the resulting virtual DPIs. -- -- @property preferred_dpi --- @param number the DPI value. +-- @tparam number preferred_dpi +-- @propertydefault This is extracted from `outputs`. +-- @negativeallowed false -- @readonly --- The maximum diagonal size in millimeters. -- -- @property mm_maximum_size --- @param number +-- @tparam number mm_maximum_size +-- @propertydefault This is extracted from `outputs`. +-- @propertyunit millimeter +-- @negativeallowed false --- The minimum diagonal size in millimeters. -- -- @property mm_minimum_size --- @param number +-- @tparam number mm_minimum_size +-- @propertydefault This is extracted from `outputs`. +-- @propertyunit millimeter +-- @negativeallowed false --- The maximum diagonal size in inches. -- -- @property inch_maximum_size --- @param number +-- @tparam number inch_maximum_size +-- @propertydefault This is extracted from `outputs`. +-- @propertyunit inch +-- @negativeallowed false --- The minimum diagonal size in inches. -- -- @property inch_minimum_size --- @param number +-- @tparam number inch_minimum_size +-- @propertydefault This is extracted from `outputs`. +-- @propertyunit inch +-- @negativeallowed false --- Emitted when a new screen is added. -- @@ -952,6 +997,8 @@ end -- `request::remove` and `request::resize`. -- -- @signalhandler awful.screen.create_screen_handler +-- @tparam table viewport +-- @sourcesignal screen request::create -- @see request::create --- Default handler for `request::remove`. @@ -971,6 +1018,8 @@ end -- end -- -- @signalhandler awful.screen.remove_screen_handler +-- @tparam table viewport +-- @sourcesignal screen request::remove -- @see request::remove --- Default handler for `request::resize`. @@ -992,6 +1041,8 @@ end -- end -- -- @signalhandler awful.screen.resize_screen_handler +-- @tparam table viewport +-- @sourcesignal screen request::resize -- @see request::resize -- Add the DPI properties. diff --git a/lib/awful/spawn.lua b/lib/awful/spawn.lua index ecada47b9..7d3e94508 100644 --- a/lib/awful/spawn.lua +++ b/lib/awful/spawn.lua @@ -1,7 +1,7 @@ --luacheck: no max line length --------------------------------------------------------------------------- ---- Spawning of programs. +--- Spawn sub-processes and optionally get their output. -- -- This module provides methods to start programs and supports startup -- notifications, which allows for callbacks and applying properties to the @@ -364,6 +364,10 @@ end --- Spawn a program using the shell. -- This calls `cmd` with `$SHELL -c` (via `awful.util.shell`). -- @tparam string cmd The command. +-- @treturn[1] integer The forked PID. +-- @treturn[1] ?string The startup notification ID, if `sn` is not false, or +-- a `callback` is provided. +-- @treturn[2] string Error message. -- @staticfct awful.spawn.with_shell function spawn.with_shell(cmd) if cmd and cmd ~= "" then @@ -500,6 +504,7 @@ end -- @tparam[opt] function done_callback Function that is called when the -- operation finishes (e.g. due to end of file). -- @tparam[opt=false] boolean close Should the stream be closed after end-of-file? +-- @noreturn -- @staticfct awful.spawn.read_lines function spawn.read_lines(input_stream, line_callback, done_callback, close) local stream = Gio.DataInputStream.new(input_stream) @@ -649,8 +654,9 @@ end -- @tparam[opt] string unique_id A string to identify the client so it isn't executed -- multiple time. -- @tparam[opt] function callback A callback function when the client is created. --- @see ruled.client +-- @noreturn -- @staticfct awful.spawn.once +-- @see ruled.client function spawn.once(cmd, rules, matcher, unique_id, callback) local hash = unique_id or hash_command(cmd, rules) local status = register_common(hash, rules, matcher, callback) @@ -682,8 +688,9 @@ end -- @tparam[opt] string unique_id A string to identify the client so it isn't executed -- multiple time. -- @tparam[opt] function callback A callback function when the client is created. --- @see ruled.client +-- @noreturn -- @staticfct awful.spawn.single_instance +-- @see ruled.client function spawn.single_instance(cmd, rules, matcher, unique_id, callback) local hash = unique_id or hash_command(cmd, rules) register_common(hash, rules, matcher, callback) diff --git a/lib/awful/tag.lua b/lib/awful/tag.lua index 7bd7a008b..662ecfacd 100644 --- a/lib/awful/tag.lua +++ b/lib/awful/tag.lua @@ -149,6 +149,8 @@ end -- -- @property index -- @tparam integer index +-- @propertydefault This is based on the current list of `t.screen:tags()`. +-- @negativeallowed false -- @propemits false false function tag.object.set_index(self, idx) @@ -203,11 +205,10 @@ function tag.object.get_index(query_tag) end end ---- Move a tag to an absolute position in the screen[]:tags() table. +--- Move a tag to an absolute position in the `screen[]:tags()` table. -- @deprecated awful.tag.move --- @param new_index Integer absolute position in the table to insert. --- @param target_tag The tag that should be moved. If null, the currently --- selected tag is used. +-- @tparam integer new_index Integer absolute position in the table to insert. +-- @tparam[opt=awful.screen.focused().selected_tag] tag target_tag The tag that should be moved. -- @see index function tag.move(new_index, target_tag) gdebug.deprecate("Use t.index = new_index instead of awful.tag.move", {deprecated_in=4}) @@ -222,6 +223,7 @@ end -- -- @method swap -- @tparam tag tag2 The second tag +-- @noreturn -- @see client.swap function tag.object.swap(self, tag2) local idx1, idx2 = tag.object.get_index(self), tag.object.get_index(tag2) @@ -243,8 +245,8 @@ end --- Swap 2 tags -- @deprecated awful.tag.swap -- @see tag.swap --- @param tag1 The first tag --- @param tag2 The second tag +-- @tparam tag tag1 The first tag +-- @tparam tag tag2 The second tag function tag.swap(tag1, tag2) gdebug.deprecate("Use t:swap(tag2) instead of awful.tag.swap", {deprecated_in=4}) @@ -263,7 +265,7 @@ end -- @constructorfct awful.tag.add -- @tparam string name The tag name, a string -- @tparam[opt=nil] table|nil props The tags initial properties, a table --- @return The created tag +-- @treturn tag The created tag. -- @see tag.delete function tag.add(name, props) local properties = props or {} @@ -308,7 +310,7 @@ end -- -- @staticfct awful.tag.new -- @tparam table names The tag name, in a table --- @tparam[opt=1] screen|number screen The tag screen (defaults to screen 1). +-- @tparam[opt=1] screen|number screen The tag screen. -- @tparam table layout The layout or layout table to set for this tags by default. -- @treturn table A table with all created tags. function tag.new(names, screen, layout) @@ -334,8 +336,9 @@ end --- Find a suitable fallback tag. -- @staticfct awful.tag.find_fallback --- @tparam screen screen The screen to look for a tag on. [awful.screen.focused()] --- @tparam[opt=nil] table|nil invalids A table of tags considered unacceptable. [selectedlist(scr)] +-- @tparam[opt=awful.screen.focused()] screen screen The screen to look for a tag on. +-- @tparam[opt=nil] table|nil invalids A table of tags considered unacceptable. +-- @treturn tag|nil Returns a fallback tag if one was found, otherwise `nil`. function tag.find_fallback(screen, invalids) local scr = screen or ascreen.focused() local t = invalids or scr.selected_tags @@ -357,6 +360,7 @@ end -- @tparam table args The arguments. -- @tparam tag args.fallback_tag A fallback tag. -- @tparam[opt=false] boolean args.allow_untagged Allow the untagged clients to remain untagged. +-- @noreturn -- @emits cleared After all clients have been untagged. -- @emits untagged For each currently tagged clients. -- @emitstparam untagged client c The untagged client. @@ -397,7 +401,7 @@ end -- stickied tags to. -- @tparam[opt=false] boolean force Move even non-sticky clients to the fallback -- tag. --- @return Returns true if the tag is successfully deleted. +-- @treturn boolean Returns true if the tag is successfully deleted. -- If there are no clients exclusively on this tag then delete it. Any -- stickied clients are assigned to the optional 'fallback_tag'. -- If after deleting the tag there is no selected tag, try and restore from @@ -465,9 +469,9 @@ end --- Delete a tag. -- @deprecated awful.tag.delete -- @see tag.delete --- @param target_tag Optional tag object to delete. [selected()] --- @param fallback_tag Tag to assign stickied tags to. [~selected()] --- @return Returns true if the tag is successfully deleted, nil otherwise. +-- @tparam[opt=mouse.screen.selected_tag] tag target_tag Optional tag object to delete. +-- @tparam[opt] tag|nil fallback_tag Tag to assign stickied tags to. +-- @treturn boolean Returns true if the tag is successfully deleted, nil otherwise. -- If there are no clients exclusively on this tag then delete it. Any -- stickied clients are assigned to the optional 'fallback_tag'. -- If after deleting the tag there is no selected tag, try and restore from @@ -481,6 +485,7 @@ end --- Update the tag history. -- @staticfct awful.tag.history.update -- @tparam screen obj Screen object. +-- @noreturn function tag.history.update(obj) local s = get_screen(obj) local curtags = s.selected_tags @@ -521,6 +526,7 @@ end --- Revert tag history. -- @staticfct awful.tag.history.restore +-- @noreturn -- @tparam screen screen The screen. -- @tparam number idx Index in history. Defaults to "previous" which is a special index -- toggling between last two selected sets of tags. Number (eg 1) will go back @@ -558,7 +564,7 @@ end --- Get a list of all tags on a screen -- @deprecated awful.tag.gettags -- @tparam screen s Screen --- @return A table with all available tags +-- @treturn table A table with all available tags -- @see screen.tags function tag.gettags(s) gdebug.deprecate("Use s.tags instead of awful.tag.gettags", {deprecated_in=4}) @@ -571,7 +577,7 @@ end --- Find a tag by name. -- @tparam screen s The screen of the tag -- @tparam string name The name of the tag --- @return The tag found, or `nil` +-- @treturn tag|nil The tag found, or `nil` -- @staticfct awful.tag.find_by_name -- @usage -- For the current screen -- local t = awful.tag.find_by_name(awful.screen.focused(), "name") @@ -594,7 +600,7 @@ end --- The tag screen. -- -- @property screen --- @tparam screen screen +-- @tparam[opt=awful.screen.focused()] screen screen -- @propemits false false -- @see screen @@ -637,8 +643,8 @@ end --- Set a tag's screen -- @deprecated awful.tag.setscreen -- @see screen --- @param s Screen --- @param t tag object +-- @tparam screen s Screen +-- @tparam tag t The tag object function tag.setscreen(s, t) -- For API consistency, the arguments have been swapped for Awesome 3.6 -- this method is already deprecated, so be silent and swap the args @@ -654,8 +660,8 @@ end --- Get a tag's screen -- @deprecated awful.tag.getscreen -- @see screen --- @param[opt] t tag object --- @return Screen number +-- @tparam[opt=awful.screen.focused().selected_taga] tag|nil t Tag object +-- @treturn screen The tag screen. function tag.getscreen(t) gdebug.deprecate("Use t.screen instead of awful.tag.getscreen(t)", {deprecated_in=4}) @@ -668,8 +674,8 @@ end --- Return a table with all visible tags -- @deprecated awful.tag.selectedlist --- @param s Screen. --- @return A table with all selected tags. +-- @tparam screen s Screen. +-- @treturn table A table with all selected tags. -- @see screen.selected_tags function tag.selectedlist(s) gdebug.deprecate("Use s.selected_tags instead of awful.tag.selectedlist", {deprecated_in=4}) @@ -681,7 +687,7 @@ end --- Return only the first visible tag. -- @deprecated awful.tag.selected --- @param s Screen. +-- @tparam screen s Screen. -- @see screen.selected_tag function tag.selected(s) gdebug.deprecate("Use s.selected_tag instead of awful.tag.selected", {deprecated_in=4}) @@ -694,7 +700,7 @@ end --- The default master width factor -- -- @beautiful beautiful.master_width_factor --- @param number (default: 0.5) +-- @tparam[opt=0.5] number master_width_factor -- @see master_width_factor -- @see gap @@ -714,7 +720,9 @@ end -- @DOC_screen_mwfact2_EXAMPLE@ -- -- @property master_width_factor --- @tparam number master_width_factor Between 0 and 1 +-- @tparam[opt=beautiful.master_width_factor] number master_width_factor +-- @rangestart 0.0 +-- @rangestop 1.0 -- @emits property::mwfact When the value changes (deprecated). -- @emits property::master_width_factor When the value changes. -- @see master_count @@ -740,8 +748,8 @@ end -- @deprecated awful.tag.setmwfact -- @see master_fill_policy -- @see master_width_factor --- @param mwfact Master width factor. --- @param t The tag to modify, if null tag.selected() is used. +-- @tparam number mwfact Master width factor. +-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. function tag.setmwfact(mwfact, t) gdebug.deprecate("Use t.master_width_factor = mwfact instead of awful.tag.setmwfact", {deprecated_in=4}) @@ -752,7 +760,8 @@ end -- @staticfct awful.tag.incmwfact -- @see master_width_factor -- @tparam number add Value to add to master width factor. --- @tparam tag t The tag to modify, if null tag.selected() is used. +-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. +-- @noreturn function tag.incmwfact(add, t) t = t or t or ascreen.focused().selected_tag tag.object.set_master_width_factor(t, tag.object.get_master_width_factor(t) + add) @@ -762,7 +771,7 @@ end -- @deprecated awful.tag.getmwfact -- @see master_width_factor -- @see master_fill_policy --- @param[opt] t The tag. +-- @tparam[opt] tag|nil t The tag. function tag.getmwfact(t) gdebug.deprecate("Use t.master_width_factor instead of awful.tag.getmwfact", {deprecated_in=4}) @@ -795,6 +804,11 @@ end -- } -- -- @tfield table awful.tag.layouts +-- @tparam[opt={}] table awful.tag.layouts +-- @see request::layouts +-- @see awful.layout.append_default_layouts +-- @see awful.layout.append_default_layout +-- @see awful.layout.remove_default_layout --- The tag client layout. -- @@ -817,6 +831,34 @@ end -- placed. The only parameter is a table or arguments returned by -- `awful.layout.parameters` -- +-- The parameter table contains: +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +-- +--
Parameter TypeDescription
`workarea` table +-- A table with `x`,`y`, `width` and `height` keys.
+-- All clients must be placed within this area. +--
`geometry` table A table with the screen geometry.
`clients` table A list of the clients to place.
`screen` screen The screen.
`padding` table +-- A table with `left`, `right`, `top` and `bottom` keys. +--
`useless_gap` integer The space that will be removed from the clients.
`geometries` table +-- Empty. Place the client as key and preferred geometry
+-- as value. Do not call `:geometry()` directly. +--
+-- -- **Stateful layouts:** -- -- The stateful layouts API is the same as stateless, but they are a function @@ -833,9 +875,13 @@ end -- -- @property layout -- @tparam layout|function layout A layout table or a constructor function +-- @propertydefault The first non-nil value of either `self.layouts[1]` or +-- `awful.layout.layouts[1]` or `awful.layout.suit.floating`. +-- @functionparam table params A table containing the state of the layout (see the table above). +-- @functionnoreturn -- @propemits false false -- @see awful.tag.layouts --- @return The layout +-- @see awful.layout.parameters --- The (proposed) list of available layouts for this tag. -- @@ -849,10 +895,13 @@ end -- front of the list. -- -- @property layouts --- @tparam table layouts +-- @tparam[opt=nil] table|nil layouts +-- @propertytype nil Use the current value of `awful.layout.layouts`. -- @request tag layouts awful granted When the `layouts` property is first called -- and there is no layouts, then that signal is called. -- @see awful.layout.layouts +-- @see screen.workarea +-- @see screen.padding -- @see layout function tag.object.set_layout(t, layout) @@ -1002,8 +1051,8 @@ end --- Set layout. -- @deprecated awful.tag.setlayout -- @see layout --- @param layout a layout table or a constructor function --- @param t The tag to modify +-- @param layout A layout table or a constructor function +-- @tparam tag t The tag to modify -- @return The layout function tag.setlayout(layout, t) gdebug.deprecate("Use t.layout = layout instead of awful.tag.setlayout", {deprecated_in=4}) @@ -1043,7 +1092,7 @@ end -- the "Non-volatile" tag is still there (but with zero clients). -- -- @property volatile --- @tparam boolean volatile +-- @tparam[opt=false] boolean volatile -- @propemits false false -- @see delete @@ -1053,7 +1102,7 @@ end -- @deprecated awful.tag.setvolatile -- @see volatile -- @tparam boolean volatile If the tag must be deleted when the last client is untagged --- @param t The tag to modify, if null tag.selected() is used. +-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. function tag.setvolatile(volatile, t) gdebug.deprecate("Use t.volatile = volatile instead of awful.tag.setvolatile", {deprecated_in=4}) @@ -1063,7 +1112,7 @@ end --- Get if the tag must be deleted when the last client closes -- @deprecated awful.tag.getvolatile -- @see volatile --- @param t The tag to modify, if null tag.selected() is used. +-- @tparam[opt=opt=awful.screen.focused().selected_tag] tag t The tag to modify. -- @treturn boolean If the tag will be deleted when the last client is untagged function tag.getvolatile(t) gdebug.deprecate("Use t.volatile instead of awful.tag.getvolatile", {deprecated_in=4}) @@ -1074,7 +1123,7 @@ end --- The default gap. -- -- @beautiful beautiful.useless_gap --- @param number (default: 0) +-- @tparam[opt=0] number useless_gap -- @see gap -- @see gap_single_client @@ -1092,7 +1141,9 @@ end -- @DOC_screen_gaps2_EXAMPLE@ -- -- @property gap --- @tparam number gap The value has to be greater than zero. +-- @tparam[opt=beautiful.useless_gap] integer gap The value has to be greater than zero. +-- @propertyunit pixel +-- @negativeallowed false -- @emits property::useless_gap When the gap changes. -- @see gap_single_client -- @see awful.tag.incgap @@ -1112,8 +1163,8 @@ end --- Set the spacing between clients -- @deprecated awful.tag.setgap -- @see gap --- @param useless_gap The spacing between clients --- @param t The tag to modify, if null tag.selected() is used. +-- @tparam number|nil useless_gap The spacing between clients +-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. function tag.setgap(useless_gap, t) gdebug.deprecate("Use t.gap = useless_gap instead of awful.tag.setgap", {deprecated_in=4}) @@ -1122,9 +1173,11 @@ end --- Increase the spacing between clients -- @staticfct awful.tag.incgap --- @see gap -- @tparam number add Value to add to the spacing between clients --- @tparam tag t The tag to modify, if null tag.selected() is used. +-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. +-- @noreturn +-- @see gap +-- @see beautiful.useless_gap function tag.incgap(add, t) t = t or t or ascreen.focused().selected_tag tag.object.set_gap(t, tag.object.get_gap(t) + add) @@ -1133,7 +1186,7 @@ end --- Enable gaps for a single client. -- -- @beautiful beautiful.gap_single_client --- @param boolean (default: true) +-- @tparam[opt=true] boolean gap_single_client -- @see gap -- @see gap_single_client @@ -1153,7 +1206,7 @@ end -- @DOC_screen_gap_single_client_false_EXAMPLE@ -- -- @property gap_single_client --- @tparam boolean gap_single_client Enable gaps for a single client +-- @tparam[opt=beautiful.gap_single_client] boolean gap_single_client Enable gaps for a single client -- @propemits false false -- @see awful.tag.incgap @@ -1199,7 +1252,7 @@ end -- `master_width_factor` -- -- @beautiful beautiful.master_fill_policy --- @param string (default: "expand") +-- @tparam[opt="expand"] string master_fill_policy -- @see master_fill_policy --- Set size fill policy for the master client(s). @@ -1207,12 +1260,6 @@ end -- Some multi-column layouts can be configured so that the space is -- redistributed when there is not enough clients to fill all columns. -- --- ** Possible values**: --- --- * *expand*: Take all the space --- * *master\_width\_factor*: Only take the ratio defined by the --- `master_width_factor` --- -- This is the default behavior of the `tile.left` layout (*expand*): -- -- @DOC_screen_mfpol2_EXAMPLE@ @@ -1225,7 +1272,10 @@ end -- redistributed on both side. -- -- @property master_fill_policy --- @tparam string master_fill_policy "expand" or "master_width_factor" +-- @tparam[opt=beautiful.master_fill_policy] string master_fill_policy +-- @propertyvalue "expand" Take all the space +-- @propertyvalue "master_width_factor" Only take the ratio defined by the +-- `master_width_factor` -- @propemits false false -- @see awful.tag.togglemfpol @@ -1240,8 +1290,9 @@ end -- @see master_fill_policy -- @tparam string policy Can be set to -- "expand" (fill all the available workarea) or --- "master_width_factor" (fill only an area inside the master width factor) +-- `master_width_factor` (fill only an area inside the master width factor) -- @tparam[opt=tag.selected()] tag t The tag to modify +-- @noreturn function tag.setmfpol(policy, t) gdebug.deprecate("Use t.master_fill_policy = policy instead of awful.tag.setmfpol", {deprecated_in=4}) @@ -1250,10 +1301,11 @@ function tag.setmfpol(policy, t) end --- Toggle size fill policy for the master client(s) --- between "expand" and "master_width_factor". +-- between "expand" and `master_width_factor`. -- @staticfct awful.tag.togglemfpol +-- @noreturn -- @see master_fill_policy --- @tparam tag t The tag to modify, if null tag.selected() is used. +-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. function tag.togglemfpol(t) t = t or ascreen.focused().selected_tag @@ -1283,7 +1335,7 @@ end --- The default number of master windows. -- -- @beautiful beautiful.master_count --- @param integer (default: 1) +-- @tparam[opt=1] integer master_count -- @see master_count --- Set the number of master windows. @@ -1291,7 +1343,8 @@ end -- @DOC_sequences_tag_master_count_EXAMPLE@ -- -- @property master_count --- @tparam integer master_count nmaster Only positive values are accepted +-- @tparam[opt=beautiful.master_count] integer master_count Only positive values are accepted +-- @rangestart 1 -- @emits property::nmaster Deprecated. -- @emits property::master_count When the value changes. -- @see awful.tag.incnmaster @@ -1312,8 +1365,8 @@ end --- The number of master clients. -- @deprecated awful.tag.setnmaster -- @see master_count --- @param nmaster The number of master windows. --- @param[opt] t The tag. +-- @tparam number nmaster The number of master windows. +-- @tparam[opt] tag t The tag. function tag.setnmaster(nmaster, t) gdebug.deprecate("Use t.master_count = nmaster instead of awful.tag.setnmaster", {deprecated_in=4}) @@ -1323,7 +1376,7 @@ end --- Get the number of master windows. -- @deprecated awful.tag.getnmaster -- @see master_count --- @param[opt] t The tag. +-- @tparam[opt] tag t The tag. function tag.getnmaster(t) gdebug.deprecate("Use t.master_count instead of awful.tag.setnmaster", {deprecated_in=4}) @@ -1335,9 +1388,10 @@ end -- @staticfct awful.tag.incnmaster -- @see master_count -- @tparam number add Value to add to number of master windows. --- @tparam[opt] tag t The tag to modify, if null tag.selected() is used. +-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. -- @tparam[opt=false] boolean sensible Limit nmaster based on the number of -- visible tiled windows? +-- @noreturn function tag.incnmaster(add, t, sensible) t = t or ascreen.focused().selected_tag @@ -1365,7 +1419,7 @@ end -- @DOC_wibox_awidget_taglist_icon_EXAMPLE@ -- -- @property icon --- @tparam path|surface icon The icon +-- @tparam[opt=nil] image|nil icon -- @propemits false false -- @see awful.widget.taglist -- @see gears.surface @@ -1374,9 +1428,9 @@ end --- Set the tag icon -- @deprecated awful.tag.seticon +-- @tparam gears.surface|string icon The icon to set, either path or image object +-- @tparam tag tag The tag -- @see icon --- @param icon the icon to set, either path or image object --- @tparam tag tag the tag function tag.seticon(icon, _tag) gdebug.deprecate("Use t.icon = icon instead of awful.tag.seticon", {deprecated_in=4}) @@ -1387,7 +1441,7 @@ end --- Get the tag icon -- @deprecated awful.tag.geticon -- @see icon --- @tparam tag tag the tag +-- @tparam tag tag The tag function tag.geticon(_tag) gdebug.deprecate("Use t.icon instead of awful.tag.geticon", {deprecated_in=4}) @@ -1398,7 +1452,7 @@ end --- The default number of columns. -- -- @beautiful beautiful.column_count --- @param integer (default: 1) +-- @tparam[opt=1] integer column_count -- @see column_count --- Set the number of columns. @@ -1406,7 +1460,8 @@ end -- @DOC_sequences_tag_column_count_EXAMPLE@ -- -- @property column_count --- @tparam integer ncol Has to be greater than 1 +-- @tparam[opt=beautiful.column_count or 1] integer column_count Has to be greater than 1 +-- @rangestart 1 -- @emits property::ncol Deprecated. -- @emits property::column_count When the value changes. -- @see awful.tag.incncol @@ -1427,8 +1482,8 @@ end --- Set number of column windows. -- @deprecated awful.tag.setncol -- @see column_count --- @param ncol The number of column. --- @param t The tag to modify, if null tag.selected() is used. +-- @tparam integer ncol The number of column. +-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. function tag.setncol(ncol, t) gdebug.deprecate("Use t.column_count = new_index instead of awful.tag.setncol", {deprecated_in=4}) @@ -1442,7 +1497,7 @@ end --- Get number of column windows. -- @deprecated awful.tag.getncol -- @see column_count --- @param[opt] t The tag. +-- @tparam[opt] tag t The tag. function tag.getncol(t) gdebug.deprecate("Use t.column_count instead of awful.tag.getncol", {deprecated_in=4}) @@ -1453,9 +1508,10 @@ end --- Increase number of column windows. -- @staticfct awful.tag.incncol -- @tparam number add Value to add to number of column windows. --- @tparam[opt] tag t The tag to modify, if null tag.selected() is used. +-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify. -- @tparam[opt=false] boolean sensible Limit column_count based on the number -- of visible tiled windows? +-- @noreturn function tag.incncol(add, t, sensible) t = t or ascreen.focused().selected_tag @@ -1487,6 +1543,7 @@ end -- -- @staticfct awful.tag.viewnone -- @tparam[opt] int|screen screen The screen. +-- @noreturn function tag.viewnone(screen) screen = screen or ascreen.focused() local tags = screen.tags @@ -1506,6 +1563,7 @@ end -- @see screen.tags -- @tparam number i The **relative** index to see. -- @tparam[opt] screen screen The screen. +-- @noreturn -- @see awful.tag.viewnext -- @see awful.tag.viewprev function tag.viewidx(i, screen) @@ -1530,8 +1588,8 @@ end --- Get a tag's index in the gettags() table. -- @deprecated awful.tag.getidx -- @see index --- @param query_tag The tag object to find. [selected()] --- @return The index of the tag, nil if the tag is not found. +-- @tparam tag query_tag The tag object to find. [selected()] +-- @treturn integer|nil The index of the tag, nil if the tag is not found. function tag.getidx(query_tag) gdebug.deprecate("Use t.index instead of awful.tag.getidx", {deprecated_in=4}) @@ -1547,10 +1605,11 @@ end -- -- @staticfct awful.tag.viewnext -- @tparam screen screen The screen. +-- @noreturn -- @see awful.tag.viewidx -- @see awful.tag.viewprev function tag.viewnext(screen) - return tag.viewidx(1, screen) + tag.viewidx(1, screen) end --- View previous tag. This is the same a `tag.viewidx(-1)`. @@ -1561,10 +1620,11 @@ end -- -- @staticfct awful.tag.viewprev -- @tparam screen screen The screen. +-- @noreturn -- @see awful.tag.viewidx -- @see awful.tag.viewnext function tag.viewprev(screen) - return tag.viewidx(-1, screen) + tag.viewidx(-1, screen) end --- View only a tag. @@ -1572,6 +1632,7 @@ end -- @DOC_sequences_tag_view_only_EXAMPLE@ -- -- @method view_only +-- @noreturn -- @see selected function tag.object.view_only(self) local tags = self.screen.tags @@ -1590,6 +1651,7 @@ end --- View only a tag. -- @deprecated awful.tag.viewonly +-- @noreturn -- @see tag.view_only -- @tparam tag t The tag object. function tag.viewonly(t) @@ -1608,6 +1670,7 @@ end -- @tparam table tags A table with tags to view only. -- @tparam[opt] screen screen The screen of the tags. -- @tparam[opt=#tags] number maximum The maximum number of tags to select. +-- @noreturn function tag.viewmore(tags, screen, maximum) maximum = maximum or #tags local selected = 0 @@ -1638,8 +1701,9 @@ end --- Toggle selection of a tag -- @staticfct awful.tag.viewtoggle --- @see selected -- @tparam tag t Tag to be toggled +-- @noreturn +-- @see selected function tag.viewtoggle(t) t.selected = not t.selected capi.screen[tag.getproperty(t, "screen")]:emit_signal("tag::history::update") @@ -1651,7 +1715,7 @@ end -- -- @deprecated awful.tag.getdata -- @tparam tag t The tag. --- @return The data table. +-- @treturn table The data table. function tag.getdata(t) return t._private.awful_tag_properties end @@ -1679,8 +1743,8 @@ end -- Use `t.prop = value` -- -- @deprecated awful.tag.setproperty --- @param t The tag. --- @param prop The property name. +-- @tparam tag t The tag. +-- @tparam string prop The property name. -- @param value The value. function tag.setproperty(t, prop, value) if not t._private.awful_tag_properties then @@ -1695,7 +1759,8 @@ end --- Tag a client with the set of current tags. -- @deprecated awful.tag.withcurrent --- @param c The client to tag. +-- @tparam client c The client to tag. +-- @noreturn function tag.withcurrent(c) gdebug.deprecate("Use c:to_selected_tags() instead of awful.tag.selectedlist", {deprecated_in=4}) @@ -1732,9 +1797,10 @@ end -- future. When a tag is detached from the screen, its signal is removed. -- -- @staticfct awful.tag.attached_connect_signal --- @tparam screen screen The screen concerned, or all if nil. --- @tparam[opt] string signal The signal name. --- @tparam[opt] function Callback +-- @tparam screen|nil screen The screen concerned, or all if `nil`. +-- @tparam string signal The signal name. +-- @tparam function callback +-- @noreturn function tag.attached_connect_signal(screen, ...) if screen then attached_connect_signal_screen(screen, ...) @@ -1809,12 +1875,12 @@ capi.tag.connect_signal("request::select", tag.object.view_only) --- Emitted when the number of urgent clients on this tag changes. -- @signal property::urgent --- @param boolean `true` if there is at least one urgent client on the tag. +-- @tparam boolean urgent `true` if there is at least one urgent client on the tag. -- @see client.urgent --- Emitted when the number of urgent clients on this tag changes. -- @signal property::urgent_count --- @param integer The number of urgent clients on the tag. +-- @tparam integer count The number of urgent clients on the tag. -- @see client.urgent --- Emitted when a screen is removed. diff --git a/lib/awful/titlebar.lua b/lib/awful/titlebar.lua index 9952a743a..99873b216 100644 --- a/lib/awful/titlebar.lua +++ b/lib/awful/titlebar.lua @@ -1,6 +1,8 @@ --------------------------------------------------------------------------- ---- Titlebars for awful. ---**Create a titlebar:** +--- Create widget area on the edge of a client. +-- +-- Create a titlebar +-- ================= -- -- This example reproduces what the default `rc.lua` does. It shows how to -- handle the titlebars on a lower level. @@ -39,418 +41,501 @@ local titlebar = { --- Show tooltips when hover on titlebar buttons. +-- -- @tfield[opt=true] boolean awful.titlebar.enable_tooltip -- @param boolean --- Title to display if client name is not set. +-- -- @field[opt='\'] awful.titlebar.fallback_name -- @tparam[opt='\'] string fallback_name - --- The titlebar foreground (text) color. +-- -- @beautiful beautiful.titlebar_fg_normal -- @param color -- @see gears.color --- The titlebar background color. +-- -- @beautiful beautiful.titlebar_bg_normal -- @param color -- @see gears.color --- The titlebar background image image. +-- -- @beautiful beautiful.titlebar_bgimage_normal -- @tparam gears.surface|string path -- @see gears.surface --- The titlebar foreground (text) color. +-- -- @beautiful beautiful.titlebar_fg -- @param color -- @see gears.color --- The titlebar background color. +-- -- @beautiful beautiful.titlebar_bg -- @param color -- @see gears.color --- The titlebar background image image. +-- -- @beautiful beautiful.titlebar_bgimage -- @tparam gears.surface|string path -- @see gears.surface --- The focused titlebar foreground (text) color. +-- -- @beautiful beautiful.titlebar_fg_focus -- @param color -- @see gears.color --- The focused titlebar background color. +-- -- @beautiful beautiful.titlebar_bg_focus -- @param color -- @see gears.color --- The focused titlebar background image image. +-- -- @beautiful beautiful.titlebar_bgimage_focus -- @tparam gears.surface|string path -- @see gears.surface --- The urgent titlebar foreground (text) color. +-- -- @beautiful beautiful.titlebar_fg_urgent -- @param color -- @see gears.color --- The urgent titlebar background color. +-- -- @beautiful beautiful.titlebar_bg_urgent -- @param color -- @see gears.color ---- The urgent titlebar background image image. +--- The urgent titlebar background image. +-- -- @beautiful beautiful.titlebar_bgimage_urgent -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_normal. +--- The normal non-floating button image. +-- -- @beautiful beautiful.titlebar_floating_button_normal -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_normal. +--- The normal non-maximized button image. +-- -- @beautiful beautiful.titlebar_maximized_button_normal -- @tparam gears.surface|string path -- @see gears.surface ---- minimize_button_normal. +--- The normal minimize button image. +-- -- @beautiful beautiful.titlebar_minimize_button_normal -- @tparam gears.surface|string path -- @see gears.surface ---- minimize_button_normal_hover. +--- The hovered minimize button image. +-- -- @beautiful beautiful.titlebar_minimize_button_normal_hover -- @tparam gears.surface|string path -- @see gears.surface ---- minimize_button_normal_press. +--- The pressed minimize button image. +-- -- @beautiful beautiful.titlebar_minimize_button_normal_press -- @tparam gears.surface|string path -- @see gears.surface ---- close_button_normal. +--- The normal close button image. +-- -- @beautiful beautiful.titlebar_close_button_normal -- @tparam gears.surface|string path -- @see gears.surface ---- close_button_normal_hover. +--- The hovered close button image. +-- -- @beautiful beautiful.titlebar_close_button_normal_hover -- @tparam gears.surface|string path -- @see gears.surface ---- close_button_normal_press. +--- The pressed close button image. +-- -- @beautiful beautiful.titlebar_close_button_normal_press -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_normal. +--- The normal non-ontop button image. +-- -- @beautiful beautiful.titlebar_ontop_button_normal -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_normal. +--- The normal non-sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_normal -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_focus. +--- The focused client non-floating button image. +-- -- @beautiful beautiful.titlebar_floating_button_focus -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_focus. +--- The focused client non-maximized button image. +-- -- @beautiful beautiful.titlebar_maximized_button_focus -- @tparam gears.surface|string path -- @see gears.surface ---- minimize_button_focus. +--- The focused client minimize button image. +-- -- @beautiful beautiful.titlebar_minimize_button_focus -- @tparam gears.surface|string path -- @see gears.surface ---- minimize_button_focus_hover. +--- The hovered+focused client minimize button image. +-- -- @beautiful beautiful.titlebar_minimize_button_focus_hover -- @tparam gears.surface|string path -- @see gears.surface ---- minimize_button_focus_press. +--- The pressed+focused minimize button image. +-- -- @beautiful beautiful.titlebar_minimize_button_focus_press -- @tparam gears.surface|string path -- @see gears.surface ---- close_button_focus. +--- The focused client close button image. +-- -- @beautiful beautiful.titlebar_close_button_focus -- @tparam gears.surface|string path -- @see gears.surface ---- close_button_focus_hover. +--- The hovered+focused close button image. +-- -- @beautiful beautiful.titlebar_close_button_focus_hover -- @tparam gears.surface|string path -- @see gears.surface ---- close_button_focus_press. +--- The pressed+focused close button image. +-- -- @beautiful beautiful.titlebar_close_button_focus_press -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_focus. +--- The focused client non-ontop button image. +-- -- @beautiful beautiful.titlebar_ontop_button_focus -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_focus. +--- The focused client sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_focus -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_normal_active. +--- The normal floating button image. +-- -- @beautiful beautiful.titlebar_floating_button_normal_active -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_normal_active_hover. +--- The hovered floating client button image. +-- -- @beautiful beautiful.titlebar_floating_button_normal_active_hover -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_normal_active_press. +--- The pressed floating client button image. +-- -- @beautiful beautiful.titlebar_floating_button_normal_active_press -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_normal_active. +--- The maximized client button image. +-- -- @beautiful beautiful.titlebar_maximized_button_normal_active -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_normal_active_hover. +--- The hozered+maximized client button image. +-- -- @beautiful beautiful.titlebar_maximized_button_normal_active_hover -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_normal_active_press. +--- The pressed+maximized button image. +-- -- @beautiful beautiful.titlebar_maximized_button_normal_active_press -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_normal_active. +--- The ontop button image. +-- -- @beautiful beautiful.titlebar_ontop_button_normal_active -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_normal_active_hover. +--- The hovered+ontop client button image. +-- -- @beautiful beautiful.titlebar_ontop_button_normal_active_hover -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_normal_active_press. +--- The pressed+ontop client button image. +-- -- @beautiful beautiful.titlebar_ontop_button_normal_active_press -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_normal_active. +--- The sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_normal_active -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_normal_active_hover. +--- The hovered+sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_normal_active_hover -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_normal_active_press. +--- The pressed+sticky client button image. +-- -- @beautiful beautiful.titlebar_sticky_button_normal_active_press -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_focus_active. +--- The floating+focused client button image. +-- -- @beautiful beautiful.titlebar_floating_button_focus_active -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_focus_active_hover. +--- The hovered+floating+focused button image. +-- -- @beautiful beautiful.titlebar_floating_button_focus_active_hover -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_focus_active_press. +--- The pressed+floating+focused button image. +-- -- @beautiful beautiful.titlebar_floating_button_focus_active_press -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_focus_active. +--- The maximized+focused button image. +-- -- @beautiful beautiful.titlebar_maximized_button_focus_active -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_focus_active_hover. +--- The hovered+maximized+focused button image. +-- -- @beautiful beautiful.titlebar_maximized_button_focus_active_hover -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_focus_active_press. +--- The pressed+maximized+focused button image. +-- -- @beautiful beautiful.titlebar_maximized_button_focus_active_press -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_focus_active. +--- The ontop+focused button image. +-- -- @beautiful beautiful.titlebar_ontop_button_focus_active -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_focus_active_hover. +--- The hovered+ontop+focused button image. +-- -- @beautiful beautiful.titlebar_ontop_button_focus_active_hover -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_focus_active_press. +--- The pressed+ontop+focused button image. +-- -- @beautiful beautiful.titlebar_ontop_button_focus_active_press -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_focus_active. +--- The sticky+focused button image. +-- -- @beautiful beautiful.titlebar_sticky_button_focus_active -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_focus_active_hover. +--- The hovered+sticky+focused button image. +-- -- @beautiful beautiful.titlebar_sticky_button_focus_active_hover -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_focus_active_press. +--- The pressed+sticky+focused button image. +-- -- @beautiful beautiful.titlebar_sticky_button_focus_active_press -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_normal_inactive. +--- The inactive+floating button image. +-- -- @beautiful beautiful.titlebar_floating_button_normal_inactive -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_normal_inactive_hover. +--- The hovered+inactive+floating button image. +-- -- @beautiful beautiful.titlebar_floating_button_normal_inactive_hover -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_normal_inactive_press. +--- The pressed+inactive+floating button image. +-- -- @beautiful beautiful.titlebar_floating_button_normal_inactive_press -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_normal_inactive. +--- The inactive+maximized button image. +-- -- @beautiful beautiful.titlebar_maximized_button_normal_inactive -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_normal_inactive_hover. +--- The hovered+inactive+maximized button image. +-- -- @beautiful beautiful.titlebar_maximized_button_normal_inactive_hover -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_normal_inactive_press. +--- The pressed+maximized+inactive button image. +-- -- @beautiful beautiful.titlebar_maximized_button_normal_inactive_press -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_normal_inactive. +--- The inactive+ontop button image. +-- -- @beautiful beautiful.titlebar_ontop_button_normal_inactive -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_normal_inactive_hover. +--- The hovered+inactive+ontop button image. +-- -- @beautiful beautiful.titlebar_ontop_button_normal_inactive_hover -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_normal_inactive_press. +--- The pressed+inactive+ontop button image. +-- -- @beautiful beautiful.titlebar_ontop_button_normal_inactive_press -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_normal_inactive. +--- The inactive+sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_normal_inactive -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_normal_inactive_hover. +--- The hovered+inactive+sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_normal_inactive_hover -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_normal_inactive_press. +--- The pressed+inactive+sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_normal_inactive_press -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_focus_inactive. +--- The inactive+focused+floating button image. +-- -- @beautiful beautiful.titlebar_floating_button_focus_inactive -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_focus_inactive_hover. +--- The hovered+inactive+focused+floating button image. +-- -- @beautiful beautiful.titlebar_floating_button_focus_inactive_hover -- @tparam gears.surface|string path -- @see gears.surface ---- floating_button_focus_inactive_press. +--- The pressed+inactive+focused+floating button image. +-- -- @beautiful beautiful.titlebar_floating_button_focus_inactive_press -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_focus_inactive. +--- The inactive+focused+maximized button image. +-- -- @beautiful beautiful.titlebar_maximized_button_focus_inactive -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_focus_inactive_hover. +--- The hovered+inactive+focused+maximized button image. +-- -- @beautiful beautiful.titlebar_maximized_button_focus_inactive_hover -- @tparam gears.surface|string path -- @see gears.surface ---- maximized_button_focus_inactive_press. +--- The pressed+inactive+focused+maximized button image. +-- -- @beautiful beautiful.titlebar_maximized_button_focus_inactive_press -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_focus_inactive. +--- The inactive+focused+ontop button image. +-- -- @beautiful beautiful.titlebar_ontop_button_focus_inactive -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_focus_inactive_hover. +--- The hovered+inactive+focused+ontop button image. +-- -- @beautiful beautiful.titlebar_ontop_button_focus_inactive_hover -- @tparam gears.surface|string path -- @see gears.surface ---- ontop_button_focus_inactive_press. +--- The pressed+inactive+focused+ontop button image. +-- -- @beautiful beautiful.titlebar_ontop_button_focus_inactive_press -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_focus_inactive. +--- The inactive+focused+sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_focus_inactive -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_focus_inactive_hover. +--- The hovered+inactive+focused+sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_focus_inactive_hover -- @tparam gears.surface|string path -- @see gears.surface ---- sticky_button_focus_inactive_press. +--- The pressed+inactive+focused+sticky button image. +-- -- @beautiful beautiful.titlebar_sticky_button_focus_inactive_press -- @tparam gears.surface|string path -- @see gears.surface --- Set a declarative widget hierarchy description. +-- -- See [The declarative layout system](../documentation/03-declarative-layout.md.html) --- @param args An array containing the widgets disposition +-- @tparam table args An array containing the widgets disposition -- @method setup +-- @noreturn local all_titlebars = setmetatable({}, { __mode = 'k' }) @@ -552,6 +637,18 @@ end -- @tparam[opt] string args.font -- @constructorfct awful.titlebar -- @treturn wibox.drawable The newly created titlebar object. +-- @usebeautiful beautiful.titlebar_fg_normal +-- @usebeautiful beautiful.titlebar_bg_normal +-- @usebeautiful beautiful.titlebar_bgimage_normal +-- @usebeautiful beautiful.titlebar_fg +-- @usebeautiful beautiful.titlebar_bg +-- @usebeautiful beautiful.titlebar_bgimage +-- @usebeautiful beautiful.titlebar_fg_focus +-- @usebeautiful beautiful.titlebar_bg_focus +-- @usebeautiful beautiful.titlebar_bgimage_focus +-- @usebeautiful beautiful.titlebar_fg_urgent +-- @usebeautiful beautiful.titlebar_bg_urgent +-- @usebeautiful beautiful.titlebar_bgimage_urgent local function new(c, args) args = args or {} local position = args.position or "top" @@ -614,9 +711,10 @@ local function new(c, args) end --- Show the client's titlebar. --- @param c The client whose titlebar is modified +-- @tparam client c The client whose titlebar is modified -- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`, -- `"right"`, `"top"`, `"bottom"`. +-- @noreturn -- @staticfct awful.titlebar.show -- @request client titlebars show granted Called when `awful.titlebar.show` is -- called. @@ -630,9 +728,10 @@ function titlebar.show(c, position) end --- Hide the client's titlebar. --- @param c The client whose titlebar is modified +-- @tparam client c The client whose titlebar is modified -- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`, -- `"right"`, `"top"`, `"bottom"`. +-- @noreturn -- @staticfct awful.titlebar.hide function titlebar.hide(c, position) position = position or "top" @@ -640,9 +739,10 @@ function titlebar.hide(c, position) end --- Toggle the client's titlebar, hiding it if it is visible, otherwise showing it. --- @param c The client whose titlebar is modified +-- @tparam client c The client whose titlebar is modified -- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`, -- `"right"`, `"top"`, `"bottom"`. +-- @noreturn -- @staticfct awful.titlebar.toggle -- @request client titlebars toggle granted Called when `awful.titlebar.toggle` is -- called. @@ -704,7 +804,7 @@ end -- Please note that this returns a textbox and all of textbox' API is available. -- This way, you can e.g. modify the font that is used. -- --- @param c The client for which a titlewidget should be created. +-- @tparam client c The client for which a titlewidget should be created. -- @return The title widget. -- @constructorfct awful.titlebar.widget.titlewidget function titlebar.widget.titlewidget(c) @@ -728,7 +828,7 @@ end -- Please note that this returns an imagebox and all of the imagebox' API is -- available. This way, you can e.g. disallow resizes. -- --- @param c The client for which an icon widget should be created. +-- @tparam client c The client for which an icon widget should be created. -- @return The icon widget. -- @constructorfct awful.titlebar.widget.iconwidget function titlebar.widget.iconwidget(c) @@ -745,12 +845,12 @@ end -- then found in the theme as `titlebar_[name]_button_[normal/focus]_[state]`. -- If that value does not exist, the focused state is ignored for the next try. -- --- @param c The client for which a button is created. +-- @tparam client c The client for which a button is created. -- @tparam string name Name of the button, used for accessing the theme and -- in the tooltip. --- @param selector A function that selects the image that should be displayed. --- @param action Function that is called when the button is clicked. --- @return The widget +-- @tparam function selector A function that selects the image that should be displayed. +-- @tparam function action Function that is called when the button is clicked. +-- @treturn wibox.widget The widget -- @constructorfct awful.titlebar.widget.button function titlebar.widget.button(c, name, selector, action) local ret = imagebox() @@ -838,8 +938,23 @@ function titlebar.widget.button(c, name, selector, action) end --- Create a new float button for a client. --- @param c The client for which the button is wanted. +-- -- @constructorfct awful.titlebar.widget.floatingbutton +-- @tparam client c The client for which the button is wanted. +-- @usebeautiful beautiful.titlebar_floating_button_normal +-- @usebeautiful beautiful.titlebar_floating_button_focus +-- @usebeautiful beautiful.titlebar_floating_button_normal_active +-- @usebeautiful beautiful.titlebar_floating_button_normal_active_hover +-- @usebeautiful beautiful.titlebar_floating_button_normal_active_press +-- @usebeautiful beautiful.titlebar_floating_button_focus_active +-- @usebeautiful beautiful.titlebar_floating_button_focus_active_hover +-- @usebeautiful beautiful.titlebar_floating_button_focus_active_press +-- @usebeautiful beautiful.titlebar_floating_button_normal_inactive +-- @usebeautiful beautiful.titlebar_floating_button_normal_inactive_hover +-- @usebeautiful beautiful.titlebar_floating_button_normal_inactive_press +-- @usebeautiful beautiful.titlebar_floating_button_focus_inactive +-- @usebeautiful beautiful.titlebar_floating_button_focus_inactive_hover +-- @usebeautiful beautiful.titlebar_floating_button_focus_inactive_press function titlebar.widget.floatingbutton(c) local widget = titlebar.widget.button(c, "floating", aclient.object.get_floating, aclient.floating.toggle) update_on_signal(c, "property::floating", widget) @@ -847,8 +962,23 @@ function titlebar.widget.floatingbutton(c) end --- Create a new maximize button for a client. --- @param c The client for which the button is wanted. +-- -- @constructorfct awful.titlebar.widget.maximizedbutton +-- @tparam client c The client for which the button is wanted. +-- @usebeautiful beautiful.titlebar_maximized_button_focus_active +-- @usebeautiful beautiful.titlebar_maximized_button_focus_active_hover +-- @usebeautiful beautiful.titlebar_maximized_button_focus_active_press +-- @usebeautiful beautiful.titlebar_maximized_button_normal_inactive +-- @usebeautiful beautiful.titlebar_maximized_button_normal_inactive_hover +-- @usebeautiful beautiful.titlebar_maximized_button_normal_inactive_press +-- @usebeautiful beautiful.titlebar_maximized_button_focus_inactive +-- @usebeautiful beautiful.titlebar_maximized_button_focus_inactive_hover +-- @usebeautiful beautiful.titlebar_maximized_button_focus_inactive_press +-- @usebeautiful beautiful.titlebar_maximized_button_normal +-- @usebeautiful beautiful.titlebar_maximized_button_focus +-- @usebeautiful beautiful.titlebar_maximized_button_normal_active +-- @usebeautiful beautiful.titlebar_maximized_button_normal_active_hover +-- @usebeautiful beautiful.titlebar_maximized_button_normal_active_press function titlebar.widget.maximizedbutton(c) local widget = titlebar.widget.button(c, "maximized", function(cl) return cl.maximized @@ -860,8 +990,15 @@ function titlebar.widget.maximizedbutton(c) end --- Create a new minimize button for a client. --- @param c The client for which the button is wanted. +-- -- @constructorfct awful.titlebar.widget.minimizebutton +-- @tparam client c The client for which the button is wanted. +-- @usebeautiful beautiful.titlebar_minimize_button_normal +-- @usebeautiful beautiful.titlebar_minimize_button_normal_hover +-- @usebeautiful beautiful.titlebar_minimize_button_normal_press +-- @usebeautiful beautiful.titlebar_minimize_button_focus +-- @usebeautiful beautiful.titlebar_minimize_button_focus_hover +-- @usebeautiful beautiful.titlebar_minimize_button_focus_press function titlebar.widget.minimizebutton(c) local widget = titlebar.widget.button(c, "minimize", function() return "" end, @@ -871,15 +1008,37 @@ function titlebar.widget.minimizebutton(c) end --- Create a new closing button for a client. --- @param c The client for which the button is wanted. +-- -- @constructorfct awful.titlebar.widget.closebutton +-- @tparam client c The client for which the button is wanted. +-- @usebeautiful beautiful.titlebar_close_button_normal +-- @usebeautiful beautiful.titlebar_close_button_normal_hover +-- @usebeautiful beautiful.titlebar_close_button_normal_press +-- @usebeautiful beautiful.titlebar_close_button_focus +-- @usebeautiful beautiful.titlebar_close_button_focus_hover +-- @usebeautiful beautiful.titlebar_close_button_focus_press function titlebar.widget.closebutton(c) return titlebar.widget.button(c, "close", function() return "" end, function(cl) cl:kill() end) end --- Create a new ontop button for a client. --- @param c The client for which the button is wanted. +-- -- @constructorfct awful.titlebar.widget.ontopbutton +-- @tparam client c The client for which the button is wanted. +-- @usebeautiful beautiful.titlebar_ontop_button_normal +-- @usebeautiful beautiful.titlebar_ontop_button_focus +-- @usebeautiful beautiful.titlebar_ontop_button_normal_active +-- @usebeautiful beautiful.titlebar_ontop_button_normal_active_hover +-- @usebeautiful beautiful.titlebar_ontop_button_normal_active_press +-- @usebeautiful beautiful.titlebar_ontop_button_focus_active +-- @usebeautiful beautiful.titlebar_ontop_button_focus_active_hover +-- @usebeautiful beautiful.titlebar_ontop_button_focus_active_press +-- @usebeautiful beautiful.titlebar_ontop_button_normal_inactive +-- @usebeautiful beautiful.titlebar_ontop_button_normal_inactive_hover +-- @usebeautiful beautiful.titlebar_ontop_button_normal_inactive_press +-- @usebeautiful beautiful.titlebar_ontop_button_focus_inactive +-- @usebeautiful beautiful.titlebar_ontop_button_focus_inactive_hover +-- @usebeautiful beautiful.titlebar_ontop_button_focus_inactive_press function titlebar.widget.ontopbutton(c) local widget = titlebar.widget.button(c, "ontop", function(cl) return cl.ontop end, @@ -889,8 +1048,22 @@ function titlebar.widget.ontopbutton(c) end --- Create a new sticky button for a client. --- @param c The client for which the button is wanted. -- @constructorfct awful.titlebar.widget.stickybutton +-- @tparam client c The client for which the button is wanted. +-- @usebeautiful beautiful.titlebar_sticky_button_normal +-- @usebeautiful beautiful.titlebar_sticky_button_focus +-- @usebeautiful beautiful.titlebar_sticky_button_normal_active +-- @usebeautiful beautiful.titlebar_sticky_button_normal_active_hover +-- @usebeautiful beautiful.titlebar_sticky_button_normal_active_press +-- @usebeautiful beautiful.titlebar_sticky_button_focus_active +-- @usebeautiful beautiful.titlebar_sticky_button_focus_active_hover +-- @usebeautiful beautiful.titlebar_sticky_button_focus_active_press +-- @usebeautiful beautiful.titlebar_sticky_button_normal_inactive +-- @usebeautiful beautiful.titlebar_sticky_button_normal_inactive_hover +-- @usebeautiful beautiful.titlebar_sticky_button_normal_inactive_press +-- @usebeautiful beautiful.titlebar_sticky_button_focus_inactive +-- @usebeautiful beautiful.titlebar_sticky_button_focus_inactive_hover +-- @usebeautiful beautiful.titlebar_sticky_button_focus_inactive_press function titlebar.widget.stickybutton(c) local widget = titlebar.widget.button(c, "sticky", function(cl) return cl.sticky end, diff --git a/lib/awful/tooltip.lua b/lib/awful/tooltip.lua index d025fa8ae..2dfe67d35 100644 --- a/lib/awful/tooltip.lua +++ b/lib/awful/tooltip.lua @@ -107,7 +107,7 @@ local offset = { --- The tooltip opacity. -- @beautiful beautiful.tooltip_opacity --- @param number opacity Between 0 and 1 +-- @tparam number opacity Between 0 and 1 --- The tooltip margins. -- @beautiful beautiful.tooltip_gaps @@ -206,7 +206,8 @@ end --- The wibox containing the tooltip widgets. -- @property wibox --- @param wibox +-- @tparam wibox wibox +-- @propertydefault Autogenerated. function tooltip:get_wibox() if self._private.wibox then @@ -229,7 +230,7 @@ end --- Is the tooltip visible? -- @property visible --- @param boolean +-- @tparam[opt=true] boolean visible -- @propemits true false function tooltip:get_visible() @@ -257,27 +258,24 @@ end -- -- @DOC_awful_tooltip_align2_EXAMPLE@ -- --- The following values are valid: --- --- * top_left --- * left --- * bottom_left --- * right --- * top_right --- * bottom_right --- * bottom --- * top --- -- @property align --- @param string --- @see mode --- @see preferred_positions +-- @tparam[opt="right"] string|nil align +-- @propertyvalue "top_left" +-- @propertyvalue "left" +-- @propertyvalue "bottom_left" +-- @propertyvalue "right" +-- @propertyvalue "top_right" +-- @propertyvalue "bottom_right" +-- @propertyvalue "bottom" +-- @propertyvalue "top" -- @propemits true false -- @propbeautiful +-- @see mode +-- @see preferred_positions --- The default tooltip alignment. -- @beautiful beautiful.tooltip_align --- @param string +-- @tparam string tooltip_align -- @see align function tooltip:get_align() @@ -300,7 +298,7 @@ end -- @DOC_awful_tooltip_shape_EXAMPLE@ -- -- @property shape --- @tparam gears.shape shape +-- @tparam[opt=gears.shape.rectangle] shap|nil shape -- @see gears.shape -- @propemits true false -- @propbeautiful @@ -324,13 +322,10 @@ end -- -- @DOC_awful_tooltip_mode2_EXAMPLE@ -- --- Valid modes are: --- --- * "mouse": Next to the mouse cursor --- * "outside": Outside of the widget --- -- @property mode --- @param string +-- @tparam[opt="mouse"] string mode +-- @propertyvalue "mouse" Next to the mouse cursor. +-- @propertyvalue "outside" Outside of the widget. -- @propemits true false function tooltip:set_mode(mode) @@ -358,12 +353,10 @@ end -- * "left" -- * "bottom" -- --- The default is: --- --- {"top", "right", "left", "bottom"} --- -- @property preferred_positions -- @tparam table preferred_positions The position, ordered by priorities +-- @propertydefault `{"top", "right", "left", "bottom"}` +-- @tablerowtype A list of strings. -- @propemits true false -- @see align -- @see mode @@ -401,16 +394,14 @@ end -- -- The valid table values are: -- --- * front --- * middle --- * back --- --- The default is: --- --- {"front", "back", "middle"} +-- * "front" +-- * "middle" +-- * "back" -- -- @property preferred_alignments --- @param string +-- @tparam table preferred_alignments +-- @tablerowtype A list of strings. +-- @propertydefault `{"front", "back", "middle"}` -- @propemits true false -- @see preferred_positions @@ -430,7 +421,7 @@ end --- Change displayed text. -- -- @property text --- @tparam string text New tooltip text, passed to +-- @tparam[opt=""] string text New tooltip text, passed to -- `wibox.widget.textbox.set_text`. -- @propemits true false -- @see wibox.widget.textbox @@ -447,7 +438,7 @@ end --- Change displayed markup. -- -- @property markup --- @tparam string text New tooltip markup, passed to +-- @tparam[opt=""] string markup New tooltip markup, passed to -- `wibox.widget.textbox.set_markup`. -- @propemits true false -- @see wibox.widget.textbox @@ -464,7 +455,9 @@ end --- Change the tooltip's update interval. -- -- @property timeout --- @tparam number timeout The timeout value. +-- @tparam[opt=1] number timeout +-- @negativeallowed false +-- @propertyunit second -- @propemits true false function tooltip:set_timeout(timeout) @@ -479,7 +472,15 @@ end -- @DOC_awful_tooltip_margins_EXAMPLE@ -- -- @property margins --- @tparam number|table New margins value. +-- @tparam[opt=0] number|table margins +-- @tparam[opt=0] number margins.top +-- @tparam[opt=0] number margins.bottom +-- @tparam[opt=0] number margins.left +-- @tparam[opt=0] number margins.right +-- @negativeallowed true +-- @propertyunit pixel +-- @propertytype number A single value for each sides. +-- @propertytype table A different value for each side. -- @propemits true false function tooltip:set_margins(val) @@ -492,7 +493,9 @@ end -- @DOC_awful_tooltip_border_width_EXAMPLE@ -- -- @property border_width --- @param number +-- @tparam[opt=0] number|nil border_width +-- @negativeallowed false +-- @propertyunit pixel -- @propemits true false -- @propbeautiful @@ -506,8 +509,10 @@ end -- @DOC_awful_tooltip_border_color_EXAMPLE@ -- -- @property border_color --- @param color +-- @tparam[opt=beautiful.tooltip_border_color or beautiful.border_color_normal or beautiful.fg_normal] +-- color|nil border_color -- @propemits true false +-- @propbeautiful function tooltip:set_border_color(val) self.widget.border_color = val @@ -519,8 +524,12 @@ end -- @DOC_awful_tooltip_margins_leftright_EXAMPLE@ -- -- @property margins_leftright --- @tparam number New margins value. +-- @tparam[opt=0] number margins_leftright +-- @negativeallowed true +-- @propertyunit pixel -- @propemits true false +-- @see margins +-- @see margins_topbottom function tooltip:set_margin_leftright(val) self.marginbox:set_left(val) @@ -538,8 +547,12 @@ end -- @DOC_awful_tooltip_margins_topbottom_EXAMPLE@ -- -- @property margins_topbottom --- @tparam number New margins value. +-- @tparam[opt=0] number margins_topbottom +-- @negativeallowed true +-- @propertyunit pixel -- @propemits true false +-- @see margins +-- @see margins_leftright function tooltip:set_margin_topbottom(val) self.marginbox:set_top(val) @@ -557,8 +570,17 @@ end -- @DOC_awful_tooltip_gaps_EXAMPLE@ -- -- @property gaps --- @tparam number|table New margins value. +-- @tparam[opt=0] number|table|nil gaps +-- @tparam[opt=0] number gaps.top +-- @tparam[opt=0] number gaps.bottom +-- @tparam[opt=0] number gaps.left +-- @tparam[opt=0] number gaps.right +-- @negativeallowed true +-- @propertytype number A single value for each sides. +-- @propertytype table A different value for each side. +-- @propertyunit pixel -- @propemits true false +-- @propbeautiful function tooltip:set_gaps(val) self._private.gaps = val @@ -570,9 +592,9 @@ end --- Add tooltip to an object. -- --- @tparam tooltip self The tooltip. -- @tparam gears.object obj An object with `mouse::enter` and -- `mouse::leave` signals. +-- @noreturn -- @method add_to_object function tooltip:add_to_object(obj) if not obj then return end @@ -583,9 +605,9 @@ end --- Remove tooltip from an object. -- --- @tparam tooltip self The tooltip. -- @tparam gears.object obj An object with `mouse::enter` and -- `mouse::leave` signals. +-- @noreturn -- @method remove_from_object function tooltip:remove_from_object(obj) obj:disconnect_signal("mouse::enter", self.show) @@ -617,14 +639,14 @@ end -- @tparam[opt=apply_dpi(5)] integer args.margin_leftright The left/right margin for the text. -- @tparam[opt=apply_dpi(3)] integer args.margin_topbottom The top/bottom margin for the text. -- @tparam[opt=nil] gears.shape args.shape The shape. --- @tparam[opt] string args.bg The background color. --- @tparam[opt] string args.fg The foreground color. --- @tparam[opt] string args.border_color The tooltip border color. --- @tparam[opt] number args.border_width The tooltip border width. +-- @tparam[opt=beautiful.tooltip_bg] string args.bg The background color. +-- @tparam[opt=beautiful.tooltip_fg] string args.fg The foreground color. +-- @tparam[opt=beautiful.tooltip_border_color] string args.border_color The tooltip border color. +-- @tparam[opt=beautiful.tooltip_border_width] number args.border_width The tooltip border width. -- @tparam[opt] string args.align The horizontal alignment. --- @tparam[opt] string args.font The tooltip font. --- @tparam[opt] number args.opacity The tooltip opacity. --- @tparam[opt] table|number args.gaps The tooltip margins. +-- @tparam[opt=beautiful.tooltip_font] string args.font The tooltip font. +-- @tparam[opt=beautiful.tooltip_opacity] number args.opacity The tooltip opacity. +-- @tparam[opt=beautiful.tooltip_gaps] table|number args.gaps The tooltip margins. -- @treturn awful.tooltip The created tooltip. -- @see add_to_object -- @see timeout @@ -633,6 +655,8 @@ end -- @see align -- @constructorfct awful.tooltip function tooltip.new(args) + args = args or {} + -- gears.object, properties are linked to set_/get_ functions local self = object { enable_properties = true, diff --git a/lib/awful/util.lua b/lib/awful/util.lua index 3d4677c7a..70ac0607b 100644 --- a/lib/awful/util.lua +++ b/lib/awful/util.lua @@ -1,5 +1,8 @@ --------------------------------------------------------------------------- ---- Utility module for awful. +--- Various small utility functions not worth putting into new modules. +-- +-- Most functions in this module are eventually moved into new modules are +-- deprecated. -- -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008 Julien Danjou @@ -19,11 +22,7 @@ local gstring = require("gears.string") local grect = require("gears.geometry").rectangle local gcolor = require("gears.color") local gfs = require("gears.filesystem") -local capi = -{ - awesome = awesome, - mouse = mouse -} +local capi = { awesome = awesome } local gdebug = require("gears.debug") local gmath = require("gears.math") @@ -38,6 +37,7 @@ util.shell = os.getenv("SHELL") or "/bin/sh" -- This function implementation **has been removed** and no longer -- do anything. Use `awful.spawn.easy_async`. -- @deprecated awful.util.pread +-- @see awful.spawn.easy_async --- Display a deprecation notice, but only once per traceback. -- @deprecated deprecate @@ -99,6 +99,12 @@ function util.mkdir(dir) end --- Eval Lua code. +-- +-- It can either be "real" code or expressions like `2 ~= 3`. +-- If the expression cannot be interpreted or returns false, this +-- function calls `error`. +-- +-- @tparam string code The code to evaluate. -- @return The return value of Lua code. -- @staticfct awful.util.eval function util.eval(s) @@ -128,7 +134,7 @@ end --- Check if a file is a Lua valid file. -- This is done by loading the content and compiling it with loadfile(). --- @param path The file path. +-- @tparam string path The file path. -- @return A function if everything is alright, a string with the error -- otherwise. -- @staticfct awful.util.checkfile @@ -222,13 +228,16 @@ function util.getdir(d) end --- Search for an icon and return the full path. +-- -- It searches for the icon path under the given directories with respect to the -- given extensions for the icon filename. --- @param iconname The name of the icon to search for. --- @param exts Table of image extensions allowed, otherwise { 'png', gif' } --- @param dirs Table of dirs to search, otherwise { '/usr/share/pixmaps/' } +-- @tparam string iconname The name of the icon to search for. +-- @tparam[opt={'png','gif'}] table exts Table of image extensions allowed. +-- @tparam[opt={'/usr/share/pixmaps/','/usr/share/icons/hicolor/'}] table dirs +-- Table of dirs to search. -- @tparam[opt] string size The size. If this is specified, subdirectories `x` -- of the dirs are searched first. +-- @treturn string|nil The icon path or `nil` if not found. -- @staticfct awful.util.geticonpath function util.geticonpath(iconname, exts, dirs, size) exts = exts or { 'png', 'gif' } @@ -326,8 +335,8 @@ end -- -- Note that this method doesn't copy entries found in `__index`. -- @deprecated util.table.crush --- @tparam table t the table to be overridden --- @tparam table set the table used to override members of `t` +-- @tparam table t The table to be overridden +-- @tparam table set The table used to override members of `t` -- @tparam[opt=false] boolean raw Use rawset (avoid the metatable) -- @treturn table t (for convenience) -- @see gears.table @@ -387,7 +396,7 @@ end --- Get a sorted table with all keys from a table. -- @deprecated util.table.keys --- @param t the table for which the keys to get +-- @param t The table for which the keys to get -- @return A table with keys -- @see gears.table function util.table.keys(t) @@ -398,7 +407,7 @@ end --- Filter a tables keys for certain content types -- @deprecated util.table.keys_filter -- @param t The table to retrieve the keys for --- @param ... the types to look for +-- @param ... The types to look for -- @return A filtered table with keys -- @see gears.table function util.table.keys_filter(t, ...) @@ -408,7 +417,7 @@ end --- Reverse a table -- @deprecated util.table.reverse --- @param t the table to reverse +-- @param t The table to reverse -- @return the reversed table -- @see gears.table function util.table.reverse(t) @@ -418,7 +427,7 @@ end --- Clone a table -- @deprecated util.table.clone --- @param t the table to clone +-- @param t The table to clone -- @param deep Create a deep clone? (default: true) -- @return a clone of t -- @see gears.table @@ -432,9 +441,9 @@ end -- given index, all elements of a table that match a given criteria. -- -- @deprecated util.table.iterate --- @param t the table to iterate --- @param filter a function that returns true to indicate a positive match --- @param start what index to start iterating from. Default is 1 (=> start of +-- @tparam table t The table to iterate. +-- @tparam function filter A function that returns true to indicate a positive match +-- @param start What index to start iterating from. Default is 1 (=> start of -- the table) -- @see gears.table function util.table.iterate(t, filter, start) @@ -445,8 +454,8 @@ end --- Merge items from the one table to another one -- @deprecated util.table.merge --- @tparam table t the container table --- @tparam table set the mixin table +-- @tparam table t The container table +-- @tparam table set The mixin table -- @treturn table Return `t` for convenience -- @see gears.table function util.table.merge(t, set) diff --git a/lib/awful/wallpaper.lua b/lib/awful/wallpaper.lua index e9374d1ba..285bc8c01 100644 --- a/lib/awful/wallpaper.lua +++ b/lib/awful/wallpaper.lua @@ -329,7 +329,6 @@ local function paint() cr:rectangle(area.x, area.y, area.width, area.height) cr:fill() end - end if not wall._private.container then @@ -413,7 +412,7 @@ end) -- wallpaper will be defined as a normal `wibox` widget tree. -- -- @property widget --- @tparam wibox.widget widget +-- @tparam[opt=nil] widget|nil widget -- @see wibox.widget.imagebox -- @see wibox.container.tile @@ -434,7 +433,9 @@ end) -- @DOC_awful_wallpaper_dpi1_EXAMPLE@ -- -- @property dpi --- @tparam[opt=screen.dpi] number dpi +-- @tparam[opt=self.screen.dpi] number dpi +-- @propertyunit pixel\_per\_inch +-- @negativeallowed false -- @see screen -- @see screen.dpi @@ -445,6 +446,7 @@ end) -- -- @property screen -- @tparam screen screen +-- @propertydefault Obtained from the constructor. -- @see screens -- @see add_screen -- @see remove_screen @@ -455,7 +457,8 @@ end) -- -- Some large wallpaper are made to span multiple screens. -- @property screens --- @tparam table screens +-- @tparam[opt={self.screen}] table screens +-- @tablerowtype A list of `screen` objects. -- @see screen -- @see add_screen -- @see remove_screen @@ -464,12 +467,13 @@ end) --- The background color. -- -- It will be used as the "fill" color if the `image` doesn't take all the --- screen space. It will also be the default background for the `widget. +-- screen space. It will also be the default background for the `widget`. -- -- As usual with colors in `AwesomeWM`, it can also be a gradient or a pattern. -- -- @property bg --- @tparam gears.color bg +-- @tparam[opt=beautiful.wallpaper_bg] color bg +-- @usebeautiful beautiful.wallpaper_bg -- @see gears.color --- The foreground color. @@ -479,12 +483,13 @@ end) -- As usual with colors in `AwesomeWM`, it can also be a gradient or a pattern. -- -- @property fg --- @tparam gears.color fg +-- @tparam[opt=beautiful.wallpaper_fg] color fg -- @see gears.color --- The default wallpaper background color. -- @beautiful beautiful.wallpaper_bg --- @tparam gears.color wallpaper_bg +-- @tparam color wallpaper_bg +-- @usebeautiful beautiful.wallpaper_fg -- @see bg --- The default wallpaper foreground color. @@ -519,18 +524,23 @@ end) -- @DOC_awful_wallpaper_padding1_EXAMPLE@ -- -- @property honor_padding --- @tparam boolean honor_padding +-- @tparam[opt=false] boolean honor_padding -- @see honor_workarea -- @see uncovered_areas --- Returns the list of screen(s) area which won't be covered by the wallpaper. -- -- When `honor_workarea`, `honor_padding` or panning are used, some section of --- the screen won't have a wallpaper. This returns a list of areas tables. Each --- table has a `x`, `y`, `width` and `height` key. +-- the screen won't have a wallpaper. -- -- @property uncovered_areas -- @tparam table uncovered_areas +-- @propertydefault This depends on the `honor_workarea` and `honor_padding` values. +-- @tablerowtype A list of area tables with the following keys: +-- @tablerowkey number x +-- @tablerowkey number y +-- @tablerowkey number width +-- @tablerowkey number height -- @see honor_workarea -- @see honor_padding -- @see uncovered_areas_color @@ -545,7 +555,7 @@ end) -- color or a gradient. -- -- @property uncovered_areas_color --- @tparam gears.color uncovered_areas_color +-- @tparam[opt="transparent"] color uncovered_areas_color -- @see uncovered_areas --- Defines where the wallpaper is placed when there is multiple screens. @@ -590,7 +600,15 @@ end) -- @DOC_awful_wallpaper_panning_custom_EXAMPLE@ -- -- @property panning_area --- @tparam function|string panning_area +-- @tparam[opt="outer"] function|string panning_area +-- @propertytype string A panning algorithm +-- @propertyvalue "outer" +-- @propertyvalue "inner" +-- @propertyvalue "inner_horizontal" +-- @propertyvalue "inner_vertical" +-- @propertytype function Custom panning function. +-- @functionparam awful.wallpaper wallpaper The wallpaper object. +-- @functionreturn A table with `x`, `y`, `width` and `height` keys, -- @see uncovered_areas function module:set_panning_area(value) @@ -711,6 +729,7 @@ end -- -- @method add_screen -- @tparam screen screen The screen object. +-- @noreturn -- @see remove_screen function module:add_screen(s) s = get_screen(s) @@ -739,6 +758,7 @@ end -- wallpaper will have an overlap. -- -- @method detach +-- @noreturn -- @see remove_screen -- @see add_screen function module:detach() @@ -762,6 +782,7 @@ end -- really need to repaint the wallpaper, call this method. -- -- @method repaint +-- @noreturn function module:repaint() for _, s in ipairs(self._private.screens) do pending_repaint[s] = true @@ -789,21 +810,28 @@ end -- -- @method remove_screen -- @tparam screen screen The screen to remove. +-- @treturn boolean `true` if the screen was removed and `false` if the screen +-- wasn't found. -- @see detach -- @see add_screen -- @see screens function module:remove_screen(s) + local ret = false + s = get_screen(s) for k, s2 in ipairs(self._private.screens) do if s == s2 then table.remove(self._private.screens, k) + ret = true end end backgrounds[s] = nil self:repaint() + + return ret end --- Create a wallpaper. diff --git a/lib/awful/wibar.lua b/lib/awful/wibar.lua index b3043a117..470868d9b 100644 --- a/lib/awful/wibar.lua +++ b/lib/awful/wibar.lua @@ -62,25 +62,22 @@ local align_map = { -- @DOC_awful_wibar_stretch_EXAMPLE@ -- -- @property stretch --- @tparam boolean stretch +-- @tparam[opt=true] boolean|nil stretch -- @propbeautiful -- @propemits true false -- @see align --- How to align non-stretched wibars. -- --- Values are: --- --- * `"top"` --- * `"bottom"` --- * `"left"` --- * `"right"` --- * `"centered"` --- -- @DOC_awful_wibar_align_EXAMPLE@ -- -- @property align --- @tparam string align +-- @tparam[opt="centered"] string|nil align +-- @propertyvalue "top" +-- @propertyvalue "bottom" +-- @propertyvalue "left" +-- @propertyvalue "right" +-- @propertyvalue "centered" -- @propbeautiful -- @propemits true false -- @see stretch @@ -93,7 +90,16 @@ local align_map = { -- @DOC_awful_wibar_margins_EXAMPLE@ -- -- @property margins --- @tparam number|table margins +-- @tparam[opt=0] number|table|nil margins +-- @tparam[opt=0] number margins.left +-- @tparam[opt=0] number margins.right +-- @tparam[opt=0] number margins.top +-- @tparam[opt=0] number margins.bottom +-- @negativeallowed true +-- @propertytype number A single value for each side. +-- @propertytype table A different value for each side. +-- @propertytype nil Fallback to `beautiful.wibar_margins`. +-- @propertyunit pixel -- @propbeautiful -- @propemits true false @@ -281,17 +287,14 @@ end --- The wibox position. -- --- The valid values are: --- --- * left --- * right --- * top --- * bottom --- -- @DOC_awful_wibar_position_EXAMPLE@ -- -- @property position --- @tparam string position Either "left", right", "top" or "bottom" +-- @tparam[opt="top"] string position +-- @propertyvalue "left" +-- @propertyvalue "right" +-- @propertyvalue "top" +-- @propertyvalue "bottom" -- @propemits true false function awfulwibar.get_position(wb) @@ -442,6 +445,7 @@ end --- Remove a wibar. -- @method remove +-- @noreturn function awfulwibar.remove(self) self.visible = false @@ -537,6 +541,19 @@ end --@DOC_wibox_constructor_COMMON@ -- @return The new wibar -- @constructorfct awful.wibar +-- @usebeautiful beautiful.wibar_favor_vertical +-- @usebeautiful beautiful.wibar_border_width +-- @usebeautiful beautiful.wibar_border_color +-- @usebeautiful beautiful.wibar_ontop +-- @usebeautiful beautiful.wibar_cursor +-- @usebeautiful beautiful.wibar_opacity +-- @usebeautiful beautiful.wibar_type +-- @usebeautiful beautiful.wibar_width +-- @usebeautiful beautiful.wibar_height +-- @usebeautiful beautiful.wibar_bg +-- @usebeautiful beautiful.wibar_bgimage +-- @usebeautiful beautiful.wibar_fg +-- @usebeautiful beautiful.wibar_shape function awfulwibar.new(args) args = args or {} local position = args.position or "top" @@ -658,10 +675,6 @@ function awfulwibar.mt:__index(_, k) end end ---@DOC_wibox_COMMON@ - ---@DOC_object_COMMON@ - return setmetatable(awfulwibar, awfulwibar.mt) -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/lib/awful/widget/button.lua b/lib/awful/widget/button.lua index c5b4282bd..c71dc8831 100644 --- a/lib/awful/widget/button.lua +++ b/lib/awful/widget/button.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- --- A simple button widget. +-- A simple button widget based on a background image. -- -- @DOC_wibox_awidget_defaults_button_EXAMPLE@ -- diff --git a/lib/awful/widget/calendar_popup.lua b/lib/awful/widget/calendar_popup.lua index 6da667ae0..19f96a373 100644 --- a/lib/awful/widget/calendar_popup.lua +++ b/lib/awful/widget/calendar_popup.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- --- A calendar popup wibox. +-- A popup wibox containing a `wibox.widget.calendar` widget. -- -- Display a month or year calendar popup using `calendar_popup.month` or `calendar_popup.year`. -- The calendar style can be tweaked by providing tables of style properties at creation: @@ -141,8 +141,10 @@ local function parse_cell_options(cell, args) props[prop] = args[prop] or beautiful["calendar_" .. cell .. "_" .. prop] or bl_style[prop] or default end if cell == "focus" and props.markup == nil then - local fg = props.fg_color and string.format('foreground="%s"', props.fg_color) or "" - local bg = props.bg_color and string.format('background="%s"', props.bg_color) or "" + local fg = props.fg_color + and string.format('foreground="%s"', gears.color.to_rgba_string(props.fg_color)) or "" + local bg = props.bg_color + and string.format('background="%s"', gears.color.to_rgba_string(props.bg_color)) or "" props.markup = string.format( '%s', fg, bg, "%s" @@ -238,10 +240,12 @@ function calendar_popup:call_calendar(offset, position, screen) end --- Toggle calendar visibility. +-- @treturn boolean The new value of `visible`. -- @method toggle function calendar_popup:toggle() self:call_calendar(0) self.visible = not self.visible + return self.visible end --- Attach the calendar to a widget to display at a specific position. @@ -384,6 +388,7 @@ end -- @tparam table args.style_focus Cell style for the current day cell (see `cell_properties`) -- @treturn wibox A wibox containing the calendar -- @constructorfct awful.widget.calendar_popup.month +-- @usebeautiful beautiful.calendar_style function calendar_popup.month(args) return get_cal_wibox("month", args) end @@ -426,4 +431,4 @@ end return setmetatable(calendar_popup, calendar_popup.mt) --- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 \ No newline at end of file +-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/lib/awful/widget/clienticon.lua b/lib/awful/widget/clienticon.lua index 1ddc3f1bb..3076256fa 100644 --- a/lib/awful/widget/clienticon.lua +++ b/lib/awful/widget/clienticon.lua @@ -86,7 +86,7 @@ end --- The widget's @{client}. -- -- @property client --- @param client +-- @tparam[opt=nil] client|nil client -- @propemits true false function clienticon:get_client() diff --git a/lib/awful/widget/common.lua b/lib/awful/widget/common.lua index c45143fa4..ef665229d 100644 --- a/lib/awful/widget/common.lua +++ b/lib/awful/widget/common.lua @@ -1,4 +1,10 @@ --------------------------------------------------------------------------- +-- This module contains helper functions to manage a layout widgets. +-- +-- This is the boilerplate code to manage a "list" of objects and display +-- them in a `wibox.layout`. It uses signals to detect when an object change +-- and its widget be updated. +-- -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008-2009 Julien Danjou -- @classmod awful.widget.common diff --git a/lib/awful/widget/keyboardlayout.lua b/lib/awful/widget/keyboardlayout.lua index ecb2a26e1..486259901 100644 --- a/lib/awful/widget/keyboardlayout.lua +++ b/lib/awful/widget/keyboardlayout.lua @@ -1,7 +1,11 @@ --------------------------------------------------------------------------- +-- Display the current keyboard layout name in a widget. +-- +-- -- @author Aleksey Fedotov <lexa@cfotr.com> -- @copyright 2015 Aleksey Fedotov -- @widgetmod awful.widget.keyboardlayout +-- @supermodule wibox.widget.base --------------------------------------------------------------------------- local capi = {awesome = awesome} @@ -132,7 +136,7 @@ end -- Create an array whose element is a table consisting of the four fields: -- vendor, file, section and group_idx, which all correspond to the -- xkb_symbols pattern "vendor/file(section):group_idx". --- @tparam string group_names The string awesome.xkb_get_group_names() returns. +-- @tparam string group_names The string `awesome.xkb_get_group_names()` returns. -- @treturn table An array of tables whose keys are vendor, file, section, and group_idx. -- @staticfct awful.keyboardlayout.get_groups_from_group_names function keyboardlayout.get_groups_from_group_names(group_names) @@ -253,6 +257,7 @@ local function update_layout(self) end --- Select the next layout. +-- @noreturn -- @method next_layout --- Create a keyboard layout widget. @@ -260,7 +265,7 @@ end -- It shows current keyboard layout name in a textbox. -- -- @constructorfct awful.widget.keyboardlayout --- @return A keyboard layout widget. +-- @treturn awful.widget.keyboardlayout A keyboard layout widget. function keyboardlayout.new() local widget = textbox() local self = widget_base.make_widget(widget, nil, {enable_properties=true}) @@ -313,9 +318,6 @@ function keyboardlayout.mt:__call(...) return _instance end ---@DOC_widget_COMMON@ - ---@DOC_object_COMMON@ return setmetatable(keyboardlayout, keyboardlayout.mt) diff --git a/lib/awful/widget/layoutbox.lua b/lib/awful/widget/layoutbox.lua index a12d892cb..a25a74c46 100644 --- a/lib/awful/widget/layoutbox.lua +++ b/lib/awful/widget/layoutbox.lua @@ -47,6 +47,7 @@ end --- Create a layoutbox widget. It draws a picture with the current layout -- symbol of the current tag. +-- @constructorfct awful.widget.layoutbox -- @tparam table args The arguments. -- @tparam screen args.screen The screen number that the layout will be represented for. -- @tparam table args.buttons The `awful.button`s for this layoutbox. @@ -114,10 +115,6 @@ function layoutbox.mt:__call(...) return layoutbox.new(...) end ---@DOC_widget_COMMON@ - ---@DOC_object_COMMON@ - return setmetatable(layoutbox, layoutbox.mt) -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/lib/awful/widget/layoutlist.lua b/lib/awful/widget/layoutlist.lua index 5fac6cd86..c3abbb618 100644 --- a/lib/awful/widget/layoutlist.lua +++ b/lib/awful/widget/layoutlist.lua @@ -33,6 +33,7 @@ local gtable = require("gears.table") local beautiful= require("beautiful") local alayout = require("awful.layout") local surface = require("gears.surface") +local gcolor = require("gears.color") local module = {} @@ -84,7 +85,7 @@ local function wb_label(item, _, textbox) local text = "" if item.name then - text = ""..item.name..'' + text = ""..item.name..'' end return text, bg, nil, item.icon, { @@ -177,33 +178,37 @@ end local layoutlist = {} --- The layoutlist default widget layout. +-- -- If no layout is specified, a `wibox.layout.fixed.vertical` will be created -- automatically. -- @property base_layout --- @param widget +-- @tparam[opt=wibox.layout.fixed.vertical] wibox.layout base_layout -- @propemits true false -- @see wibox.layout.fixed.vertical -- @see base_layout --- The delegate widget template. +-- -- @property widget_template --- @param table +-- @tparam[opt=nil] template|nil widget_template -- @propemits true false --- The layoutlist screen. +-- -- @property screen --- @param screen +-- @tparam screen screen +-- @propertydefault Obtained from the constructor. --- A function that returns the list of layout to display. -- -- @property source --- @param[opt=awful.widget.layoutlist.source.for_screen] function - ---- The layoutlist filter function. --- @property filter --- @param[opt=awful.widget.layoutlist.source.for_screen] function +-- @tparam[opt=awful.widget.layoutlist.source.for_screen] function source +-- @functionparam screen s The layoutlist screen. +-- @functionparam table metadata Various metadata. +-- @functionreturn table The list of layouts. --- The default foreground (text) color. +-- -- @beautiful beautiful.layoutlist_fg_normal -- @tparam[opt=nil] string|pattern fg_normal -- @see gears.color @@ -237,7 +242,7 @@ local layoutlist = {} --- The selected layout alignment. -- @beautiful beautiful.layoutlist_align --- @tparam[opt=left] string align *left*, *right* or *center* +-- @tparam[opt="left"] string align *left*, *right* or *center* --- The selected layout title font. -- @beautiful beautiful.layoutlist_font_selected @@ -275,16 +280,35 @@ local layoutlist = {} --- The currenly displayed layouts. -- @property layouts --- @param table +-- @tparam[opt={}] table layouts +-- @tablerowtype A list of `awful.layout.suit`. --- The currently selected layout. -- @property current_layout --- @param layout +-- @tparam[opt=nil] layout|nil current_layout +-- @readonly + +--- The current number of layouts. +-- +-- @property count +-- @readonly +-- @tparam number count The number of layouts. +-- @propertydefault This current number of layouts. +-- @negativeallowed false +-- @propemits true false function layoutlist:get_layouts() local f = self.source or self._private.source or module.source.for_screen - return f(self.screen) + local ret = f(self.screen) + + if self._private.last_count ~= #ret then + self:emit_signal("property::count", ret, self._private.last_count) + + self._private.last_count = ret + end + + return ret end function layoutlist:get_current_layout() @@ -329,6 +353,14 @@ function layoutlist:set_base_layout(layout) self:emit_signal("property::base_layout", layout) end +function layoutlist:get_count() + if not self._private.last_count then + self._do_() + end + + return self._private.last_count +end + function layoutlist:set_widget_template(widget_template) self._private.widget_template = widget_template @@ -371,22 +403,22 @@ end -- @tparam[opt] table args.widget_template A custom widget to be used for each action. -- @tparam[opt=ascreen.focused()] screen args.screen A screen -- @tparam[opt={}] table args.style Extra look and feel parameters --- @tparam boolean args.style.disable_icon --- @tparam boolean args.style.disable_name --- @tparam string|pattern args.style.fg_normal --- @tparam string|pattern args.style.bg_normal --- @tparam string|pattern args.style.fg_selected --- @tparam string|pattern args.style.bg_selected --- @tparam string args.style.font --- @tparam string args.style.font_selected --- @tparam string args.style.align *left*, *right* or *center* --- @tparam number args.style.spacing --- @tparam gears.shape args.style.shape --- @tparam number args.style.shape_border_width --- @tparam string|pattern args.style.shape_border_color --- @tparam gears.shape args.style.shape_selected --- @tparam string|pattern args.style.shape_border_width_selected --- @tparam string|pattern args.style.shape_border_color_selected +-- @tparam[opt=beautiful.layoutlist_disable_icon] boolean args.style.disable_icon +-- @tparam[opt=beautiful.layoutlist_disable_name] boolean args.style.disable_name +-- @tparam[opt=beautiful.layoutlist_fg_normal] string|pattern args.style.fg_normal +-- @tparam[opt=beautiful.layoutlist_bg_normal] string|pattern args.style.bg_normal +-- @tparam[opt=beautiful.layoutlist_fg_selected] string|pattern args.style.fg_selected +-- @tparam[opt=beautiful.layoutlist_bg_selected] string|pattern args.style.bg_selected +-- @tparam[opt=beautiful.layoutlist_font] string args.style.font +-- @tparam[opt=beautiful.layoutlist_font_selected] string args.style.font_selected +-- @tparam[opt=beautiful.layoutlist_align] string args.style.align *left*, *right* or *center* +-- @tparam[opt=beautiful.layoutlist_spacing] number args.style.spacing +-- @tparam[opt=beautiful.layoutlist_shape] gears.shape args.style.shape +-- @tparam[opt=beautiful.layoutlist_shape_border_width] number args.style.shape_border_width +-- @tparam[opt=beautiful.layoutlist_shape_border_color] string|pattern args.style.shape_border_color +-- @tparam[opt=beautiful.layoutlist_shape_selected] gears.shape args.style.shape_selected +-- @tparam[opt=beautiful.layoutlist_shape_border_width_selected] string|pattern args.style.shape_border_width_selected +-- @tparam[opt=beautiful.layoutlist_shape_border_color_selected] string|pattern args.style.shape_border_color_selected -- @treturn widget The action widget. -- @constructorfct awful.widget.layoutlist diff --git a/lib/awful/widget/only_on_screen.lua b/lib/awful/widget/only_on_screen.lua index 368a6add8..0cbabfde0 100644 --- a/lib/awful/widget/only_on_screen.lua +++ b/lib/awful/widget/only_on_screen.lua @@ -50,7 +50,7 @@ end --- The widget to be displayed -- @property widget --- @tparam widget widget The widget +-- @tparam[opt=nil] widget|nil widget only_on_screen.set_widget = base.set_widget_common @@ -66,10 +66,11 @@ function only_on_screen:set_children(children) self:set_widget(children[1]) end ---- The screen to display on. Can be a screen object, a screen index, a screen +--- The screen to display on. +-- Can be a screen object, a screen index, a screen -- name ("VGA1") or the string "primary" for the primary screen. -- @property screen --- @tparam screen|string|integer screen The screen. +-- @tparam[opt="primary"] screen screen function only_on_screen:set_screen(s) self._private.screen = s @@ -80,11 +81,11 @@ function only_on_screen:get_screen() return self._private.screen end ---- Returns a new only_on_screen container. +--- Returns a new `awful.widget.only_on_screen` container. -- This widget makes some other widget visible on just some screens. Use -- `:set_widget()` to set the widget and `:set_screen()` to set the screen. --- @param[opt] widget The widget to display. --- @param[opt] s The screen to display on. +-- @tparam[opt=nil] widget widget The widget to display. +-- @tparam[opt="primary"] screen s The screen to display on. -- @treturn table A new only_on_screen container -- @constructorfct awful.widget.only_on_screen local function new(widget, s) diff --git a/lib/awful/widget/prompt.lua b/lib/awful/widget/prompt.lua index 4dfaef49f..f1a38257d 100644 --- a/lib/awful/widget/prompt.lua +++ b/lib/awful/widget/prompt.lua @@ -73,7 +73,7 @@ end -- of `awful.spawn`. Depending on the amount of customization to your shell -- environment, this can increase startup time. -- @property with_shell --- @param[opt=false] boolean +-- @tparam[opt=false] boolean with_shell --- Create a prompt widget which will launch a command. -- For additional documentation about `args` parameter, please refer to @@ -85,10 +85,10 @@ end -- Prompt background color. -- @tparam[opt=`beautiful.prompt_fg` or `beautiful.fg_normal`] color args.fg -- Prompt foreground color. --- @tparam[opt] gears.color args.fg_cursor --- @tparam[opt] gears.color args.bg_cursor +-- @tparam[opt=beautiful.prompt_fg_cursor] gears.color args.fg_cursor +-- @tparam[opt=beautiful.prompt_bg_cursor] gears.color args.bg_cursor -- @tparam[opt] gears.color args.ul_cursor --- @tparam[opt] string args.font +-- @tparam[opt=beautiful.prompt_font] string args.font -- @tparam[opt] boolean args.autoexec -- @tparam[opt] function args.highlighter A function to add syntax highlighting -- to the command. @@ -116,6 +116,10 @@ end -- @return An instance of prompt widget, inherits from -- `wibox.container.background`. -- @constructorfct awful.widget.prompt +-- @usebeautiful beautiful.prompt_fg +-- @usebeautiful beautiful.prompt_bg +-- @usebeautiful beautiful.fg_normal When `beautiful.prompt_fg` isn't set. +-- @usebeautiful beautiful.bg_normal When `beautiful.prompt_bg` isn't set. function widgetprompt.new(args) args = args or {} local promptbox = background() diff --git a/lib/awful/widget/taglist.lua b/lib/awful/widget/taglist.lua index b4843f66d..aeb6513ec 100644 --- a/lib/awful/widget/taglist.lua +++ b/lib/awful/widget/taglist.lua @@ -35,6 +35,7 @@ -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008-2009 Julien Danjou -- @widgetmod awful.widget.taglist +-- @supermodule wibox.widget.base --------------------------------------------------------------------------- -- Grab environment we need @@ -54,6 +55,7 @@ local gcolor = require("gears.color") local gstring = require("gears.string") local gdebug = require("gears.debug") local base = require("wibox.widget.base") +local gtable = require("gears.table") local function get_screen(s) return s and capi.screen[s] @@ -64,22 +66,22 @@ taglist.filter, taglist.source = {}, {} --- The tag list main foreground (text) color. -- @beautiful beautiful.taglist_fg_focus --- @param[opt=fg_focus] color +-- @param[opt=beautiful.fg_focus] color -- @see gears.color --- The tag list main background color. -- @beautiful beautiful.taglist_bg_focus --- @param[opt=bg_focus] color +-- @param[opt=beautiful.bg_focus] color -- @see gears.color --- The tag list urgent elements foreground (text) color. -- @beautiful beautiful.taglist_fg_urgent --- @param[opt=fg_urgent] color +-- @param[opt=beautiful.fg_urgent] color -- @see gears.color --- The tag list urgent elements background color. -- @beautiful beautiful.taglist_bg_urgent --- @param[opt=bg_urgent] color +-- @param[opt=beautiful.bg_urgent] color -- @see gears.color --- The tag list occupied elements background color. @@ -250,7 +252,7 @@ function taglist.taglist_label(t, args) local taglist_squares_unsel_empty = args.squares_unsel_empty or theme.taglist_squares_unsel_empty local taglist_squares_resize = theme.taglist_squares_resize or args.squares_resize or "true" local taglist_disable_icon = args.taglist_disable_icon or theme.taglist_disable_icon or false - local font = args.font or theme.taglist_font or theme.font or "" + local font = args.font or theme.taglist_font or theme.font local text = nil local sel = capi.client.focus local bg_color = nil @@ -360,7 +362,7 @@ function taglist.taglist_label(t, args) end if not tag.getproperty(t, "icon_only") then - text = "" + text = "" if fg_color then text = text .. "" .. (gstring.xml_escape(t.name) or "") .. "" @@ -390,10 +392,10 @@ local function create_callback(w, t) common._set_common_property(w, "tag", t) end -local function taglist_update(s, w, buttons, filter, data, style, update_function, args) +local function taglist_update(s, self, buttons, filter, data, style, update_function, args) local tags = {} - local source = args and args.source or taglist.source.for_screen or nil + local source = self._private.source or taglist.source.for_screen or nil local list = source and source(s, args) or s.tags for _, t in ipairs(list) do @@ -402,14 +404,147 @@ local function taglist_update(s, w, buttons, filter, data, style, update_functio end end + if self._private.last_count ~= #tags then + self:emit_signal("property::count", #tags, self._private.last_count) + self._private.last_count = #tags + end + local function label(c) return taglist.taglist_label(c, style) end - update_function(w, buttons, label, data, tags, { - widget_template = args.widget_template, + update_function(self._private.base_layout, buttons, label, data, tags, { + widget_template = self._private.widget_template, create_callback = create_callback, }) end +--- The taglist screen. +-- +-- @property screen +-- @propertydefault Obtained from the constructor. +-- @tparam screen screen + +--- Set the taglist layout. +-- +-- @property base_layout +-- @tparam[opt=wibox.layout.fixed.horizontal] wibox.layout base_layout +-- @see wibox.layout.fixed.horizontal + +--- The current number of tags. +-- +-- Note that the `tasklist` is usually lazy-loaded. Reading this property +-- may cause the widgets to be created. Depending on where the property is called +-- from, it might, in theory, cause an infinite loop. +-- +-- @property count +-- @readonly +-- @tparam number count The number of tags. +-- @propertydefault This current number of tags. +-- @negativeallowed false +-- @propemits true false + +function taglist:set_base_layout(layout) + self._private.base_layout = base.make_widget_from_value( + layout or fixed.horizontal + ) + + local spacing = self._private.style.spacing or beautiful.taglist_spacing + + if self._private.base_layout.set_spacing and spacing then + self._private.base_layout:set_spacing(spacing) + end + + assert(self._private.base_layout.is_widget) + + self._do_taglist_update() + + self:emit_signal("widget::layout_changed") + self:emit_signal("widget::redraw_needed") + self:emit_signal("property::base_layout", layout) +end + +function taglist:get_count() + if not self._private.last_count then + self._do_taglist_update_now() + end + + return self._private.last_count +end + +function taglist:layout(_, width, height) + if self._private.base_layout then + return { base.place_widget_at(self._private.base_layout, 0, 0, width, height) } + end +end + +function taglist:fit(context, width, height) + if not self._private.base_layout then + return 0, 0 + end + + return base.fit_widget(self, context, self._private.base_layout, width, height) +end + +--- An alternative function to configure the content. +-- +-- You should use `widget_template` if it fits your use case first. This +-- API is very low level. +-- +-- @property update_function +-- @tparam function update_function +-- @propertydefault The default function delegate everything to the `widget_template`. +-- @functionparam widget layout The base layout object. +-- @functionparam table buttons The buttons for this tag entry (see below). +-- @functionparam string label The tag name. +-- @functionparam table data Arbitrary metadate. +-- @functionparam table tags The list of tags (ordered). +-- @functionparam table metadata Other values. +-- @functionnoreturn + +--- A function to restrict the content of the taglist. +-- +-- @property filter +-- @tparam[opt=nil] function|nil filter +-- @functionparam tag t The tag to accept or reject. +-- @functionreturn boolean `true` if the tag is accepter or `false` if it is rejected. +-- @see source +-- @see awful.widget.taglist.filter.noempty +-- @see awful.widget.taglist.filter.selected +-- @see awful.widget.taglist.filter.all +-- @see awful.widget.taglist.source.for_screen + +--- The function used to gather the group of tags. +-- +-- @property source +-- @tparam[opt=awful.widget.taglist.source.for_screen] function source +-- @functionparam screen s The taglist screen. +-- @functionparam table metadata Various metadata. +-- @functionreturn table The list of tags +-- @see filter +-- @see awful.widget.taglist.source.for_screen + +--- A templete used to genetate the individual tag widgets. +-- +-- @property widget_template +-- @tparam[opt=nil] template|nil widget_template + +for _, prop in ipairs { "filter", "update_function", "widget_template", "source", "screen" } do + taglist["set_"..prop] = function(self, value) + if value == self._private[prop] then return end + + self._private[prop] = value + + self._do_taglist_update() + + self:emit_signal("widget::layout_changed") + self:emit_signal("widget::redraw_needed") + self:emit_signal("property::"..prop, value) + end + + taglist["get_"..prop] = function(self) + return self._private[prop] + end +end + --- Create a new taglist widget. The last two arguments (update_function -- and layout) serve to customize the layout of the taglist (eg. to -- make it vertical). For that, you will need to copy the @@ -428,39 +563,55 @@ end -- function used to generate the list of tag. -- @tparam[opt] table args.widget_template A custom widget to be used for each tag -- @tparam[opt={}] table args.style The style overrides default theme. --- @tparam[opt=nil] string|pattern args.style.fg_focus --- @tparam[opt=nil] string|pattern args.style.bg_focus --- @tparam[opt=nil] string|pattern args.style.fg_urgent --- @tparam[opt=nil] string|pattern args.style.bg_urgent --- @tparam[opt=nil] string|pattern args.style.bg_occupied --- @tparam[opt=nil] string|pattern args.style.fg_occupied --- @tparam[opt=nil] string|pattern args.style.bg_empty --- @tparam[opt=nil] string|pattern args.style.fg_empty --- @tparam[opt=nil] string|pattern args.style.bg_volatile --- @tparam[opt=nil] string|pattern args.style.fg_volatile --- @tparam[opt=nil] string args.style.squares_sel --- @tparam[opt=nil] string args.style.squares_unsel --- @tparam[opt=nil] string args.style.squares_sel_empty --- @tparam[opt=nil] string args.style.squares_unsel_empty --- @tparam[opt=nil] string args.style.squares_resize --- @tparam[opt=nil] string args.style.disable_icon --- @tparam[opt=nil] string args.style.font --- @tparam[opt=nil] number args.style.spacing The spacing between tags. --- @tparam[opt] string args.style.squares_sel A user provided image for selected squares. --- @tparam[opt] string args.style.squares_unsel A user provided image for unselected squares. --- @tparam[opt] string args.style.squares_sel_empty A user provided image for selected squares for empty tags. --- @tparam[opt] string args.style.squares_unsel_empty A user provided image for unselected squares for empty tags. --- @tparam[opt] boolean args.style.squares_resize True or false to resize squares. --- @tparam string|pattern args.style.bg_focus The background color for focused client. --- @tparam string|pattern args.style.fg_focus The foreground color for focused client. --- @tparam string|pattern args.style.bg_urgent The background color for urgent clients. --- @tparam string|pattern args.style.fg_urgent The foreground color for urgent clients. --- @tparam string args.style.font The font. +-- @tparam[opt=beautiful.taglist_fg_focus] string|pattern args.style.fg_focus +-- @tparam[opt=beautiful.taglist_bg_focus] string|pattern args.style.bg_focus +-- @tparam[opt=beautiful.taglist_fg_urgent] string|pattern args.style.fg_urgent +-- @tparam[opt=beautiful.taglist_bg_urgent] string|pattern args.style.bg_urgent +-- @tparam[opt=beautiful.taglist_bg_occupied] string|pattern args.style.bg_occupied +-- @tparam[opt=beautiful.taglist_fg_occupied] string|pattern args.style.fg_occupied +-- @tparam[opt=beautiful.taglist_bg_empty] string|pattern args.style.bg_empty +-- @tparam[opt=beautiful.taglist_fg_empty] string|pattern args.style.fg_empty +-- @tparam[opt=beautiful.taglist_bg_volatile] string|pattern args.style.bg_volatile +-- @tparam[opt=beautiful.taglist_fg_volatile] string|pattern args.style.fg_volatile +-- @tparam[opt=beautiful.taglist_squares_sel] string args.style.squares_sel +-- @tparam[opt=beautiful.taglist_squares_unsel] string args.style.squares_unsel +-- @tparam[opt=beautiful.taglist_squares_sel_empty] string args.style.squares_sel_empty +-- @tparam[opt=beautiful.taglist_squares_unsel_empty] string args.style.squares_unsel_empty +-- @tparam[opt=beautiful.taglist_squares_resize] string args.style.squares_resize +-- @tparam[opt=beautiful.taglist_disable_icon] string args.style.disable_icon +-- @tparam[opt=beautiful.taglist_font] string args.style.font +-- @tparam[opt=beautiful.taglist_spacing] number args.style.spacing The spacing between tags. +-- @tparam[opt=beautiful.taglist_squares_sel] string args.style.squares_sel A user +-- provided image for selected squares. +-- @tparam[opt=beautiful.taglist_squares_unsel] string args.style.squares_unsel A +-- user provided image for unselected squares. +-- @tparam[opt=beautiful.taglist_squares_sel_empty] string args.style.squares_sel_empty A +-- user provided image for selected squares for empty tags. +-- @tparam[opt=beautiful.taglist_squares_unsel_empty] string args.style.squares_unsel_empty A +-- user provided image for unselected squares for empty tags. +-- @tparam[opt=beautiful.taglist_squares_resize] boolean args.style.squares_resize `true` +-- or `false` to resize squares. +-- @tparam[opt=beautiful.taglist_font] string args.style.font The font. +-- @tparam[opt=beautiful.taglist_shape] gears.shape|function args.style.shape +-- @tparam[opt=beautiful.taglist_shape_border_width] number args.style.shape_border_width +-- @tparam[opt=beautiful.taglist_shape_border_color] string args.style.shape_border_color +-- @tparam[opt=beautiful.taglist_shape_empty] gears.shape|function args.style.shape_empty +-- @tparam[opt=beautiful.taglist_shape_border_width_empty] number args.style.shape_border_width_empty +-- @tparam[opt=beautiful.taglist_shape_border_color_empty] string args.style.border_color_empty +-- @tparam[opt=beautiful.taglist_shape_focus] gears.shape|function args.style.shape_focus +-- @tparam[opt=beautiful.taglist_shape_border_width_focus] number args.style.shape_border_width_focus +-- @tparam[opt=beautiful.taglist_shape_border_color_focus] string args.style.shape_border_color_focus +-- @tparam[opt=beautiful.taglist_shape_urgent] gears.shape|function args.style.shape_urgent +-- @tparam[opt=beautiful.taglist_shape_border_width_urgent] number args.style.shape_border_width_urgent +-- @tparam[opt=beautiful.taglist_shape_border_color_urgent] string args.style.shape_border_color_urgent +-- @tparam[opt=beautiful.taglist_shape_volatile] gears.shape|function args.style.shape_volatile +-- @tparam[opt=beautiful.taglist_shape_border_width_volatile] number args.style.shape_border_width_volatile +-- @tparam[opt=beautiful.taglist_shape_border_color_volatile] string args.style.shape_border_color_volatile -- @param filter **DEPRECATED** use args.filter -- @param buttons **DEPRECATED** use args.buttons -- @param style **DEPRECATED** use args.style -- @param update_function **DEPRECATED** use args.update_function --- @param base_widget **DEPRECATED** use args.base_widget +-- @param base_widget **DEPRECATED** use args.base_layout -- @constructorfct awful.widget.taglist function taglist.new(args, filter, buttons, style, update_function, base_widget) @@ -495,28 +646,41 @@ function taglist.new(args, filter, buttons, style, update_function, base_widget) screen = screen or get_screen(args.screen) local uf = args.update_function or common.list_update - local w = base.make_widget_from_value(args.layout or fixed.horizontal) - if w.set_spacing and (args.style and args.style.spacing or beautiful.taglist_spacing) then - w:set_spacing(args.style and args.style.spacing or beautiful.taglist_spacing) - end + local w = base.make_widget(nil, nil, { + enable_properties = true, + }) + + gtable.crush(w, taglist, true) + + gtable.crush(w._private, { + style = args.style or {}, + buttons = args.buttons, + filter = args.filter, + update_function = args.update_function, + widget_template = args.widget_template, + source = args.source, + screen = screen + }) local data = setmetatable({}, { __mode = 'k' }) local queued_update = {} function w._do_taglist_update_now() - if screen.valid then - taglist_update(screen, w, args.buttons, args.filter, data, args.style, uf, args) + if w._private.screen.valid then + taglist_update( + w._private.screen, w, w._private.buttons, w._private.filter, data, args.style, uf, args + ) end - queued_update[screen] = false + queued_update[w._private.screen] = false end function w._do_taglist_update() -- Add a delayed callback for the first update. - if not queued_update[screen] then + if not queued_update[w._private.screen] then timer.delayed_call(w._do_taglist_update_now) - queued_update[screen] = true + queued_update[w._private.screen] = true end end if instances == nil then @@ -558,6 +722,9 @@ function taglist.new(args, filter, buttons, style, update_function, base_widget) instances[get_screen(s)] = nil end) end + + w:set_base_layout(args.base_layout or args.layout) + w._do_taglist_update() local list = instances[screen] if not list then @@ -605,8 +772,6 @@ function taglist.mt:__call(...) return taglist.new(...) end ---@DOC_widget_COMMON@ - --@DOC_object_COMMON@ return setmetatable(taglist, taglist.mt) diff --git a/lib/awful/widget/tasklist.lua b/lib/awful/widget/tasklist.lua index aea5c23fb..a0b29688c 100644 --- a/lib/awful/widget/tasklist.lua +++ b/lib/awful/widget/tasklist.lua @@ -14,14 +14,14 @@ -- Icon -- Client property -- --- ▪sticky --- ⌃ontop --- ▴above --- ▾below --- ✈floating --- +maximized --- ⬌maximized_horizontal --- ⬍maximized_vertical +-- ▪sticky +-- ⌃ontop +-- ▴above +-- ▾below +-- ✈floating +-- +maximized +-- ⬌maximized_horizontal +-- ⬍maximized_vertical -- -- -- **Customizing the tasklist:** @@ -71,6 +71,7 @@ -- @author Julien Danjou <julien@danjou.info> -- @copyright 2008-2009 Julien Danjou -- @widgetmod awful.widget.tasklist +-- @supermodule wibox.widget.base --------------------------------------------------------------------------- -- Grab environment we need @@ -94,6 +95,7 @@ local wmargin = require("wibox.container.margin") local wtextbox = require("wibox.widget.textbox") local clienticon = require("awful.widget.clienticon") local wbackground = require("wibox.container.background") +local gtable = require("gears.table") local function get_screen(s) return s and screen[s] @@ -104,41 +106,65 @@ local tasklist = { mt = {} } local instances --- The default foreground (text) color. +-- +-- @DOC_wibox_awidget_tasklist_style_fg_normal_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_fg_normal -- @tparam[opt=nil] string|pattern fg_normal -- @see gears.color --- The default background color. +-- +-- @DOC_wibox_awidget_tasklist_style_bg_normal_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_bg_normal -- @tparam[opt=nil] string|pattern bg_normal -- @see gears.color --- The focused client foreground (text) color. +-- +-- @DOC_wibox_awidget_tasklist_style_fg_focus_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_fg_focus -- @tparam[opt=nil] string|pattern fg_focus -- @see gears.color --- The focused client background color. +-- +-- @DOC_wibox_awidget_tasklist_style_bg_focus_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_bg_focus -- @tparam[opt=nil] string|pattern bg_focus -- @see gears.color --- The urgent clients foreground (text) color. +-- +-- @DOC_wibox_awidget_tasklist_style_fg_urgent_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_fg_urgent -- @tparam[opt=nil] string|pattern fg_urgent -- @see gears.color --- The urgent clients background color. +-- +-- @DOC_wibox_awidget_tasklist_style_bg_urgent_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_bg_urgent -- @tparam[opt=nil] string|pattern bg_urgent -- @see gears.color --- The minimized clients foreground (text) color. +-- +-- @DOC_wibox_awidget_tasklist_style_fg_minimize_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_fg_minimize -- @tparam[opt=nil] string|pattern fg_minimize -- @see gears.color --- The minimized clients background color. +-- +-- @DOC_wibox_awidget_tasklist_style_bg_minimize_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_bg_minimize -- @tparam[opt=nil] string|pattern bg_minimize -- @see gears.color @@ -160,10 +186,16 @@ local instances -- @tparam[opt=nil] string bg_image_minimize --- Disable the tasklist client icons. +-- +-- @DOC_wibox_awidget_tasklist_style_disable_icon_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_disable_icon -- @tparam[opt=false] boolean tasklist_disable_icon --- Disable the tasklist client titles. +-- +-- @DOC_wibox_awidget_tasklist_style_disable_task_name_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_disable_task_name -- @tparam[opt=false] boolean tasklist_disable_task_name @@ -171,6 +203,8 @@ local instances -- -- See the Status icons section for more details. -- +-- @DOC_wibox_awidget_tasklist_style_plain_task_name_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_plain_task_name -- @tparam[opt=false] boolean tasklist_plain_task_name @@ -210,110 +244,178 @@ local instances -- @beautiful beautiful.tasklist_minimized -- @tparam[opt=nil] string minimized +--- The focused client alignment. +-- +-- @DOC_wibox_awidget_tasklist_style_align_EXAMPLE@ +-- +-- @beautiful beautiful.tasklist_align +-- @tparam[opt="left"] string align *left*, *right* or *center* + --- The tasklist font. +-- +-- @DOC_wibox_awidget_tasklist_style_font_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_font -- @tparam[opt=nil] string font - ---- The focused client alignment. --- @beautiful beautiful.tasklist_align --- @tparam[opt=left] string align *left*, *right* or *center* +-- @see wibox.widget.textbox.font --- The focused client title alignment. +-- +-- @DOC_wibox_awidget_tasklist_style_font_focus_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_font_focus -- @tparam[opt=nil] string font_focus +-- @see wibox.widget.textbox.font --- The minimized clients font. +-- +-- @DOC_wibox_awidget_tasklist_style_font_minimized_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_font_minimized -- @tparam[opt=nil] string font_minimized +-- @see wibox.widget.textbox.font --- The urgent clients font. +-- +-- @DOC_wibox_awidget_tasklist_style_font_urgent_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_font_urgent -- @tparam[opt=nil] string font_urgent +-- @see wibox.widget.textbox.font --- The space between the tasklist elements. +-- +-- @DOC_wibox_awidget_tasklist_style_spacing_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_spacing -- @tparam[opt=0] number spacing The spacing between tasks. --- The default tasklist elements shape. +-- +-- @DOC_wibox_awidget_tasklist_style_shape_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_shape -- @tparam[opt=nil] gears.shape shape --- The default tasklist elements border width. +-- +-- @DOC_wibox_awidget_tasklist_style_shape_border_width_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_shape_border_width -- @tparam[opt=0] number shape_border_width --- The default tasklist elements border color. +-- +-- @DOC_wibox_awidget_tasklist_style_shape_border_color_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_shape_border_color -- @tparam[opt=nil] string|color shape_border_color -- @see gears.color --- The focused client shape. +-- +-- @DOC_wibox_awidget_tasklist_style_shape_focus_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_shape_focus -- @tparam[opt=nil] gears.shape shape_focus --- The focused client border width. +-- +-- @DOC_wibox_awidget_tasklist_style_shape_focus_border_width_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_shape_border_width_focus -- @tparam[opt=0] number shape_border_width_focus --- The focused client border color. +-- +-- @DOC_wibox_awidget_tasklist_style_shape_focus_border_width_focus_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_shape_border_color_focus -- @tparam[opt=nil] string|color shape_border_color_focus -- @see gears.color --- The minimized clients shape. +-- +-- @DOC_wibox_awidget_tasklist_style_shape_minimized_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_shape_minimized -- @tparam[opt=nil] gears.shape shape_minimized --- The minimized clients border width. +-- +-- @DOC_wibox_awidget_tasklist_style_shape_border_width_minimized_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_shape_border_width_minimized -- @tparam[opt=0] number shape_border_width_minimized --- The minimized clients border color. +-- +-- @DOC_wibox_awidget_tasklist_style_shape_border_color_minimized_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_shape_border_color_minimized -- @tparam[opt=nil] string|color shape_border_color_minimized -- @see gears.color --- The urgent clients shape. +-- +-- @DOC_wibox_awidget_tasklist_style_shape_urgent_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_shape_urgent -- @tparam[opt=nil] gears.shape shape_urgent --- The urgent clients border width. +-- +-- @DOC_wibox_awidget_tasklist_style_shape_border_width_urgent_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_shape_border_width_urgent -- @tparam[opt=0] number shape_border_width_urgent --- The urgent clients border color. +-- +-- @DOC_wibox_awidget_tasklist_style_shape_border_color_urgent_EXAMPLE@ +-- -- @beautiful beautiful.tasklist_shape_border_color_urgent -- @tparam[opt=nil] string|color shape_border_color_urgent -- @see gears.color +--- The icon size. +-- @beautiful beautiful.tasklist_icon_size +-- @tparam[opt=nil] integer tasklist_icon_size + -- Public structures tasklist.filter, tasklist.source = {}, {} -- This is the same template as awful.widget.common, but with an clienticon widget -local default_template = { - { - { - clienticon, - id = "icon_margin_role", - left = dpi(4), - widget = wmargin - }, +local function default_template(self) + local has_no_icon = self._private.style.disable_icon + or self._private.style.tasklist_disable_icon + or beautiful.tasklist_disable_icon + + return { { + (not has_no_icon) and { + clienticon, + id = "icon_margin_role", + left = dpi(4), + widget = wmargin + } or nil, { - id = "text_role", - widget = wtextbox, + { + id = "text_role", + widget = wtextbox, + }, + id = "text_margin_role", + left = dpi(4), + right = dpi(4), + widget = wmargin }, - id = "text_margin_role", - left = dpi(4), - right = dpi(4), - widget = wmargin + fill_space = true, + layout = wfixed.horizontal }, - fill_space = true, - layout = wfixed.horizontal - }, - id = "background_role", - widget = wbackground -} + id = "background_role", + widget = wbackground + } +end local function tasklist_label(c, args, tb) if not args then args = {} end @@ -334,12 +436,13 @@ local function tasklist_label(c, args, tb) local bg_image_focus = args.bg_image_focus or theme.tasklist_bg_image_focus or theme.bg_image_focus local bg_image_urgent = args.bg_image_urgent or theme.tasklist_bg_image_urgent or theme.bg_image_urgent local bg_image_minimize = args.bg_image_minimize or theme.tasklist_bg_image_minimize or theme.bg_image_minimize - local tasklist_disable_icon = args.tasklist_disable_icon or theme.tasklist_disable_icon or false + local tasklist_disable_icon = args.disable_icon or args.tasklist_disable_icon + or theme.tasklist_disable_icon or false local disable_task_name = args.disable_task_name or theme.tasklist_disable_task_name or false - local font = args.font or theme.tasklist_font or theme.font or "" - local font_focus = args.font_focus or theme.tasklist_font_focus or theme.font_focus or font or "" - local font_minimized = args.font_minimized or theme.tasklist_font_minimized or theme.font_minimized or font or "" - local font_urgent = args.font_urgent or theme.tasklist_font_urgent or theme.font_urgent or font or "" + local font = args.font or theme.tasklist_font or theme.font + local font_focus = args.font_focus or theme.tasklist_font_focus or theme.font_focus or font + local font_minimized = args.font_minimized or theme.tasklist_font_minimized or theme.font_minimized or font + local font_urgent = args.font_urgent or theme.tasklist_font_urgent or theme.font_urgent or font local text = "" local name = "" local bg @@ -476,10 +579,10 @@ local function create_callback(w, t) common._set_common_property(w, "client", t) end -local function tasklist_update(s, w, buttons, filter, data, style, update_function, args) +local function tasklist_update(s, self, buttons, filter, data, style, update_function, args) local clients = {} - local source = args and args.source or tasklist.source.all_clients or nil + local source = self.source or tasklist.source.all_clients or nil local list = source and source(s, args) or capi.client.get() for _, c in ipairs(list) do @@ -490,14 +593,219 @@ local function tasklist_update(s, w, buttons, filter, data, style, update_functi end end + if self._private.last_count ~= #clients then + local old = self._private.last_count + self._private.last_count = #clients + self:emit_signal("property::count", #clients, old) + end + local function label(c, tb) return tasklist_label(c, style, tb) end - update_function(w, buttons, label, data, clients, { - widget_template = args.widget_template or default_template, + update_function(self._private.base_layout, buttons, label, data, clients, { + widget_template = self._private.widget_template or default_template(self), create_callback = create_callback, }) end +--- The current number of clients. +-- +-- Note that the `tasklist` is usually lazy-loaded. Reading this property +-- may cause the widgets to be created. Depending on where the property is called +-- from, it might, in theory, cause an infinite loop. +-- +-- @property count +-- @readonly +-- @tparam number count +-- @propertydefault The current number of client. +-- @negativeallowed false +-- @propemits true false + +--- Set the tasklist layout. +-- +-- This can be used to change the layout based on the number of clients: +-- +-- @DOC_sequences_client_tasklist_layout1_EXAMPLE@ +-- +-- @property base_layout +-- @tparam[opt=wibox.layout.flex.horizontal] wibox.layout base_layout +-- @propemits true false +-- @see wibox.layout.flex.horizontal + +--- The tasklist screen. +-- +-- @DOC_sequences_client_tasklist_screen1_EXAMPLE@ +-- +-- @property screen +-- @tparam screen screen +-- @propertydefault Obtained from the constructor. +-- @propemits true false + +--- A function to narrow down the list of clients. +-- +-- @DOC_sequences_client_tasklist_custom_filter1_EXAMPLE@ +-- +-- @property filter +-- @tparam[opt=awful.widget.tasklist.filter.alltags] function filter +-- @functionparam client c The client to accept or reject. +-- @functionparam screen s The value of the tasklist `screen` property. +-- @functionreturn boolean `true` if the client is accepter or `false` if it is rejected. +-- @propemits true false +-- @see awful.widget.tasklist.filter.allscreen +-- @see awful.widget.tasklist.filter.alltags +-- @see awful.widget.tasklist.filter.currenttags +-- @see awful.widget.tasklist.filter.minimizedcurrenttags +-- @see awful.widget.tasklist.filter.focused + +--- A function called when the tasklist is refreshed. +-- +-- This is a very low level API, prefer `widget_template` whenever +-- you can. +-- +-- @property update_function +-- @tparam function|nil update_function +-- @propertydefault The default function delegate everything to the `widget_template`. +-- @functionparam widget layout The base layout object. +-- @functionparam table buttons The buttons for this client entry (see below). +-- @functionparam string label The client name. +-- @functionparam table data Arbitrary metadate. +-- @functionparam table clients The list of clients (ordered). +-- @functionparam table metadata Other values. +-- @functionnoreturn +-- @propemits true false + +--- A template for creating the client widgets. +-- +-- @DOC_sequences_client_tasklist_widget_template1_EXAMPLE@ +-- +-- @property widget_template +-- @tparam[opt=nil] template|nil widget_template +-- @propemits true false + +--- A function to gather the clients to display. +-- +-- @DOC_sequences_client_tasklist_custom_source1_EXAMPLE@ +-- +-- @property source +-- @tparam[opt=awful.widget.tasklist.source.all_clients] function source +-- @functionparam screen s The tasklist screen. +-- @functionparam table metadata Various metadata. +-- @functionreturn table The list of clients. +-- @propemits true false +-- @see awful.widget.tasklist.source.all_clients + +function tasklist:set_base_layout(layout) + self._private.base_layout = base.make_widget_from_value( + layout or flex.horizontal + ) + + local spacing = self._private.style.spacing or beautiful.tasklist_spacing + + if self._private.base_layout.set_spacing and spacing then + self._private.base_layout:set_spacing(spacing) + end + + assert(self._private.base_layout.is_widget) + + self._do_tasklist_update() + + self:emit_signal("widget::layout_changed") + self:emit_signal("widget::redraw_needed") + self:emit_signal("property::base_layout", layout) +end + +function tasklist:get_count() + if not self._private.last_count then + self._do_tasklist_update_now() + end + + return self._private.last_count +end + +function tasklist:layout(_, width, height) + if self._private.base_layout then + return { base.place_widget_at(self._private.base_layout, 0, 0, width, height) } + end +end + +function tasklist:fit(context, width, height) + if not self._private.base_layout then + return 0, 0 + end + + return base.fit_widget(self, context, self._private.base_layout, width, height) +end + +for _, prop in ipairs { "screen", "filter", "update_function", "widget_template", "source"} do + tasklist["set_"..prop] = function(self, value) + if value == self._private[prop] then return end + + self._private[prop] = value + + self._do_tasklist_update() + + self:emit_signal("widget::layout_changed") + self:emit_signal("widget::redraw_needed") + self:emit_signal("property::"..prop, value) + end + + tasklist["get_"..prop] = function(self) + return self._private[prop] + end +end + +local function update_screen(self, screen, old) + if not instances then return end + + if old and instances[old] then + for k, w in ipairs(instances[old]) do + if w == self then + table.remove(instances[old], k) + break + end + end + end + + local list = instances[screen] + + if not list then + list = setmetatable({}, { __mode = "v" }) + instances[screen] = list + end + + table.insert(list, self) +end + +function tasklist:set_screen(value) + value = get_screen(value) + + if value == self._private.screen then return end + + local old = self._private.screen + + self._private.screen = value + + update_screen(self, screen, old) + + self._do_tasklist_update() + + self:emit_signal("widget::layout_changed") + self:emit_signal("widget::redraw_needed") + self:emit_signal("property::screen", value) +end + +function tasklist:set_widget_template(widget_template) + self._private.widget_template = widget_template + + -- Remove the existing instances + self._private.data = setmetatable({}, { __mode = 'k' }) + + self._do_tasklist_update() + + self:emit_signal("widget::layout_changed") + self:emit_signal("widget::redraw_needed") + self:emit_signal("property::widget_template", widget_template) +end + --- Create a new tasklist widget. -- The last two arguments (update_function -- and layout) serve to customize the layout of the tasklist (eg. to @@ -518,53 +826,58 @@ end -- function used to generate the list of client. -- @tparam[opt] table args.widget_template A custom widget to be used for each client -- @tparam[opt={}] table args.style The style overrides default theme. --- @tparam[opt=nil] string|pattern args.style.fg_normal --- @tparam[opt=nil] string|pattern args.style.bg_normal --- @tparam[opt=nil] string|pattern args.style.fg_focus --- @tparam[opt=nil] string|pattern args.style.bg_focus --- @tparam[opt=nil] string|pattern args.style.fg_urgent --- @tparam[opt=nil] string|pattern args.style.bg_urgent --- @tparam[opt=nil] string|pattern args.style.fg_minimize --- @tparam[opt=nil] string|pattern args.style.bg_minimize --- @tparam[opt=nil] string args.style.bg_image_normal --- @tparam[opt=nil] string args.style.bg_image_focus --- @tparam[opt=nil] string args.style.bg_image_urgent --- @tparam[opt=nil] string args.style.bg_image_minimize --- @tparam[opt=nil] boolean args.style.tasklist_disable_icon --- @tparam[opt=nil] number args.style.icon_size The size of the icon --- @tparam[opt='▪'] string args.style.sticky Extra icon when client is sticky --- @tparam[opt='⌃'] string args.style.ontop Extra icon when client is ontop --- @tparam[opt='▴'] string args.style.above Extra icon when client is above --- @tparam[opt='▾'] string args.style.below Extra icon when client is below --- @tparam[opt='✈'] string args.style.floating Extra icon when client is floating --- @tparam[opt='+'] string args.style.maximized Extra icon when client is maximized --- @tparam[opt='⬌'] string args.style.maximized_horizontal Extra icon when client is maximized_horizontal --- @tparam[opt='⬍'] string args.style.maximized_vertical Extra icon when client is maximized_vertical --- @tparam[opt=false] boolean args.style.disable_task_name --- @tparam[opt=nil] string args.style.font --- @tparam[opt=left] string args.style.align *left*, *right* or *center* --- @tparam[opt=nil] string args.style.font_focus --- @tparam[opt=nil] string args.style.font_minimized --- @tparam[opt=nil] string args.style.font_urgent --- @tparam[opt=nil] number args.style.spacing The spacing between tags. --- @tparam[opt=nil] gears.shape args.style.shape --- @tparam[opt=nil] number args.style.shape_border_width --- @tparam[opt=nil] string|color args.style.shape_border_color --- @tparam[opt=nil] gears.shape args.style.shape_focus --- @tparam[opt=nil] number args.style.shape_border_width_focus --- @tparam[opt=nil] string|color args.style.shape_border_color_focus --- @tparam[opt=nil] gears.shape args.style.shape_minimized --- @tparam[opt=nil] number args.style.shape_border_width_minimized --- @tparam[opt=nil] string|color args.style.shape_border_color_minimized --- @tparam[opt=nil] gears.shape args.style.shape_urgent --- @tparam[opt=nil] number args.style.shape_border_width_urgent --- @tparam[opt=nil] string|color args.style.shape_border_color_urgent +-- @tparam[opt=beautiful.tasklist_fg_normal] string|pattern args.style.fg_normal +-- @tparam[opt=beautiful.tasklist_bg_normal] string|pattern args.style.bg_normal +-- @tparam[opt=beautiful.tasklist_fg_focus or beautiful.fg_focus] string|pattern args.style.fg_focus +-- @tparam[opt=beautiful.tasklist_bg_focus or beautiful.bg_focus] string|pattern args.style.bg_focus +-- @tparam[opt=beautiful.tasklist_fg_urgent or beautiful.fg_urgent] string|pattern args.style.fg_urgent +-- @tparam[opt=beautiful.tasklist_bg_urgent or beautiful.bg_urgent] string|pattern args.style.bg_urgent +-- @tparam[opt=beautiful.tasklist_fg_minimize or beautiful.fg_minimize] string|pattern args.style.fg_minimize +-- @tparam[opt=beautiful.tasklist_bg_minimize or beautiful.bg_minimize] string|pattern args.style.bg_minimize +-- @tparam[opt=beautiful.tasklist_bg_image_normal] string args.style.bg_image_normal +-- @tparam[opt=beautiful.tasklist_bg_image_focus] string args.style.bg_image_focus +-- @tparam[opt=beautiful.tasklist_bg_image_urgent] string args.style.bg_image_urgent +-- @tparam[opt=beautiful.tasklist_bg_image_minimize] string args.style.bg_image_minimize +-- @tparam[opt=beautiful.tasklist_disable_icon] boolean args.style.disable_icon +-- @tparam[opt=beautiful.tasklist_icon_size] number args.style.icon_size The size of the icon +-- @tparam[opt=beautiful.tasklist_sticky or '▪'] string args.style.sticky Extra icon when client is sticky +-- @tparam[opt=beautiful.tasklist_ontop or '⌃'] string args.style.ontop Extra icon when client is ontop +-- @tparam[opt=beautiful.tasklist_above or '▴'] string args.style.above Extra icon when client is above +-- @tparam[opt=beautiful.tasklist_below or '▾'] string args.style.below Extra icon when client is below +-- @tparam[opt=beautiful.tasklist_floating or '✈'] string args.style.floating Extra icon when client is floating +-- @tparam[opt=beautiful.tasklist_maximized or '+'] string args.style.maximized Extra +-- icon when client is maximized +-- @tparam[opt=beautiful.tasklist_maximized_horizontal or '⬌'] string args.style.maximized_horizontal Extra +-- icon when client is maximized_horizontal +-- @tparam[opt=beautiful.tasklist_maximized_vertical or '⬍'] string args.style.maximized_vertical Extra +-- icon when client is maximized_vertical +-- @tparam[opt=beautiful.tasklist_disable_task_name or false] boolean args.style.disable_task_name +-- @tparam[opt=beautiful.tasklist_font] string args.style.font +-- @tparam[opt=beautiful.tasklist_align or "left"] string args.style.align *left*, *right* or *center* +-- @tparam[opt=beautiful.tasklist_font_focus] string args.style.font_focus +-- @tparam[opt=beautiful.tasklist_font_minimized] string args.style.font_minimized +-- @tparam[opt=beautiful.tasklist_font_urgent] string args.style.font_urgent +-- @tparam[opt=beautiful.tasklist_spacing] number args.style.spacing The spacing between tags. +-- @tparam[opt=beautiful.tasklist_shape] gears.shape args.style.shape +-- @tparam[opt=beautiful.tasklist_shape_border_width] number args.style.shape_border_width +-- @tparam[opt=beautiful.tasklist_shape_border_color] string|color args.style.shape_border_color +-- @tparam[opt=beautiful.tasklist_shape_focus] gears.shape args.style.shape_focus +-- @tparam[opt=beautiful.tasklist_shape_border_width_focus] number args.style.shape_border_width_focus +-- @tparam[opt=beautiful.tasklist_shape_border_color_focus] string|color args.style.shape_border_color_focus +-- @tparam[opt=beautiful.tasklist_shape_minimized] gears.shape args.style.shape_minimized +-- @tparam[opt=beautiful.tasklist_shape_border_width_minimized] number args.style.shape_border_width_minimized +-- @tparam[opt=beautiful.tasklist_shape_border_color_minimized] string|color args.style.shape_border_color_minimized +-- @tparam[opt=beautiful.tasklist_shape_urgent] gears.shape args.style.shape_urgent +-- @tparam[opt=beautiful.tasklist_shape_border_width_urgent] number args.style.shape_border_width_urgent +-- @tparam[opt=beautiful.tasklist_shape_border_color_urgent] string|color args.style.shape_border_color_urgent +-- @tparam[opt=beautiful.tasklist_minimized ] string|color args.style.minimized -- @param filter **DEPRECATED** use args.filter -- @param buttons **DEPRECATED** use args.buttons -- @param style **DEPRECATED** use args.style -- @param update_function **DEPRECATED** use args.update_function --- @param base_widget **DEPRECATED** use args.base_widget +-- @param base_widget **DEPRECATED** use args.base_layout -- @constructorfct awful.widget.tasklist +-- @usebeautiful beautiful.tasklist_plain_task_name function tasklist.new(args, filter, buttons, style, update_function, base_widget) local screen = nil @@ -596,23 +909,37 @@ function tasklist.new(args, filter, buttons, style, update_function, base_widget screen = screen or get_screen(args.screen) local uf = args.update_function or common.list_update - local w = base.make_widget_from_value(args.layout or flex.horizontal) - local data = setmetatable({}, { __mode = 'k' }) + local w = base.make_widget(nil, nil, { + enable_properties = true, + }) - local spacing = args.style and args.style.spacing or args.layout and args.layout.spacing - or beautiful.tasklist_spacing - if w.set_spacing and spacing then - w:set_spacing(spacing) - end + gtable.crush(w._private, { + disable_task_name = args.disable_task_name, + disable_icon = args.disable_icon, + update_function = args.update_function, + filter = args.filter, + buttons = args.buttons, + style = args.style or {}, + screen = screen, + widget_template = args.widget_template, + source = args.source, + data = setmetatable({}, { __mode = 'k' }) + }) + + gtable.crush(w, tasklist, true) + rawset(w, "filter", nil) + rawset(w, "source", nil) local queued_update = false -- For the tests function w._do_tasklist_update_now() queued_update = false - if screen.valid then - tasklist_update(screen, w, args.buttons, args.filter, data, args.style, uf, args) + if w._private.screen.valid then + tasklist_update( + w._private.screen, w, w._private.buttons, w._private.filter, w._private.data, args.style, uf, args + ) end end @@ -624,7 +951,7 @@ function tasklist.new(args, filter, buttons, style, update_function, base_widget end end function w._unmanage(c) - data[c] = nil + w._private.data[c] = nil end if instances == nil then instances = setmetatable({}, { __mode = "k" }) @@ -681,17 +1008,20 @@ function tasklist.new(args, filter, buttons, style, update_function, base_widget instances[get_screen(s)] = nil end) end + + tasklist.set_base_layout(w, args.layout or args.base_layout) + w._do_tasklist_update() - local list = instances[screen] - if not list then - list = setmetatable({}, { __mode = "v" }) - instances[screen] = list - end - table.insert(list, w) + + update_screen(w, screen) + return w end --- Filtering function to include all clients. +-- +--@DOC_sequences_client_tasklist_filter_allscreen1_EXAMPLE@ +-- -- @return true -- @filterfunction awful.widget.tasklist.filter.allscreen function tasklist.filter.allscreen() @@ -699,8 +1029,11 @@ function tasklist.filter.allscreen() end --- Filtering function to include the clients from all tags on the screen. --- @param c The client. --- @param screen The screen we are drawing on. +-- +--@DOC_sequences_client_tasklist_filter_alltags1_EXAMPLE@ +-- +-- @tparam client c The client. +-- @tparam screen screen The screen we are drawing on. -- @return true if c is on screen, false otherwise -- @filterfunction awful.widget.tasklist.filter.alltags function tasklist.filter.alltags(c, screen) @@ -709,8 +1042,13 @@ function tasklist.filter.alltags(c, screen) end --- Filtering function to include only the clients from currently selected tags. --- @param c The client. --- @param screen The screen we are drawing on. +-- +-- This is the filter used in the default `rc.lua`. +-- +--@DOC_sequences_client_tasklist_filter_currenttags1_EXAMPLE@ +-- +-- @tparam client c The client. +-- @tparam screen screen The screen we are drawing on. -- @return true if c is in a selected tag on screen, false otherwise -- @filterfunction awful.widget.tasklist.filter.currenttags function tasklist.filter.currenttags(c, screen) @@ -734,8 +1072,11 @@ function tasklist.filter.currenttags(c, screen) end --- Filtering function to include only the minimized clients from currently selected tags. --- @param c The client. --- @param screen The screen we are drawing on. +-- +--@DOC_sequences_client_tasklist_filter_minimizedcurrenttags1_EXAMPLE@ +-- +-- @tparam client c The client. +-- @tparam screen screen The screen we are drawing on. -- @return true if c is in a selected tag on screen and is minimized, false otherwise -- @filterfunction awful.widget.tasklist.filter.minimizedcurrenttags function tasklist.filter.minimizedcurrenttags(c, screen) @@ -762,8 +1103,11 @@ function tasklist.filter.minimizedcurrenttags(c, screen) end --- Filtering function to include only the currently focused client. --- @param c The client. --- @param screen The screen we are drawing on. +-- +--@DOC_sequences_client_tasklist_filter_focused1_EXAMPLE@ +-- +-- @tparam client c The client. +-- @tparam screen screen The screen we are drawing on. -- @return true if c is focused on screen, false otherwise -- @filterfunction awful.widget.tasklist.filter.focused function tasklist.filter.focused(c, screen) @@ -784,8 +1128,6 @@ function tasklist.mt:__call(...) return tasklist.new(...) end ---@DOC_widget_COMMON@ - --@DOC_object_COMMON@ return setmetatable(tasklist, tasklist.mt) diff --git a/lib/awful/widget/watch.lua b/lib/awful/widget/watch.lua index 090fcb9e0..21d094124 100644 --- a/lib/awful/widget/watch.lua +++ b/lib/awful/widget/watch.lua @@ -1,5 +1,6 @@ --------------------------------------------------------------------------- ---- Watch widget. +--- Execute a command at a set interval and display its output. +-- -- Here is an example of simple temperature widget which will update each 15 -- seconds implemented in two different ways. -- The first, simpler one, will just display the return command output @@ -7,20 +8,18 @@ -- In the other example `sensors` returns to the widget its full output -- and it's trimmed in the widget callback function: -- --- 211 mytextclock, --- 212 wibox.widget.textbox(' | '), --- 213 -- one way to do that: --- 214 awful.widget.watch('bash -c "sensors | grep temp1"', 15), --- 215 -- another way: --- 216 awful.widget.watch('sensors', 15, function(widget, stdout) --- 217 for line in stdout:gmatch("[^\r\n]+") do --- 218 if line:match("temp1") then --- 219 widget:set_text(line) --- 220 return --- 221 end --- 222 end --- 223 end), --- 224 s.mylayoutbox, +-- -- one way to do that: +-- local w = awful.widget.watch('bash -c "sensors | grep temp1"', 15) +-- +-- -- another way: +-- local w = awful.widget.watch('sensors', 15, function(widget, stdout) +-- for line in stdout:gmatch("[^\r\n]+") do +-- if line:match("temp1") then +-- widget:set_text(line) +-- return +-- end +-- end +-- end) -- -- ![Example screenshot](../images/awful_widget_watch.png) -- @@ -32,6 +31,7 @@ -- @author Yauheni Kirylau -- @copyright 2015, 2016 Benjamin Petrenko, Yauheni Kirylau -- @widgetmod awful.widget.watch +-- @supermodule wibox.widget.base --------------------------------------------------------------------------- local setmetatable = setmetatable @@ -55,7 +55,7 @@ local watch = { mt = {} } -- function(widget, stdout, stderr, exitreason, exitcode) -- widget:set_text(stdout) -- end --- @param callback.widget Base widget instance. +-- @tparam wibox.widget callback.widget Base widget instance. -- @tparam string callback.stdout Output on stdout. -- @tparam string callback.stderr Output on stderr. -- @tparam string callback.exitreason Exit Reason. @@ -64,7 +64,7 @@ local watch = { mt = {} } -- For "exit" reason it's the exit code. -- For "signal" reason — the signal causing process termination. -- --- @param[opt=wibox.widget.textbox()] base_widget Base widget. +-- @tparam[opt=wibox.widget.textbox()] wibox.widget base_widget Base widget. -- -- @return The widget used by this watch. -- @return Its gears.timer. @@ -92,8 +92,6 @@ function watch.mt.__call(_, ...) return watch.new(...) end ---@DOC_widget_COMMON@ - --@DOC_object_COMMON@ return setmetatable(watch, watch.mt) diff --git a/lib/beautiful/init.lua b/lib/beautiful/init.lua index 9db96f254..d0d0a3d99 100644 --- a/lib/beautiful/init.lua +++ b/lib/beautiful/init.lua @@ -1,5 +1,5 @@ ---------------------------------------------------------------------------- ---- Theme library. +--- Key+value based theme library and associated utility modules. -- -- @author Damien Leone <damien.leone@gmail.com> -- @author Julien Danjou <julien@danjou.info> @@ -89,62 +89,52 @@ local active_font --- The default font. -- @beautiful beautiful.font --- @param string +-- @param[opt="sans 8"] string --- The default background color. +--- The default background color. +-- +-- The background color can be transparent. If there is a +-- compositing manager such as compton, then it will be +-- real transparency and may include blur (provided by the +-- compositor). When there is no compositor, it will take +-- a picture of the wallpaper and blend it. +-- -- @beautiful beautiful.bg_normal -- @param color --- The default focused element background color. +--- The default focused element background color. -- @beautiful beautiful.bg_focus -- @param color --- The default urgent element background color. +--- The default urgent element background color. -- @beautiful beautiful.bg_urgent -- @param color --- The default minimized element background color. +--- The default minimized element background color. -- @beautiful beautiful.bg_minimize -- @param color --- The system tray background color. --- Please note that only solid colors are currently supported. --- @beautiful beautiful.bg_systray --- @param color - --- The default focused element foreground (text) color. +--- The default focused element foreground (text) color. -- @beautiful beautiful.fg_normal -- @param color --- The default focused element foreground (text) color. +--- The default focused element foreground (text) color. -- @beautiful beautiful.fg_focus -- @param color --- The default urgent element foreground (text) color. +--- The default urgent element foreground (text) color. -- @beautiful beautiful.fg_urgent -- @param color --- The default minimized element foreground (text) color. +--- The default minimized element foreground (text) color. -- @beautiful beautiful.fg_minimize -- @param color ---- The gap between clients. --- @beautiful beautiful.useless_gap --- @param[opt=0] number - ---- The fallback border width. --- @beautiful beautiful.border_width --- @param number - ---- The fallback border color. --- @beautiful beautiful.border_color --- @param color - --- The wallpaper path. -- @beautiful beautiful.wallpaper -- @tparam string|gears.surface wallpaper --- The icon theme name. +--- The icon theme name. -- It has to be a directory in `/usr/share/icons` or an XDG icon folder. -- @beautiful beautiful.icon_theme -- @param string @@ -234,7 +224,8 @@ end --- Get the height of a font. -- --- @param name Name of the font. +-- @tparam string name Name of the font. +-- @treturn number The font height. -- @staticfct beautiful.get_font_height function beautiful.get_font_height(name) return load_font(name).height diff --git a/lib/beautiful/theme_assets.lua b/lib/beautiful/theme_assets.lua index 555a963f8..d4f61de03 100644 --- a/lib/beautiful/theme_assets.lua +++ b/lib/beautiful/theme_assets.lua @@ -86,6 +86,7 @@ end -- @tparam color bg Background color. -- @tparam color fg Main foreground color. -- @tparam color alt_fg Accent foreground color. +-- @noreturn -- @staticfct beautiful.theme_assets.gen_awesome_name function theme_assets.gen_awesome_name(cr, height, bg, fg, alt_fg) local ls = height/10 -- letter_size @@ -155,6 +156,7 @@ end -- @tparam number height Height. -- @tparam color bg Background color. -- @tparam color fg Foreground color. +-- @noreturn -- @staticfct beautiful.theme_assets.gen_logo function theme_assets.gen_logo(cr, width, height, bg, fg) local ls = math.min(width, height) diff --git a/lib/beautiful/xresources.lua b/lib/beautiful/xresources.lua index 71299cb44..97f51697f 100644 --- a/lib/beautiful/xresources.lua +++ b/lib/beautiful/xresources.lua @@ -119,6 +119,7 @@ end --- Set DPI for a given screen (defaults to global). -- @tparam number dpi DPI value. -- @tparam[opt] integer s Screen. +-- @noreturn -- @staticfct beautiful.xresources.set_dpi function xresources.set_dpi(dpi, s) s = get_screen(s) diff --git a/lib/gears/color.lua b/lib/gears/color.lua index 2d906ae0f..e982eb102 100644 --- a/lib/gears/color.lua +++ b/lib/gears/color.lua @@ -53,6 +53,7 @@ local surface = require("gears.surface") local color = { mt = {} } local pattern_cache +local color_string_cache = setmetatable({}, { __mode = "k" }) --- Parse a HTML-color. -- This function can parse colors like `#rrggbb` and `#rrggbbaa` and also `red`. @@ -281,6 +282,7 @@ end --- Create a pattern from a given string, same as @{gears.color}. -- @see gears.color +-- @treturn gears.color A cairo pattern object. -- @staticfct gears.color.create_pattern function color.create_pattern(col) if cairo.Pattern:is_type_of(col) then @@ -354,12 +356,75 @@ function color.recolor_image(image, new_color) return image end +--- Take an input color and set a different opacity. +-- +-- @staticfct gears.color.change_opacity +-- @tparam string|pattern input The input color. +-- @tparam number opacity A floating point number between 0 and 1. +-- @treturn color The new color if successful or `input` if invalid. +function color.change_opacity(input, opacity) + input = color.create_pattern(input) + + local error, r, g, b, _ = input:get_rgba() + + if error ~= "SUCCESS" then return input end + + return cairo.Pattern.create_rgba(r, g, b, opacity) +end + +--- Convert a color back to an hexadecimal color code. +-- +-- This takes an input color, pattern or gradient and attempt to convert it +-- to a color. If this fails, `fallback` is returned. This is useful when a +-- color needs to be concatenated into a Pango markup string. +-- +-- @staticfct gears.color.to_rgba_string +-- @tparam pattern|string|gradient color Note that only solid colors can be +-- convedted to the `RGBA` format. +-- @tparam[opt=nil] pattern|string|gradient fallback The color to return +-- if `color` cannot be converted to a string. +-- @treturn string The color in `#rrggbbaa` format. +-- @see gears.color.ensure_pango_color + +function color.to_rgba_string(col, fallback) + if (not col) and (not fallback) then return nil end + + -- Prevent infinite recursion. + if not col then return color.to_rgba_string(fallback) end + + if color_string_cache[col] then + return color_string_cache[col] + end + + col = color.create_pattern(col) + + local error1, error2, r, g, b, a = pcall(function () return col:get_rgba() end) + + -- Surface patterns don't have an RGBA representation. + if (not error1) or error2 ~= "SUCCESS" then return color.to_rgba_string(fallback) end + + color_string_cache[col] = string.format( + "#%02x%02x%02x%02x", + math.floor(r*255), + math.floor(g*255), + math.floor(b*255), + math.floor(a*255) + ) + + return color_string_cache[col] +end + --- Get a valid color for Pango markup -- @param check_color The color to check. -- @tparam string fallback The color to return if the first is invalid. (default: black) -- @treturn string color if it is valid, else fallback. -- @staticfct gears.color.ensure_pango_color function color.ensure_pango_color(check_color, fallback) + -- This will happen if `gears.color` has been called in the theme. + if type(check_color) == "userdata" then + return color.to_rgba_string(check_color, fallback) + end + check_color = tostring(check_color) -- Pango markup supports alpha, PangoColor does not. Thus, check for this. local len = #check_color diff --git a/lib/gears/debug.lua b/lib/gears/debug.lua index 49aac58e5..4718966a7 100644 --- a/lib/gears/debug.lua +++ b/lib/gears/debug.lua @@ -1,4 +1,6 @@ --------------------------------------------------------------------------- +-- Utility functions to make development easier. +-- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter -- @utillib gears.debug @@ -48,7 +50,7 @@ end -- @param data Value to inspect. -- @param tag The name of the value. -- @tparam[opt] int depth Depth of recursion. --- @return string A string that contains the expanded value of data. +-- @treturn string A string that contains the expanded value of data. -- @staticfct gears.debug.dump_return function debug.dump_return(data, tag, depth) return dump_raw(data, nil, tag, depth) @@ -59,6 +61,7 @@ end -- @param tag The name of the table. -- @tparam[opt] int depth Depth of recursion. -- @staticfct gears.debug.dump +-- @noreturn function debug.dump(data, tag, depth) print(debug.dump_return(data, tag, depth)) end @@ -66,6 +69,7 @@ end --- Print an warning message -- @tparam string message The warning message to print. -- @staticfct gears.debug.print_warning +-- @noreturn function debug.print_warning(message) io.stderr:write(os.date("%Y-%m-%d %T W: awesome: ") .. tostring(message) .. "\n") end @@ -73,6 +77,7 @@ end --- Print an error message -- @tparam string message The error message to print. -- @staticfct gears.debug.print_error +-- @noreturn function debug.print_error(message) io.stderr:write(os.date("%Y-%m-%d %T E: awesome: ") .. tostring(message) .. "\n") end @@ -91,6 +96,7 @@ local displayed_deprecations = {} -- @tparam integer args.deprecated_in Print the message only when Awesome's -- version is equal to or greater than deprecated_in. -- @staticfct gears.debug.deprecate +-- @noreturn -- @emits debug::deprecation This is usually routed to stdout when the API is -- newly deprecated. -- @emitstparam debug::deprecation string msg The full formatted message. @@ -141,7 +147,7 @@ end -- @tparam table fallback The new class. -- @tparam string old_name The old class name. -- @tparam string new_name The new class name. --- @tparam[opt={}] args The name. +-- @tparam[opt={}] table args The name. -- @tparam[opt] number args.deprecated_in The version which deprecated this -- class. -- @treturn table A proxy class. diff --git a/lib/gears/filesystem.lua b/lib/gears/filesystem.lua index de58e1a70..64aa43ae0 100644 --- a/lib/gears/filesystem.lua +++ b/lib/gears/filesystem.lua @@ -1,5 +1,8 @@ --------------------------------------------------------------------------- ---- Filesystem module for gears. +--- Various filesystem utility functions. +-- +-- Note that these functions are blocking. If you need to do a large number of +-- I/O operations, it is better to use `lgi.Gio` async functions. -- -- @utillib gears.filesystem --------------------------------------------------------------------------- diff --git a/lib/gears/matcher.lua b/lib/gears/matcher.lua index 869147c9d..5b4e3e1b0 100644 --- a/lib/gears/matcher.lua +++ b/lib/gears/matcher.lua @@ -225,6 +225,7 @@ end -- "except" and "except_any" keys. If no rules are provided, all rules -- registered with a source will be matched. -- @method matching_rules +-- @treturn table The matching rules. function matcher:matching_rules(o, rules) -- Match all sources. @@ -290,6 +291,7 @@ end -- @tparam string name The property name. -- @tparam function f The matching function. -- @method add_property_matcher +-- @noreturn -- @usage -- Manually match the screen in various ways. -- matcher:add_property_matcher("screen", function(c, value) -- return c.screen == value @@ -313,6 +315,7 @@ end -- the context of a rule. -- -- @method add_property_setter +-- @noreturn -- @tparam string name The property name. -- @tparam function f The setter function. function matcher:add_property_setter(name, f) @@ -472,6 +475,7 @@ end -- -- @param o The object. -- @method apply +-- @noreturn function matcher:apply(o) local callbacks, props = {}, {} for _, v in ipairs(self._matching_source) do @@ -514,6 +518,7 @@ end -- @tparam string source The source name. -- @tparam table rule A valid rule. -- @method append_rule +-- @noreturn function matcher:append_rule(source, rule) if not self._matching_rules[source] then self:add_matching_rules(source, {}, {}, {}) @@ -526,6 +531,7 @@ end -- @tparam string source The source name. -- @tparam table rules A table with rules. -- @method append_rules +-- @noreturn function matcher:append_rules(source, rules) for _, rule in ipairs(rules) do self:append_rule(source, rule) diff --git a/lib/gears/math.lua b/lib/gears/math.lua index db295f673..38eddaeb4 100644 --- a/lib/gears/math.lua +++ b/lib/gears/math.lua @@ -1,4 +1,6 @@ --------------------------------------------------------------------------- +-- Various math related functions. +-- --- Math module for gears. -- -- @utillib gears.math diff --git a/lib/gears/object.lua b/lib/gears/object.lua index b9b381c5c..35beeb223 100644 --- a/lib/gears/object.lua +++ b/lib/gears/object.lua @@ -52,6 +52,7 @@ end -- @tparam string name The name of the signal. -- @tparam function func The callback to call when the signal is emitted. -- @method connect_signal +-- @noreturn function object:connect_signal(name, func) assert(type(func) == "function", "callback must be a function, got: " .. type(func)) local sig = find_signal(self, name) @@ -105,6 +106,7 @@ end -- @tparam string name The name of the signal. -- @tparam function func The callback to call when the signal is emitted. -- @method weak_connect_signal +-- @noreturn function object:weak_connect_signal(name, func) assert(type(func) == "function", "callback must be a function, got: " .. type(func)) local sig = find_signal(self, name) @@ -116,6 +118,7 @@ end -- @tparam string name The name of the signal. -- @tparam function func The callback that should be disconnected. -- @method disconnect_signal +-- @noreturn function object:disconnect_signal(name, func) local sig = find_signal(self, name) sig.weak[func] = nil @@ -129,6 +132,7 @@ end -- function receives the object as first argument and then any extra -- arguments that are given to emit_signal() -- @method emit_signal +-- @noreturn function object:emit_signal(name, ...) local sig = find_signal(self, name) for func in pairs(sig.strong) do diff --git a/lib/gears/protected_call.lua b/lib/gears/protected_call.lua index fb967d147..7c688ee29 100644 --- a/lib/gears/protected_call.lua +++ b/lib/gears/protected_call.lua @@ -1,4 +1,9 @@ --------------------------------------------------------------------------- +-- Safely call a function and handle errors using `gears.debug`. +-- +-- This is a `pcall`/`xpcall` wrapper. All it does is to integrate into the +-- AwesomeWM-wide error handling and logging. +-- -- @author Uli Schlachter -- @copyright 2016 Uli Schlachter -- @utillib gears.protected_call diff --git a/lib/gears/shape.lua b/lib/gears/shape.lua index 1c31e741e..8b7fbea8a 100644 --- a/lib/gears/shape.lua +++ b/lib/gears/shape.lua @@ -74,7 +74,9 @@ local module = {} -- @tparam boolean br If the bottom right corner is rounded -- @tparam boolean bl If the bottom left corner is rounded -- @tparam number rate The "squareness" of the squircle, should be greater than 1 --- @tparam number delta The "smoothness" of the shape, delta must be greater than 0.01 and will be reset to 0.01 if not +-- @tparam number delta The "smoothness" of the shape, delta must be greate +-- than 0.01 and will be reset to 0.01 if not +-- @noreturn -- @staticfct gears.shape.partial_squircle function module.partial_squircle(cr, width, height, tl, tr, br, bl, rate, delta) -- rate ~ 2 can be used by icon @@ -167,7 +169,9 @@ end -- @tparam number width The shape width -- @tparam number height The shape height -- @tparam number rate The "squareness" of the squircle, should be greater than 1 --- @tparam number delta The "smoothness" of the shape, delta must be greater than 0.01 and will be reset to 0.01 if not +-- @tparam number delta The "smoothness" of the shape, delta must be greater +-- than 0.01 and will be reset to 0.01 if not +-- @noreturn -- @staticfct gears.shape.squircle function module.squircle(cr, width, height, rate, delta) module.partial_squircle(cr, width, height, true, true, true, true, rate, delta) @@ -182,6 +186,7 @@ end -- @tparam number width The width constraint -- @tparam number height The height constraint -- @tparam number n Number of grams (default n = 5 -> pentagram) +-- @noreturn -- @staticfct gears.shape.star function module.star(cr, width, height, n) -- use the minimum as size @@ -215,7 +220,8 @@ end -- @param cr A cairo content -- @tparam number width The rectangle width -- @tparam number height The rectangle height --- @tparam number radius the corner radius +-- @tparam number radius The corner radius +-- @noreturn -- @staticfct gears.shape.rounded_rect function module.rounded_rect(cr, width, height, radius) @@ -246,6 +252,7 @@ end -- @param cr A cairo content -- @param width The rectangle width -- @param height The rectangle height. +-- @noreturn -- @staticfct gears.shape.rounded_bar function module.rounded_bar(cr, width, height) module.rounded_rect(cr, width, height, height / 2) @@ -263,6 +270,7 @@ end -- @tparam boolean br If the bottom right corner is rounded -- @tparam boolean bl If the bottom left corner is rounded -- @tparam number rad The corner radius +-- @noreturn -- @staticfct gears.shape.partially_rounded_rect function module.partially_rounded_rect(cr, width, height, tl, tr, br, bl, rad) rad = rad or 10 @@ -319,6 +327,7 @@ end -- @tparam[opt=5] number corner_radius The corner radius -- @tparam[opt=10] number arrow_size The width and height of the arrow -- @tparam[opt=width/2 - arrow_size/2] number arrow_position The position of the arrow +-- @noreturn -- @staticfct gears.shape.infobubble function module.infobubble(cr, width, height, corner_radius, arrow_size, arrow_position) arrow_size = arrow_size or 10 @@ -353,6 +362,7 @@ end -- @tparam number width The shape width -- @tparam number height The shape height -- @tparam[opt=height/2] number arrow_length The length of the arrow part +-- @noreturn -- @staticfct gears.shape.rectangular_tag function module.rectangular_tag(cr, width, height, arrow_length) arrow_length = arrow_length or height/2 @@ -383,6 +393,7 @@ end -- @tparam[opt=head_width] number head_width The width of the head (/\) of the arrow -- @tparam[opt=width /2] number shaft_width The width of the shaft of the arrow -- @tparam[opt=height/2] number shaft_length The head_length of the shaft (the rest is the head) +-- @noreturn -- @staticfct gears.shape.arrow function module.arrow(cr, width, height, head_width, shaft_width, shaft_length) shaft_length = shaft_length or height / 2 @@ -408,6 +419,7 @@ end -- @param cr A cairo context -- @tparam number width The shape width -- @tparam number height The shape height +-- @noreturn -- @staticfct gears.shape.hexagon function module.hexagon(cr, width, height) cr:move_to(height/2,0) @@ -428,6 +440,7 @@ end -- @tparam number width The shape width -- @tparam number height The shape height -- @tparam[opt=height/2] number arrow_depth The width of the arrow part of the shape +-- @noreturn -- @staticfct gears.shape.powerline function module.powerline(cr, width, height, arrow_depth) arrow_depth = arrow_depth or height/2 @@ -456,6 +469,7 @@ end -- @param cr A cairo context -- @tparam number width The shape width -- @tparam number height The shape height +-- @noreturn -- @staticfct gears.shape.isosceles_triangle function module.isosceles_triangle(cr, width, height) cr:move_to( width/2, 0 ) @@ -472,6 +486,7 @@ end -- @tparam number width The shape width -- @tparam number height The shape height -- @tparam[opt=width/3] number thickness The cross section thickness +-- @noreturn -- @staticfct gears.shape.cross function module.cross(cr, width, height, thickness) thickness = thickness or width/3 @@ -500,6 +515,7 @@ end -- @tparam number width The shape width -- @tparam number height The shape height -- @tparam number corner_radius +-- @noreturn -- @staticfct gears.shape.octogon function module.octogon(cr, width, height, corner_radius) corner_radius = corner_radius or math.min(10, math.min(width, height)/4) @@ -524,6 +540,7 @@ end -- @tparam number width The shape width -- @tparam number height The shape height -- @tparam[opt=math.min(width height) / 2)] number radius The radius +-- @noreturn -- @staticfct gears.shape.circle function module.circle(cr, width, height, radius) radius = radius or math.min(width, height) / 2 @@ -539,6 +556,7 @@ end -- @param cr A cairo context -- @tparam number width The shape width -- @tparam number height The shape height +-- @noreturn -- @staticfct gears.shape.rectangle function module.rectangle(cr, width, height) cr:rectangle(0, 0, width, height) @@ -553,6 +571,7 @@ end -- @tparam number width The shape width -- @tparam number height The shape height -- @tparam[opt=width/3] number base_width The parallelogram base width +-- @noreturn -- @staticfct gears.shape.parallelogram function module.parallelogram(cr, width, height, base_width) base_width = base_width or width/3 @@ -570,6 +589,7 @@ end -- @param cr A cairo context -- @tparam number width The shape width -- @tparam number height The shape height +-- @noreturn -- @staticfct gears.shape.losange function module.losange(cr, width, height) cr:move_to(width/2 , 0 ) @@ -591,6 +611,7 @@ end -- @tparam[opt=0] number start_angle The start angle (in radian) -- @tparam[opt=math.pi/2] number end_angle The end angle (in radian) -- @tparam[opt=math.min(width height)/2] number radius The shape height +-- @noreturn -- @staticfct gears.shape.pie function module.pie(cr, width, height, start_angle, end_angle, radius) radius = radius or math.floor(math.min(width, height)/2) @@ -627,8 +648,9 @@ end -- @tparam[opt=math.min(width height)/2] number thickness The arc thickness -- @tparam[opt=0] number start_angle The start angle (in radian) -- @tparam[opt=math.pi/2] number end_angle The end angle (in radian) --- @tparam[opt=false] boolean start_rounded if the arc start rounded --- @tparam[opt=false] boolean end_rounded if the arc end rounded +-- @tparam[opt=false] boolean start_rounded If the arc start rounded +-- @tparam[opt=false] boolean end_rounded If the arc end rounded +-- @noreturn -- @staticfct gears.shape.arc function module.arc(cr, width, height, thickness, start_angle, end_angle, start_rounded, end_rounded) start_angle = start_angle or 0 @@ -752,6 +774,7 @@ end -- @tparam number h The shape height -- @tparam number percent The progressbar percent -- @tparam boolean hide_left Do not draw the left side of the shape +-- @noreturn -- @staticfct gears.shape.radial_progress function module.radial_progress(cr, w, h, percent, hide_left) percent = percent or 1 @@ -820,6 +843,12 @@ end -- @param shape A shape function -- @return A transformation handle, also act as a shape function -- @staticfct gears.shape.transform +-- @see gears.matrix.translate +-- @see gears.matrix.scale +-- @see gears.matrix.rotate +-- @see gears.matrix.rotate_at +-- @see gears.matrix.multiply +-- @see gears.matrix.invert function module.transform(shape) -- Apply the transformation matrix and apply the shape, then restore diff --git a/lib/gears/sort/init.lua b/lib/gears/sort/init.lua index 02c2123f8..2488bd7f0 100644 --- a/lib/gears/sort/init.lua +++ b/lib/gears/sort/init.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Extra sorting algorithms. +--- Utilities to sort and arrange data. -- -- @utillib gears.sort --------------------------------------------------------------------------- diff --git a/lib/gears/sort/topological.lua b/lib/gears/sort/topological.lua index 8064e40cb..e11e89e2a 100644 --- a/lib/gears/sort/topological.lua +++ b/lib/gears/sort/topological.lua @@ -18,6 +18,7 @@ end --- Ensure that `node` appears after all `dependencies`. -- @param node The node that edges are added to. -- @tparam table dependencies List of nodes that have to appear before `node`. +-- @noreturn -- @method append function tsort:append(node, dependencies) add_node(self, node) @@ -30,6 +31,7 @@ end --- Ensure that `node` appears before all `subordinates`. -- @param node The node that edges are added to. -- @tparam table subordinates List of nodes that have to appear after `node`. +-- @noreturn -- @method prepend function tsort:prepend(node, subordinates) for _, dep in ipairs(subordinates) do @@ -65,6 +67,7 @@ end --- Create a copy of this topological sort. -- This is useful to backup it before adding elements that can potentially -- have circular dependencies and thus render the original useless. +-- @treturn gears.sort.topological The cloned sorter object. -- @method clone function tsort:clone() local new = tsort.topological() @@ -78,6 +81,7 @@ end --- Remove a node from the topological map. -- -- @param node The node +-- @noreturn -- @method remove function tsort:remove(node) self._edges[node] = nil diff --git a/lib/gears/string.lua b/lib/gears/string.lua index a4e4db951..722c66ad5 100644 --- a/lib/gears/string.lua +++ b/lib/gears/string.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- String module for gears. +--- Various string manipulation and introspection fuctions. -- -- @utillib gears.string --------------------------------------------------------------------------- @@ -10,7 +10,7 @@ local xml_entity_names = { ["'"] = "'", ["\""] = """, ["<"] = "<", --- Escape a string from XML char. -- Useful to set raw text in textbox. --- @param text Text to escape. +-- @tparam string text Text to escape. -- @treturn string Escaped text. -- @staticfct gears.string.xml_escape function gstring.xml_escape(text) @@ -21,7 +21,7 @@ local xml_entity_chars = { lt = "<", gt = ">", nbsp = " ", quot = "\"", apos = " amp = "&" }; --- Unescape a string from entities. --- @param text Text to unescape. +-- @tparam string text Text to unescape. -- @treturn string Unescaped text. -- @staticfct gears.string.xml_unescape function gstring.xml_unescape(text) @@ -74,6 +74,7 @@ end --- Generate a pattern matching expression that ignores case. -- @tparam string q Original pattern matching expression. +-- @treturn string The pattern. -- @staticfct gears.string.query_to_pattern function gstring.query_to_pattern(q) local s = gstring.quote_pattern(q) diff --git a/lib/gears/surface.lua b/lib/gears/surface.lua index 55d22116b..21b4e1531 100644 --- a/lib/gears/surface.lua +++ b/lib/gears/surface.lua @@ -1,4 +1,6 @@ --------------------------------------------------------------------------- +-- Utilities to integrate and manipulate Cairo drawing surfaces. +-- -- @author Uli Schlachter -- @copyright 2012 Uli Schlachter -- @module gears.surface @@ -9,7 +11,7 @@ local type = type local capi = { awesome = awesome } local cairo = require("lgi").cairo local GdkPixbuf = require("lgi").GdkPixbuf -local color = nil +local color, beautiful = nil, nil local gdebug = require("gears.debug") local hierarchy = require("wibox.hierarchy") @@ -169,8 +171,8 @@ end -- @tparam number width The surface width -- @tparam number height The surface height -- @param shape A `gears.shape` compatible function --- @param[opt=white] shape_color The shape color or pattern --- @param[opt=transparent] bg_color The surface background color +-- @param[opt="#000000"] shape_color The shape color or pattern +-- @param[opt="#00000000"] bg_color The surface background color -- @treturn cairo.surface the new surface -- @staticfct load_from_shape function surface.load_from_shape(width, height, shape, shape_color, bg_color, ...) @@ -195,11 +197,11 @@ end -- -- If the wibox or client size change, this function need to be called -- again. --- @param draw A wibox or a client --- @param shape or gears.shape function or a custom function with a context, --- width and height as parameter. --- @param[opt] Any additional parameters will be passed to the shape function. +-- @tparam client|wibox draw A wibox or a client. +-- @tparam gears.shape|function shape The shape. +-- @param[opt] ... Any additional parameters will be passed to the shape function. -- @staticfct apply_shape_bounding +-- @noreturn function surface.apply_shape_bounding(draw, shape, ...) local geo = draw:geometry() @@ -232,7 +234,7 @@ end --- Create an SVG file with this widget content. -- This is dynamic, so the SVG will be updated along with the widget content. -- because of this, the painting may happen hover multiple event loop cycles. --- @deprecated draw_to_svg_file +-- @deprecated widget_to_svg -- @tparam widget widget A widget -- @tparam string path The output file path -- @tparam number width The surface width @@ -243,17 +245,22 @@ end -- @see wibox.widget.draw_to_image_surface function surface.widget_to_svg(widget, path, width, height) gdebug.deprecate("Use wibox.widget.draw_to_svg_file instead of ".. - "gears.surface.render_to_svg", {deprecated_in=5}) + "gears.surface.widget_to_svg", {deprecated_in=5}) local img = cairo.SvgSurface.create(path, width, height) local cr = cairo.Context(img) + -- Bad dependecy, but this is deprecated. + beautiful = beautiful or require("beautiful") + color = color or require("gears.color") + cr:set_source(color(beautiful.fg_normal)) + return img, run_in_hierarchy(widget, cr, width, height) end --- Create a cairo surface with this widget content. -- This is dynamic, so the SVG will be updated along with the widget content. -- because of this, the painting may happen hover multiple event loop cycles. --- @deprecated draw_to_image_surface +-- @deprecated widget_to_surface -- @tparam widget widget A widget -- @tparam number width The surface width -- @tparam number height The surface height @@ -268,6 +275,11 @@ function surface.widget_to_surface(widget, width, height, format) local img = cairo.ImageSurface(format or cairo.Format.ARGB32, width, height) local cr = cairo.Context(img) + -- Bad dependecy, but this is deprecated. + color = color or require("gears.color") + beautiful = beautiful or require("beautiful") + cr:set_source(color(beautiful.fg_normal)) + return img, run_in_hierarchy(widget, cr, width, height) end diff --git a/lib/gears/table.lua b/lib/gears/table.lua index b98aa66d8..9702c7bc2 100644 --- a/lib/gears/table.lua +++ b/lib/gears/table.lua @@ -1,8 +1,8 @@ --------------------------------------------------------------------------- ---- Table module for gears. +--- Various functions to worj with tables. -- -- Examples --- ======= +-- ======== -- -- Using `cycle_value`, you can cycle through values in a table. -- When the end of the table is reached, `cycle_value` loops around to the beginning. diff --git a/lib/gears/timer.lua b/lib/gears/timer.lua index b1a9644a4..b8ab26fb8 100644 --- a/lib/gears/timer.lua +++ b/lib/gears/timer.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Timer objects and functions. +--- Class to execute code at specific intervals. -- -- @usage -- -- Create a widget and update its content using the output of a shell @@ -91,6 +91,7 @@ local timer = { mt = {} } --- Start the timer. -- @method start +-- @noreturn -- @emits start function timer:start() if self.data.source_id ~= nil then @@ -110,6 +111,7 @@ end -- Does nothing if the timer isn't running. -- -- @method stop +-- @noreturn -- @emits stop function timer:stop() if self.data.source_id == nil then @@ -124,6 +126,7 @@ end -- This is equivalent to stopping the timer if it is running and then starting -- it. -- @method again +-- @noreturn -- @emits start -- @emits stop function timer:again() @@ -134,13 +137,20 @@ function timer:again() end --- The timer is started. +-- +-- For this to be `true` by default, pass `autostart` to the constructor. +-- -- @property started --- @param boolean +-- @tparam[opt=false] boolean started +-- @see start +-- @see stop --- The timer timeout value. --- **Signal:** property::timeout +-- -- @property timeout --- @param number +-- @tparam[opt=0] number timeout +-- @propertyunit second +-- @negativeallowed false -- @propemits true false local timer_instance_mt = { @@ -264,6 +274,7 @@ local delayed_calls = {} -- all, because it means that less batching happens and the delayed calls run -- prematurely. -- @staticfct gears.timer.run_delayed_calls_now +-- @noreturn function timer.run_delayed_calls_now() for _, callback in ipairs(delayed_calls) do protected_call(unpack(callback)) @@ -274,6 +285,7 @@ end --- Call the given function at the end of the current GLib event loop iteration. -- @tparam function callback The function that should be called -- @param ... Arguments to the callback function +-- @noreturn -- @staticfct gears.timer.delayed_call function timer.delayed_call(callback, ...) assert(type(callback) == "function", "callback must be a function, got: " .. type(callback)) diff --git a/lib/menubar/icon_theme.lua b/lib/menubar/icon_theme.lua index 358f00737..b1946081d 100644 --- a/lib/menubar/icon_theme.lua +++ b/lib/menubar/icon_theme.lua @@ -82,6 +82,7 @@ local index_theme_cache = {} -- @tparam string icon_theme_name Internal name of icon theme -- @tparam table base_directories Paths used for lookup -- @treturn table An instance of the class `icon_theme` +-- @usebeautiful beautiful.icon_theme icon_theme.new = function(icon_theme_name, base_directories) icon_theme_name = icon_theme_name or beautiful.icon_theme or get_default_icon_theme_name() base_directories = base_directories or get_pragmatic_base_directories() diff --git a/lib/menubar/init.lua b/lib/menubar/init.lua index 88c8fa5ad..142054f29 100644 --- a/lib/menubar/init.lua +++ b/lib/menubar/init.lua @@ -395,7 +395,8 @@ local function menulist_update(scr) end --- Refresh menubar's cache by reloading .desktop files. --- @tparam[opt] screen scr Screen. +-- @tparam[opt=awful.screen.focused()] screen scr Screen. +-- @noreturn -- @staticfct menubar.refresh function menubar.refresh(scr) scr = get_screen(scr or awful.screen.focused() or 1) @@ -452,8 +453,16 @@ local function prompt_keypressed_callback(mod, key, comm) end --- Show the menubar on the given screen. --- @param[opt] scr Screen. +-- @tparam[opt=awful.screen.focused()] screen scr Screen. +-- @noreturn -- @staticfct menubar.show +-- @usebeautiful beautiful.menubar_fg_normal +-- @usebeautiful beautiful.menubar_bg_normal +-- @usebeautiful beautiful.menubar_border_width +-- @usebeautiful beautiful.menubar_border_color +-- @usebeautiful beautiful.menubar_fg_focus +-- @usebeautiful beautiful.menubar_bg_focus +-- @usebeautiful beautiful.menubar_font function menubar.show(scr) scr = get_screen(scr or awful.screen.focused() or 1) local fg_color = theme.menubar_fg_normal or theme.menu_fg_normal or theme.fg_normal @@ -533,6 +542,7 @@ end --- Hide the menubar. -- @staticfct menubar.hide +-- @noreturn function menubar.hide() if instance then instance.wibox.visible = false diff --git a/lib/menubar/menu_gen.lua b/lib/menubar/menu_gen.lua index 19fb6e735..193eef1c5 100644 --- a/lib/menubar/menu_gen.lua +++ b/lib/menubar/menu_gen.lua @@ -57,8 +57,7 @@ menu_gen.all_categories = { icon_name = "applications-accessories", use = true } } ---- Find icons for category entries. --- @staticfct menubar.menu_gen.lookup_category_icons +-- Find icons for category entries. function menu_gen.lookup_category_icons() for _, v in pairs(menu_gen.all_categories) do v.icon = utils.lookup_icon(v.icon_name) @@ -81,6 +80,7 @@ end -- with the resulting list of menu entries as argument. -- @tparam table callback.entries All menu entries. -- @staticfct menubar.menu_gen.generate +-- @noreturn function menu_gen.generate(callback) -- Update icons for category entries menu_gen.lookup_category_icons() diff --git a/lib/menubar/utils.lua b/lib/menubar/utils.lua index 9c8f283fd..77945a398 100644 --- a/lib/menubar/utils.lua +++ b/lib/menubar/utils.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Utility module for menubar +--- Utility functions for the `menubar` module. -- -- @author Antonio Terceiro -- @copyright 2009, 2011-2012 Antonio Terceiro, Alexander Yakushev @@ -199,8 +199,9 @@ local function get_icon_lookup_path() end --- Remove CR newline from the end of the string. --- @param s string to trim +-- @tparam string s The string to trim -- @staticfct menubar.utils.rtrim +-- @treturn string The trimmed string. function utils.rtrim(s) if not s then return end if string.byte(s, #s) == 13 then @@ -357,6 +358,7 @@ end -- with the resulting list of menu entries as argument. -- @tparam table callback.programs Paths of found .desktop files. -- @staticfct menubar.utils.parse_dir +-- @noreturn function utils.parse_dir(dir_path, callback) local function get_readable_path(file) diff --git a/lib/naughty/action.lua b/lib/naughty/action.lua index 92078d744..0a4e66b50 100644 --- a/lib/naughty/action.lua +++ b/lib/naughty/action.lua @@ -27,6 +27,7 @@ local action = {} -- The action name. -- @property name -- @tparam string name The name. +-- @propertydefault This is provided by DBus. -- @propemits true false -- If the action is selected. @@ -35,17 +36,19 @@ local action = {} -- implement keyboard navigation. -- -- @property selected --- @param boolean +-- @tparam[opt=false] boolean selected -- @propemits true false --- The action position (index). -- @property position --- @param number +-- @tparam integer position +-- @propertydefault This is provided by DBus. -- @propemits true false +-- @negativeallowed false --- The action icon. -- @property icon --- @tparam gears.surface|string icon +-- @tparam[opt=nil] image|string|nil icon -- @propemits true false --- If the action should hide the label and only display the icon. @@ -53,7 +56,7 @@ local action = {} -- @DOC_wibox_nwidget_actionlist_icon_only_EXAMPLE@ -- -- @property icon_only --- @param[opt=false] boolean +-- @tparam[opt=false] boolean icon_only -- @propemits true false --- When a notification is invoked. @@ -120,6 +123,7 @@ end -- the action was invoked. If a notification is shared by many object (like -- a "mute" or "snooze" action added to all notification), calling `:invoke()` -- without adding the `notif` context will cause unexpected results. +-- @noreturn function action:invoke(notif) self:emit_signal("invoked", notif) end diff --git a/lib/naughty/container/background.lua b/lib/naughty/container/background.lua index 535fae5a1..5a24f0607 100644 --- a/lib/naughty/container/background.lua +++ b/lib/naughty/container/background.lua @@ -1,5 +1,5 @@ ---------------------------------------------------------------------------- ---- A notification background. +--- A notification background widget. -- -- This widget holds the boilerplate code associated with the notification -- background. This includes the color and potentially some other styling @@ -16,6 +16,7 @@ -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2019 Emmanuel Lepage Vallee -- @containermod naughty.widget.background +-- @supermodule wibox.container.background -- @see wibox.container.background ---------------------------------------------------------------------------- local wbg = require("wibox.container.background") @@ -43,6 +44,7 @@ end --- The attached notification. -- @property notification -- @tparam naughty.notification notification +-- @propertydefault This is usually set in the construtor. -- @propemits true false function background:set_notification(notif) @@ -100,8 +102,6 @@ local function new(args) return bg end ---@DOC_widget_COMMON@ - --@DOC_object_COMMON@ return setmetatable(background, {__call = function(_, ...) return new(...) end}) diff --git a/lib/naughty/core.lua b/lib/naughty/core.lua index 046ff0586..8f4b7f366 100644 --- a/lib/naughty/core.lua +++ b/lib/naughty/core.lua @@ -24,20 +24,23 @@ local naughty = {} --- Naughty configuration - a table containing common popup settings. -- +-- The callback has the follwing format: +-- +-- naughty.config.notify_callback = function(args) +-- args.text = 'prefix: ' .. args.text +-- return args +-- end +-- -- @table naughty.config --- @tfield[opt=apply_dpi(4)] int padding Space between popups and edge of the +-- @tfield[opt=beautiful.xresources.apply_dpi(4)] integer padding Space between popups and edge of the -- workarea. --- @tfield[opt=apply_dpi(1)] int spacing Spacing between popups. +-- @tfield[opt=beautiful.xresources.apply_dpi(1)] integer spacing Spacing between popups. -- @tfield[opt={"/usr/share/pixmaps/"}] table icon_dirs List of directories -- that will be checked by `getIcon()`. -- @tfield[opt={ "png", "gif" }] table icon_formats List of formats that will be -- checked by `getIcon()`. -- @tfield[opt] function notify_callback Callback used to modify or reject -- notifications, e.g. --- naughty.config.notify_callback = function(args) --- args.text = 'prefix: ' .. args.text --- return args --- end -- To reject a notification return `nil` from the callback. -- If the notification is a freedesktop notification received via DBUS, you can -- access the freedesktop hints via `args.freedesktop_hints` if any where @@ -45,7 +48,7 @@ local naughty = {} -- -- @tfield table presets Notification presets. See `config.presets`. -- --- @tfield table defaults Default values for the params to `notify()`. These can +-- @tfield table defaults Default values for the params to `naughty.notification{}`. These can -- optionally be overridden by specifying a preset. See `config.defaults`. -- It's done that way to preserve compatibility with Awesome 4.0 while allowing @@ -55,46 +58,61 @@ gtable.crush(naughty, require("naughty.constants")) --- Notification presets for `naughty.notify`. -- This holds presets for different purposes. A preset is a table of any --- parameters for `notify()`, overriding the default values +-- parameters for `naughty.notification{}`, overriding the default values -- (`naughty.config.defaults`). -- --- You have to pass a reference of a preset in your `notify()` as the `preset` +-- You have to pass a reference of a preset in your `naughty.notification{}` as the `preset` -- argument. -- -- The presets `"low"`, `"normal"` and `"critical"` are used for notifications -- over DBUS. -- --- @table config.presets +-- @table naughty.config.presets -- @tfield table low The preset for notifications with low urgency level. --- @tfield[opt=5] int low.timeout --- @tfield[opt=empty] table normal The default preset for every notification without a +-- @tfield[opt=5] integer low.timeout +-- @tfield[opt={}] table normal The default preset for every notification without a -- preset that will also be used for normal urgency level. +-- @tfield table ok +-- @tfield[opt="#00bb00"] string ok.bg +-- @tfield[opt="#ffffff"] string ok.fg +-- @tfield[opt=5] integer ok.timeout -- @tfield table critical The preset for notifications with a critical urgency -- level. -- @tfield[opt="#ff0000"] string critical.bg -- @tfield[opt="#ffffff"] string critical.fg --- @tfield[opt=0] string critical.timeout +-- @tfield[opt=0] integer critical.timeout +-- @tfield table info +-- @tfield[opt="#0000ff"] string info.bg +-- @tfield[opt="#ffffff"] string info.fg +-- @tfield[opt=5] integer info.timeout +-- @tfield table warn +-- @tfield[opt="#ffaa00"] string warn.bg +-- @tfield[opt="#00000"] string warn.fg +-- @tfield[opt=5] integer warn.timeout --- Defaults for `naughty.notify`. -- --- @table config.defaults --- @tfield[opt=5] int timeout +-- @table naughty.config.defaults +-- @tfield[opt=5] integer timeout -- @tfield[opt=""] string text --- @tfield[opt] int screen Defaults to `awful.screen.focused`. +-- @tfield[opt=awful.screen.focused()] integer screen -- @tfield[opt=true] boolean ontop --- @tfield[opt=apply_dpi(5)] int margin --- @tfield[opt=apply_dpi(1)] int border_width +-- @tfield[opt=beautiful.xresources.apply_dpi(5)] integer margin +-- @tfield[opt=beautiful.xresources.apply_dpi(1)] integer border_width -- @tfield[opt="top_right"] string position --- The reason why a notification is to be closed. +-- -- See [the specification](https://developer.gnome.org/notification-spec/#signals) -- for more details. --- @tfield number silent --- @tfield number expired --- @tfield number dismissed_by_user --- @tfield number dismissed_by_command --- @tfield number undefined --- @table notification_closed_reason +-- +-- @table naughty.notification_closed_reason +-- @tfield[opt=-2] number too_many_on_screen +-- @tfield[opt=-1] number silent +-- @tfield[opt=1] number expired +-- @tfield[opt=2] number dismissed_by_user +-- @tfield[opt=3] number dismissed_by_command +-- @tfield[opt=4] number undefined --- The global suspension state. -- @@ -102,7 +120,7 @@ gtable.crush(naughty, require("naughty.constants")) -- useful when watching movies or doing presentations. -- -- @property suspended --- @param boolean +-- @tparam[opt=false] boolean suspended -- @emits added -- @propemits true false @@ -113,24 +131,26 @@ gtable.crush(naughty, require("naughty.constants")) -- just vanish. -- -- @property expiration_paused --- @param[opt=false] boolean +-- @tparam[opt=false] boolean expiration_paused -- @propemits true false --- A table with all active notifications. -- -- Please note that this list is kept up-to-date even in suspended mode. -- --- **Signal:** --- --- * property::active --- -- @property active --- @param table +-- @tparam[opt={}] table active +-- @tablerowtype A list of `naughty.notification` objects. -- @propemits false false --- True when there is a handler connected to `request::display`. +-- +-- Note that using the legacy notifications is deprecated. +-- -- @property has_display_handler --- @param boolean +-- @tparam boolean has_display_handler +-- @propertydefault If `rc.lua` has a `request::display` section, this will +-- be `true`. Otherwise it is `false` and the legacy notification will be used. --- If the timeout needs to be reset when a property changes. -- @@ -148,7 +168,7 @@ gtable.crush(naughty, require("naughty.constants")) -- support for this and enabling it will cause bugs. -- -- @property image_animations_enabled --- @param[opt=false] boolean +-- @tparam[opt=false] boolean image_animations_enabled -- @propemits true false --- Enable or disable the persistent notifications. @@ -164,7 +184,7 @@ gtable.crush(naughty, require("naughty.constants")) -- that. -- -- @property persistence_enabled --- @param[opt=false] boolean +-- @tparam[opt=false] boolean persistence_enabled -- @propemits true false local properties = { @@ -177,16 +197,6 @@ local properties = { --TODO v5 Deprecate the public `naughty.notifications` (to make it private) ---- Index of notifications per screen and position. --- See config table for valid 'position' values. --- Each element is a table consisting of: --- --- @field box Wibox object containing the popup --- @field height Popup height --- @field width Popup width --- @field die Function to be executed on timeout --- @field id Unique notification id based on a counter --- @table notifications naughty.notifications = { suspended = { }, _expired = {{}} } naughty._active = {} @@ -339,9 +349,9 @@ end -- This function is deprecated in favor of -- `notification:destroy(reason, keep_visible)`. -- --- @param notification Notification object to be destroyed --- @param reason One of the reasons from `notification_closed_reason` --- @param[opt=false] keep_visible If true, keep the notification visible +-- @tparam naughty.notification notification Notification object to be destroyed +-- @tparam string reason One of the reasons from `notification_closed_reason` +-- @tparam[opt=false] boolean keep_visible If true, keep the notification visible -- @return True if the popup was successfully destroyed, nil otherwise -- @deprecated naughty.destroy function naughty.destroy(notification, reason, keep_visible) @@ -385,8 +395,8 @@ end --- Get notification by ID -- --- @param id ID of the notification --- @return notification object if it was found, nil otherwise +-- @tparam integer id ID of the notification +-- @treturn naughty.notification|nil notification object if it was found, nil otherwise -- @deprecated naughty.getById function naughty.getById(id) gdebug.deprecate("Use naughty.get_by_id", {deprecated_in=5}) @@ -395,8 +405,8 @@ end --- Get notification by ID -- --- @param id ID of the notification --- @return notification object if it was found, nil otherwise +-- @tparam integer id ID of the notification +-- @treturn naughty.notification|nil notification object if it was found, nil otherwise -- @staticfct naughty.get_by_id function naughty.get_by_id(id) -- iterate the notifications to get the notfications with the correct ID @@ -749,7 +759,7 @@ end -- @int[opt=5] args.timeout Time in seconds after which popup expires. -- Set 0 for no timeout. -- @int[opt] args.hover_timeout Delay in seconds after which hovered popup disappears. --- @tparam[opt=focused] integer|screen args.screen Target screen for the notification. +-- @tparam[opt=awful.screen.focused()] integer|screen args.screen Target screen for the notification. -- @string[opt="top_right"] args.position Corner of the workarea displaying the popups. -- Values: `"top_right"`, `"top_left"`, `"bottom_left"`, -- `"bottom_right"`, `"top_middle"`, `"bottom_middle"`, `"middle"`. @@ -766,17 +776,17 @@ end -- @tparam[opt=`beautiful.notification_shape`] gears.shape args.shape Widget shape. -- @tparam[opt=`beautiful.notification_opacity`] gears.opacity args.opacity Widget opacity. -- @tparam[opt=`beautiful.notification_margin`] gears.margin args.margin Widget margin. --- @tparam[opt] func args.run Function to run on left click. The notification +-- @tparam[opt] function args.run Function to run on left click. The notification -- object will be passed to it as an argument. -- You need to call e.g. -- `notification.die(naughty.notification_closed_reason.dismissedByUser)` from -- there to dismiss the notification yourself. --- @tparam[opt] func args.destroy Function to run when notification is destroyed. +-- @tparam[opt] function args.destroy Function to run when notification is destroyed. -- @tparam[opt] table args.preset Table with any of the above parameters. -- Note: Any parameters specified directly in args will override ones defined -- in the preset. --- @tparam[opt] int args.replaces_id Replace the notification with the given ID. --- @tparam[opt] func args.callback Function that will be called with all arguments. +-- @tparam[opt] integer args.replaces_id Replace the notification with the given ID. +-- @tparam[opt] function args.callback Function that will be called with all arguments. -- The notification will only be displayed if the function returns true. -- Note: this function is only relevant to notifications sent via dbus. -- @tparam[opt] table args.actions A list of `naughty.action`s. diff --git a/lib/naughty/init.lua b/lib/naughty/init.lua index ba23d761d..6b8774073 100644 --- a/lib/naughty/init.lua +++ b/lib/naughty/init.lua @@ -1,4 +1,6 @@ --------------------------------------------------------------------------- +-- Desktop notification handling library. +-- -- @author Uli Schlachter <psychon@znc.in> -- @copyright 2014 Uli Schlachter -- @module naughty diff --git a/lib/naughty/layout/box.lua b/lib/naughty/layout/box.lua index 0c6482471..dd7fe8f3f 100644 --- a/lib/naughty/layout/box.lua +++ b/lib/naughty/layout/box.lua @@ -167,6 +167,7 @@ end) -- -- @property notification -- @tparam naughty.notification notification +-- @propertydefault This must be provided by the constructor. -- @propemits true false --- The widget template to construct the box content. @@ -208,7 +209,7 @@ end) -- } -- -- @property widget_template --- @param widget +-- @tparam[opt=nil] template|nil widget_template -- @usebeautiful beautiful.notification_max_width The maximum width for the -- resulting widget. @@ -396,6 +397,4 @@ local function new(args) return ret end ---@DOC_wibox_COMMON@ - return setmetatable(box, {__call = function(_, args) return new(args) end}) diff --git a/lib/naughty/layout/legacy.lua b/lib/naughty/layout/legacy.lua index c5d6c887f..d132d4f65 100644 --- a/lib/naughty/layout/legacy.lua +++ b/lib/naughty/layout/legacy.lua @@ -1,5 +1,5 @@ ---------------------------------------------------------------------------- ---- A notification popup widget. +--- A notification popup widget (deprecated implementation). -- -- This is the legacy notification widget. It was the default until Awesome -- v4.3 but is now being deprecated in favor of a more flexible widget. diff --git a/lib/naughty/list/actions.lua b/lib/naughty/list/actions.lua index 46a66337d..eb51557da 100644 --- a/lib/naughty/list/actions.lua +++ b/lib/naughty/list/actions.lua @@ -24,6 +24,7 @@ -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2017 Emmanuel Lepage Vallee -- @widgetmod naughty.list.actions +-- @supermodule wibox.widget.base -- @see awful.widget.common ---------------------------------------------------------------------------- @@ -188,7 +189,7 @@ local actionlist = {} --- The actionlist parent notification. -- @property notification --- @tparam naughty.notification notification +-- @tparam[opt=nil] naughty.notification|nil notification -- @propemits true false -- @see naughty.notification @@ -196,18 +197,33 @@ local actionlist = {} -- If no layout is specified, a `wibox.layout.fixed.horizontal` will be created -- automatically. -- @property base_layout --- @tparam widget base_layout +-- @tparam[opt=wibox.layout.fixed.horizontal] widget base_layout -- @propemits true false -- @see wibox.layout.fixed.horizontal --- The actionlist parent notification. -- @property widget_template --- @tparam table widget_template +-- @tparam[opt=nil] template|nil widget_template -- @propemits true false --- A table with values to override each `beautiful.notification_action` values. -- @property style --- @tparam table style +-- @tparam[opt={}] table|nil style +-- @tparam boolean|nil style.underline_normal +-- @tparam boolean|nil style.underline_selected +-- @tparam shape|nil style.shape_normal +-- @tparam shape|nil style.shape_selected +-- @tparam gears.color|string|nil style.shape_border_color_normal +-- @tparam gears.color|string|nil style.shape_border_color_selected +-- @tparam number|nil style.shape_border_width_normal +-- @tparam number|nil style.shape_border_width_selected +-- @tparam number|nil style.icon_size +-- @tparam color|string|nil style.bg_normal +-- @tparam color|string|nil style.bg_selected +-- @tparam color|string|nil style.fg_normal +-- @tparam color|string|nil style.fg_selected +-- @tparam surface|string|nil style.bgimage_normal +-- @tparam surface|string|nil style.bgimage_selected -- @propemits true false -- @usebeautiful beautiful.font Fallback when the `font` property isn't set. -- @usebeautiful beautiful.notification_action_underline_normal Fallback. @@ -349,8 +365,6 @@ local function new(_, args) return wdg end ---@DOC_widget_COMMON@ - --@DOC_object_COMMON@ return setmetatable(module, {__call = new}) diff --git a/lib/naughty/list/notifications.lua b/lib/naughty/list/notifications.lua index d5561fcaa..9fb5afbb8 100644 --- a/lib/naughty/list/notifications.lua +++ b/lib/naughty/list/notifications.lua @@ -6,6 +6,7 @@ -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2017 Emmanuel Lepage Vallee -- @widgetmod naughty.list.notifications +-- @supermodule wibox.widget.base -- @see awful.widget.common ---------------------------------------------------------------------------- @@ -160,16 +161,17 @@ local notificationlist = {} --- The notificationlist parent notification. -- @property notification -- @tparam naughty.notification notification +-- @propertydefault This is usually set in the construtor. -- @propemits true false -- @see naughty.notification --- A `wibox.layout` to be used to place the entries. -- --- If no layout is specified, a `wibox.layout.fixed.vertical` will be created +-- If no layout is specified, a `wibox.layout.flex.horizontal` will be created -- automatically. -- -- @property base_layout --- @tparam widget base_layout +-- @tparam[opt=wibox.layout.flex.horizontal] widget base_layout -- @propemits true false -- @usebeautiful beautiful.notification_spacing -- @see wibox.layout.fixed.horizontal @@ -180,12 +182,15 @@ local notificationlist = {} --- The notificationlist parent notification. -- @property widget_template --- @tparam table widget_template +-- @tparam[opt=nil] template|nil widget_template +-- @propertydefault The default template displays the icon, title, message and +-- actions. -- @propemits true false --- A table with values to override each `beautiful.notification_action` values. -- @property style --- @tparam table style +-- @tparam[opt=nil] table|nil style +-- @propertytype nil Use the values from `beautiful` rather than hardcoded ones. -- @propemits true false -- @usebeautiful beautiful.notification_shape_normal Fallback. -- @usebeautiful beautiful.notification_shape_selected Fallback. @@ -242,7 +247,11 @@ end --- A function to prevent some notifications from being added to the list. -- @property filter --- @tparam function filter +-- @tparam[opt=nil] function|nil filter +-- @functionparam naughty.notification n The notification object. +-- @functionparam number count The number of notifications in the list. +-- @functionreturn boolean `true` if the notification is allowed and `false` if +-- it is rejected. -- @propemits true false for _, prop in ipairs { "filter", "base_layout" } do @@ -367,8 +376,6 @@ function module.filter.most_recent(n, count) return false end ---@DOC_widget_COMMON@ - --@DOC_object_COMMON@ return setmetatable(module, {__call = new}) diff --git a/lib/naughty/notification.lua b/lib/naughty/notification.lua index 446521191..a1c745333 100644 --- a/lib/naughty/notification.lua +++ b/lib/naughty/notification.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- A notification object. +--- Notification manipulation class. -- -- This class creates individual notification objects that can be manipulated -- to extend the default behavior. @@ -27,6 +27,8 @@ local pcommon = require("awful.permissions._common") local notification = {} +--luacheck: no max line length + --- Notifications font. -- @beautiful beautiful.notification_font -- @tparam string|lgi.Pango.FontDescription notification_font @@ -78,6 +80,8 @@ local notification = {} -- notifications. -- @property id -- @tparam number id +-- @propertydefault This is autogenerated. +-- @readonly -- @propemits true false --- Text of the notification. @@ -92,25 +96,26 @@ local notification = {} --- Title of the notification. --@DOC_naughty_helloworld_EXAMPLE@ -- @property title --- @tparam string title +-- @tparam[opt=""] string title -- @propemits true false --- Time in seconds after which popup expires. -- Set 0 for no timeout. -- @property timeout -- @tparam number timeout +-- @propertydefault If unspecified, it can come from either the notification +-- itself, the presets or the `ruled.notification` rules. +-- @negativeallowed false +-- @propertyunit second -- @propemits true false --- The notification urgency level. -- --- The default urgency levels are: --- --- * low --- * normal --- * critical --- -- @property urgency --- @param string +-- @tparam[opt="normal"] string urgency +-- @propertyvalue "low" +-- @propertyvalue "normal" +-- @propertyvalue "critical" -- @propemits true false --- The notification category. @@ -157,7 +162,7 @@ local notification = {} -- -- -- @property category --- @tparam string|nil category +-- @tparam[opt=nil] string|nil category -- @propemits true false --- True if the notification should be kept when an action is pressed. @@ -167,62 +172,68 @@ local notification = {} -- be updated with a date further in the future. -- -- @property resident --- @param[opt=false] boolean +-- @tparam[opt=false] boolean resident -- @propemits true false --- Delay in seconds after which hovered popup disappears. -- @property hover_timeout --- @param number +-- @tparam[opt=nil] number|nil hover_timeout +-- @negativeallowed false +-- @propertyunit second -- @propemits true false --- Target screen for the notification. -- @property screen --- @param screen +-- @tparam[opt=awful.screen.preferred()] screen screen -- @propemits true false --- Corner of the workarea displaying the popups. -- --- The possible values are: --- --- * *top_right* --- * *top_left* --- * *bottom_left* --- * *bottom_right* --- * *top_middle* --- * *bottom_middle* --- * *middle* --- --@DOC_awful_notification_box_corner_EXAMPLE@ -- -- @property position --- @param string +-- @tparam[opt=beautiful.notification_position] string|nil position +-- @propertyvalue "top_right" +-- @propertyvalue "top_left" +-- @propertyvalue "bottom_left" +-- @propertyvalue "bottom_right" +-- @propertyvalue "top_middle" +-- @propertyvalue "bottom_middle" +-- @propertyvalue "middle" -- @propemits true false -- @see awful.placement.next_to --- Boolean forcing popups to display on top. -- @property ontop --- @param boolean +-- @tparam[opt=false] boolean ontop --- Popup height. -- --@DOC_awful_notification_geometry_EXAMPLE@ -- -- @property height --- @param number +-- @tparam number|nil height -- @propemits true false +-- @propertyunit pixel +-- @negativeallowed false +-- @propbeautiful -- @see width --- Popup width. -- @property width --- @param number +-- @tparam number|nil width -- @propemits true false +-- @propertyunit pixel +-- @negativeallowed false +-- @propbeautiful -- @see height --- Notification font. --@DOC_naughty_colors_EXAMPLE@ -- @property font --- @param string +-- @tparam[opt=beautiful.notification_font] font|nil font -- @propemits true false +-- @see wibox.widget.textbox.font --- "All in one" way to access the default image or icon. -- @@ -241,14 +252,16 @@ local notification = {} -- * The `icon` of a client with `dialog` type. -- -- @property icon --- @tparam string|surface icon +-- @tparam[opt=nil] image|nil icon -- @propemits true false -- @see app_icon -- @see image --- Desired icon size in px. -- @property icon_size --- @param number +-- @tparam[opt=beautiful.notification_icon_size] integer|nil icon_size +-- @negativeallowed false +-- @propertyunit pixel -- @propemits true false --- The icon provided in the `app_icon` field of the DBus notification. @@ -257,7 +270,7 @@ local notification = {} -- icon name to be fetched from the theme. -- -- @property app_icon --- @param string +-- @tparam[opt=nil] string|nil app_icon -- @propemits true false --- The notification image. @@ -267,7 +280,7 @@ local notification = {} -- or stored elsewhere than the filesystem (databases, web, Android phones, etc). -- -- @property image --- @tparam string|surface image +-- @tparam[opt=nil] image|nil image -- @propemits true false --- The notification (animated) images. @@ -278,8 +291,11 @@ local notification = {} -- Also note that there is *zero* support for this anywhere else in `naughty` -- and very, very few applications support this. -- +-- This exists purely to comply with the specification. +-- -- @property images --- @tparam nil|table images +-- @tparam[opt=nil] nil|table images +-- @tablerowtype A list of `image`s. -- @propemits true false --- Foreground color. @@ -287,7 +303,8 @@ local notification = {} --@DOC_awful_notification_fg_EXAMPLE@ -- -- @property fg --- @tparam string|color|pattern fg +-- @tparam[beautiful.notification_fg] color|nil fg +-- @propbeautiful -- @propemits true false -- @see title -- @see gears.color @@ -297,22 +314,27 @@ local notification = {} --@DOC_awful_notification_bg_EXAMPLE@ -- -- @property bg --- @tparam string|color|pattern bg +-- @tparam[opt=beautiful.notification_bg] color|nil bg -- @propemits true false -- @see title -- @see gears.color --- Border width. -- @property border_width --- @param number +-- @tparam[opt=beautiful.notification_border_width or 0] number|nil border_width +-- @negativeallowed false +-- @propertyunit pixel +-- @propbeautiful -- @propemits true false --- Border color. -- --@DOC_awful_notification_border_color_EXAMPLE@ -- +-- Please note that only string (like `#ff0000`) are supported. +-- -- @property border_color --- @param string +-- @tparam[opt=beautiful.notification_border_color] string|nil border_color -- @propemits true false -- @see gears.color @@ -331,12 +353,15 @@ local notification = {} --@DOC_naughty_shape_EXAMPLE@ -- -- @property shape --- @tparam gears.shape shape +-- @tparam[opt=beautiful.notification_shape] shape|nil shape -- @propemits true false --- Widget opacity. -- @property opacity --- @tparam number opacity Between 0 to 1. +-- @tparam[opt=beautiful.notification_opacity] number|nil opacity +-- @rangestart 0.0 +-- @rangestop 1.0 +-- @propertyunit Gradient beween 0.0 (transparent) and 1.0 (opaque). -- @propemits true false --- Widget margin. @@ -344,7 +369,15 @@ local notification = {} --@DOC_awful_notification_margin_EXAMPLE@ -- -- @property margin --- @tparam number|table margin +-- @tparam[opt=beautiful.notification_margin] number|table|nil margin +-- @tparam[opt=0] number margin.top +-- @tparam[opt=0] number margin.bottom +-- @tparam[opt=0] number margin.left +-- @tparam[opt=0] number margin.right +-- @propertytype number A single value for all sides. +-- @propertytype table A different value for all sides. +-- @negativeallowed false +-- @propertyunit pixel -- @propemits true false -- @see shape @@ -368,14 +401,24 @@ local notification = {} -- args will override ones defined -- in the preset. -- @property preset --- @param table +-- @tparam[opt=nil] table|nil preset -- @propemits true false --- Function that will be called with all arguments. -- The notification will only be displayed if the function returns true. -- Note: this function is only relevant to notifications sent via dbus. -- @property callback --- @param function +-- @tparam[opt=nil] function|nil callback +-- @functionparam table legacy_data +-- @functionparam string appname +-- @functionparam number replaces_id +-- @functionparam string app_icon +-- @functionparam string title +-- @functionparam string message +-- @functionparam table actions +-- @functionparam table hints +-- @functionparam number expire +-- @functionnoreturn -- @propemits true false --- A table containing strings that represents actions to buttons. @@ -383,7 +426,8 @@ local notification = {} -- The table key (a number) is used by DBus to set map the action. -- -- @property actions --- @param table +-- @tparam[opt={}] table actions +-- @tablerowtype A list of `naughty.action` objects. -- @propemits true false --- Ignore this notification, do not display. @@ -392,20 +436,23 @@ local notification = {} -- handler. -- -- @property ignore --- @param boolean +-- @tparam[opt=false] boolean ignore -- @propemits true false --- Tell if the notification is currently suspended (read only). -- -- This is always equal to `naughty.suspended` ---@property suspended ---@param boolean +-- @property suspended +-- @tparam[opt=false] boolean suspended -- @propemits true false +-- @see naughty.suspended --- If the notification is expired. -- @property is_expired --- @param boolean +-- @tparam boolean is_expired -- @propemits true false +-- @propertydefault This becomes `true` either then `:destroy()` is called or +-- if the `timeout` expires. -- @see naughty.expiration_paused --- If the timeout needs to be reset when a property changes. @@ -436,7 +483,8 @@ local notification = {} -- client. -- -- @property clients --- @param table +-- @tparam[opt={}] table clients +-- @tablerowtype A list of `client` objects. --- The maximum popup width. -- @@ -444,9 +492,12 @@ local notification = {} -- this is ignored by `naughty.list.notifications` because it delegate this -- decision to the layout. -- --- @property[opt=500] max_width --- @param number +-- @property max_width +-- @tparam[opt=500] number|nil max_width +-- @propertyunit pixel +-- @negativeallowed false -- @propemits true false +-- @propbeautiful --- The application name specified by the notification. -- @@ -454,7 +505,7 @@ local notification = {} -- property, but can sometime be specified for remote or headless notifications. -- In these case, it helps to triage and detect the notification from the rules. -- @property app_name --- @param string +-- @tparam[opt=nil] string|nil app_name -- @propemits true false --- The widget template used to represent the notification. @@ -463,7 +514,8 @@ local notification = {} -- off with a specialized notification widget. -- -- @property widget_template --- @param table +-- @tparam[opt=nil] template|nil widget_template +-- @propertydefault The default template as the icon, title, message and actions. -- @propemits true false --- Destroy notification by notification object. @@ -496,6 +548,7 @@ end --- Set new notification timeout. -- @method reset_timeout -- @tparam number new_timeout Time in seconds after which notification disappears. +-- @noreturn function notification:reset_timeout(new_timeout) if self.timer then self.timer:stop() end @@ -791,6 +844,7 @@ end --- Add more actions to the notification. -- @method append_actions -- @tparam table new_actions +-- @noreturn function notification:append_actions(new_actions) self._private.actions = self._private.actions or {} @@ -901,49 +955,50 @@ end --- Create a notification. -- --- @tparam table args The argument table containing any of the arguments below. --- @string[opt=""] args.text Text of the notification. --- @string[opt] args.title Title of the notification. --- @int[opt=5] args.timeout Time in seconds after which popup expires. +-- @tparam[opt={}] table args The argument table containing any of the arguments below. +-- @tparam[opt=""] string args.text Text of the notification. +-- @tparam[opt] string args.title Title of the notification. +-- @tparam[opt=5] integer args.timeout Time in seconds after which popup expires. -- Set 0 for no timeout. --- @int[opt] args.hover_timeout Delay in seconds after which hovered popup disappears. +-- @tparam[opt] number args.hover_timeout Delay in seconds after which hovered popup disappears. -- @tparam[opt=focused] integer|screen args.screen Target screen for the notification. --- @string[opt="top_right"] args.position Corner of the workarea displaying the popups. +-- @tparam[opt="top_right"] string args.position Corner of the workarea displaying the popups. -- Values: `"top_right"`, `"top_left"`, `"bottom_left"`, -- `"bottom_right"`, `"top_middle"`, `"bottom_middle"`, `"middle"`. --- @bool[opt=true] args.ontop Boolean forcing popups to display on top. --- @int[opt=`beautiful.notification_height` or auto] args.height Popup height. --- @int[opt=`beautiful.notification_width` or auto] args.width Popup width. --- @string[opt=`beautiful.notification_font` or `beautiful.font` or `awesome.font`] args.font Notification font. --- @string[opt] args.icon Path to icon. --- @int[opt] args.icon_size Desired icon size in px. --- @string[opt=`beautiful.notification_fg` or `beautiful.fg_focus` or `'#ffffff'`] args.fg Foreground color. --- @string[opt=`beautiful.notification_fg` or `beautiful.bg_focus` or `'#535d6c'`] args.bg Background color. --- @int[opt=`beautiful.notification_border_width` or 1] args.border_width Border width. --- @string[opt=`beautiful.notification_border_color` or --- `beautiful.border_color_active` or `'#535d6c'`] args.border_color Border color. --- @tparam[opt=`beautiful.notification_shape`] gears.shape args.shape Widget shape. --- @tparam[opt=`beautiful.notification_opacity`] gears.opacity args.opacity Widget opacity. --- @tparam[opt=`beautiful.notification_margin`] gears.margin args.margin Widget margin. --- @tparam[opt] func args.run Function to run on left click. The notification +-- @tparam[opt=true] boolean args.ontop Boolean forcing popups to display on top. +-- @tparam[opt=`beautiful.notification_height` or auto] integer args.height Popup height. +-- @tparam[opt=`beautiful.notification_width` or auto] integer args.width Popup width. +-- @tparam[opt=`beautiful.notification_font` or `beautiful.font` or `awesome.font`] string|lgi.Pango.FontDescription args.font Notification font. +-- @tparam[opt] image args.icon Path to icon. +-- @tparam[opt] integer args.icon_size Desired icon size in px. +-- @tparam[opt=`beautiful.notification_fg` or `beautiful.fg_focus` or `'#ffffff'`] string args.fg Foreground color. +-- @tparam[opt=`beautiful.notification_fg` or `beautiful.bg_focus` or `'#535d6c'`] string args.bg Background color. +-- @tparam[opt=`beautiful.notification_border_width` or 1] integer args.border_width Border width. +-- @tparam[opt=`beautiful.notification_border_color` or `beautiful.border_color_active` or `'#535d6c'`] gears.color args.border_color Border color. +-- @tparam[opt=beautiful.notification_shape] gears.shape args.shape Widget shape. +-- @tparam[opt=beautiful.notification_opacity] gears.opacity args.opacity Widget opacity. +-- @tparam[opt=beautiful.notification_margin] gears.margin args.margin Widget margin. +-- @tparam[opt] function args.run Function to run on left click. The notification -- object will be passed to it as an argument. -- You need to call e.g. -- `notification.die(naughty.notification_closed_reason.dismissedByUser)` from -- there to dismiss the notification yourself. --- @tparam[opt] func args.destroy Function to run when notification is destroyed. +-- @tparam[opt] function args.destroy Function to run when notification is destroyed. -- @tparam[opt] table args.preset Table with any of the above parameters. -- Note: Any parameters specified directly in args will override ones defined -- in the preset. --- @tparam[opt] func args.callback Function that will be called with all arguments. +-- @tparam[opt] function args.callback Function that will be called with all arguments. -- The notification will only be displayed if the function returns true. -- Note: this function is only relevant to notifications sent via dbus. -- @tparam[opt] table args.actions A list of `naughty.action`s. --- @bool[opt=false] args.ignore_suspend If set to true this notification +-- @tparam[opt=false] boolean args.ignore_suspend If set to true this notification -- will be shown even if notifications are suspended via `naughty.suspend`. --- @usage naughty.notify({ title = "Achtung!", message = "You're idling", timeout = 0 }) --- @treturn ?table The notification object, or nil in case a notification was --- not displayed. +-- @treturn naughty.notification A new notification object. -- @constructorfct naughty.notification +-- @usage naughty.notification { +-- title = "Achtung!", +-- message = "You're idling", timeout = 0 +-- } local function create(args) if cst.config.notify_callback then args = cst.config.notify_callback(args) @@ -1059,6 +1114,7 @@ end -- @method grant -- @tparam string permission The permission name (just the name, no `request::`). -- @tparam string context The reason why this permission is requested. +-- @noreturn -- @see awful.permissions --- Deny a permission for a notification @@ -1066,6 +1122,7 @@ end -- @method deny -- @tparam string permission The permission name (just the name, no `request::`). -- @tparam string context The reason why this permission is requested. +-- @noreturn -- @see awful.permissions pcommon.setup_grant(notification, "notification") diff --git a/lib/naughty/widget/icon.lua b/lib/naughty/widget/icon.lua index f17c5c9d4..d44025a2b 100644 --- a/lib/naughty/widget/icon.lua +++ b/lib/naughty/widget/icon.lua @@ -1,5 +1,5 @@ ---------------------------------------------------------------------------- ---- A notification square icon. +--- A notification square icon widget. -- -- This widget is a specialized `wibox.widget.imagebox` with the following extra -- features: @@ -14,6 +14,7 @@ -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2017 Emmanuel Lepage Vallee -- @widgetmod naughty.widget.icon +-- @supermodule wibox.widget.imagebox -- @see wibox.widget.imagebox ---------------------------------------------------------------------------- local imagebox = require("wibox.widget.imagebox") @@ -24,7 +25,7 @@ local dpi = require("beautiful.xresources").apply_dpi local icon = {} --- The default way to resize the icon. +--- The default way to resize the icon. -- @beautiful beautiful.notification_icon_resize_strategy -- @param number @@ -80,6 +81,7 @@ end --- The attached notification. -- @property notification -- @tparam naughty.notification notification +-- @propertydefault This is usually set in the construtor. -- @propemits true false function icon:set_notification(notif) @@ -112,12 +114,6 @@ local valid_strategies = { --- How small icons are handled. -- --- Valid values are: --- --- * **scale**: Scale the icon up to the optimal size. --- * **center**: Keep the icon size and draw it in the center --- * **resize**: Change the size of the widget itself (*default*). --- -- Note that the size upper bound is defined by -- `beautiful.notification_icon_size`. -- @@ -126,10 +122,18 @@ local valid_strategies = { -- @property resize_strategy -- @tparam string resize_strategy -- @propemits true false +-- @propertyvalue "scale" Scale the icon up to the optimal size. +-- @propertyvalue "center" Keep the icon size and draw it in the center +-- @propertyvalue "resize" Change the size of the widget itself (*default*). -- @usebeautiful beautiful.notification_icon_resize_strategy The fallback when -- there is no specified strategy. -- @usebeautiful beautiful.notification_icon_size The size upper bound. + +--- The default notification icon size. +-- @beautiful beautiful.notification_icon_size +-- @tparam number notification_icon_size The size (in pixels). + function icon:set_resize_strategy(strategy) assert(valid_strategies[strategy], "Invalid strategy") @@ -177,8 +181,6 @@ local function new(args) return tb end ---@DOC_widget_COMMON@ - --@DOC_object_COMMON@ return setmetatable(icon, {__call = function(_, ...) return new(...) end}) diff --git a/lib/naughty/widget/message.lua b/lib/naughty/widget/message.lua index 9224f1726..f0834d135 100644 --- a/lib/naughty/widget/message.lua +++ b/lib/naughty/widget/message.lua @@ -1,5 +1,5 @@ ---------------------------------------------------------------------------- ---- A notification content message. +--- A notification content message widget. -- -- This widget is a specialized `wibox.widget.textbox` with the following extra -- features: @@ -12,6 +12,7 @@ -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2017 Emmanuel Lepage Vallee -- @widgetmod naughty.widget.message +-- @supermodule wibox.widget.textbox -- @see wibox.widget.textbox ---------------------------------------------------------------------------- local textbox = require("wibox.widget.textbox") @@ -24,6 +25,7 @@ local message = {} --- The attached notification. -- @property notification -- @tparam naughty.notification notification +-- @propertydefault This is usually set in the construtor. -- @propemits true false function message:set_notification(notif) @@ -85,8 +87,6 @@ local function new(args) return tb end ---@DOC_widget_COMMON@ - --@DOC_object_COMMON@ return setmetatable(message, {__call = function(_, ...) return new(...) end}) diff --git a/lib/naughty/widget/title.lua b/lib/naughty/widget/title.lua index dceba4f95..8b58448a8 100644 --- a/lib/naughty/widget/title.lua +++ b/lib/naughty/widget/title.lua @@ -1,5 +1,5 @@ ---------------------------------------------------------------------------- ---- A notification title. +--- A notification title widget. -- -- This widget is a specialized `wibox.widget.textbox` with the following extra -- features: @@ -12,6 +12,7 @@ -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2017 Emmanuel Lepage Vallee -- @widgetmod naughty.widget.title +-- @supermodule wibox.widget.textbox -- @see wibox.widget.textbox ---------------------------------------------------------------------------- local textbox = require("wibox.widget.textbox") @@ -24,6 +25,7 @@ local title = {} --- The attached notification. -- @property notification -- @tparam naughty.notification notification +-- @propertydefault This is usually set in the construtor. -- @propemits true false function title:set_notification(notif) @@ -86,8 +88,6 @@ local function new(args) return tb end ---@DOC_widget_COMMON@ - --@DOC_object_COMMON@ return setmetatable(title, {__call = function(_, ...) return new(...) end}) diff --git a/lib/ruled/client.lua b/lib/ruled/client.lua index 54af13a3d..0ac6f049d 100644 --- a/lib/ruled/client.lua +++ b/lib/ruled/client.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Rules for clients. +--- Apply properties to a new client based on pre-determined rules. -- -- This module applies @{rules} to clients during startup (via @{client.manage}, -- but its functions can be used for client matching in general. @@ -180,9 +180,10 @@ end --- Apply ruled.client.rules to a client. -- @tparam client c The client. +-- @noreturn -- @staticfct ruled.client.apply function module.apply(c) - return crules:apply(c) + crules:apply(c) end --- Add a new rule to the default set. @@ -527,7 +528,8 @@ end --- Apply properties and callbacks to a client. -- @tparam client c The client. -- @tparam table props Properties to apply. --- @tparam[opt] table callbacks Callbacks to apply. +-- @tparam[opt={}] table callbacks Callbacks to apply. +-- @noreturn -- @staticfct ruled.client.execute -- @request client titlebars rules granted The `titlebars_enabled` is set in the -- rules. diff --git a/lib/ruled/notification.lua b/lib/ruled/notification.lua index de6b306e5..6203cb3b6 100644 --- a/lib/ruled/notification.lua +++ b/lib/ruled/notification.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Rules for notifications. +--- Apply properties to a new `naughty.notification` based on pre-determined rules. -- --@DOC_wibox_nwidget_rules_urgency_EXAMPLE@ -- @@ -158,6 +158,7 @@ end -- -- @tparam naughty.notification n The notification. -- @staticfct ruled.notification.apply +-- @noreturn function module.apply(n) local callbacks, props = {}, {} @@ -179,6 +180,7 @@ end --- Add a new rule to the default set. -- @tparam table rule A valid rule. -- @staticfct ruled.notification.append_rule +-- @noreturn function module.append_rule(rule) nrules:append_rule("ruled.notifications", rule) end @@ -186,16 +188,20 @@ end --- Add a new rules to the default set. -- @tparam table rule A table with rules. -- @staticfct ruled.notification.append_rules +-- @noreturn function module.append_rules(rules) nrules:append_rules("ruled.notifications", rules) end --- Remove a new rule to the default set. -- @tparam table rule A valid rule. +-- @treturn boolean `true` if the rule was removed. -- @staticfct ruled.notification.remove_rule function module.remove_rule(rule) - nrules:remove_rule("ruled.notifications", rule) + local ret = nrules:remove_rule("ruled.notifications", rule) module.emit_signal("rule::removed", rule) + + return ret end --- Add a new rule source. diff --git a/lib/wibox/container/arcchart.lua b/lib/wibox/container/arcchart.lua index dde2327ee..d7138685f 100644 --- a/lib/wibox/container/arcchart.lua +++ b/lib/wibox/container/arcchart.lua @@ -1,6 +1,5 @@ --------------------------------------------------------------------------- --- --- A circular chart (arc chart). +-- A circular chart (arc chart) container. -- -- It can contain a central widget (or not) and display multiple values. -- @@ -43,7 +42,19 @@ local arcchart = { mt = {} } --- The arc thickness. -- @beautiful beautiful.arcchart_thickness --- @param number +-- @tparam number arcchart_thickness + +--- If the chart has rounded edges. +-- @beautiful beautiful.arcchart_rounded_edge +-- @tparam boolean arcchart_rounded_edge + +--- The radial background. +-- @beautiful beautiful.arcchart_bg +-- @tparam gears.color arcchart_bg + +--- The (radiant) angle where the first value start. +-- @beautiful beautiful.arcchart_start_angle +-- @tparam number arcchart_start_angle local function outline_workarea(width, height) local x, y = 0, 0 @@ -102,7 +113,6 @@ function arcchart:after_draw_children(_, cr, width, height) local wa = outline_workarea(width, height) cr:translate(wa.x+border_width/2, wa.y+border_width/2) - -- Get the min and max value --local min_val = self:get_min_value() or 0 --TODO support min_values local max_val = self:get_max_value() @@ -191,7 +201,7 @@ end --- The widget to wrap in a radial proggressbar. -- @property widget --- @tparam widget widget The widget +-- @tparam[opt=nil] widget|nil widget -- @interface container arcchart.set_widget = base.set_widget_common @@ -207,6 +217,7 @@ end --- Reset this layout. The widget will be removed and the rotation reset. -- @method reset +-- @noreturn -- @interface container function arcchart:reset() self:set_widget(nil) @@ -229,6 +240,10 @@ end -- @tparam[opt=0] number paddings.bottom -- @tparam[opt=0] number paddings.left -- @tparam[opt=0] number paddings.right +-- @propertytype number A single padding value for each side. +-- @propertytype table A different padding value for each side. +-- @propertyunit pixel +-- @negativeallowed false -- @emits [opt=bob] property::paddings When the `paddings` changes. -- @emitstparam property::paddings widget self The object being modified. -- @emitstparam property::paddings table paddings The new paddings. @@ -238,40 +253,46 @@ end --- The border background color. --@DOC_wibox_container_arcchart_border_color_EXAMPLE@ -- @property border_color --- @tparam color border_color +-- @tparam color|nil border_color -- @propemits true false -- @propbeautiful --- The arcchart values foreground colors. --@DOC_wibox_container_arcchart_color_EXAMPLE@ -- @property colors --- @tparam table values An ordered set of colors for each value in arcchart. +-- @tparam table colors +-- @tablerowtype An ordered list of colors for each value in arcchart. -- @propemits true false --- @propbeautiful +-- @usebeautiful beautiful.arcchart_color --- The border width. -- --@DOC_wibox_container_arcchart_border_width_EXAMPLE@ -- -- @property border_width --- @tparam[opt=3] number border_width +-- @tparam[opt=0] number|nil border_width +-- @negativeallowed false +-- @propertyunit pixel -- @propemits true false -- @propbeautiful --- The minimum value. -- @property min_value --- @tparam number min_value +-- @tparam[opt=0] number min_value +-- @negativeallowed true -- @propemits true false --- The maximum value. -- @property max_value -- @tparam number max_value +-- @propertydefault The sum of all `values`. +-- @negativeallowed true -- @propemits true false --- The radial background. --@DOC_wibox_container_arcchart_bg_EXAMPLE@ -- @property bg --- @tparam color bg +-- @tparam color|nil bg -- @see gears.color -- @propemits true false -- @propbeautiful @@ -279,7 +300,10 @@ end --- The value. --@DOC_wibox_container_arcchart_value_EXAMPLE@ -- @property value --- @tparam number value Between min_value and max_value +-- @tparam[opt=0] number value +-- @rangestart `min_value` +-- @rangestop `max_value` +-- @negativeallowed true -- @see values -- @propemits true false @@ -288,27 +312,35 @@ end -- shown in table order. --@DOC_wibox_container_arcchart_values_EXAMPLE@ -- @property values --- @tparam table values An ordered set of values. +-- @tparam[opt={}] table values An ordered set of values. +-- @tablerowtype A list of numbers. -- @propemits true false -- @see value --- If the chart has rounded edges. --@DOC_wibox_container_arcchart_rounded_edge_EXAMPLE@ -- @property rounded_edge --- @tparam[opt=false] boolean rounded_edge +-- @tparam[opt=false] boolean|nil rounded_edge -- @propemits true false +-- @propbeautiful --- The arc thickness. --@DOC_wibox_container_arcchart_thickness_EXAMPLE@ -- @property thickness -- @propemits true false --- @tparam number thickness +-- @tparam number|nil thickness +-- @propertyunit pixel +-- @negativeallowed false +-- @propbeautiful --- The (radiant) angle where the first value start. ---@DOC_wibox_container_arcchart_start_angle_EXAMPLE@ +-- @DOC_wibox_container_arcchart_start_angle_EXAMPLE@ -- @property start_angle --- @tparam[opt=math.pi] number start_angle A number between 0 and 2*math.pi +-- @tparam[opt=math.pi] number start_angle +-- @rangestart 0 +-- @rangestop 2*math.pi -- @propemits true false +-- @usebeautiful beautiful.arcchart_start_angle for _, prop in ipairs {"border_width", "border_color", "paddings", "colors", "rounded_edge", "bg", "thickness", "values", "min_value", "max_value", diff --git a/lib/wibox/container/background.lua b/lib/wibox/container/background.lua index 580c8fd66..8262d6a7e 100644 --- a/lib/wibox/container/background.lua +++ b/lib/wibox/container/background.lua @@ -235,8 +235,8 @@ end --- The widget displayed in the background widget. -- @property widget --- @tparam widget widget The widget to be disaplayed inside of the background --- area. +-- @tparam[opt=nil] widget|nil widget The widget to be disaplayed inside of +-- the background area. -- @interface container background.set_widget = base.set_widget_common @@ -258,7 +258,9 @@ end --@DOC_wibox_container_background_bg_EXAMPLE@ -- -- @property bg --- @tparam color bg A color string, pattern or gradient +-- @tparam color bg +-- @propertydefault When unspecified, it will inherit the value from an higher +-- level `wibox.container.background` or directly from the `wibox.bg` property. -- @see gears.color -- @propemits true false @@ -282,6 +284,8 @@ end -- -- @property fg -- @tparam color fg A color string, pattern or gradient +-- @propertydefault When unspecified, it will inherit the value from an higher +-- level `wibox.container.background` or directly from the `wibox.fg` property. -- @propemits true false -- @see gears.color @@ -306,7 +310,7 @@ end --@DOC_wibox_container_background_shape_EXAMPLE@ -- -- @property shape --- @tparam gears.shape|function shape A function taking a context, width and height as arguments +-- @tparam[opt=gears.shape.rectangle] shape shape -- @see gears.shape -- @see set_shape @@ -316,6 +320,7 @@ end -- -- @method set_shape -- @tparam gears.shape|function shape A function taking a context, width and height as arguments +-- @noreturn -- @propemits true false -- @see gears.shape -- @see shape @@ -349,7 +354,9 @@ end -- -- See `wibox.container.background.shape` for an usage example. -- @property border_width --- @tparam[opt=0] number width The border width. +-- @tparam[opt=0] number border_width +-- @propertyunit pixel +-- @negativeallowed false -- @propemits true false -- @introducedin 4.4 -- @see border_color @@ -386,7 +393,7 @@ end -- -- @deprecatedproperty shape_border_color -- @usebeautiful beautiful.fg_normal Fallback when 'fg' and `border_color` aren't set. --- @tparam[opt=self._private.foreground] color fg The border color, pattern or gradient +-- @tparam color fg The border color, pattern or gradient -- @renamedin 4.4 border_color -- @see gears.color -- @see border_color @@ -395,7 +402,8 @@ end -- -- See `wibox.container.background.shape` for an usage example. -- @property border_color --- @tparam[opt=self._private.foreground] color fg The border color, pattern or gradient +-- @tparam color border_color +-- @propertydefault `wibox.container.background.fg` if set, otherwise `beautiful.fg_normal`. -- @propemits true false -- @usebeautiful beautiful.fg_normal Fallback when 'fg' and `border_color` aren't set. -- @introducedin 4.4 @@ -442,13 +450,10 @@ end --- How the border width affects the contained widget. -- --- The valid values are: --- --- * *none*: Just apply the border, do not affect the content size (default). --- * *inner*: Squeeze the size of the content by the border width. --- -- @property border_strategy -- @tparam[opt="none"] string border_strategy +-- @propertyvalue "none" Just apply the border, do not affect the content size (default). +-- @propertyvalue "inner" Squeeze the size of the content by the border width. function background:set_border_strategy(value) self._private.border_strategy = value @@ -462,7 +467,7 @@ end -- as arguments. Any other arguments passed to this method will be appended. -- -- @property bgimage --- @tparam string|surface|function image A background image or a function +-- @tparam[opt=nil] image|nil bgimage -- @see gears.surface function background:set_bgimage(image, ...) diff --git a/lib/wibox/container/constraint.lua b/lib/wibox/container/constraint.lua index 62c051f01..a1c36bcfd 100644 --- a/lib/wibox/container/constraint.lua +++ b/lib/wibox/container/constraint.lua @@ -43,7 +43,7 @@ end --- The widget to be constrained. -- -- @property widget --- @tparam widget widget The widget +-- @tparam[opt=nil] widget|nil widget -- @interface container constraint.set_widget = base.set_widget_common @@ -61,14 +61,12 @@ function constraint:set_children(children) end --- Set the strategy to use for the constraining. --- Valid values are: --- --- * **max**: Never allow the size to be larger than the limit. --- * **min**: Never allow the size to tbe below the limit. --- * **exact**: Force the widget size. -- -- @property strategy --- @tparam string strategy Either 'max', 'min' or 'exact'. +-- @tparam[opt="max"] string strategy +-- @propertyvalue "max" Never allow the size to be larger than the limit. +-- @propertyvalue "min" Never allow the size to tbe below the limit. +-- @propertyvalue "exact" Force the widget size. -- @propemits true false function constraint:set_strategy(val) @@ -100,7 +98,11 @@ end --- Set the maximum width to val. nil for no width limit. -- -- @property width --- @tparam number width +-- @tparam[opt=nil] number|nil width +-- @negativeallowed false +-- @propertyunit pixel +-- @propertytype nil Do not set a width limit. +-- @propertytype number Set a width limit. -- @propemits true false function constraint:set_width(val) @@ -116,7 +118,11 @@ end --- Set the maximum height to val. nil for no height limit. -- -- @property height --- @tparam number height +-- @tparam[opt=nil] number|nil height +-- @negativeallowed false +-- @propertyunit pixel +-- @propertytype nil Do not set a height limit. +-- @propertytype number Set a height limit. -- @propemits true false function constraint:set_height(val) @@ -135,6 +141,7 @@ end -- and the constraints set to nil. -- -- @method reset +-- @noreturn -- @interface container function constraint:reset() self._private.width = nil diff --git a/lib/wibox/container/margin.lua b/lib/wibox/container/margin.lua index 7df9cd9cf..eb28eb576 100644 --- a/lib/wibox/container/margin.lua +++ b/lib/wibox/container/margin.lua @@ -74,7 +74,7 @@ end --- The widget to be wrapped the the margins. -- -- @property widget --- @tparam widget widget The widget +-- @tparam[opt=nil] widget|nil widget -- @interface container margin.set_widget = base.set_widget_common @@ -94,8 +94,15 @@ end --- Set all the margins to val. -- -- @property margins --- @tparam number|table val The margin value. It can be a number or a table with --- the *left*/*right*/*top*/*bottom* keys. +-- @tparam[opt=0] number|table margins +-- @tparam[opt=0] number margins.left +-- @tparam[opt=0] number margins.right +-- @tparam[opt=0] number margins.top +-- @tparam[opt=0] number margins.bottom +-- @propertytype number A single value for all margins. +-- @propertytype table A different value for each side. +-- @propertyunit pixel +-- @negativeallowed false -- @propemits false false function margin:set_margins(val) @@ -126,7 +133,8 @@ end --- Set the margins color to create a border. -- -- @property color --- @param color A color used to fill the margin. +-- @tparam[opt=nil] color|nil color A color used to fill the margin. +-- @propertytype nil Transparent margins. -- @propemits true false function margin:set_color(color) @@ -142,7 +150,7 @@ end --- Draw the margin even if the content size is 0x0. -- -- @property draw_empty --- @tparam[opt=true] boolean draw_empty Draw nothing is content is 0x0 or draw +-- @tparam[opt=true] boolean draw_empty Draw nothing is content is `0x0` or draw -- the margin anyway. -- @propemits true false @@ -156,9 +164,11 @@ function margin:get_draw_empty() return self._private.draw_empty end ---- Reset this layout. The widget will be unreferenced, the margins set to 0 +--- Reset this layout. +-- The widget will be unreferenced, the margins set to 0 -- and the color erased -- @method reset +-- @noreturn -- @interface container function margin:reset() self:set_widget(nil) @@ -169,25 +179,33 @@ end --- Set the left margin that this layout adds to its widget. -- -- @property left --- @tparam number left The new margin to use. +-- @tparam[opt=0] number left +-- @negativeallowed false +-- @propertyunit pixel -- @propemits true false --- Set the right margin that this layout adds to its widget. -- -- @property right --- @tparam number right The new margin to use. +-- @tparam[opt=0] number right +-- @negativeallowed false +-- @propertyunit pixel -- @propemits true false --- Set the top margin that this layout adds to its widget. -- -- @property top --- @tparam number top The new margin to use. +-- @tparam[opt=0] number top +-- @negativeallowed false +-- @propertyunit pixel -- @propemits true false --- Set the bottom margin that this layout adds to its widget. -- -- @property bottom --- @tparam number bottom The new margin to use. +-- @tparam[opt=0] number bottom +-- @negativeallowed false +-- @propertyunit pixel -- @propemits true false -- Create setters for each direction @@ -206,13 +224,13 @@ end --- Returns a new margin container. -- --- @param[opt] widget A widget to use. --- @param[opt] left A margin to use on the left side of the widget. --- @param[opt] right A margin to use on the right side of the widget. --- @param[opt] top A margin to use on the top side of the widget. --- @param[opt] bottom A margin to use on the bottom side of the widget. --- @param[opt] color A color for the margins. --- @param[opt] draw_empty whether or not to draw the margin when the content is empty +-- @tparam[opt] widget widget A widget to use. +-- @tparam[opt] number left A margin to use on the left side of the widget. +-- @tparam[opt] number right A margin to use on the right side of the widget. +-- @tparam[opt] number top A margin to use on the top side of the widget. +-- @tparam[opt] number bottom A margin to use on the bottom side of the widget. +-- @tparam[opt] gears.color color A color for the margins. +-- @tparam[opt] boolean draw_empty Whether or not to draw the margin when the content is empty -- @treturn table A new margin container -- @constructorfct wibox.container.margin local function new(widget, left, right, top, bottom, color, draw_empty) diff --git a/lib/wibox/container/mirror.lua b/lib/wibox/container/mirror.lua index 288308823..49b59538d 100644 --- a/lib/wibox/container/mirror.lua +++ b/lib/wibox/container/mirror.lua @@ -50,7 +50,7 @@ end --- The widget to be reflected. -- -- @property widget --- @tparam widget widget The widget. +-- @tparam[opt=nil] widget|nil widget -- @interface container mirror.set_widget = base.set_widget_common @@ -70,6 +70,7 @@ end --- Reset this layout. The widget will be removed and the axes reset. -- -- @method reset +-- @noreturn -- @interface container function mirror:reset() self._private.horizontal = false @@ -95,8 +96,8 @@ end -- -- @property reflection -- @tparam table reflection A table of booleans with the keys "horizontal", "vertical". --- @tparam boolean reflection.horizontal --- @tparam boolean reflection.vertical +-- @tparam[opt=false] boolean reflection.horizontal +-- @tparam[opt=false] boolean reflection.vertical -- @propemits true false function mirror:get_reflection() diff --git a/lib/wibox/container/place.lua b/lib/wibox/container/place.lua index 7fd6a8091..66d198662 100644 --- a/lib/wibox/container/place.lua +++ b/lib/wibox/container/place.lua @@ -75,7 +75,7 @@ end --- The widget to be placed. -- -- @property widget --- @tparam widget widget The widget +-- @tparam[opt=nil] widget|nil widget -- @interface container place.set_widget = base.set_widget_common @@ -94,6 +94,7 @@ end --- Reset this layout. The widget will be removed and the rotation reset. -- @method reset +-- @noreturn -- @interface container function place:reset() self:set_widget(nil) @@ -101,30 +102,24 @@ end --- The vertical alignment. -- --- Possible values are: --- --- * *top* --- * *center* (default) --- * *bottom* --- --@DOC_wibox_container_place_valign_EXAMPLE@ -- -- @property valign -- @tparam[opt="center"] string valign +-- @propertyvalue "top" +-- @propertyvalue "center" +-- @propertyvalue "bottom" -- @propemits true false --- The horizontal alignment. -- --- Possible values are: --- --- * *left* --- * *center* (default) --- * *right* --- --@DOC_wibox_container_place_halign_EXAMPLE@ -- -- @property halign -- @tparam[opt="center"] string halign +-- @propertyvalue "left" +-- @propertyvalue "center" +-- @propertyvalue "right" -- @propemits true false function place:set_valign(value) diff --git a/lib/wibox/container/radialprogressbar.lua b/lib/wibox/container/radialprogressbar.lua index b8ec08055..11c676787 100644 --- a/lib/wibox/container/radialprogressbar.lua +++ b/lib/wibox/container/radialprogressbar.lua @@ -131,7 +131,7 @@ end --- The widget to wrap in a radial proggressbar. -- -- @property widget --- @tparam widget widget The widget +-- @tparam[opt=nil] widget|nil widget -- @interface container radialprogressbar.set_widget = base.set_widget_common @@ -148,6 +148,7 @@ end --- Reset this container. -- -- @method reset +-- @noreturn -- @interface container function radialprogressbar:reset() self:set_widget(nil) @@ -166,11 +167,15 @@ end -- --@DOC_wibox_container_radialprogressbar_padding_EXAMPLE@ -- @property paddings --- @tparam[opt=0] table|number paddings A number or a table +-- @tparam[opt=0] table|number|nil paddings A number or a table -- @tparam[opt=0] number paddings.top -- @tparam[opt=0] number paddings.bottom -- @tparam[opt=0] number paddings.left -- @tparam[opt=0] number paddings.right +-- @propertytype number A single value for each sides. +-- @propertytype table A different value for each side. +-- @negativeallowed false +-- @propertyunit pixel -- @propbeautiful -- @propemits false false @@ -178,7 +183,10 @@ end -- --@DOC_wibox_container_radialprogressbar_value_EXAMPLE@ -- @property value --- @tparam number value Between min_value and max_value. +-- @tparam[opt=0] number value +-- @rangestart `min_value` +-- @rangestop `max_value` +-- @negativeallowed true -- @propemits true false function radialprogressbar:set_value(val) @@ -201,7 +209,7 @@ end -- --@DOC_wibox_container_radialprogressbar_border_color_EXAMPLE@ -- @property border_color --- @tparam color border_color +-- @tparam color|nil border_color -- @propbeautiful -- @propemits true false @@ -209,7 +217,7 @@ end -- --@DOC_wibox_container_radialprogressbar_color_EXAMPLE@ -- @property color --- @tparam color color +-- @tparam color|nil color -- @propbeautiful -- @propemits true false @@ -217,20 +225,24 @@ end -- --@DOC_wibox_container_radialprogressbar_border_width_EXAMPLE@ -- @property border_width --- @tparam[opt=3] number border_width +-- @tparam[opt=2] number|nil border_width +-- @negativeallowed false +-- @propertyunit pixel -- @propbeautiful -- @propemits true false --- The minimum value. -- -- @property min_value --- @tparam number min_value +-- @tparam[opt=0] number min_value +-- @negativeallowed true -- @propemits true false --- The maximum value. -- -- @property max_value --- @tparam number max_value +-- @tparam[opt=1] number max_value +-- @negativeallowed true -- @propemits true false for _, prop in ipairs {"max_value", "min_value", "border_color", "color", diff --git a/lib/wibox/container/rotate.lua b/lib/wibox/container/rotate.lua index 9da97003f..571854008 100644 --- a/lib/wibox/container/rotate.lua +++ b/lib/wibox/container/rotate.lua @@ -62,7 +62,7 @@ end --- The widget to be rotated. -- -- @property widget --- @tparam widget widget The widget. +-- @tparam[opt=nil] widget|nil widget -- @interface container rotate.set_widget = base.set_widget_common @@ -84,6 +84,7 @@ end -- The widget will be removed and the rotation reset. -- -- @method reset +-- @noreturn -- @interface container function rotate:reset() self._private.direction = nil @@ -92,16 +93,13 @@ end --- The direction of this rotating container. -- --- Valid values are: --- --- * *north* --- * *east* --- * *south* --- * *north* --- --@DOC_wibox_container_rotate_angle_EXAMPLE@ -- @property direction --- @tparam string dir The direction. +-- @tparam[opt="north"] string direction +-- @propertyvalue "north" +-- @propertyvalue "east" +-- @propertyvalue "south" +-- @propertyvalue "north" -- @propemits true false function rotate:set_direction(dir) diff --git a/lib/wibox/container/scroll.lua b/lib/wibox/container/scroll.lua index 46f928229..85c706dc6 100644 --- a/lib/wibox/container/scroll.lua +++ b/lib/wibox/container/scroll.lua @@ -222,6 +222,7 @@ end --- Pause the scrolling animation. -- @method pause +-- @noreturn -- @see continue function scroll:pause() if self._private.paused then @@ -233,6 +234,7 @@ end --- Continue the scrolling animation. -- @method continue +-- @noreturn -- @see pause function scroll:continue() if not self._private.paused then @@ -248,6 +250,7 @@ end -- display the widget without any scrolling applied. -- This function does not undo the effect of @{pause}. -- @method reset_scrolling +-- @noreturn function scroll:reset_scrolling() self._private.timer:start() if self._private.paused then @@ -258,6 +261,7 @@ end --- Set the direction in which this widget scroll. -- @method set_direction -- @param dir Either "h" for horizontal scrolling or "v" for vertical scrolling +-- @noreturn function scroll:set_direction(dir) if dir == self._private.dir then return @@ -272,7 +276,7 @@ end --- The widget to be scrolled. -- @property widget --- @tparam widget widget The widget +-- @tparam[opt=nil] widget|nil widget function scroll:set_widget(widget) if widget == self._private.widget then @@ -306,6 +310,7 @@ end -- @method set_expand -- @tparam boolean expand If true, the widget is expanded to include the extra -- space. If false, the extra space is simply left empty. +-- @noreturn -- @see set_extra_space function scroll:set_expand(expand) if expand == self._private.expand then @@ -318,6 +323,7 @@ end --- Set the number of frames per second that this widget should draw. -- @method set_fps -- @tparam number fps The number of frames per second +-- @noreturn function scroll:set_fps(fps) if fps == self._private.fps then return @@ -331,6 +337,7 @@ end -- extra space will likely be left empty between repetitions of the widgets. -- @method set_extra_space -- @tparam number extra_space The amount of extra space +-- @noreturn -- @see set_expand function scroll:set_extra_space(extra_space) if extra_space == self._private.extra_space then @@ -345,6 +352,7 @@ end -- in pixels per second. -- @method set_speed -- @tparam number speed The speed for the animation +-- @noreturn function scroll:set_speed(speed) if speed == self._private.speed then return @@ -359,6 +367,7 @@ end -- and the rest is made visible via scrolling. -- @method set_max_size -- @tparam number max_size The maximum size of this widget or nil for unlimited. +-- @noreturn function scroll:set_max_size(max_size) if max_size == self._private.max_size then return @@ -384,6 +393,7 @@ end -- which the widget is drawn and should be between 0 and `size+extra_space`. -- @method set_step_function -- @tparam function step_function A step function. +-- @noreturn -- @see step_functions function scroll:set_step_function(step_function) -- Call the step functions once to see if it works @@ -399,6 +409,7 @@ end -- This restricts the child widget's maximal size. -- @method set_space_for_scrolling -- @tparam number space_for_scrolling The space for scrolling +-- @noreturn function scroll:set_space_for_scrolling(space_for_scrolling) if space_for_scrolling == self._private.space_for_scrolling then return diff --git a/lib/wibox/container/tile.lua b/lib/wibox/container/tile.lua index 46fdd391c..15c264dd1 100644 --- a/lib/wibox/container/tile.lua +++ b/lib/wibox/container/tile.lua @@ -92,8 +92,10 @@ end --@DOC_wibox_container_tile_horizontal_spacing_EXAMPLE@ -- -- @property horizontal_spacing --- @tparam number horizontal_spacing +-- @tparam[opt=0] number horizontal_spacing -- @propemits true false +-- @propertyunit pixel +-- @negativeallowed false -- @see vertical_spacing --- The vertical spacing between the tiled. @@ -101,7 +103,9 @@ end --@DOC_wibox_container_tile_vertical_spacing_EXAMPLE@ -- -- @property vertical_spacing --- @tparam number vertical_spacing +-- @tparam[opt=0] number vertical_spacing +-- @propertyunit pixel +-- @negativeallowed false -- @propemits true false -- @see horizontal_spacing @@ -110,7 +114,7 @@ end --@DOC_wibox_container_tile_horizontal_crop_EXAMPLE@ -- -- @property horizontal_crop --- @tparam[opt=false] boolean tiled +-- @tparam[opt=false] boolean horizontal_crop -- @see vertical_crop --- Avoid painting incomplete vertical tiles. @@ -118,7 +122,7 @@ end --@DOC_wibox_container_tile_vertical_crop_EXAMPLE@ -- -- @property vertical_crop --- @tparam[opt=false] boolean tiled +-- @tparam[opt=false] boolean vertical_crop -- @see horizontal_crop --- Enable or disable the tiling. @@ -199,9 +203,19 @@ end --- Create a new tile container. -- @tparam table args --- @tparam wibox.widget widget args.widget The widget to tile. +-- @tparam wibox.widget args.widget args.widget The widget to tile. -- @tparam string args.halign Either `left`, `right` or `center`. -- @tparam string args.valign Either `top`, `bottom` or `center`. +-- @tparam number args.horizontal_spacing The horizontal spacing between the tiled. +-- @tparam number args.vertical_spacing The vertical spacing between the tiled. +-- @tparam boolean args.horizontal_crop Avoid painting incomplete horizontal tiles. +-- @tparam boolean args.vertical_crop Avoid painting incomplete vertical tiles. +-- @tparam boolean args.tiled Enable or disable the tiling. +-- @tparam wibox.widget args.widget The widget to be placed. +-- @tparam boolean args.fill_vertical Fill the vertical space. +-- @tparam boolean args.fill_horizontal Fill the horizontal space. +-- @tparam boolean args.content_fill_vertical Stretch the contained widget so it takes all the vertical space. +-- @tparam boolean args.content_fill_horizontal Stretch the contained widget so it takes all the horizontal space. -- @constructorfct wibox.container.tile function module.mt:__call(...) return new(...) diff --git a/lib/wibox/drawable.lua b/lib/wibox/drawable.lua index b8748df77..b79bb3d67 100644 --- a/lib/wibox/drawable.lua +++ b/lib/wibox/drawable.lua @@ -199,7 +199,7 @@ local function find_widgets(self, result, hierarchy, x, y) end end ---- Find a widget by a point. +-- Find a widget by a point. -- The drawable must have drawn itself at least once for this to work. -- @param x X coordinate of the point -- @param y Y coordinate of the point diff --git a/lib/wibox/hierarchy.lua b/lib/wibox/hierarchy.lua index 3472716d1..13ec3e4e3 100644 --- a/lib/wibox/hierarchy.lua +++ b/lib/wibox/hierarchy.lua @@ -23,6 +23,7 @@ local widgets_to_count = setmetatable({}, { __mode = "k" }) -- visible in any hierarchy. -- @param widget The widget that should be counted. -- @staticfct wibox.hierarchy.count_widget +-- @noreturn function hierarchy.count_widget(widget) widgets_to_count[widget] = true end @@ -232,6 +233,7 @@ end --- Get the widget that this hierarchy manages. -- @method get_widget +-- @treturn wibox.widget The widget held by this node. function hierarchy:get_widget() return self._widget end @@ -318,6 +320,7 @@ end -- @param context The context in which widgets are drawn. -- @param cr The cairo context that is used for drawing. -- @method draw +-- @noreturn function hierarchy:draw(context, cr) local widget = self:get_widget() if not widget._private.visible then diff --git a/lib/wibox/init.lua b/lib/wibox/init.lua index e606864b7..9715a93ee 100644 --- a/lib/wibox/init.lua +++ b/lib/wibox/init.lua @@ -1,4 +1,6 @@ --------------------------------------------------------------------------- +-- Box where widget can be displayed. +-- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter -- @popupmod wibox @@ -101,6 +103,7 @@ end -- @tparam string path The path. -- @tparam[opt=nil] table context A widget context. -- @method save_to_svg +-- @noreturn function wibox:save_to_svg(path, context) wibox.widget.draw_to_svg_file( self:to_widget(), path, self:geometry().width, self:geometry().height, context @@ -402,6 +405,7 @@ end -- automatically called when needed. -- @param wibox -- @method draw +-- @noreturn --- Connect a global signal on the wibox class. -- @@ -414,6 +418,7 @@ end -- @tparam string name The name of the signal -- @tparam function func The function to attach -- @staticfct wibox.connect_signal +-- @noreturn -- @usage wibox.connect_signal("added", function(notif) -- -- do something -- end) @@ -422,6 +427,7 @@ end -- @tparam string name The signal name. -- @param ... The signal callback arguments -- @staticfct wibox.emit_signal +-- @noreturn --- Disconnect a signal from a source. -- @tparam string name The name of the signal diff --git a/lib/wibox/layout/align.lua b/lib/wibox/layout/align.lua index 58f341794..93ee8a7f7 100644 --- a/lib/wibox/layout/align.lua +++ b/lib/wibox/layout/align.lua @@ -164,7 +164,10 @@ end -- This is the widget that is at the left/top. -- -- @property first --- @tparam widget first +-- @tparam[opt=nil] widget|nil first +-- @propertytype nil This spot will be empty. Depending on how large the second +-- widget is an and the value of `expand`, it might mean it will leave an empty +-- area. -- @propemits true false function align:set_first(widget) @@ -181,7 +184,9 @@ end -- This is the centered one. -- -- @property second --- @tparam widget second +-- @tparam[opt=nil] widget|nil second +-- @propertytype nil When this property is `nil`, then there will be an empty +-- area. -- @propemits true false function align:set_second(widget) @@ -198,7 +203,10 @@ end -- This is the widget that is at the right/bottom. -- -- @property third --- @tparam widget third +-- @tparam[opt=nil] widget|nil third +-- @propertytype nil This spot will be empty. Depending on how large the second +-- widget is an and the value of `expand`, it might mean it will leave an empty +-- area. -- @propemits true false function align:set_third(widget) @@ -256,24 +264,21 @@ end --- Set the expand mode, which determines how child widgets expand to take up -- unused space. -- --- The following values are valid: --- --- * `"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 expand How to use unused space. +-- @propertyvalue "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. +-- @propertyvalue "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. +-- @propertyvalue "none" All widgets are given their minimal required size or the +-- remaining space, whichever is smaller. The center widget gets priority. function align:set_expand(mode) if mode == "none" or mode == "outside" then diff --git a/lib/wibox/layout/fixed.lua b/lib/wibox/layout/fixed.lua index bd76c3207..d40c160d1 100644 --- a/lib/wibox/layout/fixed.lua +++ b/lib/wibox/layout/fixed.lua @@ -1,4 +1,6 @@ --------------------------------------------------------------------------- +-- Place many widgets in a column or row, until the available space is used up. +-- -- A `fixed` layout may be initialized with any number of child widgets, and -- during runtime widgets may be added and removed dynamically. -- @@ -134,6 +136,7 @@ end -- -- @method add -- @tparam widget ... Widgets that should be added (must at least be one). +-- @noreturn -- @interface layout function fixed:add(...) -- No table.pack in Lua 5.1 :-( @@ -296,7 +299,7 @@ end --@DOC_wibox_layout_fixed_spacing_widget_EXAMPLE@ -- -- @property spacing_widget --- @tparam widget spacing_widget +-- @tparam[opt=nil] widget|nil spacing_widget -- @propemits true false -- @interface layout @@ -401,7 +404,7 @@ end -- widget will get all the space that is left. If this is false, the last widget -- won't be handled specially and there can be space left unused. -- @property fill_space --- @tparam boolean fill_space +-- @tparam[opt=false] boolean fill_space -- @propemits true false function fixed:fill_space(val) @@ -452,7 +455,8 @@ end --@DOC_wibox_layout_fixed_spacing_EXAMPLE@ -- -- @property spacing --- @tparam number spacing Spacing between widgets. +-- @tparam[opt=0] number spacing Spacing between widgets. +-- @negativeallowed true -- @propemits true false -- @interface layout diff --git a/lib/wibox/layout/flex.lua b/lib/wibox/layout/flex.lua index 9fceef375..08335bcab 100644 --- a/lib/wibox/layout/flex.lua +++ b/lib/wibox/layout/flex.lua @@ -1,4 +1,7 @@ --------------------------------------------------------------------------- +-- Split the space equally between multiple widgets. +-- +-- -- A `flex` layout may be initialized with any number of child widgets, and -- during runtime widgets may be added and removed dynamically. -- @@ -35,7 +38,7 @@ local flex = {} --- From `wibox.layout.fixed`. -- @property fill_space --- @tparam boolean fill_space +-- @tparam[opt=true] boolean fill_space -- @propemits true false -- @hidden @@ -45,11 +48,12 @@ local flex = {} -- -- @tparam widget ... Widgets that should be added (must at least be one). -- @method add +-- @noreturn -- @interface layout --- Remove a widget from the layout. -- --- @tparam index The widget index to remove. +-- @tparam number index The widget index to remove. -- @treturn boolean index If the operation is successful. -- @method remove -- @interface layout @@ -87,7 +91,7 @@ local flex = {} --@DOC_wibox_layout_flex_spacing_widget_EXAMPLE@ -- -- @property spacing_widget --- @tparam widget spacing_widget +-- @tparam[opt=nil] widget|nil spacing_widget -- @propemits true false -- @interface layout @@ -98,7 +102,9 @@ local flex = {} --@DOC_wibox_layout_flex_spacing_EXAMPLE@ -- -- @property spacing --- @tparam number spacing Spacing between widgets. +-- @tparam[opt=0] number spacing Spacing between widgets. +-- @propertyunit pixel +-- @negativeallowed true -- @propemits true false -- @interface layout @@ -196,7 +202,9 @@ end --That is, maximum width for horizontal and maximum height for vertical. -- -- @property max_widget_size --- @tparam number max_widget_size +-- @tparam[opt=nil] number|nil max_widget_size +-- @propertytype nil No size limit. +-- @negativeallowed false -- @propemits true false function flex:set_max_widget_size(val) diff --git a/lib/wibox/layout/grid.lua b/lib/wibox/layout/grid.lua index 6ecc04167..9ef13ffd9 100644 --- a/lib/wibox/layout/grid.lua +++ b/lib/wibox/layout/grid.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- A grid layout. +--- Place multiple widgets in multiple rows and columns. -- -- Widgets spanning several columns or rows cannot be included using the -- declarative system. @@ -40,19 +40,16 @@ local dir_properties = { "spacing", "homogeneous", "expand" } --- Set the preferred orientation of the grid layout. -- --- Allowed values are "horizontal" and "vertical". --- When calling `get_next_empty`, empty cells are browsed differently: --- --- * for "horizontal", the grid can be extended horizontally. The current --- column is filled first; if no empty cell is found up to `forced_num_rows`, --- the next column is filled, creating it if it does not exist. --- --- * for "vertical", the grid can be extended vertically. The current row is --- filled first; if no empty cell is found up to `forced_num_cols`, the next --- row is filled, creating it if it does not exist. +-- When calling `get_next_empty`, empty cells are browsed differently. -- --@DOC_wibox_layout_grid_orientation_EXAMPLE@ --- @param[opt="vertical"] string Preferred orientation: "horizontal" or "vertical". +-- @tparam[opt="vertical"] string orientation Preferred orientation. +-- @propertyvalue "horizontal" The grid can be extended horizontally. The current +-- column is filled first; if no empty cell is found up to `forced_num_rows`, +-- the next column is filled, creating it if it does not exist. +-- @propertyvalue "vertical" The grid can be extended vertically. The current row is +-- filled first; if no empty cell is found up to `forced_num_cols`, the next +-- row is filled, creating it if it does not exist. -- @property orientation --- Allow to superpose widgets in the same cell. @@ -60,88 +57,115 @@ local dir_properties = { "spacing", "homogeneous", "expand" } -- widget and prevent from adding it. -- --@DOC_wibox_layout_grid_superpose_EXAMPLE@ --- @param[opt=false] boolean +-- @tparam[opt=false] boolean superpose -- @property superpose --- Force the number of rows of the layout. -- @property forced_num_rows --- @tparam[opt=nil] number|nil number Forced number of rows (`nil` for automatic). +-- @tparam[opt=nil] number|nil forced_num_rows +-- @propertytype nil Automatically determine the number of rows. +-- @propertyunit rows +-- @negativeallowed false +-- @see forced_num_cols --- Force the number of columns of the layout. -- @property forced_num_cols --- @tparam[opt=nil] number|nil number Forced number of columns (`nil` for automatic). +-- @tparam[opt=nil] number|nil forced_num_cols +-- @propertytype nil Automatically determine the number of columns.' +-- @propertyunit columns +-- @negativeallowed false +-- @see forced_num_rows --- Set the minimum size for the columns. -- --@DOC_wibox_layout_grid_min_size_EXAMPLE@ --- @param[opt=0] number Minimum size of the columns. +-- @tparam[opt=0] number min_cols_size Minimum size of the columns. -- @property min_cols_size +-- @propertyunit pixel +-- @negativeallowed false +-- @see min_rows_size --- Set the minimum size for the rows. --- @param[opt=0] number Minimum size of the rows. +-- @tparam[opt=0] number min_rows_size Minimum size of the rows. -- @property min_rows_size +-- @propertyunit pixel +-- @negativeallowed false +-- @see min_cols_size --- The spacing between columns. -- --- see `spacing` --- --- @param[opt=0] number The spacing +-- @tparam[opt=0] number horizontal_spacing -- @property horizontal_spacing +-- @propertyunit pixel +-- @negativeallowed false +-- @see spacing +-- @see vertical_spacing --- The spacing between rows. -- --- see `spacing` --- --- @param[opt=0] number The spacing +-- @tparam[opt=0] number vertical_spacing -- @property vertical_spacing +-- @propertyunit pixel +-- @negativeallowed false +-- @see spacing +-- @see horizontal_spacing --- The spacing between rows and columns. --- Set both `horizontal_spacing` and `vertical_spacing` to the same value. +-- -- Get the value `horizontal_spacing` or `vertical_spacing` defined by the -- preferred `orientation`. -- --@DOC_wibox_layout_grid_spacing_EXAMPLE@ --- @param[opt=0] number The spacing +-- @tparam[opt=0] number spacing -- @property spacing +-- @negativeallowed false +-- @see vertical_spacing +-- @see horizontal_spacing --- Controls if the columns are expanded to use all the available width. -- --- see `expand` --- --- @param[opt=false] boolean Expand the grid into the available space +-- @tparam[opt=false] boolean horizontal_expand Expand the grid into the available space -- @property horizontal_expand +-- @see expand +-- @see vertical_expand --- Controls if the rows are expanded to use all the available height. -- --- see `expand` --- --- @param[opt=false] boolean Expand the grid into the available space +-- @tparam[opt=false] boolean vertical_expand Expand the grid into the available space -- @property vertical_expand +-- @see expand +-- @see horizontal_expand --- Controls if the columns/rows are expanded to use all the available space. --- Set both `horizontal_expand` and `vertical_expand` to the same value. +-- -- Get the value `horizontal_expand` or `vertical_expand` defined by the -- preferred `orientation`. -- --@DOC_wibox_layout_grid_expand_EXAMPLE@ --- @param[opt=false] boolean Expand the grid into the available space +-- @tparam[opt=false] boolean expand Expand the grid into the available space -- @property expand +-- @see horizontal_expand +-- @see vertical_expand --- Controls if the columns all have the same width or if the width of each -- column depends on the content. -- -- see `homogeneous` -- --- @param[opt=true] boolean All the columns have the same width. +-- @tparam[opt=true] boolean horizontal_homogeneous All the columns have the same width. -- @property horizontal_homogeneous +-- @see vertical_homogeneous +-- @see homogeneous --- Controls if the rows all have the same height or if the height of each row -- depends on the content. -- -- see `homogeneous` -- --- @param[opt=true] boolean All the rows have the same height. +-- @tparam[opt=true] boolean vertical_homogeneous All the rows have the same height. -- @property vertical_homogeneous +-- @see homogeneous +-- @see horizontal_homogeneous --- Controls if the columns/rows all have the same size or if the size depends -- on the content. @@ -150,8 +174,11 @@ local dir_properties = { "spacing", "homogeneous", "expand" } -- by the preferred `orientation`. -- --@DOC_wibox_layout_grid_expand_EXAMPLE@ --- @param[opt=true] boolean All the columns/rows have the same size. +-- @tparam[opt=true] boolean homogeneous All the columns/rows have the same size. -- @property homogeneous +-- @see vertical_homogeneous +-- @see horizontal_homogeneous + --- Child widget position. Return of `get_widget_position`. -- @field row Top row index @@ -288,7 +315,9 @@ end -- The widgets are assumed to span one cell. -- -- @method add --- @param ... Widgets that should be added (must at least be one) +-- @tparam wibox.widget ... Widgets that should be added (must at least be one) +-- @interface layout +-- @noreturn function grid:add(...) local args = { n=select('#', ...), ... } assert(args.n > 0, "need at least one widget to add") @@ -305,7 +334,7 @@ end --@DOC_wibox_layout_grid_add_EXAMPLE@ -- -- @method add_widget_at --- @param child Widget that should be added +-- @tparam wibox.widget child Widget that should be added -- @tparam number row Row number for the top left corner of the widget -- @tparam number col Column number for the top left corner of the widget -- @tparam[opt=1] number row_span The number of rows the widget spans. @@ -400,7 +429,7 @@ end --- Return the coordinates of the widget. -- @method get_widget_position --- @param widget The widget +-- @tparam widget widget The widget -- @treturn table The `position` table of the coordinates in the grid, with -- fields `row`, `col`, `row_span` and `col_span`. function grid:get_widget_position(widget) @@ -441,8 +470,8 @@ end --- Replace old widget by new widget, spanning the same columns and rows. -- @method replace_widget --- @param old The widget to remove --- @param new The widget to add +-- @tparam widget old The widget to remove +-- @tparam widget new The widget to add -- @treturn boolean If the operation is successful (widget found) function grid:replace_widget(old, new) -- check if the new object is a widget @@ -861,8 +890,9 @@ end --- Reset the grid layout. -- Remove all widgets and reset row and column counts -- --- **Signal:** widget::reset -- @method reset +-- @emits reset +-- @noreturn function grid:reset() self._private.widgets = {} -- reset the number of columns and rows to the forced value or to 0 diff --git a/lib/wibox/layout/manual.lua b/lib/wibox/layout/manual.lua index eb2bdbdeb..e98458cd1 100644 --- a/lib/wibox/layout/manual.lua +++ b/lib/wibox/layout/manual.lua @@ -20,6 +20,8 @@ local manual_layout = {} -- -- @method add -- @tparam widget ... Widgets that should be added +-- @interface layout +-- @noreturn --- Remove a widget from the layout. -- @@ -166,6 +168,7 @@ end -- @tparam widget widget The widget. -- @tparam table|function point Either an `{x=x,y=y}` table or a function -- returning the new geometry. +-- @noreturn function manual_layout:add_at(widget, point) assert(not widget.point, "2 points are specified, only one is supported") @@ -189,6 +192,7 @@ end -- @method move -- @tparam number index The widget index. -- @tparam table|function point A new point value. +-- @noreturn -- @see add_at function manual_layout:move(index, point) assert(self._private.pos[index]) @@ -203,6 +207,7 @@ end -- @method move_widget -- @tparam widget widget The widget. -- @tparam table|function point A new point value. +-- @noreturn -- @see add_at function manual_layout:move_widget(widget, point) local idx, l = self:index(widget, false) diff --git a/lib/wibox/layout/ratio.lua b/lib/wibox/layout/ratio.lua index ba73b4b22..d960490f8 100644 --- a/lib/wibox/layout/ratio.lua +++ b/lib/wibox/layout/ratio.lua @@ -29,7 +29,7 @@ local ratio = {} --@DOC_wibox_layout_ratio_spacing_widget_EXAMPLE@ -- -- @property spacing_widget --- @tparam widget spacing_widget +-- @tparam[opt=nil] widget|nil spacing_widget -- @propemits true false -- @interface layout @@ -38,7 +38,8 @@ local ratio = {} --@DOC_wibox_layout_ratio_spacing_EXAMPLE@ -- -- @property spacing --- @tparam number spacing Spacing between widgets. +-- @tparam[opt=0] number spacing +-- @negativeallowed true -- @propemits true false -- @interface layout @@ -215,6 +216,7 @@ end -- @tparam number index The widget index to change -- @tparam number increment An floating point value between -1 and 1 where the -- end result is within 0 and 1 +-- @noreturn function ratio:inc_ratio(index, increment) if #self._private.widgets == 1 or (not index) or (not self._private.ratios[index]) or increment < -1 or increment > 1 then @@ -234,6 +236,7 @@ end -- @tparam widget widget The widget to adjust -- @tparam number increment An floating point value between -1 and 1 where the -- end result is within 0 and 1 +-- @noreturn function ratio:inc_widget_ratio(widget, increment) if not widget or not increment then return end @@ -247,6 +250,7 @@ end -- @method set_ratio -- @tparam number index The index of the widget to change -- @tparam number percent An floating point value between 0 and 1 +-- @noreturn function ratio:set_ratio(index, percent) if not percent or #self._private.widgets == 1 or not index or not self._private.widgets[index] or percent < 0 or percent > 1 then @@ -286,6 +290,7 @@ end -- @method set_widget_ratio -- @tparam widget widget The widget to adjust. -- @tparam number percent A floating point value between 0 and 1. +-- @noreturn function ratio:set_widget_ratio(widget, percent) local index = self:index(widget) @@ -302,6 +307,7 @@ end -- @tparam number before The sum of the ratio before the widget -- @tparam number itself The ratio for "widget" -- @tparam number after The sum of the ratio after the widget +-- @noreturn function ratio:adjust_ratio(index, before, itself, after) if not self._private.widgets[index] or not before or not itself or not after then return @@ -342,19 +348,15 @@ end -- @see wibox.layout.ratio.adjust_ratio -- @deprecated wibox.layout.ratio.ajust_ratio -- @tparam number index The index of the widget to change --- @tparam number index The index of the widget to change --- @tparam number before The sum of the ratio before the widget -- @tparam number before The sum of the ratio before the widget -- @tparam number itself The ratio for "widget" --- @tparam number itself The ratio for "widget" --- @tparam number after The sum of the ratio after the widget -- @tparam number after The sum of the ratio after the widget function ratio:ajust_ratio(...) require('gears.debug').deprecate( "Use `:adjust_ratio` rather than `:ajust_ratio`", { deprecated_in = 5 } ) - return self:adjust_ratio(...) + self:adjust_ratio(...) end --- Update all widgets to match a set of a ratio. @@ -364,6 +366,7 @@ end -- @tparam number before The sum of the ratio before the widget -- @tparam number itself The ratio for "widget" -- @tparam number after The sum of the ratio after the widget +-- @noreturn function ratio:adjust_widget_ratio(widget, before, itself, after) local index = self:index(widget) self:adjust_ratio(index, before, itself, after) @@ -375,11 +378,9 @@ end -- @deprecated wibox.layout.ratio.ajust_widget_ratio -- @tparam widget widget The widget to adjust -- @tparam number before The sum of the ratio before the widget --- @tparam number before The sum of the ratio before the widget --- @tparam number itself The ratio for "widget" -- @tparam number itself The ratio for "widget" -- @tparam number after The sum of the ratio after the widget --- @tparam number after The sum of the ratio after the widget +-- @noreturn function ratio:ajust_widget_ratio(...) require('gears.debug').deprecate( "Use `:adjust_widget_ratio` rather than `:ajust_widget_ratio`", @@ -392,6 +393,7 @@ end -- -- @method add -- @tparam widget ... Widgets that should be added (must at least be one) +-- @noreturn -- @emits widget::added All new widgets are passed in the parameters. -- @emitstparam widget::added widget self The layout. function ratio:add(...) @@ -439,6 +441,8 @@ end -- @method insert -- @tparam number index The position. -- @tparam widget widget The widget. +-- @treturn boolean `true` if the widget was inserted and `false` if the index +-- is invalid. -- @emits widget::inserted -- @emitstparam widget::inserted widget self The ratio layout. -- @emitstparam widget::inserted widget widget index The inserted widget. @@ -454,24 +458,23 @@ function ratio:insert(index, widget) self:emit_signal("widget::layout_changed") self:emit_signal("widget::inserted", widget, #self._private.widgets) + + return true end --- Set how the space of invisible or `0x0` sized widget is redistributed. -- --- Possible values: --- --- * "default": Honor the ratio and do not redistribute the space. --- * "justify": Distribute the space among remaining widgets. --- * "center": Squash remaining widgets and leave equal space on both side. --- * "inner_spacing": Add equal spacing between all widgets. --- * "spacing": Add equal spacing between all widgets and on the outside. --- * "left": Squash remaining widgets and leave empty space on the left. --- * "right": Squash remaining widgets and leave empty space on the right. --- --@DOC_wibox_layout_ratio_strategy_EXAMPLE@ -- -- @property inner_fill_strategy --- @tparam string inner_fill_strategy One of the value listed above. +-- @tparam[opt="default"] string inner_fill_strategy One of the value listed above. +-- @propertyvalue "default" Honor the ratio and do not redistribute the space. +-- @propertyvalue "justify" Distribute the space among remaining widgets. +-- @propertyvalue "center" Squash remaining widgets and leave equal space on both side. +-- @propertyvalue "inner_spacing" Add equal spacing between all widgets. +-- @propertyvalue "spacing" Add equal spacing between all widgets and on the outside. +-- @propertyvalue "left" Squash remaining widgets and leave empty space on the left. +-- @propertyvalue "right" Squash remaining widgets and leave empty space on the right. -- @propemits true false function ratio:get_inner_fill_strategy() diff --git a/lib/wibox/layout/stack.lua b/lib/wibox/layout/stack.lua index b570f449d..82d13c2a8 100644 --- a/lib/wibox/layout/stack.lua +++ b/lib/wibox/layout/stack.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- --- A stacked layout. +-- Place multiple widgets on top of each other. -- -- This layout display widgets on top of each other. It can be used to overlay -- a `wibox.widget.textbox` on top of a `awful.widget.progressbar` or manage @@ -26,12 +26,13 @@ local stack = {mt={}} --- Add some widgets to the given stack layout. -- -- @tparam widget ... Widgets that should be added (must at least be one) +-- @noreturn -- @method add -- @interface layout --- Remove a widget from the layout. -- --- @tparam index The widget index to remove +-- @tparam number index The widget index to remove -- @treturn boolean index If the operation is successful -- @method remove -- @interface layout @@ -62,7 +63,9 @@ local stack = {mt={}} -- --@DOC_wibox_layout_stack_spacing_EXAMPLE@ -- @property spacing --- @tparam number spacing Spacing between widgets. +-- @tparam[opt=0] number spacing Spacing between widgets. +-- @negativeallowed false +-- @propertyunit pixel -- @propemits true false -- @interface layout @@ -99,7 +102,7 @@ end --- If only the first stack widget is drawn. -- -- @property top_only --- @tparam boolean top_only +-- @tparam[opt=false] boolean top_only -- @propemits true false function stack:get_top_only() @@ -115,7 +118,8 @@ end --- Raise a widget at `index` to the top of the stack. -- -- @method raise --- @tparam number index the widget index to raise +-- @tparam number index The widget index to raise +-- @noreturn function stack:raise(index) if (not index) or (not self._private.widgets[index]) then return end @@ -132,6 +136,7 @@ end -- @tparam widget widget The widget to raise -- @tparam[opt=false] boolean recursive Also look deeper in the hierarchy to -- find the widget +-- @noreturn function stack:raise_widget(widget, recursive) local idx, layout = self:index(widget, recursive) @@ -155,17 +160,21 @@ end --@DOC_wibox_layout_stack_offset_EXAMPLE@ -- -- @property horizontal_offset --- @tparam number horizontal_offset +-- @tparam[opt=0] number horizontal_offset +-- @propertyunit pixel +-- @negativeallowed true -- @propemits true false --- @see vertial_offset +-- @see vertical_offset --- Add an vertical offset to each layers. -- -- Note that this reduces the overall size of each widgets by the sum of all -- layers offsets. -- --- @property vertial_offset --- @tparam number vertial_offset +-- @property vertical_offset +-- @tparam[opt=0] number vertical_offset +-- @propertyunit pixel +-- @negativeallowed true -- @propemits true false -- @see horizontal_offset diff --git a/lib/wibox/widget/background.lua b/lib/wibox/widget/background.lua index 0919c2799..7712d5540 100644 --- a/lib/wibox/widget/background.lua +++ b/lib/wibox/widget/background.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- --- This class has been moved to `wibox.container.background` +-- This class has been moved to `wibox.container.background`. -- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter diff --git a/lib/wibox/widget/base.lua b/lib/wibox/widget/base.lua index 26e035231..13a85d722 100644 --- a/lib/wibox/widget/base.lua +++ b/lib/wibox/widget/base.lua @@ -1,4 +1,6 @@ --------------------------------------------------------------------------- +-- Base class of every widgets, containers and layouts, +-- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter -- @classmod wibox.widget.base @@ -22,8 +24,10 @@ local base = {} --- Get or set the children elements. -- @property children --- @tparam table children The children. +-- @tparam[opt={}] table children +-- @tablerowtype A list of `wibox.widget`. -- @baseclass wibox.widget.base +-- @see all_children --- Get all direct and indirect children widgets. -- This will scan all containers recursively to find widgets @@ -31,34 +35,54 @@ local base = {} -- widgets hierarchy. A hierarchy loop is when a widget, or any of its -- children, contain (directly or indirectly) itself. -- @property all_children --- @tparam table children The children. +-- @tparam[opt={}] table all_children +-- @tablerowtype A list of `wibox.widget`. -- @baseclass wibox.widget.base +-- @see children --- Force a widget height. -- @property forced_height --- @tparam number|nil height The height (`nil` for automatic) +-- @tparam[opt=nil] number|nil forced_height +-- @propertyunit pixel +-- @propertytype nil Let the layout decide the height. Usually using the widget +-- native height. +-- @propertytype number Enforce a number of pixels. +-- @negativeallowed false -- @baseclass wibox.widget.base +-- @see forced_width --- Force a widget width. -- @property forced_width --- @tparam number|nil width The width (`nil` for automatic) +-- @tparam[opt=nil] number|nil forced_width +-- @propertyunit pixel +-- @propertytype nil Let the layout decide the width. Usually using the widget +-- native width. +-- @propertytype number Enforce a number of pixels. +-- @negativeallowed false -- @baseclass wibox.widget.base +-- @see forced_height --- The widget opacity (transparency). -- @property opacity --- @tparam[opt=1] number opacity The opacity (between 0 and 1) +-- @tparam[opt=1.0] number opacity +-- @rangestart 0.0 +-- @rangestop 1.0 +-- @propertyunit A gradient between transparent (`0.0`) and opaque (`1.0`). -- @baseclass wibox.widget.base +-- @see visible --- The widget visibility. -- @property visible --- @param boolean +-- @tparam[opt=true] boolean visible -- @baseclass wibox.widget.base +-- @see opacity --- The widget buttons. -- -- The table contains a list of `awful.button` objects. -- @property buttons --- @param table +-- @tparam[opt={}] table buttons +-- @tablerowtype A list of `awful.button`. -- @see awful.button -- @baseclass wibox.widget.base @@ -92,7 +116,7 @@ local base = {} -- @tparam number button The button number. -- @tparam table mods The modifiers (mod4, mod1 (alt), Control, Shift) -- @tparam table find_widgets_result The entry from the result of --- @{wibox.drawable:find_widgets} for the position that the mouse hit. +-- @{wibox:find_widgets} for the position that the mouse hit. -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing -- the widget. -- @tparam widget find_widgets_result.widget The widget being displayed. @@ -123,7 +147,7 @@ local base = {} -- @tparam number button The button number. -- @tparam table mods The modifiers (mod4, mod1 (alt), Control, Shift) -- @tparam table find_widgets_result The entry from the result of --- @{wibox.drawable:find_widgets} for the position that the mouse hit. +-- @{wibox:find_widgets} for the position that the mouse hit. -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing -- the widget. -- @tparam widget find_widgets_result.widget The widget being displayed. @@ -148,7 +172,7 @@ local base = {} -- @signal mouse::enter -- @tparam table self The current object instance itself. -- @tparam table find_widgets_result The entry from the result of --- @{wibox.drawable:find_widgets} for the position that the mouse hit. +-- @{wibox:find_widgets} for the position that the mouse hit. -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing -- the widget. -- @tparam widget find_widgets_result.widget The widget being displayed. @@ -173,7 +197,7 @@ local base = {} -- @signal mouse::leave -- @tparam table self The current object instance itself. -- @tparam table find_widgets_result The entry from the result of --- @{wibox.drawable:find_widgets} for the position that the mouse hit. +-- @{wibox:find_widgets} for the position that the mouse hit. -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing -- the widget. -- @tparam widget find_widgets_result.widget The widget being displayed. @@ -223,6 +247,7 @@ end --- Add a new `awful.button` to this widget. -- @tparam awful.button button The button to add. -- @method wibox.widget.base:add_button +-- @noreturn function base.widget:add_button(button) if not button then return end @@ -410,6 +435,7 @@ end -- @tparam string signal_name -- @param ... Other arguments -- @method wibox.widget.base:emit_signal_recursive +-- @noreturn function base.widget:emit_signal_recursive(signal_name, ...) -- This is a convenience wrapper, the real implementation is in the -- hierarchy. @@ -498,6 +524,15 @@ end -- This gives only tight bounds if no rotations by non-multiples of 90° are -- used. -- @staticfct wibox.widget.base.rect_to_device_geometry +-- @param cr The cairo context. +-- @tparam number x The `x` value. +-- @tparam number y The `y` value. +-- @tparam number width The `width` value. +-- @tparam number height The `height` value. +-- @treturn number The new `x` value. +-- @treturn number The new `y` value. +-- @treturn number The new `width` value. +-- @treturn number The new `height` value. function base.rect_to_device_geometry(cr, x, y, width, height) return matrix.transform_rectangle(cr.matrix, x, y, width, height) end @@ -583,6 +618,7 @@ end -- -- This is used internally and should not be called directly. -- @staticfct wibox.widget.base.handle_button +-- @noreturn function base.handle_button(event, widget, x, y, button, modifiers, geometry) x = x or y -- luacheck: no unused local function is_any(mod) @@ -995,6 +1031,7 @@ end -- -- This function raises an error if the widget is not valid. -- @staticfct wibox.widget.base.check_widget +-- @noreturn function base.check_widget(widget) assert(type(widget) == "table", "Type should be table, but is " .. tostring(type(widget))) assert(widget.is_widget, "Argument is not a widget!") diff --git a/lib/wibox/widget/calendar.lua b/lib/wibox/widget/calendar.lua index b7b21c86a..c4b541032 100644 --- a/lib/wibox/widget/calendar.lua +++ b/lib/wibox/widget/calendar.lua @@ -1,15 +1,15 @@ --------------------------------------------------------------------------- --- A calendar widget. +-- Display a monthly or yearly calendar. -- -- This module defines two widgets: a month calendar and a year calendar -- -- The two widgets have a `date` property, in the form of --- a table {day=[number|nil], month=[number|nil], year=[number]}. +-- a table `{day=[number|nil], month=[number|nil], year=[number]}`. -- --- The `year` widget displays the whole specified year, e.g. {year=2006}. +-- The `year` widget displays the whole specified year, e.g. `{year=2006}`. -- --- The `month` widget displays the calendar for the specified month, e.g. {month=12, year=2006}, --- highlighting the specified day if the day is provided in the date, e.g. {day=22, month=12, year=2006}. +-- The `month` widget displays the calendar for the specified month, e.g. `{month=12, year=2006}`, +-- highlighting the specified day if the day is provided in the date, e.g. `{day=22, month=12, year=2006}`. -- -- Cell and container styles can be overridden using the `fn_embed` callback function -- which is called before adding the widgets to the layouts. The `fn_embed` function @@ -68,46 +68,57 @@ local properties = { "date" , "font" , "spacing" , "week_numbers" --- The calendar date. -- --- A table representing the date {day=[number|nil], month=[number|nil], year=[number]}. --- --- E.g.. {day=21, month=2, year=2005}, {month=2, year=2005}, {year=2005} --- @tparam date table Date table. +-- E.g.. `{day=21, month=2, year=2005}`, `{month=2, year=2005}, {year=2005}` +-- @tparam[opt=nil] table|nil date -- @tparam number date.year Date year -- @tparam number|nil date.month Date month -- @tparam number|nil date.day Date day +-- @propertytype nil The current date. -- @property date --- The calendar font. -- -- Choose a monospace font for a better rendering. +-- --@DOC_wibox_widget_calendar_font_EXAMPLE@ --- @param[opt="Monospace 10"] string Font of the calendar +-- +-- @tparam[opt="Monospace 10"] font font Font of the calendar -- @property font +-- @usebeautiful beautiful.calendar_font --- The calendar spacing. -- -- The spacing between cells in the month. -- The spacing between months in a year calendar is twice this value. --- @param[opt=5] number Spacing of the grid +-- @tparam[opt=5] number spacing Spacing of the grid -- @property spacing +-- @negativeallowed false +-- @propertyunit pixel +-- @usebeautiful beautiful.calendar_spacing --- Display the calendar week numbers. -- --@DOC_wibox_widget_calendar_week_numbers_EXAMPLE@ --- @param[opt=false] boolean Display week numbers +-- +-- @tparam[opt=false] boolean week_numbers Display week numbers -- @property week_numbers +-- @usebeautiful beautiful.calendar_week_numbers --- Start the week on Sunday. -- --@DOC_wibox_widget_calendar_start_sunday_EXAMPLE@ --- @param[opt=false] boolean Start the week on Sunday +-- +-- @tparam[opt=false] boolean start_sunday Start the week on Sunday -- @property start_sunday +-- @usebeautiful beautiful.calendar_start_sunday --- Format the weekdays with three characters instead of two -- --@DOC_wibox_widget_calendar_long_weekdays_EXAMPLE@ --- @param[opt=false] boolean Use three characters for the weekdays instead of two +-- +-- @tparam[opt=false] boolean long_weekdays Use three characters for the weekdays instead of two -- @property long_weekdays +-- @usebeautiful beautiful.calendar_long_weekdays --- The widget encapsulating function. -- @@ -119,15 +130,22 @@ local properties = { "date" , "font" , "spacing" , "week_numbers" -- It is used to add a container to the grid layout and to the cells: -- --@DOC_wibox_widget_calendar_fn_embed_cell_EXAMPLE@ --- @param function Function to embed the widget depending on its flag +-- @tparam[opt=nil] function|nil fn_embed Function to embed the widget depending on its flag. +-- @functionparam widget widget +-- @functionparam string flag The type of widget. It is one of `"header"`, `"monthheader"`, +-- `"weeknumber"` `"weekday"`, `"focus"`, `"month"` or `"normal"`. +-- @functionparam table date A table with `day`, `month` and `year` keys. +-- @functionreturn widget A new widget to insert into the calendar. +-- @propertytype nil Use an uncustomized `wibox.widget.textbox`. -- @property fn_embed --- Allow cells to have flexible height -- --@DOC_wibox_widget_calendar_flex_height_EXAMPLE@ -- --- @param[opt=false] boolean Allow flex height. +-- @tparam[opt=false] boolean flex_height Allow flex height. -- @property flex_height +-- @usebeautiful beautiful.flex_height --- Make a textbox -- @tparam string text Text of the textbox @@ -257,7 +275,7 @@ end --- Create a grid layout for the year calendar -- @tparam table props Table of year calendar properties --- @param date Year to display (number or string) +-- @tparam number|string date Year to display. -- @treturn widget Grid layout local function create_year(props, date) -- Create a grid widget with the 12 months diff --git a/lib/wibox/widget/checkbox.lua b/lib/wibox/widget/checkbox.lua index f04cf6640..0577eb296 100644 --- a/lib/wibox/widget/checkbox.lua +++ b/lib/wibox/widget/checkbox.lua @@ -83,7 +83,9 @@ local checkbox = {} --- The outer (unchecked area) border width. -- -- @property border_width --- @tparam number border_width +-- @tparam number|nil border_width +-- @negativeallowed false +-- @propertyunit pixel -- @propbeautiful -- @propemits true false @@ -91,35 +93,37 @@ local checkbox = {} -- --@DOC_wibox_widget_checkbox_bg_EXAMPLE@ -- @property bg --- @tparam color bg +-- @tparam color|nil bg -- @propbeautiful -- @propemits true false --- The outer (unchecked area) border color. -- -- @property border_color --- @tparam color border_color +-- @tparam color|nil border_color -- @propbeautiful -- @propemits true false --- The checked part border color. -- -- @property check_border_color --- @tparam color check_border_color +-- @tparam color|nil check_border_color -- @propbeautiful -- @propemits true false --- The checked part border width. -- -- @property check_border_width --- @tparam number check_border_width +-- @tparam number|nil check_border_width -- @propbeautiful +-- @negativeallowed false +-- @propertyunit pixel -- @propemits true false --- The checked part filling color. -- -- @property check_color --- @tparam color check_color +-- @tparam color|nil check_color -- @propbeautiful -- @propemits true false @@ -127,7 +131,7 @@ local checkbox = {} -- --@DOC_wibox_widget_checkbox_shape_EXAMPLE@ -- @property shape --- @tparam gears.shape shape +-- @tparam shape|nil shape -- @propbeautiful -- @propemits true false -- @see gears.shape @@ -137,7 +141,7 @@ local checkbox = {} -- If none is set, then the `shape` property will be used. --@DOC_wibox_widget_checkbox_check_shape_EXAMPLE@ -- @property check_shape --- @tparam gears.shape shape +-- @tparam shape|nil check_shape -- @propbeautiful -- @propemits true false -- @see gears.shape @@ -145,11 +149,15 @@ local checkbox = {} --- The padding between the outline and the progressbar. -- -- @property paddings --- @tparam[opt=0] table|number paddings A number or a table +-- @tparam[opt=0] table|number|nil paddings A number or a table -- @tparam[opt=0] number paddings.top -- @tparam[opt=0] number paddings.bottom -- @tparam[opt=0] number paddings.left -- @tparam[opt=0] number paddings.right +-- @propertyunit pixel +-- @negativeallowed true +-- @propertytype number A single number for all sides. +-- @propertytype table A different value for each sides: -- @propbeautiful -- @propemits false false @@ -159,7 +167,7 @@ local checkbox = {} -- filling color. Note that `check_color` and `border_color` have priority -- over this property. -- @property color --- @tparam color color +-- @tparam color|nil color -- @propbeautiful -- @propemits true false @@ -254,7 +262,7 @@ end --- If the checkbox is checked. -- @property checked --- @param boolean +-- @tparam[opt=false] boolean checked for _, prop in ipairs {"border_width", "bg", "border_color", "check_border_color", "check_border_width", "check_color", "shape", "check_shape", "paddings", diff --git a/lib/wibox/widget/graph.lua b/lib/wibox/widget/graph.lua index 51b5d7545..96fa3d2e5 100644 --- a/lib/wibox/widget/graph.lua +++ b/lib/wibox/widget/graph.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- A graph widget. +--- Display multiple values as a stream of bars. -- -- The graph goes from left to right. To change this to right to left, use -- a `wibox.container.mirror` widget. This can also be used to have data @@ -36,7 +36,9 @@ local graph = { mt = {} } --@DOC_wibox_widget_graph_border_width_EXAMPLE@ -- -- @property border_width --- @tparam number border_width +-- @tparam[opt=0] number border_width +-- @propertyunit pixel +-- @negativeallowed false -- @propemits true false -- @see border_color @@ -45,7 +47,7 @@ local graph = { mt = {} } --@DOC_wibox_widget_graph_border_color_EXAMPLE@ -- -- @property border_color --- @tparam gears.color border_color The border color to set. +-- @tparam color|nil border_color The border color to set. -- @propbeautiful -- @propemits true false -- @see gears.color @@ -67,7 +69,7 @@ local graph = { mt = {} } --@DOC_wibox_widget_graph_background_color_EXAMPLE@ -- -- @property background_color --- @tparam gears.color background_color The graph background color. +-- @tparam color background_color The graph background color. -- @usebeautiful beautiful.graph_bg -- @propemits true false -- @see gears.color @@ -84,7 +86,8 @@ local graph = { mt = {} } -- @DOC_wibox_widget_graph_stacked_group_disable_EXAMPLE@ -- -- @property group_colors --- @tparam table colors A table with colors for data groups. +-- @tparam[opt=self.color] table group_colors A table with colors for data groups. +-- @tablerowtype List of color values. -- @see gears.color --- The maximum value the graph should handle. @@ -97,7 +100,8 @@ local graph = { mt = {} } -- @DOC_wibox_widget_graph_max_value_EXAMPLE@ -- -- @property max_value --- @tparam number max_value +-- @tparam[opt=1] number max_value +-- @negativeallowed true -- @propemits true false --- The minimum value the graph should handle. @@ -110,10 +114,11 @@ local graph = { mt = {} } -- @DOC_wibox_widget_graph_min_value_EXAMPLE@ -- -- @property min_value --- @tparam number min_value +-- @tparam[opt=0] number min_value +-- @negativeallowed true -- @propemits true false ---- Set the graph to automatically scale its values. Default is false. +--- Set the graph to automatically scale its values. -- -- If this property is set to true, the graph calculates -- effective `min_value` and `max_value` based on the displayed data, @@ -126,7 +131,7 @@ local graph = { mt = {} } -- @DOC_wibox_widget_graph_scale1_EXAMPLE@ -- -- @property scale --- @tparam boolean scale +-- @tparam[opt=false] boolean scale -- @propemits true false --- Clamp graph bars to keep them inside the widget for out-of-range values. @@ -144,15 +149,16 @@ local graph = { mt = {} } -- @DOC_wibox_widget_graph_clamp_bars_EXAMPLE@ -- -- @property clamp_bars --- @tparam boolean clamp_bars +-- @tparam[opt=false] boolean clamp_bars -- @propemits true false ---- The value corresponding to the starting point of graph bars. Default is 0. +--- The value corresponding to the starting point of graph bars. -- -- @DOC_wibox_widget_graph_baseline_value_EXAMPLE@ -- -- @property baseline_value --- @tparam number baseline_value +-- @tparam[opt=0] number baseline_value +-- @negativeallowed true -- @propemits true false --- Set the width or the individual steps. @@ -161,6 +167,8 @@ local graph = { mt = {} } -- -- @property step_width -- @tparam[opt=1] number step_width +-- @propertyunit pixel +-- @negativeallowed false -- @propemits true false --- Set the spacing between the steps. @@ -169,6 +177,8 @@ local graph = { mt = {} } -- -- @property step_spacing -- @tparam[opt=0] number step_spacing +-- @propertyunit pixel +-- @negativeallowed false -- @propemits true false --- The step shape. @@ -176,7 +186,7 @@ local graph = { mt = {} } --@DOC_wibox_widget_graph_step_shape_EXAMPLE@ -- -- @property step_shape --- @tparam[opt=rectangle] gears.shape|function step_shape +-- @tparam[opt=gears.rect.rectangle] shape step_shape -- @propemits true false -- @see gears.shape @@ -190,7 +200,7 @@ local graph = { mt = {} } -- @DOC_wibox_widget_graph_normal_vs_stacked_EXAMPLE@ -- -- @property stack --- @tparam boolean stack +-- @tparam[opt=false] boolean stack -- @propemits true false --- Display NaN indication. Default is true. @@ -205,7 +215,7 @@ local graph = { mt = {} } -- @DOC_wibox_widget_graph_nan_color_EXAMPLE@ -- -- @property nan_indication --- @tparam boolean nan_indication +-- @tparam[opt=true] boolean nan_indication -- @propemits true false --- The color of NaN indication. @@ -216,7 +226,7 @@ local graph = { mt = {} } -- @DOC_wibox_widget_graph_stacked_nan_EXAMPLE@ -- -- @property nan_color --- @tparam gears.color nan_color The color of NaN indication. +-- @tparam[opt="#ffff00"] color nan_color The color of NaN indication. -- @propemits true false -- @see gears.color @@ -377,7 +387,7 @@ end -- -- @method pick_data_group_color -- @tparam number group_idx The index of the data group. --- @treturn gears.color The color to paint the data group's values with. +-- @treturn color The color to paint the data group's values with. function graph:pick_data_group_color(group_idx) -- Use an individual group color, if there's one local data_group_colors = self._private.group_colors @@ -672,6 +682,7 @@ end -- -- @method compute_drawn_values_num -- @tparam number usable_width +-- @treturn number The number of values. function graph:compute_drawn_values_num(usable_width) if usable_width <= 0 then return 0 @@ -718,6 +729,7 @@ end -- @method add_value -- @tparam[opt=NaN] number value The value to be added to a graph's data group. -- @tparam[opt=1] integer group The index of the data group. +-- @noreturn Note that it actually returns something, but that's better undocumented. function graph:add_value(value, group) value = value or 0/0 -- default to NaN group = group or 1 @@ -762,6 +774,7 @@ end -- Removes all values from all data groups. -- -- @method clear +-- @noreturn Note that it actually returns something, but that's better undocumented. function graph:clear() self._private.values = {} self:emit_signal("widget::redraw_needed") @@ -784,6 +797,8 @@ end -- @property capacity -- @tparam[opt=nil] integer|nil capacity The maximum number of values to keep -- per data group (`nil` for automatic guess). +-- @negativeallowed false +-- @propertyunit Number of value. -- @propemits true false function graph:set_capacity(capacity) -- Property override to avoid emitting the "redraw_needed" signal, diff --git a/lib/wibox/widget/imagebox.lua b/lib/wibox/widget/imagebox.lua index ace4eed74..79b6f710b 100644 --- a/lib/wibox/widget/imagebox.lua +++ b/lib/wibox/widget/imagebox.lua @@ -296,15 +296,8 @@ end --- The image rendered by the `imagebox`. -- --- It can can be any of the following: --- --- * 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. +-- @tparam[opt=nil] image|nil image -- @propemits false false --- Set the `imagebox` image. @@ -370,7 +363,7 @@ end -- @DOC_wibox_widget_imagebox_clip_shape_EXAMPLE@ -- -- @property clip_shape --- @tparam function|gears.shape clip_shape A `gears.shape` compatible shape function. +-- @tparam[opt=gears.shape.rectangle] shape clip_shape A `gears.shape` compatible shape function. -- @propemits true false -- @see gears.shape @@ -402,7 +395,7 @@ end -- @DOC_wibox_widget_imagebox_resize_EXAMPLE@ -- @property resize -- @propemits true false --- @tparam boolean resize +-- @tparam[opt=true] boolean resize --- Allow the image to be upscaled (made bigger). -- @@ -412,7 +405,7 @@ end -- -- @DOC_wibox_widget_imagebox_upscale_EXAMPLE@ -- @property upscale --- @tparam boolean upscale +-- @tparam[opt=self.resize] boolean upscale -- @see downscale -- @see resize @@ -424,7 +417,7 @@ end -- -- @DOC_wibox_widget_imagebox_downscale_EXAMPLE@ -- @property downscale --- @tparam boolean downscale +-- @tparam[opt=self.resize] boolean downscale -- @see upscale -- @see resize @@ -439,7 +432,7 @@ end --@DOC_wibox_widget_imagebox_stylesheet_EXAMPLE@ -- -- @property stylesheet --- @tparam string stylesheet +-- @tparam[opt=""] string stylesheet -- @propemits true false --- Set the SVG DPI (dot per inch). @@ -455,7 +448,8 @@ end --@DOC_wibox_widget_imagebox_dpi_EXAMPLE@ -- -- @property dpi --- @tparam number|table dpi +-- @tparam[opt=96] number|table dpi +-- @negativeallowed false -- @propemits true false -- @see auto_dpi @@ -516,38 +510,30 @@ end --- Set the horizontal fit policy. -- --- Valid values are: --- --- * `"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 +-- @propertyvalue "auto" Honor the `resize` variable and preserve the aspect ratio. +-- @propertyvalue "none" Do not resize at all. +-- @propertyvalue "fit" Resize to the widget width. -- @propemits true false -- @see vertical_fit_policy -- @see resize --- Set the vertical fit policy. -- --- 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 vertical_fit_policy +-- @propertyvalue "auto" Honor the `resize` variable and preserve the aspect ratio. +-- @propertyvalue "none" Do not resize at all. +-- @propertyvalue "fit" Resize to the widget height. -- @propemits true false -- @see horizontal_fit_policy -- @see resize @@ -555,32 +541,26 @@ end --- The vertical alignment. -- --- Possible values are: --- --- * `"top"` --- * `"center"` (default) --- * `"bottom"` --- -- @DOC_wibox_widget_imagebox_valign_EXAMPLE@ -- -- @property valign -- @tparam[opt="center"] string valign +-- @propertyvalue "top" +-- @propertyvalue "center" +-- @propertyvalue "bottom" -- @propemits true false -- @see wibox.container.place -- @see halign --- The horizontal alignment. -- --- Possible values are: --- --- * `"left"` --- * `"center"` (default) --- * `"right"` --- -- @DOC_wibox_widget_imagebox_halign_EXAMPLE@ -- -- @property halign -- @tparam[opt="center"] string halign +-- @propertyvalue "left" +-- @propertyvalue "center" +-- @propertyvalue "right" -- @propemits true false -- @see wibox.container.place -- @see valign @@ -597,7 +577,8 @@ end -- @DOC_wibox_widget_imagebox_max_scaling_factor_EXAMPLE@ -- -- @property max_scaling_factor --- @tparam number max_scaling_factor +-- @tparam[opt=0] number max_scaling_factor Use `0` for "no limit". +-- @negativeallowed false -- @propemits true false -- @see valign -- @see halign @@ -629,8 +610,12 @@ end -- @DOC_wibox_widget_imagebox_scaling_quality_EXAMPLE@ -- -- @property scaling_quality --- @tparam string scaling_quality Either `"fast"`, `"good"`, `"best"`, --- `"nearest"` or `"bilinear"`. +-- @tparam[opt="good"] string scaling_quality +-- @propertyvalue "fast" A high-performance filter. +-- @propertyvalue "good" A reasonable-performance filter. +-- @propertyvalue "best" The highest-quality available. +-- @propertyvalue "nearest" Nearest-neighbor filtering (blocky). +-- @propertyvalue "bilinear" Linear interpolation in two dimensions. -- @propemits true false -- @see resize -- @see horizontal_fit_policy diff --git a/lib/wibox/widget/init.lua b/lib/wibox/widget/init.lua index 683e8bc7b..b96caac7f 100644 --- a/lib/wibox/widget/init.lua +++ b/lib/wibox/widget/init.lua @@ -1,4 +1,6 @@ --------------------------------------------------------------------------- +--- Utility function for working with widgets. +-- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter -- @module wibox.widget @@ -6,6 +8,8 @@ local cairo = require("lgi").cairo local hierarchy = require("wibox.hierarchy") +local gcolor = require("gears.color") +local beautiful = nil local widget = { base = require("wibox.widget.base"); @@ -37,6 +41,7 @@ setmetatable(widget, { -- @tparam number width The width of the widget -- @tparam number height The height of the widget -- @tparam[opt={dpi=96}] table context The context information to give to the widget. +-- @noreturn -- @staticfct wibox.widget.draw_to_cairo_context function widget.draw_to_cairo_context(wdg, cr, width, height, context) local function no_op() end @@ -51,10 +56,15 @@ end -- @tparam number width The surface width -- @tparam number height The surface height -- @tparam[opt={dpi=96}] table context The context information to give to the widget. +-- @noreturn -- @staticfct wibox.widget.draw_to_svg_file function widget.draw_to_svg_file(wdg, path, width, height, context) local img = cairo.SvgSurface.create(path, width, height) local cr = cairo.Context(img) + + beautiful = beautiful or require("beautiful") + cr:set_source(gcolor(beautiful.fg_normal)) + widget.draw_to_cairo_context(wdg, cr, width, height, context) img:finish() end @@ -70,6 +80,10 @@ end function widget.draw_to_image_surface(wdg, width, height, format, context) local img = cairo.ImageSurface(format or cairo.Format.ARGB32, width, height) local cr = cairo.Context(img) + + beautiful = beautiful or require("beautiful") + cr:set_source(gcolor(beautiful.fg_normal)) + widget.draw_to_cairo_context(wdg, cr, width, height, context) return img end diff --git a/lib/wibox/widget/piechart.lua b/lib/wibox/widget/piechart.lua index 608fdcf6b..79140ff67 100644 --- a/lib/wibox/widget/piechart.lua +++ b/lib/wibox/widget/piechart.lua @@ -140,15 +140,22 @@ end --- The pie chart data list. -- -- @property data_list --- @tparam table data_list Sorted table where each entry has a label as its +-- @tparam[opt={}] table data_list +-- @tablerowtype Sorted list where each entry has a label as its -- first value and a number as its second value. +-- @tablerowkey string 1 The label. +-- @tablerowkey number 2 The value. -- @propemits false false --- The pie chart data. -- -- @property data --- @tparam table data Labels as keys and number as value. +-- @tparam[opt={}] table data +-- @tablerowtype Key/value pair. +-- @tablerowkey string key The label. +-- @tablerowkey number value The value. -- @propemits false false +-- @see data_list --- The border color. -- @@ -156,7 +163,7 @@ end -- --@DOC_wibox_widget_piechart_border_color_EXAMPLE@ -- @property border_color --- @tparam color border_color +-- @tparam color|nil border_color -- @propemits true false -- @propbeautiful -- @see gears.color @@ -165,7 +172,9 @@ end -- --@DOC_wibox_widget_piechart_border_width_EXAMPLE@ -- @property border_width --- @tparam[opt=1] number border_width +-- @tparam[opt=1] number|nil border_width +-- @propertyunit pixel +-- @negativeallowed false -- @propemits true false -- @propbeautiful @@ -175,7 +184,8 @@ end -- required are set, colors will be re-used in order. -- -- @property colors --- @tparam table colors A table of colors, one for each elements. +-- @tparam table|nil colors A table of colors, one for each elements. +-- @propertytype table List of colors (numerical keys). -- @propemits true false -- @propbeautiful -- @see gears.color @@ -191,7 +201,8 @@ end -- --@DOC_wibox_widget_piechart_label_EXAMPLE@ -- @property display_labels --- @param[opt=true] boolean +-- @tparam[opt=true] boolean display_labels +-- @propemits true false --- The pie elements border width. -- diff --git a/lib/wibox/widget/progressbar.lua b/lib/wibox/widget/progressbar.lua index 9e1979849..c34ce3801 100644 --- a/lib/wibox/widget/progressbar.lua +++ b/lib/wibox/widget/progressbar.lua @@ -54,7 +54,7 @@ local progressbar = { mt = {} } -- @DOC_wibox_widget_progressbar_border_color_EXAMPLE@ -- -- @property border_color --- @tparam gears.color color The border color to set. +-- @tparam color|nil border_color The border color to set. -- @propemits true false -- @propbeautiful -- @see gears.color @@ -64,7 +64,12 @@ local progressbar = { mt = {} } -- @DOC_wibox_widget_progressbar_border_width_EXAMPLE@ -- -- @property border_width --- @tparam number border_width +-- @tparam number|nil border_width +-- @propertytype nil Defaults to `beautiful.progressbar_border_width`. +-- @propertytype number The number of pixels +-- @propertyunit pixel +-- @negativeallowed false +-- @propbeautiful -- @propemits true false -- @propbeautiful @@ -75,7 +80,7 @@ local progressbar = { mt = {} } -- @DOC_wibox_widget_progressbar_bar_border_color_EXAMPLE@ -- -- @property bar_border_color --- @tparam gears.color color The border color to set. +-- @tparam color|nil bar_border_color The border color to set. -- @propemits true false -- @propbeautiful -- @see gears.color @@ -85,8 +90,12 @@ local progressbar = { mt = {} } -- @DOC_wibox_widget_progressbar_bar_border_width_EXAMPLE@ -- -- @property bar_border_width --- @tparam number bar_border_width +-- @tparam number|nil bar_border_width +-- @propertyunit pixel +-- @negativeallowed false -- @propbeautiful +-- @usebeautiful beautiful.progressbar_border_width Fallback when +-- `beautiful.progressbar_bar_border_width` isn't set. -- @propemits true false --- The progressbar foreground color. @@ -94,7 +103,8 @@ local progressbar = { mt = {} } -- @DOC_wibox_widget_progressbar_color_EXAMPLE@ -- -- @property color --- @tparam gears.color color The progressbar color. +-- @tparam color|nil color The progressbar color. +-- @propertytype nil Fallback to the current value of `beautiful.progressbar_fg`. -- @propemits true false -- @usebeautiful beautiful.progressbar_fg -- @see gears.color @@ -104,7 +114,8 @@ local progressbar = { mt = {} } -- @DOC_wibox_widget_progressbar_background_color_EXAMPLE@ -- -- @property background_color --- @tparam gears.color color The progressbar background color. +-- @tparam color|nil background_color The progressbar background color. +-- @propertytype nil Fallback to the current value of `beautiful.progressbar_bg`. -- @propemits true false -- @usebeautiful beautiful.progressbar_bg -- @see gears.color @@ -114,7 +125,7 @@ local progressbar = { mt = {} } --@DOC_wibox_widget_progressbar_bar_shape_EXAMPLE@ -- -- @property bar_shape --- @tparam[opt=gears.shape.rectangle] gears.shape shape +-- @tparam shape|nil bar_shape -- @propemits true false -- @propbeautiful -- @see gears.shape @@ -124,7 +135,7 @@ local progressbar = { mt = {} } --@DOC_wibox_widget_progressbar_shape_EXAMPLE@ -- -- @property shape --- @tparam[opt=gears.shape.rectangle] gears.shape shape +-- @tparam shape|nil shape -- @propemits true false -- @propbeautiful -- @see gears.shape @@ -147,11 +158,15 @@ local progressbar = { mt = {} } --- The progressbar to draw ticks. -- +-- The add a little bar in between the values. +-- -- @DOC_wibox_widget_progressbar_ticks_EXAMPLE@ -- -- @property ticks -- @tparam[opt=false] boolean ticks -- @propemits true false +-- @see ticks_gap +-- @see ticks_size --- The progressbar ticks gap. -- @@ -159,7 +174,11 @@ local progressbar = { mt = {} } -- -- @property ticks_gap -- @tparam[opt=1] number ticks_gap +-- @propertyunit pixel +-- @negativeallowed false -- @propemits true false +-- @see ticks_size +-- @see ticks --- The progressbar ticks size. -- @@ -171,7 +190,11 @@ local progressbar = { mt = {} } -- -- @property ticks_size -- @tparam[opt=4] number ticks_size +-- @propertyunit pixel +-- @negativeallowed false -- @propemits true false +-- @see ticks_gap +-- @see ticks --- The maximum value the progressbar should handle. -- @@ -182,6 +205,7 @@ local progressbar = { mt = {} } -- -- @property max_value -- @tparam[opt=1] number max_value +-- @negativeallowed true -- @propemits true false -- @see value @@ -198,7 +222,7 @@ local progressbar = { mt = {} } --- The progressbar shape. -- -- @beautiful beautiful.progressbar_shape --- @tparam gears.shape shape +-- @tparam[opt=gears.shape.rectangle] shape shape -- @see gears.shape --- The progressbar border color. @@ -214,7 +238,7 @@ local progressbar = { mt = {} } --- The progressbar inner shape. -- -- @beautiful beautiful.progressbar_bar_shape --- @tparam gears.shape shape +-- @tparam[opt=gears.shape.rectangle] gears.shape shape -- @see gears.shape --- The progressbar bar border width. @@ -243,11 +267,15 @@ local progressbar = { mt = {} } -- @DOC_wibox_widget_progressbar_margins1_EXAMPLE@ -- -- @property margins --- @tparam[opt=0] (table|number|nil) margins A table for each side or a number +-- @tparam[opt=0] table|number|nil margins A table for each side or a number -- @tparam[opt=0] number margins.top -- @tparam[opt=0] number margins.bottom -- @tparam[opt=0] number margins.left -- @tparam[opt=0] number margins.right +-- @propertyunit pixel +-- @negativeallowed true +-- @propertytype number Use the same value for each side. +-- @propertytype table Use a different value for each side: -- @propemits false false -- @propbeautiful -- @see clip @@ -268,11 +296,15 @@ local progressbar = { mt = {} } -- @DOC_wibox_widget_progressbar_paddings1_EXAMPLE@ -- -- @property paddings --- @tparam[opt=0] (table|number|nil) padding A table for each side or a number +-- @tparam[opt=0] table|number|nil paddings A table for each side or a number -- @tparam[opt=0] number paddings.top -- @tparam[opt=0] number paddings.bottom -- @tparam[opt=0] number paddings.left -- @tparam[opt=0] number paddings.right +-- @propertyunit pixel +-- @negativeallowed true +-- @propertytype number Use the same value for each side. +-- @propertytype table Use a different value for each side: -- @propemits false false -- @propbeautiful -- @see clip @@ -519,7 +551,8 @@ end -- @DOC_wibox_widget_progressbar_value_EXAMPLE@ -- -- @property value --- @tparam number value The progress bar value. +-- @tparam[opt=0] number value +-- @negativeallowed true -- @propemits true false -- @see max_value @@ -591,8 +624,24 @@ end -- -- @tparam table args Standard widget() arguments. You should add width and -- height constructor parameters to set progressbar geometry. --- @tparam number args.width The width. --- @tparam number args.height The height. +-- @tparam[opt] number args.width The width. +-- @tparam[opt] number args.height The height. +-- @tparam[opt] gears.color args.border_color The progressbar border color. +-- @tparam[opt] number args.border_width The progressbar border width. +-- @tparam[opt] gears.color args.bar_border_color The progressbar inner border color. +-- @tparam[opt] number args.bar_border_width The progressbar inner border width. +-- @tparam[opt] gears.color args.color The progressbar foreground color. +-- @tparam[opt] gears.color args.background_color The progressbar background color. +-- @tparam[opt] gears.shape args.bar_shape The progressbar inner shape. +-- @tparam[opt] gears.shape args.shape The progressbar shape. +-- @tparam[opt] boolean args.clip Force the inner part (the bar) to fit in the background shape. +-- @tparam[opt] boolean args.ticks The progressbar to draw ticks. +-- @tparam[opt] number args.ticks_gap The progressbar ticks gap. +-- @tparam[opt] number args.ticks_size The progressbar ticks size. +-- @tparam[opt] number args.max_value The maximum value the progressbar should handle. +-- @tparam[opt] table|number args.margins The progressbar margins. +-- @tparam[opt] table|number args.paddings The progressbar padding. +-- @tparam[opt] number args.value Set the progressbar value. -- @treturn wibox.widget.progressbar A progressbar widget. -- @constructorfct wibox.widget.progressbar function progressbar.new(args) diff --git a/lib/wibox/widget/separator.lua b/lib/wibox/widget/separator.lua index 2ae0daa42..3d13cb881 100644 --- a/lib/wibox/widget/separator.lua +++ b/lib/wibox/widget/separator.lua @@ -31,19 +31,16 @@ local separator = {} --- The separator's orientation. -- --- Valid values are: --- --- * *vertical*: From top to bottom --- * *horizontal*: From left to right --- * *auto*: Decide depending on the widget geometry (default) --- -- The default value is selected automatically. If the widget is taller than -- large, it will use vertical and vice versa. -- --@DOC_wibox_widget_separator_orientation_EXAMPLE@ -- -- @property orientation --- @tparam string orientation +-- @tparam[opt="auto"] string orientation +-- @propertyvalue "vertical" From top to bottom. +-- @propertyvalue "horizontal" From left to right. +-- @propertyvalue "auto" Decide depending on the widget geometry. -- @propemits true false --- The separator's thickness. @@ -51,7 +48,9 @@ local separator = {} -- This is used by the default line separator, but ignored when a shape is used. -- -- @property thickness --- @tparam number thickness +-- @tparam number|nil thickness +-- @propertyunit pixel +-- @negativeallowed false -- @propbeautiful -- @propemits true false @@ -60,7 +59,7 @@ local separator = {} --@DOC_wibox_widget_separator_shape_EXAMPLE@ -- -- @property shape --- @tparam function shape A valid shape function +-- @tparam shape|nil shape A valid shape function -- @propbeautiful -- @propemits true false -- @see gears.shape @@ -68,13 +67,16 @@ local separator = {} --- The relative percentage covered by the bar. -- -- @property span_ratio --- @tparam[opt=1] number A number between 0 and 1. +-- @tparam[opt=1] number|nil span_ratio +-- @rangestart 0.0 +-- @rangestop 1.0 +-- @propertyunit A gradient between "small" (0.0) and "full width/height" (1.0). -- @propbeautiful -- @propemits true false --- The separator's color. -- @property color --- @tparam color color +-- @tparam color|nil color -- @propbeautiful -- @propemits true false -- @see gears.color @@ -84,20 +86,22 @@ local separator = {} --@DOC_wibox_widget_separator_border_color_EXAMPLE@ -- -- @property border_color --- @tparam color border_color +-- @tparam color|nil border_color -- @propbeautiful -- @propemits true false -- @see gears.color --- The separator's border width. -- @property border_width --- @tparam number border_width +-- @tparam number|nil border_width +-- @propertyunit pixel +-- @negativeallowed false -- @propbeautiful -- @propemits true false --- The separator thickness. -- @beautiful beautiful.separator_thickness --- @param number +-- @tparam[opt=1] number separator_thickness -- @see thickness --- The separator border color. @@ -107,22 +111,22 @@ local separator = {} --- The separator border width. -- @beautiful beautiful.separator_border_width --- @param number +-- @tparam[opt=0] number separator_border_width -- @see border_width --- The relative percentage covered by the bar. -- @beautiful beautiful.separator_span_ratio --- @tparam[opt=1] number A number between 0 and 1. +-- @tparam[opt=1] number separator_span_ratio A number between 0 and 1. --- The separator's color. -- @beautiful beautiful.separator_color --- @param string +-- @param color -- @see gears.color --- The separator's shape. -- -- @beautiful beautiful.separator_shape --- @tparam function shape A valid shape function +-- @tparam[opt=gears.shape.rectangle] shape shape A valid shape function -- @see gears.shape local function draw_shape(self, _, cr, width, height, shape) @@ -203,6 +207,13 @@ end --- Create a new separator. -- @constructorfct wibox.widget.separator -- @tparam table args The arguments (all properties are available). +-- @tparam[opt] string args.orientation The separator's orientation. +-- @tparam[opt] number args.thickness The separator's thickness. +-- @tparam[opt] function args.shape The separator's shape. +-- @tparam[opt] number args.span_ratio The relative percentage covered by the bar. +-- @tparam[opt] color args.color The separator's color. +-- @tparam[opt] color args.border_color The separator's border color. +-- @tparam[opt] number args.border_width The separator's border width. local function new(args) local ret = base.make_widget(nil, nil, { diff --git a/lib/wibox/widget/slider.lua b/lib/wibox/widget/slider.lua index b72577519..e397f45c7 100644 --- a/lib/wibox/widget/slider.lua +++ b/lib/wibox/widget/slider.lua @@ -30,7 +30,7 @@ local slider = {mt={}} --@DOC_wibox_widget_slider_handle_shape_EXAMPLE@ -- -- @property handle_shape --- @tparam[opt=gears shape rectangle] gears.shape shape +-- @tparam shape|nil handle_shape -- @propemits true false -- @propbeautiful -- @see gears.shape @@ -41,7 +41,7 @@ local slider = {mt={}} -- -- @property handle_color -- @propbeautiful --- @tparam color handle_color +-- @tparam color|nil handle_color -- @propemits true false --- The slider handle margins. @@ -49,11 +49,15 @@ local slider = {mt={}} --@DOC_wibox_widget_slider_handle_margins_EXAMPLE@ -- -- @property handle_margins --- @tparam[opt={}] table margins --- @tparam[opt=0] number margins.left --- @tparam[opt=0] number margins.right --- @tparam[opt=0] number margins.top --- @tparam[opt=0] number margins.bottom +-- @tparam[opt={}] table|number|nil handle_margins +-- @tparam[opt=0] number handle_margins.left +-- @tparam[opt=0] number handle_margins.right +-- @tparam[opt=0] number handle_margins.top +-- @tparam[opt=0] number handle_margins.bottom +-- @propertyunit pixel +-- @propertytype number A single value used for all sides. +-- @propertytype table A different value for each side. The side names are: +-- @negativeallowed true -- @propemits true false -- @propbeautiful @@ -62,7 +66,9 @@ local slider = {mt={}} --@DOC_wibox_widget_slider_handle_width_EXAMPLE@ -- -- @property handle_width --- @tparam number handle_width +-- @tparam number|nil handle_width +-- @negativeallowed false +-- @propertyunit pixel -- @propemits true false -- @propbeautiful @@ -71,13 +77,15 @@ local slider = {mt={}} --@DOC_wibox_widget_slider_handle_border_EXAMPLE@ -- -- @property handle_border_color --- @tparam color handle_border_color +-- @tparam color|nil handle_border_color -- @propemits true false -- @propbeautiful --- The handle border width. -- @property handle_border_width --- @tparam[opt=0] number handle_border_width +-- @tparam[opt=0] number|nil handle_border_width +-- @propertyunit pixel +-- @negativeallowed false -- @propemits true false -- @propbeautiful @@ -86,7 +94,7 @@ local slider = {mt={}} --@DOC_wibox_widget_slider_bar_shape_EXAMPLE@ -- -- @property bar_shape --- @tparam[opt=gears shape rectangle] gears.shape shape +-- @tparam shape|nil bar_shape -- @propemits true false -- @propbeautiful -- @see gears.shape @@ -96,7 +104,9 @@ local slider = {mt={}} --@DOC_wibox_widget_slider_bar_height_EXAMPLE@ -- -- @property bar_height --- @tparam number bar_height +-- @tparam number|nil bar_height +-- @propertyunit pixel +-- @negativeallowed false -- @propbeautiful -- @propemits true false @@ -105,7 +115,7 @@ local slider = {mt={}} --@DOC_wibox_widget_slider_bar_color_EXAMPLE@ -- -- @property bar_color --- @tparam color bar_color +-- @tparam color|nil bar_color -- @propbeautiful -- @propemits true false @@ -115,7 +125,7 @@ local slider = {mt={}} -- -- Only works when both `bar_active_color` and `bar_color` are passed as hex color string -- @property bar_active_color --- @tparam color bar_active_color +-- @tparam color|nil bar_active_color -- @propbeautiful -- @propemits true false @@ -124,48 +134,56 @@ local slider = {mt={}} --@DOC_wibox_widget_slider_bar_margins_EXAMPLE@ -- -- @property bar_margins --- @tparam[opt={}] table margins --- @tparam[opt=0] number margins.left --- @tparam[opt=0] number margins.right --- @tparam[opt=0] number margins.top --- @tparam[opt=0] number margins.bottom +-- @tparam[opt={}] table|number|nil bar_margins +-- @tparam[opt=0] number bar_margins.left +-- @tparam[opt=0] number bar_margins.right +-- @tparam[opt=0] number bar_margins.top +-- @tparam[opt=0] number bar_margins.bottom +-- @propertyunit pixel +-- @propertytype number A single value used for all sides. +-- @propertytype table A different value for each side. The side names are: +-- @negativeallowed true -- @propbeautiful -- @propemits true false --- The bar (background) border width. -- @property bar_border_width --- @tparam[opt=0] number bar_border_width +-- @tparam[opt=0] number|nil bar_border_width +-- @propertyunit pixel +-- @negativeallowed false -- @propemits true false +-- @propbeautiful --- The bar (background) border_color. -- --@DOC_wibox_widget_slider_bar_border_EXAMPLE@ -- -- @property bar_border_color --- @tparam color bar_border_color +-- @tparam color|nil bar_border_color -- @propbeautiful -- @propemits true false --- The slider value. -- --- **Signal:** *property::value* notify the value is changed. --- --@DOC_wibox_widget_slider_value_EXAMPLE@ -- -- @property value -- @tparam[opt=0] number value +-- @negativeallowed true -- @propemits true false --- The slider minimum value. -- -- @property minimum -- @tparam[opt=0] number minimum +-- @negativeallowed true -- @propemits true false --- The slider maximum value. -- -- @property maximum -- @tparam[opt=100] number maximum +-- @negativeallowed true -- @propemits true false --- The bar (background) border width. @@ -201,13 +219,13 @@ local slider = {mt={}} --- The handle shape. -- -- @beautiful beautiful.slider_handle_shape --- @tparam[opt=gears shape rectangle] gears.shape shape +-- @tparam[opt=gears.shape.rectangle] gears.shape shape -- @see gears.shape --- The bar (background) shape. -- -- @beautiful beautiful.slider_bar_shape --- @tparam[opt=gears shape rectangle] gears.shape shape +-- @tparam[opt=gears.shape.rectangle] gears.shape shape -- @see gears.shape --- The bar (background) height. @@ -521,8 +539,25 @@ local function mouse_press(self, x, y, button_id, _, geo) end --- Create a slider widget. --- @tparam[opt={}] table args +-- -- @constructorfct wibox.widget.slider +-- @tparam[opt={}] table args +-- @tparam[opt] gears.shape args.handle_shape The slider handle shape. +-- @tparam[opt] color args.handle_color The slider handle color. +-- @tparam[opt] table args.handle_margins The slider handle margins. +-- @tparam[opt] number args.handle_width The slider handle width. +-- @tparam[opt] color args.handle_border_color The handle border_color. +-- @tparam[opt] number args.handle_border_width The handle border width. +-- @tparam[opt] gears.shape args.bar_shape The bar (background) shape. +-- @tparam[opt] number args.bar_height The bar (background) height. +-- @tparam[opt] color args.bar_color The bar (background) color. +-- @tparam[opt] color args.bar_active_color The bar (active) color. +-- @tparam[opt] table args.bar_margins The bar (background) margins. +-- @tparam[opt] number args.bar_border_width The bar (background) border width. +-- @tparam[opt] color args.bar_border_color The bar (background) border_color. +-- @tparam[opt] number args.value The slider value. +-- @tparam[opt] number args.minimum The slider minimum value. +-- @tparam[opt] number args.maximum The slider maximum value. local function new(args) local ret = base.make_widget(nil, nil, { enable_properties = true, diff --git a/lib/wibox/widget/systray.lua b/lib/wibox/widget/systray.lua index f7a20361b..e41e7b2c6 100644 --- a/lib/wibox/widget/systray.lua +++ b/lib/wibox/widget/systray.lua @@ -1,4 +1,6 @@ --------------------------------------------------------------------------- +-- Container for the various system tray icons. +-- -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter -- @widgetmod wibox.widget.systray @@ -27,20 +29,23 @@ local display_on_screen = "primary" --- The systray background color. -- +-- Please note that only solid+opaque colors are supported. It does **not** +-- support gradients, patterns or transparent colors. +-- -- @beautiful beautiful.bg_systray --- @param string The color (string like "#ff0000" only) +-- @tparam string bg_systray The color (string like "#ff0000" only) --- The maximum number of rows for systray icons. Icons will fill the -- current column (orthogonally to the systray direction) before -- filling the next column. -- -- @beautiful beautiful.systray_max_rows --- @tparam[opt=1] integer The positive number of rows +-- @tparam[opt=1] integer systray_max_rows The positive number of rows. --- The systray icon spacing. -- -- @beautiful beautiful.systray_icon_spacing --- @tparam[opt=0] integer The icon spacing +-- @tparam[opt=0] integer systray_icon_spacing The icon spacing local function should_display_on(s) if display_on_screen == "primary" then @@ -143,7 +148,11 @@ end -- available space. Otherwise, any single icon has a size of `size`x`size`. -- -- @property base_size --- @tparam integer|nil size The base size +-- @tparam[opt=nil] integer|nil base_size +-- @propertytype integer The size. +-- @propertytype nil Select the size based on the availible space. +-- @propertyunit pixel +-- @negativeallowed false -- @propemits true false function systray:set_base_size(size) @@ -157,7 +166,7 @@ end --- Decide between horizontal or vertical display. -- -- @property horizontal --- @tparam boolean horiz Use horizontal mode? +-- @tparam[opt=true] boolean horizontal -- @propemits true false function systray:set_horizontal(horiz) @@ -171,7 +180,7 @@ end --- Should the systray icons be displayed in reverse order? -- -- @property reverse --- @tparam boolean rev Display in reverse order. +-- @tparam[opt=false] boolean reverse -- @propemits true false function systray:set_reverse(rev) @@ -189,7 +198,9 @@ end -- visible on the primary screen. The default value is "primary". -- -- @property screen --- @tparam screen|"primary" s The screen to display on. +-- @tparam[opt=nil] screen|nil screen +-- @propertytype nil Valid as long as the `systray` widget is only being displayed +-- on a single screen. -- @propemits true false function systray:set_screen(s) @@ -204,9 +215,12 @@ end -- -- Note that this widget can only exist once. -- --- @tparam boolean revers Show in the opposite direction +-- @tparam boolean reverse Show in the opposite direction -- @treturn table The new `systray` widget -- @constructorfct wibox.widget.systray +-- @usebeautiful beautiful.bg_systray +-- @usebeautiful beautiful.systray_icon_spacing +-- @usebeautiful beautiful.systray_max_rows local function new(revers) local ret = wbase.make_widget(nil, nil, {enable_properties = true}) diff --git a/lib/wibox/widget/textbox.lua b/lib/wibox/widget/textbox.lua index 3a295a8fe..41a76e053 100644 --- a/lib/wibox/widget/textbox.lua +++ b/lib/wibox/widget/textbox.lua @@ -21,11 +21,6 @@ local setmetatable = setmetatable local textbox = { mt = {} } ---- The textbox font. --- --- @beautiful beautiful.font --- @param string - --- Set the DPI of a Pango layout local function setup_dpi(box, dpi) assert(dpi, "No DPI provided") @@ -194,7 +189,7 @@ end -- @DOC_wibox_widget_textbox_markup2_EXAMPLE@ -- -- @property markup --- @tparam string markup The text to set. This can contain pango markup (e.g. +-- @tparam[opt=self.text] string markup The text to set. This can contain pango markup (e.g. -- `bold`). You can use `gears.string.escape` to escape -- parts of it. -- @propemits true false @@ -222,7 +217,7 @@ end -- @DOC_wibox_widget_textbox_text2_EXAMPLE@ -- -- @property text --- @tparam string text The text to display. Pango markup is ignored and shown +-- @tparam[opt=""] string text The text to display. Pango markup is ignored and shown -- as-is. -- @propemits true false -- @see markup @@ -245,20 +240,17 @@ end --- Set the text ellipsize mode. -- --- Valid values are: --- --- * `"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[opt="end"] string mode The ellipsize mode. +-- @tparam[opt="end"] string ellipsize +-- @propertyvalue "start" +-- @propertyvalue "middle" +-- @propertyvalue "end" +-- @propertyvalue "none" -- @propemits true false function textbox:set_ellipsize(mode) @@ -276,16 +268,13 @@ end --- Set a textbox wrap mode. -- --- Valid values are: --- --- * **word** --- * **char** --- * **word_char** --- -- @DOC_wibox_widget_textbox_wrap1_EXAMPLE@ -- -- @property wrap --- @tparam[opt="word_char"] string mode Where to wrap? After "word", "char" or "word_char". +-- @tparam[opt="word_char"] string wrap Where to wrap? After "word", "char" or "word_char". +-- @propertyvalue "word" +-- @propertyvalue "char" +-- @propertyvalue "word_char" -- @propemits true false function textbox:set_wrap(mode) @@ -306,16 +295,13 @@ end -- This aligns the text within the widget's bounds. In some situations this may -- differ from aligning the widget with `wibox.container.place`. -- --- Valid values are: --- --- * `"top"` --- * `"center"` --- * `"bottom"` --- --@DOC_wibox_widget_textbox_valign1_EXAMPLE@ -- -- @property valign --- @tparam[opt="center"] string mode The vertical alignment +-- @tparam[opt="center"] string valign +-- @propertyvalue "top" +-- @propertyvalue "center" +-- @propertyvalue "bottom" -- @propemits true false function textbox:set_valign(mode) @@ -336,16 +322,13 @@ end -- This aligns the text within the widget's bounds. In some situations this may -- differ from aligning the widget with `wibox.container.place`. -- --- Valid values are: --- --- * `"left"` --- * `"center"` --- * `"right"` --- --@DOC_wibox_widget_textbox_align1_EXAMPLE@ -- -- @property align --- @tparam[opt="left"] string mode The horizontal alignment +-- @tparam[opt="left"] string align +-- @propertyvalue "left" +-- @propertyvalue "center" +-- @propertyvalue "right" -- @propemits true false function textbox:set_align(mode) @@ -403,7 +386,7 @@ end --@DOC_wibox_widget_textbox_font2_EXAMPLE@ -- -- @property font --- @tparam[opt=beautiful.font] string font The font description as string. +-- @tparam[opt=beautiful.font] font font -- @propemits true false -- @usebeautiful beautiful.font The default font. diff --git a/lib/wibox/widget/textclock.lua b/lib/wibox/widget/textclock.lua index 2a4c2596e..94c27f9fe 100644 --- a/lib/wibox/widget/textclock.lua +++ b/lib/wibox/widget/textclock.lua @@ -1,5 +1,5 @@ --------------------------------------------------------------------------- ---- Text clock widget. +--- Display the time (and date) in a text box. -- -- The `wibox.widget.textclock` widget is part of the Awesome WM's widget -- system (see @{03-declarative-layout.md}). @@ -70,7 +70,7 @@ end -- For information about the format specifiers, see -- [the GLib docs](https://developer.gnome.org/glib/stable/glib-GDateTime.html#g-date-time-format). -- @property format --- @tparam string format The new time format. This can contain pango markup. +-- @tparam[opt=" %a %b %d %H:%M"] string format The new time format. This can contain pango markup. function textclock:set_format(format) self._private.format = format @@ -86,7 +86,7 @@ end -- e.g. "Z" for UTC, "±hh:mm" or "Europe/Amsterdam". See -- [GTimeZone](https://developer.gnome.org/glib/stable/glib-GTimeZone.html#g-time-zone-new). -- @property timezone --- @tparam string timezone +-- @tparam[opt=TimeZone.new()] string timezone function textclock:set_timezone(tzid) self._private.tzid = tzid @@ -101,7 +101,9 @@ end --- Set the clock's refresh rate. -- -- @property refresh --- @tparam number refresh How often the clock is updated, in seconds +-- @tparam[opt=60] number refresh How often the clock is updated, in seconds +-- @propertyunit second +-- @negativeallowed false function textclock:set_refresh(refresh) self._private.refresh = refresh or self._private.refresh @@ -114,6 +116,7 @@ end --- Force a textclock to update now. -- +-- @noreturn -- @method force_update function textclock:force_update() self._timer:emit_signal("timeout") diff --git a/luaa.c b/luaa.c index 233174ef0..bf1800ce9 100644 --- a/luaa.c +++ b/luaa.c @@ -19,7 +19,7 @@ * */ -/** AwesomeWM lifecycle API. +/** AwesomeWM lifecycle and low-level APIs. * * This module contains the functions and signal to manage the lifecycle of the * AwesomeWM process. It allows to execute code at specific point from the early @@ -36,6 +36,7 @@ * * @tparam string name The name of the X11 property. * @tparam string type One of "string", "number" or "boolean". + * @noreturn * @staticfct register_xproperty */ @@ -97,7 +98,7 @@ signal_array_t global_signals; * * This signal is used in the example configuration, @{05-awesomerc.md}, * to let a notification box pop up. - * @param err Table with the error object, can be converted to a string with + * @tparam table err Table with the error object, can be converted to a string with * `tostring(err)`. * @signal debug::error */ @@ -151,7 +152,7 @@ signal_array_t global_signals; /** Keyboard group has changed. * * It's used in `awful.widget.keyboardlayout` to redraw the layout. - * @param group Integer containing the changed group + * @tparam number group Integer containing the changed group * @signal xkb::group_changed. */ @@ -172,8 +173,8 @@ signal_array_t global_signals; * * This signal is emitted in the `atexit` handler as well when awesome * restarts. - * @param reason_restart Boolean value is true if the signal was sent - * because of a restart. + * @tparam boolean reason_restart Boolean value is true if the signal was sent + * because of a restart. * @signal exit */ @@ -229,6 +230,7 @@ composite_manager_running(void) /** Quit awesome. * @tparam[opt=0] integer code The exit code to use when exiting. * @staticfct quit + * @noreturn */ static int luaA_quit(lua_State *L) @@ -244,8 +246,9 @@ luaA_quit(lua_State *L) /** Execute another application, probably a window manager, to replace * awesome. * - * @param cmd The command line to execute. + * @tparam string cmd The command line to execute. * @staticfct exec + * @noreturn */ static int luaA_exec(lua_State *L) @@ -260,6 +263,7 @@ luaA_exec(lua_State *L) /** Restart awesome. * @staticfct restart + * @noreturn */ static int luaA_restart(lua_State *L) @@ -290,6 +294,7 @@ luaA_kill(lua_State *L) /** Synchronize with the X11 server. This is needed in the test suite to avoid * some race conditions. You should never need to use this function. * @staticfct sync + * @noreturn */ static int luaA_sync(lua_State *L) @@ -302,7 +307,7 @@ luaA_sync(lua_State *L) * * @param pixbuf The pixbuf as a light user datum. * @param path The pixbuf origin path - * @return A cairo surface as light user datum. + * @treturn gears.surface A cairo surface as light user datum. * @staticfct pixbuf_to_surface */ static int @@ -318,10 +323,9 @@ luaA_pixbuf_to_surface(lua_State *L) /** Load an image from a given path. * - * @param name The file name. - * @return[1] A cairo surface as light user datum. - * @return[2] nil - * @treturn[2] string Error message + * @tparam string name The file name. + * @treturn gears.surface A cairo surface as light user datum. + * @treturn nil|string The error message, if any. * @staticfct load_image */ static int @@ -351,8 +355,9 @@ luaA_load_image(lua_State *L) * The closest equal or bigger size is picked if present, otherwise the closest * smaller size is picked. The default is 0 pixels, ie. the smallest icon. * - * @param size The size of the icons in pixels. + * @tparam integer size The size of the icons in pixels. * @staticfct set_preferred_icon_size + * @noreturn */ static int luaA_set_preferred_icon_size(lua_State *L) @@ -806,9 +811,10 @@ luaA_awesome_index(lua_State *L) /** Add a global signal. * - * @param name A string with the event name. - * @param func The function to call. + * @tparam string name A string with the event name. + * @tparam function func The function to call. * @staticfct connect_signal + * @noreturn */ static int luaA_awesome_connect_signal(lua_State *L) @@ -821,9 +827,10 @@ luaA_awesome_connect_signal(lua_State *L) /** Remove a global signal. * - * @param name A string with the event name. - * @param func The function to call. + * @tparam string name A string with the event name. + * @tparam function func The function to call. * @staticfct disconnect_signal + * @noreturn */ static int luaA_awesome_disconnect_signal(lua_State *L) @@ -838,9 +845,10 @@ luaA_awesome_disconnect_signal(lua_State *L) /** Emit a global signal. * - * @param name A string with the event name. + * @tparam function name A string with the event name. * @param ... The signal arguments. * @staticfct emit_signal + * @noreturn */ static int luaA_awesome_emit_signal(lua_State *L) diff --git a/mouse.c b/mouse.c index 42d0b382d..bce3d33a4 100644 --- a/mouse.c +++ b/mouse.c @@ -19,7 +19,7 @@ * */ -/** awesome mouse API. +/** Manipulate and inspect the mouse cursor. * * The mouse buttons are represented as index. The common ones are: * @@ -76,7 +76,15 @@ static int miss_newindex_handler = LUA_REFNIL; /** * The `screen` under the cursor * @property screen - * @param screen + * @tparam screen|nil screen + * @propertytype nil This will only happen if `screen` is set to `off` in the + * modeline or command line options. It happens very early in the initialization + * before the screens are created. If you check the screen from a signal, then + * you should never have to worry about this. Another corner case where this + * *might* happen is if you use `fake_resize` to have a smaller area than the + * physical screen. + * @propertydefault It checks where the cursor is and match it to one of the + * screen `geometry`. */ /** Get the pointer position. @@ -273,7 +281,7 @@ luaA_mouse_coords(lua_State *L) /** Get the client or any object which is under the pointer. * - * @treturn client.object|nil A client or nil. + * @treturn client|wibox|nil A client, wibox or nil. * @staticfct object_under_pointer */ static int diff --git a/mousegrabber.c b/mousegrabber.c index 31e0c3457..35bbeb520 100644 --- a/mousegrabber.c +++ b/mousegrabber.c @@ -19,7 +19,7 @@ * */ -/** awesome mousegrabber API. +/** Set a callback to process all mouse events. * @author Julien Danjou <julien@danjou.info> * @copyright 2008-2009 Julien Danjou * @coreclassmod mousegrabber @@ -87,8 +87,9 @@ mousegrabber_handleevent(lua_State *L, int x, int y, uint16_t mask) *@DOC_cursor_c_COMMON@ * * - * @param func A callback function as described above. - * @param cursor The name of a X cursor to use while grabbing. + * @tparam function func A callback function as described above. + * @tparam string cursor The name of a X cursor to use while grabbing. + * @noreturn * @staticfct run */ static int @@ -120,6 +121,7 @@ luaA_mousegrabber_run(lua_State *L) /** Stop grabbing the mouse pointer. * * @staticfct stop + * @noreturn */ int luaA_mousegrabber_stop(lua_State *L) diff --git a/objects/client.c b/objects/client.c index bc3a76c9a..6bd8df267 100644 --- a/objects/client.c +++ b/objects/client.c @@ -19,7 +19,7 @@ * */ -/** A process window. +/** A process window managed by AwesomeWM. * * Clients are the name used by Awesome (and X11) to refer to a window. * @@ -39,9 +39,6 @@ * client's content. * Finally, each clients can have titlebars (see `awful.titlebar`). * - * Additionally to the classes described here, one can also use signals as - * described in @{signals} and X properties as described in @{xproperties}. - * * Some signal names are starting with a dot. These dots are artefacts from * the documentation generation, you get the real signal name by * removing the starting dot. @@ -273,9 +270,10 @@ lua_class_t client_class; * To implement focus stealing filters see `awful.ewmh.add_activate_filter`. * * @signal request::activate + * @tparam client c The client. * @tparam string context The context where this signal was used. * @tparam[opt] table hints A table with additional hints: - * @tparam[opt=false] boolean hints.raise should the client be raised? + * @tparam[opt=false] boolean hints.raise Should the client be raised? * @request client activate ewmh granted When the client asks to be activated. * @classsignal */ @@ -294,9 +292,10 @@ lua_class_t client_class; * moving the mouse. * * @signal request::autoactivate + * @tparam client c The client. * @tparam string context The context where this signal was used. * @tparam[opt] table hints A table with additional hints: - * @tparam[opt=false] boolean hints.raise should the client be raised? + * @tparam[opt=false] boolean hints.raise Should the client be raised? * @classsignal * */ @@ -307,7 +306,7 @@ lua_class_t client_class; * @tparam client c The client * @tparam string context Why and what to resize. This is used for the * handlers to know if they are capable of applying the new geometry. - * @tparam[opt={}] table Additional arguments. Each context handler may + * @tparam[opt={}] table hints Additional arguments. Each context handler may * interpret this differently. * @request client geometry client_maximize_horizontal granted When a client * (programmatically) asks for the maximization to be changed. @@ -320,6 +319,10 @@ lua_class_t client_class; * * @signal request::tag * @tparam client c The client requesting a new tag. + * @tparam[opt] tag tag A preferred tag. + * @tparam[opt] table hints + * @tparam[opt] string hints.reason + * @tparam[opt] screen hints.screen * @classsignal */ @@ -373,6 +376,8 @@ lua_class_t client_class; /** Emitted when a client gets tagged. * @signal tagged * @tparam tag t The tag object. + * @see tags + * @see untagged */ /** Emitted when a client gets unfocused. @@ -382,6 +387,8 @@ lua_class_t client_class; /** Emitted when a client gets untagged. * @signal untagged * @tparam tag t The tag object. + * @see tags + * @see tagged */ /** @@ -448,6 +455,8 @@ lua_class_t client_class; * * @property window * @tparam integer window + * @propertydefault This is generated by X11. + * @negativeallowed false * @propemits false false * @readonly */ @@ -460,6 +469,7 @@ lua_class_t client_class; * * @property name * @tparam string name + * @propertydefault This is provided by the application. * @propemits false false * @see awful.titlebar * @see awful.widget.tasklist @@ -523,6 +533,7 @@ lua_class_t client_class; * @property type * @tparam string type * @propemits false false + * @propertydefault This is provided by the application. * @readonly * @see ruled.client */ @@ -552,6 +563,7 @@ lua_class_t client_class; * @property class * @tparam string class * @propemits false false + * @propertydefault This is provided by the application. * @readonly * @see instance * @see ruled.client @@ -578,6 +590,7 @@ lua_class_t client_class; * * @property instance * @tparam string instance + * @propertydefault This is provided by the application. * @propemits false false * @readonly * @see class @@ -591,6 +604,8 @@ lua_class_t client_class; * * @property pid * @tparam integer pid + * @negativeallowed false + * @propertydefault This is randomly assigned by the kernel. * @propemits false false * @readonly */ @@ -600,6 +615,7 @@ lua_class_t client_class; * * @property role * @tparam string role + * @propertydefault This is provided by the application. * @propemits false false * @readonly * @see instance @@ -621,6 +637,8 @@ lua_class_t client_class; * * @property machine * @tparam string machine + * @propertydefault This is the hostname unless the client is from an + * SSH session or using the rarely used direct X11 network socket. * @propemits false false * @readonly */ @@ -630,6 +648,7 @@ lua_class_t client_class; * * @property icon_name * @tparam string icon_name + * @propertydefault This is provided by the application. * @propemits false false * @readonly */ @@ -661,7 +680,8 @@ lua_class_t client_class; * smallest available) * * @property icon - * @tparam surface icon + * @tparam image icon + * @propertydefault This is provided by the application. * @propemits false false * @usage local ib = wibox.widget.imagebox(c.icon) * @see awful.widget.clienticon @@ -680,7 +700,11 @@ lua_class_t client_class; * } * * @property icon_sizes - * @tparam table sizes + * @tparam table icon_sizes + * @tablerowtype A list of tables. Each table has the following rows: + * @tablerowkey integer 1 The width value. + * @tablerowkey integer 2 The height value. + * @propertydefault This is provided by the application. * @propemits false false * @readonly * @see awful.widget.clienticon @@ -702,6 +726,8 @@ lua_class_t client_class; * * @property screen * @tparam screen screen + * @propertydefault This usually correspond to where the top-left (or other + * gravities) is placed. Then it is mapped to the screen `geometry`. * @propemits false false * @see move_to_screen */ @@ -710,7 +736,7 @@ lua_class_t client_class; * Define if the client must be hidden (Never mapped, invisible in taskbar). * * @property hidden - * @tparam boolean hidden + * @tparam[opt=false] boolean hidden * @propemits false false * @see minimized * @see skip_taskbar @@ -729,7 +755,7 @@ lua_class_t client_class; * @DOC_sequences_client_minimize1_EXAMPLE@ * * @property minimized - * @tparam boolean minimized + * @tparam[opt=false] boolean minimized * @propemits false false * @see hidden * @see isvisible @@ -746,7 +772,7 @@ lua_class_t client_class; * This is enabled by default. To disable it by default, see `ruled.client`. * * @property size_hints_honor - * @tparam boolean size_hints_honor + * @tparam[opt=true] boolean size_hints_honor * @propemits false false * @see size_hints */ @@ -764,7 +790,10 @@ lua_class_t client_class; * @DOC_awful_client_border_width_EXAMPLE@ * * @property border_width - * @tparam integer border_width + * @tparam[opt=nil] integer|nil border_width + * @propertytype nil Let AwesomeWM manage it based on the client state. + * @negativeallowed false + * @propertyunit pixel * @propemits false false * @usebeautiful beautiful.border_width_active * @usebeautiful beautiful.border_width_normal @@ -805,8 +834,9 @@ lua_class_t client_class; * specifically. Other RGB colors with an alpha of `0` won't work. * * @property border_color - * @tparam color border_color Any string, gradient or pattern definition that - * can be converted to a cairo pattern. + * @tparam[opt=nil] color|nil border_color + * @propertytype nil Let AwesomeWM manage it based on the client state. + * @propertydefault * @propemits false false * @usebeautiful beautiful.border_color_marked The fallback color when the * client is marked. @@ -865,7 +895,7 @@ lua_class_t client_class; * @DOC_awful_client_urgent1_EXAMPLE@ * * @property urgent - * @tparam boolean urgent + * @tparam[opt=false] boolean urgent * @propemits false false * @request client border active granted When a client becomes active and is no * longer urgent. @@ -922,7 +952,9 @@ lua_class_t client_class; * This property has no signals when the content changes. * * @property content - * @tparam surface content + * @tparam raw_curface content + * @propertydefault This is a live surface. Always use `gears.surface` to take + * a snapshot. * @readonly * @see gears.surface */ @@ -937,7 +969,9 @@ lua_class_t client_class; * @DOC_awful_client_opacity1_EXAMPLE@ * * @property opacity - * @tparam number opacity Between 0 (transparent) to 1 (opaque). + * @tparam[opt=1.0] number opacity + * @rangestart 0.0 Transparent. + * @rangestop 1.0 Opaque. * @propemits false false * @see request::border * @see awesome.composite_manager_running @@ -947,7 +981,7 @@ lua_class_t client_class; * The client is on top of every other windows. * * @property ontop - * @tparam boolean ontop + * @tparam[opt=false] boolean ontop * @propemits false false * @see below * @see above @@ -957,7 +991,7 @@ lua_class_t client_class; * The client is above normal windows. * * @property above - * @tparam boolean above + * @tparam[opt=false] boolean above * @propemits false false * @see below * @see ontop @@ -967,7 +1001,7 @@ lua_class_t client_class; * The client is below normal windows. * * @property below - * @tparam boolean below + * @tparam[opt=false] boolean below * @propemits false false * @see above * @see ontop @@ -979,7 +1013,7 @@ lua_class_t client_class; * @DOC_sequences_client_fullscreen_EXAMPLE@ * * @property fullscreen - * @tparam boolean fullscreen + * @tparam[opt=false] boolean fullscreen * @propemits false false * @request client geometry fullscreen granted When the client must be resized * because it became (or stop being) fullscreen. @@ -997,7 +1031,7 @@ lua_class_t client_class; * @DOC_sequences_client_maximized_EXAMPLE@ * * @property maximized - * @tparam boolean maximized + * @tparam[opt=false] boolean maximized * @propemits false false * @request client geometry maximized granted When the client must be resized * because it became (or stop being) maximized. @@ -1015,7 +1049,7 @@ lua_class_t client_class; * @DOC_sequences_client_maximized_horizontal_EXAMPLE@ * * @property maximized_horizontal - * @tparam boolean maximized_horizontal + * @tparam[opt=false] boolean maximized_horizontal * @propemits false false * @request client geometry maximized_horizontal granted When the client must be resized * because it became (or stop being) maximized horizontally. @@ -1032,7 +1066,7 @@ lua_class_t client_class; * @DOC_sequences_client_maximized_vertical_EXAMPLE@ * * @property maximized_vertical - * @tparam boolean maximized_vertical + * @tparam[opt=false] boolean maximized_vertical * @propemits false false * @request client geometry maximized_vertical granted When the client must be resized * because it became (or stop being) maximized vertically. @@ -1058,7 +1092,7 @@ lua_class_t client_class; * applications can belong to each other without being modal. * * @property transient_for - * @tparam client transient_for + * @tparam[opt=nil] client|nil transient_for * @propemits false false * @readonly * @see modal @@ -1076,6 +1110,8 @@ lua_class_t client_class; * * @property group_window * @tparam integer group_window + * @propertydefault This is auto-generated by X11. + * @negativeallowed false * @propemits false false * @readonly * @see leader_window @@ -1087,7 +1123,9 @@ lua_class_t client_class; * This is the ID of the group window, not a client object. * * @property leader_window - * @tparam number leader_window + * @tparam integer leader_window + * @propertydefault This is auto-generated by X11. + * @negativeallowed false * @propemits false false * @readonly * @see transient_for @@ -1108,39 +1146,39 @@ lua_class_t client_class; * advised to set `size_hints_honor` to `false` in the `ruled.client` rules. * * @property size_hints - * @tparam[opt] table|nil hints The hints. - * @tparam[opt] table|nil hints.user_position A table with `x` and `y` keys. It + * @tparam[opt=nil] table|nil size_hints + * @tparam[opt] table|nil size_hints.user_position A table with `x` and `y` keys. It * contains the preferred position of the client. This is set when the * position has been modified by the user. See `program_position`. - * @tparam[opt] table|nil hints.program_position A table with `x` and `y` keys. It + * @tparam[opt] table|nil size_hints.program_position A table with `x` and `y` keys. It * contains the preferred position of the client. This is set when the * application itself requests a specific position. See `user_position`. - * @tparam[opt] table|nil hints.user_size A table with `width` and `height`. This + * @tparam[opt] table|nil size_hints.user_size A table with `width` and `height`. This * contains the client preferred size when it has previously been set by * the user. See `program_size` for the equivalent when the applications * itself wants to specify its preferred size. - * @tparam[opt] table|nil hints.program_size A table with `width` and `height`. This + * @tparam[opt] table|nil size_hints.program_size A table with `width` and `height`. This * contains the client preferred size as specified by the application. - * @tparam[opt] integer|nil hints.max_width The maximum width (in pixels). - * @tparam[opt] integer|nil hints.max_height The maximum height (in pixels). - * @tparam[opt] integer|nil hints.min_width The minimum width (in pixels). - * @tparam[opt] integer|nil hints.min_height The minimum height (in pixels). - * @tparam[opt] integer|nil hints.width_inc The number of pixels by which the + * @tparam[opt] integer|nil size_hints.max_width The maximum width (in pixels). + * @tparam[opt] integer|nil size_hints.max_height The maximum height (in pixels). + * @tparam[opt] integer|nil size_hints.min_width The minimum width (in pixels). + * @tparam[opt] integer|nil size_hints.min_height The minimum height (in pixels). + * @tparam[opt] integer|nil size_hints.width_inc The number of pixels by which the * client width may be increased or decreased. For example, for terminals, * the size has to be proportional with the monospace font size. - * @tparam[opt] integer|nil hints.height_inc The number of pixels by which the + * @tparam[opt] integer|nil size_hints.height_inc The number of pixels by which the * client height may be increased or decreased. For example, for terminals, * the size has to be proportional with the monospace font size. - * @tparam[opt] string|nil hints.win_gravity The client `gravity` defines the corder + * @tparam[opt] string|nil size_hints.win_gravity The client `gravity` defines the corder * from which the size is computed. For most clients, it is `north_west`, which * corresponds to the top-left of the window. This will affect how the client * is resized and other size related operations. - * @tparam[opt] integer|nil hints.min_aspect_num - * @tparam[opt] integer|nil hints.min_aspect_den - * @tparam[opt] integer|nil hints.max_aspect_num - * @tparam[opt] integer|nil hints.max_aspect_den - * @tparam[opt] integer|nil hints.base_width - * @tparam[opt] integer|nil hints.base_height + * @tparam[opt] integer|nil size_hints.min_aspect_num + * @tparam[opt] integer|nil size_hints.min_aspect_den + * @tparam[opt] integer|nil size_hints.max_aspect_num + * @tparam[opt] integer|nil size_hints.max_aspect_den + * @tparam[opt] integer|nil size_hints.base_width + * @tparam[opt] integer|nil size_hints.base_height * @propemits false false * @readonly * @see size_hints_honor @@ -1159,24 +1197,24 @@ lua_class_t client_class; * should be enabled. * * @property motif_wm_hints - * @tparam table hints The hints. - * @tparam[opt] boolean hints.functions.all - * @tparam[opt] boolean hints.functions.resize - * @tparam[opt] boolean hints.functions.move - * @tparam[opt] boolean hints.functions.minimize - * @tparam[opt] boolean hints.functions.maximize - * @tparam[opt] boolean hints.functions.close - * @tparam[opt] boolean hints.decorations.all - * @tparam[opt] boolean hints.decorations.border - * @tparam[opt] boolean hints.decorations.resizeh - * @tparam[opt] boolean hints.decorations.title - * @tparam[opt] boolean hints.decorations.menu - * @tparam[opt] boolean hints.decorations.minimize - * @tparam[opt] boolean hints.decorations.maximize - * @tparam[opt] string hints.input_mode This is either `modeless`, + * @tparam[opt={}] table motif_wm_hints + * @tparam[opt] boolean motif_wm_hints.functions.all + * @tparam[opt] boolean motif_wm_hints.functions.resize + * @tparam[opt] boolean motif_wm_hints.functions.move + * @tparam[opt] boolean motif_wm_hints.functions.minimize + * @tparam[opt] boolean motif_wm_hints.functions.maximize + * @tparam[opt] boolean motif_wm_hints.functions.close + * @tparam[opt] boolean motif_wm_hints.decorations.all + * @tparam[opt] boolean motif_wm_hints.decorations.border + * @tparam[opt] boolean motif_wm_hints.decorations.resizeh + * @tparam[opt] boolean motif_wm_hints.decorations.title + * @tparam[opt] boolean motif_wm_hints.decorations.menu + * @tparam[opt] boolean motif_wm_hints.decorations.minimize + * @tparam[opt] boolean motif_wm_hints.decorations.maximize + * @tparam[opt] string motif_wm_hints.input_mode This is either `modeless`, * `primary_application_modal`, `system_modal`, * `full_application_modal` or `unknown`. - * @tparam[opt] boolean hints.status.tearoff_window + * @tparam[opt] boolean motif_wm_hints.status.tearoff_window * @propemits false false * @readonly */ @@ -1191,7 +1229,7 @@ lua_class_t client_class; * @DOC_sequences_client_sticky_EXAMPLE@ * * @property sticky - * @tparam boolean sticky + * @tparam[opt=false] boolean sticky * @propemits false false * @see skip_taskbar */ @@ -1213,6 +1251,7 @@ lua_class_t client_class; * * @property modal * @tparam boolean modal + * @propertydefault This is provided by the application. * @propemits false false * @see transient_for */ @@ -1224,7 +1263,7 @@ lua_class_t client_class; * click on it. * * @property focusable - * @tparam boolean focusable + * @tparam[opt=true] boolean focusable * @propemits false false * @see shape_input * @see client.focus @@ -1244,7 +1283,8 @@ lua_class_t client_class; * cases, use the `shape` property. * * @property shape_bounding - * @tparam surface shape_bounding + * @tparam image shape_bounding + * @propertydefault An A1 surface where all pixels are white. * @propemits false false * @see shape * @see gears.surface.apply_shape_bounding @@ -1263,7 +1303,8 @@ lua_class_t client_class; * border. * * @property shape_clip - * @tparam surface shape_clip + * @tparam image shape_clip + * @propertydefault An A1 surface where all pixels are white. * @propemits false false * @see shape_bounding * @see shape_input @@ -1282,7 +1323,8 @@ lua_class_t client_class; * client rather than propagated below it. * * @property shape_input - * @tparam surface shape_input + * @tparam image shape_input + * @propertydefault An A1 surface where all pixels are white. * @propemits false false * @see shape_bounding * @see shape_clip @@ -1298,7 +1340,8 @@ lua_class_t client_class; * The client's bounding shape as set by the program as a (native) cairo surface. * * @property client_shape_bounding - * @tparam surface client_shape_bounding + * @tparam image client_shape_bounding + * @propertydefault An A1 surface where all pixels are white. * @propemits false false * @readonly * @see shape_bounding @@ -1315,7 +1358,8 @@ lua_class_t client_class; * The client's clip shape as set by the program as a (native) cairo surface. * * @property client_shape_clip - * @tparam surface client_shape_clip + * @tparam image client_shape_clip + * @propertydefault An A1 surface where all pixels are white. * @propemits false false * @readonly * @see shape_bounding @@ -1384,6 +1428,7 @@ lua_class_t client_class; * * @property startup_id * @tparam string startup_id + * @propertydefault This is optionally provided by the application. * @propemits false false * @see awful.spawn */ @@ -1396,7 +1441,7 @@ lua_class_t client_class; * local is_valid = pcall(function() return c.valid end) and c.valid * * @property valid - * @tparam boolean valid + * @tparam[opt=true] boolean valid * @propemits false false * @readonly * @see kill @@ -1410,7 +1455,7 @@ lua_class_t client_class; * to only get the first tag and ignore everything else. * * @property first_tag - * @tparam tag first_tag + * @tparam[opt=nil] tag|nil first_tag * @propemits false false * @readonly * @see tags @@ -1431,7 +1476,11 @@ lua_class_t client_class; * * @DOC_screen_struts_EXAMPLE@ * - * @tparam table struts A table with new strut values, or none. + * @tparam table|nil struts A table with new strut values, or none. + * @tparam[opt=0] integer struts.left + * @tparam[opt=0] integer struts.right + * @tparam[opt=0] integer struts.top + * @tparam[opt=0] integer struts.bottom * @treturn table A table with strut values. * @method struts * @see geometry @@ -1442,7 +1491,8 @@ lua_class_t client_class; /** Get or set mouse buttons bindings for a client. * * @property buttons - * @tparam table buttons + * @tparam[opt={}] table buttons + * @tablerowtype A list of `awful.button`s objects. * @propemits false false * @see awful.button * @see append_mousebinding @@ -3184,6 +3234,7 @@ out: * @DOC_sequences_client_kill1_EXAMPLE@ * * @method kill + * @noreturn * @see awesome.kill */ static int @@ -3199,6 +3250,7 @@ luaA_client_kill(lua_State *L) * @DOC_sequences_client_swap1_EXAMPLE@ * * @tparam client c A client to swap with. + * @noreturn * @method swap * @emits swapped * @emitstparam swapped client other The other client. @@ -3331,6 +3383,7 @@ luaA_client_get_first_tag(lua_State *L, client_t *c) /** Raise a client on top of others which are on the same layer. * * @method raise + * @noreturn * @emits raised * @see above * @see below @@ -3357,6 +3410,7 @@ luaA_client_raise(lua_State *L) /** Lower a client on bottom of others which are on the same layer. * * @method lower + * @noreturn * @emits lowered * @see above * @see below @@ -3389,6 +3443,7 @@ luaA_client_lower(lua_State *L) /** Stop managing a client. * * @method unmanage + * @noreturn */ static int luaA_client_unmanage(lua_State *L) @@ -4290,7 +4345,8 @@ luaA_client_set_shape_input(lua_State *L, client_t *c) /** Get or set keys bindings for a client. * * @property keys - * @tparam table keys + * @tparam[opt={}] table keys + * @tablerowtype A list of `awful.key`s objects. * @propemits false false * @see awful.key * @see append_keybinding @@ -4351,7 +4407,7 @@ luaA_client_get_icon_sizes(lua_State *L, client_t *c) * (by raising an error, the function will be stopped and nothing will be * returned to the caller). * - * @tparam interger index The index in the list of icons to get. + * @tparam integer index The index in the list of icons to get. * @treturn surface A lightuserdata for a cairo surface. This reference must be * destroyed! * @method get_icon diff --git a/objects/drawable.c b/objects/drawable.c index 0bf6a21ec..56449c0e8 100644 --- a/objects/drawable.c +++ b/objects/drawable.c @@ -20,10 +20,7 @@ * */ -/** awesome drawable API. - * - * Furthermore to the classes described here, one can also use signals as - * described in @{signals}. +/** Low-level API to allow Cairo to draw on clients and wiboxes. * * @author Uli Schlachter <psychon@znc.in> * @copyright 2012 Uli Schlachter @@ -38,8 +35,9 @@ /** Drawable object. * - * @field surface The drawable's cairo surface. - * @staticfct drawable + * @property image + * @tparam image image + * @propertydefault Autogenerated. */ /** @@ -92,12 +90,12 @@ * @staticfct instances */ -/** Set a __index metamethod for all drawable instances. +/* Set a __index metamethod for all drawable instances. * @tparam function cb The meta-method * @staticfct set_index_miss_handler */ -/** Set a __newindex metamethod for all drawable instances. +/* Set a __newindex metamethod for all drawable instances. * @tparam function cb The meta-method * @staticfct set_newindex_miss_handler */ @@ -189,6 +187,7 @@ luaA_drawable_get_surface(lua_State *L, drawable_t *drawable) * the drawable's surface has been done and should become visible. * * @method refresh + * @noreturn */ static int luaA_drawable_refresh(lua_State *L) @@ -241,4 +240,6 @@ drawable_class_setup(lua_State *L) NULL); } +/* @DOC_cobject_COMMON@ */ + // vim: filetype=c:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/objects/screen.c b/objects/screen.c index c2e00f1b8..f6425c43e 100644 --- a/objects/screen.c +++ b/objects/screen.c @@ -19,7 +19,7 @@ * */ -/** awesome screen API. +/** A physical or virtual screen object. * * Screen objects can be added and removed over time. To get a callback for all * current and future screens, use `awful.screen.connect_for_each_screen`: @@ -37,9 +37,6 @@ * Most basic Awesome objects also have a screen property, see `mouse.screen` * `client.screen`, `wibox.screen` and `tag.screen`. * - * Furthermore to the classes described here, one can also use signals as - * described in @{signals}. - * * @DOC_uml_nav_tables_screen_EXAMPLE@ * * @author Julien Danjou <julien@danjou.info> @@ -167,18 +164,19 @@ /** * The screen coordinates. * - * **Signal:** - * - * * *property::geometry* + * The returned table contains the `x`, `y`, `width` and `height` keys. * * @DOC_screen_geometry_EXAMPLE@ * * @property geometry - * @param table - * @tfield integer table.x The horizontal position - * @tfield integer table.y The vertical position - * @tfield integer table.width The width - * @tfield integer table.height The height + * @tparam table geometry + * @tparam integer geometry.x The horizontal position. + * @tparam integer geometry.y The vertical position. + * @tparam integer geometry.width The width. + * @tparam integer geometry.height The height. + * @propertydefault Either from `xrandr` or from `fake_resize`. + * @propertyunit pixel + * @propemits false false * @readonly */ @@ -208,7 +206,10 @@ * screen[1].answer = 42 * * @property index - * @param integer + * @tparam integer index + * @propertydefault The index is not derived from the geometry. It may or may + * not be from `xrandr`. It isn't a good idea to rely on indices. + * @negativeallowed false * @see screen * @readonly */ @@ -222,26 +223,26 @@ * * It can be modified be altering the `wibox` or `client` struts. * - * **Signal:** - * - * * *property::workarea* - * * @DOC_screen_workarea_EXAMPLE@ * * @property workarea + * @tparam table workarea + * @tparam integer workarea.x The horizontal position + * @tparam integer workarea.y The vertical position + * @tparam integer workarea.width The width + * @tparam integer workarea.height The height + * @propertyunit pixel + * @propertydefault Based on `geometry` with the `awful.wibar` and docks area + * substracted. + * @propemits false false * @see client.struts - * @param table - * @tfield integer table.x The horizontal position - * @tfield integer table.y The vertical position - * @tfield integer table.width The width - * @tfield integer table.height The height * @readonly */ /** Get the number of instances. * - * @return The number of screen objects alive. + * @treturn table The number of screen objects alive. * @staticfct instances */ @@ -1571,6 +1572,7 @@ luaA_screen_module_newindex(lua_State *L) * for s in screen do * print("Oh, wow, we have screen " .. tostring(s)) * end + * @treturn function A lua iterator function. * @staticfct screen */ static int @@ -1657,7 +1659,7 @@ luaA_screen_get_name(lua_State *L, screen_t *s) /** Get the number of screens. * - * @return The screen count, at least 1. + * @treturn number The screen count. * @staticfct count */ static int @@ -1681,9 +1683,9 @@ luaA_screen_count(lua_State *L) * * @tparam integer x X-coordinate for screen. * @tparam integer y Y-coordinate for screen. - * @tparam integer width width for screen. - * @tparam integer height height for screen. - * @return The new screen. + * @tparam integer width Width for screen. + * @tparam integer height Height for screen. + * @treturn screen The new screen. * @constructorfct fake_add */ static int @@ -1732,6 +1734,7 @@ luaA_screen_fake_add(lua_State *L) * @DOC_sequences_screen_fake_remove_EXAMPLE@ * * @method fake_remove + * @noreturn */ static int luaA_screen_fake_remove(lua_State *L) @@ -1770,6 +1773,9 @@ luaA_screen_fake_remove(lua_State *L) * @tparam integer width The new width for screen. * @tparam integer height The new height for screen. * @method fake_resize + * @noreturn + * @see split + * @see geometry */ static int luaA_screen_fake_resize(lua_State *L) @@ -1805,6 +1811,7 @@ luaA_screen_fake_resize(lua_State *L) * * @tparam client s A screen to swap with. * @method swap + * @noreturn */ static int luaA_screen_swap(lua_State *L) diff --git a/objects/tag.c b/objects/tag.c index 80d74b6ea..87bff22a0 100644 --- a/objects/tag.c +++ b/objects/tag.c @@ -19,7 +19,7 @@ * */ - /** awesome tag API. + /** Labelled container where `client` objects can be stored. * * What is a tag? * ============== @@ -262,7 +262,7 @@ lua_class_t tag_class; * @DOC_sequences_tag_name_EXAMPLE@ * * @property name - * @tparam string name + * @tparam[opt=""] string name * @propemits false false */ @@ -272,7 +272,7 @@ lua_class_t tag_class; * @DOC_sequences_tag_selected_EXAMPLE@ * * @property selected - * @tparam boolean selected + * @tparam[opt=false] boolean selected * @propemits false false */ @@ -280,13 +280,13 @@ lua_class_t tag_class; * True if the tag is active and can be used. * * @property activated - * @tparam boolean activated + * @tparam[opt=true] boolean activated * @propemits false false */ /** Get the number of instances. * - * @return The number of tag objects alive. + * @treturn table The number of tag objects alive. * @staticfct instances */ @@ -457,7 +457,7 @@ luaA_tag_new(lua_State *L) * * @tparam[opt=nil] table clients_table None or a table of clients to set as being tagged with * this tag. - * @return A table with the clients attached to this tags. + * @treturn table A table with the clients attached to this tags. * @method clients */ static int diff --git a/root.c b/root.c index 2b8030893..ef6aa2684 100644 --- a/root.c +++ b/root.c @@ -19,7 +19,16 @@ * */ -/** awesome root window API. +/** APIs to interact with the root window. + * + * X11 windows (clients) are stored in a tree. Each window + * can have children. A common example of this are modal + * dialog windows. + * + * This tree goes beyond a process. The root window is where + * the wallpaper is drawn. It span the combined geometry of + * every screen. It also persist when AwesomeWM is restarted. + * * @author Julien Danjou <julien@danjou.info> * @copyright 2008-2009 Julien Danjou * @coreclassmod root @@ -271,6 +280,7 @@ _string_to_key_code(const char *s) * coordinates relatives. * @param x In case of a motion event, this is the X coordinate. * @param y In case of a motion event, this is the Y coordinate. + * @noreturn * @staticfct fake_input */ static int @@ -339,7 +349,8 @@ luaA_root_fake_input(lua_State *L) * (the wallpaper). * * @property keys - * @param table + * @tparam[opt={}] table keys + * @tablerowtype A list of `awful.key` objects. * @see awful.key */ static int @@ -380,7 +391,8 @@ luaA_root_keys(lua_State *L) * known as root window). * * @property buttons - * @tparam[opt={}] table buttons The list of buttons. + * @tparam[opt={}] table buttons + * @tablerowtype A list of `awful.button` objects. * @see awful.button * * @usage @@ -427,7 +439,8 @@ luaA_root_buttons(lua_State *L) * *@DOC_cursor_c_COMMON@ * - * @param cursor_name A X cursor name. + * @tparam string cursor_name A X cursor name. + * @noreturn * @staticfct cursor */ static int @@ -453,7 +466,7 @@ luaA_root_cursor(lua_State *L) /** Get the drawins attached to a screen. * - * @return A table with all drawins. + * @treturn table A table with all drawins. * @staticfct drawins */ static int @@ -474,7 +487,8 @@ luaA_root_drawins(lua_State *L) * * @param pattern A cairo pattern as light userdata * @return A cairo surface or nothing. - * @staticfct wallpaper + * @deprecated wallpaper + * @see awful.wallpaper */ static int luaA_root_wallpaper(lua_State *L) @@ -504,7 +518,9 @@ luaA_root_wallpaper(lua_State *L) /** Get the content of the root window as a cairo surface. * * @property content - * @tparam surface A cairo surface with the root window content (aka the whole surface from every screens). + * @tparam raw_surface content A cairo surface with the root window content (aka the whole surface from every screens). + * @propertydefault This is the live content. Use `gears.surface(root.content)` to + * take a screenshot. * @see gears.surface */ static int @@ -515,7 +531,7 @@ luaA_root_get_content(lua_State *L) surface = cairo_xcb_surface_create(globalconf.connection, globalconf.screen->root, globalconf.default_visual, - globalconf.screen->width_in_pixels, + globalconf.screen->width_in_pixels, globalconf.screen->height_in_pixels); lua_pushlightuserdata(L, surface); @@ -525,8 +541,8 @@ luaA_root_get_content(lua_State *L) /** Get the size of the root window. * - * @return Width of the root window. - * @return height of the root window. + * @treturn integer Width of the root window. + * @treturn integer height of the root window. * @staticfct size */ static int @@ -539,8 +555,8 @@ luaA_root_size(lua_State *L) /** Get the physical size of the root window, in millimeter. * - * @return Width of the root window, in millimeters. - * @return height of the root window, in millimeters. + * @treturn integer Width of the root window, in millimeters. + * @treturn integer height of the root window, in millimeters. * @staticfct size_mm */ static int @@ -552,7 +568,7 @@ luaA_root_size_mm(lua_State *L) } /** Get the attached tags. - * @return A table with all tags. + * @treturn table A table with all tags. * @staticfct tags */ static int diff --git a/tests/examples/CMakeLists.txt b/tests/examples/CMakeLists.txt index 71befc532..8fe46ffc3 100644 --- a/tests/examples/CMakeLists.txt +++ b/tests/examples/CMakeLists.txt @@ -71,7 +71,9 @@ ${LUA_PATH_}") set(LUA_COV_RUNNER env -u LUA_PATH_5_1 -u LUA_PATH_5_2 -u LUA_PATH_5_3 "LUA_PATH=${LUA_PATH_}" "AWESOME_THEMES_PATH=${TOP_SOURCE_DIR}/themes/" "SOURCE_DIRECTORY=${TOP_SOURCE_DIR}" ${LUA_COV_RUNNER}) # The documentation images directory. +set(RAW_IMAGE_DIR "${CMAKE_BINARY_DIR}/raw_images") set(IMAGE_DIR "${CMAKE_BINARY_DIR}/doc/images") +file(MAKE_DIRECTORY "${RAW_IMAGE_DIR}") file(MAKE_DIRECTORY "${IMAGE_DIR}") # Escape potentially multiline strings to be part of the API doc. @@ -221,6 +223,7 @@ function(run_test test_path namespace escaped_content) # Get the file name without the extension. get_filename_component(${test_path} TEST_FILE_NAME NAME) + set(RAW_IMAGE_PATH "${RAW_IMAGE_DIR}/AUTOGEN${namespace}_${TEST_FILE_NAME}") set(IMAGE_PATH "${IMAGE_DIR}/AUTOGEN${namespace}_${TEST_FILE_NAME}") # Read the code and turn it into an usage example. @@ -231,12 +234,14 @@ function(run_test test_path namespace escaped_content) # Does the test generate an output image? if(tmp_content MATCHES "--DOC_GEN_IMAGE") + set(OUTPUT_RAW_IMAGE_PATH "${RAW_IMAGE_PATH}.svg") set(OUTPUT_IMAGE_PATH "${IMAGE_PATH}.svg") escape_string( - "![Usage example](../images/AUTOGEN${namespace}_${TEST_FILE_NAME}.svg)\n" + "\n" "${TEST_DOC_CONTENT}" TEST_DOC_CONTENT "" ) else() + set(OUTPUT_RAW_IMAGE_PATH "") set(OUTPUT_IMAGE_PATH "") endif() @@ -294,30 +299,43 @@ function(run_test test_path namespace escaped_content) STRING(REPLACE "/" "-" TARGET_NAME ${TARGET_NAME}) set(EXAMPLE_DOC_TEST_TARGETS ${EXAMPLE_DOC_TEST_TARGETS} ${TARGET_NAME} PARENT_SCOPE) - add_custom_target(${TARGET_NAME} - COMMAND "${TOP_SOURCE_DIR}/tests/examples/runner.sh" "${expected_output_path}" ${LUA_COV_RUNNER} ${template} ${test_path} ${IMAGE_PATH} + add_custom_target(${TARGET_NAME}_RAW + COMMAND "${TOP_SOURCE_DIR}/tests/examples/runner.sh" "${expected_output_path}" ${LUA_COV_RUNNER} ${template} ${test_path} ${RAW_IMAGE_PATH} VERBATIM) - if(NOT ${OUTPUT_IMAGE_PATH} STREQUAL "") - file(RELATIVE_PATH rel_output "${TOP_SOURCE_DIR}" "${OUTPUT_IMAGE_PATH}") + add_custom_target(${TARGET_NAME} + COMMAND "${TOP_SOURCE_DIR}/tests/examples/_postprocess.lua" ${OUTPUT_RAW_IMAGE_PATH} "${OUTPUT_IMAGE_PATH}" + VERBATIM + DEPENDS ${TARGET_NAME}_RAW "${TOP_SOURCE_DIR}/tests/examples/_postprocess.lua" + ) + + if(NOT ${OUTPUT_RAW_IMAGE_PATH} STREQUAL "") + file(RELATIVE_PATH rel_output "${TOP_SOURCE_DIR}" "${OUTPUT_RAW_IMAGE_PATH}") if(tmp_content MATCHES "--DOC_GEN_OUTPUT") add_custom_command( - COMMAND "${TOP_SOURCE_DIR}/tests/examples/runner.sh" "${expected_output_path}" ${LUA_COV_RUNNER} ${template} ${test_path} ${IMAGE_PATH} ${IGNORE_ERRORS} + COMMAND "${TOP_SOURCE_DIR}/tests/examples/runner.sh" "${expected_output_path}" ${LUA_COV_RUNNER} ${template} ${test_path} ${RAW_IMAGE_PATH} ${IGNORE_ERRORS} # COMMENT "Running ${rel_test_path} (via ${rel_template}, generating ${rel_output})" DEPENDS ${template} ${test_path} - OUTPUT ${OUTPUT_IMAGE_PATH} + OUTPUT ${OUTPUT_RAW_IMAGE_PATH} OUTPUT ${expected_output_path} VERBATIM) else() add_custom_command( - COMMAND "${TOP_SOURCE_DIR}/tests/examples/runner.sh" "${expected_output_path}" ${LUA_COV_RUNNER} ${template} ${test_path} ${IMAGE_PATH} ${IGNORE_ERRORS} + COMMAND "${TOP_SOURCE_DIR}/tests/examples/runner.sh" "${expected_output_path}" ${LUA_COV_RUNNER} ${template} ${test_path} ${RAW_IMAGE_PATH} ${IGNORE_ERRORS} # COMMENT "Running ${rel_test_path} (via ${rel_template}, generating ${rel_output})" DEPENDS ${template} ${test_path} - OUTPUT ${OUTPUT_IMAGE_PATH} + OUTPUT ${OUTPUT_RAW_IMAGE_PATH} VERBATIM) endif() - set(EXAMPLE_DOC_GENERATED_FILES ${OUTPUT_IMAGE_PATH} ${EXAMPLE_DOC_GENERATED_FILES} - PARENT_SCOPE) + + add_custom_command( + COMMAND "${TOP_SOURCE_DIR}/tests/examples/_postprocess.lua" ${OUTPUT_RAW_IMAGE_PATH} "${OUTPUT_IMAGE_PATH}" + DEPENDS ${template} ${test_path} ${OUTPUT_RAW_IMAGE_PATH} "${TOP_SOURCE_DIR}/tests/examples/_postprocess.lua" + OUTPUT "${OUTPUT_IMAGE_PATH}" + VERBATIM) + + set(EXAMPLE_DOC_GENERATED_FILES "${OUTPUT_IMAGE_PATH}" ${EXAMPLE_DOC_GENERATED_FILES} PARENT_SCOPE) + elseif(tmp_content MATCHES "--DOC_GEN_OUTPUT") add_custom_command( COMMAND "${TOP_SOURCE_DIR}/tests/examples/runner.sh" "${expected_output_path}" ${LUA_COV_RUNNER} ${template} ${test_path} "" ${IGNORE_ERRORS} @@ -338,7 +356,8 @@ file(GLOB_RECURSE test_files FOLLOW_SYMLINKS LIST_DIRECTORIES false # Find and run all test files. foreach(file ${test_files}) if ((NOT "${file}" MATCHES ".*/shims/.*") - AND (NOT "${file}" MATCHES ".*/template.lua")) + AND (NOT "${file}" MATCHES ".*/template.lua") + AND (NOT "${file}" MATCHES ".*/_.*[.]lua")) # Get the file name without the extension. get_filename_component(TEST_FILE_NAME ${file} NAME_WE) @@ -362,4 +381,11 @@ endforeach() add_custom_target(generate-examples DEPENDS ${EXAMPLE_DOC_GENERATED_FILES}) add_custom_target(check-examples DEPENDS ${EXAMPLE_DOC_TEST_TARGETS}) +# Some tests produce multiple files, find them and post-process them. +add_custom_target(DOC_EXAMPLES_PPOSTPROCESS_CLEANUP + COMMAND "${TOP_SOURCE_DIR}/tests/examples/_postprocess_cleanup.lua" ${RAW_IMAGE_DIR} ${IMAGE_DIR} "${TOP_SOURCE_DIR}/tests/examples/_postprocess.lua" + VERBATIM + DEPENDS ${BUILD_DIR}/doc/index.html +) + # vim: filetype=cmake:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80:foldmethod=marker diff --git a/tests/examples/_postprocess.lua b/tests/examples/_postprocess.lua new file mode 100755 index 000000000..009e19a4a --- /dev/null +++ b/tests/examples/_postprocess.lua @@ -0,0 +1,81 @@ +#!/usr/bin/env lua + +-- This script takes `.svg` file generated by Cairo or Inkscape and +-- replace hardcoded colors so they can be set using CSS or the +-- web browser itself. This makes the accessibility mode work and +-- allows themes to be created for the documentation. + +local input, output = ... + +if (not input) or (not output) then + io.stderr:write("_postprocess.lua require and \n") + io.stderr:write("Got input: "..tostring(input).."\n") + io.stderr:write("Got output: "..tostring(output).."\n") + os.exit(0) +end + +-- The second 24bit is just the 32 bit converted to #010001 and back. +local FOREGROUNDS = { + "rgb[(]0[.]5%%,0%%,0[.]5%%[)];", + "rgb[(]0[.]392157%%,0%%,0[.]392157%%[)];", + "#010001", +} + +local CLASSES = { + stroke = "svg_stroke", + fill = "svg_fill" +} + +local i, o = io.open(input, "r"), io.open(output, "w") + +if (not i) or (not o) then return end + +local line = i:read("*line") +local count + +while line do + -- Deduplicate and concatenate the classes. + local classes = {} + local token_found = {} + local class_str = {} + + for _, token in ipairs { "fill", "stroke" } do + + for _, color in ipairs(FOREGROUNDS) do + line, count = line:gsub(token .. ":" .. color, token .. ":currentcolor;") + + -- Add the CSS class. + if count > 0 then + classes[CLASSES[token]] = true + end + + line, count = line:gsub(token .. ":" .. color, token .. ":currentcolor;") + + -- Add the CSS class. + if count > 0 and not token_found[token] then + token_found[token] = true + table.insert(classes, CLASSES[token]) + end + end + end + + for class in pairs(classes) do + table.insert(class_str, class) + end + + if #class_str > 0 then + line = line:gsub(' style="', ' class="' .. table.concat(class_str, ",") .. '" style="') + end + + o:write(line .. "\n") + + -- Add the stylesheet. + if line:sub(1, 6) == "\n') + end + + -- Next line. + line = i:read("*line") +end + +o:close() diff --git a/tests/examples/_postprocess_cleanup.lua b/tests/examples/_postprocess_cleanup.lua new file mode 100755 index 000000000..90a2fae71 --- /dev/null +++ b/tests/examples/_postprocess_cleanup.lua @@ -0,0 +1,45 @@ +#!/usr/bin/env lua +-- This script locate and post process all "dangling" files CMake +-- didn't track. This allows the `tests/examples/` file to save more +-- than one output artifact. + +pcall(require, "luarocks.loader") + +local gio = require("lgi").Gio + +local name_attr = gio.FILE_ATTRIBUTE_STANDARD_NAME +local type_attr = gio.FILE_ATTRIBUTE_STANDARD_TYPE + +local raw_path, processed_path, script_path = ... + +local function list_svg(path) + local ret = {} + + local enumerator = gio.File.new_for_path(path):enumerate_children( + table.concat({name_attr, type_attr}, ",") , 0, nil, nil + ) + + for file in function() return enumerator:next_file() end do + local file_name = file:get_attribute_as_string(name_attr) + local file_type = file:get_file_type() + local match_ext = file_name:match("[.]svg$") + + if file_type == "REGULAR" and match_ext then + ret[file_name] = true + end + end + + return ret +end + +local raw_files, processed_files = list_svg(raw_path), list_svg(processed_path) + +for file in pairs(raw_files) do + if not processed_files[file] then + os.execute(table.concat({ + script_path, + raw_path .. "/" .. file, + processed_path .. "/" .. file + }, " ")) + end +end diff --git a/tests/examples/awful/mouse/coords.lua b/tests/examples/awful/mouse/coords.lua index 7b2ed7074..7f68e4222 100644 --- a/tests/examples/awful/mouse/coords.lua +++ b/tests/examples/awful/mouse/coords.lua @@ -1,4 +1,5 @@ --DOC_GEN_OUTPUT --DOC_GEN_IMAGE --DOC_HIDE +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {x = 175, width = 128, height = 96} --DOC_HIDE mouse.coords {x=175+60,y=60} --DOC_HIDE diff --git a/tests/examples/awful/notification/bg.lua b/tests/examples/awful/notification/bg.lua index 8762be5a7..591ff625f 100644 --- a/tests/examples/awful/notification/bg.lua +++ b/tests/examples/awful/notification/bg.lua @@ -28,4 +28,4 @@ local some_wibar = awful.wibar {position = "bottom", height = 48, visible = true } end -require("gears.timer").run_delayed_calls_now() +require("gears.timer").run_delayed_calls_now() --DOC_HIDE diff --git a/tests/examples/awful/notification/border_color.lua b/tests/examples/awful/notification/border_color.lua index d89affe11..28ef20f39 100644 --- a/tests/examples/awful/notification/border_color.lua +++ b/tests/examples/awful/notification/border_color.lua @@ -29,4 +29,4 @@ local some_wibar = awful.wibar {position = "bottom", height = 48, visible = true } end -require("gears.timer").run_delayed_calls_now() +require("gears.timer").run_delayed_calls_now() --DOC_HIDE diff --git a/tests/examples/awful/notification/fg.lua b/tests/examples/awful/notification/fg.lua index b3f461e85..ef521d7ce 100644 --- a/tests/examples/awful/notification/fg.lua +++ b/tests/examples/awful/notification/fg.lua @@ -29,4 +29,4 @@ local some_wibar = awful.wibar {position = "bottom", height = 48, visible = true } end -require("gears.timer").run_delayed_calls_now() +require("gears.timer").run_delayed_calls_now() --DOC_HIDE diff --git a/tests/examples/awful/notification/margin.lua b/tests/examples/awful/notification/margin.lua index ac0da4eac..49d2b54ea 100644 --- a/tests/examples/awful/notification/margin.lua +++ b/tests/examples/awful/notification/margin.lua @@ -37,4 +37,4 @@ local some_wibar = awful.wibar {position = "bottom", height = 48, visible = true } end -require("gears.timer").run_delayed_calls_now() +require("gears.timer").run_delayed_calls_now() --DOC_HIDE diff --git a/tests/examples/awful/notification/shape.lua b/tests/examples/awful/notification/shape.lua index 8b48110e2..f5b07d5ac 100644 --- a/tests/examples/awful/notification/shape.lua +++ b/tests/examples/awful/notification/shape.lua @@ -39,4 +39,4 @@ local some_wibar = awful.wibar {position = "bottom", height = 48, visible = true } end -require("gears.timer").run_delayed_calls_now() +require("gears.timer").run_delayed_calls_now() --DOC_HIDE diff --git a/tests/examples/awful/placement/aero_snap.lua b/tests/examples/awful/placement/aero_snap.lua index 6ab50a1a0..ec191f3ae 100644 --- a/tests/examples/awful/placement/aero_snap.lua +++ b/tests/examples/awful/placement/aero_snap.lua @@ -5,6 +5,10 @@ screen[1]._resize {width = 180, height = 120} --DOC_HIDE screen._add_screen {x = 190, y = 0, width = 180, height = 120} --DOC_HIDE screen._add_screen {x = 380, y = 0, width = 180, height = 120} --DOC_HIDE +for s in screen do + require("awful.tag").add("1", {screen=s, selected=true}) --DOC_HIDE +end + for _, pos in ipairs{"left", "right"} do local c1 = client.gen_fake {x = 80, y = 55, width=78, height=50} placement.align(client.focus, {position = pos, honor_workarea=true}) diff --git a/tests/examples/awful/placement/align.lua b/tests/examples/awful/placement/align.lua index 69e6b9cd6..ea0c3fda5 100644 --- a/tests/examples/awful/placement/align.lua +++ b/tests/examples/awful/placement/align.lua @@ -1,6 +1,7 @@ --DOC_HIDE_ALL --DOC_GEN_IMAGE local placement = require("awful.placement") +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {x= 50} for _, pos in ipairs{ "top_left", "top_right", "bottom_left", "bottom_right", @@ -14,6 +15,8 @@ end screen._add_screen {x = 70, y = 260 , width = 128, height = 96} screen._add_screen {x = 210, y = 260 , width = 128, height = 96} +require("awful.tag").add("1", {screen=screen[2], selected=true}) --DOC_HIDE +require("awful.tag").add("1", {screen=screen[3], selected=true}) --DOC_HIDE local c diff --git a/tests/examples/awful/placement/bottom.lua b/tests/examples/awful/placement/bottom.lua index c70ee710e..da7715da5 100644 --- a/tests/examples/awful/placement/bottom.lua +++ b/tests/examples/awful/placement/bottom.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.bottom --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE local c = client.gen_fake {x = 45, y = 35, width=40, height=30} --DOC_HIDE diff --git a/tests/examples/awful/placement/bottom_left.lua b/tests/examples/awful/placement/bottom_left.lua index 125a0e648..a5afb9dab 100644 --- a/tests/examples/awful/placement/bottom_left.lua +++ b/tests/examples/awful/placement/bottom_left.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.bottom_left --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE local c = client.gen_fake {x = 45, y = 35, width=40, height=30} --DOC_HIDE diff --git a/tests/examples/awful/placement/bottom_right.lua b/tests/examples/awful/placement/bottom_right.lua index b0d450821..5b95f2cef 100644 --- a/tests/examples/awful/placement/bottom_right.lua +++ b/tests/examples/awful/placement/bottom_right.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.bottom_right --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE local c = client.gen_fake {x = 45, y = 35, width=40, height=30} --DOC_HIDE diff --git a/tests/examples/awful/placement/center_horizontal.lua b/tests/examples/awful/placement/center_horizontal.lua index 1ab1eee22..c77f7f009 100644 --- a/tests/examples/awful/placement/center_horizontal.lua +++ b/tests/examples/awful/placement/center_horizontal.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.center_horizontal --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE local c = client.gen_fake {x = 45, y = 35, width=40, height=30} --DOC_HIDE diff --git a/tests/examples/awful/placement/center_vertical.lua b/tests/examples/awful/placement/center_vertical.lua index a867eab20..23658e9f7 100644 --- a/tests/examples/awful/placement/center_vertical.lua +++ b/tests/examples/awful/placement/center_vertical.lua @@ -2,8 +2,10 @@ -- Align a client to the vertical center of the parent area. --DOC_HEADER -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER +-- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.center_vertical --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE --[[local c = ]]client.gen_fake {x = 45, y = 35, width=40, height=30} --DOC_HIDE diff --git a/tests/examples/awful/placement/centered.lua b/tests/examples/awful/placement/centered.lua index c7af1052d..08523a424 100644 --- a/tests/examples/awful/placement/centered.lua +++ b/tests/examples/awful/placement/centered.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.centered --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE local c = client.gen_fake {x = 45, y = 35, width=40, height=30} --DOC_HIDE diff --git a/tests/examples/awful/placement/closest_mouse.lua b/tests/examples/awful/placement/closest_mouse.lua index 815b0568f..b0cd346a7 100644 --- a/tests/examples/awful/placement/closest_mouse.lua +++ b/tests/examples/awful/placement/closest_mouse.lua @@ -1,6 +1,7 @@ --DOC_GEN_OUTPUT --DOC_GEN_IMAGE --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE local c = client.gen_fake {x = 20, y = 20, width= 280, height=200, screen =screen[1]} --DOC_HIDE local bw = c.border_width --DOC_HIDE diff --git a/tests/examples/awful/placement/compose.lua b/tests/examples/awful/placement/compose.lua index 750afb29d..83b4cce01 100644 --- a/tests/examples/awful/placement/compose.lua +++ b/tests/examples/awful/placement/compose.lua @@ -1,4 +1,5 @@ --DOC_GEN_IMAGE --DOC_HIDE +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {x = 175, width = 128, height = 96} --DOC_NO_USAGE --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE local c = client.gen_fake {x = 220, y = 35, width=40, height=30} --DOC_HIDE diff --git a/tests/examples/awful/placement/compose2.lua b/tests/examples/awful/placement/compose2.lua index b0112684d..820bfafb4 100644 --- a/tests/examples/awful/placement/compose2.lua +++ b/tests/examples/awful/placement/compose2.lua @@ -1,4 +1,5 @@ --DOC_GEN_IMAGE --DOC_HIDE +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {x = 175, width = 128, height = 96} --DOC_NO_USAGE --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE local c = client.gen_fake {x = 220, y = 35, width=40, height=30} --DOC_HIDE diff --git a/tests/examples/awful/placement/left.lua b/tests/examples/awful/placement/left.lua index 3621383d7..6c9e29dfb 100644 --- a/tests/examples/awful/placement/left.lua +++ b/tests/examples/awful/placement/left.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.left --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE local c = client.gen_fake {x = 45, y = 35, width=40, height=30} --DOC_HIDE diff --git a/tests/examples/awful/placement/maximize.lua b/tests/examples/awful/placement/maximize.lua index aa40c2bf9..8466b0acd 100644 --- a/tests/examples/awful/placement/maximize.lua +++ b/tests/examples/awful/placement/maximize.lua @@ -2,6 +2,11 @@ screen[1]._resize {width = 128, height = 96} --DOC_HIDE screen._add_screen {x = 140, y = 0, width = 128, height = 96} --DOC_HIDE screen._add_screen {x = 280, y = 0, width = 128, height = 96} --DOC_HIDE + +for s in screen do --DOC_HIDE + require("awful.tag").add("1", {screen=s, selected=true}) --DOC_HIDE +end --DOC_HIDE + local placement = require("awful.placement") --DOC_HIDE for k, pos in ipairs{ --DOC_HIDE diff --git a/tests/examples/awful/placement/maximize_horizontally.lua b/tests/examples/awful/placement/maximize_horizontally.lua index de0f85b2a..4b7698c8d 100644 --- a/tests/examples/awful/placement/maximize_horizontally.lua +++ b/tests/examples/awful/placement/maximize_horizontally.lua @@ -2,8 +2,10 @@ -- Horizontally maximize the drawable in the parent area. --DOC_HEADER -- @tparam drawable d A drawable (like `client` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER +-- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.maximize_horizontally --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {width = 128, height = 96} --DOC_HIDE local placement = require("awful.placement") --DOC_HIDE diff --git a/tests/examples/awful/placement/maximize_vertically.lua b/tests/examples/awful/placement/maximize_vertically.lua index d3ef034bd..9bdef475f 100644 --- a/tests/examples/awful/placement/maximize_vertically.lua +++ b/tests/examples/awful/placement/maximize_vertically.lua @@ -2,8 +2,10 @@ -- Vetically maximize the drawable in the parent area. --DOC_HEADER -- @tparam drawable d A drawable (like `client` or `wibox`) --DOC_HEADER -- @tparam[opt={}] table args Other arguments") --DOC_HEADER +-- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.maximize_vertically --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {width = 128, height = 96} --DOC_HIDE local placement = require("awful.placement") --DOC_HIDE diff --git a/tests/examples/awful/placement/next_to.lua b/tests/examples/awful/placement/next_to.lua index ccaa893e1..833fccecb 100644 --- a/tests/examples/awful/placement/next_to.lua +++ b/tests/examples/awful/placement/next_to.lua @@ -1,5 +1,7 @@ --DOC_GEN_IMAGE --DOC_HIDE local awful = { placement = require("awful.placement") }--DOC_HIDE + +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {x= 0, width = 640, height=200} --DOC_HIDE local parent_client = client.gen_fake {x = 0, y = 0, width=350, height=70} --DOC_HIDE diff --git a/tests/examples/awful/placement/next_to_mouse.lua b/tests/examples/awful/placement/next_to_mouse.lua index 2e34e0ade..c7328f302 100644 --- a/tests/examples/awful/placement/next_to_mouse.lua +++ b/tests/examples/awful/placement/next_to_mouse.lua @@ -1,4 +1,5 @@ --DOC_GEN_IMAGE --DOC_HIDE +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE client.gen_fake {x = 10, y = 10, width=40, height=30} --DOC_HIDE diff --git a/tests/examples/awful/placement/no_offscreen.lua b/tests/examples/awful/placement/no_offscreen.lua index 4b4054ef0..95246b3d6 100644 --- a/tests/examples/awful/placement/no_offscreen.lua +++ b/tests/examples/awful/placement/no_offscreen.lua @@ -1,6 +1,8 @@ --DOC_GEN_OUTPUT --DOC_GEN_IMAGE --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE + --DOC_HIDE no_offscreen is auto-called when startup is true, avoid this. awesome.startup = false -- luacheck: globals awesome.startup --DOC_HIDE diff --git a/tests/examples/awful/placement/no_overlap.lua b/tests/examples/awful/placement/no_overlap.lua index d0fe9b1f2..f295202f7 100644 --- a/tests/examples/awful/placement/no_overlap.lua +++ b/tests/examples/awful/placement/no_overlap.lua @@ -1,4 +1,5 @@ --DOC_GEN_IMAGE --DOC_HIDE +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {width = 128, height = 96} --DOC_HIDE screen._add_screen {x = 140, y = 0 , width = 128, height = 96} --DOC_HIDE screen._add_screen {x = 0 , y = 110, width = 128, height = 96} --DOC_HIDE diff --git a/tests/examples/awful/placement/resize_to_mouse.lua b/tests/examples/awful/placement/resize_to_mouse.lua index 01cf64166..fb13b06aa 100644 --- a/tests/examples/awful/placement/resize_to_mouse.lua +++ b/tests/examples/awful/placement/resize_to_mouse.lua @@ -2,9 +2,12 @@ --DOC_GEN_IMAGE local awful = {placement = require("awful.placement")} local unpack = unpack or table.unpack -- luacheck: globals unpack (compatibility with Lua 5.1) - screen._setup_grid(64, 48, {4, 4, 4, 4}, {workarea_sides=0}) +for s in screen do + require("awful.tag").add("1", {screen=s, selected=true}) --DOC_HIDE +end + local function test_touch_mouse(c) local coords = mouse.coords() diff --git a/tests/examples/awful/placement/right.lua b/tests/examples/awful/placement/right.lua index b1f63b66a..c6227532c 100644 --- a/tests/examples/awful/placement/right.lua +++ b/tests/examples/awful/placement/right.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.right --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE local c = client.gen_fake {x = 45, y = 35, width=40, height=30} --DOC_HIDE diff --git a/tests/examples/awful/placement/skip_fullscreen-no_fullscreen.lua b/tests/examples/awful/placement/skip_fullscreen-no_fullscreen.lua index 7207f4600..060cbcf12 100644 --- a/tests/examples/awful/placement/skip_fullscreen-no_fullscreen.lua +++ b/tests/examples/awful/placement/skip_fullscreen-no_fullscreen.lua @@ -1,6 +1,8 @@ --DOC_GEN_OUTPUT --DOC_GEN_IMAGE --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE + --DOC_HIDE no_offscreen is auto-called when startup is true, avoid this. awesome.startup = false -- luacheck: globals awesome.startup --DOC_HIDE diff --git a/tests/examples/awful/placement/skip_fullscreen.lua b/tests/examples/awful/placement/skip_fullscreen.lua index 2e1e749e8..b3d5ee532 100644 --- a/tests/examples/awful/placement/skip_fullscreen.lua +++ b/tests/examples/awful/placement/skip_fullscreen.lua @@ -1,5 +1,6 @@ --DOC_GEN_OUTPUT --DOC_GEN_IMAGE --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE --DOC_HIDE no_offscreen is auto-called when startup is true, avoid this. awesome.startup = false -- luacheck: globals awesome.startup --DOC_HIDE diff --git a/tests/examples/awful/placement/stretch.lua b/tests/examples/awful/placement/stretch.lua index 696981140..cd1024852 100644 --- a/tests/examples/awful/placement/stretch.lua +++ b/tests/examples/awful/placement/stretch.lua @@ -4,6 +4,9 @@ screen[1]._resize {width = 128, height = 96} screen._add_screen {x = 140, y = 0 , width = 128, height = 96} screen._add_screen {x = 0 , y = 110, width = 128, height = 96} screen._add_screen {x = 140, y = 110, width = 128, height = 96} +for s in screen do + require("awful.tag").add("1", {screen=s, selected=true}) +end local placement = require("awful.placement") for k, pos in ipairs{ diff --git a/tests/examples/awful/placement/stretch_down.lua b/tests/examples/awful/placement/stretch_down.lua index e22caf5d8..2c39c7dbd 100644 --- a/tests/examples/awful/placement/stretch_down.lua +++ b/tests/examples/awful/placement/stretch_down.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.stretch_down --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {width = 128, height = 96} --DOC_HIDE local placement = require("awful.placement") --DOC_HIDE diff --git a/tests/examples/awful/placement/stretch_left.lua b/tests/examples/awful/placement/stretch_left.lua index db81f765d..e043abe6d 100644 --- a/tests/examples/awful/placement/stretch_left.lua +++ b/tests/examples/awful/placement/stretch_left.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.stretch_left --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {width = 128, height = 96} --DOC_HIDE local placement = require("awful.placement") --DOC_HIDE diff --git a/tests/examples/awful/placement/stretch_right.lua b/tests/examples/awful/placement/stretch_right.lua index d217a781d..9fe5ac579 100644 --- a/tests/examples/awful/placement/stretch_right.lua +++ b/tests/examples/awful/placement/stretch_right.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.stretch_right --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {width = 128, height = 96} --DOC_HIDE local placement = require("awful.placement") --DOC_HIDE diff --git a/tests/examples/awful/placement/stretch_up.lua b/tests/examples/awful/placement/stretch_up.lua index 67a2bea75..d569f6ed7 100644 --- a/tests/examples/awful/placement/stretch_up.lua +++ b/tests/examples/awful/placement/stretch_up.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.stretch_up --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {width = 128, height = 96} --DOC_HIDE local placement = require("awful.placement") --DOC_HIDE diff --git a/tests/examples/awful/placement/top.lua b/tests/examples/awful/placement/top.lua index 60fc17006..756c26162 100644 --- a/tests/examples/awful/placement/top.lua +++ b/tests/examples/awful/placement/top.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.top --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE local c = client.gen_fake {x = 45, y = 35, width=40, height=30} --DOC_HIDE diff --git a/tests/examples/awful/placement/top_left.lua b/tests/examples/awful/placement/top_left.lua index 339bd9e10..fda50a9dd 100644 --- a/tests/examples/awful/placement/top_left.lua +++ b/tests/examples/awful/placement/top_left.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.top_left --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE local c = client.gen_fake {x = 45, y = 35, width=40, height=30} --DOC_HIDE diff --git a/tests/examples/awful/placement/top_right.lua b/tests/examples/awful/placement/top_right.lua index 2df7c70a2..7d5b25296 100644 --- a/tests/examples/awful/placement/top_right.lua +++ b/tests/examples/awful/placement/top_right.lua @@ -5,6 +5,7 @@ -- @treturn table The new geometry --DOC_HEADER -- @staticfct awful.placement.top_right --DOC_HEADER +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE local c = client.gen_fake {x = 45, y = 35, width=40, height=30} --DOC_HIDE diff --git a/tests/examples/awful/placement/under_mouse.lua b/tests/examples/awful/placement/under_mouse.lua index 13c034047..53efa7cae 100644 --- a/tests/examples/awful/placement/under_mouse.lua +++ b/tests/examples/awful/placement/under_mouse.lua @@ -1,4 +1,5 @@ --DOC_GEN_IMAGE --DOC_HIDE +require("awful.tag").add("1", {screen=screen[1], selected=true}) --DOC_HIDE screen[1]._resize {width = 128, height = 96} --DOC_HIDE local awful = {placement = require("awful.placement")} --DOC_HIDE client.gen_fake {x = 10, y = 10, width=40, height=30} --DOC_HIDE diff --git a/tests/examples/awful/popup/defaultconfig.lua b/tests/examples/awful/popup/defaultconfig.lua index be28439ad..b6c7ba176 100644 --- a/tests/examples/awful/popup/defaultconfig.lua +++ b/tests/examples/awful/popup/defaultconfig.lua @@ -9,6 +9,7 @@ local naughty = require("naughty") local wibox = require("wibox") local beautiful = require("beautiful") --DOC_HIDE local look = require("_default_look") +local color = require("gears.color") screen[1]._resize {width = 640, height = 340} @@ -75,7 +76,7 @@ local function create_line(x1, y1, x2, y2) return x2-x1+6, y2-y1+6 end, draw = function(_, _, cr) - cr:set_source_rgb(0,0,0) + cr:set_source(color(beautiful.fg_normal)) cr:set_line_width(1) cr:arc(1.5, 1.5, 1.5, 0, math.pi*2) cr:arc(x2-x1+1.5, y2-y1+1.5, 1.5, 0, math.pi*2) diff --git a/tests/examples/awful/popup/wiboxtypes.lua b/tests/examples/awful/popup/wiboxtypes.lua index ccbef7ba6..b36e1604e 100644 --- a/tests/examples/awful/popup/wiboxtypes.lua +++ b/tests/examples/awful/popup/wiboxtypes.lua @@ -10,6 +10,7 @@ local wibox = require("wibox") local beautiful = require("beautiful") --DOC_HIDE local assets = require("beautiful.theme_assets") local look = require("_default_look") +local color = require("gears.color") screen[1]._resize {width = 640, height = 480} @@ -233,7 +234,7 @@ local function create_line(x1, y1, x2, y2) return x2-x1+6, y2-y1+6 end, draw = function(_, _, cr) - cr:set_source_rgb(0,0,0) + cr:set_source(color(beautiful.fg_normal)) cr:set_line_width(1) cr:arc(1.5, 1.5, 1.5, 0, math.pi*2) cr:arc(x2-x1+1.5, y2-y1+1.5, 1.5, 0, math.pi*2) diff --git a/tests/examples/awful/titlebar/constructor.lua b/tests/examples/awful/titlebar/constructor.lua index a35f0adbd..687bf97c2 100644 --- a/tests/examples/awful/titlebar/constructor.lua +++ b/tests/examples/awful/titlebar/constructor.lua @@ -5,6 +5,8 @@ local awful = { titlebar = require("awful.titlebar"), local beautiful = require("beautiful") local wibox = require("wibox") +require("awful.tag").add("1", {screen=screen[1], selected = true}) + screen[1]._resize { width = 646, height = 182 } local c @@ -38,27 +40,31 @@ c = clients[1] setup( --DOC_HIDE_END - -- Create default titlebar + -- Create default titlebar. awful.titlebar(c) +--DOC_NEWLINE --DOC_HIDE_START ) + c = clients[2] setup( --DOC_HIDE_END - -- Create titlebar on the client's bottom edge + -- Create titlebar on the client's bottom edge. awful.titlebar(c, { position = "bottom" }) --DOC_HIDE_START ) + c = clients[3] setup( --DOC_HIDE_END +--DOC_NEWLINE - -- Create titlebar with inverted colors + -- Create titlebar with inverted colors. awful.titlebar(c, { bg_normal = beautiful.fg_normal, fg_normal = beautiful.bg_normal }) --DOC_HIDE_START diff --git a/tests/examples/awful/titlebar/default.lua b/tests/examples/awful/titlebar/default.lua index 853d04ae5..1ca78a857 100644 --- a/tests/examples/awful/titlebar/default.lua +++ b/tests/examples/awful/titlebar/default.lua @@ -1,14 +1,19 @@ ---DOC_GEN_IMAGE --DOC_HIDE +--DOC_GEN_IMAGE --DOC_NO_USAGE -local place = require("awful.placement") --DOC_HIDE -local awful = { titlebar = require("awful.titlebar"), --DOC_HIDE - button = require("awful.button"), --DOC_HIDE - } --DOC_HIDE -local wibox = require("wibox") --DOC_HIDE -local gears = {table = require("gears.table")} --DOC_HIDE +--DOC_HIDE_START +local place = require("awful.placement") +local awful = { titlebar = require("awful.titlebar"), + button = require("awful.button"), + tag = require("awful.tag"), + } +local wibox = require("wibox") +local gears = {table = require("gears.table")} -local c = client.gen_fake {hide_first=true} --DOC_HIDE -place.maximize(c, {honor_padding=true, honor_workarea=true}) --DOC_HIDE +awful.tag.add("1", {screen=screen[1], selected = true}) + +local c = client.gen_fake {hide_first=true} +place.maximize(c, {honor_padding=true, honor_workarea=true}) +--DOC_HIDE_END -- Create a titlebar for the client. -- By default, `ruled.client` will create one, but all it does is to call this @@ -19,6 +24,8 @@ place.maximize(c, {honor_padding=true, honor_workarea=true}) --DOC_HIDE bg_normal = "#ff0000", }) + --DOC_NEWLINE + -- buttons for the titlebar local buttons = gears.table.join( awful.button({ }, 1, function() @@ -33,7 +40,9 @@ place.maximize(c, {honor_padding=true, honor_workarea=true}) --DOC_HIDE end) ) - top_titlebar : setup { + --DOC_NEWLINE + + top_titlebar.widget = { { -- Left awful.titlebar.widget.iconwidget(c), buttons = buttons, @@ -59,3 +68,4 @@ place.maximize(c, {honor_padding=true, honor_workarea=true}) --DOC_HIDE } --DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 + diff --git a/tests/examples/awful/titlebar/defaulttitlebar.lua b/tests/examples/awful/titlebar/defaulttitlebar.lua index 3e34f0b94..2db72c9c4 100644 --- a/tests/examples/awful/titlebar/defaulttitlebar.lua +++ b/tests/examples/awful/titlebar/defaulttitlebar.lua @@ -7,6 +7,7 @@ local gears = require("gears") local wibox = require("wibox") local beautiful = require("beautiful") --DOC_HIDE local look = require("_default_look") +local color = require("gears.color") local offset = 0 @@ -108,7 +109,7 @@ local function create_line(x1, y1, x2, y2) return x2-x1+6, y2-y1+6 end, draw = function(_, _, cr) - cr:set_source_rgb(0,0,0) + cr:set_source(color(beautiful.fg_normal)) cr:set_line_width(1) cr:arc(1.5, 1.5, 1.5, 0, math.pi*2) cr:arc(x2-x1+1.5, y2-y1+1.5, 1.5, 0, math.pi*2) diff --git a/tests/examples/awful/wibar/defaultwibar.lua b/tests/examples/awful/wibar/defaultwibar.lua index 309714e74..b4a90af89 100644 --- a/tests/examples/awful/wibar/defaultwibar.lua +++ b/tests/examples/awful/wibar/defaultwibar.lua @@ -7,6 +7,7 @@ local gears = require("gears") local wibox = require("wibox") local beautiful = require("beautiful") --DOC_HIDE local look = require("_default_look") +local color = require("gears.color") local offset = 60 @@ -99,7 +100,7 @@ local function create_line(x1, y1, x2, y2) return x2-x1+6, y2-y1+6 end, draw = function(_, _, cr) - cr:set_source_rgb(0,0,0) + cr:set_source(color(beautiful.fg_normal)) cr:set_line_width(1) cr:arc(1.5, 1.5, 1.5, 0, math.pi*2) cr:arc(x2-x1+1.5, y2-y1+1.5, 1.5, 0, math.pi*2) diff --git a/tests/examples/screen/template.lua b/tests/examples/screen/template.lua index 8fb87009c..98fcfa52c 100644 --- a/tests/examples/screen/template.lua +++ b/tests/examples/screen/template.lua @@ -10,6 +10,7 @@ local Pango = require("lgi").Pango local PangoCairo = require("lgi").PangoCairo local color = require("gears.color") local aclient = require("awful.client") +local beautiful = require("beautiful") -- Let the test request a size and file format local args = loadfile(file_path)() or 10 @@ -79,11 +80,11 @@ local function stripe_pat(col, angle, line_width, spacing) end local colors = { - geometry = "#000000", + geometry = beautiful.fg_normal, workarea = "#0000ff", tiling_area = "#ff0000", padding_area = "#ff0000", - wibar = "#000000", + wibar = beautiful.fg_normal, tiling_client = "#ff0000", gaps = "#9900ff", } @@ -94,12 +95,12 @@ local function draw_area(_, rect, name, offset, highlight) if highlight then cr:save() - cr:set_source(stripe_pat(colors[name].."22", nil, 1, 3)) + cr:set_source(stripe_pat(color.change_opacity(colors[name], 0.0863), nil, 1, 3)) cr:fill_preserve() cr:restore() end - cr:set_source(color(colors[name].."44")) + cr:set_source(color.change_opacity(colors[name], 0.1725)) cr:stroke() end @@ -115,16 +116,16 @@ local function draw_bounding_area(_, rect, hole, name, offset) end local function draw_solid_area(_, rect, name, offset, alpha) - alpha = alpha or "59" -- Defaults to 35% + alpha = alpha or 0.2314 -- Defaults to 35% local x, y = rect.x*factor+offset, rect.y*factor+offset cr:rectangle(x, y, rect.width*factor, rect.height*factor) cr:save() - cr:set_source(color.create_solid_pattern(colors[name] .. alpha)) + cr:set_source(color.change_opacity(colors[name], alpha)) cr:fill_preserve() cr:restore() - cr:set_source(color(colors[name].."44")) + cr:set_source(color.change_opacity(colors[name], 0.0863)) cr:stroke() end @@ -141,7 +142,7 @@ local function write_on_area_middle(rect, text, offset) local _, logical = playout:get_pixel_extents() local dx = (rect.x*factor+offset) + (rect.width*factor - logical.width) / 2 local dy = (rect.y*factor+offset) + (rect.height*factor - logical.height) / 2 - cr:set_source_rgb(0, 0, 0) + cr:set_source(beautiful.fg_normal) cr:move_to(dx, dy) cr:show_layout(playout) end @@ -265,7 +266,7 @@ end local function draw_vruler(s, dx2, sx, ruler, layer) local pad = 5+(layer-1)*dx2 - cr:set_source(color(ruler.color or (colors[ruler.label].."66"))) + cr:set_source(color(ruler.color or (color.change_opacity(colors[ruler.label], 0.2588)))) cr:move_to(sx+layer*dx2, ruler.y*factor) cr:line_to(sx+layer*dx2, ruler.y*factor+ruler.height*factor) cr:stroke() @@ -291,7 +292,7 @@ end local function draw_hruler(s, dx2, sy, ruler, layer) local pad = 10+(layer-1)*(dx2 or 0) - cr:set_source(color(ruler.color or (colors[ruler.label].."66"))) + cr:set_source(color(ruler.color or (color.change_opacity(colors[ruler.label], 0.2588)))) cr:move_to(ruler.x*factor, sy+pad) cr:line_to(ruler.x*factor+ruler.width*factor, sy+pad) cr:stroke() @@ -426,7 +427,7 @@ local function draw_gaps(s) x = offset.x+hgap[1]+tr_x, width = math.ceil(hgap[2]-hgap[1]), label = nil, - color = colors.gaps.."66", + color = color.change_opacity(colors.gaps, 0.2588), align = true }, 1 @@ -442,7 +443,7 @@ local function draw_gaps(s) y = offset.y+vgap[1]+tr_y, height = math.ceil(vgap[2]-vgap[1]), label = nil, - color = colors.gaps.."66", + color = color.change_opacity(colors.gaps, 0.2588), align = true }, 1 @@ -475,7 +476,12 @@ local function draw_struts(s) s, s.geometry.y*SCALE_FACTOR, get_text_height(), - {x = s.geometry.x+tr_x*2, width = left, color = colors.gaps.."66", align = true}, + { + x = s.geometry.x+tr_x*2, + width = left, + color = color.change_opacity(colors.gaps, 0.2588), + align = true + }, 1 ) end @@ -485,7 +491,12 @@ local function draw_struts(s) s, get_text_height()*1.5, s.geometry.x*SCALE_FACTOR, - {y=s.geometry.y+tr_y*(1/factor), height = top, color = colors.gaps.."66", align = true}, + { + y = s.geometry.y+tr_y*(1/factor), + height = top, + color = color.change_opacity(colors.gaps, 0.2588), + align = true + }, 1 ) end @@ -495,7 +506,12 @@ local function draw_struts(s) s, s.geometry.y*SCALE_FACTOR, get_text_height(), - {x = s.geometry.x, width = left, color = colors.gaps.."66", align = true}, + { + x = s.geometry.x, + width = left, + color = color.change_opacity(colors.gaps, 0.2588), + align = true + }, 1 ) end @@ -508,7 +524,7 @@ local function draw_struts(s) { y = s.geometry.y+tr_y*(1/factor)+s.geometry.height - bottom, height = bottom, - color = colors.gaps.."66", + color = color.change_opacity(colors.gaps, 0.2588), align = true }, 1 @@ -528,8 +544,19 @@ local function draw_mwfact(s) local w1, w2 = math.ceil(width*mwfact), math.ceil(width*(1-mwfact)) - draw_hruler(s, offset, get_text_height(), {x=offset,width=w1,color = colors.gaps.."66", align=true}, 1) - draw_hruler(s, offset, get_text_height(), {x=offset+w1,width=w2,color = colors.gaps.."66", align=true}, 1) + draw_hruler(s, offset, get_text_height(), { + x = offset, + width = w1, + color = color.change_opacity(colors.gaps, 0.2588), + align = true + }, 1) + + draw_hruler(s, offset, get_text_height(), { + x = offset+w1, + width = w2, + color = color.change_opacity(colors.gaps, 0.2588), + align = true + }, 1) cr:translate(tr_x, tr_y) end @@ -560,7 +587,7 @@ local function draw_wfact(s) { y = math.floor(offset), height =math.ceil( (height/sum) * windowfacts[1][i]), - color = colors.gaps.."66", + color = color.change_opacity(colors.gaps, 0.2588), align = true, }, 1 @@ -634,7 +661,7 @@ end -- end local function draw_info(s) - cr:set_source_rgb(0, 0, 0) + cr:set_source(beautiful.fg_normal) local pctx = PangoCairo.font_map_get_default():create_context() local playout2 = Pango.Layout.new(pctx) @@ -792,7 +819,7 @@ for k=1, screen.count() do height = c.height + 2*gap, } - draw_client(s, proxy, 'gaps', (k-1)*10, nil, "11") + draw_client(s, proxy, 'gaps', (k-1)*10, nil, 0.0431) elseif args.draw_client_snap and c.floating then local proxy = { x = c.x - sd, @@ -801,7 +828,7 @@ for k=1, screen.count() do height = c.height + 2*sd, } - draw_client(s, proxy, 'gaps', (k-1)*10, nil, "11") + draw_client(s, proxy, 'gaps', (k-1)*10, nil, 0.0431) end draw_client(s, c, 'tiling_client', (k-1)*10, label) diff --git a/tests/examples/sequences/client/tasklist_custom_filter1.lua b/tests/examples/sequences/client/tasklist_custom_filter1.lua new file mode 100644 index 000000000..d9bd0ecc9 --- /dev/null +++ b/tests/examples/sequences/client/tasklist_custom_filter1.lua @@ -0,0 +1,96 @@ + --DOC_GEN_IMAGE --DOC_HIDE_START --DOC_NO_USAGE +local module = ... +require("ruled.client") +local awful = { + tag = require("awful.tag"), + widget = { + tasklist = require("awful.widget.tasklist") + }, + button = require("awful.button"), + layout = require("awful.layout") +} +require("awful.ewmh") +local wibox = require("wibox") +screen[1]:fake_resize(0, 0, 1024, 640) +screen.fake_add(1050, 0, 1024, 640).outputs = {["eVGA1"] = {mm_height=50, mm_width=80 }} --DOC_HIDE + +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.suit.corner.nw) +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[2], awful.layout.suit.tile.left) + + +local s = screen[1] +--DOC_HIDE_END + + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + base_layout = wibox.widget { + spacing = 2, + layout = wibox.layout.fixed.horizontal, + }, + } + + --DOC_NEWLINE + --DOC_HIDE_START + +local _tl = tasklist + +function awful.spawn(name, args) + client.gen_fake{class = name, name = name, x = 2094, y=10, width = 60, height =50, screen=args.screen} +end + + +--DOC_NEWLINE + +module.add_event("Spawn some clients.", function() + --DOC_HIDE_END + + -- Spawn 5 clients on screen 1. + for i= 1, 5 do + awful.spawn("Client #"..i, {screen = screen[1]}) + end + + --DOC_NEWLINE + + -- Spawn 3 clients on screen 2. + for i=1, 3 do + awful.spawn("Client #"..(5+i), {screen = screen[2]}) + end + + --DOC_NEWLINE + --DOC_HIDE_START + + client.get()[2]:activate {} + client.get()[2].color = "#ff777733" +end) + +--DOC_NEWLINE +module.display_tags() +module.display_widget(_tl, nil, 22) + +module.add_event("Set the filter to allscreen.", function() + --DOC_HIDE_END + -- Set the filter to allscreen. + tasklist.filter = awful.widget.tasklist.filter.allscreen + --DOC_NEWLINE + --DOC_HIDE_START +end) + +module.display_widget(_tl, nil, 22) + +module.add_event("Set a custom filter function.", function() + --DOC_HIDE_END + -- Create a pointless demo filter to only have clients + -- with off numbers in the name. Because... example! + tasklist.filter = function(c, screen) -- luacheck: no unused args + return c.name:match("[13579]") and c or nil + end + --DOC_HIDE_START +end) + +module.display_widget(_tl, nil, 22) + +module.execute { display_screen = true , display_clients = true, + display_label = false, display_client_name = true, + display_mouse = true , +} diff --git a/tests/examples/sequences/client/tasklist_custom_source1.lua b/tests/examples/sequences/client/tasklist_custom_source1.lua new file mode 100644 index 000000000..29dfa161d --- /dev/null +++ b/tests/examples/sequences/client/tasklist_custom_source1.lua @@ -0,0 +1,102 @@ + --DOC_GEN_IMAGE --DOC_HIDE_START --DOC_NO_USAGE +local module = ... +require("ruled.client") +local awful = { + tag = require("awful.tag"), + widget = { + tasklist = require("awful.widget.tasklist") + }, + button = require("awful.button"), + layout = require("awful.layout") +} +require("awful.ewmh") +local wibox = require("wibox") +screen[1]:fake_resize(0, 0, 1024, 640) + +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.suit.corner.nw) + +local s = screen[1] +--DOC_HIDE_END + + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + base_layout = wibox.widget { + spacing = 2, + layout = wibox.layout.fixed.horizontal, + }, + } + + --DOC_NEWLINE + --DOC_HIDE_START + +local _tl = tasklist + +function awful.spawn(name, args) + client.gen_fake{class = name, name = name, x = 2094, y=10, width = 600, height =300, screen=args.screen} +end + + +--DOC_NEWLINE + +module.add_event("Spawn some clients.", function() + --DOC_HIDE_END + + -- Spawn 5 clients on screen 1. + for i= 1, 5 do + awful.spawn("Client #"..i, {screen = screen[1]}) + end + + --DOC_NEWLINE + + -- Make 2 clients floating. + client.get()[2].floating = true + client.get()[4].floating = true + + --DOC_NEWLINE + + --DOC_HIDE_START + client.get()[2]:geometry { + x = 150, y = 100, + } + client.get()[4]:geometry { + x = 300, y = 200, + } + + + --DOC_NEWLINE + --DOC_HIDE_START + + client.get()[2]:activate {} + client.get()[2].color = "#ff777733" +end) + +--DOC_NEWLINE +module.display_tags() +module.display_widget(_tl, nil, 22) + +module.add_event("Set a custom source function.", function() + --DOC_HIDE_END + -- Only select the floating clients for the tasklist screen. + tasklist.source = function(screen) + local ret = {} + + --DOC_NEWLINE + for _, c in ipairs(screen.clients) do + if c.floating then + table.insert(ret, c) + end + end + --DOC_NEWLINE + + return ret + end + --DOC_HIDE_START +end) + +module.display_widget(_tl, nil, 22) + +module.execute { display_screen = true , display_clients = true, + display_label = false, display_client_name = true, + display_mouse = true , +} diff --git a/tests/examples/sequences/client/tasklist_filter_allscreen1.lua b/tests/examples/sequences/client/tasklist_filter_allscreen1.lua new file mode 100644 index 000000000..93400b192 --- /dev/null +++ b/tests/examples/sequences/client/tasklist_filter_allscreen1.lua @@ -0,0 +1,82 @@ + --DOC_GEN_IMAGE --DOC_HIDE_START --DOC_NO_USAGE +local module = ... +require("ruled.client") +local awful = { + tag = require("awful.tag"), + widget = { + tasklist = require("awful.widget.tasklist") + }, + button = require("awful.button"), + layout = require("awful.layout") +} +require("awful.ewmh") +local wibox = require("wibox") +screen[1]:fake_resize(0, 0, 1024, 640) +screen.fake_add(1050, 0, 1024, 640).outputs = {["eVGA1"] = {mm_height=50, mm_width=80 }} --DOC_HIDE + +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.suit.corner.nw) +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[2], awful.layout.suit.tile.left) + +local s = screen[1] +--DOC_HIDE_END + + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + base_layout = wibox.widget { + spacing = 2, + layout = wibox.layout.fixed.horizontal, + }, + } + + --DOC_NEWLINE + --DOC_HIDE_START + +local _tl = tasklist + +function awful.spawn(name, args) + client.gen_fake{class = name, name = name, x = 2094, y=10, width = 60, height =50, screen=args.screen} +end + +--DOC_NEWLINE + +module.add_event("Spawn some clients.", function() + --DOC_HIDE_END + + -- Spawn 5 clients on screen 1. + for i= 1, 5 do + awful.spawn("Client #"..i, {screen = screen[1]}) + end + + --DOC_NEWLINE + + -- Spawn 3 clients on screen 2. + for i=1, 3 do + awful.spawn("Client #"..(5+i), {screen = screen[2]}) + end + + --DOC_NEWLINE + --DOC_HIDE_START + + client.get()[2]:activate {} + client.get()[2].color = "#ff777733" +end) + +--DOC_NEWLINE +module.display_tags() +module.display_widget(_tl, nil, 22) + +module.add_event("Set the filter to allscreen.", function() + --DOC_HIDE_END + -- Set the filter to allscreen. + tasklist.filter = awful.widget.tasklist.filter.allscreen + --DOC_NEWLINE + --DOC_HIDE_START +end) + +module.display_widget(_tl, nil, 22) + +module.execute { display_screen = true , display_clients = true, + display_label = false, display_client_name = true, + display_mouse = true , +} diff --git a/tests/examples/sequences/client/tasklist_filter_alltags1.lua b/tests/examples/sequences/client/tasklist_filter_alltags1.lua new file mode 100644 index 000000000..2823129f4 --- /dev/null +++ b/tests/examples/sequences/client/tasklist_filter_alltags1.lua @@ -0,0 +1,79 @@ + --DOC_GEN_IMAGE --DOC_HIDE_START --DOC_NO_USAGE +local module = ... +require("ruled.client") +local awful = { + tag = require("awful.tag"), + widget = { + tasklist = require("awful.widget.tasklist") + }, + button = require("awful.button"), + layout = require("awful.layout") +} +require("awful.ewmh") +local wibox = require("wibox") + +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.suit.corner.nw) + +local s = screen[1] +--DOC_HIDE_END + + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + base_layout = wibox.widget { + spacing = 2, + layout = wibox.layout.fixed.horizontal, + }, + } + + --DOC_NEWLINE + --DOC_HIDE_START + +local _tl = tasklist + +function awful.spawn(name, args) + client.gen_fake{class = name, name = name, x = 2094, y=10, width = 60, height =50, tags=args.tags} +end + +--DOC_NEWLINE + +module.add_event("Spawn some clients.", function() + --DOC_HIDE_END + + -- Spawn 5 clients on screen 1. + for i= 1, 5 do + awful.spawn("Client #"..i, {tags = {screen[1].tags[1]}}) + end + + --DOC_NEWLINE + + -- Spawn 3 clients on screen 2. + for i=1, 3 do + awful.spawn("Client #"..(5+i), {tags = {screen[1].tags[2]}}) + end + + --DOC_NEWLINE + --DOC_HIDE_START + + client.get()[2]:activate {} + client.get()[2].color = "#ff777733" +end) + +--DOC_NEWLINE +module.display_tags() +module.display_widget(_tl, nil, 22) + +module.add_event("Set the filter to alltags.", function() + --DOC_HIDE_END + -- Set the filter to alltags. + tasklist.filter = awful.widget.tasklist.filter.alltags + --DOC_NEWLINE + --DOC_HIDE_START +end) + +module.display_widget(_tl, nil, 22) + +module.execute { display_screen = false, display_clients = true, + display_label = false, display_client_name = true, + display_mouse = true , +} diff --git a/tests/examples/sequences/client/tasklist_filter_currenttags1.lua b/tests/examples/sequences/client/tasklist_filter_currenttags1.lua new file mode 100644 index 000000000..43f2ea635 --- /dev/null +++ b/tests/examples/sequences/client/tasklist_filter_currenttags1.lua @@ -0,0 +1,80 @@ + --DOC_GEN_IMAGE --DOC_HIDE_START --DOC_NO_USAGE +local module = ... +require("ruled.client") +local awful = { + tag = require("awful.tag"), + widget = { + tasklist = require("awful.widget.tasklist") + }, + button = require("awful.button"), + layout = require("awful.layout") +} +require("awful.ewmh") +local wibox = require("wibox") + +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.suit.corner.nw) + +local s = screen[1] +--DOC_HIDE_END + + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + base_layout = wibox.widget { + spacing = 2, + layout = wibox.layout.fixed.horizontal, + }, + } + + --DOC_NEWLINE + --DOC_HIDE_START + +local _tl = tasklist + +function awful.spawn(name, args) + client.gen_fake{class = name, name = name, x = 2094, y=10, width = 60, height =50, tags=args.tags} +end + +--DOC_NEWLINE + +module.add_event("Spawn some clients.", function() + --DOC_HIDE_END + + -- Spawn 5 clients on screen 1. + for k, t in ipairs(screen[1].tags) do + for i= 1, 2 do + awful.spawn("Client #"..(k-1)*2 + i, {tags = {t}}) + end + end + + --DOC_NEWLINE + + -- Selected some tags. + screen[1].tags[3].selected = true + screen[1].tags[5].selected = true + + --DOC_NEWLINE + --DOC_HIDE_START + + client.get()[2]:activate {} + client.get()[2].color = "#ff777733" +end) + +--DOC_NEWLINE +module.display_tags() +module.display_widget(_tl, nil, 22) + +module.add_event("Set the filter to currenttags.", function() + --DOC_HIDE_END + -- Set the filter to currenttags. + tasklist.filter = awful.widget.tasklist.filter.currenttags + --DOC_NEWLINE + --DOC_HIDE_START +end) + +module.display_widget(_tl, nil, 22) + +module.execute { display_screen = false, display_clients = true, + display_label = false, display_client_name = true, + display_mouse = true , +} diff --git a/tests/examples/sequences/client/tasklist_filter_focused1.lua b/tests/examples/sequences/client/tasklist_filter_focused1.lua new file mode 100644 index 000000000..c85afc0d3 --- /dev/null +++ b/tests/examples/sequences/client/tasklist_filter_focused1.lua @@ -0,0 +1,73 @@ + --DOC_GEN_IMAGE --DOC_HIDE_START --DOC_NO_USAGE +local module = ... +require("ruled.client") +local awful = { + tag = require("awful.tag"), + widget = { + tasklist = require("awful.widget.tasklist") + }, + button = require("awful.button"), + layout = require("awful.layout") +} +require("awful.ewmh") +local wibox = require("wibox") +screen[1]:fake_resize(0, 0, 1024, 640) + +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.suit.corner.nw) + +local s = screen[1] +--DOC_HIDE_END + + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + base_layout = wibox.widget { + spacing = 2, + layout = wibox.layout.fixed.horizontal, + }, + } + + --DOC_NEWLINE + --DOC_HIDE_START + +local _tl = tasklist + +function awful.spawn(name, args) + client.gen_fake{class = name, name = name, x = 2094, y=10, width = 60, height =50, screen=args.screen} +end + +--DOC_NEWLINE + +module.add_event("Spawn some clients.", function() + --DOC_HIDE_END + + -- Spawn 5 clients on screen 1. + for i= 1, 5 do + awful.spawn("Client #"..i, {screen = screen[1]}) + end + + --DOC_NEWLINE + --DOC_HIDE_START + + client.get()[2]:activate {} + client.get()[2].color = "#ff777733" +end) + +--DOC_NEWLINE +module.display_tags() +module.display_widget(_tl, nil, 22) + +module.add_event("Set the filter to focused.", function() + --DOC_HIDE_END + -- Set the filter to focused. + tasklist.filter = awful.widget.tasklist.filter.focused + --DOC_NEWLINE + --DOC_HIDE_START +end) + +module.display_widget(_tl, nil, 22) + +module.execute { display_screen = true , display_clients = true, + display_label = false, display_client_name = true, + display_mouse = true , +} diff --git a/tests/examples/sequences/client/tasklist_filter_minimizedcurrenttags1.lua b/tests/examples/sequences/client/tasklist_filter_minimizedcurrenttags1.lua new file mode 100644 index 000000000..07374239a --- /dev/null +++ b/tests/examples/sequences/client/tasklist_filter_minimizedcurrenttags1.lua @@ -0,0 +1,82 @@ + --DOC_GEN_IMAGE --DOC_HIDE_START --DOC_NO_USAGE +local module = ... +require("ruled.client") +local awful = { + tag = require("awful.tag"), + widget = { + tasklist = require("awful.widget.tasklist") + }, + button = require("awful.button"), + layout = require("awful.layout") +} +require("awful.ewmh") +local wibox = require("wibox") + +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.suit.corner.nw) + +local s = screen[1] +--DOC_HIDE_END + + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + base_layout = wibox.widget { + spacing = 2, + layout = wibox.layout.fixed.horizontal, + }, + } + + --DOC_NEWLINE + --DOC_HIDE_START + +local _tl = tasklist + +function awful.spawn(name, args) + client.gen_fake{ + class = name, name = name, x = 2094, y=10, width = 60, height =50, tags=args.tags, minimized=args.minimized + } +end + +--DOC_NEWLINE + +module.add_event("Spawn some clients.", function() + --DOC_HIDE_END + + -- Spawn 5 clients on screen 1. + for k, t in ipairs(screen[1].tags) do + for i= 1, 2 do + awful.spawn("Client #"..(k-1)*2 + i, {tags = {t}, minimized = i == 1}) + end + end + + --DOC_NEWLINE + + -- Selected some tags. + screen[1].tags[3].selected = true + screen[1].tags[5].selected = true + + --DOC_NEWLINE + --DOC_HIDE_START + + client.get()[2]:activate {} + client.get()[2].color = "#ff777733" +end) + +--DOC_NEWLINE +module.display_tags() +module.display_widget(_tl, nil, 22) + +module.add_event("Set the filter to minimizedcurrenttags.", function() + --DOC_HIDE_END + -- Set the filter to minimizedcurrenttags. + tasklist.filter = awful.widget.tasklist.filter.minimizedcurrenttags + --DOC_NEWLINE + --DOC_HIDE_START +end) + +module.display_widget(_tl, nil, 22) + +module.execute { display_screen = false, display_clients = true, + display_label = false, display_client_name = true, + display_mouse = true , +} diff --git a/tests/examples/sequences/client/tasklist_layout1.lua b/tests/examples/sequences/client/tasklist_layout1.lua new file mode 100644 index 000000000..5619de919 --- /dev/null +++ b/tests/examples/sequences/client/tasklist_layout1.lua @@ -0,0 +1,117 @@ + --DOC_GEN_IMAGE --DOC_HIDE_START --DOC_NO_USAGE +local module = ... +require("ruled.client") +local awful = { + tag = require("awful.tag"), + widget = { + tasklist = require("awful.widget.tasklist") + }, + button = require("awful.button") +} +require("awful.ewmh") +local wibox = require("wibox") +screen[1]:fake_resize(0, 0, 800, 480) +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1]) +local s = screen[1] +--DOC_HIDE_END + + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + base_layout = wibox.widget { + spacing = 2, + layout = wibox.layout.fixed.horizontal, + }, + buttons = { + awful.button({ }, 1, function (c) + c:activate { + context = "tasklist", + action = "toggle_minimization" + } + end), + awful.button({ }, 3, function() awful.menu.client_list { theme = { width = 250 } } end), + awful.button({ }, 4, function() awful.client.focus.byidx(-1) end), + awful.button({ }, 5, function() awful.client.focus.byidx( 1) end), + }, + } + + --DOC_NEWLINE + + tasklist:connect_signal("property::count", function(self) + local count = self.count + --DOC_NEWLINE + if count > 5 and not self.is_grid then + self.base_layout = wibox.widget { + forced_num_rows = 2, + homogeneous = true, + expand = true, + spacing = 2, + layout = wibox.layout.grid.horizontal + } + --DOC_NEWLINE + self.is_grid = true + elseif count <= 5 and self.is_grid then + self.base_layout = wibox.widget { + spacing = 2, + layout = wibox.layout.fixed.horizontal + } + --DOC_NEWLINE + self.is_grid = false + end + end) + + --DOC_NEWLINE + --DOC_HIDE_START + +local _tl = tasklist + +function awful.spawn(name) + client.gen_fake{class = name, name = name, x = 2094, y=10, width = 60, height =50, screen=screen[1]} +end + + +--DOC_NEWLINE + +module.add_event("Spawn 5 clients.", function() + --DOC_HIDE_END + + -- Spawn 5 clients. + for i=1, 5 do + awful.spawn("Client #"..i) + end + + --DOC_NEWLINE + --DOC_HIDE_START + + client.get()[2]:activate {} + client.get()[2].color = "#ff777733" +end) + +--DOC_NEWLINE +module.display_widget(_tl, nil, 22) + +module.add_event("Spawn another client.", function() + --DOC_HIDE_END + -- Spawn another client. + awful.spawn("Client #6") + --DOC_NEWLINE + --DOC_HIDE_START +end) + +module.display_widget(_tl, nil, 44) + +module.add_event("Kill 3 clients.", function() + --DOC_HIDE_END + -- Kill 3 clients. + for _=1, 3 do + client.get()[1]:kill() + end + --DOC_HIDE_START +end) + +module.display_widget(_tl, nil, 22) + +module.execute { display_screen = true , display_clients = true, + display_label = false, display_client_name = true, + display_mouse = true , +} diff --git a/tests/examples/sequences/client/tasklist_screen1.lua b/tests/examples/sequences/client/tasklist_screen1.lua new file mode 100644 index 000000000..392aa15b5 --- /dev/null +++ b/tests/examples/sequences/client/tasklist_screen1.lua @@ -0,0 +1,87 @@ + --DOC_GEN_IMAGE --DOC_HIDE_START --DOC_NO_USAGE +local module = ... +require("ruled.client") +local awful = { + tag = require("awful.tag"), + widget = { + tasklist = require("awful.widget.tasklist") + }, + layout = require("awful.layout"), + button = require("awful.button") +} +require("awful.ewmh") +screen[1]:fake_resize(0, 0, 1024, 640) +screen.fake_add(1050, 0, 1024, 640).outputs = {["eVGA1"] = {mm_height=50, mm_width=80 }} --DOC_HIDE + +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.suit.corner.nw) +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[2], awful.layout.suit.tile.left) + +--DOC_HIDE_END + + local tasklist = awful.widget.tasklist { + screen = screen[1], + filter = awful.widget.tasklist.filter.currenttags, + buttons = { + awful.button({ }, 1, function (c) + c:activate { + context = "tasklist", + action = "toggle_minimization" + } + end), + awful.button({ }, 3, function() awful.menu.client_list { theme = { width = 250 } } end), + awful.button({ }, 4, function() awful.client.focus.byidx(-1) end), + awful.button({ }, 5, function() awful.client.focus.byidx( 1) end), + }, + } + --DOC_NEWLINE + --DOC_HIDE_START + +local _tl = tasklist + +function awful.spawn(name, args) + client.gen_fake{class = name, name = name, x = 2094, y=10, width = 60, height =50, screen=args.screen} +end + +--DOC_NEWLINE + +module.add_event("Spawn some clients.", function() + --DOC_HIDE_END + + -- Spawn 5 clients on screen 1. + for i= 1, 5 do + awful.spawn("Client #"..i, {screen = screen[1]}) + end + + --DOC_NEWLINE + + -- Spawn 3 clients on screen 2. + for i=1, 3 do + awful.spawn("Client #"..(5+i), {screen = screen[2]}) + end + + --DOC_NEWLINE + --DOC_HIDE_START + + client.get()[2]:activate {} + client.get()[2].color = "#ff777733" +end) + +module.display_tags() + +--DOC_NEWLINE +module.display_widget(_tl, nil, 22) + +module.add_event("Change the tasklist screen.", function() + --DOC_HIDE_END + -- Change the tastlist screen. + tasklist.screen = screen[2] + --DOC_NEWLINE + --DOC_HIDE_START +end) + +module.display_widget(_tl, nil, 22) + +module.execute { display_screen = true , display_clients = true, + display_label = false , display_client_name = true, + display_mouse = true , +} diff --git a/tests/examples/sequences/client/tasklist_widget_template1.lua b/tests/examples/sequences/client/tasklist_widget_template1.lua new file mode 100644 index 000000000..08e373cba --- /dev/null +++ b/tests/examples/sequences/client/tasklist_widget_template1.lua @@ -0,0 +1,89 @@ + --DOC_GEN_IMAGE --DOC_HIDE_START --DOC_NO_USAGE +local module = ... +require("ruled.client") +local awful = { + tag = require("awful.tag"), + widget = { + tasklist = require("awful.widget.tasklist") + }, + button = require("awful.button") +} +require("awful.ewmh") +local wibox = require("wibox") +screen[1]:fake_resize(0, 0, 800, 480) +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1]) +local s = screen[1] +--DOC_HIDE_END + + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + base_layout = wibox.widget { + spacing = 2, + layout = wibox.layout.fixed.horizontal, + }, + } + + --DOC_NEWLINE + --DOC_HIDE_START + +local _tl = tasklist + +function awful.spawn(name) + client.gen_fake{class = name, name = name, x = 2094, y=10, width = 60, height =50, screen=screen[1]} +end + + +--DOC_NEWLINE + +module.add_event("Spawn 5 clients.", function() + + -- Spawn 5 clients. + for i=1, 5 do + awful.spawn("Client #"..i) + end + + client.get()[2]:activate {} + client.get()[2].color = "#ff777733" +end) + +--DOC_NEWLINE +module.display_widget(_tl, nil, 22) + +module.add_event("Change the widget template.", function() + --DOC_HIDE_END + -- Change the widget template. + tasklist.widget_template = { + { + { + { + { + id = "icon_role", + widget = wibox.widget.imagebox, + }, + margins = 2, + widget = wibox.container.margin, + }, + { + id = "text_role", + widget = wibox.widget.textbox, + }, + layout = wibox.layout.fixed.horizontal, + }, + left = 10, + right = 10, + widget = wibox.container.margin + }, + id = "background_role", + widget = wibox.container.background, + } + --DOC_NEWLINE + --DOC_HIDE_START +end) + +module.display_widget(_tl, nil, 22) + +module.execute { display_screen = true , display_clients = true, + display_label = false, display_client_name = true, + display_mouse = true , +} diff --git a/tests/examples/sequences/tag/clear.lua b/tests/examples/sequences/tag/clear.lua index 586f5da6b..2161176ad 100644 --- a/tests/examples/sequences/tag/clear.lua +++ b/tests/examples/sequences/tag/clear.lua @@ -43,7 +43,7 @@ module.display_tags() --DOC_HIDE module.add_event("Call `:clear()` on the first tag.", function() --DOC_HIDE -- Call :clear() on the first tag. screen[1].tags[1]:clear{} -end) +end) --DOC_HIDE module.display_tags() --DOC_HIDE diff --git a/tests/examples/sequences/template.lua b/tests/examples/sequences/template.lua index 6110cce4a..719c5f06f 100644 --- a/tests/examples/sequences/template.lua +++ b/tests/examples/sequences/template.lua @@ -7,6 +7,7 @@ local file_path, image_path = ... require("_common_template")(...) local capi = {client = client, screen = screen} local Pango = require("lgi").Pango +local cairo = require("lgi").cairo local PangoCairo = require("lgi").PangoCairo require("awful.screen") require("awful.tag") @@ -95,7 +96,7 @@ local function draw_lines() if (not self.widget_pos) or (not self.pager_pos) then return end cr:set_line_width(1) - cr:set_source_rgba(0,0,0,0.3) + cr:set_source(color.change_opacity(beautiful.fg_normal, 0.3)) local count = #self.widget_pos @@ -130,7 +131,7 @@ local function gen_vertical_line(args) local w = wibox.widget.base.make_widget() function w:draw(_, cr, w2, h) - cr:set_source_rgba(0,0,0,0.5) + cr:set_source(color.change_opacity(beautiful.fg_normal, 0.5)) if args.begin then cr:rectangle(w2/2-0.5, h/2, 1, h/2) @@ -146,7 +147,7 @@ local function gen_vertical_line(args) cr:arc(w2/2, args.center and h/2 or w2/2 ,bar_size/4, 0, 2*math.pi) cr:set_source_rgb(1,1,1) cr:fill_preserve() - cr:set_source_rgba(0,0,0,0.5) + cr:set_source(color.change_opacity(beautiful.fg_normal, 0.5)) cr:stroke() end end @@ -301,7 +302,8 @@ local function fake_arrange(tag) focus = focus_wrap, geometries = setmetatable({}, {__mode = "k"}), workarea = tag.screen.workarea, - useless_gap = tag.gaps or 4, + useless_gap = tag.gaps or beautiful.useless_gap or 4, + gap_single_client= tag.gap_single_client or beautiful.gap_single_client or nil, apply_size_hints = false, } @@ -354,14 +356,14 @@ local function gen_fake_clients(tag, args) cr:stroke() if show_name and type(geom.c) == "table" and geom.c.name then - cr:set_source_rgb(0, 0, 0) + cr:set_source(beautiful.fg_normal) cr:move_to(x + 2, y + height - 2) cr:show_text(geom.c.name) end end -- Draw the screen outline. - cr:set_source(color("#00000044")) + cr:set_source(color.change_opacity(beautiful.fg_normal, 0.1725)) cr:set_line_width(1.5) cr:set_dash({10,4},1) cr:rectangle(0, 0, w, h) @@ -446,7 +448,7 @@ local function gen_label(text) end local function draw_info(s, cr, factor) - cr:set_source_rgba(0, 0, 0, 0.4) + cr:set_source(color.change_opacity(beautiful.fg_normal, 0.4)) local pctx = PangoCairo.font_map_get_default():create_context() local playout = Pango.Layout.new(pctx) @@ -638,7 +640,7 @@ local function gen_screens(l, screens, args) end function s.widget:draw(_, cr, w, h) - cr:set_source(color("#00000044")) + cr:set_source(color.change_opacity(beautiful.fg_normal, 0.1725)) cr:set_line_width(1.5) cr:set_dash({10,4},1) cr:rectangle(1,1,w-2,h-2) @@ -714,7 +716,9 @@ local function gen_timeline(args) awesome.startup = false --luacheck: ignore for _, event in ipairs(history) do + require("gears.timer").run_delayed_calls_now() local ret = event.callback() + require("gears.timer").run_delayed_calls_now() if event.event == "event" then l:add(wrap_timeline(gen_vertical_space(5))) l:add(wrap_timeline(wibox.widget { @@ -725,6 +729,8 @@ local function gen_timeline(args) gen_noscreen(l, ret[1].tags, args) elseif event.event == "tags" and (#ret > 1 or args.display_screen) then gen_screens(l, ret, args) + elseif event.event == "widget" then + l:add(wrap_timeline(ret)) end end @@ -785,6 +791,39 @@ local function wrap_with_arrows(widget) } end +-- Use a recording surface to store the widget content. +function module.display_widget(wdg, width, height, context) + local function do_it() + context = context or {dpi=96} + + local w, h = wdg:fit(context, width or 9999, height or 9999) + + w, h = math.min(w, width or 9999), math.min(h, height or 9999) + + local memento = cairo.RecordingSurface( + cairo.Content.CAIRO_FORMAT_ARGB32, + cairo.Rectangle { x = 0, y = 0, width = w, height = h } + ) + + local cr = cairo.Context(memento) + + wibox.widget.draw_to_cairo_context(wdg, cr, w, h, context) + + return wibox.widget { + fit = function() + return w, h+5 + end, + draw = function(_, _, cr2) + cr2:translate(0, 5) + cr2:set_source_surface(memento) + cr2:paint() + end + } + end + + table.insert(history, {event="widget", callback = do_it}) +end + function module.display_tags() local function do_it() local ret = {} diff --git a/tests/examples/shims/beautiful.lua b/tests/examples/shims/beautiful.lua index 4798ec55a..396ace662 100644 --- a/tests/examples/shims/beautiful.lua +++ b/tests/examples/shims/beautiful.lua @@ -25,9 +25,18 @@ local function logo() return img end +-- Use a cairo pattern for the foreground to allow improve the +-- reliability of the find&replace documentation script. This +-- will be post-processed to ensure the foreground color is +-- inherited from the browser rather than hardcoded. In turn, +-- this allows the accessibility mode to work and to define the +-- color using our CSS template, which allows for light/dark +-- themes to be implemented with a single image. +local main_fg = cairo.Pattern.create_rgba(0.005, 0, 0.005, 1) + -- Default theme for the documentation examples local module = { - fg_normal = "#000000" , + fg_normal = main_fg, bg_normal = "#6181FF7D", bg_focus = "#AA00FF7D", bg_highlight = "#AA00FF7D", @@ -117,8 +126,9 @@ module.layout_cornersw = themes_path.."default/layouts/cornersww.png" module.layout_cornerse = themes_path.."default/layouts/cornersew.png" -- Taglist -module.taglist_bg_focus = module.bg_highlight -module.taglist_bg_used = module.bg_normal +module.taglist_bg_focus = module.bg_highlight +module.taglist_bg_used = module.bg_normal +module.taglist_bg_normal = module.bg_normal function module.get() diff --git a/tests/examples/uml/nav_tables/client.output.txt b/tests/examples/uml/nav_tables/client.output.txt index 65bc1681b..2b6312e52 100644 --- a/tests/examples/uml/nav_tables/client.output.txt +++ b/tests/examples/uml/nav_tables/client.output.txt @@ -3,75 +3,18 @@ Core components relationship === - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - -
Acquire other objects from a client
ClassProperty
tagc.tags
screenc.screen
awful.keyc:keys()
awful.buttonc:buttons()
 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Acquire a client from other objects
ClassProperty
tagt:clients()
screens.clients
screens.hidden_clients
screens.tiled_clients
mousemouse.current_client
- Legend: c: a client object, t: a tag object, - s: a screen object, k: an awful.key object, - b: a awful.button object, n: a naughty.notification object -
+
+
+ + + + +
Acquire other objects from a client
ClassProperty
tagc.tags
screenc.screen
awful.keyc:keys()
awful.buttonc:buttons()
+
+ + + + + +
Acquire a client from other objects
ClassProperty
tagt:clients()
screens.clients
screens.hidden_clients
screens.tiled_clients
mousemouse.current_client
+
Legend: c: a client object, t: a tag object, s: a screen object, k: an awful.key object, b: a awful.button object,n: a naughty.notification object
diff --git a/tests/examples/uml/nav_tables/screen.output.txt b/tests/examples/uml/nav_tables/screen.output.txt index d7b307854..d575afd98 100644 --- a/tests/examples/uml/nav_tables/screen.output.txt +++ b/tests/examples/uml/nav_tables/screen.output.txt @@ -3,75 +3,18 @@ Core components relationship === - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Acquire other objects from a screen
ClassProperty
tags.tags
tags.selected_tag
tags.selected_tags
clients.clients
clients.hidden_clients
clients.tiled_clients
 - - - - - - - - - - - - - - - - - - - - - - -
Acquire a screen from other objects
ClassProperty
tagt.screen
clientc.screen
naughty.notificationn.screen
- Legend: c: a client object, t: a tag object, - s: a screen object, k: an awful.key object, - b: a awful.button object, n: a naughty.notification object -
+
+
+ + + + + + +
Acquire other objects from a screen
ClassProperty
tags.tags
tags.selected_tag
tags.selected_tags
clients.clients
clients.hidden_clients
clients.tiled_clients
+
+ + + +
Acquire a screen from other objects
ClassProperty
tagt.screen
clientc.screen
naughty.notificationn.screen
+
Legend: c: a client object, t: a tag object, s: a screen object, k: an awful.key object, b: a awful.button object,n: a naughty.notification object
diff --git a/tests/examples/uml/nav_tables/tag.output.txt b/tests/examples/uml/nav_tables/tag.output.txt index 55b9ac223..8b4cbe46b 100644 --- a/tests/examples/uml/nav_tables/tag.output.txt +++ b/tests/examples/uml/nav_tables/tag.output.txt @@ -3,60 +3,15 @@ Core components relationship === - - - - - - -
- - - - - - - - - - - - - - - - - -
Acquire other objects from a tag
ClassProperty
clientt:clients()
screent.screen
 - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Acquire a tag from other objects
ClassProperty
clientc.tags
screens.tags
screens.selected_tag
screens.selected_tags
- Legend: c: a client object, t: a tag object, - s: a screen object, k: an awful.key object, - b: a awful.button object, n: a naughty.notification object -
+
+
+ + +
Acquire other objects from a tag
ClassProperty
clientt:clients()
screent.screen
+
+ + + + +
Acquire a tag from other objects
ClassProperty
clientc.tags
screens.tags
screens.selected_tag
screens.selected_tags
+
Legend: c: a client object, t: a tag object, s: a screen object, k: an awful.key object, b: a awful.button object,n: a naughty.notification object
diff --git a/tests/examples/uml/template.lua b/tests/examples/uml/template.lua index 399c50b4c..20a2750d5 100644 --- a/tests/examples/uml/template.lua +++ b/tests/examples/uml/template.lua @@ -6,7 +6,11 @@ local wibox = require("wibox") local beautiful = require("beautiful") -- Make the path relative. -local relative_image_path = "../" .. image_path:match("/(images/[^/]+)$") +local path = image_path:match("/(images/[^/]+)$") +if not path then + path = image_path:match("/(raw_images/[^/]+)$"):gsub("raw_", "") +end +local relative_image_path = "../" .. path -- This template generates an HTML table with how other classes are associated -- with a given class. @@ -162,27 +166,24 @@ local map = { } local function gen_table_header(title, o) - print([[ - - - - - - - ]]) + print(table.concat({[[
]], + [[
]]..map[title](o)..[[
ClassProperty
]], + [[]], + [[]], + [[]], + [[]], + [[]] + })) end -local function get_table_row(path, class, prop) - print([[ - - - - ]]) +local function get_table_row(rel_path, class, prop) + print([[]]) end local function get_table_footer() - print '
]]..map[title](o)..[[
ClassProperty
]].. class ..[[]].. prop ..[[
]].. class ..[[]].. prop ..[[
' + print '
' end local module = {} @@ -193,7 +194,7 @@ function module.generate_nav_table(t) assert(t.content and t.class) print("\n\nCore components relationship\n===\n") - print '' + print('
') -- Validate early to avoid debugging cryptic backtraces. for _, tab in ipairs {"to", "from"} do @@ -204,24 +205,24 @@ function module.generate_nav_table(t) assert(entry.class) assert(entry.left.msg and entry.left.card) assert(entry.right.msg and entry.right.card) - local path = relative_image_path..counter..".svg" + local rel_path = relative_image_path..counter..".svg" local fpath = image_path..counter..".svg" local widget = gen_table_uml(entry, t.class, entry.class, false) wibox.widget.draw_to_svg_file(widget, fpath, 320, 50) - get_table_row(path, entry.class, entry[tab.."_property"]) + get_table_row(rel_path, entry.class, entry[tab.."_property"]) counter = counter + 1 end end get_table_footer() end - print([[
- - -
- Legend: c: a client object, t: a tag object, - s: a screen object, k: an awful.key object, - b: a awful.button object, n: a naughty.notification object -
]]) + + -- End the last section and add a footer + print(table.concat({[[
]], + [[Legend: c: a client object, t: a tag object, s]], + [[: a screen object, k: an awful.key object, b: a awful.button object,]], + [[n: a naughty.notification object
]], + [[]] + })) end loadfile(file_path)(module) diff --git a/tests/examples/wibox/awidget/defaults/button.lua b/tests/examples/wibox/awidget/defaults/button.lua index a08be8e9c..9894743db 100644 --- a/tests/examples/wibox/awidget/defaults/button.lua +++ b/tests/examples/wibox/awidget/defaults/button.lua @@ -1,12 +1,13 @@ ---DOC_GEN_IMAGE --DOC_HEADER --DOC_HIDE -local parent = ... --DOC_NO_USAGE --DOC_HIDE -local awful = {--DOC_HIDE - button = require("awful.button"), --DOC_HIDE - widget = {button = require("awful.widget.button")} --DOC_HIDE -}--DOC_HIDE -local beautiful = require("beautiful") --DOC_HIDE +--DOC_HIDE_START --DOC_GEN_IMAGE --DOC_NO_USAGE +local parent = ... +local awful = { + button = require("awful.button"), + widget = {button = require("awful.widget.button")} +} +local beautiful = require("beautiful") - local button = --DOC_HIDE + local button = + --DOC_HIDE_END awful.widget.button { image = beautiful.awesome_icon, buttons = { @@ -16,7 +17,8 @@ local beautiful = require("beautiful") --DOC_HIDE } } -button.forced_height = 24 --DOC_HIDE -button.forced_width = 24 --DOC_HIDE +--DOC_HIDE_START +button.forced_height = 24 +button.forced_width = 24 -parent:add(button) --DOC_HIDE +parent:add(button) diff --git a/tests/examples/wibox/awidget/tasklist/style_align.lua b/tests/examples/wibox/awidget/tasklist/style_align.lua new file mode 100644 index 000000000..5ca8c0a29 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_align.lua @@ -0,0 +1,39 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 3 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +--DOC_HIDE_END +for _, value in ipairs { "left", "center", "right" } do + beautiful.tasklist_align = value + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + base_layout = wibox.layout.flex.horizontal + } + + tasklist._do_tasklist_update_now() + tasklist.forced_width = 600 + parent:add(_memento(tasklist, 600, 22, nil, true)) --luacheck: globals _memento + --DOC_HIDE_END +end + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_bg_focus.lua b/tests/examples/wibox/awidget/tasklist/style_bg_focus.lua new file mode 100644 index 000000000..cc2a2848a --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_bg_focus.lua @@ -0,0 +1,64 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local gears = { color = require("gears.color") } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END + +local grad = gears.color { + type = "linear", + from = { 0, 0 }, + to = { 0, 22 }, + stops = { + { 0, "#ff0000" }, + { 1, "#0000ff" }, + } +} + +--DOC_NEWLINE +for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff", grad } do + beautiful.tasklist_bg_focus = col + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_bg_minimize.lua b/tests/examples/wibox/awidget/tasklist/style_bg_minimize.lua new file mode 100644 index 000000000..5653b25a8 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_bg_minimize.lua @@ -0,0 +1,64 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local gears = { color = require("gears.color") } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END + +local grad = gears.color { + type = "linear", + from = { 0, 0 }, + to = { 0, 22 }, + stops = { + { 0, "#ff0000" }, + { 1, "#0000ff" }, + } +} + +--DOC_NEWLINE +for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff", grad } do + beautiful.tasklist_bg_minimize = col + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_bg_normal.lua b/tests/examples/wibox/awidget/tasklist/style_bg_normal.lua new file mode 100644 index 000000000..8b75dcb16 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_bg_normal.lua @@ -0,0 +1,64 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local gears = { color = require("gears.color") } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END + +local grad = gears.color { + type = "linear", + from = { 0, 0 }, + to = { 0, 22 }, + stops = { + { 0, "#ff0000" }, + { 1, "#0000ff" }, + } +} + +--DOC_NEWLINE +for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff", grad } do + beautiful.tasklist_bg_normal = col + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_bg_urgent.lua b/tests/examples/wibox/awidget/tasklist/style_bg_urgent.lua new file mode 100644 index 000000000..c29971a61 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_bg_urgent.lua @@ -0,0 +1,64 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local gears = { color = require("gears.color") } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END + +local grad = gears.color { + type = "linear", + from = { 0, 0 }, + to = { 0, 22 }, + stops = { + { 0, "#ff0000" }, + { 1, "#0000ff" }, + } +} + +--DOC_NEWLINE +for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff", grad } do + beautiful.tasklist_bg_urgent = col + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_disable_icon.lua b/tests/examples/wibox/awidget/tasklist/style_disable_icon.lua new file mode 100644 index 000000000..a03edd3fb --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_disable_icon.lua @@ -0,0 +1,38 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 3 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +--DOC_HIDE_END +for _, value in ipairs { true, false } do + beautiful.tasklist_disable_icon = value + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_disable_task_name.lua b/tests/examples/wibox/awidget/tasklist/style_disable_task_name.lua new file mode 100644 index 000000000..76b6ebeaa --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_disable_task_name.lua @@ -0,0 +1,39 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 3 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +--DOC_HIDE_END +for _, value in ipairs { true, false } do + beautiful.tasklist_disable_task_name = value + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_fg_focus.lua b/tests/examples/wibox/awidget/tasklist/style_fg_focus.lua new file mode 100644 index 000000000..84af9e8bd --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_fg_focus.lua @@ -0,0 +1,51 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END +for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff" } do + beautiful.tasklist_fg_focus = col + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_fg_minimize.lua b/tests/examples/wibox/awidget/tasklist/style_fg_minimize.lua new file mode 100644 index 000000000..b0479f2ac --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_fg_minimize.lua @@ -0,0 +1,51 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END +for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff" } do + beautiful.tasklist_fg_minimize = col + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_fg_normal.lua b/tests/examples/wibox/awidget/tasklist/style_fg_normal.lua new file mode 100644 index 000000000..029412f2c --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_fg_normal.lua @@ -0,0 +1,51 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END +for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff" } do + beautiful.tasklist_fg_normal = col + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_fg_urgent.lua b/tests/examples/wibox/awidget/tasklist/style_fg_urgent.lua new file mode 100644 index 000000000..cd51b5bc6 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_fg_urgent.lua @@ -0,0 +1,51 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END +for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff" } do + beautiful.tasklist_fg_urgent = col + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_font.lua b/tests/examples/wibox/awidget/tasklist/style_font.lua new file mode 100644 index 000000000..c1ca3ea3c --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_font.lua @@ -0,0 +1,51 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END +for _, font in ipairs { "sans 8", "sans 10 bold", "sans 12 italic" } do + beautiful.tasklist_font = font + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_font_focus.lua b/tests/examples/wibox/awidget/tasklist/style_font_focus.lua new file mode 100644 index 000000000..609ebd2e3 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_font_focus.lua @@ -0,0 +1,51 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END +for _, font in ipairs { "sans 8", "sans 10 bold", "sans 12 italic" } do + beautiful.tasklist_font_focus = font + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_font_minimized.lua b/tests/examples/wibox/awidget/tasklist/style_font_minimized.lua new file mode 100644 index 000000000..65d761cd8 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_font_minimized.lua @@ -0,0 +1,51 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END +for _, font in ipairs { "sans 8", "sans 10 bold", "sans 12 italic" } do + beautiful.tasklist_font_minimized = font + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_font_urgent.lua b/tests/examples/wibox/awidget/tasklist/style_font_urgent.lua new file mode 100644 index 000000000..34c638e2a --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_font_urgent.lua @@ -0,0 +1,51 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END +for _, font in ipairs { "sans 8", "sans 10 bold", "sans 12 italic" } do + beautiful.tasklist_font_urgent = font + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_plain_task_name.lua b/tests/examples/wibox/awidget/tasklist/style_plain_task_name.lua new file mode 100644 index 000000000..9585d5752 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_plain_task_name.lua @@ -0,0 +1,45 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 3 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" + +client.get()[1].floating = true +client.get()[2].sticky = true + +--DOC_HIDE_END +for _, value in ipairs { true, false } do + beautiful.tasklist_plain_task_name = value + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_shape.lua b/tests/examples/wibox/awidget/tasklist/style_shape.lua new file mode 100644 index 000000000..c5011281f --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_shape.lua @@ -0,0 +1,51 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local gears = { shape = require("gears.shape") } +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 3 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +--DOC_HIDE_END + +beautiful.tasklist_spacing = 5 + +--DOC_NEWLINE + +local function customized(cr, width, height) + return gears.shape.parallelogram(cr, width, height, width - height) +end + +--DOC_NEWLINE + +for _, shape in ipairs { gears.shape.rounded_rect, gears.shape.octogon, gears.shape.hexagon, customized } do + beautiful.tasklist_shape = shape + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_shape_border_color.lua b/tests/examples/wibox/awidget/tasklist/style_shape_border_color.lua new file mode 100644 index 000000000..9a0731aee --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_shape_border_color.lua @@ -0,0 +1,58 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local gears = { shape = require("gears.shape"), color = require("gears.color") } +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 3 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end +--DOC_HIDE_END + +beautiful.tasklist_spacing = 5 +beautiful.tasklist_shape = gears.shape.rounded_rect +beautiful.tasklist_shape_border_width = 2 + +--DOC_NEWLINE + +local grad = gears.color { + type = "linear", + from = { 0, 0 }, + to = { 0, 22 }, + stops = { + { 0, "#ff0000" }, + { 1, "#0000ff" }, + } +} + +--DOC_NEWLINE + +for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff", grad } do + beautiful.tasklist_shape_border_color = col + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 32)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_shape_border_color_minimized.lua b/tests/examples/wibox/awidget/tasklist/style_shape_border_color_minimized.lua new file mode 100644 index 000000000..b5c91c197 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_shape_border_color_minimized.lua @@ -0,0 +1,71 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local gears = { shape = require("gears.shape"), color = require("gears.color") } +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END + +beautiful.tasklist_spacing = 5 +beautiful.tasklist_shape = gears.shape.rounded_rect +beautiful.tasklist_shape_border_width = 2 + +--DOC_NEWLINE + +local grad = gears.color { + type = "linear", + from = { 0, 0 }, + to = { 0, 22 }, + stops = { + { 0, "#ff0000" }, + { 1, "#0000ff" }, + } +} + +--DOC_NEWLINE + +for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff", grad } do + beautiful.tasklist_shape_border_color_minimized = col + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 32)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_shape_border_color_urgent.lua b/tests/examples/wibox/awidget/tasklist/style_shape_border_color_urgent.lua new file mode 100644 index 000000000..fa6fe4e8e --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_shape_border_color_urgent.lua @@ -0,0 +1,71 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local gears = { shape = require("gears.shape"), color = require("gears.color") } +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END + +beautiful.tasklist_spacing = 5 +beautiful.tasklist_shape = gears.shape.rounded_rect +beautiful.tasklist_shape_border_width = 2 + +--DOC_NEWLINE + +local grad = gears.color { + type = "linear", + from = { 0, 0 }, + to = { 0, 22 }, + stops = { + { 0, "#ff0000" }, + { 1, "#0000ff" }, + } +} + +--DOC_NEWLINE + +for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff", grad } do + beautiful.tasklist_shape_border_color_urgent = col + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 32)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_shape_border_width.lua b/tests/examples/wibox/awidget/tasklist/style_shape_border_width.lua new file mode 100644 index 000000000..85de4527d --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_shape_border_width.lua @@ -0,0 +1,46 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local gears = { shape = require("gears.shape") } +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 3 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +--DOC_HIDE_END + +beautiful.tasklist_spacing = 5 +beautiful.tasklist_shape = gears.shape.rounded_rect + +--DOC_NEWLINE + +for _, bw in ipairs { 0, 2, 4, 6 } do + beautiful.tasklist_shape_border_width = bw + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 32)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_shape_border_width_minimized.lua b/tests/examples/wibox/awidget/tasklist/style_shape_border_width_minimized.lua new file mode 100644 index 000000000..95f4a36b5 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_shape_border_width_minimized.lua @@ -0,0 +1,57 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local gears = { shape = require("gears.shape"), color = require("gears.color") } +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END + +beautiful.tasklist_spacing = 5 +beautiful.tasklist_shape = gears.shape.rounded_rect +--DOC_NEWLINE + +for _, bw in ipairs { 0, 2, 4, 6 } do + beautiful.tasklist_shape_border_width_minimized = bw + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 32)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_shape_border_width_urgent.lua b/tests/examples/wibox/awidget/tasklist/style_shape_border_width_urgent.lua new file mode 100644 index 000000000..cc81b854d --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_shape_border_width_urgent.lua @@ -0,0 +1,58 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local gears = { shape = require("gears.shape"), color = require("gears.color") } +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END + +beautiful.tasklist_spacing = 5 +beautiful.tasklist_shape = gears.shape.rounded_rect + +--DOC_NEWLINE + +for _, bw in ipairs { 0, 2, 4, 6 } do + beautiful.tasklist_shape_border_width_urgent = bw + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 32)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_shape_focus.lua b/tests/examples/wibox/awidget/tasklist/style_shape_focus.lua new file mode 100644 index 000000000..9ec34ad20 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_shape_focus.lua @@ -0,0 +1,63 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local gears = { shape = require("gears.shape") } +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END + +beautiful.tasklist_spacing = 5 + +--DOC_NEWLINE + +local function customized(cr, width, height) + return gears.shape.parallelogram(cr, width, height, width - height) +end + +--DOC_NEWLINE + +for _, shape in ipairs { gears.shape.rounded_rect, gears.shape.octogon, gears.shape.hexagon, customized } do + beautiful.tasklist_shape_focus = shape + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_shape_focus_border_width.lua b/tests/examples/wibox/awidget/tasklist/style_shape_focus_border_width.lua new file mode 100644 index 000000000..d83ad7f44 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_shape_focus_border_width.lua @@ -0,0 +1,58 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local gears = { shape = require("gears.shape") } +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END + +beautiful.tasklist_spacing = 5 +beautiful.tasklist_shape = gears.shape.rounded_rect + +--DOC_NEWLINE + +for _, bw in ipairs { 0, 2, 4, 6 } do + beautiful.tasklist_shape_border_width_focus = bw + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 32)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_shape_focus_border_width_focus.lua b/tests/examples/wibox/awidget/tasklist/style_shape_focus_border_width_focus.lua new file mode 100644 index 000000000..8bd7196b7 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_shape_focus_border_width_focus.lua @@ -0,0 +1,71 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local gears = { shape = require("gears.shape"), color = require("gears.color") } +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END + +beautiful.tasklist_spacing = 5 +beautiful.tasklist_shape = gears.shape.rounded_rect +beautiful.tasklist_shape_border_width = 2 + +--DOC_NEWLINE + +local grad = gears.color { + type = "linear", + from = { 0, 0 }, + to = { 0, 22 }, + stops = { + { 0, "#ff0000" }, + { 1, "#0000ff" }, + } +} + +--DOC_NEWLINE + +for _, col in ipairs { "#ff0000", "#00ff00", "#0000ff", grad } do + beautiful.tasklist_shape_border_color_focus = col + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 32)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_shape_minimized.lua b/tests/examples/wibox/awidget/tasklist/style_shape_minimized.lua new file mode 100644 index 000000000..bbbe20dd9 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_shape_minimized.lua @@ -0,0 +1,63 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local gears = { shape = require("gears.shape") } +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END + +beautiful.tasklist_spacing = 5 + +--DOC_NEWLINE + +local function customized(cr, width, height) + return gears.shape.parallelogram(cr, width, height, width - height) +end + +--DOC_NEWLINE + +for _, shape in ipairs { gears.shape.rounded_rect, gears.shape.octogon, gears.shape.hexagon, customized } do + beautiful.tasklist_shape_minimized = shape + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_shape_urgent.lua b/tests/examples/wibox/awidget/tasklist/style_shape_urgent.lua new file mode 100644 index 000000000..9ec34ad20 --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_shape_urgent.lua @@ -0,0 +1,63 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local gears = { shape = require("gears.shape") } +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 5 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +client.get()[1].name = "Client 1# (floating)" +client.get()[2].name = "Client 2# (sticky)" +client.get()[3].name = "Client 3# (focus)" +client.get()[4].name = "Client 4# (urgent)" +client.get()[5].name = "Client 5# (minimized)" + +client.get()[1].floating = true +client.get()[2].sticky = true +client.get()[4].urgent = true +client.get()[5].minimized = true +client.focus = client.get()[3] + +--DOC_HIDE_END + +beautiful.tasklist_spacing = 5 + +--DOC_NEWLINE + +local function customized(cr, width, height) + return gears.shape.parallelogram(cr, width, height, width - height) +end + +--DOC_NEWLINE + +for _, shape in ipairs { gears.shape.rounded_rect, gears.shape.octogon, gears.shape.hexagon, customized } do + beautiful.tasklist_shape_focus = shape + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/awidget/tasklist/style_spacing.lua b/tests/examples/wibox/awidget/tasklist/style_spacing.lua new file mode 100644 index 000000000..66c4f8d6d --- /dev/null +++ b/tests/examples/wibox/awidget/tasklist/style_spacing.lua @@ -0,0 +1,39 @@ +--DOC_HIDE_START +--DOC_GEN_IMAGE +local parent = ... +local beautiful = require("beautiful") +local wibox = require("wibox") +local awful = { widget = { tasklist = require("awful.widget.tasklist") } } +local t_real = require("awful.tag").add("Test", {screen=screen[1]}) + +local s = screen[1] +parent.spacing = 5 +beautiful.tasklist_fg_focus = "#000000" + +for i=1, 3 do + client.gen_fake{ + class = "client", + name = "Client #"..i, + icon = beautiful.awesome_icon, + tags = {t_real} + } +end + +--DOC_HIDE_END +for _, spacing in ipairs { 0, 4, 8, 12 } do + beautiful.tasklist_spacing = spacing + + --DOC_HIDE_START + local tasklist = awful.widget.tasklist { + screen = s, + filter = awful.widget.tasklist.filter.currenttags, + layout = wibox.layout.fixed.horizontal + } + + tasklist._do_tasklist_update_now() + parent:add(_memento(tasklist, nil, 22)) --luacheck: globals _memento + --DOC_HIDE_END +end + + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/wibox/nwidget/default.lua b/tests/examples/wibox/nwidget/default.lua index 3f670c2ce..71b807967 100644 --- a/tests/examples/wibox/nwidget/default.lua +++ b/tests/examples/wibox/nwidget/default.lua @@ -7,6 +7,7 @@ local def = require("naughty.widget._default") local acommon = require("awful.widget.common") local aplace = require("awful.placement") local gears = require("gears") +local color = require("gears.color") beautiful.notification_bg = beautiful.bg_normal @@ -76,7 +77,7 @@ local function create_line(x1, y1, x2, y2) return x2-x1+6, y2-y1+6 end, draw = function(_, _, cr) - cr:set_source_rgb(0,0,0) + cr:set_source(color(beautiful.fg_normal)) cr:set_line_width(1) cr:arc(1.5, 1.5, 1.5, 0, math.pi*2) cr:arc(x2-x1+1.5, y2-y1+1.5, 1.5, 0, math.pi*2) diff --git a/tests/examples/wibox/template.lua b/tests/examples/wibox/template.lua index 8fd1925de..08c1af988 100644 --- a/tests/examples/wibox/template.lua +++ b/tests/examples/wibox/template.lua @@ -3,6 +3,41 @@ require("_common_template")(...) local wibox = require( "wibox" ) local surface = require( "gears.surface" ) +local cairo = require("lgi").cairo +local color = require("gears.color") +local beautiful = require("beautiful") + +--- Create a copy of the widget frozen in time. +-- This is useful whe the global state is modified between the time this is +-- called and the time the final output is rendered. +function _memento(wdg, width, height, context, force) -- luacheck: globals _memento + context = context or {dpi=96} + + local w, h = wdg:fit(context, width or 9999, height or 9999) + + w, h = math.min(force and width or w, width or 9999), math.min(force and height or h, height or 9999) + + local memento = cairo.RecordingSurface( + cairo.Content.CAIRO_FORMAT_ARGB32, + cairo.Rectangle { x = 0, y = 0, width = w, height = h } + ) + + local cr = cairo.Context(memento) + + cr:set_source(color(beautiful.fg_normal)) + + wibox.widget.draw_to_cairo_context(wdg, cr, w, h, context) + + return wibox.widget { + fit = function() + return w, h + end, + draw = function(_, _, cr2) + cr2:set_source_surface(memento) + cr2:paint() + end + } +end -- This is the main widget the tests will use as top level local container = wibox.layout.fixed.vertical() @@ -17,7 +52,7 @@ for _ = 1, 10 do end -- Get the example fallback size (the tests can return a size if the want) -local f_w, f_h = container:fit({dpi=96}, 9999, 9999) +local f_w, f_h = container:fit({dpi=96}, w or 9999, h or 9999) -- There is an overhead that cause testbox "...", add 10 until someone -- figures out the real equation diff --git a/xkb.c b/xkb.c index 40b98f8e2..0ab49a541 100644 --- a/xkb.c +++ b/xkb.c @@ -37,7 +37,8 @@ * Switch keyboard layout. * * @staticfct xkb_set_layout_group - * @tparam integer num keyboard layout number, integer from 0 to 3 + * @tparam integer num Keyboard layout number, integer from 0 to 3 + * @noreturn */ int luaA_xkb_set_layout_group(lua_State *L)