Subscribe

Subscribe

This message type is used to subscribe/unsubscribe to dwm events. The payload of this message should be a JSON document that specifies the event and the action to perform i.e. subscribe or unsubscribe.

The following events can be subscribed to:

tag_change_event
layout_change_event
client_focus_change_event
monitor_focus_change_event
focused_title_change_event
focused_state_change_event

The tag_change_event is raised when there is a change in the urgent flag for any of the clients, change in which tags are occupied by clients, or change in the current tags in view.

The layout_change_event is raised when the current layout on any of the monitors change (i.e. Monitor->lt or Monitor->ltsymbol changes).

The client_focus_change_event is raised when the focus changes to another client on any monitor (i.e. Monitor->sel changes).

This focused_title_change_event is raised when a currently selected/focused client has a title change (Monitor->sel.name change). This would be triggered when for example a new tab is opened on a focused browser and the window title changes.

The focused_state_change_event is raised when a currently selected/focused client has a state change. The following state changes trigger this event:

• oldstate
• isfixed
• isfloating
• isfullscreen
• isurgent
• neverfocus

Each of the above events are a monitor-specific event and as a result are raised when any of these events occur on a particular monitor.

The monitor_focus_change_event is raised when the monitor in focus (i.e. selmon) changes.

Message Request Format

An IPC_TYPE_SUBSCRIBE message type should contian a payload in the following format:

{
  "event": "<event_name>",
  "action": "<subscribe|unsubscribe>"
}

The event key should contain the name of the event as specified above. The action key should either be subscribe or unsubscribe.

Message Reply Format

A reply to an IPC_TYPE_SUBSCRIBE message will be a JSON document. If the event was succesfully subscribed/unsubscribe to, you will receive the following reply:

{"result": "success"}

If there was a failure parsing the message, or the event/action specified does not exist, you will receive a reply as follows:

{
  "result": "failure",
  "reason": "<reason>"
}

Receiving Events

To learn more about receiving events, go to the Events page.