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

doc: Add documentation linting and fix all issues it found.

This commit is contained in:
Emmanuel Lepage Vallee 2021-12-20 21:54:15 -08:00
parent b4c989bcf8
commit 4bd90f0f35
111 changed files with 1891 additions and 724 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
dbus.c
View File

@ -19,7 +19,14 @@
*
*/
/** awesome D-Bus API
/** A deprecated low-level D-Bus API **DO NOT USE**.
*
* `lgi.GDBus` is always better. This module will eventually be removed.
* If it ever breaks due to an upstream API change, it wont be fixed.
*
* It still exists for compatibility reasons since some user have used it
* in the past.
*
* @author Julien Danjou <julien@danjou.info>
* @copyright 2008-2009 Julien Danjou
* @module dbus
@ -798,10 +805,10 @@ luaA_dbus_disconnect_signal(lua_State *L)
* @param path A string with the dbus path.
* @param interface A string with the dbus interface.
* @param method A string with the dbus method name.
* @param type_1st_arg type of 1st argument
* @param value_1st_arg value of 1st argument
* @param type_2nd_arg type of 2nd argument
* @param value_2nd_arg value of 2nd argument
* @param type_1st_arg Type of 1st argument
* @param value_1st_arg Value of 1st argument
* @param type_2nd_arg Type of 2nd argument
* @param value_2nd_arg Value of 2nd argument
* ... etc
* @function emit_signal
*/

2
docs/05-awesomerc.md.lua
View File

@ -324,6 +324,8 @@ rc_lua:close()
table.insert(output_script, "-- @script rc.lua")
table.insert(output_script, "-- @usebeautiful beautiful.awesome_icon")
table.insert(output_script, "-- @usebeautiful beautiful.wallpaper")
rc_script = assert(io.open(rc_script, "w"))
rc_script:write(table.concat(output_script, "\n"))

66
docs/common/client_theme.ldoc
View File

