From d45ae7954a222c6ad2a4bd64739d2ae2e1e4f842 Mon Sep 17 00:00:00 2001 From: patrick96 Date: Fri, 23 Oct 2020 01:19:42 +0200 Subject: [PATCH] doc: Finish legacy action migration table --- doc/_static/.gitignore | 0 doc/index.rst | 2 +- doc/user/actions.rst | 142 ++++++++++++++++++++++++++++++----------- 3 files changed, 107 insertions(+), 37 deletions(-) create mode 100644 doc/_static/.gitignore diff --git a/doc/_static/.gitignore b/doc/_static/.gitignore new file mode 100644 index 00000000..e69de29b diff --git a/doc/index.rst b/doc/index.rst index a6bcc4e3..2e92668d 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -10,7 +10,7 @@ Welcome to the official polybar documentation. .. toctree:: :maxdepth: 1 - :caption: Contents: + :caption: Content: user/actions diff --git a/doc/user/actions.rst b/doc/user/actions.rst index 157d4e00..f674b147 100644 --- a/doc/user/actions.rst +++ b/doc/user/actions.rst @@ -8,6 +8,11 @@ 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. +These actions are not only used internally, but users can also send these +actions to polybar through `Inter Process Communication +`_ (IPC) to +trigger certain behavior in polybar modules. + Action String Format -------------------- @@ -89,9 +94,9 @@ 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: +Finally, polybar's `Inter Process Communication +`_ (IPC) can +also be used to trigger actions: .. code-block:: bash @@ -99,52 +104,117 @@ Finally, polybar's .. note:: - The quotes around the action string are necessary, otherwise your shell will + The quotes around the action string are necessary, otherwise your shell may interpret the ``#`` as the beginning of the comment and ignore the rest of the line. Supported Actions ----------------- +.. TODO 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, +In earlier versions (< 3.5.0) action strings only included information about the +module type. +This meant in 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. +Since version 3.5.0, this no longer happens. However, this also means we had to +change what actions are recognized by polybar modules. + +If you explicitly use any polybar action names in your config or any of your +scripts, you are advised to change them, as they may stop working at some point. +For now polybar still supports the old action names, will convert them to the +appropriate new action name, and will print a warning to help you find old +action names in your config. + +If you use the `menu module +`_, you most likely use +old action names to open and close the menu (for example ``menu-open-1`` or +``menu-close``). +The ``i3wm-wsnext``, ``i3wm-wsprev``, ``bspwm-desknext``, and ``bspwm-deskprev`` +actions, to switch workspaces in i3 and bspwm, may also appear in your config. + 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`` | | | -+-------------------------+------------------+---------------+ ++-------------------------+-----------------------+---------------+ +|Module Type |Legacy Action Name |New Action Name| ++=========================+=======================+===============+ +|``internal/date`` |``datetoggle`` |``toggle`` | ++-------------------------+-----------------------+---------------+ +|``internal/alsa`` |``volup`` |``inc`` | +| +-----------------------+---------------+ +| |``voldown`` |``dec`` | +| +-----------------------+---------------+ +| |``volmute`` |``toggle`` | ++-------------------------+-----------------------+---------------+ +|``internal/pulseaudio`` |``pa_volup`` |``inc`` | +| +-----------------------+---------------+ +| |``pa_voldown`` |``dec`` | +| +-----------------------+---------------+ +| |``pa_volmute`` |``toggle`` | ++-------------------------+-----------------------+---------------+ +|``internal/xbacklight`` |``xbacklight+`` |``inc`` | +| +-----------------------+---------------+ +| |``xbacklight-`` |``dec`` | ++-------------------------+-----------------------+---------------+ +|``internal/backlight`` |``backlight+`` |``inc`` | +| +-----------------------+---------------+ +| |``backlight-`` |``dec`` | ++-------------------------+-----------------------+---------------+ +|``internal/xkeyboard`` |``xkeyboard/switch`` |``switch`` | ++-------------------------+-----------------------+---------------+ +|``internal/mpd`` |``mpdplay`` |``play`` | +| +-----------------------+---------------+ +| |``mpdpause`` |``pause`` | +| +-----------------------+---------------+ +| |``mpdstop`` |``stop`` | +| +-----------------------+---------------+ +| |``mpdprev`` |``prev`` | +| +-----------------------+---------------+ +| |``mpdnext`` |``next`` | +| +-----------------------+---------------+ +| |``mpdrepeat`` |``repeat`` | +| +-----------------------+---------------+ +| |``mpdsingle`` |``single`` | +| +-----------------------+---------------+ +| |``mpdrandom`` |``random`` | +| +-----------------------+---------------+ +| |``mpdconsume`` |``consume`` | +| +-----------------------+---------------+ +| |``mpdseekN`` |``seek.N`` | ++-------------------------+-----------------------+---------------+ +|``internal/xworkspaces`` |``xworkspaces-focus=N``|``focus.N`` | +| +-----------------------+---------------+ +| |``xworkspaces-next`` |``next`` | +| +-----------------------+---------------+ +| |``xworkspaces-prev`` |``prev`` | ++-------------------------+-----------------------+---------------+ +|``internal/bspwm`` |``bspwm-deskfocusN`` |``focus.N`` | +| +-----------------------+---------------+ +| |``bspwm-desknext`` |``next`` | +| +-----------------------+---------------+ +| |``bspwm-deskprev`` |``prev`` | ++-------------------------+-----------------------+---------------+ +|``internal/i3`` |``i3wm-wsfocus-N`` |``focus.N`` | +| +-----------------------+---------------+ +| |``i3-wsnext`` |``next`` | +| +-----------------------+---------------+ +| |``i3-wsprev`` |``prev`` | ++-------------------------+-----------------------+---------------+ +|``custom/menu`` |``menu-open-N`` |``open.N`` | +| +-----------------------+---------------+ +| |``menu-close`` |``close`` | ++-------------------------+-----------------------+---------------+ + +.. note:: + + Some legacy action names are suffixed with ``N``, this means that action has + some additional data (represented by that ``N``), in the new action names, + this data will appear in exactly the same way, after a period. + +.. TODO show how to migrate