wibox: Move the documentation to a shared file

To be re-used by wibars, tooltips and menus

docs/common/wibox.ldoc

@@ -0,0 +1,224 @@
+--- Border width.
+--
+-- **Signal:**
+--
+--  * *property::border_width*
+--
+-- @property border_width
+-- @param integer
+
+--- Border color.
+--
+-- Please note that this property only support string based 24 bit or 32 bit
+-- colors:
+--
+--    Red Blue
+--     _|  _|
+--    #FF00FF
+--       T‾
+--     Green
+--
+--
+--    Red Blue
+--     _|  _|
+--    #FF00FF00
+--       T‾  ‾T
+--    Green   Alpha
+--
+-- **Signal:**
+--
+--  * *property::border_color*
+--
+-- @property border_color
+-- @param string
+
+--- On top of other windows.
+--
+-- **Signal:**
+--
+--  * *property::ontop*
+--
+-- @property ontop
+-- @param boolean
+
+--- The mouse cursor.
+--
+-- **Signal:**
+--
+--  * *property::cursor*
+--
+-- @property cursor
+-- @param string
+-- @see mouse
+
+--- Visibility.
+--
+-- **Signal:**
+--
+--  * *property::visible*
+--
+-- @property visible
+-- @param boolean
+
+--- The opacity of the wibox, between 0 and 1.
+--
+-- **Signal:**
+--
+--  * *property::opacity*
+--
+-- @property opacity
+-- @tparam number opacity (between 0 and 1)
+
+--- The window type (desktop, normal, dock, ...).
+--
+-- **Signal:**
+--
+--  * *property::type*
+--
+-- @property type
+-- @param string
+-- @see client.type
+
+--- The x coordinates.
+--
+-- **Signal:**
+--
+--  * *property::x*
+--
+-- @property x
+-- @param integer
+
+--- The y coordinates.
+--
+-- **Signal:**
+--
+--  * *property::y*
+--
+-- @property y
+-- @param integer
+
+--- The width of the wibox.
+--
+-- **Signal:**
+--
+--  * *property::width*
+--
+-- @property width
+-- @param width
+
+--- The height of the wibox.
+--
+-- **Signal:**
+--
+--  * *property::height*
+--
+-- @property height
+-- @param height
+
+--- The wibox screen.
+--
+-- @property screen
+-- @param screen
+
+---  The wibox's `drawable`.
+--
+-- **Signal:**
+--
+--  * *property::drawable*
+--
+-- @property drawable
+-- @tparam drawable drawable
+
+--- The widget that the `wibox` displays.
+-- @property widget
+-- @param widget
+
+--- The X window id.
+--
+-- **Signal:**
+--
+--  * *property::window*
+--
+-- @property window
+-- @param string
+-- @see client.window
+
+--- The wibox's bounding shape as a (native) cairo surface.
+--
+-- **Signal:**
+--
+--  * *property::shape_bounding*
+--
+-- @property shape_bounding
+-- @param surface._native
+
+--- The wibox's clip shape as a (native) cairo surface.
+--
+-- **Signal:**
+--
+--  * *property::shape_clip*
+--
+-- @property shape_clip
+-- @param surface._native
+
+--- Get or set mouse buttons bindings to a wibox.
+--
+-- @param buttons_table A table of buttons objects, or nothing.
+-- @function wibox.buttons
+
+--- Get or set wibox geometry. That's the same as accessing or setting the x,
+-- y, width or height properties of a wibox.
+--
+-- @param A table with coordinates to modify.
+-- @return A table with wibox coordinates and geometry.
+-- @function wibox.geometry
+
+--- Get or set wibox struts.
+--
+-- @param strut A table with new strut, or nothing
+-- @return The wibox strut in a table.
+-- @function wibox.struts
+-- @see client.struts
+
+--- The default background color.
+-- @beautiful beautiful.bg_normal
+-- @see bg
+
+--- The default foreground (text) color.
+-- @beautiful beautiful.fg_normal
+-- @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
+-- @name setup
+-- @class function
+
+--- The background of the wibox.
+-- @param c The background to use. This must either be a cairo pattern object,
+--   nil or a string that gears.color() understands.
+-- @property bg
+-- @see gears.color
+
+--- The background image of the drawable.
+-- 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.
+-- @param image A background image or a function
+-- @property bgimage
+-- @see gears.surface
+
+--- The foreground (text) of the wibox.
+-- @param c The foreground to use. This must either be a cairo pattern object,
+--   nil or a string that gears.color() understands.
+-- @property fg
+-- @see gears.color
+
+--- Find a widget by a point.
+-- The wibox must have drawn itself at least once for this to work.
+-- @tparam number x X coordinate of the point
+-- @tparam number y Y coordinate of the point
+-- @treturn table A sorted table of widgets positions. The first element is the biggest
+-- container while the last is the topmost widget. The table contains *x*, *y*,
+-- *width*, *height* and *widget*.
+-- @name find_widgets
+-- @class function

