-
Notifications
You must be signed in to change notification settings - Fork 598
/
client.c
4686 lines (4238 loc) · 152 KB
/
client.c
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*
* client.c - client management
*
* Copyright © 2007-2009 Julien Danjou <[email protected]>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License along
* with this program; if not, write to the Free Software Foundation, Inc.,
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*
*/
/** A process window managed by AwesomeWM.
*
* 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'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`).
*
* Some signal names are starting with a dot. These dots are artefacts from
* the documentation generation, you get the real signal name by
* removing the starting dot.
*
* Accessing client objects can be done in multiple ways depending on the
* 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`:
*
* for _, c in ipairs(client.get()) do
* -- do something
* end
*
* To execute a callback when a new client is added, use the `manage` signal:
*
* client.connect_signal("request::manage", function(c)
* -- do something
* end)
*
* 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 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`.
*
* @DOC_uml_nav_tables_client_EXAMPLE@
*
* @author Julien Danjou <[email protected]>
* @copyright 2008-2009 Julien Danjou
* @coreclassmod client
*/
#include "objects/client.h"
#include "common/atoms.h"
#include "common/xutil.h"
#include "event.h"
#include "ewmh.h"
#include "objects/drawable.h"
#include "objects/screen.h"
#include "objects/tag.h"
#include "property.h"
#include "spawn.h"
#include "systray.h"
#include "xwindow.h"
#include "math.h"
#include <xcb/xcb_atom.h>
#include <xcb/shape.h>
#include <cairo-xcb.h>
lua_class_t client_class;
/** Client class.
*
* This table allow to add more dynamic properties to the clients. For example,
* doing:
*
* function awful.client.object.set_my_cool_property(c, value)
* -- Some logic code
* c._my_secret_my_cool_property = value
* c:emit_signal("property::my_cool_property)
* end
*
* function awful.client.object.get_my_cool_property()
* return c._my_secret_my_cool_property
* end
*
* Will add a new "my_cool_property" dyanmic property to all client. These
* methods will be called when an user does `c.my_cool_property = "something"`
* or set them in `awdul.rules`.
*
* Note that doing this isn't required to set random properties to the client,
* it is only useful when setting or getting these properties require code to
* executed.
*
* @table awful.client.object
*/
/** 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.
*
* @signal scanning
* @classsignal
*/
/** Emitted when AwesomeWM is done scanning for clients.
*
* This is emitted before the `startup` signal and after the `scanning` signal.
*
* @signal scanned
* @classsignal
*/
/** Emitted when a client gains focus.
* @signal focus
* @classsignal
*/
/** Emitted before `request::manage`, after `request::unmanage`,
* and when clients swap.
* @signal list
* @classsignal
*/
/** 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
*/
/** 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
* a better fit for `ruled.client`, which has built-in dependency management.
* Using this request to mutate the client state will likely conflict with
* `ruled.client`.
*
* @signal request::manage
* @tparam client c The client.
* @tparam string context What created the client. It is currently either "new"
* or "startup".
* @tparam table hints More metadata (currently empty, it exists for compliance
* with the other `request::` signals).
* @request client border added granted When a new client needs a its initial
* border settings.
* @classsignal
*/
/** 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.
*
* The contexts are:
*
* * **user**: `c:unmanage()` was called.
* * **reparented**: The window was reparented to another window. It is no
* longer a stand alone client.
* * **destroyed**: The window was closed.
*
* @signal request::unmanage
* @tparam client c The client.
* @tparam string context Why was the client unmanaged.
* @tparam table hints More metadata (currently empty, it exists for compliance
* with the other `request::` signals).
* @classsignal
*/
/** Use `request::manage`.
* @deprecatedsignal manage
*/
/** Use `request::unmanage`.
* @deprecatedsignal unmanage
*/
/** Emitted when a mouse button is pressed in a client.
* @signal button::press
*/
/** Emitted when a mouse button is released in a client.
*
* @signal button::release
*/
/** Emitted when the mouse enters a client.
*
* @signal mouse::enter
*/
/** Emitted when the mouse leaves a client.
*
* @signal mouse::leave
*/
/**
* Emitted when the mouse moves within a client.
*
* @signal mouse::move
*/
/** Emitted when a client should get activated (focused and/or raised).
*
* **Contexts are:**
*
* * *ewmh*: When a client asks for focus (from `X11` events).
* * *autofocus.check_focus*: When autofocus is enabled (from
* `awful.autofocus`).
* * *autofocus.check_focus_tag*: When autofocus is enabled
* (from `awful.autofocus`).
* * *client.jumpto*: When a custom lua extension asks a client to be focused
* (from `client.jump_to`).
* * *client.swap.global_bydirection*: When client swapping requires a focus
* change (from `awful.client.swap.bydirection`).
* * *client.movetotag*: When a client is moved to a new tag
* (from `client.move_to_tag`).
* * *client.movetoscreen*: When the client is moved to a new screen
* (from `client.move_to_screen`).
* * *client.focus.byidx*: When selecting a client using its index
* (from `awful.client.focus.byidx`).
* * *client.focus.history.previous*: When cycling through history
* (from `awful.client.focus.history.previous`).
* * *menu.clients*: When using the builtin client menu
* (from `awful.menu.clients`).
* * *rules*: When a new client is focused from a rule (from `ruled.client`).
* * *screen.focus*: When a screen is focused (from `awful.screen.focus`).
*
* Default implementation: `awful.ewmh.activate`.
*
* To implement focus stealing filters see `awful.ewmh.add_activate_filter`.
*
* @signal request::activate
* @tparam client c The client.
* @tparam string context The context where this signal was used.
* @tparam[opt] table hints A table with additional hints:
* @tparam[opt=false] boolean hints.raise Should the client be raised?
* @request client activate ewmh granted When the client asks to be activated.
* @classsignal
*/
/** 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
* client got the focus. This includes the focus-follow-mouse model and focusing
* previous clients when the selected tag changes.
*
* This idea is that `request::autoactivate` will emit `request::activate`.
* However it is much easier to replace the handler for `request::autoactivate`
* than it is to replace the handler for `request::activate`. Thus it provides
* a nice abstraction to simplify handling the focus when switching tags or
* moving the mouse.
*
* @signal request::autoactivate
* @tparam client c The client.
* @tparam string context The context where this signal was used.
* @tparam[opt] table hints A table with additional hints:
* @tparam[opt=false] boolean hints.raise Should the client be raised?
* @classsignal
*
*/
/** Emitted when something request a client's geometry to be modified.
*
* @signal request::geometry
* @tparam client c The client
* @tparam string context Why and what to resize. This is used for the
* handlers to know if they are capable of applying the new geometry.
* @tparam[opt={}] table hints Additional arguments. Each context handler may
* interpret this differently.
* @request client geometry client_maximize_horizontal granted When a client
* (programmatically) asks for the maximization to be changed.
* @request client geometry client_maximize_vertical granted When a client
* (programmatically) asks for the maximization to be changed.
* @classsignal
*/
/** 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.
* @tparam[opt] tag tag A preferred tag.
* @tparam[opt] table hints
* @tparam[opt] string hints.reason
* @tparam[opt] screen hints.screen
* @classsignal
*/
/** 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 once to request default client mousebindings during the initial
* startup sequence.
*
* 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
* `startup`).
* @classsignal
*/
/** Emitted once to request default client keybindings during the initial
* startup sequence.
*
* 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
* @classsignal
* @request client default_keybindings startup granted Sent when AwesomeWM starts.
*/
/** Emitted when a client gets tagged.
* @signal tagged
* @tparam tag t The tag object.
* @see tags
* @see untagged
*/
/** Emitted when a client gets unfocused.
* @signal unfocus
*/
/** Emitted when a client gets untagged.
* @signal untagged
* @tparam tag t The tag object.
* @see tags
* @see tagged
*/
/**
* Emitted when the client is raised within its layer.
*
* @signal raised
* @see below
* @see above
* @see ontop
* @see raise
* @see lower
* @see lowered
*/
/** Emitted when the client is lowered within its layer.
*
* @signal lowered
* @see below
* @see above
* @see ontop
* @see raise
* @see lower
* @see raised
*/
/**
* The focused `client` or nil (in case there is none).
*
* It is not recommended to set the focused client using
* this property. Please use @{client.activate} instead of
* `client.focus = c`. Setting the focus directly bypasses
* all the filters and emits fewer signals, which tend to
* cause unwanted side effects and make it harder to alter
* the code behavior in the future. It usually takes *more*
* code to use this rather than @{client.activate} because all
* the boilerplate code (such as `c:raise()`) needs to be
* added everywhere.
*
* The main use case for this field is to check *when* there
* is an active client.
*
* if client.focus ~= nil then
* -- do something
* end
*
* If you want to check if a client is active, use:
*
* if c.active then
* -- do something
* end
*
* @tfield client focus
* @see active
* @see activate
* @see request::activate
*/
/**
* The X window id.
*
* This is rarely useful, but some DBus protocols will
* have this ID in their API, so it can be useful when
* writing AwesomeWM bindings for them.
*
* @property window
* @tparam integer window
* @propertydefault This is generated by X11.
* @negativeallowed false
* @propemits false false
* @readonly
*/
/**
* The client title.
*
* This is the text which will be shown in `awful.widget.tasklist`
* and `awful.titlebar.widget.titlewidget`.
*
* @property name
* @tparam string name
* @propertydefault This is provided by the application.
* @propemits false false
* @see awful.titlebar
* @see awful.widget.tasklist
*/
/**
* True if the client does not want to be in taskbar.
*
* Some clients, like docked bars or some `sticky` clients
* such as wallpaper sensors like Conky have no value in
* 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. Clients can modify this
* state through this property.
*
* @DOC_awful_client_skip_tasklist1_EXAMPLE@
*
* @property skip_taskbar
* @tparam[opt=false] boolean skip_taskbar
* @propemits false false
* @see sticky
* @see hidden
* @see unmanage
*/
/**
* The window type.
*
* This is useful in, among other places, the `ruled.client` rules to apply
* different properties depending on the client types. It is also used
* throughout the API to alter the client (and `wibox`) behavior depending on
* the `type`. For example, clients with the `dock` type are placed on the side
* of the screen while other like `combo` are totally ignored and never
* considered `client`s in the first place.
*
* Valid types are:
*
* <table class='widget_list' border=1>
* <tr style='font-weight: bold;'>
* <th align='center'>Name</th>
* <th align='center'>Description</th>
* </tr>
* <tr><td><b>desktop</b></td><td>The root client, it cannot be moved or resized.</td></tr>
* <tr><td><b>dock</b></td><td>A client attached to the side of the screen.</td></tr>
* <tr><td><b>splash</b></td><td>A client, usually without titlebar shown when an application starts.</td></tr>
* <tr><td><b>dialog</b></td><td>A dialog, see `transient_for`.</td></tr>
* <tr><td><b>menu</b></td><td>A context menu.</td></tr>
* <tr><td><b>toolbar</b></td><td>A floating toolbar.</td></tr>
* <tr><td><b>utility</b></td><td></td></tr>
* <tr><td><b>dropdown_menu</b></td><td>A context menu attached to a parent position.</td></tr>
* <tr><td><b>popup_menu</b></td><td>A context menu.</td></tr>
* <tr><td><b>notification</b></td><td>A notification popup.</td></tr>
* <tr><td><b>combo</b></td><td>A combobox list menu.</td></tr>
* <tr><td><b>dnd</b></td><td>A drag and drop indicator.</td></tr>
* <tr><td><b>normal</b></td><td>A normal application main window.</td></tr>
* </table>
*
* More information can be found [here](https://specifications.freedesktop.org/wm-spec/wm-spec-latest.html#idm140200472629520)
*
* @property type
* @tparam string type
* @propemits false false
* @propertydefault This is provided by the application.
* @readonly
* @see ruled.client
*/
/**
* The client class.
*
* 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`, 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:
*
* xprop WM_CLASS
*
* The class will be the second string.
*
* This *should* never change after the client is created, but some
* 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
* and point to ICCCM §4.1.2.5.
* It tends to break `ruled.client` and other AwesomeWM APIs.
*
* @property class
* @tparam string class
* @propemits false false
* @propertydefault This is provided by the application.
* @readonly
* @see instance
* @see ruled.client
*/
/**
* The client instance.
*
* The `instance` is a subtype of the `class`. Each `class` can have
* multiple instances. This is useful in the `ruled.client` rules to
* filter clients and apply different properties to them.
*
* To get a client instance from the command line, use the command:
*
* xprop WM_CLASS
*
* 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
* @propertydefault This is provided by the application.
* @propemits false false
* @readonly
* @see class
* @see ruled.client
*/
/**
* The client PID, if available.
*
* This will never change.
*
* @property pid
* @tparam integer pid
* @negativeallowed false
* @propertydefault This is randomly assigned by the kernel.
* @propemits false false
* @readonly
*/
/**
* The window role, if available.
*
* @property role
* @tparam string role
* @propertydefault This is provided by the application.
* @propemits false false
* @readonly
* @see instance
* @see class
*/
/**
* The machine the client is running on.
*
* 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 or 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
* @propertydefault This is the hostname unless the client is from an
* SSH session or using the rarely used direct X11 network socket.
* @propemits false false
* @readonly
*/
/**
* The client name when iconified.
*
* @property icon_name
* @tparam string icon_name
* @propertydefault This is provided by the application.
* @propemits false false
* @readonly
*/
/**
* The client icon as a surface.
*
* This property holds the client icon closest to the size configured via
* @{awesome.set_preferred_icon_size}.
*
* 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.
*
* Working with icons is tricky because their surfaces do not use reference
* counting correctly. If `gears.surface(c.icon)` is called multiple time on
* the same icon, it will cause a double-free error and Awesome will crash. To
* get a copy of the icon, you can use:
*
* local s = gears.surface(c.icon)
* local img = cairo.ImageSurface.create(cairo.Format.ARGB32, s:get_width(), s:get_height())
* local cr = cairo.Context(img)
* cr:set_source_surface(s, 0, 0)
* cr:paint()
*
* (Note that `awesome.set_preferred_icon_size` defaults to `0` if it wasn't
* set. It means that, by default, the preferred icon provided will be the
* smallest available)
*
* @property icon
* @tparam image icon
* @propertydefault This is provided by the application.
* @propemits false false
* @usage local ib = wibox.widget.imagebox(c.icon)
* @see awful.widget.clienticon
*/
/**
* 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 icon_sizes
* @tablerowtype A list of tables. Each table has the following rows:
* @tablerowkey integer 1 The width value.
* @tablerowkey integer 2 The height value.
* @propertydefault This is provided by the application.
* @propemits false false
* @readonly
* @see awful.widget.clienticon
* @see get_icon
*/
/**
* Client screen.
*
* The `screen` corresponds to the top-left corner of the window.
*
* 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 that
* a client's position and its screen are consistent.
*
* @DOC_sequences_client_screen_EXAMPLE@
*
* @property screen
* @tparam screen screen
* @propertydefault This usually correspond to where the top-left (or other
* gravities) is placed. Then it is mapped to the screen `geometry`.
* @propemits false false
* @see move_to_screen
*/
/**
* Define if the client must be hidden (Never mapped, invisible in taskbar).
*
* @property hidden
* @tparam[opt=false] boolean hidden
* @propemits false false
* @see minimized
* @see skip_taskbar
* @see unmanage
*/
/**
* Define if the client must be iconified (Only visible in taskbar).
*
* Minimized clients are still part of tags and screens, but
* they are not displayed. You can unminimize using `c.minimized = false`,
* but if you also want to set the focus, it is better to use:
*
* c:activate { context = "unminimized", raise = true }
*
* @DOC_sequences_client_minimize1_EXAMPLE@
*
* @property minimized
* @tparam[opt=false] boolean minimized
* @propemits false false
* @see hidden
* @see isvisible
* @see activate
*/
/**
* Honor size hints, e.g. respect size ratio.
*
* For example, a terminal such as `xterm` require the client size to be a
* multiple of the character size. Honoring size hints will cause the terminal
* window to have a small gap at the bottom.
*
* This is enabled by default. To disable it by default, see `ruled.client`.
*
* @property size_hints_honor
* @tparam[opt=true] boolean size_hints_honor
* @propemits false false
* @see size_hints
*/
/**
* The client border width.
*
* When manually set (for example, in `ruled.client` rules), this value
* will be static. Otherwise, it is controlled by many `beautiful` variables.
*
* Be careful, the borders are **around** the geometry, not part of it. If
* you want more fancy border, use the `awful.titlebar` API to create
* titlebars on each side of the client.
*
* @DOC_awful_client_border_width_EXAMPLE@
*
* @property border_width
* @tparam[opt=nil] integer|nil border_width
* @propertytype nil Let AwesomeWM manage it based on the client state.
* @negativeallowed false
* @propertyunit pixel
* @propemits false false
* @usebeautiful beautiful.border_width_active
* @usebeautiful beautiful.border_width_normal
* @usebeautiful beautiful.border_width_new
* @usebeautiful beautiful.border_width_urgent
* @usebeautiful beautiful.border_width_floating
* @usebeautiful beautiful.border_width_floating_active
* @usebeautiful beautiful.border_width_floating_normal
* @usebeautiful beautiful.border_width_floating_new
* @usebeautiful beautiful.border_width_floating_urgent
* @usebeautiful beautiful.border_width_maximized
* @usebeautiful beautiful.border_width_maximized_active
* @usebeautiful beautiful.border_width_maximized_normal
* @usebeautiful beautiful.border_width_maximized_new
* @usebeautiful beautiful.border_width_maximized_urgent
* @usebeautiful beautiful.border_width_fullscreen
* @usebeautiful beautiful.border_width_fullscreen_active
* @usebeautiful beautiful.border_width_fullscreen_normal
* @usebeautiful beautiful.border_width_fullscreen_new
* @usebeautiful beautiful.border_width_fullscreen_urgent
* @usebeautiful beautiful.fullscreen_hide_border Hide the border on fullscreen clients.
* @usebeautiful beautiful.maximized_hide_border Hide the border on maximized clients.
* @see request::border
* @see awful.permissions.update_border
* @see border_color
*/
/**
* The client border color.
*
* @DOC_awful_client_border_color_EXAMPLE@
*
* Note that setting this directly will override and disable all related theme
* variables.
*
* Setting a transparent color (e.g. to implement dynamic borders without size
* changes) is supported, but requires the color to be set to `#00000000`
* specifically. Other RGB colors with an alpha of `0` won't work.
*
* @property border_color
* @tparam[opt=nil] color|nil border_color
* @propertytype nil Let AwesomeWM manage it based on the client state.
* @propertydefault
* @propemits false false
* @usebeautiful beautiful.border_color_marked The fallback color when the
* client is marked.
* @usebeautiful beautiful.border_color_active The fallback color when the
* client is active (focused).
* @usebeautiful beautiful.border_color_normal The fallback color when the
* client isn't active/floating/new/urgent/maximized/floating/fullscreen.
* @usebeautiful beautiful.border_color_new The fallback color when the
* client is new.
* @usebeautiful beautiful.border_color_urgent The fallback color when the
* client is urgent.
* @usebeautiful beautiful.border_color_floating The fallback color when the
* client is floating and the other colors are not set.
* @usebeautiful beautiful.border_color_floating_active The color when the
* client is floating and is active (focused).
* @usebeautiful beautiful.border_color_floating_normal The color when the
* client is floating and not new/urgent/active.
* @usebeautiful beautiful.border_color_floating_new
* @usebeautiful beautiful.border_color_floating_urgent The color when the
* client is floating and urgent.
* @usebeautiful beautiful.border_color_maximized
* @usebeautiful beautiful.border_color_maximized_active
* @usebeautiful beautiful.border_color_maximized_normal
* @usebeautiful beautiful.border_color_maximized_new
* @usebeautiful beautiful.border_color_maximized_urgent The color when the
* client is urbent and maximized.
* @usebeautiful beautiful.border_color_fullscreen
* @usebeautiful beautiful.border_color_fullscreen_active
* @usebeautiful beautiful.border_color_fullscreen_normal
* @usebeautiful beautiful.border_color_fullscreen_new
* @usebeautiful beautiful.border_color_fullscreen_urgent The color when the
* client is fullscreen and urgent.
* @see request::border
* @see awful.permissions.update_border
* @see gears.color
* @see border_width
*/
/**
* Set to `true` when the client ask for attention.
*
* The urgent state is the visual equivalent of the "bell" noise from
* old computer. It is set by the client when their state changed and
* they need attention. For example, a chat client will set it when
* a new message arrive. Some terminals, like `rxvt-unicode`, will also
* set it when calling the `bell` command.
*
* There is many ways an urgent client can become for visible:
*
* * Highlight in the `awful.widget.taglist` and `awful.widget.tasklist`
* * Highlight in the `awful.titlebar`
* * Highlight of the client border color (or width).
* * Accessible using `Mod4+u` in the default config.
* * Emit the `property::urgent` signal.
*
* @DOC_awful_client_urgent1_EXAMPLE@
*
* @property urgent
* @tparam[opt=false] boolean urgent
* @propemits false false
* @request client border active granted When a client becomes active and is no
* longer urgent.
* @request client border inactive granted When a client stop being active and
* is no longer urgent.
* @request client border urgent granted When a client stop becomes urgent.
* @see request::border
* @see awful.client.urgent.jumpto
* @usebeautiful beautiful.border_color_urgent The fallback color when the
* client is urgent.
* @usebeautiful beautiful.border_color_floating_urgent The color when the
* client is floating and urgent.
* @usebeautiful beautiful.border_color_maximized_urgent The color when the
* client is urbent and maximized.
* @usebeautiful beautiful.border_color_fullscreen_urgent The color when the
* client is fullscreen and urgent.
* @usebeautiful beautiful.border_width_urgent The fallback border width when
* the client is urgent.
* @usebeautiful beautiful.border_width_floating_urgent The border width when
* the client is floating and urgent.
* @usebeautiful beautiful.border_width_maximized_urgent The border width when
* the client is maximized and urgent.
* @usebeautiful beautiful.border_width_fullscreen_urgent The border width when
* the client is fullscreen and urgent.
* @usebeautiful beautiful.titlebar_fg_urgent
* @usebeautiful beautiful.titlebar_bg_urgent
* @usebeautiful beautiful.titlebar_bgimage_urgent
* @usebeautiful beautiful.fg_urgent
* @usebeautiful beautiful.bg_urgent
*/
/**
* A cairo surface for the client window content.
*
* To get the screenshot, use:
*
* gears.surface(c.content)
*
* To save it, use:
*
* gears.surface(c.content):write_to_png(path)
*
* 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.
*
* @property content
* @tparam raw_curface content
* @propertydefault This is a live surface. Always use `gears.surface` to take
* a snapshot.
* @readonly
* @see gears.surface
*/
/**
* The client opacity.
*
* The opacity only works when a compositing manager, such as
* [picom](https://github.com/yshui/picom/), is used. Otherwise,
* the clients will remain opaque.
*
* @DOC_awful_client_opacity1_EXAMPLE@
*
* @property opacity
* @tparam[opt=1.0] number opacity
* @rangestart 0.0 Transparent.
* @rangestop 1.0 Opaque.
* @propemits false false
* @see request::border
* @see awesome.composite_manager_running
*/
/**
* The client is on top of every other windows.
*
* @property ontop
* @tparam[opt=false] boolean ontop
* @propemits false false
* @see below
* @see above
*/
/**
* The client is above normal windows.
*
* @property above
* @tparam[opt=false] boolean above
* @propemits false false
* @see below
* @see ontop
*/
/**