Merge pull request #121 from awesomeWM/doc-fix-tooltip

doc: fix/improve markup for awful.tooltip
This commit is contained in:
Daniel Hahler 2015-02-15 13:12:57 +01:00
commit a791e695bb
1 changed files with 42 additions and 42 deletions

View File

@ -1,21 +1,5 @@
-------------------------------------------------------------------------
-- @author Sébastien Gross <seb•ɱɩɲʋʃ•awesome•ɑƬ•chezwam•ɖɵʈ•org&gt
-- @copyright 2009 Sébastien Gross
-- @release @AWESOME_VERSION@
-------------------------------------------------------------------------
local mouse = mouse
local screen = screen
local timer = require("gears.timer")
local wibox = require("wibox")
local a_placement = require("awful.placement")
local beautiful = require("beautiful")
local textbox = require("wibox.widget.textbox")
local background = require("wibox.widget.background")
local setmetatable = setmetatable
local ipairs = ipairs
--- Tooltip module for awesome objects. --- Tooltip module for awesome objects.
--
-- A tooltip is a small hint displayed when the mouse cursor -- A tooltip is a small hint displayed when the mouse cursor
-- hovers a specific item. -- hovers a specific item.
-- In awesome, a tooltip can be linked with almost any -- In awesome, a tooltip can be linked with almost any
@ -47,27 +31,41 @@ local ipairs = ipairs
-- </code> -- </code>
-- Now the same tooltip is only attached to <code>myclock</code>.<br/> -- Now the same tooltip is only attached to <code>myclock</code>.<br/>
-- </p> -- </p>
-- awful.tooltip --
local tooltip = { mt = {} } -- @author Sébastien Gross &lt;seb•ɱɩɲʋʃ•awesome•ɑƬ•chezwam•ɖɵʈ•org&gt
-- @copyright 2009 Sébastien Gross
-- @release @AWESOME_VERSION@
-------------------------------------------------------------------------
local data = setmetatable({}, { __mode = 'k' }) local mouse = mouse
local screen = screen
local timer = require("gears.timer")
local wibox = require("wibox")
local a_placement = require("awful.placement")
local beautiful = require("beautiful")
local textbox = require("wibox.widget.textbox")
local background = require("wibox.widget.background")
local setmetatable = setmetatable
local ipairs = ipairs
--- Tooltip object definition. --- Tooltip object definition.
-- @name tooltip -- @table awful.tooltip
-- @field wibox The wibox displaying the tooltip. -- @field wibox The wibox displaying the tooltip.
-- @field visible True if tooltip is visible. -- @field visible True if tooltip is visible.
-- @class table local tooltip = { mt = {} }
-- Tooltip private data. --- Tooltip private data.
-- @name awful.tooltip.data -- @local
-- @table awful.tooltip.data
-- @field fg tooltip foreground color. -- @field fg tooltip foreground color.
-- @field font Tooltip font. -- @field font Tooltip font.
-- @field hide The hide() function. -- @field hide The hide() function.
-- @field show The show() function. -- @field show The show() function.
-- @field timer The text update timer. -- @field timer The text update timer.
-- @field timer_function The text update timer function. -- @field timer_function The text update timer function.
local data = setmetatable({}, { __mode = 'k' })
-- Place to tooltip on th screen. -- Place the tooltip on the screen.
-- @param self A tooltip object. -- @param self A tooltip object.
local function place(self) local function place(self)
a_placement.under_mouse(self.wibox) a_placement.under_mouse(self.wibox)
@ -119,7 +117,7 @@ end
--- Change displayed text. --- Change displayed text.
-- @param self The tooltip object. -- @param self The tooltip object.
-- @param text New tooltip text. -- @param text New tooltip text.
local function set_text(self, text) tooltip.set_text = function(self, text)
self.textbox:set_text(text) self.textbox:set_text(text)
set_geometry(self) set_geometry(self)
end end
@ -127,7 +125,7 @@ end
--- Change displayed text. --- Change displayed text.
-- @param self The tooltip object. -- @param self The tooltip object.
-- @param text New tooltip text, including pango markup. -- @param text New tooltip text, including pango markup.
local function set_markup(self, text) tooltip.set_markup = function(self, text)
self.textbox:set_markup(text) self.textbox:set_markup(text)
set_geometry(self) set_geometry(self)
end end
@ -135,7 +133,8 @@ end
--- Change the tooltip's update interval. --- Change the tooltip's update interval.
-- @param self A tooltip object. -- @param self A tooltip object.
-- @param timeout The timeout value. -- @param timeout The timeout value.
local function set_timeout(self, timeout) -- @function set_timeout
tooltip.set_timeout = function(self, timeout)
if data[self].timer then if data[self].timer then
data[self].timer.timeout = timeout data[self].timer.timeout = timeout
end end
@ -144,7 +143,7 @@ end
--- Add tooltip to an object. --- Add tooltip to an object.
-- @param self The tooltip. -- @param self The tooltip.
-- @param object An object. -- @param object An object.
local function add_to_object(self, object) tooltip.add_to_object = function(self, object)
object:connect_signal("mouse::enter", data[self].show) object:connect_signal("mouse::enter", data[self].show)
object:connect_signal("mouse::leave", data[self].hide) object:connect_signal("mouse::leave", data[self].hide)
end end
@ -152,24 +151,25 @@ end
--- Remove tooltip from an object. --- Remove tooltip from an object.
-- @param self The tooltip. -- @param self The tooltip.
-- @param object An object. -- @param object An object.
local function remove_from_object(self, object) -- @function remove_from_object
tooltip.remove_from_object = function(self, object)
object:disconnect_signal("mouse::enter", data[self].show) object:disconnect_signal("mouse::enter", data[self].show)
object:disconnect_signal("mouse::leave", data[self].hide) object:disconnect_signal("mouse::leave", data[self].hide)
end end
--- Create a new tooltip and link it to a widget. --- Create a new tooltip and link it to a widget.
-- @param args Arguments for tooltip creation may containt:<br/> -- @tparam table args Arguments for tooltip creation.
-- <code>timeout</code>: The timeout value for update_func.<br/> -- @tparam number args.timeout The timeout value for update_func.
-- <code>timer_function</code>: A function to dynamically change the tooltip -- @tparam function args.timer_function A function to dynamically change the
-- text.<br/> -- tooltip text.
-- <code>objects</code>: A list of objects linked to the tooltip.<br/> -- @tparam table args.objects A list of objects linked to the tooltip.
-- @return The created tooltip. -- @return The created tooltip.
-- @see add_to_object -- @see add_to_object
-- @see set_timeout -- @see set_timeout
-- @see set_text -- @see set_text
-- @see set_markup -- @see set_markup
local function new(args) tooltip.new = function(args)
local self = { local self = {
wibox = wibox({ }), wibox = wibox({ }),
visible = false, visible = false,
@ -182,11 +182,11 @@ local function new(args)
} }
-- export functions -- export functions
self.set_text = set_text self.set_text = tooltip.set_text
self.set_markup = set_markup self.set_markup = tooltip.set_markup
self.set_timeout = set_timeout self.set_timeout = tooltip.set_timeout
self.add_to_object = add_to_object self.add_to_object = tooltip.add_to_object
self.remove_from_object = remove_from_object self.remove_from_object = tooltip.remove_from_object
-- setup the timer action only if needed -- setup the timer action only if needed
if args.timer_function then if args.timer_function then
@ -229,7 +229,7 @@ local function new(args)
end end
function tooltip.mt:__call(...) function tooltip.mt:__call(...)
return new(...) return tooltip.new(...)
end end
return setmetatable(tooltip, tooltip.mt) return setmetatable(tooltip, tooltip.mt)