lib/wibox/init.lua

@@ -33,239 +33,30 @@ local force_forward = {
     shape_clip = true,
 }
 
---- Set the widget that the wibox displays
+--@DOC_wibox_COMMON@
+
 function wibox:set_widget(widget)
     self._drawable:set_widget(widget)
 end
 
--- Import some drawin documentation
+function wibox:get_widget()
+    return self._drawable.widget
+end
 
---- Border width.
---
--- **Signal:**
---
---  * *property::border_width*
---
--- @property border_width
--- @param integer
-
---- Border color.
---
--- Please note that this property only support string based 24 bit or 32 bit
--- colors:
---
---    Red Blue
---     _|  _|
---    #FF00FF
---       T‾
---     Green
---
---
---    Red Blue
---     _|  _|
---    #FF00FF00
---       T‾  ‾T
---    Green   Alpha
---
--- **Signal:**
---
---  * *property::border_color*
---
--- @property border_color
--- @param string
-
---- On top of other windows.
---
--- **Signal:**
---
---  * *property::ontop*
---
--- @property ontop
--- @param boolean
-
---- The mouse cursor.
---
--- **Signal:**
---
---  * *property::cursor*
---
--- @property cursor
--- @param string
--- @see mouse
-
---- Visibility.
---
--- **Signal:**
---
---  * *property::visible*
---
--- @property visible
--- @param boolean
-
---- The opacity of the wibox, between 0 and 1.
---
--- **Signal:**
---
---  * *property::opacity*
---
--- @property opacity
--- @tparam number opacity (between 0 and 1)
-
---- The window type (desktop, normal, dock, ...).
---
--- **Signal:**
---
---  * *property::type*
---
--- @property type
--- @param string
--- @see client.type
-
---- The x coordinates.
---
--- **Signal:**
---
---  * *property::x*
---
--- @property x
--- @param integer
-
---- The y coordinates.
---
--- **Signal:**
---
---  * *property::y*
---
--- @property y
--- @param integer
-
---- The width of the wibox.
---
--- **Signal:**
---
---  * *property::width*
---
--- @property width
--- @param width
-
---- The height of the wibox.
---
--- **Signal:**
---
---  * *property::height*
---
--- @property height
--- @param height
-
----  The wibox's `drawable`.
---
--- **Signal:**
---
---  * *property::drawable*
---
--- @property drawable
--- @tparam drawable drawable
-
---- The X window id.
---
--- **Signal:**
---
---  * *property::window*
---
--- @property window
--- @param string
--- @see client.window
-
---- The wibox's bounding shape as a (native) cairo surface.
---
--- **Signal:**
---
---  * *property::shape_bounding*
---
--- @property shape_bounding
--- @param surface._native
-
---- The wibox's clip shape as a (native) cairo surface.
---
--- **Signal:**
---
---  * *property::shape_clip*
---
--- @property shape_clip
--- @param surface._native
-
---- Get or set mouse buttons bindings to a wibox.
---
--- @param buttons_table A table of buttons objects, or nothing.
--- @function wibox.buttons
-
---- Get or set wibox geometry. That's the same as accessing or setting the x,
--- y, width or height properties of a wibox.
---
--- @param A table with coordinates to modify.
--- @return A table with wibox coordinates and geometry.
--- @function wibox.geometry
-
---- Get or set wibox struts.
---
--- @param strut A table with new strut, or nothing
--- @return The wibox strut in a table.
--- @function wibox.struts
--- @see client.struts
-
---- The default background color.
--- @beautiful beautiful.bg_normal
--- @see bg
-
---- The default foreground (text) color.
--- @beautiful beautiful.fg_normal
--- @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
--- @name setup
--- @class function
 wibox.setup = base.widget.setup
 
---- The background of the wibox.
--- @param c The background to use. This must either be a cairo pattern object,
---   nil or a string that gears.color() understands.
--- @property bg
--- @see gears.color
-
 function wibox:set_bg(c)
     self._drawable:set_bg(c)
 end
 
---- The background image of the drawable.
--- 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.
--- @param image A background image or a function
--- @property bgimage
--- @see gears.surface
-
 function wibox:set_bgimage(image, ...)
     self._drawable:set_bgimage(image, ...)
 end
 
---- The foreground (text) of the wibox.
--- @param c The foreground to use. This must either be a cairo pattern object,
---   nil or a string that gears.color() understands.
--- @property fg
--- @see gears.color
-
 function wibox:set_fg(c)
     self._drawable:set_fg(c)
 end
 
---- Find a widget by a point.
--- The wibox must have drawn itself at least once for this to work.
--- @tparam number x X coordinate of the point
--- @tparam number y Y coordinate of the point
--- @treturn table A sorted table of widgets positions. The first element is the biggest
--- container while the last is the topmost widget. The table contains *x*, *y*,
--- *width*, *height* and *widget*.
 function wibox:find_widgets(x, y)
     return self._drawable:find_widgets(x, y)
 end