polybar_actions.md

Since #2336, adding actions to modules in Polybar is a lot easier to both understand and implement. This is a short development guide to adding these actions because it is not very well documented. All filenames referenced here use a placeholder module name.

More concrete examples can be found by perusing this diff.

module.hpp

Add the following lines to the corresponding sections of the header file. These declare a constant for the name of the action and a function where the consequences for calling the action are found.

public:
  static constexpr auto EVENT_NAME = "name";

protected:
  void action_name();

module.cpp

In the constructor of the module, call the following function. This registers the action in the action router m_router, an instance of the action router created in the base module.

m_router->register_action(EVENT_NAME, &module_class::action_name);

This line of code tells the action router m_router to associate the action name string with the method declared in the header.

Then, implement the consequences of the action in that method:

void module_class::action_name() {
  // Implementation here
}

Payload data

Some actions, like the date module's toggle action, need no input. However, inputting some data is crucial for correctly implementing some actions, like the XWorkspaces module's focus action. To accomplish this, change the method signature to include a data parameter:

// module.hpp
void action_name(const string& data);

// module.cpp
void module_class::action_name(const string& data) {

To register this action, you must use the register_action_with_data function instead of the register_action function:

m_router->register_action_with_data(EVENT_NAME, &module_class::action_name);

Other than these minor changes, the process remains the same.

Universal Actions

A prime example.

For universal actions, the instructions are largely the same. Instead of placing the code in mymodule.hpp, place it in meta/base.hpp in the module template class. Instead of placing code in mymodule.cpp, place it in meta/base.inl (found in the includes folder too--I'm confused as well).

Make sure that your universal action names do not collide with any other action names. Polybar will blow up.