@ -344,6 +344,21 @@
* @see request::border
*/
/**
* The client border width for the fullscreen clients.
*
* This is the fallback if the more stateful version, like
* `beautiful.border_width_fullscreen_urgent` isn't set.
*
* @beautiful beautiful.border_width_fullscreen
* @param integer
* @see request::border
* @see beautiful.border_width_fullscreen_active
* @see beautiful.border_width_fullscreen_normal
* @see beautiful.border_width_fullscreen_urgent
* @see beautiful.border_width_fullscreen_new
*/
/**
* The client opacity for the normal clients.
*
@ -391,7 +406,6 @@
*
* @beautiful beautiful.opacity_floating_normal
* @param[opt=1] number
* @see request::border
*/
/**
@ -424,6 +438,21 @@
* @see request::border
*/
/**
* The client opacity for the floating clients.
*
* A number between 0 and 1. This is the fallback if the more stateful
* variables, like `beautiful.opacity_floating_new` are not set.
*
* @beautiful beautiful.opacity_floating
* @param[opt=1] number
* @see request::border
* @see beautiful.opacity_floating_normal
* @see beautiful.opacity_floating_active
* @see beautiful.opacity_floating_urgent
* @see beautiful.opacity_floating_new
*/
/**
* The client opacity for the normal maximized clients.
*
@ -431,7 +460,6 @@
*
* @beautiful beautiful.opacity_maximized_normal
* @param[opt=1] number
* @see request::border
*/
/**
@ -463,6 +491,22 @@
* @param[opt=1] number
* @see request::border
*/
/**
* The client opacity for the maximized clients.
*
* A number between 0 and 1. This is the fallback if a more stateful
* variable, like `beautiful.opacity_maximized_urgent`, isn't set.
*
* @beautiful beautiful.opacity_maximized
* @param[opt=1] number
* @see request::border
* @see beautiful.opacity_maximized_normal
* @see beautiful.opacity_maximized_active
* @see beautiful.opacity_maximized_urgent
* @see beautiful.opacity_maximized_new
*/
/**
* The client opacity for the normal fullscreen clients.
*
@ -470,7 +514,6 @@
*
* @beautiful beautiful.opacity_fullscreen_normal
* @param[opt=1] number
* @see request::border
*/
/**
@ -503,4 +546,21 @@
* @see request::border
*/
/**
* The client opacity for the fullscreen clients.
*
* A number between 0 and 1. This is the fallback if the variables
* for more stateful versions, like `beautiful.opacity_fullscreen_urgent`,
* are not set.
*
* @beautiful beautiful.opacity_fullscreen
* @param[opt=1] number
* @see request::border
* @see beautiful.opacity_fullscreen_new
* @see beautiful.opacity_fullscreen_urgent
* @see beautiful.opacity_fullscreen_active
* @see beautiful.opacity_fullscreen_normal
*/
/*

1
docs/common/notification_rules_index.ldoc
View File

@ -37,6 +37,7 @@
-- <tr><td><a href='../core_components/notification.html#auto_reset_timeout'>auto\_reset\_timeout</a></td><td>If the timeout needs to be reset when a property changes</td></tr>
-- <tr><td><a href='../core_components/notification.html#ignore_suspend'>ignore\_suspend</a></td><td></td></tr>
-- <tr><td><a href='../core_components/notification.html#clients'>clients</a></td><td>A list of clients associated with this notification</td></tr>
-- <tr><td><a href='../core_components/notification.html#max_width'>max\_width</a></td><td>The maximum popup width</td></tr>
-- <tr><td><a href='../core_components/notification.html#app_name'>app\_name</a></td><td>The application name specified by the notification</td></tr>
-- <tr><td><a href='../core_components/notification.html#widget_template'>widget\_template</a></td><td>The widget template used to represent the notification</td></tr>
-- </table>

71
docs/common/wibox.ldoc
View File

@ -2,7 +2,7 @@
--
-- @baseclass wibox
-- @property border_width
-- @param integer
-- @tparam[opt=0] integer border_width
-- @propemits false false
--- Border color.
@ -25,21 +25,21 @@
--
-- @baseclass wibox
-- @property border_color
-- @param string
-- @tparam[opt=beautiful.fg_normal] string border_color
-- @propemits false false
--- On top of other windows.
--
-- @baseclass wibox
-- @property ontop
-- @param boolean
-- @tparam[opt=false] boolean ontop
-- @propemits false false
--- The mouse cursor.
--
-- @baseclass wibox
-- @property cursor
-- @param string
-- @tparam string cursor
-- @see mouse
-- @propemits false false
@ -47,7 +47,7 @@
--
-- @baseclass wibox
-- @property visible
-- @param boolean
-- @tparam boolean visible
-- @propemits false false
--- The opacity of the wibox, between 0 and 1.
@ -61,7 +61,7 @@
--
-- @baseclass wibox
-- @property type
-- @param string
-- @tparam string type
-- @see client.type
-- @propemits false false
@ -69,35 +69,35 @@
--
-- @baseclass wibox
-- @property x
-- @param integer
-- @tparam integer x
-- @propemits false false
--- The y coordinates.
--
-- @baseclass wibox
-- @property y
-- @param integer
-- @tparam integer y
-- @propemits false false
--- The width of the wibox.
--
-- @baseclass wibox
-- @property width
-- @param width
-- @tparam integer width
-- @propemits false false
--- The height of the wibox.
--
-- @baseclass wibox
-- @property height
-- @param height
-- @tparam integer height
-- @propemits false false
--- The wibox screen.
--
-- @baseclass wibox
-- @property screen
-- @param screen
-- @tparam screen screen
-- @propemits true false
--- The wibox's `drawable`.
@ -110,14 +110,14 @@
--- The widget that the `wibox` displays.
-- @baseclass wibox
-- @property widget
-- @param widget
-- @tparam[opt=nil] wibox.widget widget
-- @propemits true false
--- The X window id.
--
-- @baseclass wibox
-- @property window
-- @param string
-- @tparam string window
-- @see client.window
-- @propemits false false
@ -129,7 +129,7 @@
--
-- @baseclass wibox
-- @property shape_bounding
-- @param surface._native
-- @tparam surface._native shape_bounding
-- @propemits false false
-- @see shape
@ -140,7 +140,7 @@
--
-- @baseclass wibox
-- @property shape_clip
-- @param surface._native
-- @tparam surface._native shape_clip
-- @propemits false false
-- @see shape
@ -152,7 +152,7 @@
--
-- @baseclass wibox
-- @property shape_input
-- @param surface._native
-- @tparam surface._native shape_input
-- @propemits false false
-- @see input_passthrough
@ -174,7 +174,7 @@
--
-- @baseclass wibox
-- @property input_passthrough
-- @param[opt=false] boolean
-- @tparam[opt=false] boolean input_passthrough
-- @see shape_input
-- @propemits true false
@ -182,14 +182,15 @@
--
-- @baseclass wibox
-- @property buttons
-- @param buttons_table A table of buttons objects, or nothing.
-- @tparam table buttons A table of buttons objects, or nothing.
-- @propemits false false
--- Get or set wibox geometry. That's the same as accessing or setting the x,
-- y, width or height properties of a wibox.
--
-- @baseclass wibox
-- @param A table with coordinates to modify.
-- @tparam[opt=nil] table|nil geo A table with coordinates to modify. If
-- nothing is specified, it only returns the current geometry.
-- @return A table with wibox coordinates and geometry.
-- @method geometry
-- @emits property::geometry When the geometry change.
@ -205,31 +206,12 @@
-- the side of the screen).
--
-- @baseclass wibox
-- @param strut A table with new strut, or nothing
-- @return The wibox strut in a table.
-- @method struts
-- @tparam table struts A table with new strut, or nothing.
-- @see client.struts
-- @emits property::struts
--- The default background color.
--
-- The background color can be transparent. If there is a
-- compositing manager such as compton, then it will be
-- real transparency and may include blur (provided by the
-- compositor). When there is no compositor, it will take
-- a picture of the wallpaper and blend it.
--
-- @baseclass wibox
-- @beautiful beautiful.bg_normal
-- @param color
-- @see bg
--- The default foreground (text) color.
-- @baseclass wibox
-- @beautiful beautiful.fg_normal
-- @param color
-- @see fg
--- Set a declarative widget hierarchy description.
-- See [The declarative layout system](../documentation/03-declarative-layout.md.html)
-- @param args An array containing the widgets disposition
@ -246,8 +228,8 @@
--
-- @baseclass wibox
-- @property bg
-- @tparam c The background to use. This must either be a cairo pattern object,
-- nil or a string that gears.color() understands.
-- @tparam[opt=beautiful.bg_normal] color bg The background to use. This
-- must either be a cairo pattern object, nil or a string that gears.color() understands.
-- @see gears.color
-- @propemits true false
-- @usebeautiful beautiful.bg_normal The default (fallback) bg color.
@ -257,18 +239,17 @@
-- If `image` is a function, it will be called with `(context, cr, width, height)`
-- as arguments. Any other arguments passed to this method will be appended.
--
-- @tparam gears.suface|string|function image A background image or a function.
-- @baseclass wibox
-- @property bgimage
-- @tparam gears.suface|string|function bgimage A background image or a function.
-- @see gears.surface
-- @propemits true false
--- The foreground (text) of the wibox.
-- @tparam color c The foreground to use. This must either be a cairo pattern object,
-- nil or a string that gears.color() understands.
--
-- @baseclass wibox
-- @property fg
-- @param color
-- @tparam[opt=beautiful.fg_normal] gears.color fg
-- @see gears.color
-- @propemits true false
-- @usebeautiful beautiful.fg_normal The default (fallback) fg color.

20
docs/common/widget.ldoc
View File

@ -19,23 +19,23 @@
-- Warning: This method it prone to stack overflow id the widget, or any of its
-- children, contain (directly or indirectly) itself.
-- @property all_children
-- @tparam table children The children.
-- @tparam table all_children The children.
-- @baseclass wibox.widget
--- 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
-- @tparam table args An array containing the widgets disposition
-- @method setup
-- @baseclass wibox.widget
--- Force a widget height.
-- @property forced_height
-- @tparam number|nil height The height (`nil` for automatic)
-- @tparam number|nil forced_height The height (`nil` for automatic)
-- @baseclass wibox.widget
--- Force a widget width.
-- @property forced_width
-- @tparam number|nil width The width (`nil` for automatic)
-- @tparam number|nil forced_width The width (`nil` for automatic)
-- @baseclass wibox.widget
--- The widget opacity (transparency).
@ -45,7 +45,7 @@
--- The widget visibility.
-- @property visible
-- @param boolean
-- @tparam[opt=true] boolean visible
-- @baseclass wibox.widget
--- The widget buttons.
@ -53,7 +53,7 @@
-- The table contains a list of `awful.button` objects.
--
-- @property buttons
-- @param table
-- @tparam table buttons
-- @see awful.button
-- @baseclass wibox.widget
@ -96,7 +96,7 @@
-- @tparam number button The button number.
-- @tparam table mods The modifiers (mod4, mod1 (alt), Control, Shift)
-- @tparam table find_widgets_result The entry from the result of
-- @{wibox.drawable:find_widgets} for the position that the mouse hit.
-- @{wibox:find_widgets} for the position that the mouse hit.
-- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
-- the widget.
-- @tparam widget find_widgets_result.widget The widget being displayed.
@ -127,7 +127,7 @@
-- @tparam number button The button number.
-- @tparam table mods The modifiers (mod4, mod1 (alt), Control, Shift)
-- @tparam table find_widgets_result The entry from the result of
-- @{wibox.drawable:find_widgets} for the position that the mouse hit.
-- @{wibox:find_widgets} for the position that the mouse hit.
-- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
-- the widget.
-- @tparam widget find_widgets_result.widget The widget being displayed.
@ -152,7 +152,7 @@
-- @signal mouse::enter
-- @tparam table self The current object instance itself.
-- @tparam table find_widgets_result The entry from the result of
-- @{wibox.drawable:find_widgets} for the position that the mouse hit.
-- @{wibox:find_widgets} for the position that the mouse hit.
-- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
-- the widget.
-- @tparam widget find_widgets_result.widget The widget being displayed.
@ -177,7 +177,7 @@
-- @signal mouse::leave
-- @tparam table self The current object instance itself.
-- @tparam table find_widgets_result The entry from the result of
-- @{wibox.drawable:find_widgets} for the position that the mouse hit.
-- @{wibox:find_widgets} for the position that the mouse hit.
-- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
-- the widget.
-- @tparam widget find_widgets_result.widget The widget being displayed.

759
docs/config.ld
View File

@ -1,24 +1,27 @@
local args = ...
local ldoc = nil
-- luacheck: globals new_type
-- Configuration file for ldoc
project='awesome'
title='awesome API documentation'
description='API documentation for awesome, a highly configurable X window manager (version @AWESOME_VERSION@).'
project='awesome' -- luacheck: globals project
title='awesome API documentation' -- luacheck: globals title
description='API documentation for awesome, a highly configurable X window manager (version @AWESOME_VERSION@).' -- luacheck: globals description
-- More on it: https://github.com/stevedonovan/LDoc/blob/master/doc/doc.md#markdown-support
format='discount'
dir='../doc'
format='discount' -- luacheck: globals format
dir='../doc' -- luacheck: globals dir
-- Make the docs prettier
pretty='lua'
style=true
template=true
backtick_references=true
merge=true
use_markdown_titles=true
wrap=true
pretty='lua' -- luacheck: globals pretty
style=true -- luacheck: globals style
template=true -- luacheck: globals template
backtick_references=true -- luacheck: globals backtick_references
merge=true -- luacheck: globals merge
use_markdown_titles=true -- luacheck: globals use_markdown_titles
wrap=true -- luacheck: globals wrap
-- luacheck: globals full_description
full_description = [[
Welcome to the documentation for the Awesome window manager. Below you find an
overview of the individual parts which links to the full documentation.
@ -92,52 +95,327 @@ topics={
'89-NEWS.md',
}
local databases, named_tags, item_id, is_init = {}, {}, 1, false
local all_theme_vars, delayed_collect = nil, {}
local function collect_item_common(tab, mod, item)
tab[item.name] = tab[item.name] or {}
local var = tab[item.name]
var[mod.name] = var[mod.name] or {}
var[mod.name][#var[mod.name] + 1] = item
end
--- Add another custom tag **value** to an existing item.
-- @tparam string tag_data The raw/unparsed string for the
-- tag. It will be parsed like any other tags.
local function add_custom_tag_common(item, tag_name, meta_tag, tag_data)
item.tags = item.tags or {}
item.tags[tag_name] = item.tags[tag_name] or {}
item.tags[tag_name][#item.tags[tag_name] + 1] = tag_data
if meta_tag.collect_callback then
delayed_collect[#delayed_collect+1] = {item, item.module, tag_name, tag_data}
end
end
-- Wrap the global `new_type` to allow us to extend what types can do, the
-- same is done below for custom tags.
local function create_type(args)
new_type(args.name, args.title, args.project_level, args.subfield_title)
databases[args.name] = databases[args.name] or {}
databases[args.name].collect = args.collect_callback
databases[args.name].finish = args.finish_callback
return args
end
-- Add the @usebeautiful from the optional/default value.
local function auto_add_usebeautiful(item)
local vars, var_names = {}, {}
-- Datamine the default values to autogenerate the @usebeautiful.
for parm in ldoc.modules.iter(item.params) do
for p in ldoc.modules.iter(item:subparam(parm)) do
local def = item:default_of_param(p)
if def and def ~= true then
for var in def:gmatch("beautiful[.][a-z_]+") do
if not var_names[var] then
vars[#vars+1] = var
end
var_names[var] = true
end
end
end
end
for _, var in ipairs(vars) do
named_tags.usebeautiful:add_to_item(item, var)
end
end
-- The first stereotype are the constructors.
new_type("constructorfct", "Constructors", false, "Parameters")
new_type("constructorfct2", "ldoc_skip", false, "Parameters")
create_type {
name = "constructorfct",
title = "Constructors",
project_level = false,
subfield_title = "Parameters",
collect_callback = auto_add_usebeautiful,
}
-- Some constructors like `awful.key` have both a named parameter
-- syntax and a multiple function parameter syntax.
create_type {
name = "constructorfct2",
title = "ldoc_skip",
project_level = false,
subfield_title = "Parameters",
}
-- Hack to get the functions on top of the signals and properties
new_type("function", "Functions", false, "Parameters")
create_type {
name = "function",
title = "Functions",
project_level = false,
subfield_title = "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")
create_type {
name = "staticfct",
title = "Static module functions",
project_level = false,
subfield_title = "Parameters",
}
-- Documentation for objects properties
new_type("property", "Object properties", false, "Type constraints")
create_type {
name = "property",
title = "Object properties",
project_level = false,
subfield_title = "Type constraints",
collect_callback = auto_add_usebeautiful,
finish_callback = function(item)
-- All properties need to have a type. Otherwise they don't render
-- properly. Also, because typed properties are kind of the point of
-- switching to ldoc in the first place.
if (not item.params) or not item.params[1] then
print(
"WARNING: The ".. item.name .." property from "..item.module.name.." is missing it's type."
)
return
end
local param = item:subparam(item.params[1])
local type = item:type_of_param(param[1])
-- Force people to use @tparam because it is easier to lint and allows
-- multiple types.
if (not type) or type == "" then
print(
"WARNING: Property ".. item.name .." from "..item.module.name.." either "..
" doesn't have a type or uses @param instead of @tparam. @tparam is required"..
" because it allows multi-type and better default value handling."
)
end
-- One of the repeated problem we have is the first word of the
-- description being removed because it is used as the property name.
-- This "rule" might be stupid, but it prevents it from accidentally
-- happening again.
if item.params[1] ~= item.name:match("[.]?("..item.params[1]..")$") then
print(
"WARNING: Property ".. item.name .." from "..item.module.name.." @tparam name"..
" doesn't match the property name. For linting purpose, please fix this."
)
end
end
}
-- Documentation for objects deprecated properties
new_type("deprecatedproperty", "Deprecated object properties", false, "Type constraints")
create_type {
name = "deprecatedproperty",
title = "Deprecated object properties",
project_level = false,
subfield_title = "Type constraints",
}
-- Documentation for objects deprecated methods
new_type("deprecatedmethod", "Deprecated object methods", false, "Parameters")
create_type {
name = "deprecatedmethod",
title = "Deprecated object methods",
project_level = false,
subfield_title = "Parameters",
}
-- Use a custom type for the methods to bypass the faulty ldoc built-in detection.
-- (yes, the space after Methods *is* on purpose to avoid clashing with ldoc
-- internal "methods" concept)
new_type("method", "Object methods ", false, "Parameters")
-- New type for signals
new_type("signal", "Signals", false, "Arguments")
create_type {
name = "method",
title = "Object methods ",
project_level = false,
subfield_title = "Parameters",
}
-- New type for signals.
local all_signals
all_signals = create_type {
name = "signal",
title = "Signals",
project_level = false,
subfield_title = "Arguments",
collection = {},
collect_callback = function(item, mod)
collect_item_common(all_signals.collection, mod, item)
end,
}
-- Deprecated signals.
new_type("deprecatedsignal", "Deprecated signals", false, "Arguments")
create_type {
name = "deprecatedsignal",
title = "Deprecated signals",
project_level = false,
subfield_title = "Arguments",
}
-- New type for signals connections
new_type("signalhandler", "Request handlers", false, "Arguments")
create_type {
name = "signalhandler",
title = "Request handlers",
project_level = false,
subfield_title = "Arguments",
}
-- Allow objects to define a set of beautiful properties affecting them
new_type("beautiful", "Theme variables", false, "Type constraints")
all_theme_vars = create_type {
name = "beautiful",
title = "Theme variables",
project_level = false,
subfield_title = "Type constraints",
collection = {},
collect_callback = function(item, mod)
if item.name:sub(1,4) ~= "beau" then
-- This would be a bug.
if item.name:match("[.]") then
print("WANRING: A beautiful variable is called `", item.name, "`. This name is invalid.")
end
-- This happens because the `ldoc` messes with the name. All variables
if item.module.name == "beautiful" then
item.name = "beautiful." .. item.name
else
print(
"WARNING: All theme variable need a `beautiful.` prefix. It appears",
item.name,
" lacks it"
)
end
end
collect_item_common(all_theme_vars.collection, mod, item)
-- Those are global variables, there can be only one per name.
if all_theme_vars.collection[item.name] then
local mod = pairs(all_theme_vars.collection[item.name])(all_theme_vars.collection[item.name])
if mod ~= item.module.name then
print("ERROR: "..item.name, "from", item.module.name, "is already defined in module ", mod)
end
end
end,
finish_callback = function(item)
if item.tags["beautiful_used_by"] then return end
-- Every variable should be consumed by something. Better "park" some
-- variable in the constructors than leave them disconnected from the
-- global model.
print("WARNING: ", item.name, "is not used by anything, add @usebeautiful or @propbeautiful")
end
}
-- Put deprecated methods in their own section
new_type("deprecated", "Deprecated functions", false, "Parameters")
create_type {
name = "deprecated",
title = "Deprecated functions",
project_level = false,
subfield_title = "Parameters",
}
-- For the legacy stateless layout related functions
new_type("legacylayout", "Layout related functions", false, "Parameters")
create_type {
name = "legacylayout",
title = "Layout related functions",
project_level = false,
subfield_title = "Parameters",
}
-- Have a category for the client layouts
new_type("clientlayout", "Client layouts", false, "Parameters")
create_type {
name = "clientlayout",
title = "Client layouts",
project_level = false,
subfield_title = "Parameters",
}
-- Source functions for the taglist/tasklist/layoutlist
new_type("sourcefunction", "List source functions", false)
create_type {
name = "sourcefunction",
title = "List source functions",
project_level = false,
}
-- Document some callback prototypes
new_type("callback", "Callback functions prototype", false, "Parameters")
create_type {
name = "callback",
title = "Callback functions prototype",
project_level = false,
subfield_title = "Parameters",
}
-- gears.matcher / awful.rules sources
new_type("rulesources", "Rule sources", false, "Parameters")
create_type {
name = "rulesources",
title = "Rule sources",
project_level = false,
subfield_title = "Parameters",
}
-- gears.matcher / awful.rules rule components
new_type("rulecomponent", "Rule components", false, "Type")
create_type {
name = "rulecomponent",
title = "Rule components",
project_level = false,
subfield_title = "Type",
}
-- Filter functions for the taglist/tasklist/layoutlist
new_type("filterfunction", "List filters", false)
create_type {
name = "filterfunction",
title = "List filters",
project_level = false,
}
-- Extra client properties available only in awful.rules/spawn constructs
new_type("clientruleproperty", "Extra properties available in the rules", false, "Type")
create_type {
name = "clientruleproperty",
title = "Extra properties available in the rules",
project_level = false,
subfield_title = "Type",
}
-- Extra *matching* properties for rules.
new_type("matchingproperty", "Extra matching properties used in rules", false, "Type")
create_type {
name = "matchingproperty",
title = "Extra matching properties used in rules",
project_level = false,
subfield_title = "Type",
}
-- Simulate the default "params" parser format, except the optional "[]" section
-- needs a space.
@ -224,16 +502,18 @@ local function default_format_callback(self, params, _, md)
end
-- Generate a format function.
local function default_format(self, callback)
local function default_format(self, callback, name)
return function(raw, item, md)
return (callback or default_format_callback)(
self, parse_custom_tags(raw, self.params or {}), item, md
)
local p = name and item.parsed_tags and item.parsed_tags[name] and item.parsed_tags[name][raw]
if not p then
p = parse_custom_tags(raw, self.params or {})
end
return (callback or default_format_callback)(self, p, item, md)
end
end
local named_tags, item_id = {}, 1
-- Add a new @something which can be used in any types.
-- @tparam table args
-- @tparam string args.name The name.
@ -250,9 +530,26 @@ add_custom_tag = function(args)
custom_tags = custom_tags or {}
databases[name] = databases[name] or {}
databases[name].collect = args.collect_callback
local f = args.format
args.format = default_format(args, f)
args.format = default_format(args, f, name)
function args:add_to_item(item, tag_value)
add_custom_tag_common(item, name, args, tag_value)
local parsed = parse_custom_tags(tag_value, args.params or {})
if parsed then
item.parsed_tags = item.parsed_tags or {}
item.parsed_tags[name] = item.parsed_tags[name] or {}
item.parsed_tags[name][tag_value] = parsed
end
item.has_show_more = item.has_show_more or (not args.hidden)
end
custom_tags[#custom_tags+1] = args
named_tags[name] = args
@ -288,7 +585,17 @@ add_custom_tag {
{
name = "name"
}
}
},
collect_callback = function(item, mod, tag, value)
local parsed = parse_custom_tags(value, named_tags.emits.params)
all_signals.collection[parsed.name.value] = all_signals.collection[parsed.name.value] or {}
local var = all_signals.collection[parsed.name.value]
var[mod.name] = var[mod.name] or {}
var[mod.name][#var[mod.name] + 1] = item
end
}
-- Avoid repetitive boilerplate code for property signals.
@ -349,7 +656,25 @@ add_custom_tag {
name = "name",
markdown = true,
}
}
},
collect_callback = function(item, mod, tag, value)
local params = parse_custom_tags(value, named_tags.usebeautiful.params)
if all_theme_vars.collection[params.name.value] then
local sig_mods = all_theme_vars.collection[params.name.value]
local _, themed_items = pairs(sig_mods)(sig_mods)
local themed_item = themed_items[1]
named_tags.beautiful_used_by:add_to_item(themed_item, item.name.." "..item.summary)
-- Auto fill the description if its empty.
if (not params.description) or params.description == "" then
params.description = themed_item.summary
end
else
print("WARNING: Could not find theme variable", params.name.value)
end
end
}
-- For all properties which have a standard `@beautiful` variable for them
@ -380,6 +705,18 @@ add_custom_tag {
end
return ret
end,
finish_callback = function(item, raw, params, modules)
local modname = item.module.name:gmatch("[^.]+$")()
local name = "beautiful."..(modname.."_"..item.name):gsub("[.]", "_")
if all_theme_vars.collection[name] then
local sig_mods = all_theme_vars.collection[name]
local _, themed_items = pairs(sig_mods)(sig_mods)
local themed_item = themed_items[1]
named_tags.beautiful_used_by:add_to_item(themed_item, item.name.." "..item.summary)
end
end
}
@ -476,7 +813,6 @@ add_custom_tag {
add_custom_tag {
name = "hidden",
hidden = true,
auto_subtags = false
}
-- Mark the item as readonly.
@ -487,6 +823,87 @@ add_custom_tag {
hidden = true,
auto_subtags = false
}
add_custom_tag {
name = "signalhandler",
hidden = false,
title = "Request handler",
auto_subtags = false,
params = {
{ name = "source" },
},
format = function(self, params, item, md)
return ldoc.markup("`"..params.source.value.."`") .. " " .. params.description
end
}
add_custom_tag {
name = "beautiful_used_by",
hidden = false,
title = "Used by",
auto_subtags = false,
params = {
{ name = "source" },
},
format = function(self, params, item, md)
return ldoc.markup("`"..params.source.value.."`") .. " " .. params.description
end
}
-- Auto generate some code for replacing request handlers.
add_custom_tag {
name = "sourcesignal",
title = "Source signal",
hidden = false,
params = {
{ name = "class" },
{ name = "signal" },
},
format = function(self, params, item, md)
return ldoc.markup("`"..params.signal.value.."` from the `"..params.class.value.."` module.")..
" This code allows to disconnect this handler and implement your own:"
end,
finish_callback = function(item, raw, params, modules)
if all_signals.collection[params.signal.value] then
local sig_mods = all_signals.collection[params.signal.value]
local _, signal_items = pairs(sig_mods)(sig_mods)
local signal_item = signal_items[1]
-- Auto generate some code.
local code = "-- Disconnect the original handler.\n"
code = code .. signal_item.module.name .. ".disconnect_signal('".. params.signal.value .."', "..item.name..")\n\n"
code = code .. "-- Connect a custom handler.\n"
code = code .. signal_item.module.name .. ".connect_signal('".. params.signal.value .."', function("
if signal_item.type == "signal" then
for idx, parm in ipairs(signal_item.params) do
code = code .. parm .. (idx == #signal_item.params and "" or ", ")
end
code = code .. ")\n -- code here\nend)"
named_tags.signalhandler:add_to_item(signal_item, item.name.." "..item.summary)
end
item.tag_extra_data = item.tag_extra_data or {}
item.tag_extra_data["sourcesignal"] = item.tag_extra_data["sourcesignal"] or {}
item.tag_extra_data["sourcesignal"][raw] = item.tag_extra_data["sourcesignal"][raw] or {}
item.tag_extra_data["sourcesignal"][raw].usage = ldoc.prettify(code)
item.has_show_more = true
end
end
}
-- @rangestart
-- @rangeend
-- @minimumvalue
-- @maximumvalue
-- @tenumvalue
-- @increments
-- @tablekey or not?
-- More fitting section names
kind_names={topic='Documentation', module='Libraries', script='Sample files'}
@ -514,7 +931,6 @@ file = {
'../selection.c',
'../spawn.c',
'../xkb.c',
'../common/luaobject.c',
'../objects/client.c',
'../objects/drawable.c',
'../objects/screen.c',
@ -573,6 +989,7 @@ file = {
'../lib/wibox/layout/rotate.lua',
'../lib/wibox/layout/scroll.lua',
'../lib/wibox/widget/background.lua',
'../lib/wibox/drawable.lua',
}
}
@ -585,10 +1002,16 @@ local function wrap_modname(str, item)
end
local named_args = {
[ "(args)" ] = true,
[ "([args])" ] = true,
[ "([args=nil])" ] = true,
[ "([args={}])" ] = true
[ "(args)" ] = true,
[ "([args])" ] = true,
[ "([args=nil])" ] = true,
[ "([args={}])" ] = true,
[ '(<span class="optional_param">args</span>)' ] = true,
}
local param_name_whitelist = {
Mod2 = true,
Lock = true,
}
-- Sections which are hidden by default, but visible when clicked.
@ -607,6 +1030,27 @@ local delimiter_for_tag = {
usebeautiful = { "table class='widget_list' border=1", "table", "tr", "tr", {"Theme variable", "Usage"}},
propbeautiful = { "table class='widget_list' border=1", "table", "tr", "tr", {"Theme variable", "Usage"}},
request = { "table class='widget_list' border=1", "table", "tr", "tr", {"Class", "Permission", "Context", "Default", "Description"}},
sourcesignal = { "div", "div", "span", "span" }
}
--- If the title is short and descritive, there is no point to bloat it.
--
-- That test is mostly to catch empty or lazy description (such as the module
-- name and nothing else).
local short_title_whitelist = {
[ "rc.lua" ] = true,
[ "naughty.action" ] = true,
[ "naughty.layout.box" ] = true,
[ "naughty.widget.title" ] = true,
[ "theme.lua" ] = true,
[ "wibox.container.margin" ] = true,
[ "wibox.container.arcchart"] = true,
[ "wibox.widget.checkbox" ] = true,
[ "wibox.widget.imagebox" ] = true,
[ "wibox.widget.separator" ] = true,
[ "wibox.widget.progressbar"] = true,
[ "naughty" ] = true,
[ "xproperties" ] = true,
}
-- Use the first word of the subtag content to map it to its tag.
@ -636,7 +1080,7 @@ local function generate_summary(item)
end
end
local ret, has_show_more = {}, false
local ret, has_show_more = {}, item.has_show_more or false
for k, v in ipairs(tgs) do
if v.count > 0 then
@ -719,20 +1163,26 @@ local function init_custom_types(item)
-- Allow the template to fetch the right sub-tags.
function item.get_auto_params(tag, value)
local extra = (item.tag_extra_data and item.tag_extra_data[tag] and item.tag_extra_data[tag][value]) or {}
-- Makes auto-generated subtags easier to implement.
if item.auto_params[tag.."tparam_override"] then
return item.auto_params[tag.."tparam_override"], named_tags[tag.."tparam"]
return item.auto_params[tag.."tparam_override"], named_tags[tag.."tparam"], extra
end
if not item.auto_params[tag.."tparam"] then return nil, nil end
local parsed = nil
local parsed = parse_custom_tags(value, named_tags[tag].params)
if item.parsed_tags and item.parsed_tags[tag] and item.parsed_tags[tag][value] then
parsed = item.parsed_tags[tag][value]
end
if not item.auto_params[tag.."tparam"] then return nil, nil, extra end
if parsed.name and item.auto_params[tag.."tparam"][parsed.name.value] then
return item.auto_params[tag.."tparam"][parsed.name.value], named_tags[tag.."tparam"]
return item.auto_params[tag.."tparam"][parsed.name.value], named_tags[tag.."tparam"], extra
end
return nil, nil
return nil, nil, extra
end
item.is_init = true
@ -780,8 +1230,7 @@ local function pipe_to_or(s)
end
-- Parse the magic parameters to type in something the template eats.
local function sanitize_type(item, ldoc)
local function sanitize_type(item)
for parm in ldoc.modules.iter(item.params) do
local t = item:type_of_param(parm)
@ -810,9 +1259,37 @@ local function sanitize_type(item, ldoc)
item.display_type = "<span class='summary_type'>N/A</span>"
end
-- Detect error prone markdown formatting.
local function detect_markdown_footguns(string)
for line in string:gmatch("[^\n]*") do
if line:sub(1,4) ~= " " then
local is_tick = false
-- Detect unquoted code with 2 underscores. They will render as italic,
-- which is definitively not wanted. Add "`" to fix.
for part in line:gmatch("[^`]*") do
if not is_tick then
local count = 0
for under in part:gmatch("[^\\]_") do
count = count + 1
end
if count > 1 then
return false
end
end
is_tick = not is_tick
end
end
end
return true
end
-- Add parentheses when there is alternative return types.
local function generate_return_tuple(item, group, ldoc)
local function generate_return_tuple(item, group)
local tuple = {}
for r in group:iter() do
@ -843,7 +1320,7 @@ local function generate_return_tuple(item, group, ldoc)
end
-- Create a return type string.
local function sanitize_return_type(item, ldoc)
local function sanitize_return_type(item)
local groups = item.retgroups
@ -870,6 +1347,164 @@ local function sanitize_return_type(item, ldoc)
item.compact_signature = true
end
-- Traverse the entire doc and reverse-map the links between our custom
-- tags and the content it is pointing toward. From that, we add some
-- "consumers"/"providers" tables to each (relevant) item.
local function global_init(_ldoc)
ldoc = _ldoc
if is_init then return end
is_init = true
local module_by_name = {}
-- First pass, gather the providers.
for _, mod in ipairs(ldoc.modules) do
module_by_name[mod.name] = mod
if mod.type ~= "topic" and ((not mod.summary) or mod.summary == "" or mod.summary:lower():sub(1,8) == "awesome") then
print("WARNING: Each module needs a good summary as its first line", mod.name, "doesn't")
end
local sum_count = 0
for line in (mod.summary or ""):gmatch("[^\n]*") do
sum_count = sum_count + 1
end
if sum_count > 1 and #mod.summary > 120 then
print("WARNING:", mod.name, "summary has to be only 1 line.")
end
if mod.summary and #mod.summary < 30 and not short_title_whitelist[mod.name] then
print("WARNING:", mod.name, "summary is too short.")
end
for tag, values in pairs(mod.tags) do
for _, value in ipairs(values.gmatch and {values} or values) do
-- Collect instances of some types.
if databases[tag] and databases[tag].collect then
delayed_collect[#delayed_collect+1] = {mod, mod, tag, value}
end
end
end
for kind, items in mod.kinds() do
for item in items() do
-- Decorate the item with our customizations.
init_custom_types(item)
-- print(item.description)
if item.summary and not detect_markdown_footguns(item.summary) then
print(
"WARNING: "..item.name.." from "..item.module.name.." seems to have"..
" ambiguous markdown in its summary, probably underscores. Please either"..
" use '`' or HTML."
)
end
-- Collect instances of some types.
if databases[item.type] and databases[item.type].collect then
databases[item.type].collect(item, mod)
end
for tag, values in pairs(item.tags) do
for _, value in ipairs(values.gmatch and {values} or values) do
-- Collect instances of some types.
if databases[tag] and databases[tag].collect then
delayed_collect[#delayed_collect+1] = {item, mod, tag, value}
end
end
end
-- Lint the parameters too.
for parm in ldoc.modules.iter(item.params) do
local first = parm:match("^[ ]*(.)")
-- If the first letter of a parameter is capital, the type is probably missing.
-- That's what happen if you rename @param to @tparam without actually adding the type.
if first and first ~= first:lower() and parm:upper() ~= parm and not param_name_whitelist[parm] then
print(
"ERROR: Parameter "..parm.." from ".. item.name .. " ".. item.module.name..
" starts with a capital letter. This is forbidden."
)
end
for p in ldoc.modules.iter(item:subparam(parm)) do
local desc = item.params.map[p]
if not detect_markdown_footguns(desc) then
print(
"WARNING: Always use '`' to encapsulate code in the parameters." ..
p .. " from " .. item.name .. " " .. item.module.name .. " contains " ..
"some ambiguous markup. If this is a false positive, use HTML."
)
end
-- It *sometime* works, but is at risk if being interpreted as code by markdown.
if desc:match("^ [ ]+") then
print(
"WARNING: ", item.name, "from", item.module.name, "has a parameter description "..
"with leading spaces. This will not render correctly", "'"..desc.."'"
)
end
first = desc:match("^[ ]*([a-z])")
if first and first ~= first:upper() then
print("WARNING: Sentences starts with a capital letter. Please fix", item.module.name, item.name)
end
--TODO convert @propbeautiful to @usebeautiful and lint them
--TODO check the module summary.
end
end
end
end
end
-- Second pass, collect the custom tags. This is delayed because
-- the tags depend on the items. Not all items have been processed if
-- this was called during the first pass. Also, collect callbacks can
-- themselves create more delayed_collect entries recursively.
for _, to_collect in ipairs(delayed_collect) do
databases[to_collect[3]].collect(to_collect[1], to_collect[2], to_collect[3], to_collect[4])
end
-- Third pass, parse every custom tags and fill the consumers tables.
for _, mod in ipairs(ldoc.modules) do
for kind, items in mod.kinds() do
for item in items() do
for tag_name, values in pairs(item.tags) do
for _, tag in ipairs(values.gmatch and {values} or values) do
local parsed = named_tags[tag_name]
and named_tags[tag_name].params
and parse_custom_tags(tag, named_tags[tag_name].params)
-- Allow the tags to, ie, auto-generate some extra content.
if named_tags[tag_name] and named_tags[tag_name].finish_callback then
named_tags[tag_name].finish_callback(item, tag, parsed, module_by_name)
end
-- Save the parsed content to be used in get_auto_params.
if parsed then
item.parsed_tags = item.parsed_tags or {}
item.parsed_tags[tag_name] = item.parsed_tags[tag_name] or {}
item.parsed_tags[tag_name][tag] = parsed
end
end
end
-- Mostly for linting.
if databases[item.type] and databases[item.type].finish then
databases[item.type].finish(item, mod, module_by_name)
end
end
end
end
end
-- Work around the fact that tag/awful.tag client/awful.client pages
-- are merged.
local function compare_module_name(input, module)
@ -956,6 +1591,8 @@ local is_deprecated = {
}
custom_display_name_handler = function(item, default_handler)
item.global_init = global_init
if is_deprecated[item.type] then
item.tags.is_deprecated = {true}
end

4
docs/ldoc.css
View File

@ -190,11 +190,11 @@ span.default_value,
border-bottom: solid 1px #bcd;
}
#content pre {
#content pre, .auto_genenerated_code {
margin: 15px;
}
pre {
pre, .auto_genenerated_code {
background-color: rgb(50, 55, 68);
color: white;
border-radius: 3px;

19
docs/ldoc.ltp
View File

@ -37,6 +37,15 @@
# local no_underscores = function(s) return s:gsub("_", " ") end
# local get_item = function(mod, name) for item in iter(mod.items) do if item.name == name then return item end end; return name == "" and mod or nil end
# -- Poke a hole to allow config.ld code to have a global initialization.
# for m in iter(ldoc.modules) do
# if #m.items > 0 then
# display_name(m.items[1])
# m.items[1].global_init(ldoc)
# break
# end
# end
# --------- modules hierarchy -------------
# local hierarchy = {}
# local curr = module
@ -67,7 +76,7 @@
# local myitems = {}
# for item in items() do
# myitems[#myitems + 1] = item
# end
# end
# all_module_kinds[#all_module_kinds + 1] = { kind = kind, items = myitems }
# end
# local filtered_kinds = { "Constructors", "Static module functions",
@ -532,7 +541,7 @@
# end -- if group_header then
# for value in iter(tag) do
<$(row_type_begin)>$(custom.format and custom.format(value, item, M) or M(value))</$(row_type_end)>
# local sub_values, sub_custom = item.get_auto_params(custom[1], value)
# local sub_values, sub_custom, extra_data = item.get_auto_params(custom[1], value)
# if sub_values then
<ul>
# for _, value in ldoc.ipairs(sub_values) do
@ -540,6 +549,12 @@
# end -- for auto_params
</ul>
# end -- if item.auto_params
# if extra_data.usage then
<br/>
<p>
<pre class="auto_genenerated_code">$(extra_data.usage)</pre>
# end -- extra_data.usage
# end -- for
</$(group_end)>
# end -- if tag

13
lib/awful/button.lua
View File

@ -70,38 +70,39 @@ button.names = {
-- Please note that Awesome ignores the status of "Lock" and "Mod2" (Num Lock).
--
-- @property modifiers
-- @tparam table modifiers
--- The mouse button identifier.
--
-- ![Mouse buttons](../images/mouse.svg)
--
-- @property button
-- @param integer
-- @tparam integer button
--- The button description.
--
-- @property description
-- @param string
-- @tparam string description
--- The button name.
--
-- @property name
-- @param string
-- @tparam string name
--- The button group.
--
-- @property group
-- @param string
-- @tparam string group
--- The callback when this button is pressed.
--
-- @property on_press
-- @param function
-- @tparam function on_press
--- The callback when this button is released.
--
-- @property on_release
-- @param function
-- @tparam function on_release
--- Execute this mousebinding.
-- @method :trigger

24
lib/awful/client.lua
View File

@ -157,7 +157,7 @@ client.focus = require("awful.client.focus")
--
-- @deprecated awful.client.jumpto
-- @see client.jump_to
-- @tparam client c the client to jump to
-- @tparam client c The client to jump to
-- @tparam bool|function merge If true then merge tags (select the client's
-- first tag additionally) when the client is not visible.
-- If it is a function, it will be called with the client and its first
@ -1153,7 +1153,7 @@ end
-- @DOC_screen_wfact4_EXAMPLE@
--
-- @legacylayout awful.client.idx
-- @tparam client c the client
-- @tparam client c The client
-- @treturn table data A table with "col", "idx" and "num" keys.
-- @treturn integer data.col The column number.
-- @treturn integer data.idx Index of the client in the column.
@ -1224,8 +1224,8 @@ end
-- @DOC_screen_wfact3_EXAMPLE@
--
-- @legacylayout awful.client.setwfact
-- @tparam number wfact the window factor value
-- @tparam client c the client
-- @tparam number wfact The window factor value
-- @tparam client c The client
-- @emits property::windowfact Emitted on the c.first_tag object.
-- @see tag.master_width_factor
function client.setwfact(wfact, c)
@ -1291,7 +1291,7 @@ end
-- @tparam number add Amount to increase/decrease the client's window factor by.
-- Should be between `-current_window_factor` and something close to
-- infinite. Normalisation then ensures that the sum of all factors is 1.
-- @tparam[opt=client.focus] client c the client.
-- @tparam[opt=client.focus] client c The client.
-- @emits property::windowfact
function client.incwfact(add, c)
c = c or capi.client.focus
@ -1462,10 +1462,10 @@ end
-- Starting from the client in focus or the given index, all clients that match
-- a given criteria.
--
-- @tparam function filter a function that returns true to indicate a positive match.
-- @tparam integer start what index to start iterating from. Defaults to using the
-- @tparam function filter A function that returns true to indicate a positive match.
-- @tparam integer start What index to start iterating from. Defaults to using the
-- index of the currently focused client.
-- @tparam[opt=nil] screen s which screen to use. nil means all screens.
-- @tparam[opt=nil] screen s Which screen to use. nil means all screens.
--
-- @staticfct awful.client.iterate
-- @usage -- un-minimize all urxvt instances
@ -1487,8 +1487,8 @@ end
-- If multiple clients match the given condition then the next one is
-- focused.
--
-- @tparam string cmd the command to execute
-- @tparam function matcher a function that returns true to indicate a matching client
-- @tparam string cmd The command to execute
-- @tparam function matcher A function that returns true to indicate a matching client
-- @tparam bool|function merge If true then merge tags (select the client's
-- first tag additionally) when the client is not visible.
-- If it is a function, it will be called with the client as argument.
@ -1611,7 +1611,7 @@ end, true, true, "keybinding")
-- @DOC_awful_client_shape1_EXAMPLE@
--
-- @property shape
-- @tparam gears.shape A gears.shape compatible function.
-- @tparam gears.shape shape A gears.shape compatible function.
-- @propemits true false
-- @see gears.shape
function client.object.set_shape(self, shape)
@ -1811,6 +1811,7 @@ end)
--- Emitted when a client need to get a titlebar.
-- @signal request::titlebars
-- @tparam client c The client.
-- @tparam[opt=nil] string content The context (like "rules")
-- @tparam[opt=nil] table hints Some hints.
-- @classsignal
@ -1834,6 +1835,7 @@ end)
-- * **floating**: When the floating or maximization state changes.
--
-- @signal request::border
-- @tparam client c The client.
-- @tparam string context The context.
-- @tparam table hints The hints.
-- @classsignal

16
lib/awful/completion.lua
View File

@ -1,5 +1,5 @@
---------------------------------------------------------------------------
--- Completion module.
--- Helper utilities for bash-like completion lists.
--
-- This module store a set of function using shell to complete commands name.
--
@ -31,7 +31,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.
-- @tparam string 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
@ -189,11 +189,13 @@ end
--- Run a generic completion.
-- For this function to run properly the awful.completion.keyword table should
-- be fed up with all keywords. The completion is run against these keywords.
-- @param text The current text the user had typed yet.
-- @param cur_pos The current cursor position.
-- @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.
-- @tparam string text The current text the user had typed yet.
-- @tparam number cur_pos The current cursor position.
-- @tparam number ncomp The number of yet requested completion using current text.
-- @tparam table keywords The keywords table uised for completion.
-- @treturn string The new match.
-- @treturn number The new cursor position.
-- @treturn table 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

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

@ -10,7 +10,7 @@ local hotkeys_popup = {
widget = require("awful.hotkeys_popup.widget"),
}
--- This is the same as awful.hotkeys_popup.widget.show_help.
--- This is the same as `awful.hotkeys_popup.widget.show_help`.
--
-- example usage:
--

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

@ -249,6 +249,21 @@ widget.labels = {
-- @tparam[opt] table args.group_rules Rules for showing 3rd-party hotkeys. @see `awful.hotkeys_popup.keys.vim`.
-- @return Widget instance.
-- @constructorfct awful.widget.hotkeys_popup.widget.new
-- @usebeautiful beautiful.hotkeys_fg
-- @usebeautiful beautiful.hotkeys_bg
-- @usebeautiful beautiful.hotkeys_border_width
-- @usebeautiful beautiful.hotkeys_border_color
-- @usebeautiful beautiful.hotkeys_shape
-- @usebeautiful beautiful.hotkeys_modifiers_fg
-- @usebeautiful beautiful.hotkeys_label_bg
-- @usebeautiful beautiful.hotkeys_label_fg
-- @usebeautiful beautiful.hotkeys_font
-- @usebeautiful beautiful.hotkeys_description_font
-- @usebeautiful beautiful.hotkeys_group_margin
-- @usebeautiful beautiful.bg_normal Fallback.
-- @usebeautiful beautiful.fg_normal Fallback.
-- @usebeautiful beautiful.fg_minimize Fallback.
-- @usebeautiful beautiful.border_width Fallback.
function widget.new(args)
args = args or {}
local widget_instance = {
@ -755,8 +770,8 @@ function widget.new(args)
end
--- Add hotkey group rules for third-party applications.
-- @tparam string group hotkeys group name,
-- @tparam table data rule data for the group
-- @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)
@ -795,8 +810,8 @@ end
--- Add hotkey group rules for third-party applications
-- (default widget instance will be used).
-- @tparam string group rule group name,
-- @tparam table data rule data for the group
-- @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)

12
lib/awful/key.lua
View File

@ -43,7 +43,7 @@ local gobject = require("gears.object")
-- keycode such as `#65`.
--
-- @property key
-- @param string
-- @tparam string key
--- The table of modifier keys.
--
@ -75,31 +75,31 @@ local gobject = require("gears.object")
-- This is used, for example, by `awful.hotkeys_popup`.
--
-- @property description
-- @param string
-- @tparam string description
--- The key name.
--
-- This can be useful when searching for keybindings by keywords.
--
-- @property name
-- @param string
-- @tparam string name
--- The key group bound to a function in a key binding.
--
-- This is used, for example, by `awful.hotkeys_popup`.
--
-- @property group
-- @param string
-- @tparam string group
--- The callback when this key is pressed.
--
-- @property on_press
-- @param function
-- @tparam function on_press
--- The callback when this key is released.
--
-- @property on_release
-- @param function
-- @tparam function on_release
local key = { mt = {}, hotkeys = {} }

18
lib/awful/keygrabber.lua
View File

@ -296,7 +296,7 @@ end
-- @DOC_text_awful_keygrabber_timeout_EXAMPLE@
--
-- @property timeout
-- @param number
-- @tparam number timeout
-- @see gears.timer
-- @see timeout_callback
@ -321,7 +321,7 @@ end
-- their corresponding key names such as `Control_L`.
--
-- @property stop_key
-- @param[opt=nil] string|table stop_key
-- @tparam[opt=nil] string|table stop_key
-- @see stop_event
--- The event on which the keygrabbing will be terminated.
@ -332,7 +332,7 @@ end
-- * "release"
--
-- @property stop_event
-- @param string
-- @tparam string stop_event
-- @see stop_key
--- Whether or not to execute the key press/release callbacks when keybindings are called.
@ -344,14 +344,14 @@ end
-- By default, keybindings block those callbacks from being executed.
--
-- @property mask_event_callback
-- @param[opt=true] boolean
-- @tparam[opt=true] boolean mask_event_callback
-- @see keybindings
-- @see keyreleased_callback
-- @see keypressed_callback
--- Do not call the callbacks on modifier keys (like `Control` or `Mod4`) events.
-- @property mask_modkeys
-- @param[opt=false] boolean
-- @tparam[opt=false] boolean mask_modkeys
-- @see mask_event_callback
--- Export all keygrabber keybindings as root (global) keybindings.
@ -365,7 +365,7 @@ end
-- have a single instance.
--
-- @property export_keybindings
-- @param[opt=false] boolean
-- @tparam[opt=false] boolean export_keybindings
--- The root (global) keybinding to start this keygrabber.
--
@ -376,7 +376,7 @@ end
-- @DOC_text_awful_keygrabber_root_keybindings_EXAMPLE@
--
-- @property root_keybindings
-- @param table
-- @tparam table root_keybindings
-- @see export_keybindings
-- @see keybindings
@ -385,7 +385,7 @@ end
-- This property contains a table of `awful.key` objects.
--
-- @property keybindings
-- @param table
-- @tparam table keybindings
-- @see export_keybindings
-- @see root_keybindings
-- @see awful.key
@ -415,7 +415,7 @@ end
-- @DOC_text_awful_keygrabber_autostart_EXAMPLE@
--
-- @property sequence
-- @param string
-- @tparam string sequence
--
--- The current (running) instance of this keygrabber.

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

@ -1,5 +1,29 @@
---------------------------------------------------------------------------
--- Layout module for awful.
--- Deterministically lay the clients in a screen workarea.
--
-- The `awful.layout` module contains many sub-modules. Each of them contain
-- one or more layout. `awful.layout` offers static layouts rather than
-- tree based like other WMs. The layout have a small number of configuration
-- variables:
--
-- * `master_width_factor`: The ratio between the main (master) section of the
-- layout and a sub-section. For example, in the `tile.left` layout, the main
-- (master) part contains `master_count` clients and the secondary part contains
-- all other clients.
-- * `master_count`: The number of clients which belong to the main (master) area.
-- * `column_count`: The number of columns to store the clients in the secondary
-- area.
-- * `master_fill_policy`: When the number of clients is below `master_count`,
-- how is the remaining space used.
-- * `gaps`: The empty space between the clients.
-- * `gap_single_client`: Same as gap, but when there is a single client. Gaps
-- are often useful as a visual cue to know where a client starts and ends.
-- This makes no sense when there is only one.
--
-- Not all layouts make use of all variables. Having such an overloaded meaning
-- to a small set of variable is useful to attach those values to keybindings
-- without having special logic for each layouts. AwesomeWM keybindings are not
-- modal, so such "limitation" actually improves usability.
--
-- @author Julien Danjou &lt;julien@danjou.info&gt;
-- @copyright 2008 Julien Danjou

4
lib/awful/layout/suit/corner.lua
View File

@ -171,6 +171,7 @@ end
-- Display master client in a corner of the screen, and slaves in one
-- column and one row around the master.
-- @clientlayout awful.layout.suit.corner.nw
-- @usebeautiful beautiful.layout_cornernw
corner.nw = {
name = "cornernw",
arrange = function (p) return do_corner(p, "NW") end,
@ -181,6 +182,7 @@ corner.nw = {
-- Display master client in a corner of the screen, and slaves in one
-- column and one row around the master.
-- @clientlayout awful.layout.suit.corner.ne
-- @usebeautiful beautiful.layout_cornerne
corner.ne = {
name = "cornerne",
arrange = function (p) return do_corner(p, "NE") end,
@ -191,6 +193,7 @@ corner.ne = {
-- Display master client in a corner of the screen, and slaves in one
-- column and one row around the master.
-- @clientlayout awful.layout.suit.corner.sw
-- @usebeautiful beautiful.layout_cornersw
corner.sw = {
name = "cornersw",
arrange = function (p) return do_corner(p, "SW") end,
@ -201,6 +204,7 @@ corner.sw = {
-- Display master client in a corner of the screen, and slaves in one
-- column and one row around the master.
-- @clientlayout awful.layout.suit.corner.se
-- @usebeautiful beautiful.layout_cornerse
corner.se = {
name = "cornerse",
arrange = function (p) return do_corner(p, "SE") end,

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

@ -107,10 +107,12 @@ end
--- The fair layout.
-- Try to give all clients the same size.
-- @clientlayout awful.layout.suit.fair
-- @usebeautiful beautiful.layout_fairv
--- The horizontal fair layout.
-- Try to give all clients the same size.
-- @clientlayout awful.layout.suit.fair.horizontal
-- @usebeautiful beautiful.layout_fairh
return fair

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

@ -114,6 +114,7 @@ end
--- The floating layout.
-- @clientlayout awful.layout.suit.floating
-- @usebeautiful beautiful.layout_floating
floating.name = "floating"

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

@ -143,6 +143,7 @@ end
--- The magnifier layout.
-- @clientlayout awful.layout.suit.magnifier
-- @usebeautiful beautiful.layout_magnifier
magnifier.name = "magnifier"

2
lib/awful/layout/suit/max.lua
View File

@ -43,6 +43,7 @@ end
--- Maximized layout.
-- @clientlayout awful.layout.suit.max
-- @usebeautiful beautiful.layout_max
max.name = "max"
function max.arrange(p)
return fmax(p, false)
@ -53,6 +54,7 @@ end
--- Fullscreen layout.
-- @clientlayout awful.layout.suit.max.fullscreen
-- @usebeautiful beautiful.layout_fullscreen
max.fullscreen = {}
max.fullscreen.name = "fullscreen"
max.fullscreen.skip_gap = max.skip_gap

2
lib/awful/layout/suit/spiral.lua
View File

@ -71,6 +71,7 @@ end
--- Dwindle layout.
-- @clientlayout awful.layout.suit.spiral.dwindle
-- @usebeautiful beautiful.layout_dwindle
spiral.dwindle = {}
spiral.dwindle.name = "dwindle"
function spiral.dwindle.arrange(p)
@ -79,6 +80,7 @@ end
--- Spiral layout.
-- @clientlayout awful.layout.suit.spiral.name
-- @usebeautiful beautiful.layout_spiral
spiral.name = "spiral"
function spiral.arrange(p)
return do_spiral(p, true)

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

@ -312,6 +312,7 @@ end
--- The main tile algo, on the right.
-- @param screen The screen number to tile.
-- @clientlayout awful.layout.suit.tile.right
-- @usebeautiful beautiful.layout_tile
tile.right = {}
tile.right.name = "tile"
tile.right.arrange = do_tile
@ -323,6 +324,7 @@ end
--- The main tile algo, on the left.
-- @param screen The screen number to tile.
-- @clientlayout awful.layout.suit.tile.left
-- @usebeautiful beautiful.layout_tileleft
tile.left = {}
tile.left.name = "tileleft"
tile.left.skip_gap = tile.skip_gap
@ -336,6 +338,7 @@ end
--- The main tile algo, on the bottom.
-- @param screen The screen number to tile.
-- @clientlayout awful.layout.suit.tile.bottom
-- @usebeautiful beautiful.layout_tilebottom
tile.bottom = {}
tile.bottom.name = "tilebottom"
tile.bottom.skip_gap = tile.skip_gap
@ -349,6 +352,7 @@ end
--- The main tile algo, on the top.
-- @param screen The screen number to tile.
-- @clientlayout awful.layout.suit.tile.top
-- @usebeautiful beautiful.layout_tiletop
tile.top = {}
tile.top.name = "tiletop"
tile.top.skip_gap = tile.skip_gap

52
lib/awful/menu.lua
View File

@ -1,5 +1,5 @@
--------------------------------------------------------------------------------
--- A menu for awful.
--- Create context menus, optionally with sub-menus.
--
-- @author Damien Leone &lt;damien.leone@gmail.com&gt;
-- @author Julien Danjou &lt;julien@danjou.info&gt;
@ -93,7 +93,7 @@ end
-- @param color
-- @see gears.color
--- The default sub-menu indicator if no menu_submenu_icon is provided.
--- The default sub-menu indicator if no `menu_submenu_icon` is provided.
-- @beautiful beautiful.menu_submenu
-- @tparam[opt="▶"] string menu_submenu The sub-menu text.
-- @see beautiful.menu_submenu_icon
@ -357,8 +357,9 @@ end
--- Show a menu.
-- @param args The arguments
-- @param args.coords Menu position defaulting to mouse.coords()
-- @tparam[opt={}] table args The arguments
-- @tparam[opt=mouse.coords] table args.coords The menu position. A table with
-- `x` and `y` as keys and position (in pixels) as values.
-- @method show
function menu:show(args)
args = args or {}
@ -390,8 +391,9 @@ function menu:hide()
end
--- Toggle menu visibility.
-- @param args The arguments
-- @param args.coords Menu position {x,y}
-- @tparam table args The arguments.
-- @tparam[opt=mouse.coords] table args.coords The menu position. A table with
-- `x` and `y` as keys and position (in pixels) as values.
-- @method toggle
function menu:toggle(args)
if self.wibox.visible then
@ -419,10 +421,10 @@ end
--- Add a new menu entry.
-- args.* params needed for the menu entry constructor.
-- @param args The item params
-- @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.
-- @tparam table args The item params.
-- @tparam[opt=awful.menu.entry] function args.new The menu entry constructor.
-- @tparam[opt] table args.theme The menu entry theme.
-- @tparam[opt] number index The index where the new entry will inserted.
-- @method add
function menu:add(args, index)
if not args then return end
@ -479,7 +481,7 @@ function menu:add(args, index)
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.
-- @tparam table|number num The index 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
@ -580,8 +582,8 @@ end
--- 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
-- @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 {}
@ -673,14 +675,24 @@ end
--------------------------------------------------------------------------------
--- Create a menu popup.
-- @param args Table containing the menu information.
--
-- * Key items: Table containing the displayed items. Each element is a table by default (when element 'new' is
-- awful.menu.entry) containing: item name, triggered action (submenu table or function), item icon (optional).
-- * Keys theme.[fg|bg]_[focus|normal], theme.border_color, theme.border_width, theme.submenu_icon, theme.height
-- and theme.width override the default display for your menu and/or of your menu entry, each of them are optional.
-- * Key auto_expand controls the submenu auto expand behaviour by setting it to true (default) or false.
--
-- @tparam table args Table containing the menu information.
-- @tparam[opt=true] boolean args.auto_expand Controls the submenu auto expand behaviour.
-- @tparam table args.items Table containing the displayed items. Each element is a
-- table by default (when element 'new' is awful.menu.entry) containing: item
-- name, triggered action (submenu table or function), item icon (optional).
-- @tparam table args.theme
-- @tparam[opt=beautiful.menu_fg_normal] color args.theme.fg_normal
-- @tparam[opt=beautiful.menu_bg_normal] color args.theme.bg_normal
-- @tparam[opt=beautiful.menu_fg_focus] color args.theme.fg_focus
-- @tparam[opt=beautiful.menu_bg_focus] color args.theme.bg_focus
-- @tparam[opt=beautiful.menu_border_color] color args.theme.border
-- @tparam[opt=beautiful.menu_border_width] integer args.theme.border_width
-- @tparam[opt=beautiful.menu_height] integer args.theme.height
-- @tparam[opt=beautiful.menu_width] integer args.theme.width
-- @tparam[opt=beautiful.menu_font] string args.theme.font
-- @tparam[opt=beautiful.menu_submenu_icon] gears.surface|string args.theme.submenu_icon
-- @tparam[opt=beautiful.menu_submenu] string args.theme.submenu
-- @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

4
lib/awful/mouse/client.lua
View File

@ -69,8 +69,8 @@ end
--- Get a client corner coordinates.
-- @deprecated awful.mouse.client.corner
-- @tparam[opt=client.focus] client c The client to get corner from, focused one by default.
-- @tparam string corner The corner to use: auto, top_left, top_right, bottom_left,
-- bottom_right, left, right, top bottom. Default is auto, and auto find the
-- @tparam string corner The corner to use: `auto`, `top_left`, `top_right`, `bottom_left`,
-- `bottom_right`, `left`, `right`, `top` or `bottom`. Default is `auto`. `auto` finds the
-- nearest corner.
-- @treturn string The corner name
-- @treturn number x The horizontal position

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

@ -116,7 +116,7 @@ end, "mouse.resize")
--- Get the client currently under the mouse cursor.
-- @property current_client
-- @tparam client|nil The client
-- @tparam client|nil current_client The client
function mouse.object.get_current_client()
local obj = capi.mouse.object_under_pointer()
@ -127,7 +127,7 @@ end
--- Get the wibox currently under the mouse cursor.
-- @property current_wibox
-- @tparam wibox|nil The wibox
-- @tparam wibox|nil current_wibox The wibox
function mouse.object.get_current_wibox()
local obj = capi.mouse.object_under_pointer()
@ -139,7 +139,7 @@ end
--- Get the widgets currently under the mouse cursor.
--
-- @property current_widgets
-- @tparam nil|table list The widget list
-- @tparam nil|table current_widgets The widget list
-- @treturn table The list of widgets.The first element is the biggest
-- container while the last is the topmost widget. The table contains *x*, *y*,
-- *width*, *height* and *widget*.
@ -164,7 +164,7 @@ end
--- Get the topmost widget currently under the mouse cursor.
-- @property current_widget
-- @tparam widget|nil widget The widget
-- @tparam widget|nil current_widget The widget
-- @treturn ?widget The widget
-- @see current_widget_geometry
@ -178,7 +178,7 @@ end
--- Get the current widget geometry.
-- @property current_widget_geometry
-- @tparam ?table The geometry.
-- @tparam ?table current_widget_geometry The geometry.
-- @see current_widget
function mouse.object.get_current_widget_geometry()
@ -189,7 +189,7 @@ end
--- Get the current widget geometries.
-- @property current_widget_geometries
-- @tparam ?table A list of geometry tables.
-- @tparam ?table current_widget_geometries A list of geometry tables.
-- @see current_widgets
function mouse.object.get_current_widget_geometries()
@ -238,7 +238,7 @@ end
--- True if the middle mouse button is pressed.
-- @property is_middle_mouse_button_pressed
-- @tparam boolean is_right_mouse_button_pressed
-- @tparam boolean is_middle_mouse_button_pressed
--- Add an `awful.button` based mousebinding to the global set.
--

10
lib/awful/mouse/resize.lua
View File

@ -52,7 +52,7 @@ end
-- This callback will be executed before the mouse grabbing starts.
-- @function awful.mouse.resize.add_enter_callback
-- @tparam function cb The callback (or nil)
-- @tparam[default=other] string context The callback context
-- @tparam[opt="other"] string context The callback context
function module.add_enter_callback(cb, context)
context = context or "other"
callbacks.enter[context] = callbacks.enter[context] or {}
@ -64,7 +64,7 @@ end
-- applying the operation.
-- @function awful.mouse.resize.add_move_callback
-- @tparam function cb The callback (or nil)
-- @tparam[default=other] string context The callback context
-- @tparam[opt="other"] string context The callback context
function module.add_move_callback(cb, context)
context = context or "other"
callbacks.move[context] = callbacks.move[context] or {}
@ -75,7 +75,7 @@ end
-- This callback is executed just before the `mousegrabber` stop
-- @function awful.mouse.resize.add_leave_callback
-- @tparam function cb The callback (or nil)
-- @tparam[default=other] string context The callback context
-- @tparam[opt="other"] string context The callback context
function module.add_leave_callback(cb, context)
context = context or "other"
callbacks.leave[context] = callbacks.leave[context] or {}
@ -93,9 +93,11 @@ end
--
-- @function awful.mouse.resize
-- @tparam client client A client.
-- @tparam[default=mouse.resize] string context The resizing context.
-- @tparam[opt=mouse.resize] string context The resizing context.
-- @tparam[opt={}] table args A set of `awful.placement` arguments.
-- @request wibox geometry mouse.resize granted Requests to resize the wibox.
-- @usebeautiful beautiful.cursor_mouse_move
-- @usebeautiful beautiful.cursor_mouse_resize
local function handler(_, client, context, args) --luacheck: no unused_args
args = args or {}
context = context or "mouse.resize"

4
lib/awful/mouse/snap.lua
View File

@ -200,6 +200,10 @@ end
-- @tparam boolean fixed_x True if the client isn't allowed to move in the x direction.
-- @tparam boolean fixed_y True if the client isn't allowed to move in the y direction.
-- @treturn table The new geometry.
-- @usebeautiful beautiful.snap_bg
-- @usebeautiful beautiful.snap_border_width
-- @usebeautiful beautiful.snap_shape
-- @usebeautiful beautiful.snapper_gap
function module.snap(c, snap, x, y, fixed_x, fixed_y)
snap = snap or module.default_distance
c = c or capi.client.focus

29
lib/awful/permissions/init.lua
View File

@ -1,5 +1,19 @@
---------------------------------------------------------------------------
--- Implements EWMH requests handling.
--- Default implementation of the various requests handers.
--
-- AwesomeWM has many `request::` signals across the core APIs. They help
-- decouple the default behavior from the core API. The request handlers
-- can be disconnected and replaced by module or `rc.lua` to alter
-- AwesomeWM behavior.
--
-- This module provides the default implementation of those request handlers.
-- Beside some legacy signals, most request handlers have a main object, a
-- named context and a table containing any low-level hints the core code is
-- aware of. Each default handler implement a context based filter mechanism.
-- This filter is called the "permissions". It allows requests to be denied.
-- For example, if a tiled client asks to be resized or moved, the permission
-- and deny it. In the documentation, many objects and properties have a
-- "permissions" section you can display by clicking "show more".
--
-- @author Julien Danjou &lt;julien@danjou.info&gt;
-- @copyright 2009 Julien Danjou
@ -143,12 +157,13 @@ end
-- @tparam client c A client to use
-- @tparam string context The context where this signal was used.
-- @tparam[opt] table hints A table with additional hints:
-- @tparam[opt=false] boolean hints.raise should the client be unminimized
-- @tparam[opt=false] boolean hints.raise Should the client be unminimized
-- and raised?
-- @tparam[opt=false] boolean hints.switch_to_tag should the client's first tag
-- @tparam[opt=false] boolean hints.switch_to_tag Should the client's first tag
-- be selected if none of the client's tags are selected?
-- @tparam[opt=false] boolean hints.switch_to_tags Select all tags associated
-- with the client.
-- @sourcesignal client request::activate
function permissions.activate(c, context, hints) -- luacheck: no unused args
if not pcommon.check(c, "client", "activate", context) then return end
@ -291,6 +306,7 @@ end
-- @tparam[opt] tag|boolean t A tag to use. If `true`, then the client is made `sticky`.
-- @tparam[opt={}] table hints Extra information.
-- @tparam[opt=nil] nil|string hints.reason Why the tag is being changed.
-- @sourcesignal client request::tag
function permissions.tag(c, t, hints) --luacheck: no unused
-- There is nothing to do
if not t and #get_valid_tags(c, c.screen) > 0 then return end
@ -317,6 +333,7 @@ end
-- @signalhandler awful.permissions.urgent
-- @tparam client c A client
-- @tparam boolean urgent If the client should be urgent
-- @sourcesignal client request::urgent
function permissions.urgent(c, urgent)
if c ~= client.focus and not aclient.property.get(c,"ignore_urgent") then
c.urgent = urgent
@ -343,6 +360,7 @@ local context_mapper = {
-- previous geometry in case it has to be restored.
-- @tparam[opt=true] boolean hints.honor_workarea Avoid overlapping the `wibar`s
-- or other desktop decoration when applying the geometry.
-- @sourcesignal client request::geometry
function permissions.geometry(c, context, hints)
if not pcommon.check(c, "client", "geometry", context) then return end
@ -416,6 +434,7 @@ end
-- @tparam[opt] integer hints.y The vertical position.
-- @tparam[opt] integer hints.width The wibox width.
-- @tparam[opt] integer hints.height The wibox height.
-- @sourcesignal client request::geometry
function permissions.wibox_geometry(w, context, hints)
if not pcommon.check(w, "wibox", "geometry", context) then return end
@ -435,6 +454,7 @@ end
-- @tparam[opt={}] table hints The hints to pass to the handler.
-- @tparam[opt=false] boolean hints.toggle Toggle the maximization state rather
-- than set it to `true`.
-- @sourcesignal client request::geometry
function permissions.merge_maximization(c, context, hints)
if not pcommon.check(c, "client", "geometry", context) then return end
@ -522,6 +542,7 @@ end
-- @tparam[opt] integer hints.y The vertical position.
-- @tparam[opt] integer hints.width The client width.
-- @tparam[opt] integer hints.height The client height.
-- @sourcesignal client request::geometry
function permissions.client_geometry_requests(c, context, hints)
if not pcommon.check(c, "client", "geometry", context) then return end
@ -563,6 +584,7 @@ end, "mouse_enter")
-- @signalhandler awful.permissions.update_border
-- @tparam client c The client.
-- @tparam string context Why is the border changed.
-- @sourcesignal client request::border
-- @usebeautiful beautiful.border_color_marked
-- @usebeautiful beautiful.border_color_active
-- @usebeautiful beautiful.border_color_normal
@ -751,6 +773,7 @@ local activate_context_map = {
-- @tparam client c The client.
-- @tparam string context Why is the client auto-activated.
-- @tparam[opt={}] table hints Extra arguments.
-- @sourcesignal client request::activated
-- @see activate
-- @see client:activate
function permissions.autoactivate(c, context, args)

18
lib/awful/prompt.lua
View File

@ -1,5 +1,5 @@
---------------------------------------------------------------------------
--- Prompt module for awful.
--- Convert a `wibox.widget.textbox` into an input prompt.
--
-- **Keyboard navigation**:
--
@ -444,21 +444,21 @@ end
-- return command
-- end}
-- }
-- @param textbox The textbox to use for the prompt. [**DEPRECATED**]
-- @param exe_callback The callback function to call with command as argument
-- @tparam wibox.widget.textbox textbox The textbox to use for the prompt. [**DEPRECATED**]
-- @tparam[opt] function|nil exe_callback The callback function to call with command as argument
-- when finished. [**DEPRECATED**]
-- @param completion_callback The callback function to call to get completion.
-- @tparam[opt] function completion_callback The callback function to call to get completion.
-- [**DEPRECATED**]
-- @param[opt] history_path File path where the history should be
-- @tparam[opt] string history_path File path where the history should be
-- saved, set nil to disable history [**DEPRECATED**]
-- @param[opt] history_max Set the maximum entries in history
-- @tparam[opt] number history_max Set the maximum entries in history
-- file, 50 by default [**DEPRECATED**]
-- @param[opt] done_callback The callback function to always call
-- @tparam[opt] function done_callback The callback function to always call
-- without arguments, regardless of whether the prompt was cancelled.
-- [**DEPRECATED**]
-- @param[opt] changed_callback The callback function to call
-- @tparam[opt] function changed_callback The callback function to call
-- with command as argument when a command was changed. [**DEPRECATED**]
-- @param[opt] keypressed_callback The callback function to call
-- @tparam[opt] function keypressed_callback The callback function to call
-- with mod table, key and command as arguments when a key was pressed.
-- [**DEPRECATED**]
-- @see gears.color

10
lib/awful/screen.lua
View File

@ -380,7 +380,7 @@ end
--
-- This method computes the different variants of the "usable" screen geometry.
--
-- @staticfct screen.get_bounding_geometry
-- @method 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.
@ -772,7 +772,7 @@ end
-- the lowest of the resulting virtual DPIs.
--
-- @property preferred_dpi
-- @tparam number preferred_dpi the DPI value.
-- @tparam number preferred_dpi The DPI value.
-- @readonly
--- The maximum diagonal size in millimeters.
@ -953,6 +953,8 @@ end
-- `request::remove` and `request::resize`.
--
-- @signalhandler awful.screen.create_screen_handler
-- @tparam table viewport
-- @sourcesignal screen request::create
-- @see request::create
--- Default handler for `request::remove`.
@ -972,6 +974,8 @@ end
-- end
--
-- @signalhandler awful.screen.remove_screen_handler
-- @tparam table viewport
-- @sourcesignal screen request::remove
-- @see request::remove
--- Default handler for `request::resize`.
@ -993,6 +997,8 @@ end
-- end
--
-- @signalhandler awful.screen.resize_screen_handler
-- @tparam table viewport
-- @sourcesignal screen request::resize
-- @see request::resize
-- Add the DPI properties.

2
lib/awful/spawn.lua
View File

@ -1,7 +1,7 @@
--luacheck: no max line length
---------------------------------------------------------------------------
--- Spawning of programs.
--- Spawn sub-processes and optionally get their output.
--
-- This module provides methods to start programs and supports startup
-- notifications, which allows for callbacks and applying properties to the

30
lib/awful/tag.lua
View File

@ -637,7 +637,7 @@ end
-- @deprecated awful.tag.setscreen
-- @see screen
-- @tparam screen s Screen
-- @tparam tag t tag object
-- @tparam tag t The tag object
function tag.setscreen(s, t)
-- For API consistency, the arguments have been swapped for Awesome 3.6
-- this method is already deprecated, so be silent and swap the args
@ -653,7 +653,7 @@ end
--- Get a tag's screen
-- @deprecated awful.tag.getscreen
-- @see screen
-- @tparam[opt] tag|nil t tag object
-- @tparam[opt=awful.screen.focused().selected_taga] tag|nil t Tag object
-- @treturn screen The tag screen.
function tag.getscreen(t)
gdebug.deprecate("Use t.screen instead of awful.tag.getscreen(t)", {deprecated_in=4})
@ -713,7 +713,7 @@ end
-- @DOC_screen_mwfact2_EXAMPLE@
--
-- @property master_width_factor
-- @tparam number master_width_factor Between 0 and 1
-- @tparam[opt=beautiful.master_width_factor] number master_width_factor Between 0 and 1
-- @emits property::mwfact When the value changes (deprecated).
-- @emits property::master_width_factor When the value changes.
-- @see master_count
@ -1006,7 +1006,7 @@ end
--- Set layout.
-- @deprecated awful.tag.setlayout
-- @see layout
-- @param layout a layout table or a constructor function
-- @param layout A layout table or a constructor function
-- @tparam tag t The tag to modify
-- @return The layout
function tag.setlayout(layout, t)
@ -1096,7 +1096,7 @@ end
-- @DOC_screen_gaps2_EXAMPLE@
--
-- @property gap
-- @tparam number gap The value has to be greater than zero.
-- @tparam[opt=beautiful.useless_gap] number gap The value has to be greater than zero.
-- @emits property::useless_gap When the gap changes.
-- @see gap_single_client
-- @see awful.tag.incgap
@ -1158,7 +1158,7 @@ end
-- @DOC_screen_gap_single_client_false_EXAMPLE@
--
-- @property gap_single_client
-- @tparam boolean gap_single_client Enable gaps for a single client
-- @tparam[opt=beautiful.gap_single_client] boolean gap_single_client Enable gaps for a single client
-- @propemits false false
-- @see awful.tag.incgap
@ -1230,7 +1230,7 @@ end
-- redistributed on both side.
--
-- @property master_fill_policy
-- @tparam string master_fill_policy "expand" or "master\_width\_factor"
-- @tparam[opt=beautiful.master_fill_policy] string master_fill_policy "expand" or "master\_width\_factor"
-- @propemits false false
-- @see awful.tag.togglemfpol
@ -1245,7 +1245,7 @@ end
-- @see master_fill_policy
-- @tparam string policy Can be set to
-- "expand" (fill all the available workarea) or
-- "master_width_factor" (fill only an area inside the master width factor)
-- `master_width_factor` (fill only an area inside the master width factor)
-- @tparam[opt=tag.selected()] tag t The tag to modify
function tag.setmfpol(policy, t)
gdebug.deprecate("Use t.master_fill_policy = policy instead of awful.tag.setmfpol", {deprecated_in=4})
@ -1296,7 +1296,7 @@ end
-- @DOC_sequences_tag_master_count_EXAMPLE@
--
-- @property master_count
-- @tparam integer master_count nmaster Only positive values are accepted
-- @tparam[opt=beautiful.master_count] integer master_count Only positive values are accepted
-- @emits property::nmaster Deprecated.
-- @emits property::master_count When the value changes.
-- @see awful.tag.incnmaster
@ -1317,7 +1317,7 @@ end
--- The number of master clients.
-- @deprecated awful.tag.setnmaster
-- @see master_count
-- @tparam nmaster The number of master windows.
-- @tparam number nmaster The number of master windows.
-- @tparam[opt] tag t The tag.
function tag.setnmaster(nmaster, t)
gdebug.deprecate("Use t.master_count = nmaster instead of awful.tag.setnmaster", {deprecated_in=4})
@ -1379,9 +1379,9 @@ end
--- Set the tag icon
-- @deprecated awful.tag.seticon
-- @tparam gears.surface|string icon The icon to set, either path or image object
-- @tparam tag tag The tag
-- @see icon
-- @tparam gears.surface|string icon the icon to set, either path or image object
-- @tparam tag tag the tag
function tag.seticon(icon, _tag)
gdebug.deprecate("Use t.icon = icon instead of awful.tag.seticon", {deprecated_in=4})
@ -1392,7 +1392,7 @@ end
--- Get the tag icon
-- @deprecated awful.tag.geticon
-- @see icon
-- @tparam tag tag the tag
-- @tparam tag tag The tag
function tag.geticon(_tag)
gdebug.deprecate("Use t.icon instead of awful.tag.geticon", {deprecated_in=4})
@ -1411,7 +1411,7 @@ end
-- @DOC_sequences_tag_column_count_EXAMPLE@
--
-- @property column_count
-- @tparam integer ncol Has to be greater than 1
-- @tparam[opt=beautiful.column_count or 1] integer column_count Has to be greater than 1
-- @emits property::ncol Deprecated.
-- @emits property::column_count When the value changes.
-- @see awful.tag.incncol
@ -1739,7 +1739,7 @@ end
-- @staticfct awful.tag.attached_connect_signal
-- @tparam screen|nil screen The screen concerned, or all if `nil`.
-- @tparam string signal The signal name.
-- @tparam function Callback
-- @tparam function callback
function tag.attached_connect_signal(screen, ...)
if screen then
attached_connect_signal_screen(screen, ...)

341
lib/awful/titlebar.lua
View File

@ -1,5 +1,5 @@
---------------------------------------------------------------------------
--- Titlebars for awful.
--- Create widget area on the edge of a client.
--
-- Create a titlebar
-- =================
@ -41,417 +41,499 @@ local titlebar = {
--- Show tooltips when hover on titlebar buttons.
--
-- @tfield[opt=true] boolean awful.titlebar.enable_tooltip
-- @param boolean
--- Title to display if client name is not set.
--
-- @field[opt='\<unknown\>'] awful.titlebar.fallback_name
-- @tparam[opt='\<unknown\>'] string fallback_name
--- The titlebar foreground (text) color.
--
-- @beautiful beautiful.titlebar_fg_normal
-- @param color
-- @see gears.color
--- The titlebar background color.
--
-- @beautiful beautiful.titlebar_bg_normal
-- @param color
-- @see gears.color
--- The titlebar background image image.
--
-- @beautiful beautiful.titlebar_bgimage_normal
-- @tparam gears.surface|string path
-- @see gears.surface
--- The titlebar foreground (text) color.
--
-- @beautiful beautiful.titlebar_fg
-- @param color
-- @see gears.color
--- The titlebar background color.
--
-- @beautiful beautiful.titlebar_bg
-- @param color
-- @see gears.color
--- The titlebar background image image.
--
-- @beautiful beautiful.titlebar_bgimage
-- @tparam gears.surface|string path
-- @see gears.surface
--- The focused titlebar foreground (text) color.
--
-- @beautiful beautiful.titlebar_fg_focus
-- @param color
-- @see gears.color
--- The focused titlebar background color.
--
-- @beautiful beautiful.titlebar_bg_focus
-- @param color
-- @see gears.color
--- The focused titlebar background image image.
--
-- @beautiful beautiful.titlebar_bgimage_focus
-- @tparam gears.surface|string path
-- @see gears.surface
--- The urgent titlebar foreground (text) color.
--
-- @beautiful beautiful.titlebar_fg_urgent
-- @param color
-- @see gears.color
--- The urgent titlebar background color.
--
-- @beautiful beautiful.titlebar_bg_urgent
-- @param color
-- @see gears.color
--- The urgent titlebar background image image.
--- The urgent titlebar background image.
--
-- @beautiful beautiful.titlebar_bgimage_urgent
-- @tparam gears.surface|string path
-- @see gears.surface
--- floating_button_normal.
--- The normal non-floating button image.
--
-- @beautiful beautiful.titlebar_floating_button_normal
-- @tparam gears.surface|string path
-- @see gears.surface
--- maximized_button_normal.
--- The normal non-maximized button image.
--
-- @beautiful beautiful.titlebar_maximized_button_normal
-- @tparam gears.surface|string path
-- @see gears.surface
--- minimize_button_normal.
--- The normal minimize button image.
--
-- @beautiful beautiful.titlebar_minimize_button_normal
-- @tparam gears.surface|string path
-- @see gears.surface
--- minimize_button_normal_hover.
--- The hovered minimize button image.
--
-- @beautiful beautiful.titlebar_minimize_button_normal_hover
-- @tparam gears.surface|string path
-- @see gears.surface
--- minimize_button_normal_press.
--- The pressed minimize button image.
--
-- @beautiful beautiful.titlebar_minimize_button_normal_press
-- @tparam gears.surface|string path
-- @see gears.surface
--- close_button_normal.
--- The normal close button image.
--
-- @beautiful beautiful.titlebar_close_button_normal
-- @tparam gears.surface|string path
-- @see gears.surface
--- close_button_normal_hover.
--- The hovered close button image.
--
-- @beautiful beautiful.titlebar_close_button_normal_hover
-- @tparam gears.surface|string path
-- @see gears.surface
--- close_button_normal_press.
--- The pressed close button image.
--
-- @beautiful beautiful.titlebar_close_button_normal_press
-- @tparam gears.surface|string path
-- @see gears.surface
--- ontop_button_normal.
--- The normal non-ontop button image.
--
-- @beautiful beautiful.titlebar_ontop_button_normal
-- @tparam gears.surface|string path
-- @see gears.surface
--- sticky_button_normal.
--- The normal non-sticky button image.
--
-- @beautiful beautiful.titlebar_sticky_button_normal
-- @tparam gears.surface|string path
-- @see gears.surface
--- floating_button_focus.
--- The focused client non-floating button image.
--
-- @beautiful beautiful.titlebar_floating_button_focus
-- @tparam gears.surface|string path
-- @see gears.surface
--- maximized_button_focus.
--- The focused client non-maximized button image.
--
-- @beautiful beautiful.titlebar_maximized_button_focus
-- @tparam gears.surface|string path
-- @see gears.surface
--- minimize_button_focus.
--- The focused client minimize button image.
--
-- @beautiful beautiful.titlebar_minimize_button_focus
-- @tparam gears.surface|string path
-- @see gears.surface
--- minimize_button_focus_hover.
--- The hovered+focused client minimize button image.
--
-- @beautiful beautiful.titlebar_minimize_button_focus_hover
-- @tparam gears.surface|string path
-- @see gears.surface
--- minimize_button_focus_press.
--- The pressed+focused minimize button image.
--
-- @beautiful beautiful.titlebar_minimize_button_focus_press
-- @tparam gears.surface|string path
-- @see gears.surface
--- close_button_focus.
--- The focused client close button image.
--
-- @beautiful beautiful.titlebar_close_button_focus
-- @tparam gears.surface|string path
-- @see gears.surface
--- close_button_focus_hover.
--- The hovered+focused close button image.
--
-- @beautiful beautiful.titlebar_close_button_focus_hover
-- @tparam gears.surface|string path
-- @see gears.surface
--- close_button_focus_press.
--- The pressed+focused close button image.
--
-- @beautiful beautiful.titlebar_close_button_focus_press
-- @tparam gears.surface|string path
-- @see gears.surface
--- ontop_button_focus.
--- The focused client non-ontop button image.
--
-- @beautiful beautiful.titlebar_ontop_button_focus
-- @tparam gears.surface|string path
-- @see gears.surface
--- sticky_button_focus.
--- The focused client sticky button image.
--
-- @beautiful beautiful.titlebar_sticky_button_focus
-- @tparam gears.surface|string path
-- @see gears.surface
--- floating_button_normal_active.
--- The normal floating button image.
--
-- @beautiful beautiful.titlebar_floating_button_normal_active
-- @tparam gears.surface|string path
-- @see gears.surface
--- floating_button_normal_active_hover.
--- The hovered floating client button image.
--
-- @beautiful beautiful.titlebar_floating_button_normal_active_hover
-- @tparam gears.surface|string path
-- @see gears.surface
--- floating_button_normal_active_press.
--- The pressed floating client button image.
--
-- @beautiful beautiful.titlebar_floating_button_normal_active_press
-- @tparam gears.surface|string path
-- @see gears.surface
--- maximized_button_normal_active.
--- The maximized client button image.
--
-- @beautiful beautiful.titlebar_maximized_button_normal_active
-- @tparam gears.surface|string path
-- @see gears.surface
--- maximized_button_normal_active_hover.
--- The hozered+maximized client button image.
--
-- @beautiful beautiful.titlebar_maximized_button_normal_active_hover
-- @tparam gears.surface|string path
-- @see gears.surface
--- maximized_button_normal_active_press.
--- The pressed+maximized button image.
--
-- @beautiful beautiful.titlebar_maximized_button_normal_active_press
-- @tparam gears.surface|string path
-- @see gears.surface
--- ontop_button_normal_active.
--- The ontop button image.
--
-- @beautiful beautiful.titlebar_ontop_button_normal_active
-- @tparam gears.surface|string path
-- @see gears.surface
--- ontop_button_normal_active_hover.
--- The hovered+ontop client button image.
--
-- @beautiful beautiful.titlebar_ontop_button_normal_active_hover
-- @tparam gears.surface|string path
-- @see gears.surface
--- ontop_button_normal_active_press.
--- The pressed+ontop client button image.
--
-- @beautiful beautiful.titlebar_ontop_button_normal_active_press
-- @tparam gears.surface|string path
-- @see gears.surface
--- sticky_button_normal_active.
--- The sticky button image.
--
-- @beautiful beautiful.titlebar_sticky_button_normal_active
-- @tparam gears.surface|string path
-- @see gears.surface
--- sticky_button_normal_active_hover.
--- The hovered+sticky button image.
--
-- @beautiful beautiful.titlebar_sticky_button_normal_active_hover
-- @tparam gears.surface|string path
-- @see gears.surface
--- sticky_button_normal_active_press.
--- The pressed+sticky client button image.
--
-- @beautiful beautiful.titlebar_sticky_button_normal_active_press
-- @tparam gears.surface|string path
-- @see gears.surface
--- floating_button_focus_active.
--- The floating+focused client button image.
--
-- @beautiful beautiful.titlebar_floating_button_focus_active
-- @tparam gears.surface|string path
-- @see gears.surface
--- floating_button_focus_active_hover.
--- The hovered+floating+focused button image.
--
-- @beautiful beautiful.titlebar_floating_button_focus_active_hover
-- @tparam gears.surface|string path
-- @see gears.surface
--- floating_button_focus_active_press.
--- The pressed+floating+focused button image.
--
-- @beautiful beautiful.titlebar_floating_button_focus_active_press
-- @tparam gears.surface|string path
-- @see gears.surface
--- maximized_button_focus_active.
--- The maximized+focused button image.
--
-- @beautiful beautiful.titlebar_maximized_button_focus_active
-- @tparam gears.surface|string path
-- @see gears.surface
--- maximized_button_focus_active_hover.
--- The hovered+maximized+focused button image.
--
-- @beautiful beautiful.titlebar_maximized_button_focus_active_hover
-- @tparam gears.surface|string path
-- @see gears.surface
--- maximized_button_focus_active_press.
--- The pressed+maximized+focused button image.
--
-- @beautiful beautiful.titlebar_maximized_button_focus_active_press
-- @tparam gears.surface|string path
-- @see gears.surface
--- ontop_button_focus_active.
--- The ontop+focused button image.
--
-- @beautiful beautiful.titlebar_ontop_button_focus_active
-- @tparam gears.surface|string path
-- @see gears.surface
--- ontop_button_focus_active_hover.
--- The hovered+ontop+focused button image.
--
-- @beautiful beautiful.titlebar_ontop_button_focus_active_hover
-- @tparam gears.surface|string path
-- @see gears.surface
--- ontop_button_focus_active_press.
--- The pressed+ontop+focused button image.
--
-- @beautiful beautiful.titlebar_ontop_button_focus_active_press
-- @tparam gears.surface|string path
-- @see gears.surface
--- sticky_button_focus_active.
--- The sticky+focused button image.
--
-- @beautiful beautiful.titlebar_sticky_button_focus_active
-- @tparam gears.surface|string path
-- @see gears.surface
--- sticky_button_focus_active_hover.
--- The hovered+sticky+focused button image.
--
-- @beautiful beautiful.titlebar_sticky_button_focus_active_hover
-- @tparam gears.surface|string path
-- @see gears.surface
--- sticky_button_focus_active_press.
--- The pressed+sticky+focused button image.
--
-- @beautiful beautiful.titlebar_sticky_button_focus_active_press
-- @tparam gears.surface|string path
-- @see gears.surface
--- floating_button_normal_inactive.
--- The inactive+floating button image.
--
-- @beautiful beautiful.titlebar_floating_button_normal_inactive
-- @tparam gears.surface|string path
-- @see gears.surface
--- floating_button_normal_inactive_hover.
--- The hovered+inactive+floating button image.
--
-- @beautiful beautiful.titlebar_floating_button_normal_inactive_hover
-- @tparam gears.surface|string path
-- @see gears.surface
--- floating_button_normal_inactive_press.
--- The pressed+inactive+floating button image.
--
-- @beautiful beautiful.titlebar_floating_button_normal_inactive_press
-- @tparam gears.surface|string path
-- @see gears.surface
--- maximized_button_normal_inactive.
--- The inactive+maximized button image.
--
-- @beautiful beautiful.titlebar_maximized_button_normal_inactive
-- @tparam gears.surface|string path
-- @see gears.surface
--- maximized_button_normal_inactive_hover.
--- The hovered+inactive+maximized button image.
--
-- @beautiful beautiful.titlebar_maximized_button_normal_inactive_hover
-- @tparam gears.surface|string path
-- @see gears.surface
--- maximized_button_normal_inactive_press.
--- The pressed+maximized+inactive button image.
--
-- @beautiful beautiful.titlebar_maximized_button_normal_inactive_press
-- @tparam gears.surface|string path
-- @see gears.surface
--- ontop_button_normal_inactive.
--- The inactive+ontop button image.
--
-- @beautiful beautiful.titlebar_ontop_button_normal_inactive
-- @tparam gears.surface|string path
-- @see gears.surface
--- ontop_button_normal_inactive_hover.
--- The hovered+inactive+ontop button image.
--
-- @beautiful beautiful.titlebar_ontop_button_normal_inactive_hover
-- @tparam gears.surface|string path
-- @see gears.surface
--- ontop_button_normal_inactive_press.
--- The pressed+inactive+ontop button image.
--
-- @beautiful beautiful.titlebar_ontop_button_normal_inactive_press
-- @tparam gears.surface|string path
-- @see gears.surface
--- sticky_button_normal_inactive.
--- The inactive+sticky button image.
--
-- @beautiful beautiful.titlebar_sticky_button_normal_inactive
-- @tparam gears.surface|string path
-- @see gears.surface
--- sticky_button_normal_inactive_hover.
--- The hovered+inactive+sticky button image.
--
-- @beautiful beautiful.titlebar_sticky_button_normal_inactive_hover
-- @tparam gears.surface|string path
-- @see gears.surface
--- sticky_button_normal_inactive_press.
--- The pressed+inactive+sticky button image.
--
-- @beautiful beautiful.titlebar_sticky_button_normal_inactive_press
-- @tparam gears.surface|string path
-- @see gears.surface
--- floating_button_focus_inactive.
--- The inactive+focused+floating button image.
--
-- @beautiful beautiful.titlebar_floating_button_focus_inactive
-- @tparam gears.surface|string path
-- @see gears.surface
--- floating_button_focus_inactive_hover.
--- The hovered+inactive+focused+floating button image.
--
-- @beautiful beautiful.titlebar_floating_button_focus_inactive_hover
-- @tparam gears.surface|string path
-- @see gears.surface
--- floating_button_focus_inactive_press.
--- The pressed+inactive+focused+floating button image.
--
-- @beautiful beautiful.titlebar_floating_button_focus_inactive_press
-- @tparam gears.surface|string path
-- @see gears.surface
--- maximized_button_focus_inactive.
--- The inactive+focused+maximized button image.
--
-- @beautiful beautiful.titlebar_maximized_button_focus_inactive
-- @tparam gears.surface|string path
-- @see gears.surface
--- maximized_button_focus_inactive_hover.
--- The hovered+inactive+focused+maximized button image.
--
-- @beautiful beautiful.titlebar_maximized_button_focus_inactive_hover
-- @tparam gears.surface|string path
-- @see gears.surface
--- maximized_button_focus_inactive_press.
--- The pressed+inactive+focused+maximized button image.
--
-- @beautiful beautiful.titlebar_maximized_button_focus_inactive_press
-- @tparam gears.surface|string path
-- @see gears.surface
--- ontop_button_focus_inactive.
--- The inactive+focused+ontop button image.
--
-- @beautiful beautiful.titlebar_ontop_button_focus_inactive
-- @tparam gears.surface|string path
-- @see gears.surface
--- ontop_button_focus_inactive_hover.
--- The hovered+inactive+focused+ontop button image.
--
-- @beautiful beautiful.titlebar_ontop_button_focus_inactive_hover
-- @tparam gears.surface|string path
-- @see gears.surface
--- ontop_button_focus_inactive_press.
--- The pressed+inactive+focused+ontop button image.
--
-- @beautiful beautiful.titlebar_ontop_button_focus_inactive_press
-- @tparam gears.surface|string path
-- @see gears.surface
--- sticky_button_focus_inactive.
--- The inactive+focused+sticky button image.
--
-- @beautiful beautiful.titlebar_sticky_button_focus_inactive
-- @tparam gears.surface|string path
-- @see gears.surface
--- sticky_button_focus_inactive_hover.
--- The hovered+inactive+focused+sticky button image.
--
-- @beautiful beautiful.titlebar_sticky_button_focus_inactive_hover
-- @tparam gears.surface|string path
-- @see gears.surface
--- sticky_button_focus_inactive_press.
--- The pressed+inactive+focused+sticky button image.
--
-- @beautiful beautiful.titlebar_sticky_button_focus_inactive_press
-- @tparam gears.surface|string path
-- @see gears.surface
--- 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
-- @tparam table args An array containing the widgets disposition
-- @method setup
@ -554,6 +636,18 @@ end
-- @tparam[opt] string args.font
-- @constructorfct awful.titlebar
-- @treturn wibox.drawable The newly created titlebar object.
-- @usebeautiful beautiful.titlebar_fg_normal
-- @usebeautiful beautiful.titlebar_bg_normal
-- @usebeautiful beautiful.titlebar_bgimage_normal
-- @usebeautiful beautiful.titlebar_fg
-- @usebeautiful beautiful.titlebar_bg
-- @usebeautiful beautiful.titlebar_bgimage
-- @usebeautiful beautiful.titlebar_fg_focus
-- @usebeautiful beautiful.titlebar_bg_focus
-- @usebeautiful beautiful.titlebar_bgimage_focus
-- @usebeautiful beautiful.titlebar_fg_urgent
-- @usebeautiful beautiful.titlebar_bg_urgent
-- @usebeautiful beautiful.titlebar_bgimage_urgent
local function new(c, args)
args = args or {}
local position = args.position or "top"
@ -616,7 +710,7 @@ local function new(c, args)
end
--- Show the client's titlebar.
-- @param c The client whose titlebar is modified
-- @tparam client c The client whose titlebar is modified
-- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`,
-- `"right"`, `"top"`, `"bottom"`.
-- @staticfct awful.titlebar.show
@ -632,7 +726,7 @@ function titlebar.show(c, position)
end
--- Hide the client's titlebar.
-- @param c The client whose titlebar is modified
-- @tparam client c The client whose titlebar is modified
-- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`,
-- `"right"`, `"top"`, `"bottom"`.
-- @staticfct awful.titlebar.hide
@ -642,7 +736,7 @@ function titlebar.hide(c, position)
end
--- Toggle the client's titlebar, hiding it if it is visible, otherwise showing it.
-- @param c The client whose titlebar is modified
-- @tparam client c The client whose titlebar is modified
-- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`,
-- `"right"`, `"top"`, `"bottom"`.
-- @staticfct awful.titlebar.toggle
@ -706,7 +800,7 @@ end
-- Please note that this returns a textbox and all of textbox' API is available.
-- This way, you can e.g. modify the font that is used.
--
-- @param c The client for which a titlewidget should be created.
-- @tparam client c The client for which a titlewidget should be created.
-- @return The title widget.
-- @constructorfct awful.titlebar.widget.titlewidget
function titlebar.widget.titlewidget(c)
@ -730,7 +824,7 @@ end
-- Please note that this returns an imagebox and all of the imagebox' API is
-- available. This way, you can e.g. disallow resizes.
--
-- @param c The client for which an icon widget should be created.
-- @tparam client c The client for which an icon widget should be created.
-- @return The icon widget.
-- @constructorfct awful.titlebar.widget.iconwidget
function titlebar.widget.iconwidget(c)
@ -747,12 +841,12 @@ end
-- then found in the theme as `titlebar_[name]_button_[normal/focus]_[state]`.
-- If that value does not exist, the focused state is ignored for the next try.
--
-- @param c The client for which a button is created.
-- @tparam client c The client for which a button is created.
-- @tparam string name Name of the button, used for accessing the theme and
-- in the tooltip.
-- @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
-- @tparam function selector A function that selects the image that should be displayed.
-- @tparam function action Function that is called when the button is clicked.
-- @treturn wibox.widget The widget
-- @constructorfct awful.titlebar.widget.button
function titlebar.widget.button(c, name, selector, action)
local ret = imagebox()
@ -840,8 +934,23 @@ function titlebar.widget.button(c, name, selector, action)
end
--- Create a new float button for a client.
-- @param c The client for which the button is wanted.
--
-- @constructorfct awful.titlebar.widget.floatingbutton
-- @tparam client c The client for which the button is wanted.
-- @usebeautiful beautiful.titlebar_floating_button_normal
-- @usebeautiful beautiful.titlebar_floating_button_focus
-- @usebeautiful beautiful.titlebar_floating_button_normal_active
-- @usebeautiful beautiful.titlebar_floating_button_normal_active_hover
-- @usebeautiful beautiful.titlebar_floating_button_normal_active_press
-- @usebeautiful beautiful.titlebar_floating_button_focus_active
-- @usebeautiful beautiful.titlebar_floating_button_focus_active_hover
-- @usebeautiful beautiful.titlebar_floating_button_focus_active_press
-- @usebeautiful beautiful.titlebar_floating_button_normal_inactive
-- @usebeautiful beautiful.titlebar_floating_button_normal_inactive_hover
-- @usebeautiful beautiful.titlebar_floating_button_normal_inactive_press
-- @usebeautiful beautiful.titlebar_floating_button_focus_inactive
-- @usebeautiful beautiful.titlebar_floating_button_focus_inactive_hover
-- @usebeautiful beautiful.titlebar_floating_button_focus_inactive_press
function titlebar.widget.floatingbutton(c)
local widget = titlebar.widget.button(c, "floating", aclient.object.get_floating, aclient.floating.toggle)
update_on_signal(c, "property::floating", widget)
@ -849,8 +958,23 @@ function titlebar.widget.floatingbutton(c)
end
--- Create a new maximize button for a client.
-- @param c The client for which the button is wanted.
--
-- @constructorfct awful.titlebar.widget.maximizedbutton
-- @tparam client c The client for which the button is wanted.
-- @usebeautiful beautiful.titlebar_maximized_button_focus_active
-- @usebeautiful beautiful.titlebar_maximized_button_focus_active_hover
-- @usebeautiful beautiful.titlebar_maximized_button_focus_active_press
-- @usebeautiful beautiful.titlebar_maximized_button_normal_inactive
-- @usebeautiful beautiful.titlebar_maximized_button_normal_inactive_hover
-- @usebeautiful beautiful.titlebar_maximized_button_normal_inactive_press
-- @usebeautiful beautiful.titlebar_maximized_button_focus_inactive
-- @usebeautiful beautiful.titlebar_maximized_button_focus_inactive_hover
-- @usebeautiful beautiful.titlebar_maximized_button_focus_inactive_press
-- @usebeautiful beautiful.titlebar_maximized_button_normal
-- @usebeautiful beautiful.titlebar_maximized_button_focus
-- @usebeautiful beautiful.titlebar_maximized_button_normal_active
-- @usebeautiful beautiful.titlebar_maximized_button_normal_active_hover
-- @usebeautiful beautiful.titlebar_maximized_button_normal_active_press
function titlebar.widget.maximizedbutton(c)
local widget = titlebar.widget.button(c, "maximized", function(cl)
return cl.maximized
@ -862,8 +986,15 @@ function titlebar.widget.maximizedbutton(c)
end
--- Create a new minimize button for a client.
-- @param c The client for which the button is wanted.
--
-- @constructorfct awful.titlebar.widget.minimizebutton
-- @tparam client c The client for which the button is wanted.
-- @usebeautiful beautiful.titlebar_minimize_button_normal
-- @usebeautiful beautiful.titlebar_minimize_button_normal_hover
-- @usebeautiful beautiful.titlebar_minimize_button_normal_press
-- @usebeautiful beautiful.titlebar_minimize_button_focus
-- @usebeautiful beautiful.titlebar_minimize_button_focus_hover
-- @usebeautiful beautiful.titlebar_minimize_button_focus_press
function titlebar.widget.minimizebutton(c)
local widget = titlebar.widget.button(c, "minimize",
function() return "" end,
@ -873,15 +1004,37 @@ function titlebar.widget.minimizebutton(c)
end
--- Create a new closing button for a client.
-- @param c The client for which the button is wanted.
--
-- @constructorfct awful.titlebar.widget.closebutton
-- @tparam client c The client for which the button is wanted.
-- @usebeautiful beautiful.titlebar_close_button_normal
-- @usebeautiful beautiful.titlebar_close_button_normal_hover
-- @usebeautiful beautiful.titlebar_close_button_normal_press
-- @usebeautiful beautiful.titlebar_close_button_focus
-- @usebeautiful beautiful.titlebar_close_button_focus_hover
-- @usebeautiful beautiful.titlebar_close_button_focus_press
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.
--
-- @constructorfct awful.titlebar.widget.ontopbutton
-- @tparam client c The client for which the button is wanted.
-- @usebeautiful beautiful.titlebar_ontop_button_normal
-- @usebeautiful beautiful.titlebar_ontop_button_focus
-- @usebeautiful beautiful.titlebar_ontop_button_normal_active
-- @usebeautiful beautiful.titlebar_ontop_button_normal_active_hover
-- @usebeautiful beautiful.titlebar_ontop_button_normal_active_press
-- @usebeautiful beautiful.titlebar_ontop_button_focus_active
-- @usebeautiful beautiful.titlebar_ontop_button_focus_active_hover
-- @usebeautiful beautiful.titlebar_ontop_button_focus_active_press
-- @usebeautiful beautiful.titlebar_ontop_button_normal_inactive
-- @usebeautiful beautiful.titlebar_ontop_button_normal_inactive_hover
-- @usebeautiful beautiful.titlebar_ontop_button_normal_inactive_press
-- @usebeautiful beautiful.titlebar_ontop_button_focus_inactive
-- @usebeautiful beautiful.titlebar_ontop_button_focus_inactive_hover
-- @usebeautiful beautiful.titlebar_ontop_button_focus_inactive_press
function titlebar.widget.ontopbutton(c)
local widget = titlebar.widget.button(c, "ontop",
function(cl) return cl.ontop end,
@ -891,8 +1044,22 @@ function titlebar.widget.ontopbutton(c)
end
--- Create a new sticky button for a client.
-- @param c The client for which the button is wanted.
-- @constructorfct awful.titlebar.widget.stickybutton
-- @tparam client c The client for which the button is wanted.
-- @usebeautiful beautiful.titlebar_sticky_button_normal
-- @usebeautiful beautiful.titlebar_sticky_button_focus
-- @usebeautiful beautiful.titlebar_sticky_button_normal_active
-- @usebeautiful beautiful.titlebar_sticky_button_normal_active_hover
-- @usebeautiful beautiful.titlebar_sticky_button_normal_active_press
-- @usebeautiful beautiful.titlebar_sticky_button_focus_active
-- @usebeautiful beautiful.titlebar_sticky_button_focus_active_hover
-- @usebeautiful beautiful.titlebar_sticky_button_focus_active_press
-- @usebeautiful beautiful.titlebar_sticky_button_normal_inactive
-- @usebeautiful beautiful.titlebar_sticky_button_normal_inactive_hover
-- @usebeautiful beautiful.titlebar_sticky_button_normal_inactive_press
-- @usebeautiful beautiful.titlebar_sticky_button_focus_inactive
-- @usebeautiful beautiful.titlebar_sticky_button_focus_inactive_hover
-- @usebeautiful beautiful.titlebar_sticky_button_focus_inactive_press
function titlebar.widget.stickybutton(c)
local widget = titlebar.widget.button(c, "sticky",
function(cl) return cl.sticky end,

44
lib/awful/tooltip.lua
View File

@ -107,7 +107,7 @@ local offset = {
--- The tooltip opacity.
-- @beautiful beautiful.tooltip_opacity
-- @param number opacity Between 0 and 1
-- @tparam number opacity Between 0 and 1
--- The tooltip margins.
-- @beautiful beautiful.tooltip_gaps
@ -206,7 +206,7 @@ end
--- The wibox containing the tooltip widgets.
-- @property wibox
-- @param wibox
-- @tparam wibox wibox
function tooltip:get_wibox()
if self._private.wibox then
@ -229,7 +229,7 @@ end
--- Is the tooltip visible?
-- @property visible
-- @param boolean
-- @tparam[opt=true] boolean visible
-- @propemits true false
function tooltip:get_visible()
@ -269,7 +269,7 @@ end
-- * top
--
-- @property align
-- @param string
-- @tparam string align
-- @see mode
-- @see preferred_positions
-- @propemits true false
@ -277,7 +277,7 @@ end
--- The default tooltip alignment.
-- @beautiful beautiful.tooltip_align
-- @param string
-- @tparam string tooltip_align
-- @see align
function tooltip:get_align()
@ -330,7 +330,7 @@ end
-- * "outside": Outside of the widget
--
-- @property mode
-- @param string
-- @tparam string mode
-- @propemits true false
function tooltip:set_mode(mode)
@ -410,7 +410,7 @@ end
-- {"front", "back", "middle"}
--
-- @property preferred_alignments
-- @param string
-- @tparam string preferred_alignments
-- @propemits true false
-- @see preferred_positions
@ -447,7 +447,7 @@ end
--- Change displayed markup.
--
-- @property markup
-- @tparam string text New tooltip markup, passed to
-- @tparam string markup New tooltip markup, passed to
-- `wibox.widget.textbox.set_markup`.
-- @propemits true false
-- @see wibox.widget.textbox
@ -479,7 +479,7 @@ end
-- @DOC_awful_tooltip_margins_EXAMPLE@
--
-- @property margins
-- @tparam number|table New margins value.
-- @tparam number|table margins New margins value.
-- @propemits true false
function tooltip:set_margins(val)
@ -492,7 +492,7 @@ end
-- @DOC_awful_tooltip_border_width_EXAMPLE@
--
-- @property border_width
-- @param number
-- @tparam[opt=0] number border_width
-- @propemits true false
-- @propbeautiful
@ -506,8 +506,10 @@ end
-- @DOC_awful_tooltip_border_color_EXAMPLE@
--
-- @property border_color
-- @param color
-- @tparam[opt=beautiful.tooltip_border_color or beautiful.border_color_normal or beautiful.fg_normal]
-- gears.color border_color
-- @propemits true false
-- @propbeautiful
function tooltip:set_border_color(val)
self.widget.border_color = val
@ -519,7 +521,7 @@ end
-- @DOC_awful_tooltip_margins_leftright_EXAMPLE@
--
-- @property margins_leftright
-- @tparam number New margins value.
-- @tparam number margins_leftright New margins value.
-- @propemits true false
function tooltip:set_margin_leftright(val)
@ -538,7 +540,7 @@ end
-- @DOC_awful_tooltip_margins_topbottom_EXAMPLE@
--
-- @property margins_topbottom
-- @tparam number New margins value.
-- @tparam number margins_topbottom New margins value.
-- @propemits true false
function tooltip:set_margin_topbottom(val)
@ -557,7 +559,7 @@ end
-- @DOC_awful_tooltip_gaps_EXAMPLE@
--
-- @property gaps
-- @tparam number|table New margins value.
-- @tparam number|table gaps New margins value.
-- @propemits true false
function tooltip:set_gaps(val)
@ -617,14 +619,14 @@ end
-- @tparam[opt=apply_dpi(5)] integer args.margin_leftright The left/right margin for the text.
-- @tparam[opt=apply_dpi(3)] integer args.margin_topbottom The top/bottom margin for the text.
-- @tparam[opt=nil] gears.shape args.shape The shape.
-- @tparam[opt] string args.bg The background color.
-- @tparam[opt] string args.fg The foreground color.
-- @tparam[opt] string args.border_color The tooltip border color.
-- @tparam[opt] number args.border_width The tooltip border width.
-- @tparam[opt=beautiful.tooltip_bg] string args.bg The background color.
-- @tparam[opt=beautiful.tooltip_fg] string args.fg The foreground color.
-- @tparam[opt=beautiful.tooltip_border_color] string args.border_color The tooltip border color.
-- @tparam[opt=beautiful.tooltip_border_width] number args.border_width The tooltip border width.
-- @tparam[opt] string args.align The horizontal alignment.
-- @tparam[opt] string args.font The tooltip font.
-- @tparam[opt] number args.opacity The tooltip opacity.
-- @tparam[opt] table|number args.gaps The tooltip margins.
-- @tparam[opt=beautiful.tooltip_font] string args.font The tooltip font.
-- @tparam[opt=beautiful.tooltip_opacity] number args.opacity The tooltip opacity.
-- @tparam[opt=beautiful.tooltip_gaps] table|number args.gaps The tooltip margins.
-- @treturn awful.tooltip The created tooltip.
-- @see add_to_object
-- @see timeout

51
lib/awful/util.lua
View File

@ -1,5 +1,8 @@
---------------------------------------------------------------------------
--- Utility module for awful.
--- Various small utility functions not worth putting into new modules.
--
-- Most functions in this module are eventually moved into new modules are
-- deprecated.
--
-- @author Julien Danjou &lt;julien@danjou.info&gt;
-- @copyright 2008 Julien Danjou
@ -19,11 +22,7 @@ local gstring = require("gears.string")
local grect = require("gears.geometry").rectangle
local gcolor = require("gears.color")
local gfs = require("gears.filesystem")
local capi =
{
awesome = awesome,
mouse = mouse
}
local capi = { awesome = awesome }
local gdebug = require("gears.debug")
local gmath = require("gears.math")
@ -38,6 +37,7 @@ util.shell = os.getenv("SHELL") or "/bin/sh"
-- This function implementation **has been removed** and no longer
-- do anything. Use `awful.spawn.easy_async`.
-- @deprecated awful.util.pread
-- @see awful.spawn.easy_async
--- Display a deprecation notice, but only once per traceback.
-- @deprecated deprecate
@ -99,6 +99,12 @@ function util.mkdir(dir)
end
--- Eval Lua code.
--
-- It can either be "real" code or expressions like `2 ~= 3`.
-- If the expression cannot be interpreted or returns false, this
-- function calls `error`.
--
-- @tparam string code The code to evaluate.
-- @return The return value of Lua code.
-- @staticfct awful.util.eval
function util.eval(s)
@ -128,7 +134,7 @@ end
--- Check if a file is a Lua valid file.
-- This is done by loading the content and compiling it with loadfile().
-- @param path The file path.
-- @tparam string path The file path.
-- @return A function if everything is alright, a string with the error
-- otherwise.
-- @staticfct awful.util.checkfile
@ -222,13 +228,16 @@ function util.getdir(d)
end
--- Search for an icon and return the full path.
--
-- It searches for the icon path under the given directories with respect to the
-- given extensions for the icon filename.
-- @param iconname The name of the icon to search for.
-- @param exts Table of image extensions allowed, otherwise { 'png', gif' }
-- @param dirs Table of dirs to search, otherwise { '/usr/share/pixmaps/' }
-- @tparam string iconname The name of the icon to search for.
-- @tparam[opt={'png','gif'}] table exts Table of image extensions allowed.
-- @tparam[opt={'/usr/share/pixmaps/','/usr/share/icons/hicolor/'}] table dirs
-- Table of dirs to search.
-- @tparam[opt] string size The size. If this is specified, subdirectories `x`
-- of the dirs are searched first.
-- @treturn string|nil The icon path or `nil` if not found.
-- @staticfct awful.util.geticonpath
function util.geticonpath(iconname, exts, dirs, size)
exts = exts or { 'png', 'gif' }
@ -326,8 +335,8 @@ end
--
-- Note that this method doesn't copy entries found in `__index`.
-- @deprecated util.table.crush
-- @tparam table t the table to be overridden
-- @tparam table set the table used to override members of `t`
-- @tparam table t The table to be overridden
-- @tparam table set The table used to override members of `t`
-- @tparam[opt=false] boolean raw Use rawset (avoid the metatable)
-- @treturn table t (for convenience)
-- @see gears.table
@ -387,7 +396,7 @@ end
--- Get a sorted table with all keys from a table.
-- @deprecated util.table.keys
-- @param t the table for which the keys to get
-- @param t The table for which the keys to get
-- @return A table with keys
-- @see gears.table
function util.table.keys(t)
@ -398,7 +407,7 @@ end
--- Filter a tables keys for certain content types
-- @deprecated util.table.keys_filter
-- @param t The table to retrieve the keys for
-- @param ... the types to look for
-- @param ... The types to look for
-- @return A filtered table with keys
-- @see gears.table
function util.table.keys_filter(t, ...)
@ -408,7 +417,7 @@ end
--- Reverse a table
-- @deprecated util.table.reverse
-- @param t the table to reverse
-- @param t The table to reverse
-- @return the reversed table
-- @see gears.table
function util.table.reverse(t)
@ -418,7 +427,7 @@ end
--- Clone a table
-- @deprecated util.table.clone
-- @param t the table to clone
-- @param t The table to clone
-- @param deep Create a deep clone? (default: true)
-- @return a clone of t
-- @see gears.table
@ -432,9 +441,9 @@ end
-- given index, all elements of a table that match a given criteria.
--
-- @deprecated util.table.iterate
-- @param t the table to iterate
-- @param filter a function that returns true to indicate a positive match
-- @param start what index to start iterating from. Default is 1 (=> start of
-- @tparam table t The table to iterate.
-- @tparam function filter A function that returns true to indicate a positive match
-- @param start What index to start iterating from. Default is 1 (=> start of
-- the table)
-- @see gears.table
function util.table.iterate(t, filter, start)
@ -445,8 +454,8 @@ end
--- Merge items from the one table to another one
-- @deprecated util.table.merge
-- @tparam table t the container table
-- @tparam table set the mixin table
-- @tparam table t The container table
-- @tparam table set The mixin table
-- @treturn table Return `t` for convenience
-- @see gears.table
function util.table.merge(t, set)

2
lib/awful/wallpaper.lua
View File

@ -470,6 +470,7 @@ end)
--
-- @property bg
-- @tparam gears.color bg
-- @usebeautiful beautiful.wallpaper_bg
-- @see gears.color
--- The foreground color.
@ -485,6 +486,7 @@ end)
--- The default wallpaper background color.
-- @beautiful beautiful.wallpaper_bg
-- @tparam gears.color wallpaper_bg
-- @usebeautiful beautiful.wallpaper_fg
-- @see bg
--- The default wallpaper foreground color.

13
lib/awful/wibar.lua
View File

@ -537,6 +537,19 @@ end
--@DOC_wibox_constructor_COMMON@
-- @return The new wibar
-- @constructorfct awful.wibar
-- @usebeautiful beautiful.wibar_favor_vertical
-- @usebeautiful beautiful.wibar_border_width
-- @usebeautiful beautiful.wibar_border_color
-- @usebeautiful beautiful.wibar_ontop
-- @usebeautiful beautiful.wibar_cursor
-- @usebeautiful beautiful.wibar_opacity
-- @usebeautiful beautiful.wibar_type
-- @usebeautiful beautiful.wibar_width
-- @usebeautiful beautiful.wibar_height
-- @usebeautiful beautiful.wibar_bg
-- @usebeautiful beautiful.wibar_bgimage
-- @usebeautiful beautiful.wibar_fg
-- @usebeautiful beautiful.wibar_shape
function awfulwibar.new(args)
args = args or {}
local position = args.position or "top"

2
lib/awful/widget/button.lua
View File

@ -1,5 +1,5 @@
---------------------------------------------------------------------------
-- A simple button widget.
-- A simple button widget based on a background image.
--
-- @DOC_wibox_awidget_defaults_button_EXAMPLE@
--

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

@ -1,5 +1,5 @@
---------------------------------------------------------------------------
-- A calendar popup wibox.
-- A popup wibox containing a `wibox.widget,calendar` widget.
--
-- Display a month or year calendar popup using `calendar_popup.month` or `calendar_popup.year`.
-- The calendar style can be tweaked by providing tables of style properties at creation:
@ -386,6 +386,7 @@ end
-- @tparam table args.style_focus Cell style for the current day cell (see `cell_properties`)
-- @treturn wibox A wibox containing the calendar
-- @constructorfct awful.widget.calendar_popup.month
-- @usebeautiful beautiful.calendar_style
function calendar_popup.month(args)
return get_cal_wibox("month", args)
end

2
lib/awful/widget/clienticon.lua
View File

@ -86,7 +86,7 @@ end
--- The widget's @{client}.
--
-- @property client
-- @param client
-- @tparam client client
-- @propemits true false
function clienticon:get_client()

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

@ -1,4 +1,10 @@
---------------------------------------------------------------------------
-- This module contains helper functions to manage a layout widgets.
--
-- This is the boilerplate code to manage a "list" of objects and display
-- them in a `wibox.layout`. It uses signals to detect when an object change
-- and its widget be updated.
--
-- @author Julien Danjou &lt;julien@danjou.info&gt;
-- @copyright 2008-2009 Julien Danjou
-- @classmod awful.widget.common

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

@ -1,4 +1,7 @@
---------------------------------------------------------------------------
-- Display the current keyboard layout name in a widget.
--
--
-- @author Aleksey Fedotov &lt;lexa@cfotr.com&gt;
-- @copyright 2015 Aleksey Fedotov
-- @widgetmod awful.widget.keyboardlayout
@ -132,7 +135,7 @@ end
-- Create an array whose element is a table consisting of the four fields:
-- vendor, file, section and group_idx, which all correspond to the
-- xkb_symbols pattern "vendor/file(section):group_idx".
-- @tparam string group_names The string awesome.xkb_get_group_names() returns.
-- @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)
@ -260,7 +263,7 @@ end
-- It shows current keyboard layout name in a textbox.
--
-- @constructorfct awful.widget.keyboardlayout
-- @return A keyboard layout widget.
-- @treturn awful.widget.keyboardlayout A keyboard layout widget.
function keyboardlayout.new()
local widget = textbox()
local self = widget_base.make_widget(widget, nil, {enable_properties=true})

53
lib/awful/widget/layoutlist.lua
View File

@ -178,33 +178,38 @@ end
local layoutlist = {}
--- The layoutlist default widget layout.
--
-- If no layout is specified, a `wibox.layout.fixed.vertical` will be created
-- automatically.
-- @property base_layout
-- @param widget
-- @tparam[opt=wibox.layout.fixed.vertical] wibox.layout base_layout
-- @propemits true false
-- @see wibox.layout.fixed.vertical
-- @see base_layout
--- The delegate widget template.
--
-- @property widget_template
-- @param table
-- @tparam[opt=nil] table widget_template
-- @propemits true false
--- The layoutlist screen.
--
-- @property screen
-- @param screen
-- @tparam screen screen
--- A function that returns the list of layout to display.
--
-- @property source
-- @param[opt=awful.widget.layoutlist.source.for_screen] function
-- @tparam[opt=awful.widget.layoutlist.source.for_screen] function source
--- The layoutlist filter function.
--
-- @property filter
-- @param[opt=awful.widget.layoutlist.source.for_screen] function
-- @tparam[opt=awful.widget.layoutlist.source.for_screen] function filter
--- The default foreground (text) color.
--
-- @beautiful beautiful.layoutlist_fg_normal
-- @tparam[opt=nil] string|pattern fg_normal
-- @see gears.color
@ -276,17 +281,17 @@ local layoutlist = {}
--- The currenly displayed layouts.
-- @property layouts
-- @param table
-- @tparam table layouts
--- The currently selected layout.
-- @property current_layout
-- @param layout
-- @tparam layout current_layout
--- The current number of layouts.
--
-- @property count
-- @readonly
-- @tparam number The number of layouts.
-- @tparam number count The number of layouts.
-- @propemits true false
function layoutlist:get_layouts()
@ -395,22 +400,22 @@ end
-- @tparam[opt] table args.widget_template A custom widget to be used for each action.
-- @tparam[opt=ascreen.focused()] screen args.screen A screen
-- @tparam[opt={}] table args.style Extra look and feel parameters
-- @tparam boolean args.style.disable_icon
-- @tparam boolean args.style.disable_name
-- @tparam string|pattern args.style.fg_normal
-- @tparam string|pattern args.style.bg_normal
-- @tparam string|pattern args.style.fg_selected
-- @tparam string|pattern args.style.bg_selected
-- @tparam string args.style.font
-- @tparam string args.style.font_selected
-- @tparam string args.style.align *left*, *right* or *center*
-- @tparam number args.style.spacing
-- @tparam gears.shape args.style.shape
-- @tparam number args.style.shape_border_width
-- @tparam string|pattern args.style.shape_border_color
-- @tparam gears.shape args.style.shape_selected
-- @tparam string|pattern args.style.shape_border_width_selected
-- @tparam string|pattern args.style.shape_border_color_selected
-- @tparam[opt=beautiful.layoutlist_disable_icon] boolean args.style.disable_icon
-- @tparam[opt=beautiful.layoutlist_disable_name] boolean args.style.disable_name
-- @tparam[opt=beautiful.layoutlist_fg_normal] string|pattern args.style.fg_normal
-- @tparam[opt=beautiful.layoutlist_bg_normal] string|pattern args.style.bg_normal
-- @tparam[opt=beautiful.layoutlist_fg_selected] string|pattern args.style.fg_selected
-- @tparam[opt=beautiful.layoutlist_bg_selected] string|pattern args.style.bg_selected
-- @tparam[opt=beautiful.layoutlist_font] string args.style.font
-- @tparam[opt=beautiful.layoutlist_font_selected] string args.style.font_selected
-- @tparam[opt=beautiful.layoutlist_align] string args.style.align *left*, *right* or *center*
-- @tparam[opt=beautiful.layoutlist_spacing] number args.style.spacing
-- @tparam[opt=beautiful.layoutlist_shape] gears.shape args.style.shape
-- @tparam[opt=beautiful.layoutlist_shape_border_width] number args.style.shape_border_width
-- @tparam[opt=beautiful.layoutlist_shape_border_color] string|pattern args.style.shape_border_color
-- @tparam[opt=beautiful.layoutlist_shape_selected] gears.shape args.style.shape_selected
-- @tparam[opt=beautiful.layoutlist_shape_border_width_selected] string|pattern args.style.shape_border_width_selected
-- @tparam[opt=beautiful.layoutlist_shape_border_color_selected] string|pattern args.style.shape_border_color_selected
-- @treturn widget The action widget.
-- @constructorfct awful.widget.layoutlist

2
lib/awful/widget/only_on_screen.lua
View File

@ -80,7 +80,7 @@ function only_on_screen:get_screen()
return self._private.screen
end
--- Returns a new only_on_screen container.
--- Returns a new `awful.widget.only_on_screen` container.
-- This widget makes some other widget visible on just some screens. Use
-- `:set_widget()` to set the widget and `:set_screen()` to set the screen.
-- @param[opt] widget The widget to display.

12
lib/awful/widget/prompt.lua
View File

@ -73,7 +73,7 @@ end
-- of `awful.spawn`. Depending on the amount of customization to your shell
-- environment, this can increase startup time.
-- @property with_shell
-- @param[opt=false] boolean
-- @tparam[opt=false] boolean with_shell
--- Create a prompt widget which will launch a command.
-- For additional documentation about `args` parameter, please refer to
@ -85,10 +85,10 @@ end
-- Prompt background color.
-- @tparam[opt=`beautiful.prompt_fg` or `beautiful.fg_normal`] color args.fg
-- Prompt foreground color.
-- @tparam[opt] gears.color args.fg_cursor
-- @tparam[opt] gears.color args.bg_cursor
-- @tparam[opt=beautiful.prompt_fg_cursor] gears.color args.fg_cursor
-- @tparam[opt=beautiful.prompt_bg_cursor] gears.color args.bg_cursor
-- @tparam[opt] gears.color args.ul_cursor
-- @tparam[opt] string args.font
-- @tparam[opt=beautiful.prompt_font] string args.font
-- @tparam[opt] boolean args.autoexec
-- @tparam[opt] function args.highlighter A function to add syntax highlighting
-- to the command.
@ -116,6 +116,10 @@ end
-- @return An instance of prompt widget, inherits from
-- `wibox.container.background`.
-- @constructorfct awful.widget.prompt
-- @usebeautiful beautiful.prompt_fg
-- @usebeautiful beautiful.prompt_bg
-- @usebeautiful beautiful.fg_normal When `beautiful.prompt_fg` isn't set.
-- @usebeautiful beautiful.bg_normal When `beautiful.prompt_bg` isn't set.
function widgetprompt.new(args)
args = args or {}
local promptbox = background()

71
lib/awful/widget/taglist.lua
View File

@ -431,7 +431,7 @@ end
--
-- @property count
-- @readonly
-- @tparam number The number of tags.
-- @tparam number count The number of tags.
-- @propemits true false
function taglist:set_base_layout(layout)
@ -482,7 +482,7 @@ end
-- API is very low level.
--
-- @property update_function
-- @tparam function update_function.
-- @tparam function update_function
--- A function to restrict the content of the taglist.
--
@ -542,34 +542,45 @@ end
-- function used to generate the list of tag.
-- @tparam[opt] table args.widget_template A custom widget to be used for each tag
-- @tparam[opt={}] table args.style The style overrides default theme.
-- @tparam[opt=nil] string|pattern args.style.fg_focus
-- @tparam[opt=nil] string|pattern args.style.bg_focus
-- @tparam[opt=nil] string|pattern args.style.fg_urgent
-- @tparam[opt=nil] string|pattern args.style.bg_urgent
-- @tparam[opt=nil] string|pattern args.style.bg_occupied
-- @tparam[opt=nil] string|pattern args.style.fg_occupied
-- @tparam[opt=nil] string|pattern args.style.bg_empty
-- @tparam[opt=nil] string|pattern args.style.fg_empty
-- @tparam[opt=nil] string|pattern args.style.bg_volatile
-- @tparam[opt=nil] string|pattern args.style.fg_volatile
-- @tparam[opt=nil] string args.style.squares_sel
-- @tparam[opt=nil] string args.style.squares_unsel
-- @tparam[opt=nil] string args.style.squares_sel_empty
-- @tparam[opt=nil] string args.style.squares_unsel_empty
-- @tparam[opt=nil] string args.style.squares_resize
-- @tparam[opt=nil] string args.style.disable_icon
-- @tparam[opt=nil] string args.style.font
-- @tparam[opt=nil] number args.style.spacing The spacing between tags.
-- @tparam[opt] string args.style.squares_sel A user provided image for selected squares.
-- @tparam[opt] string args.style.squares_unsel A user provided image for unselected squares.
-- @tparam[opt] string args.style.squares_sel_empty A user provided image for selected squares for empty tags.
-- @tparam[opt] string args.style.squares_unsel_empty A user provided image for unselected squares for empty tags.
-- @tparam[opt] boolean args.style.squares_resize True or false to resize squares.
-- @tparam string|pattern args.style.bg_focus The background color for focused client.
-- @tparam string|pattern args.style.fg_focus The foreground color for focused client.
-- @tparam string|pattern args.style.bg_urgent The background color for urgent clients.
-- @tparam string|pattern args.style.fg_urgent The foreground color for urgent clients.
-- @tparam string args.style.font The font.
-- @tparam[opt=beautiful.taglist_fg_focus] string|pattern args.style.fg_focus
-- @tparam[opt=beautiful.taglist_bg_focus] string|pattern args.style.bg_focus
-- @tparam[opt=beautiful.taglist_fg_urgent] string|pattern args.style.fg_urgent
-- @tparam[opt=beautiful.taglist_bg_urgent] string|pattern args.style.bg_urgent
-- @tparam[opt=beautiful.taglist_bg_occupied] string|pattern args.style.bg_occupied
-- @tparam[opt=beautiful.taglist_fg_occupied] string|pattern args.style.fg_occupied
-- @tparam[opt=beautiful.taglist_bg_empty] string|pattern args.style.bg_empty
-- @tparam[opt=beautiful.taglist_fg_empty] string|pattern args.style.fg_empty
-- @tparam[opt=beautiful.taglist_bg_volatile] string|pattern args.style.bg_volatile
-- @tparam[opt=beautiful.taglist_fg_volatile] string|pattern args.style.fg_volatile
-- @tparam[opt=beautiful.taglist_squares_sel] string args.style.squares_sel
-- @tparam[opt=beautiful.taglist_squares_unsel] string args.style.squares_unsel
-- @tparam[opt=beautiful.taglist_squares_sel_empty] string args.style.squares_sel_empty
-- @tparam[opt=beautiful.taglist_squares_unsel_empty] string args.style.squares_unsel_empty
-- @tparam[opt=beautiful.taglist_squares_resize] string args.style.squares_resize
-- @tparam[opt=beautiful.taglist_disable_icon] string args.style.disable_icon
-- @tparam[opt=beautiful.taglist_font] string args.style.font
-- @tparam[opt=beautiful.taglist_spacing] number args.style.spacing The spacing between tags.
-- @tparam[opt=beautiful.taglist_squares_sel] string args.style.squares_sel A user provided image for selected squares.
-- @tparam[opt=beautiful.taglist_squares_unsel] string args.style.squares_unsel A user provided image for unselected squares.
-- @tparam[opt=beautiful.taglist_squares_sel_empty] string args.style.squares_sel_empty A user provided image for selected squares for empty tags.
-- @tparam[opt=beautiful.taglist_squares_unsel_empty] string args.style.squares_unsel_empty A user provided image for unselected squares for empty tags.
-- @tparam[opt=beautiful.taglist_squares_resize] boolean args.style.squares_resize True or false to resize squares.
-- @tparam[opt=beautiful.taglist_font] string args.style.font The font.
-- @tparam[opt=beautiful.taglist_shape] gears.shape|function args.style.shape
-- @tparam[opt=beautiful.taglist_shape_border_width] number args.style.shape_border_width
-- @tparam[opt=beautiful.taglist_shape_border_color] string args.style.shape_border_color
-- @tparam[opt=beautiful.taglist_shape_empty] gears.shape|function args.style.shape_empty
-- @tparam[opt=beautiful.taglist_shape_border_width_empty] number args.style.shape_border_width_empty
-- @tparam[opt=beautiful.taglist_shape_border_color_empty] string args.style.border_color_empty
-- @tparam[opt=beautiful.taglist_shape_focus] gears.shape|function args.style.shape_focus
-- @tparam[opt=beautiful.taglist_shape_border_width_focus] number args.style.shape_border_width_focus
-- @tparam[opt=beautiful.taglist_shape_border_color_focus] string args.style.shape_border_color_focus
-- @tparam[opt=beautiful.taglist_shape_urgent] gears.shape|function args.style.shape_urgent
-- @tparam[opt=beautiful.taglist_shape_border_width_urgent] number args.style.shape_border_width_urgent
-- @tparam[opt=beautiful.taglist_shape_border_color_urgent] string args.style.shape_border_color_urgent
-- @tparam[opt=beautiful.taglist_shape_volatile] gears.shape|function args.style.shape_volatile
-- @tparam[opt=beautiful.taglist_shape_border_width_volatile] number args.style.shape_border_width_volatile
-- @tparam[opt=beautiful.taglist_shape_border_color_volatile] string args.style.shape_border_color_volatile
-- @param filter **DEPRECATED** use args.filter
-- @param buttons **DEPRECATED** use args.buttons
-- @param style **DEPRECATED** use args.style

89
lib/awful/widget/tasklist.lua
View File

@ -377,6 +377,10 @@ local instances
-- @tparam[opt=nil] string|color shape_border_color_urgent
-- @see gears.color
--- The icon size.
-- @beautiful beautiful.tasklist_icon_size
-- @tparam[opt=nil] integer tasklist_icon_size
-- Public structures
tasklist.filter, tasklist.source = {}, {}
@ -605,7 +609,7 @@ end
--
-- @property count
-- @readonly
-- @tparam number The number of client.
-- @tparam number count The number of client.
-- @propemits true false
--- Set the tasklist layout.
@ -799,53 +803,54 @@ end
-- function used to generate the list of client.
-- @tparam[opt] table args.widget_template A custom widget to be used for each client
-- @tparam[opt={}] table args.style The style overrides default theme.
-- @tparam[opt=nil] string|pattern args.style.fg_normal
-- @tparam[opt=nil] string|pattern args.style.bg_normal
-- @tparam[opt=nil] string|pattern args.style.fg_focus
-- @tparam[opt=nil] string|pattern args.style.bg_focus
-- @tparam[opt=nil] string|pattern args.style.fg_urgent
-- @tparam[opt=nil] string|pattern args.style.bg_urgent
-- @tparam[opt=nil] string|pattern args.style.fg_minimize
-- @tparam[opt=nil] string|pattern args.style.bg_minimize
-- @tparam[opt=nil] string args.style.bg_image_normal
-- @tparam[opt=nil] string args.style.bg_image_focus
-- @tparam[opt=nil] string args.style.bg_image_urgent
-- @tparam[opt=nil] string args.style.bg_image_minimize
-- @tparam[opt=nil] boolean args.style.disable_icon
-- @tparam[opt=nil] number args.style.icon_size The size of the icon
-- @tparam[opt='▪'] string args.style.sticky Extra icon when client is sticky
-- @tparam[opt='⌃'] string args.style.ontop Extra icon when client is ontop
-- @tparam[opt='▴'] string args.style.above Extra icon when client is above
-- @tparam[opt='▾'] string args.style.below Extra icon when client is below
-- @tparam[opt='✈'] string args.style.floating Extra icon when client is floating
-- @tparam[opt='<b>+</b>'] string args.style.maximized Extra icon when client is maximized
-- @tparam[opt='⬌'] string args.style.maximized_horizontal Extra icon when client is maximized_horizontal
-- @tparam[opt='⬍'] string args.style.maximized_vertical Extra icon when client is maximized_vertical
-- @tparam[opt=false] boolean args.style.disable_task_name
-- @tparam[opt=nil] string args.style.font
-- @tparam[opt="left"] string args.style.align *left*, *right* or *center*
-- @tparam[opt=nil] string args.style.font_focus
-- @tparam[opt=nil] string args.style.font_minimized
-- @tparam[opt=nil] string args.style.font_urgent
-- @tparam[opt=nil] number args.style.spacing The spacing between tags.
-- @tparam[opt=nil] gears.shape args.style.shape
-- @tparam[opt=nil] number args.style.shape_border_width
-- @tparam[opt=nil] string|color args.style.shape_border_color
-- @tparam[opt=nil] gears.shape args.style.shape_focus
-- @tparam[opt=nil] number args.style.shape_border_width_focus
-- @tparam[opt=nil] string|color args.style.shape_border_color_focus
-- @tparam[opt=nil] gears.shape args.style.shape_minimized
-- @tparam[opt=nil] number args.style.shape_border_width_minimized
-- @tparam[opt=nil] string|color args.style.shape_border_color_minimized
-- @tparam[opt=nil] gears.shape args.style.shape_urgent
-- @tparam[opt=nil] number args.style.shape_border_width_urgent
-- @tparam[opt=nil] string|color args.style.shape_border_color_urgent
-- @tparam[opt=beautiful.tasklist_fg_normal] string|pattern args.style.fg_normal
-- @tparam[opt=beautiful.tasklist_bg_normal] string|pattern args.style.bg_normal
-- @tparam[opt=beautiful.tasklist_fg_focus or beautiful.fg_focus] string|pattern args.style.fg_focus
-- @tparam[opt=beautiful.tasklist_bg_focus or beautiful.bg_focus] string|pattern args.style.bg_focus
-- @tparam[opt=beautiful.tasklist_fg_urgent or beautiful.fg_urgent] string|pattern args.style.fg_urgent
-- @tparam[opt=beautiful.tasklist_bg_urgent or beautiful.bg_urgent] string|pattern args.style.bg_urgent
-- @tparam[opt=beautiful.tasklist_fg_minimize or beautiful.fg_minimize] string|pattern args.style.fg_minimize
-- @tparam[opt=beautiful.tasklist_bg_minimize or beautiful.bg_minimize] string|pattern args.style.bg_minimize
-- @tparam[opt=beautiful.tasklist_bg_image_normal] string args.style.bg_image_normal
-- @tparam[opt=beautiful.tasklist_bg_image_focus] string args.style.bg_image_focus
-- @tparam[opt=beautiful.tasklist_bg_image_urgent] string args.style.bg_image_urgent
-- @tparam[opt=beautiful.tasklist_bg_image_minimize] string args.style.bg_image_minimize
-- @tparam[opt=beautiful.tasklist_disable_icon] boolean args.style.disable_icon
-- @tparam[opt=beautiful.tasklist_icon_size] number args.style.icon_size The size of the icon
-- @tparam[opt=beautiful.tasklist_sticky or '▪'] string args.style.sticky Extra icon when client is sticky
-- @tparam[opt=beautiful.tasklist_ontop or '⌃'] string args.style.ontop Extra icon when client is ontop
-- @tparam[opt=beautiful.tasklist_above or '▴'] string args.style.above Extra icon when client is above
-- @tparam[opt=beautiful.tasklist_below or '▾'] string args.style.below Extra icon when client is below
-- @tparam[opt=beautiful.tasklist_floating or '✈'] string args.style.floating Extra icon when client is floating
-- @tparam[opt=beautiful.tasklist_maximized or '<b>+</b>'] string args.style.maximized Extra icon when client is maximized
-- @tparam[opt=beautiful.tasklist_maximized_horizontal or '⬌'] string args.style.maximized_horizontal Extra icon when client is maximized_horizontal
-- @tparam[opt=beautiful.tasklist_maximized_vertical or '⬍'] string args.style.maximized_vertical Extra icon when client is maximized_vertical
-- @tparam[opt=beautiful.tasklist_disable_task_name or false] boolean args.style.disable_task_name
-- @tparam[opt=beautiful.tasklist_font] string args.style.font
-- @tparam[opt=beautiful.tasklist_align or "left"] string args.style.align *left*, *right* or *center*
-- @tparam[opt=beautiful.tasklist_font_focus] string args.style.font_focus
-- @tparam[opt=beautiful.tasklist_font_minimized] string args.style.font_minimized
-- @tparam[opt=beautiful.tasklist_font_urgent] string args.style.font_urgent
-- @tparam[opt=beautiful.tasklist_spacing] number args.style.spacing The spacing between tags.
-- @tparam[opt=beautiful.tasklist_shape] gears.shape args.style.shape
-- @tparam[opt=beautiful.tasklist_shape_border_width] number args.style.shape_border_width
-- @tparam[opt=beautiful.tasklist_shape_border_color] string|color args.style.shape_border_color
-- @tparam[opt=beautiful.tasklist_shape_focus] gears.shape args.style.shape_focus
-- @tparam[opt=beautiful.tasklist_shape_border_width_focus] number args.style.shape_border_width_focus
-- @tparam[opt=beautiful.tasklist_shape_border_color_focus] string|color args.style.shape_border_color_focus
-- @tparam[opt=beautiful.tasklist_shape_minimized] gears.shape args.style.shape_minimized
-- @tparam[opt=beautiful.tasklist_shape_border_width_minimized] number args.style.shape_border_width_minimized
-- @tparam[opt=beautiful.tasklist_shape_border_color_minimized] string|color args.style.shape_border_color_minimized
-- @tparam[opt=beautiful.tasklist_shape_urgent] gears.shape args.style.shape_urgent
-- @tparam[opt=beautiful.tasklist_shape_border_width_urgent] number args.style.shape_border_width_urgent
-- @tparam[opt=beautiful.tasklist_shape_border_color_urgent] string|color args.style.shape_border_color_urgent
-- @param filter **DEPRECATED** use args.filter
-- @param buttons **DEPRECATED** use args.buttons
-- @param style **DEPRECATED** use args.style
-- @param update_function **DEPRECATED** use args.update_function
-- @param base_widget **DEPRECATED** use args.base_layout
-- @constructorfct awful.widget.tasklist
-- @usebeautiful beautiful.tasklist_plain_task_name
function tasklist.new(args, filter, buttons, style, update_function, base_widget)
local screen = nil

33
lib/awful/widget/watch.lua
View File

@ -1,5 +1,6 @@
---------------------------------------------------------------------------
--- Watch widget.
--- Execute a command at a set interval and display its output.
--
-- Here is an example of simple temperature widget which will update each 15
-- seconds implemented in two different ways.
-- The first, simpler one, will just display the return command output
@ -7,20 +8,18 @@
-- In the other example `sensors` returns to the widget its full output
-- and it's trimmed in the widget callback function:
--
-- 211 mytextclock,
-- 212 wibox.widget.textbox(' | '),
-- 213 -- one way to do that:
-- 214 awful.widget.watch('bash -c "sensors | grep temp1"', 15),
-- 215 -- another way:
-- 216 awful.widget.watch('sensors', 15, function(widget, stdout)
-- 217 for line in stdout:gmatch("[^\r\n]+") do
-- 218 if line:match("temp1") then
-- 219 widget:set_text(line)
-- 220 return
-- 221 end
-- 222 end
-- 223 end),
-- 224 s.mylayoutbox,
-- -- one way to do that:
-- local w = awful.widget.watch('bash -c "sensors | grep temp1"', 15)
--
-- -- another way:
-- local w = awful.widget.watch('sensors', 15, function(widget, stdout)
-- for line in stdout:gmatch("[^\r\n]+") do
-- if line:match("temp1") then
-- widget:set_text(line)
-- return
-- end
-- end
-- end)
--
-- ![Example screenshot](../images/awful_widget_watch.png)
--
@ -55,7 +54,7 @@ local watch = { mt = {} }
-- function(widget, stdout, stderr, exitreason, exitcode)
-- widget:set_text(stdout)
-- end
-- @param callback.widget Base widget instance.
-- @tparam wibox.widget callback.widget Base widget instance.
-- @tparam string callback.stdout Output on stdout.
-- @tparam string callback.stderr Output on stderr.
-- @tparam string callback.exitreason Exit Reason.
@ -64,7 +63,7 @@ local watch = { mt = {} }
-- For "exit" reason it's the exit code.
-- For "signal" reason — the signal causing process termination.
--
-- @param[opt=wibox.widget.textbox()] base_widget Base widget.
-- @tparam[opt=wibox.widget.textbox()] wibox.widget base_widget Base widget.
--
-- @return The widget used by this watch.
-- @return Its gears.timer.

48
lib/beautiful/init.lua
View File

@ -1,5 +1,5 @@
----------------------------------------------------------------------------
--- Theme library.
--- Key+value based theme library and associated utility modules.
--
-- @author Damien Leone &lt;damien.leone@gmail.com&gt;
-- @author Julien Danjou &lt;julien@danjou.info&gt;
@ -89,62 +89,52 @@ local active_font
--- The default font.
-- @beautiful beautiful.font
-- @param string
-- @param[opt="sans 8"] string
-- The default background color.
--- The default background color.
--
-- The background color can be transparent. If there is a
-- compositing manager such as compton, then it will be
-- real transparency and may include blur (provided by the
-- compositor). When there is no compositor, it will take
-- a picture of the wallpaper and blend it.
--
-- @beautiful beautiful.bg_normal
-- @param color
-- The default focused element background color.
--- The default focused element background color.
-- @beautiful beautiful.bg_focus
-- @param color
-- The default urgent element background color.
--- The default urgent element background color.
-- @beautiful beautiful.bg_urgent
-- @param color
-- The default minimized element background color.
--- The default minimized element background color.
-- @beautiful beautiful.bg_minimize
-- @param color
-- The system tray background color.
-- Please note that only solid colors are currently supported.
-- @beautiful beautiful.bg_systray
-- @param color
-- The default focused element foreground (text) color.
--- The default focused element foreground (text) color.
-- @beautiful beautiful.fg_normal
-- @param color
-- The default focused element foreground (text) color.
--- The default focused element foreground (text) color.
-- @beautiful beautiful.fg_focus
-- @param color
-- The default urgent element foreground (text) color.
--- The default urgent element foreground (text) color.
-- @beautiful beautiful.fg_urgent
-- @param color
-- The default minimized element foreground (text) color.
--- The default minimized element foreground (text) color.
-- @beautiful beautiful.fg_minimize
-- @param color
--- The gap between clients.
-- @beautiful beautiful.useless_gap
-- @param[opt=0] number
--- The fallback border width.
-- @beautiful beautiful.border_width
-- @param number
--- The fallback border color.
-- @beautiful beautiful.border_color
-- @param color
--- The wallpaper path.
-- @beautiful beautiful.wallpaper
-- @tparam string|gears.surface wallpaper
-- The icon theme name.
--- The icon theme name.
-- It has to be a directory in `/usr/share/icons` or an XDG icon folder.
-- @beautiful beautiful.icon_theme
-- @param string
@ -234,7 +224,7 @@ end
--- Get the height of a font.
--
-- @param name Name of the font.
-- @tparam string name Name of the font.
-- @staticfct beautiful.get_font_height
function beautiful.get_font_height(name)
return load_font(name).height

4
lib/gears/debug.lua
View File

@ -1,4 +1,6 @@
---------------------------------------------------------------------------
-- Utility functions to make development easier.
--
-- @author Uli Schlachter
-- @copyright 2010 Uli Schlachter
-- @utillib gears.debug
@ -141,7 +143,7 @@ end
-- @tparam table fallback The new class.
-- @tparam string old_name The old class name.
-- @tparam string new_name The new class name.
-- @tparam[opt={}] args The name.
-- @tparam[opt={}] table args The name.
-- @tparam[opt] number args.deprecated_in The version which deprecated this
-- class.
-- @treturn table A proxy class.

5
lib/gears/filesystem.lua
View File

@ -1,5 +1,8 @@
---------------------------------------------------------------------------
--- Filesystem module for gears.
--- Various filesystem utility functions.
--
-- Note that these functions are blocking. If you need to do a large number of
-- I/O operations, it is better to use `lgi.Gio` async functions.
--
-- @utillib gears.filesystem
---------------------------------------------------------------------------

2
lib/gears/math.lua
View File

@ -1,4 +1,6 @@
---------------------------------------------------------------------------
-- Various math related functions.
--
--- Math module for gears.
--
-- @utillib gears.math

5
lib/gears/protected_call.lua
View File

@ -1,4 +1,9 @@
---------------------------------------------------------------------------
-- Safely call a function and handle errors using `gears.debug`.
--
-- This is a `pcall`/`xpcall` wrapper. All it does is to integrate into the
-- AwesomeWM-wide error handling and logging.
--
-- @author Uli Schlachter
-- @copyright 2016 Uli Schlachter
-- @utillib gears.protected_call

6
lib/gears/shape.lua
View File

@ -215,7 +215,7 @@ end
-- @param cr A cairo content
-- @tparam number width The rectangle width
-- @tparam number height The rectangle height
-- @tparam number radius the corner radius
-- @tparam number radius The corner radius
-- @staticfct gears.shape.rounded_rect
function module.rounded_rect(cr, width, height, radius)
@ -627,8 +627,8 @@ end
-- @tparam[opt=math.min(width height)/2] number thickness The arc thickness
-- @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=false] boolean start_rounded if the arc start rounded
-- @tparam[opt=false] boolean end_rounded if the arc end rounded
-- @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

2
lib/gears/sort/init.lua
View File

@ -1,5 +1,5 @@
---------------------------------------------------------------------------
--- Extra sorting algorithms.
--- Utilities to sort and arrange data.
--
-- @utillib gears.sort
---------------------------------------------------------------------------

6
lib/gears/string.lua
View File

@ -1,5 +1,5 @@
---------------------------------------------------------------------------
--- String module for gears.
--- Various string manipulation and introspection fuctions.
--
-- @utillib gears.string
---------------------------------------------------------------------------
@ -10,7 +10,7 @@ local xml_entity_names = { ["'"] = "&apos;", ["\""] = "&quot;", ["<"] = "&lt;",
--- Escape a string from XML char.
-- Useful to set raw text in textbox.
-- @param text Text to escape.
-- @tparam string text Text to escape.
-- @treturn string Escaped text.
-- @staticfct gears.string.xml_escape
function gstring.xml_escape(text)
@ -21,7 +21,7 @@ local xml_entity_chars = { lt = "<", gt = ">", nbsp = " ", quot = "\"", apos = "
amp = "&" };
--- Unescape a string from entities.
-- @param text Text to unescape.
-- @tparam string text Text to unescape.
-- @treturn string Unescaped text.
-- @staticfct gears.string.xml_unescape
function gstring.xml_unescape(text)

9
lib/gears/surface.lua
View File

@ -1,4 +1,6 @@
---------------------------------------------------------------------------
-- Utilities to integrate and manipulate Cairo drawing surfaces.
--
-- @author Uli Schlachter
-- @copyright 2012 Uli Schlachter
-- @module gears.surface
@ -195,10 +197,9 @@ end
--
-- If the wibox or client size change, this function need to be called
-- again.
-- @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.
-- @tparam client|wibox draw A wibox or a client.
-- @tparam gears.shape|function shape The shape.
-- @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()

4
lib/gears/table.lua
View File

@ -1,8 +1,8 @@
---------------------------------------------------------------------------
--- Table module for gears.
--- Various functions to worj with tables.
--
-- Examples
-- =======
-- ========
--
-- Using `cycle_value`, you can cycle through values in a table.
-- When the end of the table is reached, `cycle_value` loops around to the beginning.

17
lib/gears/timer.lua
View File

@ -1,5 +1,5 @@
---------------------------------------------------------------------------
--- Timer objects and functions.
--- Class to execute code at specific intervals.
--
-- @usage
-- -- Create a widget and update its content using the output of a shell
@ -134,13 +134,18 @@ function timer:again()
end
--- The timer is started.
-- @property started
-- @param boolean
--
-- For this to be `true` by default, pass `autostart` to the constructor.
--
-- @property[opt=false] started
-- @tparam boolean started
-- @see start
-- @see stop
--- The timer timeout value.
-- **Signal:** property::timeout
--
-- @property timeout
-- @param number
-- @tparam number timeout
-- @propemits true false
local timer_instance_mt = {
@ -273,7 +278,7 @@ end
--- Call the given function at the end of the current GLib event loop iteration.
-- @tparam function callback The function that should be called
-- @param ... Arguments to the callback function
--@param ... Arguments to the callback function
-- @staticfct gears.timer.delayed_call
function timer.delayed_call(callback, ...)
assert(type(callback) == "function", "callback must be a function, got: " .. type(callback))

1
lib/menubar/icon_theme.lua
View File

@ -82,6 +82,7 @@ local index_theme_cache = {}
-- @tparam string icon_theme_name Internal name of icon theme
-- @tparam table base_directories Paths used for lookup
-- @treturn table An instance of the class `icon_theme`
-- @usebeautiful beautiful.icon_theme
icon_theme.new = function(icon_theme_name, base_directories)
icon_theme_name = icon_theme_name or beautiful.icon_theme or get_default_icon_theme_name()
base_directories = base_directories or get_pragmatic_base_directories()

7
lib/menubar/init.lua
View File

@ -454,6 +454,13 @@ end
--- Show the menubar on the given screen.
-- @param[opt] scr Screen.
-- @staticfct menubar.show
-- @usebeautiful beautiful.menubar_fg_normal
-- @usebeautiful beautiful.menubar_bg_normal
-- @usebeautiful beautiful.menubar_border_width
-- @usebeautiful beautiful.menubar_border_color
-- @usebeautiful beautiful.menubar_fg_focus
-- @usebeautiful beautiful.menubar_bg_focus
-- @usebeautiful beautiful.menubar_font
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

4
lib/menubar/utils.lua
View File

@ -1,5 +1,5 @@
---------------------------------------------------------------------------
--- Utility module for menubar
--- Utility functions for the `menubar` module.
--
-- @author Antonio Terceiro
-- @copyright 2009, 2011-2012 Antonio Terceiro, Alexander Yakushev
@ -199,7 +199,7 @@ local function get_icon_lookup_path()
end
--- Remove CR newline from the end of the string.
-- @param s string to trim
-- @tparam string s The string to trim
-- @staticfct menubar.utils.rtrim
function utils.rtrim(s)
if not s then return end

6
lib/naughty/action.lua
View File

@ -35,12 +35,12 @@ local action = {}
-- implement keyboard navigation.
--
-- @property selected
-- @param boolean
-- @tparam boolean selected
-- @propemits true false
--- The action position (index).
-- @property position
-- @param number
-- @tparam number position
-- @propemits true false
--- The action icon.
@ -53,7 +53,7 @@ local action = {}
-- @DOC_wibox_nwidget_actionlist_icon_only_EXAMPLE@
--
-- @property icon_only
-- @param[opt=false] boolean
-- @tparam[opt=false] boolean icon_only
-- @propemits true false
--- When a notification is invoked.

3
lib/naughty/container/background.lua
View File

@ -1,5 +1,5 @@
----------------------------------------------------------------------------
--- A notification background.
--- A notification background widget.
--
-- This widget holds the boilerplate code associated with the notification
-- background. This includes the color and potentially some other styling
@ -16,6 +16,7 @@
-- @author Emmanuel Lepage Vallee &lt;elv1313@gmail.com&gt;
-- @copyright 2019 Emmanuel Lepage Vallee
-- @containermod naughty.widget.background
-- @supermodule wibox.container.background
-- @see wibox.container.background
----------------------------------------------------------------------------
local wbg = require("wibox.container.background")

2
lib/naughty/init.lua
View File

@ -1,4 +1,6 @@
---------------------------------------------------------------------------
-- Desktop notification handling library.
--
-- @author Uli Schlachter &lt;psychon@znc.in&gt;
-- @copyright 2014 Uli Schlachter
-- @module naughty

2
lib/naughty/layout/box.lua
View File

@ -208,7 +208,7 @@ end)
-- }
--
-- @property widget_template
-- @param widget
-- @tparam[opt=nil] widget|nil|table widget_template
-- @usebeautiful beautiful.notification_max_width The maximum width for the
-- resulting widget.

2
lib/naughty/layout/legacy.lua
View File

@ -1,5 +1,5 @@
----------------------------------------------------------------------------
--- A notification popup widget.
--- A notification popup widget (deprecated implementation).
--
-- This is the legacy notification widget. It was the default until Awesome
-- v4.3 but is now being deprecated in favor of a more flexible widget.

64
lib/naughty/notification.lua
View File

@ -1,5 +1,5 @@
---------------------------------------------------------------------------
--- A notification object.
--- Notification manipulation class.
--
-- This class creates individual notification objects that can be manipulated
-- to extend the default behavior.
@ -110,7 +110,7 @@ local notification = {}
-- * critical
--
-- @property urgency
-- @param string
-- @tparam string urgency
-- @propemits true false
--- The notification category.
@ -167,17 +167,17 @@ local notification = {}
-- be updated with a date further in the future.
--
-- @property resident
-- @param[opt=false] boolean
-- @tparam[opt=false] boolean resident
-- @propemits true false
--- Delay in seconds after which hovered popup disappears.
-- @property hover_timeout
-- @param number
-- @tparam[opt=nil] number|nil hover_timeout
-- @propemits true false
--- Target screen for the notification.
-- @property screen
-- @param screen
-- @tparam screen screen
-- @propemits true false
--- Corner of the workarea displaying the popups.
@ -195,34 +195,35 @@ local notification = {}
--@DOC_awful_notification_box_corner_EXAMPLE@
--
-- @property position
-- @param string
-- @tparam[opt=beautiful.notification_position] string position
-- @propemits true false
-- @see awful.placement.next_to
--- Boolean forcing popups to display on top.
-- @property ontop
-- @param boolean
-- @tparam[opt=false] boolean ontop
--- Popup height.
--
--@DOC_awful_notification_geometry_EXAMPLE@
--
-- @property height
-- @param number
-- @tparam number height
-- @propemits true false
-- @see width
--- Popup width.
-- @property width
-- @param number
-- @tparam number width
-- @propemits true false
-- @see height
--- Notification font.
--@DOC_naughty_colors_EXAMPLE@
-- @property font
-- @param string
-- @tparam string font
-- @propemits true false
-- @see wibox.widget.textbox.font
--- "All in one" way to access the default image or icon.
--
@ -248,7 +249,7 @@ local notification = {}
--- Desired icon size in px.
-- @property icon_size
-- @param number
-- @tparam[opt=beautiful.notification_icon_size] number icon_size
-- @propemits true false
--- The icon provided in the `app_icon` field of the DBus notification.
@ -257,7 +258,7 @@ local notification = {}
-- icon name to be fetched from the theme.
--
-- @property app_icon
-- @param string
-- @tparam string app_icon
-- @propemits true false
--- The notification image.
@ -287,7 +288,7 @@ local notification = {}
--@DOC_awful_notification_fg_EXAMPLE@
--
-- @property fg
-- @tparam string|color|pattern fg
-- @tparam[beautiful.notification_fg] string|color|pattern fg
-- @propemits true false
-- @see title
-- @see gears.color
@ -297,14 +298,14 @@ local notification = {}
--@DOC_awful_notification_bg_EXAMPLE@
--
-- @property bg
-- @tparam string|color|pattern bg
-- @tparam[opt=beautiful.notification_bg] string|color|pattern bg
-- @propemits true false
-- @see title
-- @see gears.color
--- Border width.
-- @property border_width
-- @param number
-- @tparam[opt=beautiful.notification_border_width or 0] number border_width
-- @propemits true false
--- Border color.
@ -312,7 +313,7 @@ local notification = {}
--@DOC_awful_notification_border_color_EXAMPLE@
--
-- @property border_color
-- @param string
-- @tparam[opt=beautiful.notification_border_color] string border_color
-- @propemits true false
-- @see gears.color
@ -368,14 +369,14 @@ local notification = {}
-- args will override ones defined
-- in the preset.
-- @property preset
-- @param table
-- @tparam table preset
-- @propemits true false
--- Function that will be called with all arguments.
-- The notification will only be displayed if the function returns true.
-- Note: this function is only relevant to notifications sent via dbus.
-- @property callback
-- @param function
-- @tparam function callback
-- @propemits true false
--- A table containing strings that represents actions to buttons.
@ -383,7 +384,7 @@ local notification = {}
-- The table key (a number) is used by DBus to set map the action.
--
-- @property actions
-- @param table
-- @tparam table actions
-- @propemits true false
--- Ignore this notification, do not display.
@ -392,19 +393,20 @@ local notification = {}
-- handler.
--
-- @property ignore
-- @param boolean
-- @tparam[opt=false] boolean ignore
-- @propemits true false
--- Tell if the notification is currently suspended (read only).
--
-- This is always equal to `naughty.suspended`
--@property suspended
--@param boolean
-- @property suspended
-- @tparam[opt=false] boolean suspended
-- @propemits true false
-- @see naughty.suspended
--- If the notification is expired.
-- @property is_expired
-- @param boolean
-- @tparam boolean is_expired
-- @propemits true false
-- @see naughty.expiration_paused
@ -436,7 +438,7 @@ local notification = {}
-- client.
--
-- @property clients
-- @param table
-- @tparam table clients
--- The maximum popup width.
--
@ -444,8 +446,8 @@ local notification = {}
-- this is ignored by `naughty.list.notifications` because it delegate this
-- decision to the layout.
--
-- @property[opt=500] max_width
-- @param number
-- @property max_width
-- @tparam[opt=500] number max_width
-- @propemits true false
--- The application name specified by the notification.
@ -454,7 +456,7 @@ local notification = {}
-- property, but can sometime be specified for remote or headless notifications.
-- In these case, it helps to triage and detect the notification from the rules.
-- @property app_name
-- @param string
-- @tparam string app_name
-- @propemits true false
--- The widget template used to represent the notification.
@ -463,7 +465,7 @@ local notification = {}
-- off with a specialized notification widget.
--
-- @property widget_template
-- @param table
-- @tparam table|nil widget_template
-- @propemits true false
--- Destroy notification by notification object.
@ -921,9 +923,9 @@ end
-- @tparam[opt=`beautiful.notification_fg` or `beautiful.bg_focus` or `'#535d6c'`] string args.bg Background color.
-- @tparam[opt=`beautiful.notification_border_width` or 1] integer args.border_width Border width.
-- @tparam[opt=`beautiful.notification_border_color` or `beautiful.border_color_active` or `'#535d6c'`] gears.color args.border_color Border color.
-- @tparam[opt=`beautiful.notification_shape`] gears.shape args.shape Widget shape.
-- @tparam[opt=`beautiful.notification_opacity`] gears.opacity args.opacity Widget opacity.
-- @tparam[opt=`beautiful.notification_margin`] gears.margin args.margin Widget margin.
-- @tparam[opt=beautiful.notification_shape] gears.shape args.shape Widget shape.
-- @tparam[opt=beautiful.notification_opacity] gears.opacity args.opacity Widget opacity.
-- @tparam[opt=beautiful.notification_margin] gears.margin args.margin Widget margin.
-- @tparam[opt] function args.run Function to run on left click. The notification
-- object will be passed to it as an argument.
-- You need to call e.g.

10
lib/naughty/widget/icon.lua
View File

@ -1,5 +1,5 @@
----------------------------------------------------------------------------
--- A notification square icon.
--- A notification square icon widget.
--
-- This widget is a specialized `wibox.widget.imagebox` with the following extra
-- features:
@ -14,6 +14,7 @@
-- @author Emmanuel Lepage Vallee &lt;elv1313@gmail.com&gt;
-- @copyright 2017 Emmanuel Lepage Vallee
-- @widgetmod naughty.widget.icon
-- @supermodule wibox.widget.imagebox
-- @see wibox.widget.imagebox
----------------------------------------------------------------------------
local imagebox = require("wibox.widget.imagebox")
@ -24,7 +25,7 @@ local dpi = require("beautiful.xresources").apply_dpi
local icon = {}
-- The default way to resize the icon.
--- The default way to resize the icon.
-- @beautiful beautiful.notification_icon_resize_strategy
-- @param number
@ -130,6 +131,11 @@ local valid_strategies = {
-- there is no specified strategy.
-- @usebeautiful beautiful.notification_icon_size The size upper bound.
--- The default notification icon size.
-- @beautiful beautiful.notification_icon_size
-- @tparam number notification_icon_size The size (in pixels).
function icon:set_resize_strategy(strategy)
assert(valid_strategies[strategy], "Invalid strategy")

3
lib/naughty/widget/message.lua
View File

@ -1,5 +1,5 @@
----------------------------------------------------------------------------
--- A notification content message.
--- A notification content message widget.
--
-- This widget is a specialized `wibox.widget.textbox` with the following extra
-- features:
@ -12,6 +12,7 @@
-- @author Emmanuel Lepage Vallee &lt;elv1313@gmail.com&gt;
-- @copyright 2017 Emmanuel Lepage Vallee
-- @widgetmod naughty.widget.message
-- @supermodule wibox.widget.textbox
-- @see wibox.widget.textbox
----------------------------------------------------------------------------
local textbox = require("wibox.widget.textbox")

3
lib/naughty/widget/title.lua
View File

@ -1,5 +1,5 @@
----------------------------------------------------------------------------
--- A notification title.
--- A notification title widget.
--
-- This widget is a specialized `wibox.widget.textbox` with the following extra
-- features:
@ -12,6 +12,7 @@
-- @author Emmanuel Lepage Vallee &lt;elv1313@gmail.com&gt;
-- @copyright 2017 Emmanuel Lepage Vallee
-- @widgetmod naughty.widget.title
-- @supermodule wibox.widget.textbox
-- @see wibox.widget.textbox
----------------------------------------------------------------------------
local textbox = require("wibox.widget.textbox")

2
lib/ruled/client.lua
View File

@ -1,5 +1,5 @@
---------------------------------------------------------------------------
--- Rules for clients.
--- Apply properties to a new client based on pre-determined rules.
--
-- This module applies @{rules} to clients during startup (via @{client.manage},
-- but its functions can be used for client matching in general.

2
lib/ruled/notification.lua
View File

@ -1,5 +1,5 @@
---------------------------------------------------------------------------
--- Rules for notifications.
--- Apply properties to a new `naughty.notification` based on pre-determined rules.
--
--@DOC_wibox_nwidget_rules_urgency_EXAMPLE@
--

29
lib/wibox/container/arcchart.lua
View File

@ -1,6 +1,5 @@
---------------------------------------------------------------------------
--
-- A circular chart (arc chart).
-- A circular chart (arc chart) container.
--
-- It can contain a central widget (or not) and display multiple values.
--
@ -43,7 +42,19 @@ local arcchart = { mt = {} }
--- The arc thickness.
-- @beautiful beautiful.arcchart_thickness
-- @param number
-- @tparam number arcchart_thickness
--- If the chart has rounded edges.
-- @beautiful beautiful.arcchart_rounded_edge
-- @tparam boolean arcchart_rounded_edge
--- The radial background.
-- @beautiful beautiful.arcchart_bg
-- @tparam gears.color arcchart_bg
--- The (radiant) angle where the first value start.
-- @beautiful beautiful.arcchart_start_angle
-- @tparam number arcchart_start_angle
local function outline_workarea(width, height)
local x, y = 0, 0
@ -102,7 +113,6 @@ function arcchart:after_draw_children(_, cr, width, height)
local wa = outline_workarea(width, height)
cr:translate(wa.x+border_width/2, wa.y+border_width/2)
-- Get the min and max value
--local min_val = self:get_min_value() or 0 --TODO support min_values
local max_val = self:get_max_value()
@ -245,9 +255,9 @@ end
--- The arcchart values foreground colors.
--@DOC_wibox_container_arcchart_color_EXAMPLE@
-- @property colors
-- @tparam table values An ordered set of colors for each value in arcchart.
-- @tparam table colors An ordered set of colors for each value in arcchart.
-- @propemits true false
-- @propbeautiful
-- @usebeautiful beautiful.arcchart_color
--- The border width.
--
@ -279,7 +289,7 @@ end
--- The value.
--@DOC_wibox_container_arcchart_value_EXAMPLE@
-- @property value
-- @tparam number value Between min_value and max_value
-- @tparam number value Between `min_value` and `max_value`
-- @see values
-- @propemits true false
@ -297,18 +307,21 @@ end
-- @property rounded_edge
-- @tparam[opt=false] boolean rounded_edge
-- @propemits true false
-- @propbeautiful
--- The arc thickness.
--@DOC_wibox_container_arcchart_thickness_EXAMPLE@
-- @property thickness
-- @propemits true false
-- @tparam number thickness
-- @propbeautiful
--- The (radiant) angle where the first value start.
--@DOC_wibox_container_arcchart_start_angle_EXAMPLE@
-- @DOC_wibox_container_arcchart_start_angle_EXAMPLE@
-- @property start_angle
-- @tparam[opt=math.pi] number start_angle A number between 0 and 2*math.pi
-- @propemits true false
-- @usebeautiful beautiful.arcchart_start_angle
for _, prop in ipairs {"border_width", "border_color", "paddings", "colors",
"rounded_edge", "bg", "thickness", "values", "min_value", "max_value",

8
lib/wibox/container/background.lua
View File

@ -349,7 +349,7 @@ end
--
-- See `wibox.container.background.shape` for an usage example.
-- @property border_width
-- @tparam[opt=0] number width The border width.
-- @tparam[opt=0] number border_width The border width.
-- @propemits true false
-- @introducedin 4.4
-- @see border_color
@ -386,7 +386,7 @@ end
--
-- @deprecatedproperty shape_border_color
-- @usebeautiful beautiful.fg_normal Fallback when 'fg' and `border_color` aren't set.
-- @tparam[opt=self._private.foreground] color fg The border color, pattern or gradient
-- @tparam color fg The border color, pattern or gradient
-- @renamedin 4.4 border_color
-- @see gears.color
-- @see border_color
@ -395,7 +395,7 @@ end
--
-- See `wibox.container.background.shape` for an usage example.
-- @property border_color
-- @tparam[opt=self._private.foreground] color fg The border color, pattern or gradient
-- @tparam[opt=fg] color border_color The border color, pattern or gradient
-- @propemits true false
-- @usebeautiful beautiful.fg_normal Fallback when 'fg' and `border_color` aren't set.
-- @introducedin 4.4
@ -462,7 +462,7 @@ end
-- as arguments. Any other arguments passed to this method will be appended.
--
-- @property bgimage
-- @tparam string|surface|function image A background image or a function
-- @tparam string|surface|function bgimage A background image or a function
-- @see gears.surface
function background:set_bgimage(image, ...)

18
lib/wibox/container/margin.lua
View File

@ -94,7 +94,7 @@ end
--- Set all the margins to val.
--
-- @property margins
-- @tparam number|table val The margin value. It can be a number or a table with
-- @tparam number|table margins The margin value. It can be a number or a table with
-- the *left*/*right*/*top*/*bottom* keys.
-- @propemits false false
@ -126,7 +126,7 @@ end
--- Set the margins color to create a border.
--
-- @property color
-- @param color A color used to fill the margin.
-- @tparam gears.color color A color used to fill the margin.
-- @propemits true false
function margin:set_color(color)
@ -206,13 +206,13 @@ end
--- Returns a new margin container.
--
-- @param[opt] widget A widget to use.
-- @param[opt] left A margin to use on the left side of the widget.
-- @param[opt] right A margin to use on the right side of the widget.
-- @param[opt] top A margin to use on the top side of the widget.
-- @param[opt] bottom A margin to use on the bottom side of the widget.
-- @param[opt] color A color for the margins.
-- @param[opt] draw_empty whether or not to draw the margin when the content is empty
-- @tparam[opt] widget widget A widget to use.
-- @tparam[opt] number left A margin to use on the left side of the widget.
-- @tparam[opt] number right A margin to use on the right side of the widget.
-- @tparam[opt] number top A margin to use on the top side of the widget.
-- @tparam[opt] number bottom A margin to use on the bottom side of the widget.
-- @tparam[opt] gears.color color A color for the margins.
-- @tparam[opt] boolean draw_empty Whether or not to draw the margin when the content is empty
-- @treturn table A new margin container
-- @constructorfct wibox.container.margin
local function new(widget, left, right, top, bottom, color, draw_empty)

