Skip to content
This repository has been archived by the owner on Apr 18, 2023. It is now read-only.

Commit

Permalink
Browse files Browse the repository at this point in the history
Merge remote-tracking branch 'vanilla/next' into gaps-next
  • Loading branch information
Airblader committed May 21, 2021
2 parents 55b090a + e44aa7a commit dd7cfdd
Show file tree
Hide file tree
Showing 10 changed files with 353 additions and 52 deletions.
17 changes: 17 additions & 0 deletions RELEASE-NOTES-next
Expand Up @@ -6,6 +6,23 @@
This is i3 v4.19. This version is considered stable. All users of i3 are
strongly encouraged to upgrade.

Background/wallpaper workaround:

Some login managers (e.g. gdm) start the X11 server with the -background none
flag. When this flag is set, a background needs to be explicitly set later in
the X11 session, otherwise stale copies of closed windows remain visible on the
X11 root window (symptom looks like “my terminal window is not closing”).

i3 works around this situation by setting a screenshot as background when
starting. Any background you set before starting i3 (e.g. in your Xsession) or
after starting i3 (e.g. via exec statements in the i3 config) will be visible.

A downside of this workaround is that if you have any windows already open in
your X11 session, those will be part of the screenshot.

To fix this issue, starting in v4.20, i3 detects whether the -background none
option is enabled and only then sets a screenshot as background.


┌────────────────────────────┐
│ Changes in i3 v4.20 │
Expand Down
184 changes: 153 additions & 31 deletions docs/ipc
Expand Up @@ -14,7 +14,8 @@ most languages. In the default configuration file, the ipc-socket gets created
in +/tmp/i3-%u.XXXXXX/ipc-socket.%p+ where +%u+ is your UNIX username, +%p+ is
the PID of i3 and XXXXXX is a string of random characters from the portable
filename character set (see mkdtemp(3)). You can get the socketpath from i3 by
calling +i3 --get-socketpath+.
executing +i3 --get-socketpath+, which will print the path to the standard
output (plus a newline).

All i3 utilities, like +i3-msg+ and +i3-input+ will read the +I3_SOCKET_PATH+
X11 property, stored on the X11 root window.
Expand All @@ -39,12 +40,12 @@ my $sock = IO::Socket::UNIX->new(Peer => $path);

== Sending messages to i3

To send a message to i3, you have to format in the binary message format which
i3 expects. This format specifies a magic string in the beginning to ensure
the integrity of messages (to prevent follow-up errors). Following the magic
string comes the length of the payload of the message as 32-bit integer, and
the type of the message as 32-bit integer (the integers are not converted, so
they are in native byte order).
To send a message to i3, you have to format it in the binary message format
which i3 expects. This format specifies a magic string in the beginning to
ensure the integrity of messages (to prevent follow-up errors). Following the
magic string comes the length of the payload of the message as a 32-bit
integer, and the type of the message as a 32-bit integer (the integers are not
converted, so they are in native byte order).

The magic string currently is "i3-ipc" and will only be changed when a change
in the IPC API is done which breaks compatibility (we hope that we don’t need
Expand Down Expand Up @@ -96,18 +97,30 @@ $sock->write(format_ipc_command("exit"));

== Receiving replies from i3

Replies from i3 usually consist of a simple string (the length of the string
is the message_length, so you can consider them length-prefixed) which in turn
contain the JSON serialization of a data structure. For example, the
GET_WORKSPACES message returns an array of workspaces (each workspace is a map
with certain attributes).
Each message sent to i3 will cause exactly one reply to be sent in return. The
order of the sent replies will always correspond to the order of the sent
requests. The only exception to this is <<events>>, which (once subscribed to)
may be sent at any time (though never in the middle of another event or reply).

=== Reply format
It is generally safe to send several messages to i3 without first waiting for a
reply for each one (pipelining) -- though, note that depending on the language /
network library you use, writing to the socket without also reading from it may
cause a deadlock due to the socket buffers getting full.

The reply format is identical to the normal message format. There also is
the magic string, then the message length, then the message type and the
payload.

The payload of replies from i3 usually consists of a simple string (the length
of the string is the message_length, so you can consider them length-prefixed),
which in turn contain the JSON serialization of a data structure. For example,
the GET_WORKSPACES message returns an array of workspaces (each workspace is a
map with certain attributes).

Replies currently have a 1:1 correspondence to messages, with the message type
of the reply corresponding to the message type of the message which caused the
reply to be sent.

The following reply types are implemented:

COMMAND (0)::
Expand All @@ -127,7 +140,7 @@ BAR_CONFIG (6)::
VERSION (7)::
Reply to the GET_VERSION message.
BINDING_MODES (8)::
Reply to the GET_BINDING_MODES message.
Reply to the GET_BINDING_MODES message.
GET_CONFIG (9)::
Reply to the GET_CONFIG message.
TICK (10)::
Expand All @@ -137,8 +150,20 @@ SYNC (11)::
GET_BINDING_STATE (12)::
Reply to the GET_BINDING_STATE message.

== Messages and replies

[[_command_reply]]
=== COMMAND reply
=== RUN_COMMAND / COMMAND

Run the payload as an https://i3wm.org/docs/userguide.html#list_of_commands[i3
command] (like the commands you can bind to keys).

