doc(client): Improve signal documentation
Signed-off-by: Lucas Schwiderski <lucas@lschwiderski.de>
This commit is contained in:
Lucas Schwiderski
parent
fd59806392
commit
bf4ad3310d
101
objects/client.c
101
objects/client.c
|
|
@ -136,7 +136,7 @@ lua_class_t client_class;
|
|||
* @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
|
||||
* initialized, but before clients are added.
|
||||
|
|
@ -145,7 +145,7 @@ lua_class_t client_class;
|
|||
* @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.
|
||||
*
|
||||
|
|
@ -153,23 +153,23 @@ lua_class_t client_class;
|
|||
* @classsignal
|
||||
*/
|
||||
|
||||
/** When a client gains focus.
|
||||
/** Emitted when a client gains focus.
|
||||
* @signal focus
|
||||
* @classsignal
|
||||
*/
|
||||
|
||||
/** Before manage, after unmanage, and when clients swap.
|
||||
/** Emitted before `manage`, after `unmanage`, and when clients swap.
|
||||
* @signal list
|
||||
* @classsignal
|
||||
*/
|
||||
|
||||
/** When 2 clients are swapped
|
||||
/** Emitted when 2 clients are swapped
|
||||
* @tparam client client The other client
|
||||
* @tparam boolean is_source If self is the source or the destination of the swap
|
||||
* @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
|
||||
* recommended to use this to initialize the client content. This use case is
|
||||
|
|
@ -188,7 +188,7 @@ lua_class_t client_class;
|
|||
* @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
|
||||
* depend on the current client should answer this request.
|
||||
|
|
@ -216,32 +216,32 @@ lua_class_t client_class;
|
|||
* @deprecatedsignal unmanage
|
||||
*/
|
||||
|
||||
/** When a mouse button is pressed in a client.
|
||||
/** Emitted when a mouse button is pressed in a client.
|
||||
* @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
|
||||
*/
|
||||
|
||||
/** When the mouse enters a client.
|
||||
/** Emitted when the mouse enters a client.
|
||||
*
|
||||
* @signal mouse::enter
|
||||
*/
|
||||
|
||||
/** When the mouse leaves a client.
|
||||
/** Emitted when the mouse leaves a client.
|
||||
*
|
||||
* @signal mouse::leave
|
||||
*/
|
||||
|
||||
/**
|
||||
* When the mouse moves within a client.
|
||||
* Emitted when the mouse moves within a client.
|
||||
*
|
||||
* @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:**
|
||||
*
|
||||
|
|
@ -279,7 +279,7 @@ lua_class_t client_class;
|
|||
* @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
|
||||
* 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
|
||||
* @tparam client c The client
|
||||
|
|
@ -315,23 +315,38 @@ lua_class_t client_class;
|
|||
* @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
|
||||
* @tparam client c The client requesting a new tag.
|
||||
* @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
|
||||
* @tparam client c The client whose property changed.
|
||||
* @classsignal
|
||||
*/
|
||||
|
||||
/** Emitted during startup to gather the default client mousebindings.
|
||||
*
|
||||
* This signals gives a chance to all module to register new client keybindings.
|
||||
* Assuming the client rules does not overwrite them with the `keys` property,
|
||||
* they will be added to all clients.
|
||||
* This signal gives all modules a chance to register their default client
|
||||
* mousebindings.
|
||||
* They will then be added to all new clients, unless rules overwrite them via
|
||||
* the `buttons` property.
|
||||
*
|
||||
* @signal request::default_mousebindings
|
||||
* @tparam string context The reason why the signal was sent (currently always
|
||||
|
|
@ -339,41 +354,29 @@ lua_class_t client_class;
|
|||
* @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.
|
||||
* Assuming the client rules does not overwrite them with the `keys` property,
|
||||
* they will be added to all clients.
|
||||
* This signal gives all modules a chance to register their default client
|
||||
* keybindings.
|
||||
* They will then be added to all new clients, unless rules overwrite them via
|
||||
* the `keys` property.
|
||||
*
|
||||
* @signal request::default_keybindings
|
||||
* @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
|
||||
* @request client default_keybindings startup granted Sent when AwesomeWM starts.
|
||||
*/
|
||||
|
||||
/** When a client gets tagged.
|
||||
/** Emitted when a client gets tagged.
|
||||
* @signal tagged
|
||||
* @tparam tag t The tag object.
|
||||
*/
|
||||
|
||||
/** When a client gets unfocused.
|
||||
/** Emitted when a client gets unfocused.
|
||||
* @signal unfocus
|
||||
*/
|
||||
|
||||
/** When a client gets untagged.
|
||||
/** Emitted when a client gets untagged.
|
||||
* @signal untagged
|
||||
* @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).
|
||||
*
|
||||
* 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
|
||||
* `client.focus = c`. Setting the focus directly bypasses
|
||||
* 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"
|
||||
* 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`.
|
||||
*
|
||||
* 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
|
||||
* @{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
|
||||
* widget.
|
||||
|
|
@ -649,6 +652,14 @@ lua_class_t client_class;
|
|||
* The available sizes of client icons. This is a table where each entry
|
||||
* contains the width and height of an icon.
|
||||
*
|
||||
* Example:
|
||||
*
|
||||
* {
|
||||
* { 24, 24 },
|
||||
* { 32, 32 },
|
||||
* { 64, 64 },
|
||||
* }
|
||||
*
|
||||
* @property icon_sizes
|
||||
* @tparam table sizes
|
||||
* @propemits false false
|
||||
|
|
|
|||
Loading…
Reference in New Issue