2
lib/wibox/container/radialprogressbar.lua
View File

@ -178,7 +178,7 @@ end
--
--@DOC_wibox_container_radialprogressbar_value_EXAMPLE@
-- @property value
-- @tparam number value Between min_value and max_value.
-- @tparam number value Between `min_value` and `max_value`.
-- @propemits true false
function radialprogressbar:set_value(val)

2
lib/wibox/container/rotate.lua
View File

@ -101,7 +101,7 @@ end
--
--@DOC_wibox_container_rotate_angle_EXAMPLE@
-- @property direction
-- @tparam string dir The direction.
-- @tparam[opt="north"] string direction The direction.
-- @propemits true false
function rotate:set_direction(dir)

16
lib/wibox/container/tile.lua
View File

@ -110,7 +110,7 @@ end
--@DOC_wibox_container_tile_horizontal_crop_EXAMPLE@
--
-- @property horizontal_crop
-- @tparam[opt=false] boolean tiled
-- @tparam[opt=false] boolean horizontal_crop
-- @see vertical_crop
--- Avoid painting incomplete vertical tiles.
@ -118,7 +118,7 @@ end
--@DOC_wibox_container_tile_vertical_crop_EXAMPLE@
--
-- @property vertical_crop
-- @tparam[opt=false] boolean tiled
-- @tparam[opt=false] boolean vertical_crop
-- @see horizontal_crop
--- Enable or disable the tiling.
@ -199,9 +199,19 @@ end
--- Create a new tile container.
-- @tparam table args
-- @tparam wibox.widget widget args.widget The widget to tile.
-- @tparam wibox.widget args.widget args.widget The widget to tile.
-- @tparam string args.halign Either `left`, `right` or `center`.
-- @tparam string args.valign Either `top`, `bottom` or `center`.
-- @tparam number args.horizontal_spacing The horizontal spacing between the tiled.
-- @tparam number args.vertical_spacing The vertical spacing between the tiled.
-- @tparam boolean args.horizontal_crop Avoid painting incomplete horizontal tiles.
-- @tparam boolean args.vertical_crop Avoid painting incomplete vertical tiles.
-- @tparam boolean args.tiled Enable or disable the tiling.
-- @tparam wibox.widget args.widget The widget to be placed.
-- @tparam boolean args.fill_vertical Fill the vertical space.
-- @tparam boolean args.fill_horizontal Fill the horizontal space.
-- @tparam boolean args.content_fill_vertical Stretch the contained widget so it takes all the vertical space.
-- @tparam boolean args.content_fill_horizontal Stretch the contained widget so it takes all the horizontal space.
-- @constructorfct wibox.container.tile
function module.mt:__call(...)
return new(...)

