doc: improve client class (#1221)

This commit is contained in:
Daniel Hahler 2016-11-16 11:14:19 +01:00 committed by GitHub
parent 9b335b5bf1
commit 55689b4cc7
1 changed files with 25 additions and 22 deletions

View File

@ -21,21 +21,25 @@
/** A process window.
*
* Clients are the name used by Awesome (and X11) to refer to a window. An
* application can have multiple clients (like for dialogs) or none at all
* (like command line applications). Clients are usually grouped by classes. A
* class is the name used by X11 to help window manager distinguish between
* window and write rules for them. See the `xprop` command line application. A
* client also have a `type` and `size_hints` used to define its behavior.
* Clients are the name used by Awesome (and X11) to refer to a window.
*
* A program can have multiple clients (e.g. for dialogs) or none at all (e.g.
* command line applications).
* Clients are usually grouped by classes.
* A class is the name used by X11 to help the window manager distinguish
* between windows and write rules for them. A client's behavior is also
* defined by its `type` and `size_hints` properties.
* See the `xprop` command line application to query properties for a client.
*
* ![Client geometry](../images/client_geo.svg)
*
* The client `:geometry()` return a table with *x*, *y*, *width* and *height*.
* The area returned **exclude the border width**. All clients also have a
* `shape_bounding` and `shape_clip` used to "crop" the client content. Finally,
* each clients can have titlebars (see `awful.titlebar`).
* The client's `:geometry()` function returns a table with *x*, *y*, *width*
* and *height*. The area returned **excludes the border width**.
* All clients also have a `shape_bounding` and `shape_clip` used to "crop" the
* client's content.
* Finally, each clients can have titlebars (see `awful.titlebar`).
*
* Furthermore to the classes described here, one can also use signals as
* Additionally to the classes described here, one can also use signals as
* described in @{signals} and X properties as described in @{xproperties}.
*
* Some signal names are starting with a dot. These dots are artefacts from
@ -43,41 +47,40 @@
* removing the starting dot.
*
* Accessing client objects can be done in multiple ways depending on the
* context. To get the current focused client, use:
* context.
* To get the currently focused client:
*
* local c = client.focus
*
* if c then
* -- do something
* end
*
* To get a list of all clients, use `client:get`
* To get a list of all clients, use `client:get`:
*
* for _, c in ipairs(client.get()) do
* -- do something
* end
*
* To get a callback when a new client is added, use the `manage` signal:
* To execute a callback when a new client is added, use the `manage` signal:
*
* client.connect_signal("manage", function(c)
* -- do something
* end)
*
* To be notified a property changed in a client, use:
* To be notified when a property of a client changed:
*
* client.connect_signal("property::name", function(c)
* -- do something
* end)
*
* To be notified when a property change for a specific client (assuming it is
* stored in the variable `c`), use:
* To be notified when a property of a specific client `c` changed:
*
* c:connect_signal("property::name", function()
* -- do something
* end)
*
* To get all the clients for a screen, use either `screen.clients` or
* `screen.tiled_clients`
* To get all the clients for a screen use either `screen.clients` or
* `screen.tiled_clients`.
*
* @author Julien Danjou <julien@danjou.info>
* @copyright 2008-2009 Julien Danjou