awesomewm-mirrors
/
awesome
mirror of https://github.com/awesomeWM/awesome.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

doc: Use an explicit tag for all static functions. 

This way their name doesn't get mangle by the broken magic. It will also
eventually allow to `error()` in the template when the implicit
`@function` is used.

This commit also fixes a large number of issues found while
proof-reading everything.
This commit is contained in:
Emmanuel Lepage Vallee 2019-06-07 19:08:05 -04:00
parent 11d7a614d9
commit b4ece0f053
83 changed files with 586 additions and 370 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/common/cobject.ldoc
View File

@ -3,7 +3,7 @@
/** Disconnect from a signal.
* @tparam string name The name of the signal.
* @tparam function func The callback that should be disconnected.
* @function disconnect_signal
* @staticfct disconnect_signal
*/
/** Emit a signal.
@ -12,13 +12,13 @@
* @param ... Extra arguments for the callback functions. Each connected
* function receives the object as first argument and then any extra
* arguments that are given to emit_signal().
* @function emit_signal
* @staticfct emit_signal
*/
/** Connect to a signal.
* @tparam string name The name of the signal.
* @tparam function func The callback to call when the signal is emitted.
* @function connect_signal
* @staticfct connect_signal
*/
/*

42
docs/config.ld
View File

@ -56,6 +56,9 @@ tparam_alias('screen_or_idx', 'screen|int')
new_type("constructorfct", "Constructors", false, "Parameters")
-- Hack to get the functions on top of the signals and properties
new_type("function", "Functions", false, "Parameters")
-- For "classes", use an explicit type for static functions. This allows
-- @function and its implicit cousin to be banned in the CI.
new_type("staticfct", "Static module functions", false, "Parameters")
-- Documentation for objects properties
new_type("property", "Object properties", false, "Type")
-- Documentation for objects deprecated properties
@ -141,6 +144,7 @@ file = {
'../lib/wibox/container/init.lua',
'../lib/naughty/constants.lua',
'../lib/naughty/dbus.lua',
'../lib/beautiful/gtk.lua',
-- Ignore some parts of the widget library
'../lib/awful/widget/init.lua',
@ -189,7 +193,23 @@ local coreclassmap = {
mouse = "mouse<span class='listplusign'> and awful.mouse</span>",
}
-- Add the full module name in front.
local add_mod = {
["function"] = true,
constructorfct = true,
staticfct = true,
deprecated = true,
}
-- Add the arguments.
local add_args = {
constructorfct = true,
staticfct = true,
}
custom_display_name_handler = function(item, default_handler)
local ret = default_handler(item)
-- Remove the "namespace" from the signals and properties
if no_prefix[item.type] then
local name = item.name:match("%.([^.]+)$")
@ -201,15 +221,22 @@ custom_display_name_handler = function(item, default_handler)
return coreclassmap[item.name]
end
-- Undocumented API to make the libraries and classmod "function" section
-- more consistent. Right now some have their full awful.foo.bar while other
-- have "just" `bar`. Given we use constructors from metatables, we have no
-- choice but to use the full function name. It also makes copy/paste easier.
if add_mod[item.type] and (not ret:find(".", 1, true)) and (not ret:find(":", 1, true)) then
ret = item.module.name .. "." .. ret
end
if item.type == "deprecated" or item.type == "deprecatedproperty" then
return default_handler(item) .. "<i class=\"deprecated_label\"> [deprecated]</i>"
return ret .. "<i class=\"deprecated_label\"> [deprecated]</i>"
end
if item.type == "method" then
return render_methods(item)
end
local ret = default_handler(item)
-- Get rid of the "module:" in front of method names. It is either wrong or
-- just redundant.
@ -221,17 +248,8 @@ custom_display_name_handler = function(item, default_handler)
return ret:gsub("^module", item.module.name)
end
-- Undocumented API to make the libraries and classmod "function" section
-- more consistent. Right now some have their full awful.foo.bar while other
-- have "just" `bar`. Given we use constructors from metatables, we have no
-- choice but to use the full function name. It also makes copy/paste easier.
if (item.type == "function" or item.type == "constructorfct")
and (not ret:find(".", 1, true)) and (not ret:find(":", 1, true)) then
ret = item.module.name .. "." .. ret
end
-- It isn't there by default.
if item.type == "constructorfct" then
if add_args[item.type] then
ret = ret .. " " .. item.args
end

34
lib/awful/client.lua
View File

@ -239,7 +239,7 @@ end
--- Get a client by its relative index to another client.
-- If no client is passed, the focused client will be used.
--
-- @function awful.client.next
-- @staticfct awful.client.next
-- @tparam int i The index. Use 1 to get the next, -1 to get the previous.
-- @client[opt] sel The client.
-- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom)
@ -274,7 +274,7 @@ function client.next(i, sel, stacked)
end
--- Swap a client with another client in the given direction.
-- @function awful.client.swap.bydirection
-- @staticfct awful.client.swap.bydirection
-- @tparam string dir The direction, can be either "up", "down", "left" or "right".
-- @client[opt=focused] c The client.
-- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom)
@ -295,8 +295,9 @@ function client.swap.bydirection(dir, c, stacked)
end
end
--- Swap a client with another client in the given direction. Swaps across screens.
-- @function awful.client.swap.global_bydirection
--- Swap a client with another client in the given direction.
-- Swaps across screens.
-- @staticfct awful.client.swap.global_bydirection
-- @param dir The direction, can be either "up", "down", "left" or "right".
-- @client[opt] sel The client.
function client.swap.global_bydirection(dir, sel)
@ -329,7 +330,7 @@ function client.swap.global_bydirection(dir, sel)
end
--- Swap a client by its relative index.
-- @function awful.client.swap.byidx
-- @staticfct awful.client.swap.byidx
-- @param i The index.
-- @client[opt] c The client, otherwise focused one is used.
function client.swap.byidx(i, c)
@ -342,7 +343,7 @@ end
--- Cycle clients.
--
-- @function awful.client.cycle
-- @staticfct awful.client.cycle
-- @param clockwise True to cycle clients clockwise.
-- @param[opt] s The screen where to cycle clients.
-- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom)
@ -886,7 +887,7 @@ end
--- Restore (=unminimize) a random client.
-- @function awful.client.restore
-- @staticfct awful.client.restore
-- @param s The screen to use.
-- @return The restored client if some client was restored, otherwise nil.
function client.restore(s)
@ -907,7 +908,7 @@ function client.restore(s)
return nil
end
--- Normalize a set of numbers to 1
--- Normalize a set of numbers to 1.
-- @param set the set of numbers to normalize
-- @param num the number of numbers to normalize
local function normalize(set, num)
@ -1204,7 +1205,7 @@ end
--- Set a client property to be persistent across restarts (via X properties).
--
-- @function awful.client.property.persist
-- @staticfct awful.client.property.persist
-- @param prop The property name.
-- @param kind The type (used for register_xproperty).
-- One of "string", "number" or "boolean".
@ -1221,16 +1222,17 @@ function client.property.persist(prop, kind)
end
end
---
-- Returns an iterator to cycle through, starting from the client in focus or
-- the given index, all clients that match a given criteria.
--- Returns an iterator to cycle through clients.
--
-- Starting from the client in focus or the given index, all clients that match
-- a given criteria.
--
-- @param filter a function that returns true to indicate a positive match
-- @param start what index to start iterating from. Defaults to using the
-- index of the currently focused client.
-- @param s which screen to use. nil means all screens.
--
-- @function awful.client.iterate
-- @staticfct awful.client.iterate
-- @usage -- un-minimize all urxvt instances
-- local urxvt = function (c)
-- return awful.rules.match(c, {class = "URxvt"})
@ -1387,7 +1389,7 @@ do
-- See `awful.client.focus.history.enable_tracking` to enable it again.
-- @treturn int The internal value of `disabled_count` (calls to this
-- function without calling `awful.client.focus.history.enable_tracking`).
-- @function awful.client.focus.history.disable_tracking
-- @staticfct awful.client.focus.history.disable_tracking
function client.focus.history.disable_tracking()
disabled_count = disabled_count + 1
if disabled_count == 1 then
@ -1401,7 +1403,7 @@ do
-- This is the default, but can be disabled
-- through `awful.client.focus.history.disable_tracking`.
-- @treturn boolean True if history tracking has been enabled.
-- @function awful.client.focus.history.enable_tracking
-- @staticfct awful.client.focus.history.enable_tracking
function client.focus.history.enable_tracking()
assert(disabled_count > 0)
disabled_count = disabled_count - 1
@ -1414,7 +1416,7 @@ do
--- Is history tracking enabled?
-- @treturn bool True if history tracking is enabled.
-- @treturn int The number of times that tracking has been disabled.
-- @function awful.client.focus.history.is_enabled
-- @staticfct awful.client.focus.history.is_enabled
function client.focus.history.is_enabled()
return disabled_count == 0, disabled_count
end

3
lib/awful/completion.lua
View File

@ -32,6 +32,7 @@ local bashcomp_src = "@SYSCONFDIR@/bash_completion"
--- Enable programmable bash completion in awful.completion.bash at the price of
-- a slight overhead.
-- @param src The bash completion source file, /etc/bash_completion by default.
-- @staticfct awful.completion.bashcomp_load
function completion.bashcomp_load(src)
if src then bashcomp_src = src end
local c, err = io.popen("/usr/bin/env bash -c 'source " .. bashcomp_src .. "; complete -p'")
@ -70,6 +71,7 @@ completion.default_shell = nil
-- @treturn string The new command.
-- @treturn number The new cursor position.
-- @treturn table The table with all matches.
-- @staticfct awful.completion.shell
function completion.shell(command, cur_pos, ncomp, shell)
local wstart = 1
local wend = 1
@ -192,6 +194,7 @@ end
-- @param ncomp The number of yet requested completion using current text.
-- @param keywords The keywords table uised for completion.
-- @return The new match, the new cursor position, the table of all matches.
-- @staticfct awful.completion.generic
function completion.generic(text, cur_pos, ncomp, keywords) -- luacheck: no unused args
-- The keywords table may be empty
if #keywords == 0 then

3
lib/awful/ewmh.lua
View File

@ -54,6 +54,7 @@ local ewmh = {
--- Update a client's settings when its geometry changes, skipping signals
-- resulting from calls within.
local repair_geometry_lock = false
local function repair_geometry(window)
if repair_geometry_lock then return end
repair_geometry_lock = true
@ -166,6 +167,7 @@ end
-- @see generic_activate_filters
-- @see contextual_activate_filters
-- @see remove_activate_filter
-- @staticfct awful.ewmh.add_activate_filter
function ewmh.add_activate_filter(f, context)
if not context then
table.insert(ewmh.generic_activate_filters, f)
@ -185,6 +187,7 @@ end
-- @see generic_activate_filters
-- @see contextual_activate_filters
-- @see add_activate_filter
-- @staticfct awful.ewmh.remove_activate_filter
function ewmh.remove_activate_filter(f, context)
local tab = context and (ewmh.contextual_activate_filters[context] or {})
or ewmh.generic_activate_filters

2
lib/awful/hotkeys_popup/init.lua
View File

@ -24,7 +24,7 @@ local hotkeys_popup = {
-- @tparam[opt] screen s The screen.
-- @tparam[opt=true] boolean show_args.show_awesome_keys Show AwesomeWM hotkeys.
-- When set to `false` only app-specific hotkeys will be shown.
-- @function awful.hotkeys_popup.show_help
-- @staticfct awful.hotkeys_popup.show_help
-- @see awful.hotkeys_popup.widget.show_help
hotkeys_popup.show_help = hotkeys_popup.widget.show_help

6
lib/awful/hotkeys_popup/widget.lua
View File

@ -490,6 +490,7 @@ function widget.new(args)
-- @tparam[opt] table show_args Additional arguments.
-- @tparam[opt=true] boolean show_args.show_awesome_keys Show AwesomeWM hotkeys.
-- When set to `false` only app-specific hotkeys will be shown.
-- @method show_help
function widget_instance:show_help(c, s, show_args)
show_args = show_args or {}
local show_awesome_keys = show_args.show_awesome_keys ~= false
@ -549,6 +550,7 @@ function widget.new(args)
--- Add hotkey descriptions for third-party applications.
-- @tparam table hotkeys Table with bindings,
-- see `awful.hotkeys_popup.key.vim` as an example.
-- @method add_hotkeys
function widget_instance:add_hotkeys(hotkeys)
for group, bindings in pairs(hotkeys) do
for _, binding in ipairs(bindings) do
@ -571,6 +573,7 @@ function widget.new(args)
-- @tparam string group hotkeys group name,
-- @tparam table data rule data for the group
-- see `awful.hotkeys_popup.key.vim` as an example.
-- @method add_group_rules
function widget_instance:add_group_rules(group, data)
self.group_rules[group] = data
end
@ -591,6 +594,7 @@ end
-- @tparam[opt] table args Additional arguments.
-- @tparam[opt=true] boolean args.show_awesome_keys Show AwesomeWM hotkeys.
-- When set to `false` only app-specific hotkeys will be shown.
-- @staticfct awful.hotkeys_popup.widget.show_help
function widget.show_help(...)
return get_default_widget():show_help(...)
end
@ -599,6 +603,7 @@ end
-- (default widget instance will be used).
-- @tparam table hotkeys Table with bindings,
-- see `awful.hotkeys_popup.key.vim` as an example.
-- @staticfct awful.hotkeys_popup.widget.add_hotkeys
function widget.add_hotkeys(...)
return get_default_widget():add_hotkeys(...)
end
@ -608,6 +613,7 @@ end
-- @tparam string group rule group name,
-- @tparam table data rule data for the group
-- see `awful.hotkeys_popup.key.vim` as an example.
-- @staticfct awful.hotkeys_popup.widget.add_group_rules
function widget.add_group_rules(group, data)
return get_default_widget():add_group_rules(group, data)
end

5
lib/awful/key.lua
View File

@ -3,7 +3,7 @@
--
-- @author Julien Danjou &lt;julien@danjou.info&gt;
-- @copyright 2009 Julien Danjou
-- @module awful.key
-- @classmod awful.key
---------------------------------------------------------------------------
-- Grab environment we need
@ -59,6 +59,7 @@ capi.awesome.connect_signal("xkb::map_changed" , function() conversion = nil en
-- @tparam table mod A modified table. Valid modifiers are: Any, Mod1,
-- Mod2, Mod3, Mod4, Mod5, Shift, Lock and Control.
-- @tparam string k The key
-- @staticfct awful.key.execute
function key.execute(mod, k)
local modmap = generate_conversion_map()
local active = capi.awesome._active_modifiers
@ -111,6 +112,7 @@ end
-- @tparam table data User data for key,
-- for example {description="select next tag", group="tag"}.
-- @treturn table A table with one or several key objects.
-- @constructorfct awful.key
function key.new(mod, _key, press, release, data)
if type(release)=='table' then
data=release
@ -145,6 +147,7 @@ end
-- @param _key The key object.
-- @param pressed_mod The modifiers to compare with.
-- @param pressed_key The key to compare with.
-- @staticfct awful.key.match
function key.match(_key, pressed_mod, pressed_key)
-- First, compare key.
if pressed_key ~= _key.key then return false end

20
lib/awful/keygrabber.lua
View File

@ -724,16 +724,6 @@ function keygrab.run_with_keybindings(args)
return ret
end
--- Run a grabbing function.
--
-- Calling this is equivalent to `keygrabber.run`.
--
-- @param g The key grabber callback that will get the key events until it
-- will be deleted or a new grabber is added.
-- @return the given callback `g`.
--
-- @deprecated awful.keygrabber.run
--- A lower level API to interact with the keygrabber directly.
--
-- Grab keyboard input and read pressed keys, calling the least callback
@ -750,7 +740,7 @@ end
--
-- Here is the content of the modifier table:
--
-- <table>
-- <table class='widget_list' border=1>
-- <tr style='font-weight: bold;'>
-- <th align='center'>Modifier name </th>
-- <th align='center'>Key name</th>
@ -785,7 +775,7 @@ end
-- end
-- end)
-- end
-- @function awful.keygrabber.run
-- @deprecated awful.keygrabber.run
function keygrab.run(g)
-- Remove the grabber if it is in the stack.
keygrab.stop(g)
@ -807,7 +797,7 @@ end
local signals = {}
--- Connect to a signal for all keygrabbers at once.
-- @function awful.keygrabber.connect_signal
-- @staticfct awful.keygrabber.connect_signal
-- @tparam string name The signal name.
-- @tparam function callback The callback.
function keygrab.connect_signal(name, callback)
@ -820,7 +810,7 @@ function keygrab.connect_signal(name, callback)
end
--- Disconnect to a signal for all keygrabbers at once.
-- @function awful.keygrabber.disconnect_signal
-- @staticfct awful.keygrabber.disconnect_signal
-- @tparam string name The signal name.
-- @tparam function callback The callback.
function keygrab.disconnect_signal(name, callback)
@ -840,7 +830,7 @@ end
-- `my_keygrabber:emit_signal(name, ...)`. This function works on the whole
-- keygrabber module, not one of its instance.
--
-- @function awful.keygrabber.emit_signal
-- @staticfct awful.keygrabber.emit_signal
-- @tparam string name The signal name.
-- @param ... Other arguments for the callbacks.
function keygrab.emit_signal(name, ...)

10
lib/awful/layout/init.lua
View File

@ -73,7 +73,7 @@ layout.layouts = {
-- awful.layout.suit.corner.sw,
-- awful.layout.suit.corner.se,
--
-- @field layout.layouts
-- @field awful.layout.layouts
--- Return the tag layout index (from `awful.layout.layouts`).
--
@ -82,6 +82,7 @@ layout.layouts = {
--
-- @tparam tag t The tag.
-- @treturn nil|number The layout index.
-- @staticfct awful.layout.get_tag_layout_index
function layout.get_tag_layout_index(t)
return gtable.hasitem(layout.layouts, t.layout)
end
@ -95,6 +96,7 @@ local delayed_arrange = {}
--- Get the current layout.
-- @param screen The screen.
-- @return The layout function.
-- @staticfct awful.layout.get
function layout.get(screen)
screen = screen or capi.mouse.screen
local t = get_screen(screen).selected_tag
@ -105,6 +107,7 @@ end
-- @param i Relative index.
-- @param s The screen.
-- @param[opt] layouts A table of layouts.
-- @staticfct awful.layout.inc
function layout.inc(i, s, layouts)
if type(i) == "table" then
-- Older versions of this function had arguments (layouts, i, s), but
@ -150,6 +153,7 @@ end
--- Set the layout function of the current tag.
-- @param _layout Layout name.
-- @tparam[opt=mouse.screen.selected_tag] tag t The tag to modify.
-- @staticfct awful.layout.set
function layout.set(_layout, t)
t = t or capi.mouse.screen.selected_tag
t.layout = _layout
@ -168,6 +172,7 @@ end
-- @treturn table A table with the workarea (x, y, width, height), the screen
-- geometry (x, y, width, height), the clients, the screen and sometime, a
-- "geometries" table with client as keys and geometry as value
-- @staticfct awful.layout.parameters
function layout.parameters(t, screen)
screen = get_screen(screen)
t = t or screen.selected_tag
@ -210,6 +215,7 @@ end
--- Arrange a screen using its current layout.
-- @param screen The screen to arrange.
-- @staticfct awful.layout.arrange
function layout.arrange(screen)
screen = get_screen(screen)
if not screen or delayed_arrange[screen] then return end
@ -250,6 +256,7 @@ end
--- Get the current layout name.
-- @param _layout The layout.
-- @return The layout name.
-- @staticfct awful.layout.getname
function layout.getname(_layout)
_layout = _layout or layout.get()
return _layout.name
@ -318,6 +325,7 @@ capi.client.connect_signal("list", function()
-- @tparam client c The client
-- @tparam string context The context
-- @tparam table hints Additional hints
-- @signalhandler awful.layout.move_handler
function layout.move_handler(c, context, hints) --luacheck: no unused args
-- Quit if it isn't a mouse.move on a tiled layout, that's handled elsewhere
if c.floating then return end

13
lib/awful/layout/suit/fair.lua
View File

@ -88,21 +88,30 @@ local function do_fair(p, orientation)
end
end
--- Horizontal fair layout.
-- Horizontal fair layout.
-- @param screen The screen to arrange.
fair.horizontal = {}
fair.horizontal.name = "fairh"
function fair.horizontal.arrange(p)
return do_fair(p, "east")
end
--- Vertical fair layout.
-- Vertical fair layout.
-- @param screen The screen to arrange.
fair.name = "fairv"
function fair.arrange(p)
return do_fair(p, "south")
end
--- The fair layout.
-- Try to give all clients the same size.
-- @clientlayout awful.layout.suit.fair
--- The horizontal fair layout.
-- Try to give all clients the same size.
-- @clientlayout awful.layout.suit.fair.horizontal
return fair
-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

3
lib/awful/layout/suit/floating.lua
View File

@ -22,6 +22,7 @@ local capi =
local floating = {}
--- Jump mouse cursor to the client's corner when resizing it.
-- @field awful.layout.suit.floating.resize_jump_to_corner
floating.resize_jump_to_corner = true
function floating.mouse_resize_handler(c, corner, x, y)
@ -103,7 +104,7 @@ function floating.arrange()
end
--- The floating layout.
-- @clientlayout awful.layout.suit.
-- @clientlayout awful.layout.suit.floating
floating.name = "floating"

1
lib/awful/layout/suit/tile.lua
View File

@ -43,6 +43,7 @@ local tile = {}
-- @see gears.surface
--- Jump mouse cursor to the client's corner when resizing it.
-- @field awful.layout.suit.tile.resize_jump_to_corner
tile.resize_jump_to_corner = true
local function mouse_resize_handler(c, _, _, _, orientation)

21
lib/awful/menu.lua
View File

@ -5,7 +5,7 @@
-- @author Julien Danjou &lt;julien@danjou.info&gt;
-- @author dodo
-- @copyright 2008, 2011 Damien Leone, Julien Danjou, dodo
-- @module awful.menu
-- @popupmod awful.menu
--------------------------------------------------------------------------------
local wibox = require("wibox")
@ -358,6 +358,7 @@ end
--- Show a menu.
-- @param args The arguments
-- @param args.coords Menu position defaulting to mouse.coords()
-- @method show
function menu:show(args)
args = args or {}
local coords = args.coords or nil
@ -371,6 +372,7 @@ function menu:show(args)
end
--- Hide a menu popup.
-- @method hide
function menu:hide()
-- Remove items from screen
for i = 1, #self.items do
@ -389,6 +391,7 @@ end
--- Toggle menu visibility.
-- @param args The arguments
-- @param args.coords Menu position {x,y}
-- @method toggle
function menu:toggle(args)
if self.wibox.visible then
self:hide()
@ -397,7 +400,8 @@ function menu:toggle(args)
end
end
--- Update menu content
--- Update menu content.
-- @method update
function menu:update()
if self.wibox.visible then
self:show({ coords = { x = self.x, y = self.y } })
@ -407,6 +411,7 @@ end
--- Get the elder parent so for example when you kill
-- it, it will destroy the whole family.
-- @method get_root
function menu:get_root()
return self.parent and menu.get_root(self.parent) or self
end
@ -417,6 +422,7 @@ end
-- @param args.new (Default: awful.menu.entry) The menu entry constructor.
-- @param[opt] args.theme The menu entry theme.
-- @param[opt] index The index where the new entry will inserted.
-- @method add
function menu:add(args, index)
if not args then return end
local theme = load_theme(args.theme or {}, self.theme)
@ -470,8 +476,9 @@ function menu:add(args, index)
return item
end
--- Delete menu entry at given position
-- @param num The position in the table of the menu entry to be deleted; can be also the menu entry itself
--- Delete menu entry at given position.
-- @param num The position in the table of the menu entry to be deleted; can be also the menu entry itself.
-- @method delete
function menu:delete(num)
if type(num) == "table" then
num = gtable.hasitem(self.items, num)
@ -511,6 +518,7 @@ end
-- returning `true` or `false` to indicate whether the client should be
-- included in the menu.
-- @return The menu.
-- @constructorfct awful.menu.clients
function menu.clients(args, item_args, filter)
local cls_t = {}
for c in client_iterate(filter or function() return true end) do
@ -553,6 +561,7 @@ local clients_menu = nil
-- returning `true` or `false` to indicate whether the client should be
-- included in the menu.
-- @return The menu.
-- @constructorfct awful.menu.client_list
function menu.client_list(args, item_args, filter)
if clients_menu and clients_menu.wibox.visible then
clients_menu:hide()
@ -565,10 +574,11 @@ end
--------------------------------------------------------------------------------
--- Default awful.menu.entry constructor
--- Default awful.menu.entry constructor.
-- @param parent The parent menu (TODO: This is apparently unused)
-- @param args the item params
-- @return table with 'widget', 'cmd', 'akey' and all the properties the user wants to change
-- @constructorfct awful.menu.entry
function menu.entry(parent, args) -- luacheck: no unused args
args = args or {}
args.text = args[1] or args.text or ""
@ -668,6 +678,7 @@ end
-- * Key auto_expand controls the submenu auto expand behaviour by setting it to true (default) or false.
--
-- @param parent Specify the parent menu if we want to open a submenu, this value should never be set by the user.
-- @constructorfct awful.menu
-- @usage -- The following function builds and shows a menu of clients that match
-- -- a particular rule.
-- -- Bound to a key, it can be used to select from dozens of terminals open on

8
lib/awful/mouse/init.lua
View File

@ -72,7 +72,7 @@ function mouse.client_under_pointer()
end
--- Move a client.
-- @function awful.mouse.client.move
-- @staticfct awful.mouse.client.move
-- @param c The client to move, or the focused one if nil.
-- @param snap The pixel to snap clients.
-- @param finished_cb Deprecated, do not use
@ -125,7 +125,7 @@ function mouse.client.dragtotag.border(c)
end
--- Move the wibox under the cursor.
-- @function awful.mouse.wibox.move
-- @staticfct awful.mouse.wibox.move
--@tparam wibox w The wibox to move, or none to use that under the pointer
function mouse.wibox.move(w)
w = w or mouse.current_wibox
@ -183,7 +183,7 @@ function mouse.client.corner(c, corner)
end
--- Resize a client.
-- @function awful.mouse.client.resize
-- @staticfct awful.mouse.client.resize
-- @param c The client to resize, or the focused one by default.
-- @tparam string corner The corner to grab on resize. Auto detected by default.
-- @tparam[opt={}] table args A set of `awful.placement` arguments
@ -417,7 +417,7 @@ end)
-- @treturn integer table.y The vertical position
-- @treturn table table.buttons Table containing the status of buttons, e.g. field [1] is true
-- when button 1 is pressed.
-- @function mouse.coords
-- @staticfct mouse.coords
return mouse

14
lib/awful/placement.lua
View File

@ -811,7 +811,8 @@ end
-- or `wibox`)
-- @tparam[opt={}] table args The arguments
-- @treturn table The new geometry
-- @treturn string The corner name
-- @treturn string The corner name.
-- @staticfct awful.placement.closest_corner
function placement.closest_corner(d, args)
args = add_context(args, "closest_corner")
d = d or capi.client.focus
@ -855,6 +856,7 @@ end
-- @tparam[opt={}] table args The arguments
-- @tparam[opt=client's screen] integer args.screen The screen.
-- @treturn table The new client geometry.
-- @staticfct awful.placement.no_offscreen
function placement.no_offscreen(c, args)
--compatibility with the old API
@ -897,6 +899,7 @@ end
-- @param c The client.
-- @tparam[opt={}] table args Other arguments
-- @treturn table The new geometry
-- @staticfct awful.placement.no_overlap
function placement.no_overlap(c, args)
c = c or capi.client.focus
args = add_context(args, "no_overlap")
@ -969,6 +972,7 @@ end
-- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`)
-- @tparam[opt={}] table args Other arguments
-- @treturn table The new geometry
-- @staticfct awful.placement.under_mouse
function placement.under_mouse(d, args)
args = add_context(args, "under_mouse")
d = d or capi.client.focus
@ -993,6 +997,7 @@ end
-- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`)
-- @tparam[opt={}] table args Other arguments
-- @treturn table The new geometry
-- @staticfct awful.placement.next_to_mouse
function placement.next_to_mouse(d, args)
if type(args) == "number" then
gdebug.deprecate(
@ -1042,6 +1047,7 @@ end
-- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`)
-- @tparam[opt={}] table args Other arguments
-- @treturn table The new geometry
-- @staticfct awful.placement.resize_to_mouse
function placement.resize_to_mouse(d, args)
d = d or capi.client.focus
args = add_context(args, "resize_to_mouse")
@ -1119,6 +1125,7 @@ end
-- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`)
-- @tparam[opt={}] table args Other arguments
-- @treturn table The new geometry
-- @staticfct awful.placement.align
function placement.align(d, args)
args = add_context(args, "align")
d = d or capi.client.focus
@ -1193,6 +1200,7 @@ end
-- @tparam[opt=client.focus] drawable d A drawable (like `client` or `wibox`)
-- @tparam[opt={}] table args The arguments
-- @treturn table The new geometry
-- @staticfct awful.placement.stretch
function placement.stretch(d, args)
args = add_context(args, "stretch")
@ -1265,6 +1273,7 @@ end
-- @tparam[opt=client.focus] drawable d A drawable (like `client` or `wibox`)
-- @tparam[opt={}] table args The arguments
-- @treturn table The new geometry
-- @staticfct awful.placement.maximize
function placement.maximize(d, args)
args = add_context(args, "maximize")
d = d or capi.client.focus
@ -1318,6 +1327,7 @@ end
-- @tparam[opt=client.focus] drawable d A drawable (like `client` or `wibox`)
-- @tparam[opt={}] table args The arguments
-- @treturn table The new geometry
-- @staticfct awful.placement.scale
function placement.scale(d, args)
args = add_context(args, "scale_to_percent")
d = d or capi.client.focus
@ -1400,6 +1410,7 @@ end
-- @treturn table The new geometry
-- @treturn string The choosen position ("left", "right", "top" or "bottom")
-- @treturn string The choosen anchor ("front", "middle" or "back")
-- @staticfct awful.placement.next_to
function placement.next_to(d, args)
args = add_context(args, "next_to")
d = d or capi.client.focus
@ -1527,6 +1538,7 @@ end
-- @tparam[opt=client.focus] drawable d A drawable (like `client` or `wibox`)
-- @tparam[opt={}] table args The arguments
-- @treturn boolean If the geometry was restored
-- @staticfct awful.placement.restore
function placement.restore(d, args)
if not args or not args.context then return false end
d = d or capi.client.focus

3
lib/awful/popup.lua
View File

@ -234,6 +234,7 @@ end
-- @see awful.popup.preferred_positions
-- @see awful.popup.preferred_anchors
-- @treturn table The new geometry
-- @method move_next_to
function popup:move_next_to(obj)
if self._private.is_relative == false then return end
@ -256,6 +257,7 @@ end
--
-- @tparam widget widget The widget
-- @tparam[opt=1] number button The button index
-- @method bind_to_widget
function popup:bind_to_widget(widget, button)
if not self._private.button_for_widget then
self._private.button_for_widget = {}
@ -267,6 +269,7 @@ end
--- Unbind the popup from a widget button.
-- @tparam widget widget The widget
-- @method unbind_to_widget
function popup:unbind_to_widget(widget)
widget:disconnect_signal("button::press", self._private.show_fct)
end

1
lib/awful/prompt.lua
View File

@ -454,6 +454,7 @@ end
-- with mod table, key and command as arguments when a key was pressed.
-- [**DEPRECATED**]
-- @see gears.color
-- @staticfct awful.prompt.run
function prompt.run(args, textbox, exe_callback, completion_callback,
history_path, history_max, done_callback,
changed_callback, keypressed_callback)

13
lib/awful/rules.lua
View File

@ -134,6 +134,7 @@ local crules = gmatcher()
-- @client c The client.
-- @tab rule The rule to check.
-- @treturn bool True if it matches, false otherwise.
-- @staticfct awful.rules.match
function rules.match(c, rule)
return crules:_match(c, rule)
end
@ -142,6 +143,7 @@ end
-- @client c The client.
-- @tab rule The rule to check.
-- @treturn bool True if at least one rule is matched, false otherwise.
-- @staticfct awful.rules.match_any
function rules.match_any(c, rule)
return crules:_match_any(c, rule)
end
@ -151,6 +153,7 @@ end
-- @tab entry Rule entry (with keys `rule`, `rule_any`, `except` and/or
-- `except_any`).
-- @treturn bool
-- @staticfct awful.rules.matches
function rules.matches(c, entry)
return crules:matches_rule(c, entry)
end
@ -160,6 +163,7 @@ end
-- @tab _rules The rules to check. List with "rule", "rule_any", "except" and
-- "except_any" keys.
-- @treturn table The list of matched rules.
-- @staticfct awful.rules.matching_rules
function rules.matching_rules(c, _rules)
return crules:matching_rules(c, _rules)
end
@ -169,13 +173,15 @@ end
-- @tab _rules The rules to check. List of tables with `rule`, `rule_any`,
-- `except` and `except_any` keys.
-- @treturn bool True if at least one rule is matched, false otherwise.
-- @staticfct awful.rules.matches_list
function rules.matches_list(c, _rules)
return crules:matches_rules(c, _rules)
end
--- Remove a source.
-- @tparam string name The source name.
-- @treturn boolean If the source was removed,
-- @treturn boolean If the source was removed.
-- @staticfct awful.rules.remove_rule_source
function rules.remove_rule_source(name)
return crules:remove_matching_source(name)
end
@ -183,6 +189,7 @@ end
--- Apply awful.rules.rules to a client.
-- @client c The client.
-- @staticfct awful.rules.apply
function rules.apply(c)
return crules:apply(c)
end
@ -226,7 +233,7 @@ end
-- @tparam[opt={}] table precede A list of names of sources this source have a
-- priority over.
-- @treturn boolean Returns false if a dependency conflict was found.
-- @function awful.rules.add_rule_source
-- @staticfct awful.rules.add_rule_source
function rules.add_rule_source(name, cb, ...)
local function callback(_, ...)
@ -519,7 +526,7 @@ end
-- @client c The client.
-- @tab props Properties to apply.
-- @tab[opt] callbacks Callbacks to apply.
-- @function awful.rules.execute
-- @staticfct awful.rules.execute
crules._execute = function(_, c, props, callbacks)
-- This has to be done first, as it will impact geometry related props.

20
lib/awful/screen.lua
View File

@ -69,7 +69,7 @@ end
--
-- The number returned can be used as an index into the global
-- `screen` table/object.
-- @function awful.screen.getbycoord
-- @staticfct awful.screen.getbycoord
-- @tparam number x The x coordinate
-- @tparam number y The y coordinate
-- @treturn ?number The screen index
@ -86,7 +86,7 @@ end
--
-- This moves the mouse pointer to the last known position on the new screen,
-- or keeps its position relative to the current focused screen.
-- @function awful.screen.focus
-- @staticfct awful.screen.focus
-- @screen _screen Screen number (defaults / falls back to mouse.screen).
function screen.focus(_screen)
client = client or require("awful.client")
@ -149,7 +149,7 @@ end
--
-- This moves the mouse pointer to the last known position on the new screen,
-- or keeps its position relative to the current focused screen.
-- @function awful.screen.focus_bydirection
-- @staticfct awful.screen.focus_bydirection
-- @param dir The direction, can be either "up", "down", "left" or "right".
-- @param _screen Screen.
function screen.focus_bydirection(dir, _screen)
@ -166,7 +166,7 @@ end
-- This moves the mouse pointer to the last known position on the new screen,
-- or keeps its position relative to the current focused screen.
--
-- @function awful.screen.focus_relative
-- @staticfct awful.screen.focus_relative
-- @tparam int offset Value to add to the current focused screen index. 1 to
-- focus the next one, -1 to focus the previous one.
function screen.focus_relative(offset)
@ -242,6 +242,7 @@ end
-- focused screen by default.
-- @tparam client c A client.
-- @treturn screen The preferred screen.
-- @staticfct awful.screen.preferred
function screen.preferred(c)
return capi.awesome.startup and c.screen or screen.focused()
end
@ -254,7 +255,7 @@ end
-- It is possible to set `awful.screen.default_focused_args` to override the
-- default settings.
--
-- @function awful.screen.focused
-- @staticfct awful.screen.focused
-- @tparam[opt] table args
-- @tparam[opt=false] boolean args.client Use the client screen instead of the
-- mouse screen.
@ -272,7 +273,7 @@ end
--
-- This method computes the different variants of the "usable" screen geometry.
--
-- @function screen.get_bounding_geometry
-- @staticfct screen.get_bounding_geometry
-- @tparam[opt={}] table args The arguments
-- @tparam[opt=false] boolean args.honor_padding Whether to honor the screen's padding.
-- @tparam[opt=false] boolean args.honor_workarea Whether to honor the screen's workarea.
@ -341,7 +342,7 @@ end
--
-- This is used by `screen.clients` internally (with `stacked=true`).
--
-- @function screen:get_clients
-- @method get_clients
-- @tparam[opt=true] boolean stacked Use stacking order? (top to bottom)
-- @treturn table The clients list.
function screen.object.get_clients(s, stacked)
@ -430,7 +431,7 @@ end
--- Call a function for each existing and created-in-the-future screen.
--
-- @function awful.screen.connect_for_each_screen
-- @staticfct awful.screen.connect_for_each_screen
-- @tparam function func The function to call.
-- @screen func.screen The screen.
function screen.connect_for_each_screen(func)
@ -441,7 +442,7 @@ function screen.connect_for_each_screen(func)
end
--- Undo the effect of connect_for_each_screen.
-- @function awful.screen.disconnect_for_each_screen
-- @staticfct awful.screen.disconnect_for_each_screen
-- @tparam function func The function that should no longer be called.
function screen.disconnect_for_each_screen(func)
capi.screen.disconnect_signal("added", func)
@ -525,6 +526,7 @@ end
-- defaulting to 96.
--
-- @tparam boolean enabled Enable or disable automatic DPI support.
-- @staticfct awful.screen.set_auto_dpi_enabled
function screen.set_auto_dpi_enabled(enabled)
for s in capi.screen do
s.data.dpi_cache = nil

9
lib/awful/spawn.lua
View File

@ -344,6 +344,7 @@ end
-- @treturn[1] ?string The startup notification ID, if `sn` is not false, or
-- a `callback` is provided.
-- @treturn[2] string Error message.
-- @staticfct awful.spawn
function spawn.spawn(cmd, sn_rules, callback)
if cmd and cmd ~= "" then
local enable_sn = (sn_rules ~= false or callback)
@ -363,6 +364,7 @@ end
--- Spawn a program using the shell.
-- This calls `cmd` with `$SHELL -c` (via `awful.util.shell`).
-- @tparam string cmd The command.
-- @staticfct awful.spawn.with_shell
function spawn.with_shell(cmd)
if cmd and cmd ~= "" then
cmd = { util.shell, "-c", cmd }
@ -389,6 +391,7 @@ end
-- termination.
-- @treturn[1] Integer the PID of the forked process.
-- @treturn[2] string Error message.
-- @staticfct awful.spawn.with_line_callback
function spawn.with_line_callback(cmd, callbacks)
local stdout_callback, stderr_callback, done_callback, exit_callback =
callbacks.stdout, callbacks.stderr, callbacks.output_done, callbacks.exit
@ -434,6 +437,7 @@ end
-- @treturn[1] Integer the PID of the forked process.
-- @treturn[2] string Error message.
-- @see spawn.with_line_callback
-- @staticfct awful.spawn.easy_async
function spawn.easy_async(cmd, callback)
local stdout = ''
local stderr = ''
@ -484,6 +488,7 @@ end
-- @treturn[1] Integer the PID of the forked process.
-- @treturn[2] string Error message.
-- @see spawn.with_line_callback
-- @staticfct awful.spawn.easy_async_with_shell
function spawn.easy_async_with_shell(cmd, callback)
return spawn.easy_async({ util.shell, "-c", cmd or "" }, callback)
end
@ -495,6 +500,7 @@ end
-- @tparam[opt] function done_callback Function that is called when the
-- operation finishes (e.g. due to end of file).
-- @tparam[opt=false] boolean close Should the stream be closed after end-of-file?
-- @staticfct awful.spawn.read_lines
function spawn.read_lines(input_stream, line_callback, done_callback, close)
local stream = Gio.DataInputStream.new(input_stream)
local function done()
@ -644,6 +650,7 @@ end
-- multiple time.
-- @tparam[opt] function callback A callback function when the client is created.
-- @see awful.rules
-- @staticfct awful.spawn.once
function spawn.once(cmd, rules, matcher, unique_id, callback)
local hash = unique_id or hash_command(cmd, rules)
local status = register_common(hash, rules, matcher, callback)
@ -676,6 +683,7 @@ end
-- multiple time.
-- @tparam[opt] function callback A callback function when the client is created.
-- @see awful.rules
-- @staticfct awful.spawn.single_instance
function spawn.single_instance(cmd, rules, matcher, unique_id, callback)
local hash = unique_id or hash_command(cmd, rules)
register_common(hash, rules, matcher, callback)
@ -703,6 +711,7 @@ local raise_rules = {focus = true, switch_to_tags = true, raise = true}
-- @tparam[opt] function callback A callback function when the client is created.
-- @see awful.rules
-- @treturn client The client if it already exists.
-- @staticfct awful.spawn.raise_or_spawn
function spawn.raise_or_spawn(cmd, rules, matcher, unique_id, callback)
local hash = unique_id or hash_command(cmd, rules)

35
lib/awful/tag.lua
View File

@ -296,7 +296,7 @@ function tag.add(name, props)
end
--- Create a set of tags and attach it to a screen.
-- @function awful.tag.new
-- @staticfct awful.tag.new
-- @param names The tag name, in a table
-- @param screen The tag screen, or 1 if not set.
-- @param layout The layout or layout table to set for this tags by default.
@ -322,7 +322,7 @@ function tag.new(names, screen, layout)
end
--- Find a suitable fallback tag.
-- @function awful.tag.find_fallback
-- @staticfct awful.tag.find_fallback
-- @param screen The screen to look for a tag on. [awful.screen.focused()]
-- @param invalids A table of tags we consider unacceptable. [selectedlist(scr)]
function tag.find_fallback(screen, invalids)
@ -340,7 +340,7 @@ end
--
-- mouse.screen.selected_tag:delete()
--
-- @function tag.delete
-- @method delete
-- @see awful.tag.add
-- @see awful.tag.find_fallback
-- @tparam[opt=awful.tag.find_fallback()] tag fallback_tag Tag to assign
@ -429,7 +429,7 @@ function tag.delete(target_tag, fallback_tag)
end
--- Update the tag history.
-- @function awful.tag.history.update
-- @staticfct awful.tag.history.update
-- @param obj Screen object.
function tag.history.update(obj)
local s = get_screen(obj)
@ -470,7 +470,7 @@ function tag.history.update(obj)
end
--- Revert tag history.
-- @function awful.tag.history.restore
-- @staticfct awful.tag.history.restore
-- @param screen The screen.
-- @param idx Index in history. Defaults to "previous" which is a special index
-- toggling between last two selected sets of tags. Number (eg 1) will go back
@ -522,6 +522,7 @@ end
-- @tparam screen s The screen of the tag
-- @tparam string name The name of the tag
-- @return The tag found, or `nil`
-- @staticfct awful.tag.find_by_name
-- @usage -- For the current screen
-- local t = awful.tag.find_by_name(awful.screen.focused(), "name")
--
@ -696,7 +697,7 @@ function tag.setmwfact(mwfact, t)
end
--- Increase master width factor.
-- @function awful.tag.incmwfact
-- @staticfct awful.tag.incmwfact
-- @see master_width_factor
-- @param add Value to add to master width factor.
-- @param t The tag to modify, if null tag.selected() is used.
@ -972,7 +973,7 @@ function tag.setgap(useless_gap, t)
end
--- Increase the spacing between clients
-- @function awful.tag.incgap
-- @staticfct awful.tag.incgap
-- @see gap
-- @param add Value to add to the spacing between clients
-- @param t The tag to modify, if null tag.selected() is used.
@ -1079,7 +1080,7 @@ end
--- Toggle size fill policy for the master client(s)
-- between "expand" and "master_width_factor".
-- @function awful.tag.togglemfpol
-- @staticfct awful.tag.togglemfpol
-- @see master_fill_policy
-- @tparam tag t The tag to modify, if null tag.selected() is used.
function tag.togglemfpol(t)
@ -1160,7 +1161,7 @@ function tag.getnmaster(t)
end
--- Increase the number of master windows.
-- @function awful.tag.incnmaster
-- @staticfct awful.tag.incnmaster
-- @see master_count
-- @param add Value to add to number of master windows.
-- @param[opt] t The tag to modify, if null tag.selected() is used.
@ -1278,7 +1279,7 @@ function tag.getncol(t)
end
--- Increase number of column windows.
-- @function awful.tag.incncol
-- @staticfct awful.tag.incncol
-- @param add Value to add to number of column windows.
-- @param[opt] t The tag to modify, if null tag.selected() is used.
-- @tparam[opt=false] boolean sensible Limit column_count based on the number
@ -1309,7 +1310,7 @@ function tag.incncol(add, t, sensible)
end
--- View no tag.
-- @function awful.tag.viewnone
-- @staticfct awful.tag.viewnone
-- @tparam[opt] int|screen screen The screen.
function tag.viewnone(screen)
screen = screen or ascreen.focused()
@ -1322,7 +1323,7 @@ end
--- View a tag by its taglist index.
--
-- This is equivalent to `screen.tags[i]:view_only()`
-- @function awful.tag.viewidx
-- @staticfct awful.tag.viewidx
-- @see screen.tags
-- @param i The **relative** index to see.
-- @param[opt] screen The screen.
@ -1357,14 +1358,14 @@ function tag.getidx(query_tag)
end
--- View next tag. This is the same as tag.viewidx(1).
-- @function awful.tag.viewnext
-- @staticfct awful.tag.viewnext
-- @param screen The screen.
function tag.viewnext(screen)
return tag.viewidx(1, screen)
end
--- View previous tag. This is the same a tag.viewidx(-1).
-- @function awful.tag.viewprev
-- @staticfct awful.tag.viewprev
-- @param screen The screen.
function tag.viewprev(screen)
return tag.viewidx(-1, screen)
@ -1404,7 +1405,7 @@ end
-- selected. The tags already selected do not count. To do nothing if one or
-- more of the tags are already selected, set `maximum` to zero.
--
-- @function awful.tag.viewmore
-- @staticfct awful.tag.viewmore
-- @param tags A table with tags to view only.
-- @param[opt] screen The screen of the tags.
-- @tparam[opt=#tags] number maximum The maximum number of tags to select.
@ -1437,7 +1438,7 @@ function tag.viewmore(tags, screen, maximum)
end
--- Toggle selection of a tag
-- @function awful.tag.viewtoggle
-- @staticfct awful.tag.viewtoggle
-- @see selected
-- @tparam tag t Tag to be toggled
function tag.viewtoggle(t)
@ -1530,7 +1531,7 @@ end
--- Add a signal to all attached tags and all tags that will be attached in the
-- future. When a tag is detached from the screen, its signal is removed.
--
-- @function awful.tag.attached_connect_signal
-- @staticfct awful.tag.attached_connect_signal
-- @screen screen The screen concerned, or all if nil.
-- @tparam[opt] string signal The signal name.
-- @tparam[opt] function Callback

15
lib/awful/titlebar.lua
View File

@ -431,8 +431,7 @@ local titlebar = {
--- 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
-- @method setup
local all_titlebars = setmetatable({}, { __mode = 'k' })
@ -564,6 +563,7 @@ end
-- @param c The client whose titlebar is modified
-- @param[opt] position The position of the titlebar. Must be one of "left",
-- "right", "top", "bottom". Default is "top".
-- @staticfct awful.titlebar.show
function titlebar.show(c, position)
position = position or "top"
if load_titlebars(c, true, position) then return end
@ -577,6 +577,7 @@ end
-- @param c The client whose titlebar is modified
-- @param[opt] position The position of the titlebar. Must be one of "left",
-- "right", "top", "bottom". Default is "top".
-- @staticfct awful.titlebar.hide
function titlebar.hide(c, position)
position = position or "top"
get_titlebar_function(c, position)(c, 0)
@ -586,6 +587,7 @@ end
-- @param c The client whose titlebar is modified
-- @param[opt] position The position of the titlebar. Must be one of "left",
-- "right", "top", "bottom". Default is "top".
-- @staticfct awful.titlebar.toggle
function titlebar.toggle(c, position)
position = position or "top"
if load_titlebars(c, true, position) then return end
@ -602,6 +604,7 @@ end
-- This way, you can e.g. modify the font that is used.
-- @param c The client for which a titlewidget should be created.
-- @return The title widget.
-- @staticfct awful.titlebar.widget.titlewidget
function titlebar.widget.titlewidget(c)
local ret = textbox()
local function update()
@ -618,6 +621,7 @@ end
-- available. This way, you can e.g. disallow resizes.
-- @param c The client for which an icon widget should be created.
-- @return The icon widget.
-- @staticfct awful.titlebar.widget.iconwidget
function titlebar.widget.iconwidget(c)
return clienticon(c)
end
@ -635,6 +639,7 @@ end
-- @param selector A function that selects the image that should be displayed.
-- @param action Function that is called when the button is clicked.
-- @return The widget
-- @staticfct awful.titlebar.widget.button
function titlebar.widget.button(c, name, selector, action)
local ret = imagebox()
@ -718,6 +723,7 @@ end
--- Create a new float button for a client.
-- @param c The client for which the button is wanted.
-- @staticfct awful.titlebar.widget.floatingbutton
function titlebar.widget.floatingbutton(c)
local widget = titlebar.widget.button(c, "floating", aclient.object.get_floating, aclient.floating.toggle)
c:connect_signal("property::floating", widget.update)
@ -726,6 +732,7 @@ end
--- Create a new maximize button for a client.
-- @param c The client for which the button is wanted.
-- @staticfct awful.titlebar.widget.maximizedbutton
function titlebar.widget.maximizedbutton(c)
local widget = titlebar.widget.button(c, "maximized", function(cl)
return cl.maximized
@ -738,6 +745,7 @@ end
--- Create a new minimize button for a client.
-- @param c The client for which the button is wanted.
-- @staticfct awful.titlebar.widget.minimizebutton
function titlebar.widget.minimizebutton(c)
local widget = titlebar.widget.button(c, "minimize",
function() return "" end,
@ -748,12 +756,14 @@ end
--- Create a new closing button for a client.
-- @param c The client for which the button is wanted.
-- @staticfct awful.titlebar.widget.closebutton
function titlebar.widget.closebutton(c)
return titlebar.widget.button(c, "close", function() return "" end, function(cl) cl:kill() end)
end
--- Create a new ontop button for a client.
-- @param c The client for which the button is wanted.
-- @staticfct awful.titlebar.widget.ontopbutton
function titlebar.widget.ontopbutton(c)
local widget = titlebar.widget.button(c, "ontop",
function(cl) return cl.ontop end,
@ -764,6 +774,7 @@ end
--- Create a new sticky button for a client.
-- @param c The client for which the button is wanted.
-- @staticfct awful.titlebar.widget.stickybutton
function titlebar.widget.stickybutton(c)
local widget = titlebar.widget.button(c, "sticky",
function(cl) return cl.sticky end,

11
lib/awful/tooltip.lua
View File

@ -276,20 +276,13 @@ function tooltip:set_align(value)
end
--- The shape of the tooltip window.
-- If the shape require some parameters, use `set_shape`.
--
-- @DOC_awful_tooltip_shape_EXAMPLE@
--
-- @property shape
-- @see gears.shape
-- @see set_shape
-- @see beautiful.tooltip_shape
--- Set the tooltip shape.
-- All other arguments will be passed to the shape function.
-- @tparam gears.shape s The shape
-- @see shape
-- @see gears.shape
function tooltip:set_shape(s)
self.backgroundbox:set_shape(s)
end
@ -520,7 +513,7 @@ end
-- @tparam tooltip self The tooltip.
-- @tparam gears.object obj An object with `mouse::enter` and
-- `mouse::leave` signals.
-- @function add_to_object
-- @method add_to_object
function tooltip:add_to_object(obj)
if not obj then return end
@ -533,7 +526,7 @@ end
-- @tparam tooltip self The tooltip.
-- @tparam gears.object obj An object with `mouse::enter` and
-- `mouse::leave` signals.
-- @function remove_from_object
-- @method remove_from_object
function tooltip:remove_from_object(obj)
obj:disconnect_signal("mouse::enter", self.show)
obj:disconnect_signal("mouse::leave", self.hide)

4
lib/awful/util.lua
View File

@ -99,6 +99,7 @@ end
--- Eval Lua code.
-- @return The return value of Lua code.
-- @staticfct awful.util.eval
function util.eval(s)
return assert(load(s))()
end
@ -129,6 +130,7 @@ end
-- @param path The file path.
-- @return A function if everything is alright, a string with the error
-- otherwise.
-- @staticfct awful.util.checkfile
function util.checkfile(path)
local f, e = loadfile(path)
-- Return function if function, otherwise return error.
@ -140,6 +142,7 @@ end
-- It checks if the configuration file is valid, and then restart if it's ok.
-- If it's not ok, the error will be returned.
-- @return Never return if awesome restart, or return a string error.
-- @staticfct awful.util.restart
function util.restart()
local c = util.checkfile(capi.awesome.conffile)
@ -225,6 +228,7 @@ end
-- @param dirs Table of dirs to search, otherwise { '/usr/share/pixmaps/' }
-- @tparam[opt] string size The size. If this is specified, subdirectories `x`
-- of the dirs are searched first.
-- @staticfct awful.util.geticonpath
function util.geticonpath(iconname, exts, dirs, size)
exts = exts or { 'png', 'gif' }
dirs = dirs or { '/usr/share/pixmaps/', '/usr/share/icons/hicolor/' }

8
lib/awful/wibar.lua
View File

@ -217,11 +217,6 @@ local function set_position(wb, position, skip_reattach)
end
end
--- Stretch the wibar.
--
-- @property stretch
-- @param[opt=true] boolean
local function get_stretch(w)
return w._stretch
end
@ -233,7 +228,8 @@ local function set_stretch(w, value)
end
--- Remove a wibar.
-- @function remove
-- @method remove
local function remove(self)
self.visible = false

5
lib/awful/widget/calendar_popup.lua
View File

@ -203,6 +203,7 @@ end
-- @tparam string position Two-character position of the calendar in the screen
-- @tparam screen screen Screen where to display the calendar
-- @treturn wibox The wibox calendar
-- @method call_calendar
function calendar_popup:call_calendar(offset, position, screen)
local inc_offset = offset or 0
local pos = position or self.position
@ -230,7 +231,8 @@ function calendar_popup:call_calendar(offset, position, screen)
return self
end
--- Toggle calendar visibility
--- Toggle calendar visibility.
-- @method toggle
function calendar_popup:toggle()
self:call_calendar(0)
self.visible = not self.visible
@ -247,6 +249,7 @@ end
-- @tparam[opt={}] table args Additional options
-- @tparam[opt=true] bool args.on_hover Show popup during mouse hover
-- @treturn wibox The wibox calendar
-- @method attach
function calendar_popup:attach(widget, position, args)
position = position or "tr"
args = args or {}

1
lib/awful/widget/keyboardlayout.lua
View File

@ -135,6 +135,7 @@ end
-- xkb_symbols pattern "vendor/file(section):group_idx".
-- @tparam string group_names The string awesome.xkb_get_group_names() returns.
-- @treturn table An array of tables whose keys are vendor, file, section, and group_idx.
-- @staticfct awful.keyboardlayout.get_groups_from_group_names
function keyboardlayout.get_groups_from_group_names(group_names)
if group_names == nil then
return nil

48
lib/beautiful/gtk.lua
View File

@ -63,54 +63,6 @@ local function read_gtk_color_properties_from_widget(gtk_widget, properties)
return result
end
-- luacheck: max comment line length 300
--- Get GTK+3 theme variables from GtkStyleContext
-- @treturn table Key-value table with the following structure:
-- <table class='widget_list' border=1>
-- <tr style='font-weight: bold;'> <th align='center'>Result key</th> <th align='center'>StyleContext key</th> <th align='center'>StyleContext fallback #1</th> <th align='center'>StyleContext fallback #2</th> <th align='center'>GTK Widget fallback</th> </tr>
-- <tr> <td>`font_size`</td> <td></td> <td></td> <td></td> <td>Label font-size</td> </tr>
-- <tr> <td>`font_family`</td> <td></td> <td></td> <td></td> <td>Label font-family</td> </tr>
-- <tr> <td>`bg_color`</td> <td>`theme_bg_color`</td> <td></td> <td></td> <td>Window bg</td> </tr>
-- <tr> <td>`fg_color`</td> <td>`theme_fg_color`</td> <td></td> <td></td> <td>Window fg</td> </tr>
-- <tr> <td>`base_color`</td> <td>`theme_base_color`</td> <td></td> <td></td> <td>Entry bg</td> </tr>
-- <tr> <td>`text_color`</td> <td>`theme_text_color`</td> <td></td> <td></td> <td>Entry fg</td> </tr>
-- <tr> <td>`button_bg_color`</td> <td>`theme_button_bg_color`</td> <td>`theme_bg_color`</td> <td></td> <td>Button bg</td> </tr>
-- <tr> <td>`button_fg_color`</td> <td>`theme_button_fg_color`</td> <td>`theme_fg_color`</td> <td></td> <td>Button fg</td> </tr>
-- <tr> <td>`button_border_color`</td> <td></td> <td></td> <td></td> <td>Button border-color</td> </tr>
-- <tr> <td>`button_border_radius`</td> <td></td> <td></td> <td></td> <td>Button border-radius</td> </tr>
-- <tr> <td>`button_border_width`</td> <td></td> <td></td> <td></td> <td>Button border-top-width</td> </tr>
-- <tr> <td>`selected_bg_color`</td> <td>`theme_selected_bg_color`</td> <td></td> <td></td> <td>ToggleButton bg</td> </tr>
-- <tr> <td>`selected_fg_color`</td> <td>`theme_selected_fg_color`</td> <td></td> <td></td> <td>ToggleButton fg</td> </tr>
-- <tr> <td>`menubar_bg_color`</td> <td>`menubar_bg_color`</td> <td>`theme_bg_color`</td> <td></td> <td>HeaderBar bg</td> </tr>
-- <tr> <td>`menubar_fg_color`</td> <td>`menubar_fg_color`</td> <td>`theme_fg_color`</td> <td></td> <td>HeaderBar fg</td> </tr>
-- <tr> <td>`header_button_bg_color`</td> <td>`header_button_bg_color`</td> <td>`menubar_bg_color`</td> <td>`theme_bg_color`</td> <td>HeaderBar > Button bg</td> </tr>
-- <tr> <td>`header_button_fg_color`</td> <td>`header_button_fg_color`</td> <td>`menubar_fg_color`</td> <td>`theme_fg_color`</td> <td>HeaderBar > Button fg</td> </tr>
-- <tr> <td>`header_button_border_color`</td> <td></td> <td></td> <td></td> <td>HeaderBar > Button border-color</td> </tr>
-- <tr> <td>`error_color`</td> <td>`error_color`</td> <td>`error_bg_color`</td> <td></td> <td>destructive Button bg</td> </tr>
-- <tr> <td>`error_bg_color`</td> <td>`error_bg_color`</td> <td>`error_color`</td> <td></td> <td>destructive Button bg</td> </tr>
-- <tr> <td>`error_fg_color`</td> <td>`error_fg_color`</td> <td>`theme_selected_fg_color`</td> <td></td> <td>destructive Button fg</td> </tr>
-- <tr> <td>`warning_color`</td> <td>`warning_color`</td> <td>`warning_bg_color`</td> <td></td> <td></td> </tr>
-- <tr> <td>`warning_bg_color`</td> <td>`warning_bg_color`</td> <td>`warning_color`</td> <td></td> <td></td> </tr>
-- <tr> <td>`warning_fg_color`</td> <td>`warning_fg_color`</td> <td>`theme_selected_fg_color`</td> <td></td> <td></td> </tr>
-- <tr> <td>`success_color`</td> <td>`success_color`</td> <td>`success_bg_color`</td> <td></td> <td></td> </tr>
-- <tr> <td>`success_bg_color`</td> <td>`success_bg_color`</td> <td>`success_color`</td> <td></td> <td></td> </tr>
-- <tr> <td>`success_fg_color`</td> <td>`success_fg_color`</td> <td>`theme_selected_fg_color`</td> <td></td> <td></td> </tr>
-- <tr> <td>`tooltip_bg_color`</td> <td>`theme_tooltip_bg_color`</td> <td>`theme_bg_color`</td> <td></td> <td></td> </tr>
-- <tr> <td>`tooltip_fg_color`</td> <td>`theme_tooltip_fg_color`</td> <td>`theme_fg_color`</td> <td></td> <td></td> </tr>
-- <tr> <td>`osd_bg_color`</td> <td>`osd_bg`</td> <td>`theme_tooltip_bg_color`</td> <td>`theme_bg_color`</td> <td></td> </tr>
-- <tr> <td>`osd_fg_color`</td> <td>`osd_fg`</td> <td>`theme_tooltip_fg_color`</td> <td>`theme_fg_color`</td> <td></td> </tr>
-- <tr> <td>`osd_border_color`</td> <td>`osd_borders_color`</td> <td>`osd_fg_color`</td> <td></td> <td></td> </tr>
-- <tr> <td>`wm_bg_color`</td> <td>`wm_bg`</td> <td>`menubar_bg_color`</td> <td>`theme_bg_color`</td> <td>HeaderBar bg</td> </tr>
-- <tr> <td>`wm_border_focused_color`</td> <td>`wm_border_focused`</td> <td>`theme_selected_bg_color`</td> <td></td> <td>ToggleButton bg</td> </tr>
-- <tr> <td>`wm_border_unfocused_color`</td> <td>`wm_border_unfocused`</td> <td>`wm_border`</td> <td>`menubar_bg_color`</td> <!--<td>`theme_bg_color`</td>--> <td>HeaderBar bg</td> </tr>
-- <tr> <td>`wm_title_focused_color`</td> <td>`wm_title_focused`</td> <td>`wm_title`</td> <td>`theme_selected_fg_color`</td> <td>ToggleButton fg</td> </tr>
-- <tr> <td>`wm_title_unfocused_color`</td> <td>`wm_title_unfocused`</td> <td>`wm_unfocused_title`</td> <td>`menubar_fg_color`</td> <!--<td>`theme_fg_color`</td>--> <td>HeaderBar fg</td> </tr>
-- <tr> <td>`wm_icons_focused_color`</td> <td>`wm_icons_focused`</td> <td>`wm_title_focused`</td> <td>`theme_selected_fg_color`</td> <td>ToggleButton fg</td> </tr>
-- <tr> <td>`wm_icons_unfocused_color`</td> <td>`wm_icons_unfocused`</td> <td>`wm_title_unfocused`</td> <td>`menubar_fg_color`</td> <!--<td>`theme_fg_color`</td>--> <td>HeaderBar fg</td> </tr>
-- </table>
--
function gtk.get_theme_variables()
if gtk.cached_theme_variables then
return gtk.cached_theme_variables

57
lib/beautiful/init.lua
View File

@ -37,6 +37,56 @@ local descs = setmetatable({}, { __mode = 'k' })
local fonts = setmetatable({}, { __mode = 'v' })
local active_font
-- luacheck: max comment line length 300
--- Get GTK+3 theme variables from GtkStyleContext
-- @treturn table Key-value table with the following structure:
-- <table class='widget_list' border=1>
-- <tr style='font-weight: bold;'> <th align='center'>Result key</th> <th align='center'>StyleContext key</th> <th align='center'>StyleContext fallback #1</th> <th align='center'>StyleContext fallback #2</th> <th align='center'>GTK Widget fallback</th> </tr>
-- <tr> <td>`font_size`</td> <td></td> <td></td> <td></td> <td>Label font-size</td> </tr>
-- <tr> <td>`font_family`</td> <td></td> <td></td> <td></td> <td>Label font-family</td> </tr>
-- <tr> <td>`bg_color`</td> <td>`theme_bg_color`</td> <td></td> <td></td> <td>Window bg</td> </tr>
-- <tr> <td>`fg_color`</td> <td>`theme_fg_color`</td> <td></td> <td></td> <td>Window fg</td> </tr>
-- <tr> <td>`base_color`</td> <td>`theme_base_color`</td> <td></td> <td></td> <td>Entry bg</td> </tr>
-- <tr> <td>`text_color`</td> <td>`theme_text_color`</td> <td></td> <td></td> <td>Entry fg</td> </tr>
-- <tr> <td>`button_bg_color`</td> <td>`theme_button_bg_color`</td> <td>`theme_bg_color`</td> <td></td> <td>Button bg</td> </tr>
-- <tr> <td>`button_fg_color`</td> <td>`theme_button_fg_color`</td> <td>`theme_fg_color`</td> <td></td> <td>Button fg</td> </tr>
-- <tr> <td>`button_border_color`</td> <td></td> <td></td> <td></td> <td>Button border-color</td> </tr>
-- <tr> <td>`button_border_radius`</td> <td></td> <td></td> <td></td> <td>Button border-radius</td> </tr>
-- <tr> <td>`button_border_width`</td> <td></td> <td></td> <td></td> <td>Button border-top-width</td> </tr>
-- <tr> <td>`selected_bg_color`</td> <td>`theme_selected_bg_color`</td> <td></td> <td></td> <td>ToggleButton bg</td> </tr>
-- <tr> <td>`selected_fg_color`</td> <td>`theme_selected_fg_color`</td> <td></td> <td></td> <td>ToggleButton fg</td> </tr>
-- <tr> <td>`menubar_bg_color`</td> <td>`menubar_bg_color`</td> <td>`theme_bg_color`</td> <td></td> <td>HeaderBar bg</td> </tr>
-- <tr> <td>`menubar_fg_color`</td> <td>`menubar_fg_color`</td> <td>`theme_fg_color`</td> <td></td> <td>HeaderBar fg</td> </tr>
-- <tr> <td>`header_button_bg_color`</td> <td>`header_button_bg_color`</td> <td>`menubar_bg_color`</td> <td>`theme_bg_color`</td> <td>HeaderBar > Button bg</td> </tr>
-- <tr> <td>`header_button_fg_color`</td> <td>`header_button_fg_color`</td> <td>`menubar_fg_color`</td> <td>`theme_fg_color`</td> <td>HeaderBar > Button fg</td> </tr>
-- <tr> <td>`header_button_border_color`</td> <td></td> <td></td> <td></td> <td>HeaderBar > Button border-color</td> </tr>
-- <tr> <td>`error_color`</td> <td>`error_color`</td> <td>`error_bg_color`</td> <td></td> <td>destructive Button bg</td> </tr>
-- <tr> <td>`error_bg_color`</td> <td>`error_bg_color`</td> <td>`error_color`</td> <td></td> <td>destructive Button bg</td> </tr>
-- <tr> <td>`error_fg_color`</td> <td>`error_fg_color`</td> <td>`theme_selected_fg_color`</td> <td></td> <td>destructive Button fg</td> </tr>
-- <tr> <td>`warning_color`</td> <td>`warning_color`</td> <td>`warning_bg_color`</td> <td></td> <td></td> </tr>
-- <tr> <td>`warning_bg_color`</td> <td>`warning_bg_color`</td> <td>`warning_color`</td> <td></td> <td></td> </tr>
-- <tr> <td>`warning_fg_color`</td> <td>`warning_fg_color`</td> <td>`theme_selected_fg_color`</td> <td></td> <td></td> </tr>
-- <tr> <td>`success_color`</td> <td>`success_color`</td> <td>`success_bg_color`</td> <td></td> <td></td> </tr>
-- <tr> <td>`success_bg_color`</td> <td>`success_bg_color`</td> <td>`success_color`</td> <td></td> <td></td> </tr>
-- <tr> <td>`success_fg_color`</td> <td>`success_fg_color`</td> <td>`theme_selected_fg_color`</td> <td></td> <td></td> </tr>
-- <tr> <td>`tooltip_bg_color`</td> <td>`theme_tooltip_bg_color`</td> <td>`theme_bg_color`</td> <td></td> <td></td> </tr>
-- <tr> <td>`tooltip_fg_color`</td> <td>`theme_tooltip_fg_color`</td> <td>`theme_fg_color`</td> <td></td> <td></td> </tr>
-- <tr> <td>`osd_bg_color`</td> <td>`osd_bg`</td> <td>`theme_tooltip_bg_color`</td> <td>`theme_bg_color`</td> <td></td> </tr>
-- <tr> <td>`osd_fg_color`</td> <td>`osd_fg`</td> <td>`theme_tooltip_fg_color`</td> <td>`theme_fg_color`</td> <td></td> </tr>
-- <tr> <td>`osd_border_color`</td> <td>`osd_borders_color`</td> <td>`osd_fg_color`</td> <td></td> <td></td> </tr>
-- <tr> <td>`wm_bg_color`</td> <td>`wm_bg`</td> <td>`menubar_bg_color`</td> <td>`theme_bg_color`</td> <td>HeaderBar bg</td> </tr>
-- <tr> <td>`wm_border_focused_color`</td> <td>`wm_border_focused`</td> <td>`theme_selected_bg_color`</td> <td></td> <td>ToggleButton bg</td> </tr>
-- <tr> <td>`wm_border_unfocused_color`</td> <td>`wm_border_unfocused`</td> <td>`wm_border`</td> <td>`menubar_bg_color`</td> <!--<td>`theme_bg_color`</td>--> <td>HeaderBar bg</td> </tr>
-- <tr> <td>`wm_title_focused_color`</td> <td>`wm_title_focused`</td> <td>`wm_title`</td> <td>`theme_selected_fg_color`</td> <td>ToggleButton fg</td> </tr>
-- <tr> <td>`wm_title_unfocused_color`</td> <td>`wm_title_unfocused`</td> <td>`wm_unfocused_title`</td> <td>`menubar_fg_color`</td> <!--<td>`theme_fg_color`</td>--> <td>HeaderBar fg</td> </tr>
-- <tr> <td>`wm_icons_focused_color`</td> <td>`wm_icons_focused`</td> <td>`wm_title_focused`</td> <td>`theme_selected_fg_color`</td> <td>ToggleButton fg</td> </tr>
-- <tr> <td>`wm_icons_unfocused_color`</td> <td>`wm_icons_unfocused`</td> <td>`wm_title_unfocused`</td> <td>`menubar_fg_color`</td> <!--<td>`theme_fg_color`</td>--> <td>HeaderBar fg</td> </tr>
-- </table>
--
-- @staticfct beautiful.gtk.get_theme_variables
--- The default font.
-- @beautiful beautiful.font
@ -155,6 +205,7 @@ end
-- See https://developer.gnome.org/pango/stable/pango-Fonts.html#PangoFontDescription.
-- @tparam string|lgi.Pango.FontDescription name The name of the font.
-- @treturn lgi.Pango.FontDescription
-- @staticfct beautiful.get_font
function beautiful.get_font(name)
return load_font(name).description
end
@ -165,6 +216,7 @@ end
-- @tparam string|Pango.FontDescription name The base font.
-- @tparam string merge Attributes that should be merged, e.g. "bold".
-- @treturn lgi.Pango.FontDescription
-- @staticfct beautiful.get_merged_font
function beautiful.get_merged_font(name, merge)
local font = beautiful.get_font(name)
merge = Pango.FontDescription.from_string(merge)
@ -175,7 +227,8 @@ end
--- Get the height of a font.
--
-- @param name Name of the font
-- @param name Name of the font.
-- @staticfct beautiful.get_font_height
function beautiful.get_font_height(name)
return load_font(name).height
end
@ -208,6 +261,7 @@ end
-- the theme file (which should return a table) or directly a table
-- containing all the theme values.
-- @treturn true|nil True if successful, nil in case of error.
-- @staticfct beautiful.init
function beautiful.init(config)
if config then
local state, t_theme = nil, nil
@ -258,6 +312,7 @@ end
--- Get the current theme.
--
-- @treturn table The current theme table.
-- @staticfct beautiful.get
function beautiful.get()
return theme
end

10
lib/beautiful/theme_assets.lua
View File

@ -3,7 +3,7 @@
--
-- @author Yauhen Kirylau &lt;yawghen@gmail.com&gt;
-- @copyright 2015 Yauhen Kirylau
-- @submodule beautiful
-- @module beautiful
----------------------------------------------------------------------------
local cairo = require("lgi").cairo
@ -19,6 +19,7 @@ local theme_assets = {}
-- @tparam number size Size.
-- @tparam color fg Background color.
-- @return Image with the square.
-- @staticfct beautiful.theme_assets.taglist_squares_sel
function theme_assets.taglist_squares_sel(size, fg)
local img = cairo.ImageSurface(cairo.Format.ARGB32, size, size)
local cr = cairo.Context(img)
@ -31,6 +32,7 @@ end
-- @tparam number size Size.
-- @tparam color fg Background color.
-- @return Image with the square.
-- @staticfct beautiful.theme_assets.taglist_squares_unsel
function theme_assets.taglist_squares_unsel(size, fg)
local img = cairo.ImageSurface(cairo.Format.ARGB32, size, size)
local cr = cairo.Context(img)
@ -84,6 +86,7 @@ end
-- @tparam color bg Background color.
-- @tparam color fg Main foreground color.
-- @tparam color alt_fg Accent foreground color.
-- @staticfct beautiful.theme_assets.gen_awesome_name
function theme_assets.gen_awesome_name(cr, height, bg, fg, alt_fg)
local ls = height/10 -- letter_size
local letter_line = ls/18
@ -152,6 +155,7 @@ end
-- @tparam number height Height.
-- @tparam color bg Background color.
-- @tparam color fg Foreground color.
-- @staticfct beautiful.theme_assets.gen_logo
function theme_assets.gen_logo(cr, width, height, bg, fg)
local ls = math.min(width, height)
@ -174,6 +178,7 @@ end
-- @tparam color bg Background color.
-- @tparam color fg Background color.
-- @return Image with the logo.
-- @staticfct beautiful.theme_assets.awesome_icon
function theme_assets.awesome_icon(size, bg, fg)
local img = cairo.ImageSurface(cairo.Format.ARGB32, size, size)
local cr = cairo.Context(img)
@ -187,6 +192,7 @@ end
-- @tparam color alt_fg Accent foreground color.
-- @tparam screen s Screen (to get wallpaper size).
-- @return Wallpaper image.
-- @staticfct beautiful.theme_assets.wallpaper
function theme_assets.wallpaper(bg, fg, alt_fg, s)
s = s or screen.primary
local height = s.geometry.height
@ -215,6 +221,7 @@ end
-- @tparam string postfix `nil`, `"hover"` or `"press"`.
-- @tparam string toggle_state `nil`, `"active"` or `"inactive"`.
-- @treturn table Beautiful theme table with the images recolored.
-- @staticfct beautiful.theme_assets.recolor_titlebar
function theme_assets.recolor_titlebar(theme, color, state, postfix, toggle_state)
if postfix then postfix='_'..postfix end
if toggle_state then toggle_state='_'..toggle_state end
@ -266,6 +273,7 @@ end
-- @tparam table theme Beautiful theme table
-- @tparam color color Icons' color.
-- @treturn table Beautiful theme table with the images recolored.
-- @staticfct beautiful.theme_assets.recolor_layout
function theme_assets.recolor_layout(theme, color)
for _, layout_name in ipairs({
'layout_fairh',

9
lib/beautiful/xresources.lua
View File

@ -3,7 +3,7 @@
--
-- @author Yauhen Kirylau &lt;yawghen@gmail.com&gt;
-- @copyright 2015 Yauhen Kirylau
-- @submodule beautiful
-- @module beautiful
----------------------------------------------------------------------------
-- Grab environment
@ -45,7 +45,8 @@ local fallback = {
}
--- Get current base colorscheme from xrdb.
-- @treturn table Color table with keys 'background', 'foreground' and 'color0'..'color15'
-- @treturn table Color table with keys 'background', 'foreground' and 'color0'..'color15'.
-- @staticfct beautiful.xresources.get_current_theme
function xresources.get_current_theme()
local keys = { 'background', 'foreground' }
for i=0,15 do table.insert(keys, "color"..i) end
@ -77,7 +78,7 @@ end
-- This function is deprecated. Use `s.dpi` and avoid getting the DPI without
-- a screen.
--
-- @deprecated xresources.get_dpi
-- @deprecated beautiful.xresources.get_dpi
-- @tparam[opt] integer|screen s The screen.
-- @treturn number DPI value.
@ -118,6 +119,7 @@ end
--- Set DPI for a given screen (defaults to global).
-- @tparam number dpi DPI value.
-- @tparam[opt] integer s Screen.
-- @staticfct beautiful.xresources.set_dpi
function xresources.set_dpi(dpi, s)
s = get_screen(s)
if not s then
@ -132,6 +134,7 @@ end
-- @tparam number size Size
-- @tparam[opt] integer|screen s The screen.
-- @treturn integer Resulting size (rounded to integer).
-- @staticfct beautiful.xresources.apply_dpi
function xresources.apply_dpi(size, s)
return round(size / 96 * xresources.get_dpi(s))
end

14
lib/gears/color.lua
View File

@ -32,10 +32,6 @@
-- calling :set_matrix() on it, because this function uses a cache and your
-- changes could thus have unintended side effects. Use @{create_pattern_uncached}
-- if you need to modify the returned pattern.
-- @see create_pattern_uncached, create_solid_pattern, create_png_pattern,
-- create_linear_pattern, create_radial_pattern
-- @tparam string col The string describing the pattern.
-- @return a cairo pattern object
--
-- @author Uli Schlachter
-- @copyright 2010 Uli Schlachter
@ -65,6 +61,7 @@ local pattern_cache
-- @param col The color to parse
-- @treturn table 4 values representing color in RGBA format (each of them in
-- [0, 1] range) or nil if input is incorrect.
-- @staticfct gears.color.parse_color
-- @usage -- This will return 0, 1, 0, 1
-- gears.color.parse_color("#00ff00ff")
function color.parse_color(col)
@ -123,6 +120,7 @@ end
--
-- @param col The color for the pattern
-- @return A cairo pattern object
-- @staticfct gears.color.create_solid_pattern
function color.create_solid_pattern(col)
if col == nil then
col = "#000000"
@ -136,6 +134,7 @@ end
--
-- @param file The filename of the file
-- @return a cairo pattern object
-- @staticfct gears.color.create_png_pattern
function color.create_png_pattern(file)
if type(file) == "table" then
file = file.file
@ -192,6 +191,7 @@ end
-- For the explanation of `<stops>`, see `color.create_pattern`.
-- @tparam string|table arg The argument describing the pattern.
-- @return a cairo pattern object
-- @staticfct gears.color.create_linear_pattern
function color.create_linear_pattern(arg)
local pat
@ -217,6 +217,7 @@ end
-- For the explanation of `<stops>`, see `color.create_pattern`.
-- @tparam string|table arg The argument describing the pattern
-- @return a cairo pattern object
-- @staticfct gears.color.create_radial_pattern
function color.create_radial_pattern(arg)
local pat
@ -249,6 +250,7 @@ color.types = {
-- @see create_pattern
-- @param col The string describing the pattern.
-- @return a cairo pattern object
-- @staticfct gears.color.create_pattern_uncached
function color.create_pattern_uncached(col)
-- If it already is a cairo pattern, just leave it as that
if cairo.Pattern:is_type_of(col) then
@ -273,6 +275,7 @@ end
--- Create a pattern from a given string, same as @{gears.color}.
-- @see gears.color
-- @staticfct gears.color.create_pattern
function color.create_pattern(col)
if cairo.Pattern:is_type_of(col) then
return col
@ -285,6 +288,7 @@ end
-- operator OVER) doesn't influence the visual result.
-- @param col An argument that `create_pattern` accepts.
-- @return The pattern if it is surely opaque, else nil
-- @staticfct gears.color.create_opaque_pattern
function color.create_opaque_pattern(col)
local pattern = color.create_pattern(col)
local kind = pattern:get_type()
@ -335,6 +339,7 @@ end
-- @param image Image or path to it.
-- @param new_color New color.
-- @return Recolored image.
-- @staticfct gears.color.recolor_image
function color.recolor_image(image, new_color)
if type(image) == 'string' then
image = surface.duplicate_surface(image)
@ -349,6 +354,7 @@ end
-- @param check_color The color to check.
-- @tparam string fallback The color to return if the first is invalid. (default: black)
-- @treturn string color if it is valid, else fallback.
-- @staticfct gears.color.ensure_pango_color
function color.ensure_pango_color(check_color, fallback)
check_color = tostring(check_color)
-- Pango markup supports alpha, PangoColor does not. Thus, check for this.

11
lib/gears/debug.lua
View File

@ -49,6 +49,7 @@ end
-- @param tag The name of the value.
-- @tparam[opt] int depth Depth of recursion.
-- @return string A string that contains the expanded value of data.
-- @staticfct gears.debug.dump_return
function debug.dump_return(data, tag, depth)
return dump_raw(data, nil, tag, depth)
end
@ -57,23 +58,27 @@ end
-- @param data Table to print.
-- @param tag The name of the table.
-- @tparam[opt] int depth Depth of recursion.
-- @staticfct gears.debug.dump
function debug.dump(data, tag, depth)
print(debug.dump_return(data, tag, depth))
end
--- Print an warning message
-- @tparam string message The warning message to print
-- @tparam string message The warning message to print.
-- @staticfct gears.debug.print_warning
function debug.print_warning(message)
io.stderr:write(os.date("%Y-%m-%d %T W: awesome: ") .. tostring(message) .. "\n")
end
--- Print an error message
-- @tparam string message The error message to print
-- @tparam string message The error message to print.
-- @staticfct gears.debug.print_error
function debug.print_error(message)
io.stderr:write(os.date("%Y-%m-%d %T E: awesome: ") .. tostring(message) .. "\n")
end
local displayed_deprecations = {}
--- Display a deprecation notice, but only once per traceback.
--
-- This function also emits the `debug::deprecate` signal on the `awesome`
@ -84,6 +89,7 @@ local displayed_deprecations = {}
-- @tparam boolean args.raw Print the message as-is without the automatic context
-- @tparam integer args.deprecated_in Print the message only when Awesome's
-- version is equal to or greater than deprecated_in.
-- @staticfct gears.debug.deprecate
function debug.deprecate(see, args)
args = args or {}
if args.deprecated_in then
@ -124,6 +130,7 @@ end
-- @tparam string old_name The old class name
-- @tparam string new_name The new class name
-- @treturn table A proxy class.
-- @staticfct gears.debug.deprecate_class
function debug.deprecate_class(fallback, old_name, new_name)
local message = old_name.." has been renamed to "..new_name

18
lib/gears/filesystem.lua
View File

@ -26,6 +26,7 @@ end
--- Create a directory, including all missing parent directories.
-- @tparam string dir The directory.
-- @return (true, nil) on success, (false, err) on failure
-- @staticfct gears.filesystem.make_directories
function filesystem.make_directories(dir)
return make_directory(Gio.File.new_for_path(dir))
end
@ -37,7 +38,8 @@ end
--- Create all parent directories for a given path.
-- @tparam string path The path whose parents should be created.
-- @return (true, nil) on success, (false, err) on failure
-- @return (true, nil) on success, (false, err) on failure.
-- @staticfct gears.filesystem.make_parent_directories
function filesystem.make_parent_directories(path)
return make_directory(Gio.File.new_for_path(path):get_parent())
end
@ -45,6 +47,7 @@ end
--- Check if a file exists, is readable and not a directory.
-- @tparam string filename The file path.
-- @treturn boolean True if file exists and is readable.
-- @staticfct gears.filesystem.file_readable
function filesystem.file_readable(filename)
local gfile = Gio.File.new_for_path(filename)
local gfileinfo = gfile:query_info("standard::type,access::can-read",
@ -56,6 +59,7 @@ end
--- Check if a file exists, is executable and not a directory.
-- @tparam string filename The file path.
-- @treturn boolean True if file exists and is executable.
-- @staticfct gears.filesystem.file_executable
function filesystem.file_executable(filename)
local gfile = Gio.File.new_for_path(filename)
local gfileinfo = gfile:query_info("standard::type,access::can-execute",
@ -67,6 +71,7 @@ end
--- Check if a path exists, is readable and a directory.
-- @tparam string path The directory path.
-- @treturn boolean True if path exists and is readable.
-- @staticfct gears.filesystem.dir_readable
function filesystem.dir_readable(path)
local gfile = Gio.File.new_for_path(path)
local gfileinfo = gfile:query_info("standard::type,access::can-read",
@ -78,30 +83,35 @@ end
--- Check if a path is a directory.
-- @tparam string path The directory path
-- @treturn boolean True if path exists and is a directory.
-- @staticfct gears.filesystem.is_dir
function filesystem.is_dir(path)
return Gio.File.new_for_path(path):query_file_type({}) == "DIRECTORY"
end
--- Get the config home according to the XDG basedir specification.
-- @return the config home (XDG_CONFIG_HOME) with a slash at the end.
-- @staticfct gears.filesystem.get_xdg_config_home
function filesystem.get_xdg_config_home()
return (os.getenv("XDG_CONFIG_HOME") or os.getenv("HOME") .. "/.config") .. "/"
end
--- Get the cache home according to the XDG basedir specification.
-- @return the cache home (XDG_CACHE_HOME) with a slash at the end.
-- @staticfct gears.filesystem.get_xdg_cache_home
function filesystem.get_xdg_cache_home()
return (os.getenv("XDG_CACHE_HOME") or os.getenv("HOME") .. "/.cache") .. "/"
end
--- Get the data home according to the XDG basedir specification.
-- @treturn string the data home (XDG_DATA_HOME) with a slash at the end.
-- @staticfct gears.filesystem.get_xdg_data_home
function filesystem.get_xdg_data_home()
return (os.getenv("XDG_DATA_HOME") or os.getenv("HOME") .. "/.local/share") .. "/"
end
--- Get the data dirs according to the XDG basedir specification.
-- @treturn table the data dirs (XDG_DATA_DIRS) with a slash at the end of each entry.
-- @staticfct gears.filesystem.get_xdg_data_dirs
function filesystem.get_xdg_data_dirs()
local xdg_data_dirs = os.getenv("XDG_DATA_DIRS") or "/usr/share:/usr/local/share"
return gtable.map(
@ -112,12 +122,14 @@ end
--- Get the path to the user's config dir.
-- This is the directory containing the configuration file ("rc.lua").
-- @return A string with the requested path with a slash at the end.
-- @staticfct gears.filesystem.get_configuration_dir
function filesystem.get_configuration_dir()
return awesome.conffile:match(".*/") or "./"
end
--- Get the path to a directory that should be used for caching data.
-- @return A string with the requested path with a slash at the end.
-- @staticfct gears.filesystem.get_cache_dir
function filesystem.get_cache_dir()
local result = filesystem.get_xdg_cache_home() .. "awesome/"
filesystem.make_directories(result)
@ -126,12 +138,14 @@ end
--- Get the path to the directory where themes are installed.
-- @return A string with the requested path with a slash at the end.
-- @staticfct gears.filesystem.get_themes_dir
function filesystem.get_themes_dir()
return (os.getenv('AWESOME_THEMES_PATH') or awesome.themes_path) .. "/"
end
--- Get the path to the directory where our icons are installed.
-- @return A string with the requested path with a slash at the end.
-- @staticfct gears.filesystem.get_awesome_icon_dir
function filesystem.get_awesome_icon_dir()
return (os.getenv('AWESOME_ICON_PATH') or awesome.icon_path) .. "/"
end
@ -141,6 +155,7 @@ end
-- default paths.
-- @param d The directory to get (either "config" or "cache").
-- @return A string containing the requested path.
-- @staticfct gears.filesystem.get_dir
function filesystem.get_dir(d)
if d == "config" then
-- No idea why this is what is returned, I recommend everyone to use
@ -159,6 +174,7 @@ end
-- If ommited, all files are considered.
-- @treturn string|nil A randomly selected filename from the specified path (with
-- a specified extension if required) or nil if no suitable file is found.
-- @staticfct gears.filesystem.get_random_file_from_dir
function filesystem.get_random_file_from_dir(path, exts)
local files, valid_exts = {}, {}