2
lib/wibox/drawable.lua
View File

@ -199,7 +199,7 @@ local function find_widgets(self, result, hierarchy, x, y)
end
end
--- Find a widget by a point.
-- Find a widget by a point.
-- The drawable must have drawn itself at least once for this to work.
-- @param x X coordinate of the point
-- @param y Y coordinate of the point

2
lib/wibox/init.lua
View File

@ -1,4 +1,6 @@
---------------------------------------------------------------------------
-- Box where widget can be displayed.
--
-- @author Uli Schlachter
-- @copyright 2010 Uli Schlachter
-- @popupmod wibox

2
lib/wibox/layout/align.lua
View File

@ -273,7 +273,7 @@ end
-- `"inside"`.
--
-- @property expand
-- @tparam[opt="inside"] string mode How to use unused space.
-- @tparam[opt="inside"] string expand How to use unused space.
function align:set_expand(mode)
if mode == "none" or mode == "outside" then

2
lib/wibox/layout/fixed.lua
View File

@ -1,4 +1,6 @@
---------------------------------------------------------------------------
-- Place many widgets in a column or row, until the available space is used up.
--
-- A `fixed` layout may be initialized with any number of child widgets, and
-- during runtime widgets may be added and removed dynamically.
--

5
lib/wibox/layout/flex.lua
View File

