From 3e4f8d402ea93b60553f44367e17f5c3d7b53513 Mon Sep 17 00:00:00 2001 From: patrick96 Date: Sun, 7 Jun 2020 21:52:54 +0200 Subject: [PATCH] doc: Initial action documentation --- doc/conf.py | 4 ++ doc/index.rst | 2 + doc/user/actions.rst | 150 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 156 insertions(+) create mode 100644 doc/user/actions.rst diff --git a/doc/conf.py b/doc/conf.py index 9be48761..9b85ded9 100644 --- a/doc/conf.py +++ b/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 ------------------------------------------------- diff --git a/doc/index.rst b/doc/index.rst index fcd2ce7d..89a8ada8 100644 --- a/doc/index.rst +++ b/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: diff --git a/doc/user/actions.rst b/doc/user/actions.rst new file mode 100644 index 00000000..157d4e00 --- /dev/null +++ b/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 `_ 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 `_ +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 `_ +(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`` | | | ++-------------------------+------------------+---------------+