151 lines
5.0 KiB
ReStructuredText
151 lines
5.0 KiB
ReStructuredText
Actions
|
|
=======
|
|
|
|
.. versionadded:: 3.5.0
|
|
|
|
"Actions" are used to trigger certain behavior in modules.
|
|
For example, when you click on your volume module (pulseaudio or alsa), polybar
|
|
internally sends an action to that module that tells it to mute/unmute the
|
|
audio.
|
|
|
|
Action String Format
|
|
--------------------
|
|
|
|
An action string follows the following format:
|
|
|
|
::
|
|
|
|
#NAME.ACTION[.DATA]
|
|
|
|
Where ``NAME`` is the name of the target module (not the type!) and ``ACTION``
|
|
is the name of the action in that module. ``DATA`` is optional data attached to
|
|
an action (for example to say which menu level should be opened).
|
|
|
|
For example the
|
|
`date module <https://github.com/polybar/polybar/wiki/Module:-date>`_ supports
|
|
the ``toggle`` action to toggle between the regular and the alternative time and
|
|
date format.
|
|
If you have the following date module:
|
|
|
|
.. code-block:: ini
|
|
|
|
[module/mydate]
|
|
type = internal/date
|
|
...
|
|
|
|
The action string for toggling between the date formats would look like this:
|
|
|
|
::
|
|
|
|
#mydate.toggle
|
|
|
|
As an example for an action string with additional data, take the menu module:
|
|
|
|
.. code-block:: ini
|
|
|
|
[module/powermenu]
|
|
type = custom/menu
|
|
menu-0-0 = Poweroff
|
|
menu-0-0-exec = poweroff
|
|
menu-0-1 = Suspend
|
|
menu-0-1-exec = systemctl suspend
|
|
|
|
The action name to open a certain menu level is ``open``, so to open level 0
|
|
(`menu-0`), the action string additionally has the level attached to it:
|
|
|
|
::
|
|
|
|
#powermenu.open.0
|
|
|
|
Triggering Actions
|
|
------------------
|
|
|
|
Most modules already use action strings to trigger actions when you click on or
|
|
scroll over a module.
|
|
But in some cases you may want or need to manually send action strings to
|
|
polybar to trigger a certain behavior.
|
|
|
|
Everywhere where you can specify a command to run on click or scroll, you can
|
|
also specify an action string.
|
|
For example, in the bar section, you can specify a command that is triggered
|
|
when you click anywhere on the bar (where there isn't another click action):
|
|
|
|
.. code-block:: ini
|
|
|
|
[bar/mybar]
|
|
...
|
|
click-left = #mydate.toggle
|
|
...
|
|
|
|
This will then trigger the ``toggle`` action on the ``mydate`` module when you
|
|
click anywhere on the bar.
|
|
|
|
Similarly, we can use action strings in ``%{A}``
|
|
`formatting tags <https://github.com/polybar/polybar/wiki/Formatting#action-a>`_
|
|
just as we would regular commands:
|
|
|
|
::
|
|
|
|
%{A1:firefox:}%{A3:#mydate.toggle:}Opens firefox on left-click and toggles the
|
|
date on right-click %{A}%{A}
|
|
|
|
Finally, polybar's
|
|
`Inter Process Messaging <https://github.com/polybar/polybar/wiki/Inter-process-messaging>`_
|
|
(IPC) can also be used to trigger actions:
|
|
|
|
.. code-block:: bash
|
|
|
|
polybar-msg action "#mydate.toggle"
|
|
|
|
.. note::
|
|
|
|
The quotes around the action string are necessary, otherwise your shell will
|
|
interpret the ``#`` as the beginning of the comment and ignore the rest of the
|
|
line.
|
|
|
|
Supported Actions
|
|
-----------------
|
|
|
|
|
|
Legacy Action Names
|
|
-------------------
|
|
|
|
Before actions included the name of the module it should be sent to, action
|
|
strings only included information about the module type.
|
|
This meant for bars that contained multiple different modules of the same type,
|
|
actions for these modules were sometimes processed by the wrong module with the
|
|
same type.
|
|
|
|
Migration to New Action Strings
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
+-------------------------+------------------+---------------+
|
|
|Module Type |Legacy Action Name|New Action Name|
|
|
+=========================+==================+===============+
|
|
|``internal/date`` |``datetoggle`` |``toggle`` |
|
|
+-------------------------+------------------+---------------+
|
|
|``internal/alsa`` |``volup`` |``inc`` |
|
|
| +------------------+---------------+
|
|
| |``voldown`` |``dec`` |
|
|
| +------------------+---------------+
|
|
| |``volmute`` |``toggle`` |
|
|
+-------------------------+------------------+---------------+
|
|
|``internal/pulseaudio`` | | |
|
|
+-------------------------+------------------+---------------+
|
|
|``internal/xbacklight`` | | |
|
|
+-------------------------+------------------+---------------+
|
|
|``internal/backlight`` | | |
|
|
+-------------------------+------------------+---------------+
|
|
|``internal/xkeyboard`` | | |
|
|
+-------------------------+------------------+---------------+
|
|
|``internal/mpd`` | | |
|
|
+-------------------------+------------------+---------------+
|
|
|``internal/xworkspaces`` | | |
|
|
+-------------------------+------------------+---------------+
|
|
|``internal/bspwm`` | | |
|
|
+-------------------------+------------------+---------------+
|
|
|``internal/i3`` | | |
|
|
+-------------------------+------------------+---------------+
|
|
|``custom/menu`` | | |
|
|
+-------------------------+------------------+---------------+
|