From 12662d4cb1064b8729ebe0808da36019bfc0537d Mon Sep 17 00:00:00 2001 From: Aire-One Date: Sat, 27 Mar 2021 20:24:30 +0100 Subject: [PATCH] doc(@supermodule): wibox.widget.base doc --- lib/wibox/widget/base.lua | 228 ++++++++++++++++++++++++++++++++++---- 1 file changed, 206 insertions(+), 22 deletions(-) diff --git a/lib/wibox/widget/base.lua b/lib/wibox/widget/base.lua index 57123c71..22da60fe 100644 --- a/lib/wibox/widget/base.lua +++ b/lib/wibox/widget/base.lua @@ -2,6 +2,7 @@ -- @author Uli Schlachter -- @copyright 2010 Uli Schlachter -- @classmod wibox.widget.base +-- @supermodule gears.object --------------------------------------------------------------------------- local object = require("gears.object") @@ -17,6 +18,184 @@ local table = table local base = {} +-- {{{ Properties available on all widgets + +--- Get or set the children elements. +-- @property children +-- @tparam table children The children. +-- @baseclass wibox.widget.base + +--- Get all direct and indirect children widgets. +-- This will scan all containers recursively to find widgets +-- Warning: This method it prone to stack overflow if there is a loop in the +-- 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. +-- @baseclass wibox.widget.base + +--- Force a widget height. +-- @property forced_height +-- @tparam number|nil height The height (`nil` for automatic) +-- @baseclass wibox.widget.base + +--- Force a widget width. +-- @property forced_width +-- @tparam number|nil width The width (`nil` for automatic) +-- @baseclass wibox.widget.base + +--- The widget opacity (transparency). +-- @property opacity +-- @tparam[opt=1] number opacity The opacity (between 0 and 1) +-- @baseclass wibox.widget.base + +--- The widget visibility. +-- @property visible +-- @param boolean +-- @baseclass wibox.widget.base + +--- The widget buttons. +-- +-- The table contains a list of `awful.button` objects. +-- @property buttons +-- @param table +-- @see awful.button +-- @baseclass wibox.widget.base + +-- }}} + +-- {{{ Signals available on the widgets. + +--- When the layout (size) change. +-- This signal is emitted when the previous results of `:layout()` and `:fit()` +-- are no longer valid. Unless this signal is emitted, `:layout()` and `:fit()` +-- must return the same result when called with the same arguments. +-- @signal widget::layout_changed +-- @see widget::redraw_needed +-- @baseclass wibox.widget.base + +--- When the widget content changed. +-- This signal is emitted when the content of the widget changes. The widget will +-- be redrawn, it is not re-layouted. Put differently, it is assumed that +-- `:layout()` and `:fit()` would still return the same results as before. +-- @signal widget::redraw_needed +-- @see widget::layout_changed +-- @baseclass wibox.widget.base + +--- When a mouse button is pressed over the widget. +-- @signal button::press +-- @tparam table self The current object instance itself. +-- @tparam number lx The horizontal position relative to the (0,0) position in +-- the widget. +-- @tparam number ly The vertical position relative to the (0,0) position in the +-- widget. +-- @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. +-- @tparam wibox.drawable find_widgets_result.drawable The drawable containing +-- the widget. +-- @tparam widget find_widgets_result.widget The widget being displayed. +-- @tparam wibox.hierarchy find_widgets_result.hierarchy The hierarchy +-- managing the widget's geometry. +-- @tparam number find_widgets_result.x An approximation of the X position that +-- the widget is visible at on the surface. +-- @tparam number find_widgets_result.y An approximation of the Y position that +-- the widget is visible at on the surface. +-- @tparam number find_widgets_result.width An approximation of the width that +-- the widget is visible at on the surface. +-- @tparam number find_widgets_result.height An approximation of the height that +-- the widget is visible at on the surface. +-- @tparam number find_widgets_result.widget_width The exact width of the widget +-- in its local coordinate system. +-- @tparam number find_widgets_result.widget_height The exact height of the widget +-- in its local coordinate system. +-- @see mouse +-- @baseclass wibox.widget.base + +--- When a mouse button is released over the widget. +-- @signal button::release +-- @tparam table self The current object instance itself. +-- @tparam number lx The horizontal position relative to the (0,0) position in +-- the widget. +-- @tparam number ly The vertical position relative to the (0,0) position in the +-- widget. +-- @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. +-- @tparam wibox.drawable find_widgets_result.drawable The drawable containing +-- the widget. +-- @tparam widget find_widgets_result.widget The widget being displayed. +-- @tparam wibox.hierarchy find_widgets_result.hierarchy The hierarchy +-- managing the widget's geometry. +-- @tparam number find_widgets_result.x An approximation of the X position that +-- the widget is visible at on the surface. +-- @tparam number find_widgets_result.y An approximation of the Y position that +-- the widget is visible at on the surface. +-- @tparam number find_widgets_result.width An approximation of the width that +-- the widget is visible at on the surface. +-- @tparam number find_widgets_result.height An approximation of the height that +-- the widget is visible at on the surface. +-- @tparam number find_widgets_result.widget_width The exact width of the widget +-- in its local coordinate system. +-- @tparam number find_widgets_result.widget_height The exact height of the widget +-- in its local coordinate system. +-- @see mouse +-- @baseclass wibox.widget.base + +--- When the mouse enter a widget. +-- @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. +-- @tparam wibox.drawable find_widgets_result.drawable The drawable containing +-- the widget. +-- @tparam widget find_widgets_result.widget The widget being displayed. +-- @tparam wibox.hierarchy find_widgets_result.hierarchy The hierarchy +-- managing the widget's geometry. +-- @tparam number find_widgets_result.x An approximation of the X position that +-- the widget is visible at on the surface. +-- @tparam number find_widgets_result.y An approximation of the Y position that +-- the widget is visible at on the surface. +-- @tparam number find_widgets_result.width An approximation of the width that +-- the widget is visible at on the surface. +-- @tparam number find_widgets_result.height An approximation of the height that +-- the widget is visible at on the surface. +-- @tparam number find_widgets_result.widget_width The exact width of the widget +-- in its local coordinate system. +-- @tparam number find_widgets_result.widget_height The exact height of the widget +-- in its local coordinate system. +-- @see mouse +-- @baseclass wibox.widget.base + +--- When the mouse leave a widget. +-- @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. +-- @tparam wibox.drawable find_widgets_result.drawable The drawable containing +-- the widget. +-- @tparam widget find_widgets_result.widget The widget being displayed. +-- @tparam wibox.hierarchy find_widgets_result.hierarchy The hierarchy +-- managing the widget's geometry. +-- @tparam number find_widgets_result.x An approximation of the X position that +-- the widget is visible at on the surface. +-- @tparam number find_widgets_result.y An approximation of the Y position that +-- the widget is visible at on the surface. +-- @tparam number find_widgets_result.width An approximation of the width that +-- the widget is visible at on the surface. +-- @tparam number find_widgets_result.height An approximation of the height that +-- the widget is visible at on the surface. +-- @tparam number find_widgets_result.widget_width The exact width of the widget +-- in its local coordinate system. +-- @tparam number find_widgets_result.widget_height The exact height of the widget +-- in its local coordinate system. +-- @see mouse +-- @baseclass wibox.widget.base + +-- }}} + -- {{{ Functions on widgets -- Functions available on all widgets. @@ -30,7 +209,7 @@ end, true) --- Set a widget's visibility. -- @tparam boolean b Whether the widget is visible. --- @method set_visible +-- @method wibox.widget.base:set_visible function base.widget:set_visible(b) if b ~= self._private.visible then self._private.visible = b @@ -42,6 +221,7 @@ end --- Add a new `awful.button` to this widget. -- @tparam awful.button button The button to add. +-- @method wibox.widget.base:add_button function base.widget:add_button(button) if not button then return end @@ -65,7 +245,7 @@ end --- Is the widget visible? -- @treturn boolean --- @method get_visible +-- @method wibox.widget.base:get_visible function base.widget:get_visible() return self._private.visible or false end @@ -73,7 +253,7 @@ end --- Set a widget's opacity. -- @tparam number o The opacity to use (a number from 0 (transparent) to 1 -- (opaque)). --- @method set_opacity +-- @method wibox.widget.base:set_opacity function base.widget:set_opacity(o) if o ~= self._private.opacity then self._private.opacity = o @@ -83,7 +263,7 @@ end --- Get the widget's opacity. -- @treturn number The opacity (between 0 (transparent) and 1 (opaque)). --- @method get_opacity +-- @method wibox.widget.base:get_opacity function base.widget:get_opacity() return self._private.opacity end @@ -91,8 +271,8 @@ end --- Set the widget's forced width. -- @tparam[opt] number width With `nil` the default mechanism of calling the -- `:fit` method is used. --- @see fit_widget --- @method set_forced_width +-- @see wibox.widget.base:fit_widget +-- @method wibox.widget.base:set_forced_width function base.widget:set_forced_width(width) if width ~= self._private.forced_width then self._private.forced_width = width @@ -108,7 +288,7 @@ end -- actual size is during a `mouse::enter`, `mouse::leave` or button event. -- @treturn[opt] number The forced width (nil if automatic). -- @see fit_widget --- @method get_forced_width +-- @method wibox.widget.base:get_forced_width function base.widget:get_forced_width() return self._private.forced_width end @@ -116,8 +296,8 @@ end --- Set the widget's forced height. -- @tparam[opt] number height With `nil` the default mechanism of calling the -- `:fit` method is used. --- @see fit_widget --- @method set_height +-- @see wibox.widget.base:fit_widget +-- @method wibox.widget.base:set_height function base.widget:set_forced_height(height) if height ~= self._private.forced_height then self._private.forced_height = height @@ -132,7 +312,7 @@ end -- If there is no forced width/height, then the only way to get the widget's -- actual size is during a `mouse::enter`, `mouse::leave` or button event. -- @treturn[opt] number The forced height (nil if automatic). --- @method get_forced_height +-- @method wibox.widget.base:get_forced_height function base.widget:get_forced_height() return self._private.forced_height end @@ -141,7 +321,7 @@ end -- -- This method should be re-implemented by the relevant widgets. -- @treturn table children The children. --- @method get_children +-- @method wibox.widget.base:get_children function base.widget:get_children() return {} end @@ -151,7 +331,7 @@ end -- The default implementation does nothing, this must be re-implemented by -- all layout and container widgets. -- @tparam table children A table composed of valid widgets. --- @method set_children +-- @method wibox.widget.base:set_children function base.widget:set_children(children) -- luacheck: no unused -- Nothing on purpose end @@ -171,7 +351,7 @@ end -- *Warning*: This method it prone to stack overflow if the widget, or any of -- its children, contains (directly or indirectly) itself. -- @treturn table children The children. --- @method get_all_children +-- @method wibox.widget.base:get_all_children function base.widget:get_all_children() local ret = {} digg_children(ret, self) @@ -197,8 +377,10 @@ function base.set_widget_common(self, widget) end --- Emit a signal and ensure all parent widgets in the hierarchies also --- forward the signal. This is useful to track signals when there is a dynamic --- set of containers and layouts wrapping the widget. +-- forward the signal. +-- +-- This is useful to track signals when there is a dynamic set of containers +-- and layouts wrapping the widget. -- -- Note that this function has some flaws: -- @@ -213,7 +395,7 @@ end -- -- @tparam string signal_name -- @param ... Other arguments --- @method emit_signal_recursive +-- @method wibox.widget.base:emit_signal_recursive function base.widget:emit_signal_recursive(signal_name, ...) -- This is a convenience wrapper, the real implementation is in the -- hierarchy. @@ -223,12 +405,14 @@ end --- Get the index of a widget. -- @tparam widget widget The widget to look for. --- @tparam[opt] boolean recursive Also check sub-widgets? --- @tparam[opt] widget ... Additional widgets to add at the end of the "path" --- @treturn number The index. +-- @tparam[opt] boolean recursive Recursively check accross the sub-widgets +-- hierarchy. +-- @tparam[opt] widget ... Additional widgets to add at the end of the +-- sub-widgets hierarchy "path". +-- @treturn number The widget index. -- @treturn widget The parent widget. --- @treturn table The path between "self" and "widget". --- @method index +-- @treturn table The hierarchy path between "self" and "widget". +-- @method wibox.widget.base:index function base.widget:index(widget, recursive, ...) local widgets = self:get_children() for idx, w in ipairs(widgets) do @@ -577,7 +761,7 @@ end -- -- See [The declarative layout system](../documentation/03-declarative-layout.md.html). -- @tparam table args A table containing the widget's disposition. --- @method setup +-- @method wibox.widget.base:setup function base.widget:setup(args) local f,ids = self.set_widget or self.add or self.set_first,{} local w, id = drill(ids, args)