Aire-One
/
awesome
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

doc(client): Improve signal documentation 

Signed-off-by: Lucas Schwiderski <lucas@lschwiderski.de>
This commit is contained in:
Lucas Schwiderski 2021-06-17 12:00:43 +02:00
parent fd59806392
commit bf4ad3310d
No known key found for this signature in database
GPG Key ID: AA12679AAA6DF4D8
1 changed files with 56 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
objects/client.c
View File

@ -136,7 +136,7 @@ lua_class_t client_class;
* @table awful.client.object * @table awful.client.object
*/ */
/** AwesomeWM is about to scan for existing clients. /** Emitted when AwesomeWM is about to scan for existing clients.
* *
* Connect to this signal when code needs to be executed after screens are * Connect to this signal when code needs to be executed after screens are
* initialized, but before clients are added. * initialized, but before clients are added.
@ -145,7 +145,7 @@ lua_class_t client_class;
* @classsignal * @classsignal
*/ */
/** AwesomeWM is done scanning for clients. /** Emitted when AwesomeWM is done scanning for clients.
* *
* This is emitted before the `startup` signal and after the `scanning` signal. * This is emitted before the `startup` signal and after the `scanning` signal.
* *
@ -153,23 +153,23 @@ lua_class_t client_class;
* @classsignal * @classsignal
*/ */
/** When a client gains focus. /** Emitted when a client gains focus.
* @signal focus * @signal focus
* @classsignal * @classsignal
*/ */
/** Before manage, after unmanage, and when clients swap. /** Emitted before `manage`, after `unmanage`, and when clients swap.
* @signal list * @signal list
* @classsignal * @classsignal
*/ */
/** When 2 clients are swapped /** Emitted when 2 clients are swapped
* @tparam client client The other client * @tparam client client The other client
* @tparam boolean is_source If self is the source or the destination of the swap * @tparam boolean is_source If self is the source or the destination of the swap
* @signal swapped * @signal swapped
*/ */
/** When a new client appears and gets managed by Awesome. /** Emitted when a new client appears and gets managed by Awesome.
* *
* This request should be implemented by code which track the client. It isn't * This request should be implemented by code which track the client. It isn't
* recommended to use this to initialize the client content. This use case is * recommended to use this to initialize the client content. This use case is
@ -188,7 +188,7 @@ lua_class_t client_class;
* @classsignal * @classsignal
*/ */
/** When a client is going away. /** Emitted when a client is going away.
* *
* Each places which store `client` objects in non-weak table or whose state * Each places which store `client` objects in non-weak table or whose state
* depend on the current client should answer this request. * depend on the current client should answer this request.
@ -216,32 +216,32 @@ lua_class_t client_class;
* @deprecatedsignal unmanage * @deprecatedsignal unmanage
*/ */
/** When a mouse button is pressed in a client. /** Emitted when a mouse button is pressed in a client.
* @signal button::press * @signal button::press
*/ */
/** When a mouse button is released in a client. /** Emitted when a mouse button is released in a client.
* *
* @signal button::release * @signal button::release
*/ */
/** When the mouse enters a client. /** Emitted when the mouse enters a client.
* *
* @signal mouse::enter * @signal mouse::enter
*/ */
/** When the mouse leaves a client. /** Emitted when the mouse leaves a client.
* *
* @signal mouse::leave * @signal mouse::leave
*/ */
/** /**
* When the mouse moves within a client. * Emitted when the mouse moves within a client.
* *
* @signal mouse::move * @signal mouse::move
*/ */
/** When a client should get activated (focused and/or raised). /** Emitted when a client should get activated (focused and/or raised).
* *
* **Contexts are:** * **Contexts are:**
* *
@ -279,7 +279,7 @@ lua_class_t client_class;
* @classsignal * @classsignal
*/ */
/** When an event could lead to the client being activated. /** Emitted when an event could lead to the client being activated.
* *
* This is an layer "on top" of `request::activate` for event which are not * This is an layer "on top" of `request::activate` for event which are not
* actual request for activation/focus, but where "it would be nice" if the * actual request for activation/focus, but where "it would be nice" if the
@ -300,7 +300,7 @@ lua_class_t client_class;
* *
*/ */
/** When something request a client geometry to be modified. /** Emitted when something request a client's geometry to be modified.
* *
* @signal request::geometry * @signal request::geometry
* @tparam client c The client * @tparam client c The client
@ -315,23 +315,38 @@ lua_class_t client_class;
* @classsignal * @classsignal
*/ */
/** When the client requests to be moved to a tag or needs a new tag. /** Emitted when a client requests to be moved to a tag or needs a new tag.
* *
* @signal request::tag * @signal request::tag
* @tparam client c The client requesting a new tag.
* @classsignal * @classsignal
*/ */
/** When the client requests to become urgent. /** Emitted when any client's `urgent` property changes.
*
* Emitted both when `urgent = true` and `urgent = false`, so you will likely
* want to check `c.urgent` within the signal callback.
*
* client.connect_signal("property::urgent", function(c)
* if c.urgent then
* naughty.notify {
* title = "Urgent client",
* message = c.name,
* }
* end
* end)
* *
* @signal request::urgent * @signal request::urgent
* @tparam client c The client whose property changed.
* @classsignal * @classsignal
*/ */
/** Emitted during startup to gather the default client mousebindings. /** Emitted during startup to gather the default client mousebindings.
* *
* This signals gives a chance to all module to register new client keybindings. * This signal gives all modules a chance to register their default client
* Assuming the client rules does not overwrite them with the `keys` property, * mousebindings.
* they will be added to all clients. * They will then be added to all new clients, unless rules overwrite them via
* the `buttons` property.
* *
* @signal request::default_mousebindings * @signal request::default_mousebindings
* @tparam string context The reason why the signal was sent (currently always * @tparam string context The reason why the signal was sent (currently always
@ -339,41 +354,29 @@ lua_class_t client_class;
* @classsignal * @classsignal
*/ */
/** Emitted during startup to gather the default client keybindings. /** Emitted once when AwesomeWM starts to add default keybindings.
* *
* This signals gives a chance to all module to register new client keybindings. * This signal gives all modules a chance to register their default client
* Assuming the client rules does not overwrite them with the `keys` property, * keybindings.
* they will be added to all clients. * They will then be added to all new clients, unless rules overwrite them via
* the `keys` property.
* *
* @signal request::default_keybindings * @signal request::default_keybindings
* @tparam string context The reason why the signal was sent (currently always * @tparam string context The reason why the signal was sent (currently always
* `startup`).
* @classsignal
*/
/** Sent once when AwesomeWM starts to add default keybindings.
*
* Keybindings can be set directly on clients. Actually, older version of
* AwesomeWM did that through the rules. However this makes it impossible for
* auto-configured modules to add their own keybindings. Using the signals,
* `rc.lua` or any module can cleanly manage keybindings.
*
* @signal request::default_keybindings
* @tparam string context The context (currently always "startup").
* @classsignal * @classsignal
* @request client default_keybindings startup granted Sent when AwesomeWM starts. * @request client default_keybindings startup granted Sent when AwesomeWM starts.
*/ */
/** When a client gets tagged. /** Emitted when a client gets tagged.
* @signal tagged * @signal tagged
* @tparam tag t The tag object. * @tparam tag t The tag object.
*/ */
/** When a client gets unfocused. /** Emitted when a client gets unfocused.
* @signal unfocus * @signal unfocus
*/ */
/** When a client gets untagged. /** Emitted when a client gets untagged.
* @signal untagged * @signal untagged
* @tparam tag t The tag object. * @tparam tag t The tag object.
*/ */
@ -404,7 +407,7 @@ lua_class_t client_class;
/** /**
* The focused `client` or nil (in case there is none). * The focused `client` or nil (in case there is none).
* *
* It is not recommanded to set the focused client using * It is not recommended to set the focused client using
* this property. Please use `c:activate{}` instead of * this property. Please use `c:activate{}` instead of
* `client.focus = c`. Setting the focus directly bypasses * `client.focus = c`. Setting the focus directly bypasses
* all the filters and emits fewer signals, which tend to * all the filters and emits fewer signals, which tend to
@ -591,12 +594,12 @@ lua_class_t client_class;
*/ */
/** /**
* The machine client is running on. * The machine the client is running on.
* *
* X11 windows can "live" in another computer but shown * X11 windows can "live" in one computer but be shown
* in another one. This is called "network transparency" * in another one. This is called "network transparency"
* and is either used directly by allowing remote windows * and is either used directly by allowing remote windows
* using the `xhosts` command for using proxies such as * using the `xhosts` command or using proxies such as
* `ssh -X` or `ssh -Y`. * `ssh -X` or `ssh -Y`.
* *
* According to EWMH, this property contains the value * According to EWMH, this property contains the value
@ -622,7 +625,7 @@ lua_class_t client_class;
* This property holds the client icon closest to the size configured via * This property holds the client icon closest to the size configured via
* @{awesome.set_preferred_icon_size}. * @{awesome.set_preferred_icon_size}.
* *
* It is not a path or an "real" file. Rather, it is already a bitmap surface. * It is not a path or a "real" file. Rather, it is already a bitmap surface.
* *
* Typically you would want to use @{awful.widget.clienticon} to get this as a * Typically you would want to use @{awful.widget.clienticon} to get this as a
* widget. * widget.
@ -649,6 +652,14 @@ lua_class_t client_class;
* The available sizes of client icons. This is a table where each entry * The available sizes of client icons. This is a table where each entry
* contains the width and height of an icon. * contains the width and height of an icon.
* *
* Example:
*
* {
* { 24, 24 },
* { 32, 32 },
* { 64, 64 },
* }
*
* @property icon_sizes * @property icon_sizes
* @tparam table sizes * @tparam table sizes
* @propemits false false * @propemits false false