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
@type json() :: :json.decode_value()
Functions
Returns a specification to start this module under a supervisor.
See Supervisor
.
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
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.
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
Connects to the Sway socket. name
identifies the connection
Multiple instances of this library may be used as long as they have different name
s.
How to supervise
iex> children = [ {SwaySock, :my_socket} ]
...> Supervisor.start_link(children, strategy: :one_for_one)
subscribe(conn, event_types, callback, callback_start_state \\ nil)
View SourceCreates 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
.