@ -1,4 +1,7 @@
---------------------------------------------------------------------------
-- Split the space equally between multiple widgets.
--
--
-- A `flex` layout may be initialized with any number of child widgets, and
-- during runtime widgets may be added and removed dynamically.
--
@ -49,7 +52,7 @@ local flex = {}
--- Remove a widget from the layout.
--
-- @tparam index The widget index to remove.
-- @tparam number index The widget index to remove.
-- @treturn boolean index If the operation is successful.
-- @method remove
-- @interface layout

40
lib/wibox/layout/grid.lua
View File

@ -1,5 +1,5 @@
---------------------------------------------------------------------------
--- A grid layout.
--- Place multiple widgets in multiple rows and columns.
--
-- Widgets spanning several columns or rows cannot be included using the
-- declarative system.
@ -52,7 +52,7 @@ local dir_properties = { "spacing", "homogeneous", "expand" }
-- row is filled, creating it if it does not exist.
--
--@DOC_wibox_layout_grid_orientation_EXAMPLE@
-- @param[opt="vertical"] string Preferred orientation: "horizontal" or "vertical".
-- @tparam[opt="vertical"] string orientation Preferred orientation: "horizontal" or "vertical".
-- @property orientation
--- Allow to superpose widgets in the same cell.
@ -60,39 +60,39 @@ local dir_properties = { "spacing", "homogeneous", "expand" }
-- widget and prevent from adding it.
--
--@DOC_wibox_layout_grid_superpose_EXAMPLE@
-- @param[opt=false] boolean
-- @tparam[opt=false] boolean superpose
-- @property superpose
--- Force the number of rows of the layout.
-- @property forced_num_rows
-- @tparam[opt=nil] number|nil number Forced number of rows (`nil` for automatic).
-- @tparam[opt=nil] number|nil forced_num_rows Forced number of rows (`nil` for automatic).
--- Force the number of columns of the layout.
-- @property forced_num_cols
-- @tparam[opt=nil] number|nil number Forced number of columns (`nil` for automatic).
-- @tparam[opt=nil] number|nil forced_num_cols Forced number of columns (`nil` for automatic).
--- Set the minimum size for the columns.
--
--@DOC_wibox_layout_grid_min_size_EXAMPLE@
-- @param[opt=0] number Minimum size of the columns.
-- @tparam[opt=0] number min_cols_size Minimum size of the columns.
-- @property min_cols_size
--- Set the minimum size for the rows.
-- @param[opt=0] number Minimum size of the rows.
-- @tparam[opt=0] number min_rows_size Minimum size of the rows.
-- @property min_rows_size
--- The spacing between columns.
--
-- see `spacing`
--
-- @param[opt=0] number The spacing
-- @tparam[opt=0] number horizontal_spacing The spacing
-- @property horizontal_spacing
--- The spacing between rows.
--
-- see `spacing`
--
-- @param[opt=0] number The spacing
-- @tparam[opt=0] number vertical_spacing The spacing
-- @property vertical_spacing
--- The spacing between rows and columns.
@ -101,21 +101,21 @@ local dir_properties = { "spacing", "homogeneous", "expand" }
-- preferred `orientation`.
--
--@DOC_wibox_layout_grid_spacing_EXAMPLE@
-- @param[opt=0] number The spacing
-- @tparam[opt=0] number spacing The spacing
-- @property spacing
--- Controls if the columns are expanded to use all the available width.
--
-- see `expand`
--
-- @param[opt=false] boolean Expand the grid into the available space
-- @tparam[opt=false] boolean horizontal_expand Expand the grid into the available space
-- @property horizontal_expand
--- Controls if the rows are expanded to use all the available height.
--
-- see `expand`
--
-- @param[opt=false] boolean Expand the grid into the available space
-- @tparam[opt=false] boolean vertical_expand Expand the grid into the available space
-- @property vertical_expand
--- Controls if the columns/rows are expanded to use all the available space.
@ -124,7 +124,7 @@ local dir_properties = { "spacing", "homogeneous", "expand" }
-- preferred `orientation`.
--
--@DOC_wibox_layout_grid_expand_EXAMPLE@
-- @param[opt=false] boolean Expand the grid into the available space
-- @tparam[opt=false] boolean expand Expand the grid into the available space
-- @property expand
--- Controls if the columns all have the same width or if the width of each
@ -132,7 +132,7 @@ local dir_properties = { "spacing", "homogeneous", "expand" }
--
-- see `homogeneous`
--
-- @param[opt=true] boolean All the columns have the same width.
-- @tparam[opt=true] boolean horizontal_homogeneous All the columns have the same width.
-- @property horizontal_homogeneous
--- Controls if the rows all have the same height or if the height of each row
@ -140,7 +140,7 @@ local dir_properties = { "spacing", "homogeneous", "expand" }
--
-- see `homogeneous`
--
-- @param[opt=true] boolean All the rows have the same height.
-- @tparam[opt=true] boolean vertical_homogeneous All the rows have the same height.
-- @property vertical_homogeneous
--- Controls if the columns/rows all have the same size or if the size depends
@ -150,7 +150,7 @@ local dir_properties = { "spacing", "homogeneous", "expand" }
-- by the preferred `orientation`.
--
--@DOC_wibox_layout_grid_expand_EXAMPLE@
-- @param[opt=true] boolean All the columns/rows have the same size.
-- @tparam[opt=true] boolean homogeneous All the columns/rows have the same size.
-- @property homogeneous
--- Child widget position. Return of `get_widget_position`.
@ -305,7 +305,7 @@ end
--@DOC_wibox_layout_grid_add_EXAMPLE@
--
-- @method add_widget_at
-- @param child Widget that should be added
-- @tparam wibox.widget child Widget that should be added
-- @tparam number row Row number for the top left corner of the widget
-- @tparam number col Column number for the top left corner of the widget
-- @tparam[opt=1] number row_span The number of rows the widget spans.
@ -400,7 +400,7 @@ end
--- Return the coordinates of the widget.
-- @method get_widget_position
-- @param widget The widget
-- @tparam widget widget The widget
-- @treturn table The `position` table of the coordinates in the grid, with
-- fields `row`, `col`, `row_span` and `col_span`.
function grid:get_widget_position(widget)
@ -441,8 +441,8 @@ end
--- Replace old widget by new widget, spanning the same columns and rows.
-- @method replace_widget
-- @param old The widget to remove
-- @param new The widget to add
-- @tparam widget old The widget to remove
-- @tparam widget new The widget to add
-- @treturn boolean If the operation is successful (widget found)
function grid:replace_widget(old, new)
-- check if the new object is a widget

