+--
+-- | Name |
+-- Description |
+--
+-- | placement | The client default placement on the screen |
+-- | honor\_padding | When applying the placement, honor the screen padding |
+-- | honor\_workarea | When applying the placement, honor the screen work area |
+-- | tag | The client default tag |
+-- | tags | The client default tags |
+-- | new\_tag | Create a new tag for this client |
+-- | switch\_to\_tags | Unselect the current tags and select this client tags |
+-- | focus | Define if the client should grab focus by default |
+-- | titlebars\_enabled | Should this client have a titlebar by default |
+-- | callback | A function to call when this client is ready |
+-- | marked | If a client is marked or not |
+-- | is\_fixed | Return if a client has a fixed size or not |
+-- | immobilized | Is the client immobilized horizontally? |
+-- | immobilized | Is the client immobilized vertically? |
+-- | floating | The client floating state |
+-- | x | The x coordinates |
+-- | y | The y coordinates |
+-- | width | The width of the client |
+-- | height | The height of the client |
+-- | dockable | If the client is dockable |
+-- | requests\_no\_titlebar | If the client requests not to be decorated with a titlebar |
+-- | shape | Set the client shape |
+-- | window | The X window id |
+-- | name | The client title |
+-- | skip\_taskbar | True if the client does not want to be in taskbar |
+-- | type | The window type |
+-- | class | The client class |
+-- | instance | The client instance |
+-- | pid | The client PID, if available |
+-- | role | The window role, if available |
+-- | machine | The machine client is running on |
+-- | icon\_name | The client name when iconified |
+-- | icon | The client icon as a surface |
+-- | icon\_sizes | The available sizes of client icons |
+-- | screen | Client screen |
+-- | hidden | Define if the client must be hidden, i |
+-- | minimized | Define it the client must be iconify, i |
+-- | size\_hints\_honor | Honor size hints, e |
+-- | border\_width | The client border width |
+-- | border\_color | The client border color |
+-- | urgent | The client urgent state |
+-- | content | A cairo surface for the client window content |
+-- | opacity | The client opacity |
+-- | ontop | The client is on top of every other windows |
+-- | above | The client is above normal windows |
+-- | below | The client is below normal windows |
+-- | fullscreen | The client is fullscreen or not |
+-- | maximized | The client is maximized (horizontally and vertically) or not |
+-- | maximized\_horizontal | The client is maximized horizontally or not |
+-- | maximized\_vertical | The client is maximized vertically or not |
+-- | transient\_for | The client the window is transient for |
+-- | group\_window | Window identification unique to a group of windows |
+-- | leader\_window | Identification unique to windows spawned by the same command |
+-- | size\_hints | A table with size hints of the client |
+-- | motif\_wm\_hints | The motif WM hints of the client |
+-- | sticky | Set the client sticky, i |
+-- | modal | Indicate if the client is modal |
+-- | focusable | True if the client can receive the input focus |
+-- | shape\_bounding | The client's bounding shape as set by awesome as a (native) cairo surface |
+-- | shape\_clip | The client's clip shape as set by awesome as a (native) cairo surface |
+-- | shape\_input | The client's input shape as set by awesome as a (native) cairo surface |
+-- | client\_shape\_bounding | The client's bounding shape as set by the program as a (native) cairo surface |
+-- | client\_shape\_clip | The client's clip shape as set by the program as a (native) cairo surface |
+-- | startup\_id | The FreeDesktop StartId |
+-- | valid | If the client that this object refers to is still managed by awesome |
+-- | first\_tag | The first tag of the client |
+--
diff --git a/docs/config.ld b/docs/config.ld
index a640e4f7..0d783ace 100644
--- a/docs/config.ld
+++ b/docs/config.ld
@@ -72,6 +72,8 @@ new_type("callback", "Callback functions prototype", false, "Parameters")
new_type("rulesources", "Rule sources", false, "param")
-- Filter functions for the taglist/tasklist/layoutlist
new_type("filterfunction", "List filters", false)
+-- Extra client properties available only in awful.rules/spawn constructs
+new_type("clientruleproperty", "Extra properties available in awful.rules and awful.spawn", false, "Type")
-- More fitting section names
kind_names={topic='Documentation', module='Libraries', script='Sample files'}
@@ -135,10 +137,14 @@ file = {
}
}
+local no_prefix = {
+ property = true, signal = true, clientruleproperty = true
+}
+
custom_display_name_handler = function(item, default_handler)
-- Remove the "namespace" from the signals and properties
- if item.type == "property" or item.type == "signal" then
+ if no_prefix[item.type] then
local name = item.name:match("%.([^.]+)$")
return name ~= "" and name or item.name
end
diff --git a/docs/ldoc.css b/docs/ldoc.css
index 6cea44f1..a761088f 100644
--- a/docs/ldoc.css
+++ b/docs/ldoc.css
@@ -22,7 +22,7 @@ hr {
margin: 15px 0;
}
-code, tt {
+tt {
font-family: monospace;
}
span.parameter {
@@ -47,6 +47,19 @@ p.name {
font-family: monospace;
}
+kbd, p code, ol code {
+ background-color: #eaedf587;
+ padding-left: 3px;
+ padding-right: 3px;
+ border-radius: 3px;
+ border-style: solid;
+ border-width: 1px;
+ border-color: #b7bac1;
+ font-family: monospace;
+ margin-left: 5px;
+ margin-right: 5px;
+}
+
#navigation {
float: left;
background-color: white;
@@ -136,6 +149,7 @@ pre {
padding: 15px;
overflow: auto;
font-family: monospace;
+ max-width: 720px;
}
#content ul pre.example {
@@ -191,6 +205,58 @@ table th, table td {
padding: 2px;
}
+.widget_list td {
+ padding-top: 10px;
+ padding-bottom: 10px;
+}
+
+.widget_list tr td:first-child {
+ padding-left: 5px;
+}
+
+.widget_list tr td:last-child {
+ padding-right: 10px;
+}
+
+.widget_list {
+ border-collapse: unset;
+ overflow: hidden;
+ border-style: solid;
+ border-width: 0.5px;
+ border-top-left-radius: 7px;
+ border-top-right-radius: 7px;
+}
+
+.widget_list th {
+ background-color: #2c3e67;
+ font-weight: bold;
+ color: white;
+ padding-top: 10px;
+ padding-bottom: 10px;
+}
+
+.widget_list th:first-child {
+ border-top-left-radius: 7px;
+ border-bottom-width: 1px;
+ padding-left: 20px;
+ padding-right: 20px;
+}
+
+.widget_list th:last-child {
+ border-top-right-radius: 7px;
+ border-width: 0px;
+ border-bottom-width: 1px;
+ padding-left: 20px;
+ padding-right: 20px;
+}
+
+.widget_list td {
+ border-style: solid;
+ border-width: 0px;
+ border-right-width: 1px;;
+ border-bottom-width: 1px;
+}
+
#about {
padding: 15px;
padding-left: 16em;
diff --git a/docs/load_ldoc.cmake b/docs/load_ldoc.cmake
index a783e7db..161d49e0 100644
--- a/docs/load_ldoc.cmake
+++ b/docs/load_ldoc.cmake
@@ -1,23 +1,23 @@
# To avoid copy pasting, some documentation is stored in reusable files
set(SHAPE_FILE "${SOURCE_DIR}/docs/common/${SHAPE_NAME}.lua")
-set(path "${SOURCE_DIR}/docs/common/")
+foreach(path ${BUILD_DIR}/docs/common/;${SOURCE_DIR}/docs/common/)
+ # Get the documentation file list
+ file(GLOB doc_files RELATIVE "${path}" "${path}/*.ldoc")
-# Get the documentation file list
-file(GLOB doc_files RELATIVE "${path}" "${path}/*.ldoc")
+ foreach(doc_file_name ${doc_files})
+ # Read the file
+ file(READ "${path}/${doc_file_name}" doc_file_content)
-foreach(doc_file_name ${doc_files})
- # Read the file
- file(READ "${path}/${doc_file_name}" doc_file_content)
+ # Remove the file extension
+ string(REGEX REPLACE "\\.ldoc" "" DOC_FILE_NAME ${doc_file_name})
- # Remove the file extension
- string(REGEX REPLACE "\\.ldoc" "" DOC_FILE_NAME ${doc_file_name})
+ # There is a trailing \n, remove it or it cannot be included in existing blocks
+ string(REGEX REPLACE "\n$" "" doc_file_content "${doc_file_content}")
- # There is a trailing \n, remove it or it cannot be included in existing blocks
- string(REGEX REPLACE "\n$" "" doc_file_content "${doc_file_content}")
-
- # Create a new variable usable from lua files
- set(DOC_${DOC_FILE_NAME}_COMMON "${doc_file_content}")
+ # Create a new variable usable from lua files
+ set(DOC_${DOC_FILE_NAME}_COMMON "${doc_file_content}")
+ endforeach()
endforeach()
# vim: filetype=cmake:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80:foldmethod=marker
diff --git a/lib/awful/client.lua b/lib/awful/client.lua
index ffa20e04..f75270cf 100644
--- a/lib/awful/client.lua
+++ b/lib/awful/client.lua
@@ -59,6 +59,93 @@ client.property = {}
client.shape = require("awful.client.shape")
client.focus = require("awful.client.focus")
+--- The client default placement on the screen.
+--
+-- The default config uses:
+--
+-- awful.placement.no_overlap+awful.placement.no_offscreen
+--
+-- @clientruleproperty placement
+-- @see awful.placement
+
+--- When applying the placement, honor the screen padding.
+-- @clientruleproperty honor_padding
+-- @param[opt=true] boolean
+-- @see awful.placement
+
+--- When applying the placement, honor the screen work area.
+--
+-- The workarea is the part of the screen that excludes the bars and docks.
+--
+-- @clientruleproperty honor_workarea
+-- @param[opt=true] boolean
+-- @see awful.placement
+
+--- The client default tag.
+-- @clientruleproperty tag
+-- @param tag
+-- @see tag
+-- @see new_tag
+-- @see tags
+-- @see switch_to_tags
+
+--- The client default tags.
+--
+-- Avoid using the tag and tags properties at the same time, it will cause
+-- issues.
+--
+-- @clientruleproperty tags
+-- @param[opt={tag}] table
+-- @see tag
+-- @see new_tag
+-- @see tags
+-- @see switch_to_tags
+
+--- Create a new tag for this client.
+--
+-- If the value is `true`, the new tag will be named after the client `class`.
+-- If it is a string, it will be the tag name.
+--
+-- If a table is used, all of its properties will be passed to the tag
+-- constructor:
+--
+-- new_tag = {
+-- name = "My new tag!", -- The tag name.
+-- layout = awful.layout.suit.max, -- Set the tag layout.
+-- volatile = true, -- Remove the tag when the client is closed.
+-- }
+--
+-- @tparam[opt=false] table|string|boolean new_tag
+-- @clientruleproperty new_tag
+-- @see tag
+-- @see tags
+-- @see switch_to_tags
+
+--- Unselect the current tags and select this client tags.
+-- Note that this property was called `switchtotag` in previous Awesome versions.
+-- @clientruleproperty switch_to_tags
+-- @param[opt=false] boolean
+-- @see tag.selected
+
+--- Define if the client should grab focus by default.
+--
+-- The `request::activate` context for this call is `rules`.
+--
+-- @clientruleproperty focus
+-- @param[opt=false] boolean
+
+--- Should this client have a titlebar by default.
+-- @clientruleproperty titlebars_enabled
+-- @param[opt=false] boolean
+-- @see awful.titlebar
+
+--- A function to call when this client is ready.
+--
+-- It can be useful to set extra properties or perform actions.
+--
+-- @clientruleproperty callback
+-- @see awful.spawn
+
--- Jump to the given client.
-- Takes care of focussing the screen, the right tag, etc.
--
diff --git a/lib/awful/rules.lua b/lib/awful/rules.lua
index 29d7e4bf..8e60794c 100644
--- a/lib/awful/rules.lua
+++ b/lib/awful/rules.lua
@@ -8,17 +8,98 @@
-- to add random properties that will be later accessible as `c.property_name`
-- (where `c` is a valid client object)
--
--- In addition to the existing properties, the following are supported:
+-- Syntax
+-- ===
+-- You should fill this table with your rule and properties to apply.
+-- For example, if you want to set xterm maximized at startup, you can add:
--
--- * placement
--- * honor_padding
--- * honor_workarea
--- * tag
--- * new_tag
--- * switch_to_tags (also called switchtotag)
--- * focus
--- * titlebars_enabled
--- * callback
+-- { rule = { class = "xterm" },
+-- properties = { maximized_vertical = true, maximized_horizontal = true } }
+--
+-- If you want to set mplayer floating at startup, you can add:
+--
+-- { rule = { name = "MPlayer" },
+-- properties = { floating = true } }
+--
+-- If you want to put Firefox on a specific tag at startup, you can add:
+--
+-- { rule = { instance = "firefox" },
+-- properties = { tag = mytagobject } }
+--
+-- Alternatively, you can specify the tag by name:
+--
+-- { rule = { instance = "firefox" },
+-- properties = { tag = "3" } }
+--
+-- If you want to put Thunderbird on a specific screen at startup, use:
+--
+-- { rule = { instance = "Thunderbird" },
+-- properties = { screen = 1 } }
+--
+-- Assuming that your X11 server supports the RandR extension, you can also specify
+-- the screen by name:
+--
+-- { rule = { instance = "Thunderbird" },
+-- properties = { screen = "VGA1" } }
+--
+-- If you want to put Emacs on a specific tag at startup, and immediately switch
+-- to that tag you can add:
+--
+-- { rule = { class = "Emacs" },
+-- properties = { tag = mytagobject, switchtotag = true } }
+--
+-- If you want to apply a custom callback to execute when a rule matched,
+-- for example to pause playing music from mpd when you start dosbox, you
+-- can add:
+--
+-- { rule = { class = "dosbox" },
+-- callback = function(c)
+-- awful.spawn('mpc pause')
+-- end }
+--
+-- Note that all "rule" entries need to match. If any of the entry does not
+-- match, the rule won't be applied.
+--
+-- If a client matches multiple rules, they are applied in the order they are
+-- put in this global rules table. If the value of a rule is a string, then the
+-- match function is used to determine if the client matches the rule.
+--
+-- If the value of a property is a function, that function gets called and
+-- function's return value is used for the property.
+--
+-- To match multiple clients to a rule one need to use slightly different
+-- syntax:
+--
+-- { rule_any = { class = { "MPlayer", "Nitrogen" }, instance = { "xterm" } },
+-- properties = { floating = true } }
+--
+-- To match multiple clients with an exception one can couple `rules.except` or
+-- `rules.except_any` with the rules:
+--
+-- { rule = { class = "Firefox" },
+-- except = { instance = "Navigator" },
+-- properties = {floating = true},
+-- },
+--
+-- { rule_any = { class = { "Pidgin", "Xchat" } },
+-- except_any = { role = { "conversation" } },
+-- properties = { tag = "1" }
+-- }
+--
+-- { rule = {},
+-- except_any = { class = { "Firefox", "Vim" } },
+-- properties = { floating = true }
+-- }
+--
+-- Applicable client properties
+-- ===
+--
+-- The table below holds the list of default client properties along with
+-- some extra properties that are specific to the rules. Note that any property
+-- can be set in the rules and interpreted by user provided code. This table
+-- only represent those offered by default.
+--
+--@DOC_rules_index_COMMON@
--
-- @author Julien Danjou <julien@danjou.info>
-- @copyright 2009 Julien Danjou
@@ -44,90 +125,7 @@ local unpack = unpack or table.unpack -- luacheck: globals unpack (compatibility
local rules = {}
---[[--
-This is the global rules table.
-
-You should fill this table with your rule and properties to apply.
-For example, if you want to set xterm maximized at startup, you can add:
-
- { rule = { class = "xterm" },
- properties = { maximized_vertical = true, maximized_horizontal = true } }
-
-If you want to set mplayer floating at startup, you can add:
-
- { rule = { name = "MPlayer" },
- properties = { floating = true } }
-
-If you want to put Firefox on a specific tag at startup, you can add:
-
- { rule = { instance = "firefox" },
- properties = { tag = mytagobject } }
-
-Alternatively, you can specify the tag by name:
-
- { rule = { instance = "firefox" },
- properties = { tag = "3" } }
-
-If you want to put Thunderbird on a specific screen at startup, use:
-
- { rule = { instance = "Thunderbird" },
- properties = { screen = 1 } }
-
-Assuming that your X11 server supports the RandR extension, you can also specify
-the screen by name:
-
- { rule = { instance = "Thunderbird" },
- properties = { screen = "VGA1" } }
-
-If you want to put Emacs on a specific tag at startup, and immediately switch
-to that tag you can add:
-
- { rule = { class = "Emacs" },
- properties = { tag = mytagobject, switch_to_tags = true } }
-
-If you want to apply a custom callback to execute when a rule matched,
-for example to pause playing music from mpd when you start dosbox, you
-can add:
-
- { rule = { class = "dosbox" },
- callback = function(c)
- awful.spawn('mpc pause')
- end }
-
-Note that all "rule" entries need to match. If any of the entry does not
-match, the rule won't be applied.
-
-If a client matches multiple rules, they are applied in the order they are
-put in this global rules table. If the value of a rule is a string, then the
-match function is used to determine if the client matches the rule.
-
-If the value of a property is a function, that function gets called and
-function's return value is used for the property.
-
-To match multiple clients to a rule one need to use slightly different
-syntax:
-
- { rule_any = { class = { "MPlayer", "Nitrogen" }, instance = { "xterm" } },
- properties = { floating = true } }
-
-To match multiple clients with an exception one can couple `rules.except` or
-`rules.except_any` with the rules:
-
- { rule = { class = "Firefox" },
- except = { instance = "Navigator" },
- properties = {floating = true},
- },
-
- { rule_any = { class = { "Pidgin", "Xchat" } },
- except_any = { role = { "conversation" } },
- properties = { tag = "1" }
- }
-
- { rule = {},
- except_any = { class = { "Firefox", "Vim" } },
- properties = { floating = true }
- }
-]]--
+--- This is the global rules table.
rules.rules = {}
--- Check if a client matches a rule.
@@ -536,11 +534,6 @@ function rules.extra_properties.geometry(c, _, props)
c:geometry(new_geo) --TODO use request::geometry
end
---- Create a new tag based on a rule.
--- @tparam client c The client
--- @tparam boolean|function|string value The value.
--- @tparam table props The properties.
--- @treturn tag The new tag
function rules.high_priority_properties.new_tag(c, value, props)
local ty = type(value)
local t = nil
diff --git a/lib/awful/spawn.lua b/lib/awful/spawn.lua
index 402dad5c..6eaff0c0 100644
--- a/lib/awful/spawn.lua
+++ b/lib/awful/spawn.lua
@@ -8,6 +8,9 @@
-- program after it has been launched. This requires currently that the
-- applicaton supports them.
--
+-- Frequently asked questions
+-- ===
+--
-- **Rules of thumb when a shell is needed**:
--
-- * A shell is required when the commands contain `&&`, `;`, `||`, `&` or
@@ -45,44 +48,56 @@
-- *instance*, a *role*, and a *type*. See `client.class`, `client.instance`,
-- `client.role` and `client.type` for more information about these properties.
--
--- **The startup notification protocol**:
+-- **Understanding blocking versus asynchronous execution**:
--
--- The startup notification protocol is an optional specification implemented
--- by X11 applications to bridge the chain of knowledge between the moment a
--- program is launched to the moment its window (client) is shown. It can be
--- found [on the FreeDesktop.org website](https://www.freedesktop.org/wiki/Specifications/startup-notification-spec/).
+-- Awesome is single threaded, it means only one thing is executed at any time.
+-- But Awesome isn't doomed to be slow. It may not have multiple threads, but
+-- it has something called coroutine and also has callbacks. This means things
+-- that take time to execute can still do so in the background (using C threads
+-- or external process + sockets). When they are done, they can notify the
+-- Awesome thread. This works perfectly and avoid blocking Awesome.
--
--- Awesome has support for the various events that are part of the protocol, but
--- the most useful is the identifier, usually identified by its `SNID` acronym in
--- the documentation. It isn't usually necessary to even know it exists, as it
--- is all done automatically. However, if more control is required, the
--- identifier can be specified by an environment variable called
--- `DESKTOP_STARTUP_ID`. For example, let us consider execution of the following
--- command:
+-- If you want to update the text of a `wibox.widget.textbox` with the output
+-- of a shell command, you should use the `awful.spawn.easy_async_with_shell`
+-- command. It is strongly recommanded not to use `io.popen` is explained in the
+-- "Getting a command's output" section. Asynchronous execution is at first a
+-- bit tricky to understand if you never used that before. The example below
+-- should demonstrate how it works.
--
--- DESKTOP_STARTUP_ID="something_TIME$(date '+%s')" my_command
+-- If we do (but *really*, don't do that):
--
--- This should (if the program correctly implements the protocol) result in
--- `c.startup_id` to at least match `something`.
--- This identifier can then be used in `awful.rules` to configure the client.
+-- -- **NEVER, EVER, DO THIS**: your computer will freeze
+-- os.execute("sleep 1; echo foo > /tmp/foo.txt")
+-- mylabel.text = io.popen("cat /tmp/foo.txt"):read("*all")
--
--- Awesome can automatically set the `DESKTOP_STARTUP_ID` variable. This is used
--- by `awful.spawn` to specify additional rules for the startup. For example:
+-- The label will display `foo`. But If we do:
--
--- awful.spawn("urxvt -e maxima -name CALCULATOR", {
--- floating = true,
--- tag = mouse.screen.selected_tag,
--- placement = awful.placement.bottom_right,
--- })
+-- -- Don't do this, it wont work.
+-- -- Assumes /tmp/foo.txt does not exist
+-- awful.spawn.with_shell("sleep 1; echo foo > /tmp/foo.txt")
+-- mylabel.text = io.popen("cat /tmp/foo.txt"):read("*all")
--
--- This can also be used from the command line:
+-- Then the label will be **empty**. `awful.spawn` and `awful.spawn.with_shell`
+-- will **not** block and thus the `io.popen` will be executed before
+-- `sleep 1` finishes. This is why we have async functions to execute shell
+-- commands. There are many variants with difference characteristics and
+-- complexity. `awful.spawn.easy_async` is the most common as it is good enough
+-- for the general "I want to execute a command and do something with the
+-- output when it finishes".
--
--- awesome-client 'awful=require("awful");
--- awful.spawn("urxvt -e maxima -name CALCULATOR", {
--- floating = true,
--- tag = mouse.screen.selected_tag,
--- placement = awful.placement.bottom_right,
--- })'
+-- -- This is the correct way
+-- local command = "sleep 1; echo foo > /tmp/foo.txt"
+--
+-- awful.spawn.easy_async_with_shell(command, function()
+-- awful.spawn.easy_async_with_shell("cat /tmp/foo.txt", function(out)
+-- mylabel.text = out
+-- end)
+-- end)
+--
+-- In this variant, Awesome will not block. Again, like other spawn, you
+-- cannot add code outside of the callback function to use the result of the
+-- command. The code will be executed before the command is finished so the
+-- result wont yet be available.
--
-- **Getting a command's output**:
--
@@ -148,6 +163,53 @@
-- [Desktop Entry](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html)
-- specification.
--
+-- Spawning applications with specific properties
+-- ===
+--
+-- **The startup notification protocol**:
+--
+-- The startup notification protocol is an optional specification implemented
+-- by X11 applications to bridge the chain of knowledge between the moment a
+-- program is launched to the moment its window (client) is shown. It can be
+-- found [on the FreeDesktop.org website](https://www.freedesktop.org/wiki/Specifications/startup-notification-spec/).
+--
+-- Awesome has support for the various events that are part of the protocol, but
+-- the most useful is the identifier, usually identified by its `SNID` acronym in
+-- the documentation. It isn't usually necessary to even know it exists, as it
+-- is all done automatically. However, if more control is required, the
+-- identifier can be specified by an environment variable called
+-- `DESKTOP_STARTUP_ID`. For example, let us consider execution of the following
+-- command:
+--
+-- DESKTOP_STARTUP_ID="something_TIME$(date '+%s')" my_command
+--
+-- This should (if the program correctly implements the protocol) result in
+-- `c.startup_id` to at least match `something`.
+-- This identifier can then be used in `awful.rules` to configure the client.
+--
+-- Awesome can automatically set the `DESKTOP_STARTUP_ID` variable. This is used
+-- by `awful.spawn` to specify additional rules for the startup. For example:
+--
+-- awful.spawn("urxvt -e maxima -name CALCULATOR", {
+-- floating = true,
+-- tag = mouse.screen.selected_tag,
+-- placement = awful.placement.bottom_right,
+-- })
+--
+-- This can also be used from the command line:
+--
+-- awesome-client 'awful=require("awful");
+-- awful.spawn("urxvt -e maxima -name CALCULATOR", {
+-- floating = true,
+-- tag = mouse.screen.selected_tag,
+-- placement = awful.placement.bottom_right,
+-- })'
+--
+-- This table contains the client properties that are valid when used the
+-- `sn_rules` or `prop` function argument. They are the same as in `awful.rules`.
+--
+--@DOC_rules_index_COMMON@
+--
-- @author Julien Danjou <julien@danjou.info>
-- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
-- @copyright 2008 Julien Danjou
diff --git a/objects/client.c b/objects/client.c
index ce3e748d..2144c3c5 100644
--- a/objects/client.c
+++ b/objects/client.c
@@ -108,7 +108,28 @@
/** Client class.
*
- * @table object
+ * This table allow to add more dynamic properties to the clients. For example,
+ * doing:
+ *
+ * function awful.client.object.set_my_cool_property(c, value)
+ * -- Some logic code
+ * c._my_secret_my_cool_property = value
+ * c:emit_signal("property::my_cool_property)
+ * end
+ *
+ * function awful.client.object.get_my_cool_property()
+ * return c._my_secret_my_cool_property
+ * end
+ *
+ * Will add a new "my_cool_property" dyanmic property to all client. These
+ * methods will be called when an user does `c.my_cool_property = "something"`
+ * or set them in `awdul.rules`.
+ *
+ * Note that doing this isn't required to set random properties to the client,
+ * it is only useful when setting or getting these properties require code to
+ * executed.
+ *
+ * @table awful.object
*/
/** When a client gains focus.