*Message:*

The message payload is the string containing the command to execute. There is
no JSON encoding or trailing newline.

*Reply:*

The reply consists of a list of serialized maps for each command that was
parsed. Each has the property +success (bool)+ and may also include a
Expand Down Expand Up @@ -172,7 +197,15 @@ When the specified command cannot be parsed, `success` will be false and
-------------------

[[_workspaces_reply]]
=== WORKSPACES reply
=== GET_WORKSPACES / WORKSPACES

Get the list of current workspaces.

*Message:*

No payload.

*Reply:*

The reply consists of a serialized list of workspaces. Each workspace has the
following properties:
Expand Down Expand Up @@ -236,7 +269,16 @@ output (string)::
-------------------

[[_subscribe_reply]]
=== SUBSCRIBE reply
=== SUBSCRIBE

Subscribe this IPC connection to the event types specified in the message
payload. See <<events>>.

*Message:*

A JSON-encoded array of event types to subscribe to.

*Reply:*

The reply consists of a single serialized map. The only property is
+success (bool)+, indicating whether the subscription was successful (the
Expand All @@ -248,7 +290,15 @@ default) or whether a JSON parse error occurred.
-------------------

[[_outputs_reply]]
=== OUTPUTS reply
=== GET_OUTPUTS / OUTPUTS

Get the list of current outputs.

*Message:*

No payload.

*Reply:*

The reply consists of a serialized list of outputs. Each output has the
following properties:
Expand All @@ -259,7 +309,7 @@ active (boolean)::
Whether this output is currently active (has a valid mode).
primary (boolean)::
Whether this output is currently the primary output.
current_workspace (string)::
current_workspace (string or null)::
The name of the current workspace that is visible on this output. +null+ if
the output is not active.
rect (map)::
Expand Down Expand Up @@ -295,7 +345,15 @@ rect (map)::
-------------------

[[_tree_reply]]
=== TREE reply
=== GET_TREE / TREE

Get the i3 layout tree.

*Message:*

No payload.

*Reply:*

The reply consists of a serialized tree. Each node in the tree (representing
one container) has at least the properties listed below. While the nodes might
Expand Down Expand Up @@ -331,7 +389,7 @@ orientation (string)::
"vertical".
THIS FIELD IS OBSOLETE. It is still present, but your code should not
use it. Instead, rely on the layout field.
percent (float)::
percent (float or null)::
The percentage which this container takes in its parent. A value of
+null+ means that the percent property does not make sense for this
container, for example for the root container.
Expand All @@ -355,9 +413,9 @@ deco_rect (map)::
geometry (map)::
The original geometry the window specified when i3 mapped it. Used when
switching a window to floating mode, for example.
window (integer)::
window (integer or null)::
The X11 window ID of the *actual client window* inside this container.
This field is set to null for split containers or otherwise empty
This field is set to +null+ for split containers or otherwise empty
containers. This ID corresponds to what xwininfo(1) and other
X11-related tools display (usually in hex).
window_properties (map)::
Expand Down Expand Up @@ -538,7 +596,15 @@ JSON dump:
-----------------------

[[_marks_reply]]
=== MARKS reply
=== GET_MARKS / MARKS

Gets the names of all currently set marks.

*Message:*

No payload.

*Reply:*

The reply consists of a single array of strings for each container that has a
mark. A mark can only be set on one container, so the array is unique.
Expand All @@ -547,7 +613,15 @@ The order of that array is undefined.
If no window has a mark the response will be the empty array [].

