diff --git a/lib/awful/tooltip.lua.in b/lib/awful/tooltip.lua.in
index 0e2ef9353..341426fea 100644
--- a/lib/awful/tooltip.lua.in
+++ b/lib/awful/tooltip.lua.in
@@ -1,21 +1,5 @@
--------------------------------------------------------------------------
--- @author Sébastien Gross <seb•ɱɩɲʋʃ•awesome•ɑƬ•chezwam•ɖɵʈ•org>
--- @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.
+--
-- A tooltip is a small hint displayed when the mouse cursor
-- hovers a specific item.
-- In awesome, a tooltip can be linked with almost any
@@ -47,27 +31,41 @@ local ipairs = ipairs
--
-- Now the same tooltip is only attached to myclock
.
--
--- awful.tooltip
-local tooltip = { mt = {} }
+--
+-- @author Sébastien Gross <seb•ɱɩɲʋʃ•awesome•ɑƬ•chezwam•ɖɵʈ•org>
+-- @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.
--- @name tooltip
+-- @table awful.tooltip
-- @field wibox The wibox displaying the tooltip.
-- @field visible True if tooltip is visible.
--- @class table
+local tooltip = { mt = {} }
--- Tooltip private data.
--- @name awful.tooltip.data
+--- Tooltip private data.
+-- @local
+-- @table awful.tooltip.data
-- @field fg tooltip foreground color.
-- @field font Tooltip font.
-- @field hide The hide() function.
-- @field show The show() function.
-- @field timer The text update timer.
-- @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.
local function place(self)
a_placement.under_mouse(self.wibox)
@@ -119,7 +117,7 @@ end
--- Change displayed text.
-- @param self The tooltip object.
-- @param text New tooltip text.
-local function set_text(self, text)
+tooltip.set_text = function(self, text)
self.textbox:set_text(text)
set_geometry(self)
end
@@ -127,7 +125,7 @@ end
--- Change displayed text.
-- @param self The tooltip object.
-- @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)
set_geometry(self)
end
@@ -135,7 +133,8 @@ end
--- Change the tooltip's update interval.
-- @param self A tooltip object.
-- @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
data[self].timer.timeout = timeout
end
@@ -144,7 +143,7 @@ end
--- Add tooltip to an object.
-- @param self The tooltip.
-- @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::leave", data[self].hide)
end
@@ -152,24 +151,25 @@ end
--- Remove tooltip from an object.
-- @param self The tooltip.
-- @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::leave", data[self].hide)
end
--- Create a new tooltip and link it to a widget.
--- @param args Arguments for tooltip creation may containt:
--- timeout
: The timeout value for update_func.
--- timer_function
: A function to dynamically change the tooltip
--- text.
--- objects
: A list of objects linked to the tooltip.
+-- @tparam table args Arguments for tooltip creation.
+-- @tparam number args.timeout The timeout value for update_func.
+-- @tparam function args.timer_function A function to dynamically change the
+-- tooltip text.
+-- @tparam table args.objects A list of objects linked to the tooltip.
-- @return The created tooltip.
-- @see add_to_object
-- @see set_timeout
-- @see set_text
-- @see set_markup
-local function new(args)
+tooltip.new = function(args)
local self = {
wibox = wibox({ }),
visible = false,
@@ -182,11 +182,11 @@ local function new(args)
}
-- export functions
- self.set_text = set_text
- self.set_markup = set_markup
- self.set_timeout = set_timeout
- self.add_to_object = add_to_object
- self.remove_from_object = remove_from_object
+ self.set_text = tooltip.set_text
+ self.set_markup = tooltip.set_markup
+ self.set_timeout = tooltip.set_timeout
+ self.add_to_object = tooltip.add_to_object
+ self.remove_from_object = tooltip.remove_from_object
-- setup the timer action only if needed
if args.timer_function then
@@ -229,7 +229,7 @@ local function new(args)
end
function tooltip.mt:__call(...)
- return new(...)
+ return tooltip.new(...)
end
return setmetatable(tooltip, tooltip.mt)