9
lib/gears/geometry.lua
View File

@ -21,7 +21,8 @@ local gears = {geometry = {rectangle = {} } }
-- @tparam number geom.height The rectangle height
-- @tparam number x X coordinate of point
-- @tparam number y Y coordinate of point
-- @treturn number The squared distance of the rectangle to the provided point
-- @treturn number The squared distance of the rectangle to the provided point.
-- @staticfct gears.geometry.rectangle.get_square_distance
function gears.geometry.rectangle.get_square_distance(geom, x, y)
local dist_x, dist_y = 0, 0
if x < geom.x then
@ -42,6 +43,7 @@ end
-- @tparam number x The x coordinate
-- @tparam number y The y coordinate
-- @return The key from the closest geometry.
-- @staticfct gears.geometry.rectangle.get_closest_by_coord
function gears.geometry.rectangle.get_closest_by_coord(list, x, y)
local dist = math.huge
local ret = nil
@ -66,6 +68,7 @@ end
-- @tparam number y The y coordinate
-- @return The key from the closest geometry. In case no result is found, *nil*
-- is returned.
-- @staticfct gears.geometry.rectangle.get_by_coord
function gears.geometry.rectangle.get_by_coord(list, x, y)
for k, geometry in pairs(list) do
if x >= geometry.x and x < geometry.x + geometry.width
@ -126,6 +129,7 @@ end
-- @tparam table recttbl A table of rectangle specifications.
-- @tparam table cur The current rectangle.
-- @return The index for the rectangle in recttbl closer to cur in the given direction. nil if none found.
-- @staticfct gears.geometry.rectangle.get_in_direction
function gears.geometry.rectangle.get_in_direction(dir, recttbl, cur)
local dist, dist_min
local target = nil
@ -151,6 +155,7 @@ end
-- @param a The area.
-- @param b The other area.
-- @return True if they intersect, false otherwise.
-- @staticfct gears.geometry.rectangle.area_intersect_area
function gears.geometry.rectangle.area_intersect_area(a, b)
return (b.x < a.x + a.width
and b.x + b.width > a.x
@ -170,6 +175,7 @@ end
-- @tparam number b.width The rectangle width
-- @tparam number b.height The rectangle height
-- @treturn table The intersect area.
-- @staticfct gears.geometry.rectangle.get_intersection
function gears.geometry.rectangle.get_intersection(a, b)
local g = {}
g.x = math.max(a.x, b.x)
@ -191,6 +197,7 @@ end
-- @tparam number elem.width The rectangle width
-- @tparam number elem.height The rectangle height
-- @return The new area list.
-- @staticfct gears.geometry.rectangle.area_remove
function gears.geometry.rectangle.area_remove(areas, elem)
for i = #areas, 1, -1 do
-- Check if the 'elem' intersect

9
lib/gears/math.lua
View File

@ -37,10 +37,9 @@ end
-- For example, if we consider a set with value { 10, 15, 34 },
-- it will return a table containing 2^n set:
-- { }, { 10 }, { 15 }, { 34 }, { 10, 15 }, { 10, 34 }, etc.
-- @class function
-- @name subsets
-- @param set A set.
-- @return A table with all subset.
-- @staticfct gears.math.subsets
function gmath.subsets(set)
local mask = {}
local ret = {}
@ -56,11 +55,10 @@ function gmath.subsets(set)
end
--- Make i cycle.
-- @class function
-- @name cycle
-- @param t A length. Must be greater than zero.
-- @param i An absolute index to fit into #t.
-- @return An integer in (1, t) or nil if t is less than or equal to zero.
-- @staticfct gears.math.cycle
function gmath.cycle(t, i)
if t < 1 then return end
i = i % t
@ -71,10 +69,9 @@ function gmath.cycle(t, i)
end
--- Round a number to an integer.
-- @class function
-- @name round
-- @tparam number x
-- @treturn integer
-- @staticfct gears.math.round
function gmath.round(x)
return math.floor(x + 0.5)
end

8
lib/gears/object.lua
View File

@ -49,6 +49,7 @@ end
--@DOC_text_gears_object_signal_EXAMPLE@
-- @tparam string name The name of the signal
-- @tparam function func The callback to call when the signal is emitted
-- @method connect_signal
function object:connect_signal(name, func)
assert(type(func) == "function", "callback must be a function, got: " .. type(func))
local sig = find_signal(self, name)
@ -95,6 +96,7 @@ end
-- collected and automatically disconnects the signal when that happens.
-- @tparam string name The name of the signal
-- @tparam function func The callback to call when the signal is emitted
-- @method weak_connect_signal
function object:weak_connect_signal(name, func)
assert(type(func) == "function", "callback must be a function, got: " .. type(func))
local sig = find_signal(self, name)
@ -105,6 +107,7 @@ end
--- Disonnect to a signal.
-- @tparam string name The name of the signal
-- @tparam function func The callback that should be disconnected
-- @method disconnect_signal
function object:disconnect_signal(name, func)
local sig = find_signal(self, name)
sig.weak[func] = nil
@ -117,6 +120,7 @@ end
-- @param ... Extra arguments for the callback functions. Each connected
-- function receives the object as first argument and then any extra arguments
-- that are given to emit_signal()
-- @method emit_signal
function object:emit_signal(name, ...)
local sig = find_signal(self, name)
for func in pairs(sig.strong) do
@ -179,7 +183,8 @@ end
-- when an unknown property is set.
-- @tparam[opt=nil] table args.class
-- @treturn table A new object
-- @function gears.object
-- @constructorfct gears.object
local function new(args)
args = args or {}
local ret = {}
@ -236,6 +241,7 @@ end
-- @tparam[opt=2] integer level Level for `debug.getinfo(level, "S")`.
-- Typically 2 or 3.
-- @treturn string The module name, e.g. "wibox.container.background".
-- @staticfct gears.object.modulename
function object.modulename(level)
return debug.getinfo(level, "S").source:gsub(".*/lib/", ""):gsub("/", "."):gsub("%.lua", "")
end

1
lib/gears/protected_call.lua
View File

@ -43,6 +43,7 @@ end
-- @tparam function func The function to call
-- @param ... Arguments to the function
-- @return The result of the given function, or nothing if an error occurred.
-- @staticfct gears.protected_call
function protected_call.call(func, ...)
return do_pcall(func, ...)
end

21
lib/gears/shape.lua
View File

@ -55,6 +55,7 @@ local module = {}
-- @tparam number width The rectangle width
-- @tparam number height The rectangle height
-- @tparam number radius the corner radius
-- @staticfct gears.shape.rounded_rect
function module.rounded_rect(cr, width, height, radius)
radius = radius or 10
@ -83,7 +84,8 @@ end
--
-- @param cr A cairo content
-- @param width The rectangle width
-- @param height The rectangle height
-- @param height The rectangle height.
-- @staticfct gears.shape.rounded_bar
function module.rounded_bar(cr, width, height)
module.rounded_rect(cr, width, height, height / 2)
end
@ -100,6 +102,7 @@ end
-- @tparam boolean br If the bottom right corner is rounded
-- @tparam boolean bl If the bottom left corner is rounded
-- @tparam number rad The corner radius
-- @staticfct gears.shape.partially_rounded_rect
function module.partially_rounded_rect(cr, width, height, tl, tr, br, bl, rad)
rad = rad or 10
if width / 2 < rad then
@ -151,6 +154,7 @@ end
-- @tparam[opt=5] number corner_radius The corner radius
-- @tparam[opt=10] number arrow_size The width and height of the arrow
-- @tparam[opt=width/2 - arrow_size/2] number arrow_position The position of the arrow
-- @staticfct gears.shape.infobubble
function module.infobubble(cr, width, height, corner_radius, arrow_size, arrow_position)
arrow_size = arrow_size or 10
corner_radius = math.min((height-arrow_size)/2, corner_radius or 5)
@ -184,6 +188,7 @@ end
-- @tparam number width The shape width
-- @tparam number height The shape height
-- @tparam[opt=height/2] number arrow_length The length of the arrow part
-- @staticfct gears.shape.rectangular_tag
function module.rectangular_tag(cr, width, height, arrow_length)
arrow_length = arrow_length or height/2
if arrow_length > 0 then
@ -213,6 +218,7 @@ end
-- @tparam[opt=head_width] number head_width The width of the head (/\) of the arrow
-- @tparam[opt=width /2] number shaft_width The width of the shaft of the arrow
-- @tparam[opt=height/2] number shaft_length The head_length of the shaft (the rest is the head)
-- @staticfct gears.shape.arrow
function module.arrow(cr, width, height, head_width, shaft_width, shaft_length)
shaft_length = shaft_length or height / 2
shaft_width = shaft_width or width / 2
@ -237,6 +243,7 @@ end
-- @param cr A cairo context
-- @tparam number width The shape width
-- @tparam number height The shape height
-- @staticfct gears.shape.hexagon
function module.hexagon(cr, width, height)
cr:move_to(height/2,0)
cr:line_to(width-height/2,0)
@ -256,6 +263,7 @@ end
-- @tparam number width The shape width
-- @tparam number height The shape height
-- @tparam[opt=height/2] number arrow_depth The width of the arrow part of the shape
-- @staticfct gears.shape.powerline
function module.powerline(cr, width, height, arrow_depth)
arrow_depth = arrow_depth or height/2
local offset = 0
@ -283,6 +291,7 @@ end
-- @param cr A cairo context
-- @tparam number width The shape width
-- @tparam number height The shape height
-- @staticfct gears.shape.isosceles_triangle
function module.isosceles_triangle(cr, width, height)
cr:move_to( width/2, 0 )
cr:line_to( width , height )
@ -298,6 +307,7 @@ end
-- @tparam number width The shape width
-- @tparam number height The shape height
-- @tparam[opt=width/3] number thickness The cross section thickness
-- @staticfct gears.shape.cross
function module.cross(cr, width, height, thickness)
thickness = thickness or width/3
local xpadding = (width - thickness) / 2
@ -325,6 +335,7 @@ end
-- @tparam number width The shape width
-- @tparam number height The shape height
-- @tparam number corner_radius
-- @staticfct gears.shape.octogon
function module.octogon(cr, width, height, corner_radius)
corner_radius = corner_radius or math.min(10, math.min(width, height)/4)
local offset = math.sqrt( (corner_radius*corner_radius) / 2 )
@ -348,6 +359,7 @@ end
-- @tparam number width The shape width
-- @tparam number height The shape height
-- @tparam[opt=math.min(width height) / 2)] number radius The radius
-- @staticfct gears.shape.circle
function module.circle(cr, width, height, radius)
radius = radius or math.min(width, height) / 2
cr:move_to(width/2+radius, height/2)
@ -362,6 +374,7 @@ end
-- @param cr A cairo context
-- @tparam number width The shape width
-- @tparam number height The shape height
-- @staticfct gears.shape.rectangle
function module.rectangle(cr, width, height)
cr:rectangle(0, 0, width, height)
end
@ -375,6 +388,7 @@ end
-- @tparam number width The shape width
-- @tparam number height The shape height
-- @tparam[opt=width/3] number base_width The parallelogram base width
-- @staticfct gears.shape.parallelogram
function module.parallelogram(cr, width, height, base_width)
base_width = base_width or width/3
cr:move_to(width-base_width, 0 )
@ -391,6 +405,7 @@ end
-- @param cr A cairo context
-- @tparam number width The shape width
-- @tparam number height The shape height
-- @staticfct gears.shape.losange
function module.losange(cr, width, height)
cr:move_to(width/2 , 0 )
cr:line_to(width , height/2 )
@ -411,6 +426,7 @@ end
-- @tparam[opt=0] number start_angle The start angle (in radian)
-- @tparam[opt=math.pi/2] number end_angle The end angle (in radian)
-- @tparam[opt=math.min(width height)/2] number radius The shape height
-- @staticfct gears.shape.pie
function module.pie(cr, width, height, start_angle, end_angle, radius)
radius = radius or math.floor(math.min(width, height)/2)
start_angle, end_angle = start_angle or 0, end_angle or math.pi/2
@ -444,6 +460,7 @@ end
-- @tparam[opt=math.pi/2] number end_angle The end angle (in radian)
-- @tparam[opt=false] boolean start_rounded if the arc start rounded
-- @tparam[opt=false] boolean end_rounded if the arc end rounded
-- @staticfct gears.shape.arc
function module.arc(cr, width, height, thickness, start_angle, end_angle, start_rounded, end_rounded)
start_angle = start_angle or 0
end_angle = end_angle or math.pi/2
@ -562,6 +579,7 @@ end
-- @tparam number h The shape height
-- @tparam number percent The progressbar percent
-- @tparam boolean hide_left Do not draw the left side of the shape
-- @staticfct gears.shape.radial_progress
function module.radial_progress(cr, w, h, percent, hide_left)
percent = percent or 1
local total_length = (2*(w-h))+2*((h/2)*math.pi)
@ -628,6 +646,7 @@ end
--
-- @param shape A shape function
-- @return A transformation handle, also act as a shape function
-- @staticfct gears.shape.transform
function module.transform(shape)
-- Apply the transformation matrix and apply the shape, then restore

