aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorLibravatar Brian Ashworth <bosrsf04@gmail.com>2019-02-27 13:23:10 -0500
committerLibravatar Drew DeVault <sir@cmpwn.com>2019-03-04 12:50:43 -0500
commit7371ed55fef9dc4a2ae63fee34e2e55d631bda15 (patch)
tree1ad246ca7ed3ca15c673edda193d80b925a9e32c
parentconfig: remove double assignement to result in get_output_config (diff)
downloadsway-7371ed55fef9dc4a2ae63fee34e2e55d631bda15.tar.gz
sway-7371ed55fef9dc4a2ae63fee34e2e55d631bda15.tar.zst
sway-7371ed55fef9dc4a2ae63fee34e2e55d631bda15.zip
Add sway-ipc.7.scd to document IPC protocol
This add `sway-ipc.7.scd` that documents the IPC protocol. This also increased the minimum scdoc version from 1.8.1 to 1.9.0 to allow for table cells to be continued on the following line
-rw-r--r--README.md2
-rw-r--r--meson.build1
-rw-r--r--sway/sway-ipc.7.scd1578
-rw-r--r--sway/sway.1.scd1
-rw-r--r--sway/sway.5.scd2
-rw-r--r--swaymsg/swaymsg.1.scd4
6 files changed, 1586 insertions, 2 deletions
diff --git a/README.md b/README.md
index 239e7e3e..832a3096 100644
--- a/README.md
+++ b/README.md
@@ -40,7 +40,7 @@ Install dependencies:
40* pango 40* pango
41* cairo 41* cairo
42* gdk-pixbuf2 \*\* 42* gdk-pixbuf2 \*\*
43* [scdoc](https://git.sr.ht/~sircmpwn/scdoc) >= 1.8.1 (optional: man pages) \* 43* [scdoc](https://git.sr.ht/~sircmpwn/scdoc) >= 1.9.0 (optional: man pages) \*
44* git \* 44* git \*
45 45
46_\*Compile-time dep_ 46_\*Compile-time dep_
diff --git a/meson.build b/meson.build
index d3172bdd..45df8799 100644
--- a/meson.build
+++ b/meson.build
@@ -107,6 +107,7 @@ if scdoc.found()
107 'sway/sway.5.scd', 107 'sway/sway.5.scd',
108 'sway/sway-bar.5.scd', 108 'sway/sway-bar.5.scd',
109 'sway/sway-input.5.scd', 109 'sway/sway-input.5.scd',
110 'sway/sway-ipc.7.scd',
110 'sway/sway-output.5.scd', 111 'sway/sway-output.5.scd',
111 'swaymsg/swaymsg.1.scd', 112 'swaymsg/swaymsg.1.scd',
112 'swaynag/swaynag.1.scd', 113 'swaynag/swaynag.1.scd',
diff --git a/sway/sway-ipc.7.scd b/sway/sway-ipc.7.scd
new file mode 100644
index 00000000..63fbacc7
--- /dev/null
+++ b/sway/sway-ipc.7.scd
@@ -0,0 +1,1578 @@
1sway-ipc(7)
2
3# NAME
4
5sway-ipc - IPC protocol for sway
6
7# DESCRIPTION
8
9This details the interprocess communication (IPC) protocol for *sway*(1). This
10IPC protocol can be used to control or obtain information from a sway process.
11
12The IPC protocol uses a UNIX socket as the method of communication. The path
13to the socket is stored in the environment variable _SWAYSOCK_ and, for
14backwards compatibility with i3, _I3SOCK_. You can also retrieve the socket
15path by calling _sway --get-socketpath_.
16
17# MESSAGE AND REPLY FORMAT
18
19The format for messages and replies is:
20 <magic-string> <payload-length> <payload-type> <payload>
21Where++
22 <magic-string> is _i3-ipc_, for compatibility with i3++
23 <payload-length> is a 32-bit integer in native byte order++
24 <payload-type> is a 32-bit integer in native byte order
25
26For example, sending the _exit_ command would look like the following hexdump:
27```
2800000000 | 69 33 2d 69 70 63 04 00 00 00 00 00 00 00 65 78 |i3-ipc........ex|
2900000010 | 69 74 |it |
30```
31
32The payload for replies will be a valid serialized JSON data structure.
33
34# MESSAGES AND REPLIES
35
36The following message types and their corresponding reply types are currently
37supported. *For all replies, any properties not listed are subject to removal.*
38
39[- *TYPE NUMBER*
40:- *MESSAGE NAME*
41:- *PURPOSE*
42|- 0
43: RUN_COMMAND
44:[ Runs the payload as sway commands
45|- 1
46: GET_WORKSPACES
47: Get the list of current workspaces
48|- 2
49: SUBSCRIBE
50: Subscribe the IPC connection to the events listed in the payload
51|- 3
52: GET_OUTPUTS
53: Get the list of current outputs
54|- 4
55: GET_TREE
56: Get the node layout tree
57|- 5
58: GET_MARKS
59: Get the names of all the marks currently set
60|- 6
61: GET_BAR_CONFIG
62: Get the specified bar config or a list of bar config names
63|- 7
64: GET_VERSION
65: Get the version of sway that owns the IPC socket
66|- 8
67: GET_BINDING_MODES
68: Get the list of binding mode names
69|- 9
70: GET_CONFIG
71: Returns the config that was last loaded
72|- 10
73: SEND_TICK
74: Sends a tick event with the specified payload
75|- 11
76: SYNC
77: Replies failure object for i3 compatibility
78|- 100
79: GET_INPUTS
80: Get the list of input devices
81|- 101
82: GET_SEATS
83: Get the list of seats
84
85## 0. RUN_COMMAND
86
87*MESSAGE*++
88Parses and runs the payload as sway commands
89
90*REPLY*++
91An array of objects corresponding to each command that was parsed. Each object
92has the property _success_, which is a boolean indicating whether the command
93was successful. The object may also contain the property _error_, which is a
94human readable error message.
95
96*Example Reply:*
97```
98[
99 {
100 "success": true
101 },
102 {
103 "success": false,
104 "error": "Invalid/unknown command"
105 }
106]
107```
108
109## 1. GET_WORKSPACES
110
111*MESSAGE*++
112Retrieves the list of workspaces.
113
114*REPLY*++
115The reply is an array of objects corresponding to each workspace. Each object
116has the following properties:
117
118[- *PROPERTY*
119:- *DATA TYPE*
120:- *DESCRIPTION*
121|- num
122: integer
123:[ The workspace number or -1 for workspaces that do not start with a number
124|- name
125: string
126: The name of the workspace
127|- visible
128: boolean
129: Whether the workspace is currently visible on any output
130|- focused
131: boolean
132: Whether the workspace is currently focused by the default seat (_seat0_)
133|- urgent
134: boolean
135: Whether a view on the workspace has the urgent flag set
136|- rect
137: object
138: The bounds of the workspace. It consists of _x_, _y_, _width_, and _height_
139|- output
140: string
141: The name of the output that the workspace is on
142
143
144*Example Reply:*
145```
146[
147 {
148 "num": 1,
149 "name": "1",
150 "visible": true,
151 "focused": true,
152 "rect": {
153 "x": 0,
154 "y": 23,
155 "width": 1920,
156 "height": 1057
157 },
158 "output": "eDP-1"
159 },
160]
161```
162
163## 2. SUBSCRIBE
164
165*MESSAGE*++
166Subscribe this IPC connection to the event types specified in the message
167payload. The payload should be a valid JSON array of events. See the _EVENTS_
168section for the list of supported events.
169
170*REPLY*++
171A single object that contains the property _success_, which is a boolean value
172indicating whether the subscription was successful or not.
173
174*Example Reply:*
175```
176{
177 "success": true
178}
179```
180
181## 3. GET_OUTPUTS
182
183*MESSAGE*++
184Retrieve the list of outputs
185
186*REPLY*++
187An array of objects corresponding to each output. Each object has the
188following properties:
189
190[- *PROPERTY*
191:- *DATA TYPE*
192:- *DESCRIPTION*
193|- name
194: string
195:[ The name of the output. On DRM, this is the connector
196|- make
197: string
198: The make of the output
199|- model
200: string
201: The model of the output
202|- serial
203: string
204: The output's serial number as a hexadecimal string
205|- active
206: boolean
207: Whether this output is active/enabled
208|- primary
209: boolean
210: For i3 compatibility, this will be false. It does not make sense in Wayland
211|- scale
212: float
213: The scale currently in use on the output or _-1_ for disabled outputs
214|- transform
215: string
216: The transform currently in use for the output. This can be _normal_, _90_,
217 _180_, _270_, _flipped-90_, _flipped-180_, or _flipped-270_
218|- current_workspace
219: string
220: The workspace currently visible on the output or _null_ for disabled outputs
221|- modes
222: array
223: An array of supported mode objects. Each object contains _width_, _height_,
224 and _refresh_
225|- current_mode
226: object
227: An object representing the current mode containing _width_, _height_, and
228 _refresh_
229|- rect
230: object
231: The bounds for the output consisting of _x_, _y_, _width_, and _height_
232
233
234*Example Reply:*
235```
236[
237 {
238 "name": "HDMI-A-2",
239 "make": "Unknown",
240 "model": "NS-19E310A13",
241 "serial": "0x00000001",
242 "active": true,
243 "primary": false,
244 "scale": 1.0,
245 "transform": "normal",
246 "current_workspace": "1",
247 "modes": [
248 {
249 "width": 640,
250 "height": 480,
251 "refresh": 59940
252 },
253 {
254 "width": 800,
255 "height": 600,
256 "refresh": 60317
257 },
258 {
259 "width": 1024,
260 "height": 768,
261 "refresh": 60004
262 },
263 {
264 "width": 1920,
265 "height": 1080,
266 "refresh": 60000
267 }
268 ],
269 "current_mode": {
270 "width": 1920,
271 "height": 1080,
272 "refresh": 60000
273 }
274 }
275]
276```
277
278## 4. GET_TREE
279
280*MESSAGE*++
281Retrieve a JSON representation of the tree
282
283*REPLY*++
284An array of object the represent the current tree. Each object represents one
285node and will have the following properties:
286
287[- *PROPERTY*
288:- *DATA TYPE*
289:- *DESCRIPTION*
290|- id
291: integer
292:[ The internal unique ID for this node
293|- name
294: string
295: The name of the node such as the output name or window title. For the
296 scratchpad, this will be _\_\_i3\_scratch_ for compatibility with i3.
297|- type
298: string
299: The node type. It can be _root_, _output_, _workspace_, _con_, or
300 _floating\_con_
301|- border
302: string
303: The border style for the node. It can be _normal_, _none_, _pixel_, or _csd_
304|- current_border_width
305: integer
306: Number of pixels used for the border width
307|- layout
308: string
309: The node's layout. It can either be _splith_, _splitv_, _stacked_,
310 _tabbed_, or _output_
311|- percent
312: float
313: The percentage of the node's parent that it takes up or _null_ for the root
314 and other special nodes such as the scratchpad
315|- rect
316: object
317: The absolute geometry of the node
318|- window_rect
319: object
320: The geometry of the contents inside the node
321|- deco_rect
322: object
323: The geometry of the decorations inside the node
324|- geometry
325: object
326: The natural geometry of the contents if it were to size itself
327|- urgent
328: boolean
329: Whether the node or any of its descendants has the urgent hint set. Note:
330 This may not exist when compiled without _xwayland_ support
331|- focused
332: boolean
333: Whether the node is currently focused by the default seat (_seat0_)
334|- focus
335: array
336: Array of child node IDs in the current focus order
337|- node
338: array
339: The tiling children nodes for the node
340|- floating_nodes
341: array
342: The floating children nodes for the node
343|- representation
344: string
345: (Only workspaces) A string representation of the layout of the workspace
346 that can be used as an aid in submitting reproduction steps for bug reports
347|- app_id
348: string
349: (Only views) For an xdg-shell view, the name of the application, if set.
350 Otherwise, _null_
351|- pid
352: integer
353: (Only views) The PID of the application that owns the view
354|- window
355: integer
356: (Only xwayland views) The X11 window ID for the xwayland view
357|- window_properties
358: object
359: (Only xwayland views) An object containing the _title_, _class_, _instance_,
360 _window\_role_, and _transient\_for_ for the view
361
362
363*Example Reply:*
364```
365{
366 "id": 1,
367 "name": "root",
368 "rect": {
369 "x": 0,
370 "y": 0,
371 "width": 1920,
372 "height": 1080
373 },
374 "focused": false,
375 "focus": [
376 3
377 ],
378 "border": "none",
379 "current_border_width": 0,
380 "layout": "splith",
381 "percent": null,
382 "window_rect": {
383 "x": 0,
384 "y": 0,
385 "width": 0,
386 "height": 0
387 },
388 "deco_rect": {
389 "x": 0,
390 "y": 0,
391 "width": 0,
392 "height": 0
393 },
394 "geometry": {
395 "x": 0,
396 "y": 0,
397 "width": 0,
398 "height": 0
399 },
400 "window": null,
401 "urgent": false,
402 "floating_nodes": [
403 ],
404 "type": "root",
405 "nodes": [
406 {
407 "id": 2147483647,
408 "name": "__i3",
409 "rect": {
410 "x": 0,
411 "y": 0,
412 "width": 1920,
413 "height": 1080
414 },
415 "focused": false,
416 "focus": [
417 2147483646
418 ],
419 "border": "none",
420 "current_border_width": 0,
421 "layout": "output",
422 "percent": null,
423 "window_rect": {
424 "x": 0,
425 "y": 0,
426 "width": 0,
427 "height": 0
428 },
429 "deco_rect": {
430 "x": 0,
431 "y": 0,
432 "width": 0,
433 "height": 0
434 },
435 "geometry": {
436 "x": 0,
437 "y": 0,
438 "width": 0,
439 "height": 0
440 },
441 "window": null,
442 "urgent": false,
443 "floating_nodes": [
444 ],
445 "type": "output",
446 "nodes": [
447 {
448 "id": 2147483646,
449 "name": "__i3_scratch",
450 "rect": {
451 "x": 0,
452 "y": 0,
453 "width": 1920,
454 "height": 1080
455 },
456 "focused": false,
457 "focus": [
458 ],
459 "border": "none",
460 "current_border_width": 0,
461 "layout": "splith",
462 "percent": null,
463 "window_rect": {
464 "x": 0,
465 "y": 0,
466 "width": 0,
467 "height": 0
468 },
469 "deco_rect": {
470 "x": 0,
471 "y": 0,
472 "width": 0,
473 "height": 0
474 },
475 "geometry": {
476 "x": 0,
477 "y": 0,
478 "width": 0,
479 "height": 0
480 },
481 "window": null,
482 "urgent": false,
483 "floating_nodes": [
484 ],
485 "type": "workspace"
486 }
487 ]
488 },
489 {
490 "id": 3,
491 "name": "eDP-1",
492 "rect": {
493 "x": 0,
494 "y": 0,
495 "width": 1920,
496 "height": 1080
497 },
498 "focused": false,
499 "focus": [
500 4
501 ],
502 "border": "none",
503 "current_border_width": 0,
504 "layout": "output",
505 "percent": 1.0,
506 "window_rect": {
507 "x": 0,
508 "y": 0,
509 "width": 0,
510 "height": 0
511 },
512 "deco_rect": {
513 "x": 0,
514 "y": 0,
515 "width": 0,
516 "height": 0
517 },
518 "geometry": {
519 "x": 0,
520 "y": 0,
521 "width": 0,
522 "height": 0
523 },
524 "window": null,
525 "urgent": false,
526 "floating_nodes": [
527 ],
528 "type": "output",
529 "active": true,
530 "primary": false,
531 "make": "Unknown",
532 "model": "0x38ED",
533 "serial": "0x00000000",
534 "scale": 1.0,
535 "transform": "normal",
536 "current_workspace": "1",
537 "modes": [
538 {
539 "width": 1920,
540 "height": 1080,
541 "refresh": 60052
542 }
543 ],
544 "current_mode": {
545 "width": 1920,
546 "height": 1080,
547 "refresh": 60052
548 },
549 "nodes": [
550 {
551 "id": 4,
552 "name": "1",
553 "rect": {
554 "x": 0,
555 "y": 23,
556 "width": 1920,
557 "height": 1057
558 },
559 "focused": false,
560 "focus": [
561 6,
562 5
563 ],
564 "border": "none",
565 "current_border_width": 0,
566 "layout": "splith",
567 "percent": null,
568 "window_rect": {
569 "x": 0,
570 "y": 0,
571 "width": 0,
572 "height": 0
573 },
574 "deco_rect": {
575 "x": 0,
576 "y": 0,
577 "width": 0,
578 "height": 0
579 },
580 "geometry": {
581 "x": 0,
582 "y": 0,
583 "width": 0,
584 "height": 0
585 },
586 "window": null,
587 "urgent": false,
588 "floating_nodes": [
589 ],
590 "num": 1,
591 "output": "eDP-1",
592 "type": "workspace",
593 "representation": "H[URxvt termite]",
594 "nodes": [
595 {
596 "id": 5,
597 "name": "urxvt",
598 "rect": {
599 "x": 0,
600 "y": 23,
601 "width": 960,
602 "height": 1057
603 },
604 "focused": false,
605 "focus": [
606 ],
607 "border": "normal",
608 "current_border_width": 2,
609 "layout": "none",
610 "percent": 0.5,
611 "window_rect": {
612 "x": 2,
613 "y": 0,
614 "width": 956,
615 "height": 1030
616 },
617 "deco_rect": {
618 "x": 0,
619 "y": 0,
620 "width": 960,
621 "height": 25
622 },
623 "geometry": {
624 "x": 0,
625 "y": 0,
626 "width": 1124,
627 "height": 422
628 },
629 "window": 4194313,
630 "urgent": false,
631 "floating_nodes": [
632 ],
633 "type": "con",
634 "pid": 23959,
635 "app_id": null,
636 "window_properties": {
637 "class": "URxvt",
638 "instance": "urxvt",
639 "title": "urxvt",
640 "transient_for": null
641 },
642 "nodes": [
643 ]
644 },
645 {
646 "id": 6,
647 "name": "",
648 "rect": {
649 "x": 960,
650 "y": 23,
651 "width": 960,
652 "height": 1057
653 },
654 "focused": true,
655 "focus": [
656 ],
657 "border": "normal",
658 "current_border_width": 2,
659 "layout": "none",
660 "percent": 0.5,
661 "window_rect": {
662 "x": 2,
663 "y": 0,
664 "width": 956,
665 "height": 1030
666 },
667 "deco_rect": {
668 "x": 0,
669 "y": 0,
670 "width": 960,
671 "height": 25
672 },
673 "geometry": {
674 "x": 0,
675 "y": 0,
676 "width": 817,
677 "height": 458
678 },
679 "window": null,
680 "urgent": false,
681 "floating_nodes": [
682 ],
683 "type": "con",
684 "pid": 25370,
685 "app_id": "termite",
686 "nodes": [
687 ]
688 }
689 ]
690 }
691 ]
692 }
693 ]
694}
695```
696
697## 5. GET_MARKS
698
699*MESSAGE*++
700Retrieve the currently set marks
701
702*REPLY*++
703An array of marks current set. Since each mark can only be set for one
704container, this is a set so each value is unique and the order is undefined.
705
706*Example Reply:*
707```
708[
709 "one",
710 "test"
711]
712```
713
714## 6. GET_BAR_CONFIG (WITHOUT A PAYLOAD)
715
716*MESSAGE*++
717When sending without a payload, this retrieves the list of configured bar IDs
718
719*REPLY*++
720An array of bar IDs, which are strings
721
722*Example Reply:*
723```
724[
725 "bar-0",
726 "bar-1"
727]
728```
729
730## 6. GET_BAR_CONFIG (WITH A PAYLOAD)
731
732*MESSAGE*++
733When sent with a bar ID as the payload, this retrieves the config associated
734with the specified by the bar ID in the payload. This is used by swaybar, but
735could also be used for third party bars
736
737*REPLY*++
738An object that represents the configuration for the bar with the bar ID sent as
739the payload. The following properties exists and more information about what
740their value mean can be found in *sway-bar*(5):
741
742[- *PROPERTY*
743:- *DATA TYPE*
744:- *DESCRIPTION*
745|- id
746: string
747:[ The bar ID
748|- mode
749: string
750: The mode for the bar. It can be _dock_, _hide_, or _invisible_
751|- position
752: string
753: The bar's position. It can currently either be _bottom_ or _top_
754|- status_command
755: string
756: The command which should be run to generate the status line
757|- font
758: string
759: The font to use for the text on the bar
760|- workspace_buttons
761: boolean
762: Whether to display the workspace buttons on the bar
763|- binding_mode_indicator
764: boolean
765: Whether to display the current binding mode on the bar
766|- verbose
767: boolean
768: For i3 compatibility, this will be the boolean value _false_.
769|- colors
770: object
771: An object containing the _#RRGGBBAA_ colors to use for the bar. See below
772 for more information
773|- gaps
774: object
775: An object representing the gaps for the bar consisting of _top_, _right_,
776 _bottom_, and _left_.
777|- bar_height
778: integer
779: The absolute height to use for the bar or _0_ to automatically size based
780 on the font
781|- status_padding
782: integer
783: The vertical padding to use for the status line
784|- status_edge_padding
785: integer
786: The horizontal padding to use for the status line when at the end of an
787 output
788
789
790The colors object contains the following properties, which are all strings
791containing the _#RRGGBBAA_ representation of the color:
792[- *PROPERTY*
793:- *DESCRIPTION*
794|- background
795:[ The color to use for the bar background on unfocused outputs
796|- statusline
797: The color to use for the status line text on unfocused outputs
798|- separator
799: The color to use for the separator text on unfocused outputs
800|- focused_background
801: The color to use for the background of the bar on the focused output
802|- focused_statusline
803: The color to use for the status line text on the focused output
804|- focused_separator
805: The color to use for the separator text on the focused output
806|- focused_workspace_text
807: The color to use for the text of the focused workspace button
808|- focused_workspace_bg
809: The color to use for the background of the focused workspace button
810|- focused_workspace_border
811: The color to use for the border of the focused workspace button
812|- active_workspace_text
813: The color to use for the text of the workspace buttons for the visible
814 workspaces on unfocused outputs
815|- active_workspace_bg
816: The color to use for the background of the workspace buttons for the visible
817 workspaces on unfocused outputs
818|- active_workspace_border
819: The color to use for the border of the workspace buttons for the visible
820 workspaces on unfocused outputs
821|- inactive_workspace_text
822: The color to use for the text of the workspace buttons for workspaces that
823 are not visible
824|- inactive_workspace_bg
825: The color to use for the background of the workspace buttons for workspaces
826 that are not visible
827|- inactive_workspace_border
828: The color to use for the border of the workspace buttons for workspaces
829 that are not visible
830|- urgent_workspace_text
831: The color to use for the text of the workspace buttons for workspaces that
832 contain an urgent view
833|- urgent_workspace_bg
834: The color to use for the background of the workspace buttons for workspaces
835 that contain an urgent view
836|- urgent_workspace_border
837: The color to use for the border of the workspace buttons for workspaces that
838 contain an urgent view
839|- binding_mode_text
840: The color to use for the text of the binding mode indicator
841|- binding_mode_bg
842: The color to use for the background of the binding mode indicator
843|- binding_mode_border
844: The color to use for the border of the binding mode indicator
845
846
847*Example Reply:*
848```
849{
850 "id": "bar-0",
851 "mode": "dock",
852 "position": "top",
853 "status_command": "while date +'%Y-%m-%d %l:%M:%S %p'; do sleep 1; done",
854 "font": "monospace 10",
855 "gaps": {
856 "top": 0,
857 "right": 0,
858 "bottom": 0,
859 "left": 0
860 },
861 "bar_height": 0,
862 "status_padding": 1,
863 "status_edge_padding": 3,
864 "workspace_buttons": true,
865 "binding_mode_indicator": true,
866 "verbose": false,
867 "pango_markup": false,
868 "colors": {
869 "background": "#323232ff",
870 "statusline": "#ffffffff",
871 "separator": "#666666ff",
872 "focused_background": "#323232ff",
873 "focused_statusline": "#ffffffff",
874 "focused_separator": "#666666ff",
875 "focused_workspace_border": "#4c7899ff",
876 "focused_workspace_bg": "#285577ff",
877 "focused_workspace_text": "#ffffffff",
878 "inactive_workspace_border": "#32323200",
879 "inactive_workspace_bg": "#32323200",
880 "inactive_workspace_text": "#5c5c5cff",
881 "active_workspace_border": "#333333ff",
882 "active_workspace_bg": "#5f676aff",
883 "active_workspace_text": "#ffffffff",
884 "urgent_workspace_border": "#2f343aff",
885 "urgent_workspace_bg": "#900000ff",
886 "urgent_workspace_text": "#ffffffff",
887 "binding_mode_border": "#2f343aff",
888 "binding_mode_bg": "#900000ff",
889 "binding_mode_text": "#ffffffff"
890 },
891}
892```
893
894## 7. GET_VERSION
895
896*MESSAGE*++
897Retrieve version information about the sway process
898
899*REPLY*++
900An object containing the following properties:
901
902[- *PROPERTY*
903:- *DATA TYPE*
904:- *DESCRIPTION*
905|- major
906: integer
907:[ The major version of the sway process
908|- minor
909: integer
910: The minor version of the sway process
911|- patch
912: integer
913: The patch version of the sway process
914|- human_readable
915: string
916: A human readable version string that will likely contain more useful
917 information such as the git commit short hash and git branch
918|- loaded_config_file_name
919: string
920: The path to the loaded config file
921
922
923*Example Reply:*
924```
925{
926 "human_readable": "1.0-rc1-117-g2f7247e0 (Feb 24 2019, branch 'master')",
927 "major": 1,
928 "minor": 0,
929 "patch": 0,
930 "loaded_config_file_name": "/home/redsoxfan/.config/sway/config"
931}
932```
933
934## 8. GET_BINDING_MODES
935
936*MESSAGE*++
937Retrieve the list of binding modes that currently configured
938
939*REPLY*++
940An array of strings, with each string being the name of a binding mode. This
941will always contain at least one mode (currently _default_), which is the
942default binding mode
943
944*Example Reply:*
945```
946[
947 "default",
948 "resize",
949]
950```
951
952## 9. GET_CONFIG
953
954*MESSAGE*++
955Retrieve the contents of the config that was last loaded
956
957*REPLY*++
958An object with a single string property containing the contents of the config
959
960*Example Reply:*
961```
962{
963 "config": "set $mod Mod4\nbindsym $mod+q exit\n"
964}
965```
966
967## 10. SEND_TICK
968
969*MESSAGE*++
970Issues a _TICK_ event to all clients subscribing to the event to ensure that
971all events prior to the tick were received. If a payload is given, it will be
972included in the _TICK_ event
973
974*REPLY*++
975A single object contains the property _success_, which is a boolean value
976indicating whether the _TICK_ event was sent.
977
978*Example Reply:*
979```
980{
981 "success": true
982}
983```
984
985## 11. SYNC
986
987*MESSAGE*++
988For i3 compatibility, this command will just return a failure object since it
989does not make sense to implement in sway due to the X11 nature of the command.
990If you are curious about what this IPC command does in i3, refer to the i3
991documentation.
992
993*REPLY*++
994A single object that contains the property _success_, which is set to the
995boolean value _false_.
996
997*Exact Reply:*
998```
999{
1000 "success": false
1001}
1002```
1003
1004## 100. GET_INPUTS
1005
1006*MESSAGE*++
1007Retrieve a list of the input devices currently available
1008
1009*REPLY*++
1010An array of objects corresponding to each input device. Each object has the
1011following properties:
1012
1013[- *PROPERTY*
1014:- *DATA TYPE*
1015:- *DESCRIPTION*
1016|- identifier
1017: string
1018:[ The identifier for the input device
1019|- name
1020: string
1021: The human readable name for the device
1022|- vendor
1023: integer
1024: The vendor code for the input device
1025|- product
1026: integer
1027: The product code for the input device
1028|- type
1029: string
1030: The device type. Currently this can be _keyboard_, _pointer_, _touch_,
1031 _tablet\_tool_, _tablet\_pad_, or _switch_
1032|- xkb_active_layout_name
1033: string
1034: (Only keyboards) The active keyboard layout in use
1035|- libinput_send_events
1036: string
1037: (Only libinput devices) The send events value in use by libinput for this
1038 device. It can be _enabled_, _disabled_, or _disabled\_on\_external\_mouse_
1039
1040
1041*Example Reply:*
1042```
1043[
1044 {
1045 "identifier": "1:1:AT_Translated_Set_2_keyboard",
1046 "name": "AT Translated Set 2 keyboard",
1047 "vendor": 1,
1048 "product": 1,
1049 "type": "keyboard",
1050 "xkb_active_layout_name": "English (US)",
1051 "libinput_send_events": "enabled"
1052 },
1053 {
1054 "identifier": "1267:5:Elan_Touchpad",
1055 "name": "Elan Touchpad",
1056 "vendor": 1267,
1057 "product": 5,
1058 "type": "pointer",
1059 "libinput_send_events": "enabled"
1060 },
1061 {
1062 "identifier": "3034:22494:USB2.0_VGA_UVC_WebCam:_USB2.0_V",
1063 "name": "USB2.0 VGA UVC WebCam: USB2.0 V",
1064 "vendor": 3034,
1065 "product": 22494,
1066 "type": "keyboard",
1067 "xkb_active_layout_name": "English (US)",
1068 "libinput_send_events": "enabled"
1069 },
1070 {
1071 "identifier": "0:3:Sleep_Button",
1072 "name": "Sleep Button",
1073 "vendor": 0,
1074 "product": 3,
1075 "type": "keyboard",
1076 "xkb_active_layout_name": "English (US)",
1077 "libinput_send_events": "enabled"
1078 },
1079 {
1080 "identifier": "0:5:Lid_Switch",
1081 "name": "Lid Switch",
1082 "vendor": 0,
1083 "product": 5,
1084 "type": "switch",
1085 "libinput_send_events": "enabled"
1086 {
1087 "identifier": "0:6:Video_Bus",
1088 "name": "Video Bus",
1089 "vendor": 0,
1090 "product": 6,
1091 "type": "keyboard",
1092 "xkb_active_layout_name": "English (US)",
1093 "libinput_send_events": "enabled"
1094 },
1095 {
1096 "identifier": "0:1:Power_Button",
1097 "name": "Power Button",
1098 "vendor": 0,
1099 "product": 1,
1100 "type": "keyboard",
1101 "xkb_active_layout_name": "English (US)",
1102 "libinput_send_events": "enabled"
1103 }
1104]
1105```
1106
1107## 101. GET_SEATS
1108
1109*MESSAGE*++
1110Retrieve a list of the seats currently configured
1111
1112*REPLY*++
1113An array of objects corresponding to each seat. There will always be at least
1114one seat. Each object has the following properties:
1115
1116[- *PROPERTY*
1117:- *DATA TYPE*
1118:- *DESCRIPTION*
1119|- name
1120: string
1121:] The unique name for the seat
1122|- capabilities
1123: integer
1124: The number of capabilities that the seat has
1125|- focus
1126: integer
1127: The id of the node currently focused by the seat or _0_ when the seat is
1128 not currently focused by a node (i.e. a surface layer or xwayland unmanaged
1129 has focus)
1130|- devices
1131: array
1132: An array of input devices that are attached to the seat. Currently, this
1133 is an array of objects that are identical to those returned by _GET\_INPUTS_
1134
1135
1136*Example Reply:*
1137```
1138[
1139 {
1140 "name": "seat0",
1141 "capabilities": 3,
1142 "focus": 7,
1143 "devices": [
1144 {
1145 "identifier": "1:1:AT_Translated_Set_2_keyboard",
1146 "name": "AT Translated Set 2 keyboard",
1147 "vendor": 1,
1148 "product": 1,
1149 "type": "keyboard",
1150 "xkb_active_layout_name": "English (US)",
1151 "libinput_send_events": "enabled"
1152 },
1153 {
1154 "identifier": "1267:5:Elan_Touchpad",
1155 "name": "Elan Touchpad",
1156 "vendor": 1267,
1157 "product": 5,
1158 "type": "pointer",
1159 "libinput_send_events": "enabled"
1160 },
1161 {
1162 "identifier": "3034:22494:USB2.0_VGA_UVC_WebCam:_USB2.0_V",
1163 "name": "USB2.0 VGA UVC WebCam: USB2.0 V",
1164 "vendor": 3034,
1165 "product": 22494,
1166 "type": "keyboard",
1167 "xkb_active_layout_name": "English (US)",
1168 "libinput_send_events": "enabled"
1169 },
1170 {
1171 "identifier": "0:3:Sleep_Button",
1172 "name": "Sleep Button",
1173 "vendor": 0,
1174 "product": 3,
1175 "type": "keyboard",
1176 "xkb_active_layout_name": "English (US)",
1177 "libinput_send_events": "enabled"
1178 },
1179 {
1180 "identifier": "0:5:Lid_Switch",
1181 "name": "Lid Switch",
1182 "vendor": 0,
1183 "product": 5,
1184 "type": "switch",
1185 "libinput_send_events": "enabled"
1186 {
1187 "identifier": "0:6:Video_Bus",
1188 "name": "Video Bus",
1189 "vendor": 0,
1190 "product": 6,
1191 "type": "keyboard",
1192 "xkb_active_layout_name": "English (US)",
1193 "libinput_send_events": "enabled"
1194 },
1195 {
1196 "identifier": "0:1:Power_Button",
1197 "name": "Power Button",
1198 "vendor": 0,
1199 "product": 1,
1200 "type": "keyboard",
1201 "xkb_active_layout_name": "English (US)",
1202 "libinput_send_events": "enabled"
1203 }
1204 ]
1205 }
1206]
1207```
1208
1209# EVENTS
1210
1211Events are a way for client to get notified of changes to sway. A client can
1212subscribe to any events it wants to be notified of changes for. The event is
1213sent in the same format as a reply. The following events are currently
1214available:
1215
1216[- *EVENT TYPE*
1217:- *NAME*
1218:- *DESCRIPTION*
1219|- 0x80000000
1220: workspace
1221:[ Sent whenever an event involving a workspace occurs such as initialization
1222 of a new workspace or a different workspace gains focus
1223|- 0x80000002
1224: mode
1225: Sent whenever the binding mode changes
1226|- 0x80000003
1227: window
1228: Sent whenever an event involving a view occurs such as being reparented,
1229 focused, or closed
1230|- 0x80000004
1231: barconfig_update
1232: Sent whenever a bar config changes
1233|- 0x80000005
1234: binding
1235: Sent when a configured binding is executed
1236|- 0x80000006
1237: shutdown
1238: Sent when the ipc shuts down because sway is exiting
1239|- 0x80000007
1240: tick
1241: Sent when an ipc client sends a _SEND\_TICK_ message
1242|- 0x80000014
1243: bar_status_update
1244: Send when the visibility of a bar should change due to a modifier
1245
1246
1247## 0x80000000. WORKSPACE
1248
1249Sent whenever a change involving a workspace occurs. The event consists of a
1250single object with the following properties:
1251
1252[- *PROPERTY*
1253:- *DATA TYPE*
1254:- *DESCRIPTION*
1255|- change
1256: string
1257:[ The type of change that occurred. See below for more information
1258|- current
1259: object
1260: An object representing the workspace effected or _null_ for _reload_ changes
1261|- old
1262: object
1263: For a _focus_ change, this is will be an object representing the workspace
1264 being switched from. Otherwise, it is _null_
1265
1266
1267The following change types are currently available:
1268[- *TYPE*
1269:- *DESCRIPTION*
1270|- init
1271:[ The workspace was created
1272|- empty
1273: The workspace is empty and is being destroyed since it is not visible
1274|- focus
1275: The workspace was focused. See the _old_ property for the previous focus
1276|- move
1277: The workspace was moved to a different output
1278|- rename
1279: The workspace was renamed
1280|- urgent
1281: A view on the workspace has had their urgency hint set or all urgency hints
1282 for views on the workspace have been cleared
1283|- reload
1284: The configuration file has been reloaded
1285
1286
1287*Example Event:*
1288```
1289{
1290 "change": "init",
1291 "old": null,
1292 "current": {
1293 "id": 10,
1294 "name": "2",
1295 "rect": {
1296 "x": 0,
1297 "y": 0,
1298 "width": 0,
1299 "height": 0
1300 },
1301 "focused": false,
1302 "focus": [
1303 ],
1304 "border": "none",
1305 "current_border_width": 0,
1306 "layout": "splith",
1307 "percent": null,
1308 "window_rect": {
1309 "x": 0,
1310 "y": 0,
1311 "width": 0,
1312 "height": 0
1313 },
1314 "deco_rect": {
1315 "x": 0,
1316 "y": 0,
1317 "width": 0,
1318 "height": 0
1319 },
1320 "geometry": {
1321 "x": 0,
1322 "y": 0,
1323 "width": 0,
1324 "height": 0
1325 },
1326 "window": null,
1327 "urgent": false,
1328 "floating_nodes": [
1329 ],
1330 "num": 2,
1331 "output": "eDP-1",
1332 "type": "workspace",
1333 "representation": null,
1334 "nodes": [
1335 ]
1336 }
1337}
1338```
1339
1340## 0x80000002. MODE
1341
1342Sent whenever the binding mode changes. The event consists of a single object
1343with the following properties:
1344
1345[- *PROPERTY*
1346:- *DATA TYPE*
1347:- *DESCRIPTION*
1348|- change
1349: string
1350:[ The binding mode that became active
1351|- pango_markup
1352: boolean
1353: Whether the mode should be parsed as pango markup
1354
1355
1356*Example Event:*
1357```
1358{
1359 "change": "default",
1360 "pango_markup": false
1361}
1362```
1363
1364## 0x80000003. WINDOW
1365
1366Sent whenever a change involving a view occurs. The event consists of a single
1367object with the following properties:
1368
1369[- *PROPERTY*
1370:- *DATA TYPE*
1371:- *DESCRIPTION*
1372|- change
1373: string
1374:[ The type of change that occurred. See below for more information
1375|- container
1376: object
1377: An object representing the view effected
1378
1379
1380The following change types are currently available:
1381[- *TYPE*
1382:- *DESCRIPTION*
1383|- new
1384:[ The view was created
1385|- close
1386: The view was closed
1387|- focus
1388: The view was focused
1389|- title
1390: The view's title has changed
1391|- fullscreen_mode
1392: The view's fullscreen mode has changed
1393|- move
1394: The view has been reparented in the tree
1395|- floating
1396: The view has become floating or is no longer floating
1397|- urgent
1398: The view's urgency hint has changed status
1399|- mark
1400: A mark has been added or removed from the view
1401
1402
1403*Example Event:*
1404```
1405{
1406 "change": "new",
1407 "container": {
1408 "id": 12,
1409 "name": null,
1410 "rect": {
1411 "x": 0,
1412 "y": 0,
1413 "width": 0,
1414 "height": 0
1415 },
1416 "focused": false,
1417 "focus": [
1418 ],
1419 "border": "none",
1420 "current_border_width": 0,
1421 "layout": "none",
1422 "percent": 0.0,
1423 "window_rect": {
1424 "x": 0,
1425 "y": 0,
1426 "width": 0,
1427 "height": 0
1428 },
1429 "deco_rect": {
1430 "x": 0,
1431 "y": 0,
1432 "width": 0,
1433 "height": 0
1434 },
1435 "geometry": {
1436 "x": 0,
1437 "y": 0,
1438 "width": 1124,
1439 "height": 422
1440 },
1441 "window": 4194313,
1442 "urgent": false,
1443 "floating_nodes": [
1444 ],
1445 "type": "con",
1446 "pid": 19787,
1447 "app_id": null,
1448 "window_properties": {
1449 "class": "URxvt",
1450 "instance": "urxvt",
1451 "transient_for": null
1452 },
1453 "nodes": [
1454 ]
1455 }
1456}
1457```
1458
1459## 0x80000004. BARCONFIG_UPDATE
1460
1461Sent whenever a config for a bar changes. The event is identical to that of
1462_GET_BAR_CONFIG_ when a bar ID is given as a payload. See _6. GET\_BAR\_CONFIG
1463(WITH A PAYLOAD)_ above for more information.
1464
1465## 0x80000005. BINDING
1466
1467Sent whenever a binding is executed. The event is a single object with the
1468following properties:
1469
1470[- *PROPERTY*
1471:- *DATA TYPE*
1472:- *DESCRIPTION*
1473|- change
1474: string
1475:[ The change that occurred for the binding. Currently this will only be _run_
1476|- command
1477: string
1478: The command associated with the binding
1479|- event_state_mask
1480: array
1481: An array of strings that correspond to each modifier key for the binding
1482|- input_code
1483: integer
1484: For keyboard bindcodes, this is the key code for the binding. For mouse
1485 bindings, this is the X11 button number, if there is an equivalent. In all
1486 other cases, this will be _0_.
1487|- symbol
1488: string
1489: For keyboard bindsyms, this is the bindsym for the binding. Otherwise, this
1490 will be _null_
1491|- input_type
1492: string
1493: The input type that triggered the binding. This is either _keyboard_ or
1494 _mouse_
1495
1496
1497*Example Event:*
1498```
1499{
1500 "change": "run",
1501 "binding": {
1502 "command": "workspace 2",
1503 "event_state_mask": [
1504 "Mod4"
1505 ],
1506 "input_code": 0,
1507 "symbol": "2",
1508 "input_type": "keyboard"
1509 }
1510}
1511```
1512
1513## 0x80000006. SHUTDOWN
1514
1515Sent whenever the IPC is shutting down. The event is a single object with the
1516property _change_, which is a string containing the reason for the shutdown.
1517Currently, the only value for _change_ is _exit_, which is issued when sway is
1518exiting.
1519
1520*Example Event:*
1521```
1522{
1523 "change": "exit"
1524}
1525```
1526
1527## 0x80000007. TICK
1528
1529Sent when first subscribing to tick events or by a _SEND\_TICK_ message. The
1530event is a single object with the following properties:
1531
1532[- *PROPERTY*
1533:- *DATA TYPE*
1534:- *DESCRIPTION*
1535|- first
1536: boolean
1537: Whether this event was triggered by subscribing to the tick events
1538|- payload
1539: string
1540: The payload given with a _SEND\_TICK_ message, if any. Otherwise, an empty
1541 string
1542
1543
1544*Example Event:*
1545```
1546{
1547 "first": true
1548 "payload": ""
1549}
1550```
1551
1552## 0x80000014. BAR_STATUS_UPDATE
1553
1554Sent when the visibility of a bar changes due to a modifier being pressed. The
1555event is a single object with the following properties:
1556
1557[- *PROPERTY*
1558:- *DATA TYPE*
1559:- *DESCRIPTION*
1560|- id
1561: string
1562:[ The bar ID effected
1563|- visible_by_modifier
1564: boolean
1565: Whether the bar should be made visible due to a modifier being pressed
1566
1567
1568*Example Event:*
1569```
1570{
1571 "id": "bar-0",
1572 "visible_by_modifier": true
1573}
1574```
1575
1576# SEE ALSO
1577
1578*sway*(1) *sway*(5) *sway-bar*(5) *swaymsg*(1) *sway-input*(5) *sway-output*(5)
diff --git a/sway/sway.1.scd b/sway/sway.1.scd
index bce63527..cfb4817a 100644
--- a/sway/sway.1.scd
+++ b/sway/sway.1.scd
@@ -89,3 +89,4 @@ source contributors. For more information about sway development, see
89# SEE ALSO 89# SEE ALSO
90 90
91*sway*(5) *swaymsg*(1) *sway-input*(5) *sway-output*(5) *sway-bar*(5) 91*sway*(5) *swaymsg*(1) *sway-input*(5) *sway-output*(5) *sway-bar*(5)
92*sway-ipc*(7)
diff --git a/sway/sway.5.scd b/sway/sway.5.scd
index 63b9fecd..847b7727 100644
--- a/sway/sway.5.scd
+++ b/sway/sway.5.scd
@@ -748,4 +748,4 @@ The following attributes may be matched with:
748 748
749# SEE ALSO 749# SEE ALSO
750 750
751*sway*(1) *sway-input*(5) *sway-output*(5) *sway-bar*(5) 751*sway*(1) *sway-input*(5) *sway-output*(5) *sway-bar*(5) *sway-ipc*(7)
diff --git a/swaymsg/swaymsg.1.scd b/swaymsg/swaymsg.1.scd
index f55f86a9..523db6cc 100644
--- a/swaymsg/swaymsg.1.scd
+++ b/swaymsg/swaymsg.1.scd
@@ -82,3 +82,7 @@ _swaymsg_ [options...] [message]
82 Subscribe to a list of event types. The argument for this type should be 82 Subscribe to a list of event types. The argument for this type should be
83 provided in the form of a valid JSON array. If any of the types are invalid 83 provided in the form of a valid JSON array. If any of the types are invalid
84 or if an valid JSON array is not provided, this will result in an failure. 84 or if an valid JSON array is not provided, this will result in an failure.
85
86# SEE ALSO
87
88*sway*(5) *sway-bar*(5) *sway-input*(5) *sway-output*(5) *sway-ipc*(7)