[[_bar_config_reply]]
=== BAR_CONFIG reply
=== GET_BAR_CONFIG / BAR_CONFIG

Gets the specified bar configuration or the names of all bar configurations if payload is empty.

*Message:*

No payload, or the ID of the bar whose configuration to retrieve.

*Reply:*

This can be used by third-party workspace bars (especially i3bar, but others
are free to implement compatible alternatives) to get the +bar+ block
Expand Down Expand Up @@ -647,7 +721,15 @@ binding_mode_text/binding_mode_bg/binding_mode_border::
--------------

[[_version_reply]]
=== VERSION reply
=== GET_VERSION / VERSION

Gets the i3 version.

*Message:*

No payload.

*Reply:*

The reply consists of a single JSON dictionary with the following keys:

Expand Down Expand Up @@ -680,7 +762,15 @@ loaded_config_file_name (string)::
-------------------

[[_binding_modes_reply]]
=== BINDING_MODES reply
=== GET_BINDING_MODES / BINDING_MODES

Gets the names of all currently configured binding modes.

*Message:*

No payload.

*Reply:*

The reply consists of an array of all currently configured binding modes.

Expand All @@ -690,7 +780,15 @@ The reply consists of an array of all currently configured binding modes.
---------------------

[[_config_reply]]
=== CONFIG reply
=== GET_CONFIG / CONFIG

Returns the last loaded i3 config.

*Message:*

No payload.

*Reply:*

The config reply is a map which currently only contains the "config" member,
which is a string containing the config file as loaded by i3 most recently.
Expand All @@ -701,7 +799,15 @@ which is a string containing the config file as loaded by i3 most recently.
-------------------

[[_tick_reply]]
=== TICK reply
=== SEND_TICK / TICK

Sends a tick event with the specified payload.

*Message:*

The payload of the tick event to send to IPC event listeners.

*Reply:*

The reply is a map containing the "success" member. After the reply was
received, the tick event has been written to all IPC connections which subscribe
Expand All @@ -715,7 +821,15 @@ events generated prior to the +SEND_TICK+ message (happened-before relation).
-------------------

[[_sync_reply]]
=== SYNC reply
=== SYNC

Sends an i3 sync event with the specified random value to the specified window.

*Message:*

A JSON-encoded map with the properties "rnd" and "window" (both integer).

*Reply:*

The reply is a map containing the "success" member. After the reply was
received, the https://i3wm.org/docs/testsuite.html#i3_sync[i3 sync message] was
Expand All @@ -727,7 +841,15 @@ responded to.
-------------------

[[_binding_state_reply]]
=== GET_BINDING_STATE reply
=== GET_BINDING_STATE

Request the current binding state, i.e. the currently active binding mode name.

*Message:*

No payload.

*Reply:*

The binding_state reply is a map which currently only contains the "name"
member, which is the name of the currently active binding mode as a string.
Expand Down
9 changes: 8 additions & 1 deletion docs/userguide
Expand Up @@ -608,9 +608,10 @@ Default is +left+
title_align left|center|right
---------------------------------------------

[[default_border]]
=== Default border style for new windows

This option determines which border style new windows will have. The default is
This option determines which border style *new* windows will have. The default is
+normal+. Note that default_floating_border applies only to windows which are starting out as
floating windows, e.g., dialog windows, but not windows that are floated later on.

Expand Down Expand Up @@ -2664,10 +2665,16 @@ border 1pixel
bindsym $mod+t border normal 0
# use no window title and a thick border
bindsym $mod+y border pixel 3
# use window title *and* a thick border
bindsym $mod+y border normal 3
# use neither window title nor border
bindsym $mod+u border none
# no border on VLC
for_window [class="vlc"] border none
----------------------------------------------

To change the default for all windows, see the directive <<default_border>>.

[[shmlog]]
=== Enabling shared memory logging

Expand Down
1 change: 0 additions & 1 deletion i3bar/src/xcb.c
Expand Up @@ -1540,7 +1540,6 @@ void clean_xcb(void) {
free_font();

xcb_free_cursor(xcb_connection, cursor);
xcb_flush(xcb_connection);
xcb_aux_sync(xcb_connection);
xcb_disconnect(xcb_connection);

Expand Down

0 comments on commit dd7cfdd

Please sign in to comment.