7
lib/gears/sort/topological.lua
View File

@ -18,6 +18,7 @@ end
--- Ensure that `node` appears after all `dependencies`.
-- @param node The node that edges are added to.
-- @tparam table dependencies List of nodes that have to appear before `node`.
-- @method append
function tsort:append(node, dependencies)
add_node(self, node)
for _, dep in ipairs(dependencies) do
@ -29,6 +30,7 @@ end
--- Ensure that `node` appears before all `subordinates`.
-- @param node The node that edges are added to.
-- @tparam table subordinates List of nodes that have to appear after `node`.
-- @method prepend
function tsort:prepend(node, subordinates)
for _, dep in ipairs(subordinates) do
self:append(dep, { node })
@ -63,6 +65,7 @@ end
--- Create a copy of this topological sort.
-- This is useful to backup it before adding elements that can potentially
-- have circular dependencies and thus render the original useless.
-- @method clone
function tsort:clone()
local new = tsort.topological()
@ -75,6 +78,7 @@ end
--- Remove a node from the topological map.
--
-- @param node The node
-- @method remove
function tsort:remove(node)
self._edges[node] = nil
for _, deps in pairs(self._edges) do
@ -86,6 +90,7 @@ end
-- @treturn[1] table A sorted list of nodes
-- @treturn[2] nil
-- @return[2] A node around which a loop exists
-- @method sort
function tsort:sort()
local result, state = {}, {}
for node in pairs(self._edges) do
@ -104,7 +109,7 @@ end
--
--@DOC_text_gears_sort_topological_EXAMPLE@
--
-- @function gears.sort.topological
-- @constructorfct gears.sort.topological
function tsort.topological()
return setmetatable({

45
lib/gears/string.lua
View File

@ -7,43 +7,41 @@
local gstring = {}
local xml_entity_names = { ["'"] = "&apos;", ["\""] = "&quot;", ["<"] = "&lt;", [">"] = "&gt;", ["&"] = "&amp;" };
--- Escape a string from XML char.
-- Useful to set raw text in textbox.
-- @class function
-- @name xml_escape
-- @param text Text to escape.
-- @return Escape text.
-- @staticfct gears.string.xml_escape
function gstring.xml_escape(text)
return text and text:gsub("['&<>\"]", xml_entity_names) or nil
end
local xml_entity_chars = { lt = "<", gt = ">", nbsp = " ", quot = "\"", apos = "'", ndash = "-", mdash = "-",
amp = "&" };
amp = "&" };
--- Unescape a string from entities.
-- @class function
-- @name xml_unescape
-- @param text Text to unescape.
-- @return Unescaped text.
-- @staticfct gears.string.xml_unescape
function gstring.xml_unescape(text)
return text and text:gsub("&(%a+);", xml_entity_chars) or nil
end
--- Count number of lines in a string
-- @class function
-- @name linecount
-- @tparam string text Input string.
-- @treturn int Number of lines.
-- @staticfct gears.string.linecount
function gstring.linecount(text)
return select(2, text:gsub('\n', '\n')) + 1
end
--- Split a string into multiple lines
-- @class function
-- @name linewrap
--- Split a string into multiple lines.
-- @param text String to wrap.
-- @param width Maximum length of each line. Default: 72.
-- @param indent Number of spaces added before each wrapped line. Default: 0.
-- @return The string with lines wrapped to width.
-- @staticfct gears.string.linewrap
function gstring.linewrap(text, width, indent)
text = text or ""
width = width or 72
@ -62,8 +60,7 @@ end
--- Escape all special pattern-matching characters so that lua interprets them
-- literally instead of as a character class.
-- Source: http://stackoverflow.com/a/20778724/15690
-- @class function
-- @name quote_pattern
-- @staticfct gears.string.quote_pattern
function gstring.quote_pattern(s)
-- All special characters escaped in a string: %%, %^, %$, ...
local patternchars = '['..("%^$().[]*+-?"):gsub("(.)", "%%%1")..']'
@ -72,8 +69,7 @@ end
--- Generate a pattern matching expression that ignores case.
-- @param s Original pattern matching expression.
-- @class function
-- @name query_to_pattern
-- @staticfct gears.string.query_to_pattern
function gstring.query_to_pattern(q)
local s = gstring.quote_pattern(q)
-- Poor man's case-insensitive character matching.
@ -87,11 +83,10 @@ end
--- Split separates a string containing a delimiter into the list of
-- substrings between that delimiter.
-- @class function
-- @name split
-- @tparam string str String to be splitted
-- @tparam string delimiter Character where the string will be splitted
-- @treturn table list of the substrings
-- @staticfct gears.string.split
function gstring.split(str, delimiter)
local pattern = "(.-)" .. delimiter .. "()"
local result = {}
@ -106,22 +101,20 @@ function gstring.split(str, delimiter)
return result
end
--- Check if a string starts with another string
-- @class function
-- @name startswith
--- Check if a string starts with another string.
-- @tparam string str String to search
-- @tparam string sub String to check for
-- @tparam string sub String to check for.
-- @staticfct gears.string.startswith
function gstring.startswith(str, sub)
return string.sub(str, 1, string.len(sub)) == sub
return string.sub(str, 1, string.len(sub)) == sub
end
--- Check if a string ends with another string
-- @class function
-- @name endswith
--- Check if a string ends with another string.
-- @tparam string str String to search
-- @tparam string sub String to check for
-- @tparam string sub String to check for.
-- @staticfct gears.string.endswith
function gstring.endswith(str, sub)
return sub == "" or string.sub(str,-string.len(sub)) == sub
return sub == "" or string.sub(str,-string.len(sub)) == sub
end
return gstring

30
lib/gears/surface.lua
View File

@ -35,7 +35,8 @@ end
-- @param default The default value to return on error; when nil, then a surface
-- in an error state is returned.
-- @return The loaded surface, or the replacement default
-- @return An error message, or nil on success
-- @return An error message, or nil on success.
-- @staticfct load_uncached_silently
function surface.load_uncached_silently(_surface, default)
-- On nil, return some sane default
if not _surface then
@ -71,7 +72,8 @@ end
-- in an error state is returned.
-- @return The loaded surface, or the replacement default, or nil if called with
-- nil.
-- @return An error message, or nil on success
-- @return An error message, or nil on success.
-- @staticfct load_silently
function surface.load_silently(_surface, default)
if type(_surface) == "string" then
local cache = surface_cache[_surface]
@ -106,6 +108,7 @@ end
-- via `gears.debug.print_error`.
-- @param _surface The surface to load or nil
-- @return The loaded surface, or nil
-- @staticfct load_uncached
function surface.load_uncached(_surface)
return do_load_and_handle_errors(_surface, surface.load_uncached_silently)
end
@ -114,7 +117,8 @@ end
-- This is usually needed for loading images by file name. Errors are handled
-- via `gears.debug.print_error`.
-- @param _surface The surface to load or nil
-- @return The loaded surface, or nil
-- @return The loaded surface, or nil.
-- @staticfct gears.surface
function surface.load(_surface)
return do_load_and_handle_errors(_surface, surface.load_silently)
end
@ -125,7 +129,8 @@ end
--- Get the size of a cairo surface
-- @param surf The surface you are interested in
-- @return The surface's width and height
-- @return The surface's width and height.
-- @staticfct get_size
function surface.get_size(surf)
local cr = cairo.Context(surf)
local x, y, w, h = cr:clip_extents()
@ -142,6 +147,7 @@ end
-- surface.
-- @param s Source surface.
-- @return The surface's duplicate.
-- @staticfct duplicate_surface
function surface.duplicate_surface(s)
s = surface.load(s)
@ -166,6 +172,7 @@ end
-- @param[opt=white] shape_color The shape color or pattern
-- @param[opt=transparent] bg_color The surface background color
-- @treturn cairo.surface the new surface
-- @staticfct load_from_shape
function surface.load_from_shape(width, height, shape, shape_color, bg_color, ...)
color = color or require("gears.color")
@ -191,7 +198,8 @@ end
-- @param draw A wibox or a client
-- @param shape or gears.shape function or a custom function with a context,
-- width and height as parameter.
-- @param[opt] Any additional parameters will be passed to the shape function
-- @param[opt] Any additional parameters will be passed to the shape function.
-- @staticfct apply_shape_bounding
function surface.apply_shape_bounding(draw, shape, ...)
local geo = draw:geometry()
@ -224,13 +232,15 @@ end
--- Create an SVG file with this widget content.
-- This is dynamic, so the SVG will be updated along with the widget content.
-- because of this, the painting may happen hover multiple event loop cycles.
-- @deprecated wibox.widget.draw_to_svg_file
-- @deprecated draw_to_svg_file
-- @tparam widget widget A widget
-- @tparam string path The output file path
-- @tparam number width The surface width
-- @tparam number height The surface height
-- @return The cairo surface
-- @return The hierarchy
-- @return The hierarchy.
-- @see wibox.widget.draw_to_svg_file
-- @see wibox.widget.draw_to_image_surface
function surface.widget_to_svg(widget, path, width, height)
gdebug.deprecate("Use wibox.widget.draw_to_svg_file instead of "..
"gears.surface.render_to_svg", {deprecated_in=5})
@ -243,13 +253,15 @@ end
--- Create a cairo surface with this widget content.
-- This is dynamic, so the SVG will be updated along with the widget content.
-- because of this, the painting may happen hover multiple event loop cycles.
-- @deprecated wibox.widget.draw_to_image_surface
-- @deprecated draw_to_image_surface
-- @tparam widget widget A widget
-- @tparam number width The surface width
-- @tparam number height The surface height
-- @param[opt=cairo.Format.ARGB32] format The surface format
-- @return The cairo surface
-- @return The hierarchy
-- @return The hierarchy.
-- @see wibox.widget.draw_to_svg_file
-- @see wibox.widget.draw_to_image_surface
function surface.widget_to_surface(widget, width, height, format)
gdebug.deprecate("Use wibox.widget.draw_to_image_surface instead of "..
"gears.surface.render_to_surface", {deprecated_in=5})

51
lib/gears/table.lua
View File

@ -12,10 +12,9 @@ local gtable = {}
--- Join all tables given as arguments.
-- This will iterate over all tables and insert their entries into a new table.
-- @class function
-- @name join
-- @tparam table ... Tables to join.
-- @treturn table A new table containing all entries from the arguments.
-- @staticfct gears.table.join
function gtable.join(...)
local ret = {}
for i = 1, select("#", ...) do
@ -36,12 +35,12 @@ end
--- Override elements in the first table by the one in the second.
--
-- Note that this method doesn't copy entries found in `__index`.
-- @class function
-- @name crush
--
-- @tparam table t the table to be overriden
-- @tparam table set the table used to override members of `t`
-- @tparam[opt=false] bool raw Use rawset (avoid the metatable)
-- @treturn table t (for convenience)
-- @staticfct gears.table.crush
function gtable.crush(t, set, raw)
if raw then
for k, v in pairs(set) do
@ -63,10 +62,9 @@ end
--
-- This function removes any entries with non-numeric keys.
--
-- @class function
-- @name from_sparse
-- @tparam table t A potentially sparse table.
-- @treturn table A packed table with only numeric keys.
-- @staticfct gears.table.from_sparse
function gtable.from_sparse(t)
local keys= {}
for k in pairs(t) do
@ -86,12 +84,12 @@ function gtable.from_sparse(t)
end
--- Check if a table has an item and return its key.
-- @class function
-- @name hasitem
--
-- @tparam table t The table.
-- @param item The item to look for in values of the table.
-- @treturn[1] string|number The key of the item.
-- @treturn[2] nil
-- @staticfct gears.table.hasitem
function gtable.hasitem(t, item)
for k, v in pairs(t) do
if v == item then
@ -110,6 +108,7 @@ end
-- @tparam[opt=nil] number max The maximum number of entries to find.
-- @treturn table|nil An ordered table with all the keys or `nil` if none were
-- found.
-- @staticfct gears.table.find_keys
function gtable.find_keys(t, matcher, ordered, max)
if max == 0 then return nil end
@ -134,7 +133,8 @@ end
-- returning a boolean.
-- @tparam[opt=false] boolean ordered If true, only look for continuous
-- numeric keys.
-- @return The table key or nil
-- @return The table key or nil.
-- @staticfct gears.table.find_first_key
function gtable.find_first_key(t, matcher, ordered)
local ret = gtable.find_keys(t, matcher, ordered, 1)
@ -143,10 +143,10 @@ end
--- Get a sorted table with all integer keys from a table.
-- @class function
-- @name keys
--
-- @tparam table t The table for which the keys to get.
-- @treturn table A table with keys
-- @treturn table A table with keys.
-- @staticfct gears.table.keys
function gtable.keys(t)
local keys = { }
for k, _ in pairs(t) do
@ -159,11 +159,11 @@ function gtable.keys(t)
end
--- Filter a table's keys for certain content type.
-- @class function
-- @name keys_filter
--
-- @tparam table t The table to retrieve the keys for.
-- @tparam string ... The types to look for.
-- @treturn table A filtered table.
-- @staticfct gears.table.keys_filter
function gtable.keys_filter(t, ...)
local keys = gtable.keys(t)
local keys_filtered = { }
@ -179,10 +179,10 @@ function gtable.keys_filter(t, ...)
end
--- Reverse a table.
-- @class function
-- @name reverse
--
-- @tparam table t The table to reverse.
-- @treturn table A reversed table.
-- @staticfct gears.table.reverse
function gtable.reverse(t)
local tr = { }
-- Reverse all elements with integer keys.
@ -199,11 +199,11 @@ function gtable.reverse(t)
end
--- Clone a table.
-- @class function
-- @name clone
--
-- @tparam table t The table to clone.
-- @tparam[opt=true] bool deep Create a deep clone?
-- @treturn table A clone of `t`.
-- @staticfct gears.table.clone
function gtable.clone(t, deep)
deep = deep == nil and true or deep
local c = { }
@ -218,11 +218,10 @@ function gtable.clone(t, deep)
end
--- Iterate over a table.
--
-- Returns an iterator to cycle through all elements of a table that match a
-- given criteria, starting from the first element or the given index.
--
-- @class function
-- @name iterate
-- @tparam table t The table to iterate.
-- @tparam func filter A function that returns true to indicate a positive
-- match.
@ -230,6 +229,7 @@ end
-- @tparam[opt=1] int start Index to start iterating from.
-- Default is 1 (=> start of the table).
-- @treturn func
-- @staticfct gears.table.iterate
function gtable.iterate(t, filter, start)
local count = 0
local index = start or 1
@ -246,11 +246,11 @@ function gtable.iterate(t, filter, start)
end
--- Merge items from one table to another one.
-- @class function
-- @name merge
--
-- @tparam table t The container table
-- @tparam table set The mixin table.
-- @treturn table (for convenience)
-- @treturn table (for convenience).
-- @staticfct gears.table.merge
function gtable.merge(t, set)
for _, v in ipairs(set) do
table.insert(t, v)
@ -259,13 +259,14 @@ function gtable.merge(t, set)
end
--- Map a function to a table.
--
-- The function is applied to each value on the table, returning a modified
-- table.
-- @class function
-- @name map
--
-- @tparam function f The function to be applied to each value in the table.
-- @tparam table tbl The container table whose values will be operated on.
-- @treturn table
-- @staticfct gears.table.map
function gtable.map(f, tbl)
local t = {}
for k,v in pairs(tbl) do

8
lib/gears/timer.lua
View File

@ -194,7 +194,7 @@ end
-- @tparam number timeout Timeout in seconds (e.g. 1.5).
-- @tparam function callback Function to run.
-- @treturn timer The timer object that was set up.
-- @function gears.timer.start_new
-- @staticfct gears.timer.start_new
-- @see gears.timer.weak_start_new
function timer.start_new(timeout, callback)
local t = timer.new({ timeout = timeout })
@ -216,7 +216,7 @@ end
-- @tparam number timeout Timeout in seconds (e.g. 1.5).
-- @tparam function callback Function to start.
-- @treturn timer The timer object that was set up.
-- @function gears.timer.weak_start_new
-- @staticfct gears.timer.weak_start_new
-- @see gears.timer.start_new
function timer.weak_start_new(timeout, callback)
local indirection = setmetatable({}, { __mode = "v" })
@ -234,7 +234,7 @@ local delayed_calls = {}
--- Run all pending delayed calls now. This function should best not be used at
-- all, because it means that less batching happens and the delayed calls run
-- prematurely.
-- @function gears.timer.run_delayed_calls_now
-- @staticfct gears.timer.run_delayed_calls_now
function timer.run_delayed_calls_now()
for _, callback in ipairs(delayed_calls) do
protected_call(unpack(callback))
@ -245,7 +245,7 @@ end
--- Call the given function at the end of the current main loop iteration
-- @tparam function callback The function that should be called
-- @param ... Arguments to the callback function
-- @function gears.timer.delayed_call
-- @staticfct gears.timer.delayed_call
function timer.delayed_call(callback, ...)
assert(type(callback) == "function", "callback must be a function, got: " .. type(callback))
table.insert(delayed_calls, { callback, ... })

8
lib/gears/wallpaper.lua
View File

@ -50,7 +50,8 @@ end
-- global variable.
-- @param s The screen to set the wallpaper on or nil for all screens
-- @return[1] The available geometry (table with entries width and height)
-- @return[1] A cairo context that the wallpaper should be drawn to
-- @return[1] A cairo context that the wallpaper should be drawn to.
-- @staticfct gears.wallpaper.prepare_context
function wallpaper.prepare_context(s)
s = get_screen(s)
@ -109,6 +110,7 @@ end
-- @param pattern The wallpaper that should be set. This can be a cairo surface,
-- a description for gears.color or a cairo pattern.
-- @see gears.color
-- @staticfct gears.wallpaper.set
function wallpaper.set(pattern)
if cairo.Surface:is_type_of(pattern) then
pattern = cairo.Pattern.create_for_surface(pattern)
@ -130,6 +132,7 @@ end
-- gears.color. The default is black.
-- @param scale The scale factor for the wallpaper. Default is 1 (original size).
-- @see gears.color
-- @staticfct gears.wallpaper.centered
function wallpaper.centered(surf, s, background, scale)
local geom, cr = wallpaper.prepare_context(s)
local original_surf = surf
@ -169,6 +172,7 @@ end
-- @param s The screen whose wallpaper should be set. Can be nil, in which case
-- all screens are set.
-- @param offset This can be set to a table with entries x and y.
-- @staticfct gears.wallpaper.tiled
function wallpaper.tiled(surf, s, offset)
local _, cr = wallpaper.prepare_context(s)
@ -198,6 +202,7 @@ end
-- @param ignore_aspect If this is true, the image's aspect ratio is ignored.
-- The default is to honor the aspect ratio.
-- @param offset This can be set to a table with entries x and y.
-- @staticfct gears.wallpaper.maximized
function wallpaper.maximized(surf, s, ignore_aspect, offset)
local geom, cr = wallpaper.prepare_context(s)
local original_surf = surf
@ -238,6 +243,7 @@ end
-- @param background The background color that should be used. Gets handled via
-- gears.color. The default is black.
-- @see gears.color
-- @staticfct gears.wallpaper.fit
function wallpaper.fit(surf, s, background)
local geom, cr = wallpaper.prepare_context(s)
local original_surf = surf

29
lib/menubar/init.lua
View File

@ -4,19 +4,25 @@
-- List of menubar keybindings:
-- ---
--
-- * "Left" | "C-j" select an item on the left
-- * "Right" | "C-k" select an item on the right
-- * "Backspace" exit the current category if we are in any
-- * "Escape" exit the current directory or exit menubar
-- * "Home" select the first item
-- * "End" select the last
-- * "Return" execute the entry
-- * "C-Return" execute the command with awful.spawn
-- * "C-M-Return" execute the command in a terminal
-- <table class='widget_list' border=1>
-- <tr style='font-weight: bold;'>
-- <th align='center'>Keybinding</th>
-- <th align='center'>Description</th>
-- </tr> </td></tr>
-- <tr><td><kbd>Left</kbd><kbd>C-j</kbd></td><td> select an item on the left </td></tr>
-- <tr><td><kbd>Right</kbd><kbd>C-k</kbd></td><td> select an item on the right </td></tr>
-- <tr><td><kbd>Backspace </kbd></td><td> exit the current category if we are in any </td></tr>
-- <tr><td><kbd>Escape </kbd></td><td> exit the current directory or exit menubar </td></tr>
-- <tr><td><kbd>Home </kbd></td><td> select the first item </td></tr>
-- <tr><td><kbd>End </kbd></td><td> select the last </td></tr>
-- <tr><td><kbd>Return </kbd></td><td> execute the entry </td></tr>
-- <tr><td><kbd>C-Return </kbd></td><td> execute the command with awful.spawn </td></tr>
-- <tr><td><kbd>C-M-Return </kbd></td><td> execute the command in a terminal </td></tr>
-- </table>
--
-- @author Alexander Yakushev &lt;yakushev.alex@gmail.com&gt;
-- @copyright 2011-2012 Alexander Yakushev
-- @module menubar
-- @popupmod menubar
---------------------------------------------------------------------------
-- Grab environment we need
@ -362,6 +368,7 @@ end
--- Refresh menubar's cache by reloading .desktop files.
-- @tparam[opt] screen scr Screen.
-- @staticfct menubar.refresh
function menubar.refresh(scr)
scr = get_screen(scr or awful.screen.focused() or 1)
menubar.menu_gen.generate(function(entries)
@ -418,6 +425,7 @@ end
--- Show the menubar on the given screen.
-- @param[opt] scr Screen.
-- @staticfct menubar.show
function menubar.show(scr)
scr = get_screen(scr or awful.screen.focused() or 1)
local fg_color = theme.menubar_fg_normal or theme.menu_fg_normal or theme.fg_normal
@ -492,6 +500,7 @@ function menubar.show(scr)
end
--- Hide the menubar.
-- @staticfct menubar.hide
function menubar.hide()
if instance then
instance.wibox.visible = false

2
lib/menubar/menu_gen.lua
View File

@ -58,6 +58,7 @@ menu_gen.all_categories = {
}
--- Find icons for category entries.
-- @staticfct menubar.menu_gen.lookup_category_icons
function menu_gen.lookup_category_icons()
for _, v in pairs(menu_gen.all_categories) do
v.icon = utils.lookup_icon(v.icon_name)
@ -79,6 +80,7 @@ end
-- @tparam function callback Will be fired when all menu entries were parsed
-- with the resulting list of menu entries as argument.
-- @tparam table callback.entries All menu entries.
-- @staticfct menubar.menu_gen.generate
function menu_gen.generate(callback)
-- Update icons for category entries
menu_gen.lookup_category_icons()

7
lib/menubar/utils.lua
View File

@ -131,6 +131,7 @@ local all_icon_sizes = {
local supported_icon_file_exts = { png = 1, xpm = 2, svg = 3 }
local icon_lookup_path = nil
--- Get a list of icon lookup paths.
-- @treturn table A list of directories, without trailing slash.
local function get_icon_lookup_path()
@ -198,6 +199,7 @@ end
--- Remove CR newline from the end of the string.
-- @param s string to trim
-- @staticfct menubar.utils.rtrim
function utils.rtrim(s)
if not s then return end
if string.byte(s, #s) == 13 then
@ -209,6 +211,7 @@ end
--- Lookup an icon in different folders of the filesystem.
-- @tparam string icon_file Short or full name of the icon.
-- @treturn string|boolean Full name of the icon, or false on failure.
-- @staticfct menubar.utils.lookup_icon_uncached
function utils.lookup_icon_uncached(icon_file)
if not icon_file or icon_file == "" then
return false
@ -244,6 +247,7 @@ local lookup_icon_cache = {}
--- Lookup an icon in different folders of the filesystem (cached).
-- @param icon Short or full name of the icon.
-- @return full name of the icon.
-- @staticfct menubar.utils.lookup_icon
function utils.lookup_icon(icon)
if not lookup_icon_cache[icon] and lookup_icon_cache[icon] ~= false then
lookup_icon_cache[icon] = utils.lookup_icon_uncached(icon)
@ -254,6 +258,7 @@ end
--- Parse a .desktop file.
-- @param file The .desktop file.
-- @return A table with file entries.
-- @staticfct menubar.utils.parse_desktop_file
function utils.parse_desktop_file(file)
local program = { show = true, file = file }
@ -350,6 +355,7 @@ end
-- @tparam function callback Will be fired when all the files were parsed
-- with the resulting list of menu entries as argument.
-- @tparam table callback.programs Paths of found .desktop files.
-- @staticfct menubar.utils.parse_dir
function utils.parse_dir(dir_path, callback)
local function get_readable_path(file)
@ -413,6 +419,7 @@ end
-- @tparam str text Text.
-- @tparam number|screen s Screen
-- @treturn int Text width.
-- @staticfct menubar.utils.compute_text_width
function utils.compute_text_width(text, s)
local w, _ = w_textbox(gstring.xml_escape(text)):get_preferred_size(s)
return w

5
lib/naughty/core.lua
View File

@ -196,6 +196,7 @@ local conns = {}
-- @usage naughty.connect_signal("added", function(notif)
-- -- do something
-- end)
-- @staticfct naughty.connect_signal
function naughty.connect_signal(name, func)
assert(name)
conns[name] = conns[name] or {}
@ -205,6 +206,7 @@ end
--- Emit a notification signal.
-- @tparam string name The signal name.
-- @param ... The signal callback arguments
-- @staticfct naughty.emit_signal
function naughty.emit_signal(name, ...)
assert(name)
for _, func in pairs(conns[name] or {}) do
@ -216,6 +218,7 @@ end
-- @tparam string name The name of the signal
-- @tparam function func The attached function
-- @treturn boolean If the disconnection was successful
-- @staticfct naughty.disconnect_signal
function naughty.disconnect_signal(name, func)
for k, v in ipairs(conns[name] or {}) do
if v == func then
@ -291,6 +294,7 @@ end
-- @treturn true|nil True if all notifications were successfully destroyed, nil
-- otherwise.
-- @see notification_closed_reason
-- @staticfct naughty.destroy_all_notifications
function naughty.destroy_all_notifications(screens, reason)
if not screens then
screens = {}
@ -323,6 +327,7 @@ end
--
-- @param id ID of the notification
-- @return notification object if it was found, nil otherwise
-- @staticfct naughty.get_by_id
function naughty.get_by_id(id)
-- iterate the notifications to get the notfications with the correct ID
for s in pairs(naughty.notifications) do

15
lib/wibox/hierarchy.lua
View File

@ -5,7 +5,7 @@
--
-- @author Uli Schlachter
-- @copyright 2015 Uli Schlachter
-- @module wibox.hierarchy
-- @classmod wibox.hierarchy
---------------------------------------------------------------------------
local matrix = require("gears.matrix")
@ -22,6 +22,7 @@ local widgets_to_count = setmetatable({}, { __mode = "k" })
-- occurrences. Note that for correct operations, the widget must not yet be
-- visible in any hierarchy.
-- @param widget The widget that should be counted.
-- @staticfct wibox.hierarchy.count_widget
function hierarchy.count_widget(widget)
widgets_to_count[widget] = true
end
@ -203,6 +204,7 @@ end
-- hierarchy on widget::layout_changed on some widget.
-- @param callback_arg A second argument that is given to the above callbacks.
-- @return A new widget hierarchy
-- @constructorfct wibox.hierarchy.new
function hierarchy.new(context, widget, width, height, redraw_callback, layout_callback, callback_arg)
local result = hierarchy_new(redraw_callback, layout_callback, callback_arg)
result:update(context, widget, width, height)
@ -217,6 +219,7 @@ end
-- @param[opt] region A region to use for accumulating changed parts
-- @return A cairo region describing the changed parts (either the `region`
-- argument or a new, internally created region).
-- @method update
function hierarchy:update(context, widget, width, height, region)
region = region or cairo.Region.create()
hierarchy_update(self, context, widget, width, height, region, self._matrix, self._matrix_to_device)
@ -224,6 +227,7 @@ function hierarchy:update(context, widget, width, height, region)
end
--- Get the widget that this hierarchy manages.
-- @method get_widget
function hierarchy:get_widget()
return self._widget
end
@ -231,6 +235,7 @@ end
--- Get a matrix that transforms to the parent's coordinate space from this
-- hierarchy's coordinate system.
-- @return A matrix describing the transformation.
-- @method get_matrix_to_parent
function hierarchy:get_matrix_to_parent()
return self._matrix
end
@ -239,6 +244,7 @@ end
-- system (aka the coordinate system of the device that this
-- hierarchy is applied upon) from this hierarchy's coordinate system.
-- @return A matrix describing the transformation.
-- @method get_matrix_to_device
function hierarchy:get_matrix_to_device()
return self._matrix_to_device
end
@ -246,6 +252,7 @@ end
--- Get a matrix that transforms from the parent's coordinate space into this
-- hierarchy's coordinate system.
-- @return A matrix describing the transformation.
-- @method get_matrix_from_parent
function hierarchy:get_matrix_from_parent()
local m = self:get_matrix_to_parent()
return m:invert()
@ -255,6 +262,7 @@ end
-- system (aka the coordinate system of the device that this
-- hierarchy is applied upon) into this hierarchy's coordinate system.
-- @return A matrix describing the transformation.
-- @method get_matrix_from_device
function hierarchy:get_matrix_from_device()
local m = self:get_matrix_to_device()
return m:invert()
@ -264,6 +272,7 @@ end
-- This includes the size of this element plus the size of all children
-- (after applying the corresponding transformation).
-- @return x, y, width, height
-- @method get_draw_extents
function hierarchy:get_draw_extents()
local ext = self._draw_extents
return ext.x, ext.y, ext.width, ext.height
@ -271,6 +280,7 @@ end
--- Get the size that this hierarchy logically covers (in the current coordinate space).
-- @return width, height
-- @method get_size
function hierarchy:get_size()
local ext = self._size
return ext.width, ext.height
@ -278,6 +288,7 @@ end
--- Get a list of all children.
-- @return List of all children hierarchies.
-- @method get_children
function hierarchy:get_children()
return self._children
end
@ -286,6 +297,7 @@ end
-- only works with widgets registered via `count_widget`.
-- @param widget The widget that should be counted
-- @return The number of times that this widget is contained in this hierarchy.
-- @method get_count
function hierarchy:get_count(widget)
return self._widget_counts[widget] or 0
end
@ -301,6 +313,7 @@ end
-- context. The context's clip is used to skip parts that aren't visible.
-- @param context The context in which widgets are drawn.
-- @param cr The cairo context that is used for drawing.
-- @method draw
function hierarchy:draw(context, cr)
local widget = self:get_widget()
if not widget._private.visible then

53
lib/wibox/widget/base.lua
View File

@ -18,12 +18,12 @@ local base = {}
-- {{{ Functions on widgets
--- Functions available on all widgets.
-- Functions available on all widgets.
base.widget = {}
--- Set/get a widget's buttons.
-- @tab _buttons The table of buttons that is bound to the widget.
-- @function buttons
-- @method buttons
function base.widget:buttons(_buttons)
if _buttons then
self._private.widget_buttons = _buttons
@ -33,7 +33,7 @@ end
--- Set a widget's visibility.
-- @tparam boolean b Whether the widget is visible.
-- @function set_visible
-- @method set_visible
function base.widget:set_visible(b)
if b ~= self._private.visible then
self._private.visible = b
@ -45,7 +45,7 @@ end
--- Is the widget visible?
-- @treturn boolean
-- @function get_visible
-- @method get_visible
function base.widget:get_visible()
return self._private.visible or false
end
@ -53,7 +53,7 @@ end
--- Set a widget's opacity.
-- @tparam number o The opacity to use (a number from 0 (transparent) to 1
-- (opaque)).
-- @function set_opacity
-- @method set_opacity
function base.widget:set_opacity(o)
if o ~= self._private.opacity then
self._private.opacity = o
@ -63,7 +63,7 @@ end
--- Get the widget's opacity.
-- @treturn number The opacity (between 0 (transparent) and 1 (opaque)).
-- @function get_opacity
-- @method get_opacity
function base.widget:get_opacity()
return self._private.opacity
end
@ -72,7 +72,7 @@ end
-- @tparam[opt] number width With `nil` the default mechanism of calling the
-- `:fit` method is used.
-- @see fit_widget
-- @function set_forced_width
-- @method set_forced_width
function base.widget:set_forced_width(width)
if width ~= self._private.forced_width then
self._private.forced_width = width
@ -88,7 +88,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
-- @function get_forced_width
-- @method get_forced_width
function base.widget:get_forced_width()
return self._private.forced_width
end
@ -97,7 +97,7 @@ end
-- @tparam[opt] number height With `nil` the default mechanism of calling the
-- `:fit` method is used.
-- @see fit_widget
-- @function set_height
-- @method set_height
function base.widget:set_forced_height(height)
if height ~= self._private.forced_height then
self._private.forced_height = height
@ -112,7 +112,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).
-- @function get_forced_height
-- @method get_forced_height
function base.widget:get_forced_height()
return self._private.forced_height
end
@ -121,7 +121,7 @@ end
--
-- This method should be re-implemented by the relevant widgets.
-- @treturn table The children
-- @function get_children
-- @method get_children
function base.widget:get_children()
return {}
end
@ -131,7 +131,7 @@ end
-- The default implementation does nothing, this must be re-implemented by
-- all layout and container widgets.
-- @tab children A table composed of valid widgets.
-- @function set_children
-- @method set_children
function base.widget:set_children(children) -- luacheck: no unused
-- Nothing on purpose
end
@ -151,7 +151,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 The children
-- @function get_all_children
-- @method get_all_children
function base.widget:get_all_children()
local ret = {}
digg_children(ret, self)
@ -175,7 +175,7 @@ end
--
-- @tparam string signal_name
-- @param ... Other arguments
-- @function emit_signal_recursive
-- @method emit_signal_recursive
function base.widget:emit_signal_recursive(signal_name, ...)
-- This is a convenience wrapper, the real implementation is in the
-- hierarchy.
@ -190,7 +190,7 @@ end
-- @treturn number The index.
-- @treturn widget The parent widget.
-- @treturn table The path between "self" and "widget".
-- @function index
-- @method index
function base.widget:index(widget, recursive, ...)
local widgets = self:get_children()
for idx, w in ipairs(widgets) do
@ -261,7 +261,7 @@ end
--
-- This gives only tight bounds if no rotations by non-multiples of 90° are
-- used.
-- @function wibox.widget.base.rect_to_device_geometry
-- @staticfct wibox.widget.base.rect_to_device_geometry
function base.rect_to_device_geometry(cr, x, y, width, height)
return matrix.transform_rectangle(cr.matrix, x, y, width, height)
end
@ -278,7 +278,7 @@ end
-- @tparam number height The available height for the widget.
-- @treturn number The width that the widget wants to use.
-- @treturn number The height that the widget wants to use.
-- @function wibox.widget.base.fit_widget
-- @staticfct wibox.widget.base.fit_widget
function base.fit_widget(parent, context, widget, width, height)
record_dependency(parent, widget)
@ -326,7 +326,7 @@ end
-- @tparam number width The available width for the widget.
-- @tparam number height The available height for the widget.
-- @treturn[opt] table The result from the widget's `:layout` callback.
-- @function wibox.widget.base.layout_widget
-- @staticfct wibox.widget.base.layout_widget
function base.layout_widget(parent, context, widget, width, height)
record_dependency(parent, widget)
@ -346,7 +346,7 @@ end
--- Handle a button event on a widget.
--
-- This is used internally and should not be called directly.
-- @function wibox.widget.base.handle_button
-- @staticfct wibox.widget.base.handle_button
function base.handle_button(event, widget, x, y, button, modifiers, geometry)
x = x or y -- luacheck: no unused
local function is_any(mod)
@ -395,7 +395,7 @@ end
-- @tparam number height The height of the widget in its own coordinate system.
-- That is, after applying the transformation matrix.
-- @treturn table An opaque object that can be returned from `:layout()`.
-- @function wibox.widget.base.place_widget_via_matrix
-- @staticfct wibox.widget.base.place_widget_via_matrix
function base.place_widget_via_matrix(widget, mat, width, height)
return {
_widget = widget,
@ -415,7 +415,7 @@ end
-- @tparam number height The height of the widget in its own coordinate system.
-- That is, after applying the transformation matrix.
-- @treturn table An opaque object that can be returned from `:layout()`.
-- @function wibox.widget.base.place_widget_at
-- @staticfct wibox.widget.base.place_widget_at
function base.place_widget_at(widget, x, y, width, height)
return base.place_widget_via_matrix(widget, matrix.create_translate(x, y), width, height)
end
@ -535,7 +535,7 @@ end
--
-- See [The declarative layout system](../documentation/03-declarative-layout.md.html).
-- @tab args A table containing the widget's disposition.
-- @function setup
-- @method 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)
@ -562,7 +562,7 @@ end
--
-- See [The declarative layout system](../documentation/03-declarative-layout.md.html).
-- @tab args A table containing the widgets disposition.
-- @function wibox.widget.base.make_widget_declarative
-- @constructorfct wibox.widget.base.make_widget_declarative
function base.make_widget_declarative(args)
local ids = {}
@ -608,6 +608,7 @@ end
-- @param wdg The value.
-- @param[opt=nil] ... Arguments passed to the contructor (if any).
-- @treturn The new widget.
-- @constructorfct wibox.widget.base.make_widget_from_value
function base.make_widget_from_value(wdg, ...)
local is_function, t = is_callable(wdg)
@ -635,7 +636,7 @@ end
-- and setter methods.
-- @tparam[opt=nil] table args.class The widget class
-- @see fit_widget
-- @function wibox.widget.base.make_widget
-- @constructorfct wibox.widget.base.make_widget
function base.make_widget(proxy, widget_name, args)
args = args or {}
local ret = object {
@ -714,7 +715,7 @@ function base.make_widget(proxy, widget_name, args)
end
--- Generate an empty widget which takes no space and displays nothing.
-- @function wibox.widget.base.empty_widget
-- @constructorfct wibox.widget.base.empty_widget
function base.empty_widget()
return base.make_widget()
end
@ -722,7 +723,7 @@ end
--- Do some sanity checking on a widget.
--
-- This function raises an error if the widget is not valid.
-- @function wibox.widget.base.check_widget
-- @staticfct wibox.widget.base.check_widget
function base.check_widget(widget)
assert(type(widget) == "table", "Type should be table, but is " .. tostring(type(widget)))
assert(widget.is_widget, "Argument is not a widget!")

3
lib/wibox/widget/init.lua
View File

@ -37,6 +37,7 @@ setmetatable(widget, {
-- @tparam number width The width of the widget
-- @tparam number height The height of the widget
-- @tparam[opt={dpi=96}] table context The context information to give to the widget.
-- @staticfct wibox.widget.draw_to_cairo_context
function widget.draw_to_cairo_context(wdg, cr, width, height, context)
local function no_op() end
context = context or {dpi=96}
@ -50,6 +51,7 @@ end
-- @tparam number width The surface width
-- @tparam number height The surface height
-- @tparam[opt={dpi=96}] table context The context information to give to the widget.
-- @staticfct wibox.widget.draw_to_svg_file
function widget.draw_to_svg_file(wdg, path, width, height, context)
local img = cairo.SvgSurface.create(path, width, height)
local cr = cairo.Context(img)
@ -64,6 +66,7 @@ end
-- @param[opt=cairo.Format.ARGB32] format The surface format
-- @tparam[opt={dpi=96}] table context The context information to give to the widget.
-- @return The cairo surface
-- @staticfct wibox.widget.draw_to_image_surface
function widget.draw_to_image_surface(wdg, width, height, format, context)
local img = cairo.ImageSurface(format or cairo.Format.ARGB32, width, height)
local cr = cairo.Context(img)

24
luaa.c
View File

@ -33,7 +33,7 @@
*
* @tparam string name The name of the X11 property.
* @tparam string type One of "string", "number" or "boolean".
* @function register_xproperty
* @staticfct register_xproperty
*/
#define _GNU_SOURCE
@ -216,7 +216,7 @@ composite_manager_running(void)
/** Quit awesome.
* @tparam[opt=0] integer code The exit code to use when exiting.
* @function quit
* @staticfct quit
*/
static int
luaA_quit(lua_State *L)
@ -233,7 +233,7 @@ luaA_quit(lua_State *L)
* awesome.
*
* @param cmd The command line to execute.
* @function exec
* @staticfct exec
*/
static int
luaA_exec(lua_State *L)
@ -247,7 +247,7 @@ luaA_exec(lua_State *L)
}
/** Restart awesome.
* @function restart
* @staticfct restart
*/
static int
luaA_restart(lua_State *L)
@ -262,7 +262,7 @@ luaA_restart(lua_State *L)
* @tparam integer sig Signal number.
* See `awesome.unix_signal` for a list of signals.
* @treturn boolean true if the signal was successfully sent, else false
* @function kill
* @staticfct kill
*/
static int
luaA_kill(lua_State *L)
@ -277,7 +277,7 @@ luaA_kill(lua_State *L)
/** Synchronize with the X11 server. This is needed in the test suite to avoid
* some race conditions. You should never need to use this function.
* @function sync
* @staticfct sync
*/
static int
luaA_sync(lua_State *L)
@ -291,7 +291,7 @@ luaA_sync(lua_State *L)
* @param pixbuf The pixbuf as a light user datum.
* @param path The pixbuf origin path
* @return A cairo surface as light user datum.
* @function pixbuf_to_surface
* @staticfct pixbuf_to_surface
*/
static int
luaA_pixbuf_to_surface(lua_State *L)
@ -310,7 +310,7 @@ luaA_pixbuf_to_surface(lua_State *L)
* @return[1] A cairo surface as light user datum.
* @return[2] nil
* @treturn[2] string Error message
* @function load_image
* @staticfct load_image
*/
static int
luaA_load_image(lua_State *L)
@ -340,7 +340,7 @@ luaA_load_image(lua_State *L)
* smaller size is picked. The default is 0 pixels, ie. the smallest icon.
*
* @param size The size of the icons in pixels.
* @function set_preferred_icon_size
* @staticfct set_preferred_icon_size
*/
static int
luaA_set_preferred_icon_size(lua_State *L)
@ -674,7 +674,7 @@ luaA_awesome_index(lua_State *L)
*
* @param name A string with the event name.
* @param func The function to call.
* @function connect_signal
* @staticfct connect_signal
*/
static int
luaA_awesome_connect_signal(lua_State *L)
@ -689,7 +689,7 @@ luaA_awesome_connect_signal(lua_State *L)
*
* @param name A string with the event name.
* @param func The function to call.
* @function disconnect_signal
* @staticfct disconnect_signal
*/
static int
luaA_awesome_disconnect_signal(lua_State *L)
@ -706,7 +706,7 @@ luaA_awesome_disconnect_signal(lua_State *L)
*
* @param name A string with the event name.
* @param ... The signal arguments.
* @function emit_signal
* @staticfct emit_signal
*/
static int
luaA_awesome_emit_signal(lua_State *L)

2
mouse.c
View File

@ -274,7 +274,7 @@ luaA_mouse_coords(lua_State *L)
/** Get the client or any object which is under the pointer.
*
* @treturn client.object|nil A client or nil.
* @function object_under_pointer
* @staticfct object_under_pointer
*/
static int
luaA_mouse_object_under_pointer(lua_State *L)

6
mousegrabber.c
View File

@ -89,7 +89,7 @@ mousegrabber_handleevent(lua_State *L, int x, int y, uint16_t mask)
*
* @param func A callback function as described above.
* @param cursor The name of a X cursor to use while grabbing.
* @function run
* @staticfct run
*/
static int
luaA_mousegrabber_run(lua_State *L)
@ -119,7 +119,7 @@ luaA_mousegrabber_run(lua_State *L)
/** Stop grabbing the mouse pointer.
*
* @function stop
* @staticfct stop
*/
int
luaA_mousegrabber_stop(lua_State *L)
@ -132,7 +132,7 @@ luaA_mousegrabber_stop(lua_State *L)
/** Check if mousegrabber is running.
*
* @treturn boolean True if running, false otherwise.
* @function isrunning
* @staticfct isrunning
*/
static int
luaA_mousegrabber_isrunning(lua_State *L)

6
objects/button.c
View File

@ -45,17 +45,17 @@
/** Get the number of instances.
* @treturn int The number of button objects alive.
* @function instances
* @staticfct instances
*/
/** Set a __index metamethod for all button instances.
* @tparam function cb The meta-method
* @function set_index_miss_handler
* @staticfct set_index_miss_handler
*/
/** Set a __newindex metamethod for all button instances.
* @tparam function cb The meta-method
* @function set_newindex_miss_handler
* @staticfct set_newindex_miss_handler
*/
/** When bound mouse button + modifiers are pressed.

8
objects/client.c
View File

@ -932,17 +932,17 @@
/** Get the number of instances.
*
* @return The number of client objects alive.
* @function instances
* @staticfct instances
*/
/* Set a __index metamethod for all client instances.
* @tparam function cb The meta-method
* @function set_index_miss_handler
* @staticfct set_index_miss_handler
*/
/* Set a __newindex metamethod for all client instances.
* @tparam function cb The meta-method
* @function set_newindex_miss_handler
* @staticfct set_newindex_miss_handler
*/
typedef enum {
@ -2426,7 +2426,7 @@ client_kill(client_t *c)
* @tparam[opt] boolean stacked Return clients in stacking order? (ordered from
* top to bottom).
* @treturn table A table with clients.
* @function get
* @staticfct get
*/
static int
luaA_client_get(lua_State *L)

8
objects/drawable.c
View File

@ -39,7 +39,7 @@
/** Drawable object.
*
* @field surface The drawable's cairo surface.
* @function drawable
* @staticfct drawable
*/
/**
@ -89,17 +89,17 @@
/** Get the number of instances.
*
* @return The number of drawable objects alive.
* @function instances
* @staticfct instances
*/
/** Set a __index metamethod for all drawable instances.
* @tparam function cb The meta-method
* @function set_index_miss_handler
* @staticfct set_index_miss_handler
*/
/** Set a __newindex metamethod for all drawable instances.
* @tparam function cb The meta-method
* @function set_newindex_miss_handler
* @staticfct set_newindex_miss_handler
*/
static lua_class_t drawable_class;

6
objects/key.c
View File

@ -74,17 +74,17 @@
/** Get the number of instances.
*
* @return The number of key objects alive.
* @function instances
* @staticfct instances
*/
/** Set a __index metamethod for all key instances.
* @tparam function cb The meta-method
* @function set_index_miss_handler
* @staticfct set_index_miss_handler
*/
/** Set a __newindex metamethod for all key instances.
* @tparam function cb The meta-method
* @function set_newindex_miss_handler
* @staticfct set_newindex_miss_handler
*/
static void

10
objects/screen.c
View File

@ -191,17 +191,17 @@
/** Get the number of instances.
*
* @return The number of screen objects alive.
* @function instances
* @staticfct instances
*/
/* Set a __index metamethod for all screen instances.
* @tparam function cb The meta-method
* @function set_index_miss_handler
* @staticfct set_index_miss_handler
*/
/* Set a __newindex metamethod for all screen instances.
* @tparam function cb The meta-method
* @function set_newindex_miss_handler
* @staticfct set_newindex_miss_handler
*/
DO_ARRAY(xcb_randr_output_t, randr_output, DO_NOTHING);
@ -1090,7 +1090,7 @@ luaA_screen_module_index(lua_State *L)
* for s in screen do
* print("Oh, wow, we have screen " .. tostring(s))
* end
* @function screen
* @staticfct screen
*/
static int
luaA_screen_module_call(lua_State *L)
@ -1147,7 +1147,7 @@ luaA_screen_get_workarea(lua_State *L, screen_t *s)
/** Get the number of screens.
*
* @return The screen count, at least 1.
* @function count
* @staticfct count
*/
static int
luaA_screen_count(lua_State *L)

10
objects/tag.c
View File

@ -240,17 +240,17 @@
/** Get the number of instances.
*
* @return The number of tag objects alive.
* @function instances
* @staticfct instances
*/
/* Set a __index metamethod for all tag instances.
* @tparam function cb The meta-method
* @function set_index_miss_handler
* @staticfct set_index_miss_handler
*/
/* Set a __newindex metamethod for all tag instances.
* @tparam function cb The meta-method
* @function set_newindex_miss_handler
* @staticfct set_newindex_miss_handler
*/
@ -408,10 +408,10 @@ luaA_tag_new(lua_State *L)
/** Get or set the clients attached to this tag.
*
* @param clients_table None or a table of clients to set as being tagged with
* @tparam[opt=nil] table clients_table None or a table of clients to set as being tagged with
* this tag.
* @return A table with the clients attached to this tags.
* @function clients
* @method clients
*/
static int
luaA_tag_clients(lua_State *L)

20
root.c
View File

@ -223,7 +223,7 @@ _string_to_key_code(const char *s)
* "Shift". Here is a list of the "real" key names matching the modifiers in
* `fake_input`:
*
* <table>
* <table class='widget_list' border=1>
* <tr style='font-weight: bold;'>
* <th align='center'>Modifier name </th>
* <th align='center'>Key name</th>
@ -266,7 +266,7 @@ _string_to_key_code(const char *s)
* coordinates relatives.
* @param x In case of a motion event, this is the X coordinate.
* @param y In case of a motion event, this is the Y coordinate.
* @function fake_input
* @staticfct fake_input
*/
static int
luaA_root_fake_input(lua_State *L)
@ -334,7 +334,7 @@ luaA_root_fake_input(lua_State *L)
*
* @tparam table|nil keys_array An array of key binding objects, or nothing.
* @return The array of key bindings objects of this client.
* @function keys
* @staticfct keys
*/
static int
luaA_root_keys(lua_State *L)
@ -374,7 +374,7 @@ luaA_root_keys(lua_State *L)
*
* @param button_table An array of mouse button bindings objects, or nothing.
* @return The array of mouse button bindings objects.
* @function buttons
* @staticfct buttons
*/
static int
luaA_root_buttons(lua_State *L)
@ -413,7 +413,7 @@ luaA_root_buttons(lua_State *L)
*@DOC_cursor_c_COMMON@
*
* @param cursor_name A X cursor name.
* @function cursor
* @staticfct cursor
*/
static int
luaA_root_cursor(lua_State *L)
@ -439,7 +439,7 @@ luaA_root_cursor(lua_State *L)
/** Get the drawins attached to a screen.
*
* @return A table with all drawins.
* @function drawins
* @staticfct drawins
*/
static int
luaA_root_drawins(lua_State *L)
@ -459,7 +459,7 @@ luaA_root_drawins(lua_State *L)
*
* @param pattern A cairo pattern as light userdata
* @return A cairo surface or nothing.
* @function wallpaper
* @staticfct wallpaper
*/
static int
luaA_root_wallpaper(lua_State *L)
@ -484,7 +484,7 @@ luaA_root_wallpaper(lua_State *L)
*
* @return Width of the root window.
* @return height of the root window.
* @function size
* @staticfct size
*/
static int
luaA_root_size(lua_State *L)
@ -498,7 +498,7 @@ luaA_root_size(lua_State *L)
*
* @return Width of the root window, in millimeters.
* @return height of the root window, in millimeters.
* @function size_mm
* @staticfct size_mm
*/
static int
luaA_root_size_mm(lua_State *L)
@ -510,7 +510,7 @@ luaA_root_size_mm(lua_State *L)
/** Get the attached tags.
* @return A table with all tags.
* @function tags
* @staticfct tags
*/
static int
luaA_root_tags(lua_State *L)

2
selection.c
View File

@ -38,7 +38,7 @@
/** Get the selection (clipboard) content.
*
* @return A string with the selection (clipboard) content.
* @function selection
* @staticfct selection
*/
static xcb_window_t selection_window = XCB_NONE;

2
spawn.c
View File

@ -426,7 +426,7 @@ spawn_child_exited(pid_t pid, int status)
* @treturn[1] integer stdout, if `stdout` is true.
* @treturn[1] integer stderr, if `stderr` is true.
* @treturn[2] string An error string if an error occurred.
* @function spawn
* @staticfct spawn
*/
int
luaA_spawn(lua_State *L)

3
tests/examples/awful/placement/bottom.lua
View File

@ -3,8 +3,7 @@
-- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER
-- @tparam[opt={}] table args Other arguments") --DOC_HEADER
-- @treturn table The new geometry --DOC_HEADER
-- @name bottom --DOC_HEADER
-- @class function --DOC_HEADER
-- @staticfct awful.placement.bottom --DOC_HEADER
screen[1]._resize {width = 128, height = 96} --DOC_HIDE
local awful = {placement = require("awful.placement")} --DOC_HIDE

3
tests/examples/awful/placement/bottom_left.lua
View File

@ -3,8 +3,7 @@
-- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER
-- @tparam[opt={}] table args Other arguments") --DOC_HEADER
-- @treturn table The new geometry --DOC_HEADER
-- @name bottom_left --DOC_HEADER
-- @class function --DOC_HEADER
-- @staticfct awful.placement.bottom_left --DOC_HEADER
screen[1]._resize {width = 128, height = 96} --DOC_HIDE
local awful = {placement = require("awful.placement")} --DOC_HIDE

3
tests/examples/awful/placement/bottom_right.lua
View File

@ -3,8 +3,7 @@
-- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER
-- @tparam[opt={}] table args Other arguments") --DOC_HEADER
-- @treturn table The new geometry --DOC_HEADER
-- @name bottom_right --DOC_HEADER
-- @class function --DOC_HEADER
-- @staticfct awful.placement.bottom_right --DOC_HEADER
screen[1]._resize {width = 128, height = 96} --DOC_HIDE
local awful = {placement = require("awful.placement")} --DOC_HIDE

4
tests/examples/awful/placement/center_horizontal.lua
View File

@ -3,8 +3,8 @@
-- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER
-- @tparam[opt={}] table args Other arguments") --DOC_HEADER
-- @treturn table The new geometry --DOC_HEADER
-- @name center_horizontal --DOC_HEADER
-- @class function --DOC_HEADER
-- @staticfct awful.placement.center_horizontal --DOC_HEADER
screen[1]._resize {width = 128, height = 96} --DOC_HIDE
local awful = {placement = require("awful.placement")} --DOC_HIDE
local c = client.gen_fake {x = 45, y = 35, width=40, height=30} --DOC_HIDE

3
tests/examples/awful/placement/center_vertical.lua
View File

@ -2,8 +2,7 @@
-- Align a client to the vertical center of the parent area. --DOC_HEADER
-- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER
-- @tparam[opt={}] table args Other arguments") --DOC_HEADER
-- @name center_vertical --DOC_HEADER
-- @class function --DOC_HEADER
-- @staticfct awful.placement.center_vertical --DOC_HEADER
screen[1]._resize {width = 128, height = 96} --DOC_HIDE
local awful = {placement = require("awful.placement")} --DOC_HIDE

3
tests/examples/awful/placement/centered.lua
View File

@ -3,8 +3,7 @@
-- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER
-- @tparam[opt={}] table args Other arguments") --DOC_HEADER
-- @treturn table The new geometry --DOC_HEADER
-- @name centered --DOC_HEADER
-- @class function --DOC_HEADER
-- @staticfct awful.placement.centered --DOC_HEADER
screen[1]._resize {width = 128, height = 96} --DOC_HIDE
local awful = {placement = require("awful.placement")} --DOC_HIDE

3
tests/examples/awful/placement/left.lua
View File

@ -3,8 +3,7 @@
-- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER
-- @tparam[opt={}] table args Other arguments") --DOC_HEADER
-- @treturn table The new geometry --DOC_HEADER
-- @name left --DOC_HEADER
-- @class function --DOC_HEADER
-- @staticfct awful.placement.left --DOC_HEADER
screen[1]._resize {width = 128, height = 96} --DOC_HIDE
local awful = {placement = require("awful.placement")} --DOC_HIDE

3
tests/examples/awful/placement/maximize_horizontally.lua
View File

@ -2,8 +2,7 @@
-- Horizontally maximize the drawable in the parent area. --DOC_HEADER
-- @tparam drawable d A drawable (like `client` or `wibox`) --DOC_HEADER
-- @tparam[opt={}] table args Other arguments") --DOC_HEADER
-- @name maximize_horizontally --DOC_HEADER
-- @class function --DOC_HEADER
-- @staticfct awful.placement.maximize_horizontally --DOC_HEADER
screen[1]._resize {width = 128, height = 96} --DOC_HIDE
local placement = require("awful.placement") --DOC_HIDE

3
tests/examples/awful/placement/maximize_vertically.lua
View File

@ -2,8 +2,7 @@
-- Vetically maximize the drawable in the parent area. --DOC_HEADER
-- @tparam drawable d A drawable (like `client` or `wibox`) --DOC_HEADER
-- @tparam[opt={}] table args Other arguments") --DOC_HEADER
-- @name maximize_vertically --DOC_HEADER
-- @class function --DOC_HEADER
-- @staticfct awful.placement.maximize_vertically --DOC_HEADER
screen[1]._resize {width = 128, height = 96} --DOC_HIDE
local placement = require("awful.placement") --DOC_HIDE

3
tests/examples/awful/placement/right.lua
View File

@ -3,8 +3,7 @@
-- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER
-- @tparam[opt={}] table args Other arguments") --DOC_HEADER
-- @treturn table The new geometry --DOC_HEADER
-- @name right --DOC_HEADER
-- @class function --DOC_HEADER
-- @staticfct awful.placement.right --DOC_HEADER
screen[1]._resize {width = 128, height = 96} --DOC_HIDE
local awful = {placement = require("awful.placement")} --DOC_HIDE

3
tests/examples/awful/placement/stretch_down.lua
View File

@ -3,8 +3,7 @@
-- @tparam drawable d A drawable (like `client` or `wibox`) --DOC_HEADER
-- @tparam[opt={}] table args Other arguments --DOC_HEADER
-- @treturn table The new geometry --DOC_HEADER
-- @name stretch_down --DOC_HEADER
-- @class function --DOC_HEADER
-- @staticfct awful.placement.stretch_down --DOC_HEADER
screen[1]._resize {width = 128, height = 96} --DOC_HIDE
local placement = require("awful.placement") --DOC_HIDE

3
tests/examples/awful/placement/stretch_left.lua
View File

@ -3,8 +3,7 @@
-- @tparam drawable d A drawable (like `client` or `wibox`) --DOC_HEADER
-- @tparam[opt={}] table args Other arguments --DOC_HEADER
-- @treturn table The new geometry --DOC_HEADER
-- @name stretch_left --DOC_HEADER
-- @class function --DOC_HEADER
-- @staticfct awful.placement.stretch_left --DOC_HEADER
screen[1]._resize {width = 128, height = 96} --DOC_HIDE
local placement = require("awful.placement") --DOC_HIDE

3
tests/examples/awful/placement/stretch_right.lua
View File

@ -3,8 +3,7 @@
-- @tparam drawable d A drawable (like `client` or `wibox`) --DOC_HEADER
-- @tparam[opt={}] table args Other arguments --DOC_HEADER
-- @treturn table The new geometry --DOC_HEADER
-- @name stretch_right --DOC_HEADER
-- @class function --DOC_HEADER
-- @staticfct awful.placement.stretch_right --DOC_HEADER
screen[1]._resize {width = 128, height = 96} --DOC_HIDE
local placement = require("awful.placement") --DOC_HIDE

3
tests/examples/awful/placement/stretch_up.lua
View File

@ -3,8 +3,7 @@
-- @tparam drawable d A drawable (like `client` or `wibox`) --DOC_HEADER
-- @tparam[opt={}] table args Other arguments --DOC_HEADER
-- @treturn table The new geometry --DOC_HEADER
-- @name stretch_up --DOC_HEADER
-- @class function --DOC_HEADER
-- @staticfct awful.placement.stretch_up --DOC_HEADER
screen[1]._resize {width = 128, height = 96} --DOC_HIDE
local placement = require("awful.placement") --DOC_HIDE

3
tests/examples/awful/placement/top.lua
View File

@ -3,8 +3,7 @@
-- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER
-- @tparam[opt={}] table args Other arguments") --DOC_HEADER
-- @treturn table The new geometry --DOC_HEADER
-- @name top --DOC_HEADER
-- @class function --DOC_HEADER
-- @staticfct awful.placement.top --DOC_HEADER
screen[1]._resize {width = 128, height = 96} --DOC_HIDE
local awful = {placement = require("awful.placement")} --DOC_HIDE

3
tests/examples/awful/placement/top_left.lua
View File

@ -3,8 +3,7 @@
-- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER
-- @tparam[opt={}] table args Other arguments") --DOC_HEADER
-- @treturn table The new geometry --DOC_HEADER
-- @name top_left --DOC_HEADER
-- @class function --DOC_HEADER
-- @staticfct awful.placement.top_left --DOC_HEADER
screen[1]._resize {width = 128, height = 96} --DOC_HIDE
local awful = {placement = require("awful.placement")} --DOC_HIDE

3
tests/examples/awful/placement/top_right.lua
View File

@ -3,8 +3,7 @@
-- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER
-- @tparam[opt={}] table args Other arguments") --DOC_HEADER
-- @treturn table The new geometry --DOC_HEADER
-- @name top_right --DOC_HEADER
-- @class function --DOC_HEADER
-- @staticfct awful.placement.top_right --DOC_HEADER
screen[1]._resize {width = 128, height = 96} --DOC_HIDE
local awful = {placement = require("awful.placement")} --DOC_HIDE

6
xkb.c
View File

@ -36,7 +36,7 @@
/**
* Switch keyboard layout.
*
* @function xkb_set_layout_group
* @staticfct xkb_set_layout_group
* @tparam integer num keyboard layout number, integer from 0 to 3
*/
int
@ -56,7 +56,7 @@ luaA_xkb_set_layout_group(lua_State *L)
/**
* Get current layout number.
*
* @function xkb_get_layout_group
* @staticfct xkb_get_layout_group
* @treturn integer num Current layout number, integer from 0 to 3.
*/
int
@ -87,7 +87,7 @@ luaA_xkb_get_layout_group(lua_State *L)
/**
* Get layout short names.
*
* @function xkb_get_group_names
* @staticfct xkb_get_group_names
* @treturn string A string describing the current layout settings,
* e.g.: 'pc+us+de:2+inet(evdev)+group(alt_shift_toggle)+ctrl(nocaps)'
*/