View Source SwaySock (sway_sock v0.3.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.

Examples

Check out the examples/ directory.

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.

Types

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
@spec get_bar_config(atom(), binary()) :: json()

Returns the list of configured bar IDs.

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

@spec get_binding_modes(atom()) :: json()

Returns a list of configured binding modes

@spec get_binding_state(atom()) :: json()

Returns the currently active binding mode.

@spec get_config(atom()) :: json()

Returns the contents of the last-loaded sway configuration

@spec get_inputs(atom()) :: json()

Returns a list of the input devices currently available

@spec get_marks(atom()) :: json()

Returns the currently set marks

@spec get_outputs(atom()) :: json()

Returns the list of outputs

@spec get_tree(atom()) :: json()

Returns the JSON representation of sway's node tree

@spec get_version(atom()) :: json()

Returns version information about the current sway process

@spec get_workspaces(atom()) :: json()

Retrieves the list of active workspaces

Link to this function

run_command(conn, script)

View Source
@spec run_command(atom(), binary()) :: :ok | :error

Runs the sway commands in script

Returns {:error, <errors>} if any of the commands in script fail. The second element of the tuple will be the list of errors reported by sway. Returns :ok otherwise.

Link to this function

send_tick(conn, payload \\ "")

View Source
@spec send_tick(atom(), binary()) :: :ok | :error

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. Returns :ok if the message was successfully sent. Returns :error otherwise

@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, callback_start_state \\ nil)

View Source

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

Events

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.

Callback

The callback must accept two arguments:

  • The first is the the event details, and has this structure: {:event_name, payload} It is a two-element tuple where the first element is an atom representing the event, and the second is its payload.

  • The second argument is state for the callback. The return value of one invocation of the callback is used as the state for the next. The state is initialized to callback_start_state.