6
lib/wibox/layout/stack.lua
View File

@ -1,5 +1,5 @@
---------------------------------------------------------------------------
-- A stacked layout.
-- Place multiple widgets on top of each other.
--
-- This layout display widgets on top of each other. It can be used to overlay
-- a `wibox.widget.textbox` on top of a `awful.widget.progressbar` or manage
@ -31,7 +31,7 @@ local stack = {mt={}}
--- Remove a widget from the layout.
--
-- @tparam index The widget index to remove
-- @tparam number index The widget index to remove
-- @treturn boolean index If the operation is successful
-- @method remove
-- @interface layout
@ -115,7 +115,7 @@ end
--- Raise a widget at `index` to the top of the stack.
--
-- @method raise
-- @tparam number index the widget index to raise
-- @tparam number index The widget index to raise
function stack:raise(index)
if (not index) or (not self._private.widgets[index]) then return end

2
lib/wibox/widget/background.lua
View File

@ -1,5 +1,5 @@
---------------------------------------------------------------------------
-- This class has been moved to `wibox.container.background`
-- This class has been moved to `wibox.container.background`.
--
-- @author Uli Schlachter
-- @copyright 2010 Uli Schlachter

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

@ -1,4 +1,6 @@
---------------------------------------------------------------------------
-- Base class of every widgets, containers and layouts,
--
-- @author Uli Schlachter
-- @copyright 2010 Uli Schlachter
-- @classmod wibox.widget.base
@ -31,17 +33,17 @@ local base = {}
-- widgets hierarchy. A hierarchy loop is when a widget, or any of its
-- children, contain (directly or indirectly) itself.
-- @property all_children
-- @tparam table children The children.
-- @tparam table all_children The children.
-- @baseclass wibox.widget.base
--- Force a widget height.
-- @property forced_height
-- @tparam number|nil height The height (`nil` for automatic)
-- @tparam number|nil forced_height The height (`nil` for automatic)
-- @baseclass wibox.widget.base
--- Force a widget width.
-- @property forced_width
-- @tparam number|nil width The width (`nil` for automatic)
-- @tparam number|nil forced_width The width (`nil` for automatic)
-- @baseclass wibox.widget.base
--- The widget opacity (transparency).
@ -51,14 +53,14 @@ local base = {}
--- The widget visibility.
-- @property visible
-- @param boolean
-- @tparam[opt=true] boolean visible
-- @baseclass wibox.widget.base
--- The widget buttons.
--
-- The table contains a list of `awful.button` objects.
-- @property buttons
-- @param table
-- @tparam table buttons
-- @see awful.button
-- @baseclass wibox.widget.base
@ -92,7 +94,7 @@ local base = {}
-- @tparam number button The button number.
-- @tparam table mods The modifiers (mod4, mod1 (alt), Control, Shift)
-- @tparam table find_widgets_result The entry from the result of
-- @{wibox.drawable:find_widgets} for the position that the mouse hit.
-- @{wibox:find_widgets} for the position that the mouse hit.
-- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
-- the widget.
-- @tparam widget find_widgets_result.widget The widget being displayed.
@ -123,7 +125,7 @@ local base = {}
-- @tparam number button The button number.
-- @tparam table mods The modifiers (mod4, mod1 (alt), Control, Shift)
-- @tparam table find_widgets_result The entry from the result of
-- @{wibox.drawable:find_widgets} for the position that the mouse hit.
-- @{wibox:find_widgets} for the position that the mouse hit.
-- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
-- the widget.
-- @tparam widget find_widgets_result.widget The widget being displayed.
@ -148,7 +150,7 @@ local base = {}
-- @signal mouse::enter
-- @tparam table self The current object instance itself.
-- @tparam table find_widgets_result The entry from the result of
-- @{wibox.drawable:find_widgets} for the position that the mouse hit.
-- @{wibox:find_widgets} for the position that the mouse hit.
-- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
-- the widget.
-- @tparam widget find_widgets_result.widget The widget being displayed.
@ -173,7 +175,7 @@ local base = {}
-- @signal mouse::leave
-- @tparam table self The current object instance itself.
-- @tparam table find_widgets_result The entry from the result of
-- @{wibox.drawable:find_widgets} for the position that the mouse hit.
-- @{wibox:find_widgets} for the position that the mouse hit.
-- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
-- the widget.
-- @tparam widget find_widgets_result.widget The widget being displayed.

