API Docs

Connection

UNIX socket connection to a running i3 session. Connection() will open a connection to the default i3 session conneciton obtained with the command i3 --get-socketpath. In most use cases this is likely to be the only valid connection.

Node

A node in an i3 tree.

Output

Data structure describing an output device.

Rectangle

A rectangle on a screen within an i3 session.

Fields

• x: $x$ position in pixels.
• y: $y$ position in pixels.
• Δx: Extent in $x$ in pixels. Referred to by i3 IPC as width.
• Δy: Extent in $y$ in pixels. Referred to by i3 IPC as height.

Workspace

Data structure describing and i3 workspace.

children(n::Node)

Get the immediate children of the i3 tree node.

child(n::Node, i)

Get the child of n at index i.

command([cnxn,] cmd)

Execute i3 command cmd. If no connection is provided, the default will be used.

config([cnxn])

Get the currently loaded i3 config file.

criteria_string(args)

Construct the string for specifying the command criteria to an i3 command. args should be in iterable of key-value pairs or 2-tuples.

defaultconnection!()

Set the cached connection to the default i3 session. This sets a global variable which is accessible through defaultconnection().

defaultconnection()

Get the cached connection to the default i3 session.

descendants(𝒻, n::Node)

Return the descendants of node n for which f(n) == true.

descendants(𝒻)

Get the descendants of the root node of the current tree for which 𝒻 returns true.

descendants(n::Node)

Returns an iterator of all descendants of the i3 Node.

descendants()

Gets all descendants of the current tree. This is just like tree(), except that it returns the tree flattened.

exec([cnxn,] arg; no_startup_id=false)

Executes the command given by the string (or Cmd) arg. If no_startup_id, the resulting new window may not open in the same workspace or move thet mouse cursor.

Note that the argument arg will automatically be enclosed with quotes when sent to i3, so outer quites are not necessary.

exit([cnxn])

Exit the i3 session.

floating([cnxn])

Toggle the current window between floating and tiled.

focus([cnxn, arg]; kwargs...)

Focus a window. arg should be a string, valid options are "left", "right", "up", "down", "parent", "child", "next" "prev". Keyword arguments can be valid command criteria.

Examples

I3.focus("right")  # moves focus to window to the right
I3.focus(class="firefox")  # focuses the window in which firefox is running

fullscreen_string([cnxn])

Toggle fullscreen of the current window.

getfocused(cnxn::Connection)

Get the currently focused window. Returns nothing if there isn't one.

haschildren(n::Node)

Returns true if the i3 tree node has immediate children, else false.

isfocused(n)

Whether the node is the currently focused window.

isleaf(n)

Whether the node is a leaf, i.e. has no descendants other than itself.

isnormalwindow(n)

Returns true if iswindwo(n) and the window type is "normal". These are "normal" windows in (arguably) the most obvious sense and should exclude toolbars, notifications and docks.

Note: This does not find floating windows.

iswindow(n)

Determines whether a node is a "normal" window. This should imply that the node is drawn on screen provided the workspace containing it is visible. Determining whether the node is actually visible is more expensive, see isvisible.

Note: This does not find floating windows.

layout([cnxn,] arg; toggle=false)

Change the current window layout. Valid optiosn are "default", "tabbed", "stacking", "splitv", "splith".

leaves(n::Node)

Get all leaves descended from the i3 tree node n. That is, only nodes which are descended from n but which do not themsleves have any children will appear in the returned list.

mark([cnxn,] arg)

Marks the current container with the name arg.

marks([cnxn])

Get list of marks.

messagemeta

Extract metadata from and i3 IPC message. Valid messages start with the bytes b"i3-ipc" followed by the message body as dictionary parsed from JSON.

move([cnxn,] arg [, x])

Move the current window. Valid arguments are "up", "down", "left", "right". If an integer x is provided, window will be moved by this many pixels.

moveposition([cnxn,] arg [, x]; absolute=false)
moveposition(x, y)

Move the current window. Valid arguments are "up", "right", "left", "down", "center", "mouse".

output([cnxn,] name)

Retrieve the output with name name. Returns nothing if it does not exist.

outputs([cnxn])

Retrieve a list of outputs on the i3 server accessible at connection cnxn.

pack

Prepare a message to be sent to the i3 session via IPC.

receive(cnxn)

Receive a message from the i3 session as a JSON. Returns type, v where type is the message type and v is the message body.

receivebytes(cnxn)

Receive an IPC message from the i3 session as a Vector{UInt8}. Returns type, v where type is the message type and v is the message body.

reload([cnxn])

Reload the i3 session.

restart([cnxn])

Restart the i3 session.

send

Send an IPC message to an i3 session.

sendreceive(cnxn, mtype, x=nothing)

Send a message of type mtype with body x (no body will be included if isnothing(x)) to the i3 session and wait for a response, returning the response as a dictionary parse from JSON.

sendreceivebytes(cnxn, mtype, x=nothing)

Send a message of type mtype with body x (no body will be included if isnothing(x)) to the i3 session and wait for a response, returning the response as a Vector{UInt8}.

serve(f, sockname)

Create a server at socket sockname. Once the socket is created, the server will block the thread until a single connection is accepted. Once this occurs, the server will repeatedly execute the function f on the IO stream from the socket.

To run this asyncronously use @async. To run on a new CPU thread, use Threads.@spawn.

socketpath()

Get the i3 session socket path by calling i3 --get-socketpath.

split([cnxn,] arg)

Split the current window (i.e. so that new windows will be contained in the current windows area).

Valid arguments are "vertical", "horizontal", "toggle".

tree([cnxn])

Get the root node of the i3 session tree. The entire tree is descended from the root node.

unmark([cnxn])

Unmark the current container.

workspace([cnxn,] name)

Retrieve the workspace with name name. Returns nothing if it does not exist.

workspaces([cnxn])

Retrieve a list of workspaces on the i3 server accessible at connection cnxn.