doc: Initial action documentation

doc/conf.py

@@ -89,6 +89,10 @@ exclude_patterns = []
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = None
 
+highlight_language = 'none'
+
+smartquotes = False
+
 
 # -- Options for HTML output -------------------------------------------------
 

doc/index.rst

@@ -12,6 +12,8 @@ Welcome to the official polybar documentation.
    :maxdepth: 2
    :caption: Contents:
 
+   user/actions
+
 .. toctree::
    :maxdepth: 1
    :caption: Manual Pages:

doc/user/actions.rst

@@ -0,0 +1,150 @@
+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``          |                  |               |
++-------------------------+------------------+---------------+