doc: Improve the client documentation.
This commit is contained in:
Uli Schlachter
Emmanuel Lepage Vallee
parent
cb9c33cda8
commit
8df463f971
|
|
@ -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.
|
||||
--
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue