Usage examples

The examples below assume some familiarity with Qt development as well as i3wm's IPC idioms.

Listening to the window manager

Below is an example that monitors window events from i3wm.

There are no free functions. All functionality is through the qi3pc class. So first, an object of that class has to be constructed.

auto ipc = qi3pc();

Events from the window manager are available as Qt signals. To monitor those events, simply subscribe to them as to any other Qt signal. Window events include creation of new window, focus change, window move, etc.

QObject::connect(&ipc,
                 &qi3pc::windowEvent,
                 [](qi3pc::WindowChange change, const QJsonObject& container){
                    qDebug() << "Window event!";
 
                    if (change == qi3pc::WindowChange::Focus) {  
                        qDebug() << "Window focus changed!";
                    }
                });

Next, connect to the i3wm's IPC server.

ipc.connect();

Multiple qi3pc objects can be instantiated in the same application. Each object is only notified of the event it cares about. These events have to be explicitly subscribed to. Without this, the qi3pc::windowEvent signal will never fire on this object, and the lambda in the connection above will never run.

QStringList events("window");
ipc.subscribe(events);

Talking to the window manager

Below is an example showing how to automatically move to a newly created workspace.

MyClass::MyClass() {
    QObject::connect(&m_ipc,
                     &qip3c::workspaceEvent,
                     this,
                     &MyClass::handleWorkspaceEvent);
 
    m_ipc.connect();
 
    QStringList events("workspace");
    m_ipc.subscribe(events);
}
 
void
MyClass::handleWorkspaceEvent(qi3pc::WorkspaceChange change,
                              const QJsonObject& current,
                              const QJsonObject& old)
{
    Q_UNUSED(old)
    if (change == qi3pc::WorkspaceChange::Init) {
        if (auto jsonStr = current["name"]; !jsonStr.isUndefined()) {
            QString name = jsonStr.toString();
 
            QByteArray payload;
            QString i3Command = "workspace " + name;
            payload.append(i3Command.toStdString().c_str());
            m_ipc.sendMessage<qi3pc::IpcType::Command>(payload);
        }
    }
}

When a new workspace is created, a command is sent to switch to it. As simple as that!

A conversation with the window manager

In the example above, after sending the workspace change request to i3wm, the response is not monitored, simply because the interesting side effect is the wokspace change itself (and also because it was just a simple example). However, sometimes we are interested in the reply from the wm. For those cases, message replies are also published with Qt signals.

To actively fetch information from i3wm, the fetch methods can be used (e.g. qi3pc::fetchWorkspaces). When called, a message is sent to i3wm, and the reply is published through a reply signal. In the case of workspaces, through qi3pc::workspacesUpdated.

Additionally, the reply is cached along with its last update time. This cached data is available through another member function, in this case qi3pc::workspaces.

The following is an example of using that workflow.

MyClass::MyClass() {
    m_ipc.connect();
    
    QObject::connect(&m_ipc,
                     &qi3pc::workspacesUpdated,
                     this,
                     &MyClass::handleWorkspaceReply);
    
    // Query up-to-date workspace information from i3wm
    m_ipc.fetchWorkspaces();
}
 
void
MyClass::handleWorkspaceReply(const qi3pc::DataArray& data)
{
    qDebug() << "List of workspaces";
    qDebug() << data->first;
 
  qDebug() << "Cached list of workspaces";
  qDebug() << ipc.workspaces().first();
}

Note that in this case there was no need to subscribe to workspace events with qi3pc::subscribe.

More examples

Other examples can be found in the repository.