doc(@supermodule): wibox.widget.base doc
This commit is contained in:
parent
3a6fa10754
commit
12662d4cb1
|
|
@ -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)
|
||||
|
|
|
|||
Loading…
Reference in New Issue