31
lib/wibox/widget/calendar.lua
View File

@ -1,5 +1,5 @@
---------------------------------------------------------------------------
-- A calendar widget.
-- Display a monthly or yearly calendar.
--
-- This module defines two widgets: a month calendar and a year calendar
--
@ -71,7 +71,7 @@ local properties = { "date" , "font" , "spacing" , "week_numbers"
-- A table representing the date {day=[number|nil], month=[number|nil], year=[number]}.
--
-- E.g.. {day=21, month=2, year=2005}, {month=2, year=2005}, {year=2005}
-- @tparam date table Date table.
-- @tparam table date Date table.
-- @tparam number date.year Date year
-- @tparam number|nil date.month Date month
-- @tparam number|nil date.day Date day
@ -80,34 +80,44 @@ local properties = { "date" , "font" , "spacing" , "week_numbers"
--- The calendar font.
--
-- Choose a monospace font for a better rendering.
--
--@DOC_wibox_widget_calendar_font_EXAMPLE@
-- @param[opt="Monospace 10"] string Font of the calendar
--
-- @tparam[opt="Monospace 10"] string font Font of the calendar
-- @property font
-- @usebeautiful beautiful.calendar_font
--- The calendar spacing.
--
-- The spacing between cells in the month.
-- The spacing between months in a year calendar is twice this value.
-- @param[opt=5] number Spacing of the grid
-- @tparam[opt=5] number spacing Spacing of the grid
-- @property spacing
-- @usebeautiful beautiful.calendar_spacing
--- Display the calendar week numbers.
--
--@DOC_wibox_widget_calendar_week_numbers_EXAMPLE@
-- @param[opt=false] boolean Display week numbers
--
-- @tparam[opt=false] boolean week_numbers Display week numbers
-- @property week_numbers
-- @usebeautiful beautiful.calendar_week_numbers
--- Start the week on Sunday.
--
--@DOC_wibox_widget_calendar_start_sunday_EXAMPLE@
-- @param[opt=false] boolean Start the week on Sunday
--
-- @tparam[opt=false] boolean start_sunday Start the week on Sunday
-- @property start_sunday
-- @usebeautiful beautiful.calendar_start_sunday
--- Format the weekdays with three characters instead of two
--
--@DOC_wibox_widget_calendar_long_weekdays_EXAMPLE@
-- @param[opt=false] boolean Use three characters for the weekdays instead of two
--
-- @tparam[opt=false] boolean long_weekdays Use three characters for the weekdays instead of two
-- @property long_weekdays
-- @usebeautiful beautiful.calendar_long_weekdays
--- The widget encapsulating function.
--
@ -119,15 +129,16 @@ local properties = { "date" , "font" , "spacing" , "week_numbers"
-- It is used to add a container to the grid layout and to the cells:
--
--@DOC_wibox_widget_calendar_fn_embed_cell_EXAMPLE@
-- @param function Function to embed the widget depending on its flag
-- @tparam function fn_embed Function to embed the widget depending on its flag
-- @property fn_embed
--- Allow cells to have flexible height
--
--@DOC_wibox_widget_calendar_flex_height_EXAMPLE@
--
-- @param[opt=false] boolean Allow flex height.
-- @tparam[opt=false] boolean flex_height Allow flex height.
-- @property flex_height
-- @usebeautiful beautiful.flex_height
--- Make a textbox
-- @tparam string text Text of the textbox
@ -257,7 +268,7 @@ end
--- Create a grid layout for the year calendar
-- @tparam table props Table of year calendar properties
-- @param date Year to display (number or string)
-- @tparam number|string date Year to display.
-- @treturn widget Grid layout
local function create_year(props, date)
-- Create a grid widget with the 12 months

4
lib/wibox/widget/checkbox.lua
View File

@ -137,7 +137,7 @@ local checkbox = {}
-- If none is set, then the `shape` property will be used.
--@DOC_wibox_widget_checkbox_check_shape_EXAMPLE@
-- @property check_shape
-- @tparam gears.shape shape
-- @tparam gears.shape check_shape
-- @propbeautiful
-- @propemits true false
-- @see gears.shape
@ -254,7 +254,7 @@ end
--- If the checkbox is checked.
-- @property checked
-- @param boolean
-- @tparam[opt=false] boolean checked
for _, prop in ipairs {"border_width", "bg", "border_color", "check_border_color",
"check_border_width", "check_color", "shape", "check_shape", "paddings",

4
lib/wibox/widget/graph.lua
View File

@ -1,5 +1,5 @@
---------------------------------------------------------------------------
--- A graph widget.
--- Display multiple values as a stream of bars.
--
-- The graph goes from left to right. To change this to right to left, use
-- a `wibox.container.mirror` widget. This can also be used to have data
@ -84,7 +84,7 @@ local graph = { mt = {} }
-- @DOC_wibox_widget_graph_stacked_group_disable_EXAMPLE@
--
-- @property group_colors
-- @tparam table colors A table with colors for data groups.
-- @tparam table group_colors A table with colors for data groups.
-- @see gears.color
--- The maximum value the graph should handle.

2
lib/wibox/widget/imagebox.lua
View File

@ -547,7 +547,7 @@ end
-- @DOC_wibox_widget_imagebox_vertical_fit_policy_EXAMPLE@
--
-- @property vertical_fit_policy
-- @tparam[opt="auto"] string horizontal_fit_policy
-- @tparam[opt="auto"] string vertical_fit_policy
-- @propemits true false
-- @see horizontal_fit_policy
-- @see resize

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

@ -1,4 +1,6 @@
---------------------------------------------------------------------------
--- Utility function for working with widgets.
--
-- @author Uli Schlachter
-- @copyright 2010 Uli Schlachter
-- @module wibox.widget

2
lib/wibox/widget/piechart.lua
View File

@ -191,7 +191,7 @@ end
--
--@DOC_wibox_widget_piechart_label_EXAMPLE@
-- @property display_labels
-- @param[opt=true] boolean
-- @tparam[opt=true] boolean display_labels
--- The pie elements border width.
--

32
lib/wibox/widget/progressbar.lua
View File

@ -54,7 +54,7 @@ local progressbar = { mt = {} }
-- @DOC_wibox_widget_progressbar_border_color_EXAMPLE@
--
-- @property border_color
-- @tparam gears.color color The border color to set.
-- @tparam gears.color border_color The border color to set.
-- @propemits true false
-- @propbeautiful
-- @see gears.color
@ -75,7 +75,7 @@ local progressbar = { mt = {} }
-- @DOC_wibox_widget_progressbar_bar_border_color_EXAMPLE@
--
-- @property bar_border_color
-- @tparam gears.color color The border color to set.
-- @tparam gears.color bar_border_color The border color to set.
-- @propemits true false
-- @propbeautiful
-- @see gears.color
@ -104,7 +104,7 @@ local progressbar = { mt = {} }
-- @DOC_wibox_widget_progressbar_background_color_EXAMPLE@
--
-- @property background_color
-- @tparam gears.color color The progressbar background color.
-- @tparam gears.color background_color The progressbar background color.
-- @propemits true false
-- @usebeautiful beautiful.progressbar_bg
-- @see gears.color
@ -114,7 +114,7 @@ local progressbar = { mt = {} }
--@DOC_wibox_widget_progressbar_bar_shape_EXAMPLE@
--
-- @property bar_shape
-- @tparam[opt=gears.shape.rectangle] gears.shape shape
-- @tparam[opt=gears.shape.rectangle] gears.shape bar_shape
-- @propemits true false
-- @propbeautiful
-- @see gears.shape
@ -243,7 +243,7 @@ local progressbar = { mt = {} }
-- @DOC_wibox_widget_progressbar_margins1_EXAMPLE@
--
-- @property margins
-- @tparam[opt=0] (table|number|nil) margins A table for each side or a number
-- @tparam[opt=0] table|number|nil margins A table for each side or a number
-- @tparam[opt=0] number margins.top
-- @tparam[opt=0] number margins.bottom
-- @tparam[opt=0] number margins.left
@ -268,7 +268,7 @@ local progressbar = { mt = {} }
-- @DOC_wibox_widget_progressbar_paddings1_EXAMPLE@
--
-- @property paddings
-- @tparam[opt=0] (table|number|nil) padding A table for each side or a number
-- @tparam[opt=0] (table|number|nil) paddings A table for each side or a number
-- @tparam[opt=0] number paddings.top
-- @tparam[opt=0] number paddings.bottom
-- @tparam[opt=0] number paddings.left
@ -591,8 +591,24 @@ end
--
-- @tparam table args Standard widget() arguments. You should add width and
-- height constructor parameters to set progressbar geometry.
-- @tparam number args.width The width.
-- @tparam number args.height The height.
-- @tparam[opt] number args.width The width.
-- @tparam[opt] number args.height The height.
-- @tparam[opt] gears.color args.border_color The progressbar border color.
-- @tparam[opt] number args.border_width The progressbar border width.
-- @tparam[opt] gears.color args.bar_border_color The progressbar inner border color.
-- @tparam[opt] number args.bar_border_width The progressbar inner border width.
-- @tparam[opt] gears.color args.color The progressbar foreground color.
-- @tparam[opt] gears.color args.background_color The progressbar background color.
-- @tparam[opt] gears.shape args.bar_shape The progressbar inner shape.
-- @tparam[opt] gears.shape args.shape The progressbar shape.
-- @tparam[opt] boolean args.clip Force the inner part (the bar) to fit in the background shape.
-- @tparam[opt] boolean args.ticks The progressbar to draw ticks.
-- @tparam[opt] number args.ticks_gap The progressbar ticks gap.
-- @tparam[opt] number args.ticks_size The progressbar ticks size.
-- @tparam[opt] number args.max_value The maximum value the progressbar should handle.
-- @tparam[opt] table|number args.margins The progressbar margins.
-- @tparam[opt] table|number args.paddings The progressbar padding.
-- @tparam[opt] number args.value Set the progressbar value.
-- @treturn wibox.widget.progressbar A progressbar widget.
-- @constructorfct wibox.widget.progressbar
function progressbar.new(args)

11
lib/wibox/widget/separator.lua
View File

@ -68,7 +68,7 @@ local separator = {}
--- The relative percentage covered by the bar.
--
-- @property span_ratio
-- @tparam[opt=1] number A number between 0 and 1.
-- @tparam[opt=1] number span_ratio A number between 0 and 1.
-- @propbeautiful
-- @propemits true false
@ -112,7 +112,7 @@ local separator = {}
--- The relative percentage covered by the bar.
-- @beautiful beautiful.separator_span_ratio
-- @tparam[opt=1] number A number between 0 and 1.
-- @tparam[opt=1] number separator_span_ratio A number between 0 and 1.
--- The separator's color.
-- @beautiful beautiful.separator_color
@ -203,6 +203,13 @@ end
--- Create a new separator.
-- @constructorfct wibox.widget.separator
-- @tparam table args The arguments (all properties are available).
-- @tparam[opt] string args.orientation The separator's orientation.
-- @tparam[opt] number args.thickness The separator's thickness.
-- @tparam[opt] function args.shape The separator's shape.
-- @tparam[opt] number args.span_ratio The relative percentage covered by the bar.
-- @tparam[opt] color args.color The separator's color.
-- @tparam[opt] color args.border_color The separator's border color.
-- @tparam[opt] number args.border_width The separator's border width.
local function new(args)
local ret = base.make_widget(nil, nil, {

30
lib/wibox/widget/slider.lua
View File

@ -30,7 +30,7 @@ local slider = {mt={}}
--@DOC_wibox_widget_slider_handle_shape_EXAMPLE@
--
-- @property handle_shape
-- @tparam[opt=gears shape rectangle] gears.shape shape
-- @tparam[opt=gears shape rectangle] gears.shape handle_shape
-- @propemits true false
-- @propbeautiful
-- @see gears.shape
@ -49,7 +49,7 @@ local slider = {mt={}}
--@DOC_wibox_widget_slider_handle_margins_EXAMPLE@
--
-- @property handle_margins
-- @tparam[opt={}] table margins
-- @tparam[opt={}] table handle_margins
-- @tparam[opt=0] number margins.left
-- @tparam[opt=0] number margins.right
-- @tparam[opt=0] number margins.top
@ -86,7 +86,7 @@ local slider = {mt={}}
--@DOC_wibox_widget_slider_bar_shape_EXAMPLE@
--
-- @property bar_shape
-- @tparam[opt=gears shape rectangle] gears.shape shape
-- @tparam[opt=gears shape rectangle] gears.shape bar_shape
-- @propemits true false
-- @propbeautiful
-- @see gears.shape
@ -124,7 +124,7 @@ local slider = {mt={}}
--@DOC_wibox_widget_slider_bar_margins_EXAMPLE@
--
-- @property bar_margins
-- @tparam[opt={}] table margins
-- @tparam[opt={}] table bar_margins
-- @tparam[opt=0] number margins.left
-- @tparam[opt=0] number margins.right
-- @tparam[opt=0] number margins.top
@ -136,6 +136,7 @@ local slider = {mt={}}
-- @property bar_border_width
-- @tparam[opt=0] number bar_border_width
-- @propemits true false
-- @propbeautiful
--- The bar (background) border_color.
--
@ -148,8 +149,6 @@ local slider = {mt={}}
--- The slider value.
--
-- **Signal:** *property::value* notify the value is changed.
--
--@DOC_wibox_widget_slider_value_EXAMPLE@
--
-- @property value
@ -521,8 +520,25 @@ local function mouse_press(self, x, y, button_id, _, geo)
end
--- Create a slider widget.
-- @tparam[opt={}] table args
--
-- @constructorfct wibox.widget.slider
-- @tparam[opt={}] table args
-- @tparam[opt] gears.shape args.handle_shape The slider handle shape.
-- @tparam[opt] color args.handle_color The slider handle color.
-- @tparam[opt] table args.handle_margins The slider handle margins.
-- @tparam[opt] number args.handle_width The slider handle width.
-- @tparam[opt] color args.handle_border_color The handle border_color.
-- @tparam[opt] number args.handle_border_width The handle border width.
-- @tparam[opt] gears.shape args.bar_shape The bar (background) shape.
-- @tparam[opt] number args.bar_height The bar (background) height.
-- @tparam[opt] color args.bar_color The bar (background) color.
-- @tparam[opt] color args.bar_active_color The bar (active) color.
-- @tparam[opt] table args.bar_margins The bar (background) margins.
-- @tparam[opt] number args.bar_border_width The bar (background) border width.
-- @tparam[opt] color args.bar_border_color The bar (background) border_color.
-- @tparam[opt] number args.value The slider value.
-- @tparam[opt] number args.minimum The slider minimum value.
-- @tparam[opt] number args.maximum The slider maximum value.
local function new(args)
local ret = base.make_widget(nil, nil, {
enable_properties = true,

24
lib/wibox/widget/systray.lua
View File

@ -1,4 +1,6 @@
---------------------------------------------------------------------------
-- Container for the various system tray icons.
--
-- @author Uli Schlachter
-- @copyright 2010 Uli Schlachter
-- @widgetmod wibox.widget.systray
@ -27,20 +29,23 @@ local display_on_screen = "primary"
--- The systray background color.
--
-- Please note that only solid+opaque colors are supported. It does **not**
-- support gradients, patterns or transparent colors.
--
-- @beautiful beautiful.bg_systray
-- @param string The color (string like "#ff0000" only)
-- @tparam string bg_systray The color (string like "#ff0000" only)
--- The maximum number of rows for systray icons. Icons will fill the
-- current column (orthogonally to the systray direction) before
-- filling the next column.
--
-- @beautiful beautiful.systray_max_rows
-- @tparam[opt=1] integer The positive number of rows
-- @tparam[opt=1] integer systray_max_rows The positive number of rows.
--- The systray icon spacing.
--
-- @beautiful beautiful.systray_icon_spacing
-- @tparam[opt=0] integer The icon spacing
-- @tparam[opt=0] integer systray_icon_spacing The icon spacing
local function should_display_on(s)
if display_on_screen == "primary" then
@ -143,7 +148,7 @@ end
-- available space. Otherwise, any single icon has a size of `size`x`size`.
--
-- @property base_size
-- @tparam integer|nil size The base size
-- @tparam integer|nil base_size The base size
-- @propemits true false
function systray:set_base_size(size)
@ -157,7 +162,7 @@ end
--- Decide between horizontal or vertical display.
--
-- @property horizontal
-- @tparam boolean horiz Use horizontal mode?
-- @tparam boolean horizontal Use horizontal mode?
-- @propemits true false
function systray:set_horizontal(horiz)
@ -171,7 +176,7 @@ end
--- Should the systray icons be displayed in reverse order?
--
-- @property reverse
-- @tparam boolean rev Display in reverse order.
-- @tparam boolean reverse Display in reverse order.
-- @propemits true false
function systray:set_reverse(rev)
@ -189,7 +194,7 @@ end
-- visible on the primary screen. The default value is "primary".
--
-- @property screen
-- @tparam screen|"primary" s The screen to display on.
-- @tparam screen|"primary" screen The screen to display on.
-- @propemits true false
function systray:set_screen(s)
@ -204,9 +209,12 @@ end
--
-- Note that this widget can only exist once.
--
-- @tparam boolean revers Show in the opposite direction
-- @tparam boolean reverse Show in the opposite direction
-- @treturn table The new `systray` widget
-- @constructorfct wibox.widget.systray
-- @usebeautiful beautiful.bg_systray
-- @usebeautiful beautiful.systray_icon_spacing
-- @usebeautiful beautiful.systray_max_rows
local function new(revers)
local ret = wbase.make_widget(nil, nil, {enable_properties = true})

Some files were not shown because too many files have changed in this diff Show More