diff --git a/docs/common/rule.ldoc b/docs/common/rule.ldoc index 082458a3..357b27fc 100644 --- a/docs/common/rule.ldoc +++ b/docs/common/rule.ldoc @@ -1,6 +1,6 @@ --- ---- A table which content will be used to set the target object properties. +--- A table whose content will be used to set the target object properties. -- -- @rulecomponent properties -- @param table @@ -14,7 +14,7 @@ -- @param table -- @see properties ---- A table which content will be compared to the target object current properties. +--- A table whose content will be compared to the target object current properties. -- -- @rulecomponent rule -- @param table @@ -50,7 +50,7 @@ -- @see rule -- @see except ---- A table which content will be compared to the target object current properties. +--- A table whose content will be compared to the target object current properties. -- -- The comparison will be made using the lesser (`<`) operator. -- @@ -59,7 +59,7 @@ -- @see rule -- @see except ---- A table which content will be compared to the target object current properties. +--- A table whose content will be compared to the target object current properties. -- -- The comparison will be made using the greater (`>`) operator. -- diff --git a/lib/awful/client.lua b/lib/awful/client.lua index 1a7e51f9..243b9fbc 100644 --- a/lib/awful/client.lua +++ b/lib/awful/client.lua @@ -1422,12 +1422,12 @@ 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. +-- This will traverse the chain formed by the `transient_for` property of `self` +-- until a client `c` with `c.transient_for == c2` is found. The found client +-- `c` is returned. If no client is found, `nil` is returned. +-- +-- While `transient_for` chains are technically possible, they are unlikely, so +-- the most likely return values are `self` and `nil`. -- -- @method is_transient_for -- @tparam client c2 The parent client to check. diff --git a/objects/client.c b/objects/client.c index bde2695b..7b2d3a20 100644 --- a/objects/client.c +++ b/objects/client.c @@ -446,8 +446,8 @@ /** * The client title. * - * This is the text which will be shown in the `awful.widget.tasklist` - * and the `awful.titlebar`. + * This is the text which will be shown in `awful.widget.tasklist` + * and `awful.titlebar.widget.titlewidget`. * * @property name * @tparam string name @@ -464,7 +464,8 @@ * the `awful.widget.tasklist` and should not be shown there. * * The default value of this property reflects the value of the - * `_NET_WM_STATE_SKIP_TASKBAR` X11 protocol xproperty. + * `_NET_WM_STATE_SKIP_TASKBAR` X11 protocol xproperty. Clients can modify this + * state through this property. * * @property skip_taskbar * @tparam[opt=false] boolean skip_taskbar @@ -472,8 +473,6 @@ * @see sticky */ -//TODO v5: Rename to skip_tasklist? - /** * The window type. * @@ -519,7 +518,7 @@ * * 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" + * is also useful, along with `instance`, to implement "windows counter" * used in many popular docks and Alt-Tab like popups. * * To get a client class from the command line, use the command: @@ -532,7 +531,8 @@ * 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. + * applications change their classes, please report a bug to them + * and point to ICCCM §4.1.2.5. * It tends to break `ruled.client` and other AwesomeWM APIs. * * @property class @@ -555,6 +555,12 @@ * * The instance will be the first string. * + * This *should* never change after the client is created. 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 and point to ICCCM §4.1.2.5. + * It tends to break `ruled.client` and other AwesomeWM APIs. + * * @property instance * @tparam string instance * @propemits false false @@ -591,6 +597,10 @@ * using the `xhosts` command for using proxies such as * `ssh -X` or `ssh -Y`. * + * According to EWMH, this property contains the value + * returned by `gethostname()` on the computer that the + * client is running on. + * * @property machine * @tparam string machine * @propemits false false @@ -652,8 +662,8 @@ * 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. + * cause several other changes to the state in order to ensure that + * a client's position and its screen are consistent. * * @property screen * @tparam screen screen @@ -736,13 +746,16 @@ * * 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. + * Please note that this only creates a new cairo surface + * referring to the client's content. This means that + * changes to the client's content may or may not become + * visible in the returned surface. If you want to take a + * screenshot, a copy of the surface's content needs to + * be taken. Note that the content of parts of a window + * that are currently not visible are undefined. + * + * The only way to get an animated client screenshot widget is to poll this + * property multiple time per seconds. This is obviously a bad idea. * * This property has no signals when the content changes. * @@ -843,20 +856,16 @@ * 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 + * client. If the client is also `modal`, then 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 + * This is common for "Save as" dialogs or other dialogs where it + * is not 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` + * However, `modal` is not 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 * @tparam client transient_for * @propemits false false @@ -870,6 +879,8 @@ * Window identification unique to a group of windows. * * This is the ID of the group window, not a client object. + * The group window is most likely not a visible client, but + * only an invisible and internal window. * * @property group_window * @tparam integer group_window @@ -893,6 +904,9 @@ /** * A table with size hints of the client. * + * For details on the meaning of the fields, refer to ICCCM § 4.1.2.3 + * `WM_NORMAL_HINTS`. + * * 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 @@ -931,6 +945,8 @@ * @tparam[opt] integer|nil hints.min_aspect_den * @tparam[opt] integer|nil hints.max_aspect_num * @tparam[opt] integer|nil hints.max_aspect_den + * @tparam[opt] integer|nil hints.base_width + * @tparam[opt] integer|nil hints.base_height * @propemits false false * @see size_hints_honor * @see geometry @@ -990,10 +1006,10 @@ * 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 + * is not 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` + * However, `modal` is not 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. * @@ -1006,7 +1022,7 @@ /** * True if the client can receive the input focus. * - * The client wont get focused even when the user + * The client will not get focused even when the user * click on it. * * @property focusable @@ -1026,7 +1042,7 @@ * * 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 + * in the titlebars and a compositing manager. For the vast majority of use * cases, use the `shape` property. * * @property shape_bounding @@ -1204,6 +1220,8 @@ * keys to define how much space of the screen `workarea` this client * should reserve for itself. * + * This corresponds to EWMH's `_NET_WM_STRUT` and `_NET_WM_STRUT_PARTIAL`. + * * @tparam table struts A table with new strut values, or none. * @treturn table A table with strut values. * @method struts