View Source SwaySock (sway_sock v0.2.0)

SwaySock is a library for controlling the running Sway process through its IPC interface.

You can query the state of the window manager, listen to events, and execute sway commands. This module provides the main API to interfacing with Sway via IPC

Overview

start_link/1 starts a Supervisor that connects to Sway's Unix Domain Socket. This implies the library is useless without a currently running sway instace.

The architecture is simple. All commands apart from subscribe/3 are translated to IPC messages and sent to the sway socket. The response is immediately read from the socket and returned as-is.

subscribe/3 is a special case. The i3 docs explain it clearly:

Caveat: As soon as you subscribe to an event, it is not guaranteed any longer that the requests to i3 are processed in order. This means, the following situation can happen: You send a GET_WORKSPACES request but you receive a "workspace" event before receiving the reply to GET_WORKSPACES. If your program does not want to cope which such kinds of race conditions (an event based library may not have a problem here), I suggest you create a separate connection to receive events.

The same applies to Sway. This library opts to open a new connection to the sway socket for each event subscription. This is always done in supervised Task.

Reply structure

The sway developers may change the format of replies across releases. Users of this library are encouraged to refer to the sway-ipc manual (man sway-ipc) for the schemas of the JSON sway sends back.

Summary

Functions

Returns a specification to start this module under a supervisor.

Returns the list of configured bar IDs.

Returns a list of configured binding modes

Returns the currently active binding mode.

Returns the contents of the last-loaded sway configuration

Returns a list of the input devices currently available

Returns the currently set marks

Returns the list of outputs

Returns the JSON representation of sway's node tree

Returns version information about the current sway process

Retrieves the list of active workspaces

Runs the sway commands in script

Sends a TICK event to all clients subscribing to the event to ensure that all events prior to the tick were received.

Connects to the Sway socket. name identifies the connection

Creates a new linked process that invokes callback when any of the listed event_types occurs

Functions

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this function

get_bar_config(conn, bar_id \\ "")

View Source

Returns the list of configured bar IDs.

When bar_id is non-empty, this function returns the configuration of the given bar instead.

Returns a list of configured binding modes

Returns the currently active binding mode.

Returns the contents of the last-loaded sway configuration

Returns a list of the input devices currently available

Returns the currently set marks

Returns the list of outputs

Returns the JSON representation of sway's node tree

Returns version information about the current sway process

Retrieves the list of active workspaces

Link to this function

run_command(conn, script)

View Source

Runs the sway commands in script

Commands are generally separated by newlines. However, they can also be separated by commas (,) or semi-colons (;). See the sway manual (man 5 sway) for more details.

Link to this function

send_tick(conn, payload \\ "")

View Source

Sends a TICK event to all clients subscribing to the event to ensure that all events prior to the tick were received.

If a payload is given, it will be included in the TICK event

@spec start_link(name :: atom()) :: {:ok, pid()}

Connects to the Sway socket. name identifies the connection

Multiple instances of this library may be used as long as they have different names.

How to supervise

iex> children = [ {SwaySock, :my_socket} ]
...> Supervisor.start_link(children, strategy: :one_for_one)
Link to this function

subscribe(conn, event_types, callback)

View Source

Creates a new linked process that invokes callback when any of the listed event_types occurs

You may subscribe to any of the following events

:workspace, :output, :mode, :window, :barconfig_update, :binding, :shutdown, :tick, :bar_state_update, :input

Events are described in the sway-ipc manual under the "EVENTS" section.