From 5e720c974491d6f0ae39f1490c720efeaa038266 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage-Vallee Date: Mon, 30 Dec 2019 15:17:23 -0800 Subject: [PATCH] doc: Major client documentation backfill. This commit mostly rewrite the client documentation and pay the technical debt accumulated over the years. Most of the client documentation was still one-liners from the luadoc era. It now has all the new tags, type. It also has actual description of what the properties do beyond the name. --- lib/awful/client.lua | 242 +++++++++------ objects/client.c | 698 +++++++++++++++++++++++++++++-------------- 2 files changed, 618 insertions(+), 322 deletions(-) diff --git a/lib/awful/client.lua b/lib/awful/client.lua index ae74a9f4..246b7f24 100644 --- a/lib/awful/client.lua +++ b/lib/awful/client.lua @@ -74,7 +74,7 @@ client.focus = require("awful.client.focus") --- When applying the placement, honor the screen padding. -- @clientruleproperty honor_padding --- @param[opt=true] boolean +-- @tparam[opt=true] boolean honor_padding -- @see awful.placement --- When applying the placement, honor the screen work area. @@ -82,7 +82,7 @@ client.focus = require("awful.client.focus") -- The workarea is the part of the screen that excludes the bars and docks. -- -- @clientruleproperty honor_workarea --- @param[opt=true] boolean +-- @tparam[opt=true] boolean honor_workarea -- @see awful.placement --- The client default tag. @@ -90,7 +90,7 @@ client.focus = require("awful.client.focus") -- @DOC_sequences_client_rules_tags_EXAMPLE@ -- -- @clientruleproperty tag --- @param tag +-- @tparam tag tag -- @see tag -- @see new_tag -- @see tags @@ -102,7 +102,7 @@ client.focus = require("awful.client.focus") -- issues. -- -- @clientruleproperty tags --- @param[opt={tag}] table +-- @tparam[opt={tag}] table tags -- @see tag -- @see new_tag -- @see tags @@ -130,7 +130,7 @@ client.focus = require("awful.client.focus") -- @DOC_sequences_client_rules_switch_to_tags_EXAMPLE@ -- -- @clientruleproperty switch_to_tags --- @param[opt=false] boolean +-- @tparam[opt=false] boolean switch_to_tags -- @see tag.selected --- Define if the client should grab focus by default. @@ -138,11 +138,11 @@ client.focus = require("awful.client.focus") -- The `request::activate` context for this call is `rules`. -- -- @clientruleproperty focus --- @param[opt=false] boolean +-- @tparam[opt=false] boolean focus --- Should this client have a titlebar by default. -- @clientruleproperty titlebars_enabled --- @param[opt=false] boolean +-- @tparam[opt=false] boolean titlebars_enabled -- @see awful.titlebar --- A function to call when this client is ready. @@ -177,6 +177,8 @@ end -- tag as arguments. -- @request client activate client.jumpto granted When a client is activated -- because `c:jump_to()` is called. +-- @see activate +-- @see active function client.object.jump_to(self, merge) local s = get_screen(screen.focused()) -- focus the screen @@ -251,7 +253,7 @@ end -- @tparam int i The index. Use 1 to get the next, -1 to get the previous. -- @client[opt] sel The client. -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom) --- @return A client, or nil if no client is available. +-- @treturn[opt] client|nil A client, or nil if no client is available. -- -- @usage -- focus the next window in the index -- awful.client.next(1) @@ -282,10 +284,16 @@ function client.next(i, sel, stacked) end --- Swap a client with another client in the given direction. +-- -- @staticfct awful.client.swap.bydirection -- @tparam string dir The direction, can be either "up", "down", "left" or "right". -- @client[opt=focused] c The client. -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom) +-- @see swap +-- @see swapped +-- @see awful.client.swap.global_bydirection +-- @see awful.client.swap.byidx +-- @see awful.client.cycle function client.swap.bydirection(dir, c, stacked) local sel = c or capi.client.focus if sel then @@ -304,12 +312,18 @@ function client.swap.bydirection(dir, c, stacked) end --- Swap a client with another client in the given direction. +-- -- Swaps across screens. -- @staticfct awful.client.swap.global_bydirection --- @param dir The direction, can be either "up", "down", "left" or "right". +-- @tparam string dir The direction, can be either "up", "down", "left" or "right". -- @client[opt] sel The client. -- @request client activate client.swap.global_bydirection granted When a client -- could be activated because `awful.client.swap.global_bydirection` was called. +-- @see swap +-- @see swapped +-- @see awful.client.swap.bydirection +-- @see awful.client.swap.byidx +-- @see awful.client.cycle function client.swap.global_bydirection(dir, sel) sel = sel or capi.client.focus local scr = get_screen(sel and sel.screen or screen.focused()) @@ -340,9 +354,15 @@ function client.swap.global_bydirection(dir, sel) end --- Swap a client by its relative index. +-- -- @staticfct awful.client.swap.byidx --- @param i The index. +-- @tparam integer i The index. -- @client[opt] c The client, otherwise focused one is used. +-- @see swap +-- @see swapped +-- @see awful.client.swap.bydirection +-- @see awful.client.swap.global_bydirection +-- @see awful.client.cycle function client.swap.byidx(i, c) local sel = c or capi.client.focus local target = client.next(i, sel) @@ -351,12 +371,20 @@ function client.swap.byidx(i, c) end end ---- Cycle clients. +--- Cycle through the clients to change the focus. +-- +-- This will swap the client from one position to the next +-- in the layout. -- -- @staticfct awful.client.cycle --- @param clockwise True to cycle clients clockwise. --- @param[opt] s The screen where to cycle clients. +-- @tparam boolean clockwise True to cycle clients clockwise. +-- @tparam[opt] screen s The screen where to cycle clients. -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom) +-- @see swap +-- @see swapped +-- @see awful.client.swap.bydirection +-- @see awful.client.swap.global_bydirection +-- @see awful.client.swap.byidx function client.cycle(clockwise, s, stacked) s = s or screen.focused() local cls = client.visible(s, stacked) @@ -402,7 +430,7 @@ end -- -- @legacylayout awful.client.getmaster -- @screen_or_idx[opt=awful.screen.focused()] s The screen. --- @return The master window. +-- @treturn client The master client. function client.getmaster(s) s = s or screen.focused() return client.visible(s)[1] @@ -431,10 +459,10 @@ end --- Move/resize a client relative to current coordinates. -- @deprecated awful.client.moveresize --- @param x The relative x coordinate. --- @param y The relative y coordinate. --- @param w The relative width. --- @param h The relative height. +-- @tparam integer x The relative x coordinate. +-- @tparam integer y The relative y coordinate. +-- @tparam integer w The relative width. +-- @tparam integer h The relative height. -- @client[opt] c The client, otherwise focused one is used. -- @see client.relative_move function client.moveresize(x, y, w, h, c) @@ -460,7 +488,7 @@ end --- Move a client to a tag. -- @deprecated awful.client.movetotag --- @param target The tag to move the client to. +-- @tparam tag target The tag to move the client to. -- @client[opt] c The client to move, otherwise the focused one is used. -- @see client.move_to_tag function client.movetotag(target, c) @@ -469,10 +497,12 @@ function client.movetotag(target, c) end --- Move a client to a tag. +-- -- @method move_to_tag -- @tparam tag target The tag to move the client to. -- @request client activate client.movetotag granted When a client could be -- activated because `c:move_to_tag()` was called. +-- @see tags function client.object.move_to_tag(self, target) local s = target.screen if self and s then @@ -486,18 +516,22 @@ function client.object.move_to_tag(self, target) end --- Toggle a tag on a client. +-- -- @deprecated awful.client.toggletag --- @param target The tag to toggle. +-- @tparam tag target The tag to toggle. -- @client[opt] c The client to toggle, otherwise the focused one is used. -- @see client.toggle_tag +-- @see tags function client.toggletag(target, c) gdebug.deprecate("Use c:toggle_tag(target) instead of awful.client.toggletag", {deprecated_in=4}) client.object.toggle_tag(c or capi.client.focus, target) end --- Toggle a tag on a client. +-- -- @method toggle_tag -- @tparam tag target The tag to move the client to. +-- @see tags function client.object.toggle_tag(self, target) -- Check that tag and client screen are identical if self and get_screen(self.screen) == get_screen(target.screen) then @@ -523,7 +557,7 @@ end --- Move a client to a screen. Default is next screen, cycling. -- @deprecated awful.client.movetoscreen -- @client c The client to move. --- @param s The screen, default to current + 1. +-- @tparam screen s The screen, default to current + 1. -- @see screen -- @see client.move_to_screen function client.movetoscreen(c, s) @@ -590,14 +624,11 @@ end --- If a client is marked or not. -- --- **Signal:** --- --- * *marked* (for legacy reasons, use `property::marked`) --- * *unmarked* (for legacy reasons, use `property::marked`) --- * *property::marked* --- -- @property marked --- @param boolean +-- @tparam boolean marked +-- @emits marked (for legacy reasons, use `property::marked`) +-- @emits unmarker (for legacy reasons, use `property::marked`) +-- @emits property::marked --- The border color when the client is focused. -- @@ -664,7 +695,7 @@ end --- Return the marked clients and empty the marked table. -- @deprecated awful.client.getmarked --- @return A table with all marked clients. +-- @treturn table A table with all marked clients. function client.getmarked() local copy = gtable.clone(client.data.marked, false) @@ -682,7 +713,7 @@ end -- Floating client are not handled by tiling layouts. -- @deprecated awful.client.floating.set -- @client c A client. --- @param s True or false. +-- @tparam boolean s True or false. function client.floating.set(c, s) gdebug.deprecate("Use c.floating = true instead of awful.client.floating.set", {deprecated_in=4}) client.object.set_floating(c, s) @@ -691,7 +722,7 @@ end -- Set a client floating state, overriding auto-detection. -- Floating client are not handled by tiling layouts. -- @client c A client. --- @param s True or false. +-- @tparam boolan s True or false. function client.object.set_floating(c, s) c = c or capi.client.focus if c and client.property.get(c, "floating") ~= s then @@ -741,13 +772,10 @@ end --- Return if a client has a fixed size or not. -- --- **Signal:** --- --- * *property::is_fixed* --- -- This property is read only. -- @property is_fixed --- @param boolean The fixed size state +-- @tparam[opt=false] boolean is_fixed The fixed size state +-- @propemits false false -- @see size_hints -- @see size_hints_honor @@ -772,7 +800,7 @@ end -- -- This property is read only. -- @property immobilized_horizontal --- @param boolean The immobilized state +-- @tparam[opt=false] boolean immobilized_horizontal The immobilized state -- @see maximized -- @see maximized_horizontal -- @see fullscreen @@ -788,7 +816,7 @@ end -- -- This property is read only. -- @property immobilized_vertical --- @param boolean The immobilized state +-- @tparam[opt=false] boolean immobilized_vertical The immobilized state -- @see maximized -- @see maximized_vertical -- @see fullscreen @@ -801,7 +829,7 @@ end -- @client c A client. -- @see floating -- @deprecated awful.client.floating.get --- @return True or false. Note that some windows might be floating even if you +-- @treturn boolean True or false. Note that some windows might be floating even if you -- did not set them manually. For example, windows with a type different than -- normal. function client.floating.get(c) @@ -817,10 +845,6 @@ end -- did not set them manually. For example, windows with a type different than -- normal. -- --- **Signal:** --- --- * *property::floating* --- -- @property floating -- @tparam boolean floating The floating state. -- @request client border floating granted When a border update is required @@ -829,6 +853,7 @@ end -- floating. -- @request client border inactive granted When a client stop being active and -- is not floating. +-- @propemits false false function client.object.get_floating(c) c = c or capi.client.focus @@ -901,39 +926,43 @@ end --- The x coordinates. -- --- **Signal:** --- --- * *property::x* --- -- @property x --- @param integer +-- @tparam integer x +-- @emits property::geometry +-- @emitstparam property::geometry table geo The +-- geometry (with `x`, `y`, `width`, `height`). +-- @emits property::x +-- @emits property::position --- The y coordinates. -- --- **Signal:** --- --- * *property::y* --- -- @property y --- @param integer +-- @tparam integer y +-- @emits property::geometry +-- @emitstparam property::geometry table geo The +-- geometry (with `x`, `y`, `width`, `height`). +-- @emits property::y +-- @emits property::position --- The width of the client. -- --- **Signal:** --- --- * *property::width* --- -- @property width --- @param width +-- @tparam integer width +-- @emits property::geometry +-- @emitstparam property::geometry table geo The +-- geometry (with `x`, `y`, `width`, `height`). +-- @emits property::width +-- @emits property::size --- The height of the client. -- --- **Signal:** --- --- * *property::height* --- -- @property height --- @param height +-- @tparam integer height +-- @emits property::geometry +-- @emitstparam property::geometry table geo The +-- geometry (with `x`, `y`, `width`, `height`). +-- @emits property::height +-- @emits property::size -- Add the geometry helpers to match the wibox API for _, v in ipairs {"x", "y", "width", "height"} do @@ -949,8 +978,8 @@ end --- Restore (=unminimize) a random client. -- @staticfct awful.client.restore --- @param s The screen to use. --- @return The restored client if some client was restored, otherwise nil. +-- @tparam screen s The screen to use. +-- @treturn client The restored client if some client was restored, otherwise nil. function client.restore(s) s = s or screen.focused() local cls = capi.client.get(s) @@ -970,8 +999,8 @@ function client.restore(s) end --- Normalize a set of numbers to 1. --- @param set the set of numbers to normalize --- @param num the number of numbers to normalize +-- @tparam table set the set of numbers to normalize. +-- @tparam number num the number of numbers to normalize. local function normalize(set, num) num = num or #set local total = 0 @@ -998,9 +1027,9 @@ end -- -- @legacylayout awful.client.idx -- @client c the client --- @return col the column number --- @return idx index of the client in the column --- @return num the number of visible clients in the column +-- @treturn integer col The column number. +-- @treturn integer idx Index of the client in the column. +-- @treturn integer num The number of visible clients in the column. function client.idx(c) c = c or capi.client.focus if not c then return end @@ -1058,8 +1087,9 @@ end --- Set the window factor of a client -- -- @legacylayout awful.client.setwfact --- @param wfact the window factor value +-- @tparam number wfact the window factor value -- @client c the client +-- @emits property::windowfact function client.setwfact(wfact, c) -- get the currently selected window c = c or capi.client.focus @@ -1114,7 +1144,8 @@ end -- @tparam number add Amount to increase/decrease the client's window factor. -- Should be between `-current_window_factor` and something close to -- infinite. The normalisation then ensures that the sum of all factors is 1. --- @client c the client +-- @client c the client. +-- @emits property::windowfact function client.incwfact(add, c) c = c or capi.client.focus if not c then return end @@ -1152,12 +1183,9 @@ end -- Clients with a type of "utility", "toolbar" or "dock" are dockable by -- default. -- --- **Signal:** --- --- * *property::dockable* --- -- @property dockable --- @param boolean The dockable state +-- @tparam boolean dockable The dockable state +-- @propemits false false function client.object.get_dockable(c) local value = client.property.get(c, "dockable") @@ -1180,7 +1208,7 @@ end -- to the edge of the workarea. -- -- @client c A client. --- @param value True or false. +-- @tparam boolean value True or false. -- @deprecated awful.client.dockable.set function client.dockable.set(c, value) gdebug.deprecate("Use c.dockable = value instead of awful.client.dockable.set", {deprecated_in=4}) @@ -1193,12 +1221,10 @@ end -- various ways. This property uses the motif MWM_DECOR_TITLE hint and -- interprets it as the client (not) wanting a titlebar. -- --- **Signal:** --- --- * *property::requests_no_titlebar* --- -- @property requests_no_titlebar --- @param boolean Whether the client requests not to get a titlebar +-- @tparam boolean requests_no_titlebar Whether the client +-- requests not to get a titlebar. +-- @propemits false false function client.object.get_requests_no_titlebar(c) local hints = c.motif_wm_hints @@ -1224,8 +1250,8 @@ end) -- This method is deprecated. It is now possible to use `c.value` directly. -- -- @client c The client. --- @param prop The property name. --- @return The property. +-- @tparam string prop The property name. +-- @return The property value. -- @deprecated awful.client.property.get function client.property.get(c, prop) if not c._private._persistent_properties_loaded then @@ -1248,8 +1274,8 @@ end -- directly. -- -- @client c The client. --- @param prop The property name. --- @param value The value. +-- @tparam string prop The property name. +-- @param value The property value. -- @deprecated awful.client.property.set function client.property.set(c, prop, value) if not c._private.awful_client_properties then @@ -1267,8 +1293,8 @@ end --- Set a client property to be persistent across restarts (via X properties). -- -- @staticfct awful.client.property.persist --- @param prop The property name. --- @param kind The type (used for register_xproperty). +-- @tparam string prop The property name. +-- @tparam string kind The type (used for register_xproperty). -- One of "string", "number" or "boolean". function client.property.persist(prop, kind) local xprop = "awful.client.property." .. prop @@ -1288,10 +1314,10 @@ end -- Starting from the client in focus or the given index, all clients that match -- a given criteria. -- --- @param filter a function that returns true to indicate a positive match --- @param start what index to start iterating from. Defaults to using the +-- @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. --- @param s which screen to use. nil means all screens. +-- @tparam screen s which screen to use. nil means all screens. -- -- @staticfct awful.client.iterate -- @usage -- un-minimize all urxvt instances @@ -1313,8 +1339,8 @@ end -- If multiple clients match the given condition then the next one is -- focussed. -- --- @param cmd the command to execute --- @param 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. @@ -1354,7 +1380,7 @@ end -- @client c The client. -- @tparam function matcher A function that should return true, if -- a matching parent client is found. --- @treturn client.client|nil The matching parent client or nil. +-- @treturn client|nil The matching parent client or nil. function client.get_transient_for_matching(c, matcher) gdebug.deprecate("Use c:get_transient_for_matching(matcher) instead of".. "awful.client.get_transient_for_matching", {deprecated_in=4}) @@ -1366,7 +1392,10 @@ end -- @method get_transient_for_matching -- @tparam function matcher A function that should return true, if -- a matching parent client is found. --- @treturn client.client|nil The matching parent client or nil. +-- @treturn client|nil The matching parent client or nil. +-- @see transient_for +-- @see modal +-- @see is_transient_for function client.object.get_transient_for_matching(self, matcher) local tc = self.transient_for while tc do @@ -1379,11 +1408,12 @@ function client.object.get_transient_for_matching(self, matcher) end --- Is a client transient for another one? +-- -- @deprecated awful.client.is_transient_for -- @see client.is_transient_for -- @client c The child client (having transient_for). -- @client c2 The parent client to check. --- @treturn client.client|nil The parent client or nil. +-- @treturn client|nil The parent client or nil. function client.is_transient_for(c, c2) gdebug.deprecate("Use c:is_transient_for(c2) instead of".. "awful.client.is_transient_for", {deprecated_in=4}) @@ -1391,9 +1421,20 @@ function client.is_transient_for(c, c2) end --- Is a client transient for another one? +-- +-- This will traverse the chain of `transient_for` client +-- until a client which is transient for `c2` is found. If +-- one is found, it will be returned. If none is found, then +-- `nil` will be returned. Most of the time there is no +-- long chain of clients, so `self` or `nil` are the most +-- likely return values. +-- -- @method is_transient_for -- @client c2 The parent client to check. --- @treturn client.client|nil The parent client or nil. +-- @treturn client|nil The parent client or nil. +-- @see transient_for +-- @see modal +-- @see client.get_transient_for_matching function client.object.is_transient_for(self, c2) local tc = self while tc.transient_for do @@ -1418,12 +1459,15 @@ object.properties._legacy_accessors(client, "keys", "_keys", true, function(new_ end, true, true, "keybinding") --- Set the client shape. +-- -- @property shape -- @tparam gears.shape A gears.shape compatible function. +-- @propemits true false -- @see gears.shape function client.object.set_shape(self, shape) client.property.set(self, "_shape", shape) set_shape(self) + self:emit_signal("property::shape", shape) end -- Proxy those properties to decorate their accessors with an extra flag to @@ -1643,7 +1687,7 @@ capi.client.connect_signal("request::manage", function (c) require("awful.placement").no_offscreen(c) end - if awesome.startup then + if capi.awesome.startup then client.focus.history.add(c) end diff --git a/objects/client.c b/objects/client.c index 7856eb63..7bd1cd35 100644 --- a/objects/client.c +++ b/objects/client.c @@ -140,6 +140,7 @@ * initialized, but before clients are added. * * @signal scanning + * @classsignal */ /** AwesomeWM is done scanning for clients. @@ -147,14 +148,17 @@ * This is emitted before the `startup` signal and after the `scanning` signal. * * @signal scanned + * @classsignal */ /** When a client gains focus. * @signal focus + * @classsignal */ /** Before manage, after unmanage, and when clients swap. * @signal list + * @classsignal */ /** When 2 clients are swapped @@ -179,6 +183,7 @@ * with the other `request::` signals). * @request client border added granted When a new client needs a its initial * border settings. + * @classsignal */ /** When a client is going away. @@ -198,6 +203,7 @@ * @tparam string context Why was the client unmanaged. * @tparam table hints More metadata (currently empty, it exists for compliance * with the other `request::` signals). + * @classsignal */ /** Use `request::manage`. @@ -208,30 +214,31 @@ * @deprecatedsignal unmanage */ -/** +/** When a mouse button is pressed in a client. * @signal button::press */ -/** +/** When a mouse button is released in a client. + * * @signal button::release */ -/** +/** When the mouse enters a client. + * * @signal mouse::enter */ -/** +/** When the mouse leaves a client. + * * @signal mouse::leave */ /** + * When the mouse moves within a client. + * * @signal mouse::move */ -/** - * @signal property::window - */ - /** When a client should get activated (focused and/or raised). * * **Contexts are:** @@ -267,6 +274,7 @@ * @tparam[opt] table hints A table with additional hints: * @tparam[opt=false] boolean hints.raise should the client be raised? * @request client activate ewmh granted When the client asks to be activated. + * @classsignal */ /** When an event could lead to the client being activated. @@ -286,6 +294,7 @@ * @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 raised? + * @classsignal * */ @@ -301,14 +310,19 @@ * (programmatically) asks for the maximization to be changed. * @request client geometry client_maximize_vertical granted When a client * (programmatically) asks for the maximization to be changed. + * @classsignal */ -/** +/** When the tag requests to be moved to a tag or needs a new tag. + * * @signal request::tag + * @classsignal */ -/** +/** When the client requests to become urgent. + * * @signal request::urgent + * @classsignal */ /** Emitted during startup to gather the default client mousebindings. @@ -363,151 +377,231 @@ */ /** + * Emitted when the client is raised within its layer. + * * @signal raised + * @see below + * @see above + * @see ontop + * @see raise + * @see lower + * @see lowered */ -/** +/** Emitted when the client is lowered within its layer. + * * @signal lowered + * @see below + * @see above + * @see ontop + * @see raise + * @see lower + * @see raised */ /** * The focused `client` or nil (in case there is none). * + * It is not recommanded to set the focused client using + * this property. Please use `c:activate{}` instead of + * `client.focus = c`. Setting the focus directly bypasses + * all the filters and emits fewer signals, which tend to + * cause unwanted side effects and make it harder to alter + * the code behavior in the future. It usually takes *more* + * code to use this rather than `:activate{}` because all + * the boilerplate code (such as `c:raise()`) needs to be + * added everywhere. + * + * The main use case for this field is to check *when* there + * is an active client. + * + * if client.focus ~= nil then + * -- do something + * end + * + * If you want to check if a client is active, use: + * + * if c.active then + * -- do something + * end + * * @tfield client focus + * @see active + * @see activate + * @see request::activate */ /** * The X window id. * - * **Signal:** - * - * * *property::window* + * This is rarely useful, but some DBus protocols will + * have this ID in their API, so it can be useful when + * writing AwesomeWM bindings for them. * * @property window - * @param string + * @tparam integer window + * @propemits false false */ /** * The client title. * - * **Signal:** - * - * * *property::name* + * This is the text which will be shown in the `awful.widget.tasklist` + * and the `awful.titlebar`. * * @property name - * @param string + * @tparam string name + * @propemits false false + * @see awful.titlebar + * @see awful.widget.tasklist */ /** * True if the client does not want to be in taskbar. * - * **Signal:** + * Some clients, like docked bars or some `sticky` clients + * such as wallpaper sensors like Conky have no value in + * the `awful.widget.tasklist` and should not be shown there. * - * * *property::skip\_taskbar* + * The default value of this property reflects the value of the + * `_NET_WM_STATE_SKIP_TASKBAR` X11 protocol xproperty. * * @property skip_taskbar - * @param boolean + * @tparam[opt=false] boolean skip_taskbar + * @propemits false false + * @see sticky */ +//TODO v5: Rename to skip_tasklist? + /** * The window type. * + * This is useful in, among other places, the `ruled.client` rules to apply + * different properties depending on the client types. It is also used + * throughout the API to alter the client (and `wibox`) behavior depending on + * the `type`. For example, clients with the `dock` type are placed on the side + * of the screen while other like `combo` are totally ignored and never + * considered `client`s in the first place. + * * Valid types are: * - * * **desktop**: The root client, it cannot be moved or resized. - * * **dock**: A client attached to the side of the screen. - * * **splash**: A client, usually without titlebar shown when an application starts. - * * **dialog**: A dialog, see `transient_for`. - * * **menu**: A context menu. - * * **toolbar**: A floating toolbar. - * * **utility**: - * * **dropdown_menu**: A context menu attached to a parent position. - * * **popup_menu**: A context menu. - * * **notification**: A notification popup. - * * **combo**: A combobox list menu. - * * **dnd**: A drag and drop indicator. - * * **normal**: A normal application main window. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
NameDescription
desktopThe root client, it cannot be moved or resized.
dockA client attached to the side of the screen.
splashA client, usually without titlebar shown when an application starts.
dialogA dialog, see `transient_for`.
menuA context menu.
toolbarA floating toolbar.
utility
dropdown_menuA context menu attached to a parent position.
popup_menuA context menu.
notificationA notification popup.
comboA combobox list menu.
dndA drag and drop indicator.
normalA normal application main window.
* * More information can be found [here](https://specifications.freedesktop.org/wm-spec/wm-spec-latest.html#idm140200472629520) * - * **Signal:** - * - * * *property::type* - * * @property type - * @param string + * @tparam string type + * @propemits false false + * @see ruled.client */ /** * The client class. * - * To get a client class from the command line, use the command `xprop - * WM_CLASS`. The class will be the second string. + * A class usually maps to the application name. It is useful in, among other + * places, the rules to apply different properties to different clients. It + * is also useful, along with `instance`, so implement "windows counter" + * used in many popular docks and Alt-Tab like popups. * - * **Signal:** + * To get a client class from the command line, use the command: * - * * *property::class* + * xprop WM_CLASS + * + * The class will be the second string. + * + * This *should* never change after the client is created, but some + * buggy application like the Spotify desktop client are known to + * violate the specification and do it anyway. There *is* a signal for + * this property, but it should hopefully never be useful. If your + * applications change their classes, please report a bug to them. + * It tends to break `ruled.client` and other AwesomeWM APIs. * * @property class - * @param string + * @tparam string class + * @propemits false false + * @see instance + * @see ruled.client */ /** * The client instance. * - * To get a client instance from the command line, use the command `xprop - * WM_CLASS`. The instance will be the first string. + * The `instance` is a subtype of the `class`. Each `class` can have + * multiple instances. This is useful in the `ruled.client` rules to + * filter clients and apply different properties to them. * - * **Signal:** + * To get a client instance from the command line, use the command: * - * * *property::instance* + * xprop WM_CLASS + * + * The instance will be the first string. * * @property instance - * @param string + * @tparam string instance + * @propemits false false + * @see class + * @see ruled.client */ /** * The client PID, if available. * - * **Signal:** - * - * * *property::pid* + * This will never change. * * @property pid - * @param number + * @tparam integer pid + * @propemits false false */ /** * The window role, if available. * - * **Signal:** - * - * * *property::role* - * * @property role - * @param string + * @tparam string role + * @propemits false false + * @see instance + * @see class */ /** * The machine client is running on. * - * **Signal:** - * - * * *property::machine* + * X11 windows can "live" in another computer but shown + * in another one. This is called "network transparency" + * and is either used directly by allowing remote windows + * using the `xhosts` command for using proxies such as + * `ssh -X` or `ssh -Y`. * * @property machine - * @param string + * @tparam string machine + * @propemits false false */ /** * The client name when iconified. * - * **Signal:** - * - * * *property::icon\_name* - * * @property icon_name - * @param string + * @tparam string icon_name + * @propemits false false */ /** @@ -526,67 +620,65 @@ * the same icon, it will cause a double-free error and Awesome will crash. To * get a copy of the icon, you can use: * - * local s = gears.surface(c.icon) - * local img = cairo.ImageSurface.create(cairo.Format.ARGB32, s:get_width(), s:get_height()) - * local cr = cairo.Context(img) - * cr:set_source_surface(s, 0, 0) - * cr:paint() - * - * **Signal:** - * - * * *property::icon* + * local s = gears.surface(c.icon) + * local img = cairo.ImageSurface.create(cairo.Format.ARGB32, s:get_width(), s:get_height()) + * local cr = cairo.Context(img) + * cr:set_source_surface(s, 0, 0) + * cr:paint() * * @property icon - * @param surface + * @tparam surface icon + * @propemits false false * @usage local ib = wibox.widget.imagebox(c.icon) + * @see awful.widget.clienticon */ /** * The available sizes of client icons. This is a table where each entry * contains the width and height of an icon. * - * **Signal:** - * - * * *property::icon\_sizes* - * * @property icon_sizes * @tparam table sizes + * @propemits false false + * @see awful.widget.clienticon * @see get_icon */ /** * Client screen. * - * **Signal:** + * The `screen` corresponds to the top-left corner of the window. * - * * *property::screen* + * Please note that clients can only be on one screen at once. X11 + * does not natively allow clients to be in multiple locations at + * once. Changing the screen directly will affect the tags and may + * cause several other changes to the state in order to ensure no + * screen specific code is changing the other screens clients. * * @property screen - * @param screen + * @tparam screen screen + * @propemits false false + * @see move_to_screen */ /** * Define if the client must be hidden, i.e. never mapped, * invisible in taskbar. * - * **Signal:** - * - * * *property::hidden* - * * @property hidden - * @param boolean + * @tparam boolean hidden + * @propemits false false + * @see minimized */ /** * Define it the client must be iconify, i.e. only visible in * taskbar. * - * **Signal:** - * - * * *property::minimized* - * * @property minimized - * @param boolean + * @tparam boolean minimized + * @propemits false false + * @see hidden */ /** @@ -598,19 +690,17 @@ * * This is enabled by default. To disable it by default, see `ruled.client`. * - * **Signal:** - * - * * *property::size\_hints\_honor* - * * @property size_hints_honor - * @param boolean + * @tparam boolean size_hints_honor + * @propemits false false * @see size_hints */ /** * The client border width. + * * @property border_width - * @param integer + * @tparam integer border_width * @propemits false false * @see request::border */ @@ -619,7 +709,7 @@ * The client border color. * * @property border_color - * @param color Any string, gradients and patterns will be converted to a + * @tparam color border_color Any string, gradients and patterns will be converted to a * cairo pattern. * @propemits false false * @see request::border @@ -629,12 +719,8 @@ /** * The client urgent state. * - * **Signal:** - * - * * *property::urgent* - * * @property urgent - * @param boolean + * @tparam boolean urgent * @propemits false false * @see request::border */ @@ -650,49 +736,58 @@ * * gears.surface(c.content):write_to_png(path) * + * Please note that once taken, the surface wont be + * updated when the client content changes. Since + * AwesomeWM does not have a compositor, the only way + * to get an animated client screenshot widget is to + * poll this property multiple time per seconds. This + * is very slow and should be used only when the said + * widget is visible rather than all the time. + * + * This property has no signals when the content changes. + * * @property content - * @param surface + * @tparam surface content + * @see gears.surface */ /** * The client opacity. * - * **Signal:** - * - * * *property::opacity* - * * @property opacity - * @param number Between 0 (transparent) to 1 (opaque) + * @tparam number opacity Between 0 (transparent) to 1 (opaque). * @propemits false false * @see request::border */ /** * The client is on top of every other windows. + * * @property ontop - * @param boolean + * @tparam boolean ontop + * @propemits false false + * @see below + * @see above */ /** * The client is above normal windows. * - * **Signal:** - * - * * *property::above* - * * @property above - * @param boolean + * @tparam boolean above + * @propemits false false + * @see below + * @see ontop */ /** * The client is below normal windows. * - * **Signal:** - * - * * *property::below* - * * @property below - * @param boolean + * @tparam boolean below + * @propemits false false + * @see above + * @see ontop */ /** @@ -747,42 +842,98 @@ /** * The client the window is transient for. * + * A transient window is a client that "belongs" to another + * client. If the client is also `modal`, then it always has + * to be on top of the other window *and* the parent client + * cannot be focused while the child client exists. + * This is common for "Save as" dialogs or other dialogs where + * isn't possible to modify the content of the "parent" client + * while the dialog is open. + * + * However, `modal` isn't a requirement for using the `transient_for` + * concept. "Tools" such as popup palette in canvas-and-palettes + * applications can belong to each other without being modal. + * + * However this it is also + * possible to have + * * @property transient_for - * @param client + * @tparam client transient_for * @propemits false false + * @see modal + * @see type + * @see is_transient_for + * @see get_transient_for_matching */ /** * Window identification unique to a group of windows. * + * This is the ID of the group window, not a client object. + * * @property group_window - * @param client + * @tparam integer group_window * @propemits false false + * @see leader_window */ /** * Identification unique to windows spawned by the same command. + * + * This is the ID of the group window, not a client object. + * * @property leader_window - * @param client + * @tparam number leader_window + * @propemits false false + * @see transient_for + * @see modal + * @see group_window */ /** * A table with size hints of the client. * + * Please note that most fields are optional and may or may not be set. + * + * When the client is tiled, the `size_hints` usually get in the way and + * cause the layouts to behave incorrectly. To mitigate this, it is often + * advised to set `size_hints_honor` to `false` in the `ruled.client` rules. + * * @property size_hints - * @param table - * @tfield integer table.user_position - * @tfield integer table.user_size - * @tfield integer table.program_position - * @tfield integer table.program_size - * @tfield integer table.max_width - * @tfield integer table.max_height - * @tfield integer table.min_width - * @tfield integer table.min_height - * @tfield integer table.width_inc - * @tfield integer table.height_inc + * @tparam[opt] table|nil hints The hints. + * @tparam[opt] table|nil hints.user_position A table with `x` and `y` keys. It + * contains the preferred position of the client. This is set when the + * position has been modified by the user. See `program_position`. + * @tparam[opt] table|nil hints.program_position A table with `x` and `y` keys. It + * contains the preferred position of the client. This is set when the + * application itself requests a specific position. See `user_position`. + * @tparam[opt] table|nil hints.user_size A table with `width` and `height`. This + * contains the client preferred size when it has previously been set by + * the user. See `program_size` for the equivalent when the applications + * itself wants to specify its preferred size. + * @tparam[opt] table|nil hints.program_size A table with `width` and `height`. This + * contains the client preferred size as specified by the application. + * @tparam[opt] integer|nil hints.max_width The maximum width (in pixels). + * @tparam[opt] integer|nil hints.max_height The maximum height (in pixels). + * @tparam[opt] integer|nil hints.min_width The minimum width (in pixels). + * @tparam[opt] integer|nil hints.min_height The minimum height (in pixels). + * @tparam[opt] integer|nil hints.width_inc The number of pixels by which the + * client width may be increased or decreased. For example, for terminals, + * the size has to be proportional with the monospace font size. + * @tparam[opt] integer|nil hints.height_inc The number of pixels by which the + * client height may be increased or decreased. For example, for terminals, + * the size has to be proportional with the monospace font size. + * @tparam[opt] string|nil hints.win_gravity The client `gravity` defines the corder + * from which the size is computed. For most clients, it is `north_west`, which + * corresponds to the top-left of the window. This will affect how the client + * is resized and other size related operations. + * @tparam[opt] integer|nil hints.min_aspect_num + * @tparam[opt] integer|nil hints.min_aspect_den + * @tparam[opt] integer|nil hints.max_aspect_num + * @tparam[opt] integer|nil hints.max_aspect_den * @propemits false false * @see size_hints_honor + * @see geometry */ /** @@ -797,103 +948,168 @@ * should be enabled. * * @property motif_wm_hints - * @param table - * @tfield[opt] table table.functions - * @tfield[opt] boolean table.functions.all - * @tfield[opt] boolean table.functions.resize - * @tfield[opt] boolean table.functions.move - * @tfield[opt] boolean table.functions.minimize - * @tfield[opt] boolean table.functions.maximize - * @tfield[opt] boolean table.functions.close - * @tfield[opt] table table.decorations - * @tfield[opt] boolean table.decorations.all - * @tfield[opt] boolean table.decorations.border - * @tfield[opt] boolean table.decorations.resizeh - * @tfield[opt] boolean table.decorations.title - * @tfield[opt] boolean table.decorations.menu - * @tfield[opt] boolean table.decorations.minimize - * @tfield[opt] boolean table.decorations.maximize - * @tfield[opt] string table.input_mode - * @tfield[opt] table table.status - * @tfield[opt] boolean table.status.tearoff_window + * @tparam table hints The hints. + * @tparam[opt] boolean hints.functions.all + * @tparam[opt] boolean hints.functions.resize + * @tparam[opt] boolean hints.functions.move + * @tparam[opt] boolean hints.functions.minimize + * @tparam[opt] boolean hints.functions.maximize + * @tparam[opt] boolean hints.functions.close + * @tparam[opt] boolean hints.decorations.all + * @tparam[opt] boolean hints.decorations.border + * @tparam[opt] boolean hints.decorations.resizeh + * @tparam[opt] boolean hints.decorations.title + * @tparam[opt] boolean hints.decorations.menu + * @tparam[opt] boolean hints.decorations.minimize + * @tparam[opt] boolean hints.decorations.maximize + * @tparam[opt] string hints.input_mode This is either `modeless`, + * `primary_application_modal`, `system_modal`, + * `full_application_modal` or `unknown`. + * @tparam[opt] boolean hints.status.tearoff_window * @propemits false false */ /** * Set the client sticky, i.e. available on all tags. * + * Please note that AwesomeWM implements `sticky` clients + * per screens rather than globally like some other + * implementations. + * * @property sticky - * @param boolean + * @tparam boolean sticky * @propemits false false + * @see skip_taskbar */ /** * Indicate if the client is modal. * + * A transient window is a client that "belongs" to another + * client. If the client is also `modal`, then it always has + * to be on top of the other window *and* the parent client + * cannot be focused while the child client exists. + * This is common for "Save as" dialogs or other dialogs where + * isn't possible to modify the content of the "parent" client + * while the dialog is open. + * + * However, `modal` isn't a requirement for using the `transient_for` + * concept. "Tools" such as popup palette in canvas-and-palettes + * applications can belong to each other without being modal. + * * @property modal - * @param boolean + * @tparam boolean modal * @propemits false false + * @see transient_for */ /** * True if the client can receive the input focus. * + * The client wont get focused even when the user + * click on it. + * * @property focusable - * @param boolean + * @tparam boolean focusable * @propemits false false + * @see shape_input + * @see client.focus + * @see active + * @see activate */ /** * The client's bounding shape as set by awesome as a (native) cairo surface. * - * @see gears.surface.apply_shape_bounding + * The bounding shape is the outer shape of the client. It is outside of the + * border. + * + * Do not use this directly unless you want total control over the shape (such + * as shape with holes). Even then, it is usually recommended to use transparency + * in the titlebars and a compositing manager. For the vast majority use use + * cases, use the `shape` property. + * * @property shape_bounding - * @param surface + * @tparam surface shape_bounding * @propemits false false + * @see shape + * @see gears.surface.apply_shape_bounding + * @see gears.shape + * @see shape_clip + * @see shape_input + * @see client_shape_bounding + * @see client_shape_clip + * @see gears.surface */ /** * The client's clip shape as set by awesome as a (native) cairo surface. * - * **Signal:** - * - * * *property::shape\_clip* + * The shape_clip is the shape of the client *content*. It is *inside* the + * border. * * @property shape_clip - * @param surface + * @tparam surface shape_clip + * @propemits false false + * @see shape_bounding + * @see shape_input + * @see shape + * @see gears.surface.apply_shape_bounding + * @see gears.shape + * @see client_shape_bounding + * @see client_shape_clip + * @see gears.surface */ /** * The client's input shape as set by awesome as a (native) cairo surface. * - * **Signal:** - * - * * *property::shape\_input* + * The input shape is the shape where mouse input will be passed to the + * client rather than propagated below it. * * @property shape_input - * @param surface + * @tparam surface shape_input + * @propemits false false + * @see shape_bounding + * @see shape_clip + * @see shape + * @see gears.surface.apply_shape_bounding + * @see gears.shape + * @see client_shape_bounding + * @see client_shape_clip + * @see gears.surface */ /** * The client's bounding shape as set by the program as a (native) cairo surface. * - * **Signal:** - * - * * *property::shape\_client\_bounding* - * * @property client_shape_bounding - * @param surface + * @tparam surface client_shape_bounding + * @propemits false false + * @see shape_bounding + * @see shape_clip + * @see shape_input + * @see shape + * @see gears.surface.apply_shape_bounding + * @see gears.shape + * @see client_shape_clip + * @see gears.surface */ /** * The client's clip shape as set by the program as a (native) cairo surface. * - * **Signal:** - * - * * *property::shape\_client\_clip* - * * @property client_shape_clip - * @param surface + * @tparam surface client_shape_clip + * @propemits false false + * @see shape_bounding + * @see shape_clip + * @see shape_input + * @see shape + * @see gears.surface.apply_shape_bounding + * @see gears.shape + * @see client_shape_bounding + * @see gears.surface */ /** @@ -950,12 +1166,9 @@ * "snid", fix_startup_id, {}, {"awful.spawn", "ruled.client"} * ) * - * **Signal:** - * - * * *property::startup\_id* - * * @property startup_id - * @param string + * @tparam string startup_id + * @propemits false false * @see awful.spawn */ @@ -966,52 +1179,49 @@ * * local is_valid = pcall(function() return c.valid end) and c.valid * - * **Signal:** - * - * * *property::valid* - * * @property valid - * @param boolean + * @tparam boolean valid + * @propemits false false + * @see kill */ /** - * The first tag of the client. Optimized form of `c:tags()[1]`. + * The first tag of the client. * - * **Signal:** - * - * * *property::first\_tag* + * Optimized form of `c:tags()[1]`. Not every workflow uses the + * ability to set multiple tags to a client. It is often enough + * to only get the first tag and ignore everything else. * * @property first_tag - * @param tag - */ - -/** When the height or width changed. - * @signal property::size - * @see client.geometry - */ - -/** When the x or y coordinate changed. - * @signal property::position - * @see client.geometry + * @tparam tag first_tag + * @propemits false false + * @see tags */ /** Return client struts (reserved space at the edge of the screen). * - * @param struts A table with new strut values, or none. - * @return A table with strut values. + * The struts area is a table with a `left`, `right`, `top` and `bottom` + * keys to define how much space of the screen `workarea` this client + * should reserve for itself. + * + * @tparam table struts A table with new strut values, or none. + * @treturn table A table with strut values. * @method struts + * @see geometry + * @see screen.workarea */ /** Get or set mouse buttons bindings for a client. * * @property buttons - * @param table + * @tparam table buttons + * @propemits false false * @see awful.button */ /** Get the number of instances. * - * @return The number of client objects alive. + * @treturn integer The number of client objects alive. * @staticfct instances */ @@ -2561,6 +2771,9 @@ client_kill(client_t *c) * top to bottom). * @treturn table A table with clients. * @staticfct get + * @usage for _, c in client.get() do + * -- do something + * end */ static int luaA_client_get(lua_State *L) @@ -2600,7 +2813,7 @@ luaA_client_get(lua_State *L) /** Check if a client is visible on its screen. * - * @return A boolean value, true if the client is visible, false otherwise. + * @treturn boolean A boolean value, true if the client is visible, false otherwise. * @method isvisible */ static int @@ -2710,8 +2923,13 @@ out: /** Kill a client. + * + * This method can be used to close (kill) a **client** using the + * X11 protocol. To use the POSIX way to kill a **process**, use + * `awesome.kill`. * * @method kill + * @see awesome.kill */ static int luaA_client_kill(lua_State *L) @@ -2724,6 +2942,17 @@ luaA_client_kill(lua_State *L) /** Swap a client with another one in global client list. * @client c A client to swap with. * @method swap + * @emits swapped + * @emitstparam swapped client The other client. + * @emitstparam swapped boolean `true` when `:swap()` was called + * on *self* rather than the other client. `false` when + * `:swap()` was called on the other client. + * @emits list + * @see swapped + * @see awful.client.swap.bydirection + * @see awful.client.swap.global_bydirection + * @see awful.client.swap.byidx + * @see awful.client.cycle */ static int luaA_client_swap(lua_State *L) @@ -2766,14 +2995,13 @@ luaA_client_swap(lua_State *L) * * Use the `first_tag` field to access the first tag of a client directly. * - * **Signal:** - * - * * *property::tags* - * * @tparam table tags_table A table with tags to set, or `nil` to get the * current tags. * @treturn table A table with all tags. * @method tags + * @emits property::tags + * @see first_tag + * @see toggle_tag */ static int luaA_client_tags(lua_State *L) @@ -2843,6 +3071,11 @@ luaA_client_get_first_tag(lua_State *L, client_t *c) /** Raise a client on top of others which are on the same layer. * * @method raise + * @emits raised + * @see above + * @see below + * @see ontop + * @see lower */ static int luaA_client_raise(lua_State *L) @@ -2864,6 +3097,11 @@ luaA_client_raise(lua_State *L) /** Lower a client on bottom of others which are on the same layer. * * @method lower + * @emits lowered + * @see above + * @see below + * @see ontop + * @see raise */ static int luaA_client_lower(lua_State *L) @@ -3119,8 +3357,17 @@ HANDLE_TITLEBAR(left, CLIENT_TITLEBAR_LEFT) /** Return or set client geometry. * * @tparam table|nil geo A table with new coordinates, or nil. + * @tparam integer geo.x The horizontal position. + * @tparam integer geo.y The vertical position. + * @tparam integer geo.width The width. + * @tparam integer geo.width The height. * @treturn table A table with client geometry and coordinates. * @method geometry + * @see struts + * @see x + * @see y + * @see width + * @see height */ static int luaA_client_geometry(lua_State *L) @@ -3153,11 +3400,19 @@ luaA_client_geometry(lua_State *L) /** Apply size hints to a size. * - * @param width Desired width of client - * @param height Desired height of client - * @return Actual width of client - * @return Actual height of client + * This method applies the client size hints. The client + * will be resized according to the size hints as long + * as `size_hints_honor` is true. Regardless of the + * status of `size_hints_honor`, this method will + * return the size with the size hints applied. + * + * @tparam integer width Desired width of client + * @tparam integer height Desired height of client + * @treturn integer Actual width of client + * @treturn integer Actual height of client * @method apply_size_hints + * @see size_hints + * @see size_hints_honor */ static int luaA_client_apply_size_hints(lua_State *L) @@ -3773,7 +4028,8 @@ luaA_client_set_shape_input(lua_State *L, client_t *c) /** Get or set keys bindings for a client. * * @property keys - * @param table + * @tparam table keys + * @propemits false false * @see awful.key */ static int @@ -3816,10 +4072,6 @@ luaA_client_get_icon_sizes(lua_State *L, client_t *c) } /** Get the client's n-th icon. - * - * **Signal:** - * - * * *property::icon* * * @tparam interger index The index in the list of icons to get. * @treturn surface A lightuserdata for a cairo surface. This reference must be