121 lines
3.7 KiB
ReStructuredText
121 lines
3.7 KiB
ReStructuredText
Inter-process-messaging
|
|
=======================
|
|
|
|
Polybar supports controlling parts of the bar and its modules from the outside
|
|
through inter-process-messaging (IPC).
|
|
|
|
IPC is disabled by default and can be enabled by setting ``enable-ipc = true``
|
|
in the bar section.
|
|
|
|
By default polybar ships with the ``polybar-msg`` tool that is needed to send
|
|
messages to polybar.
|
|
|
|
.. note:: Starting with version 3.6.0, the underlying IPC mechanism has been
|
|
completely changed.
|
|
|
|
Writing directly to the named pipe to send IPC messages has been
|
|
deprecated, ``polybar-msg`` should be used exclusively
|
|
Everything you could do by directly writing to the named pipe, you
|
|
can also do using ``polybar-msg``.
|
|
In addition, hook messages are also deprecated; they are replaced by
|
|
actions on the :ref:`ipc module <actions-ipc>`.
|
|
|
|
Unless noted otherwise, everything in this guide is still valid for
|
|
older versions.
|
|
|
|
Sending Messages
|
|
----------------
|
|
|
|
``polybar-msg`` can be called on the commandline like this:
|
|
|
|
.. code-block:: shell
|
|
|
|
polybar-msg [-p <pid>] <type> <payload>
|
|
|
|
If the ``-p`` argument is specified, the message is only sent to the running
|
|
polybar instance with the given process ID.
|
|
Otherwise, the message is sent to all running polybar processes that have IPC
|
|
enabled.
|
|
|
|
.. note:: IPC messages are only sent to polybar instances running under the
|
|
same user as ``polybar-msg`` is running as.
|
|
|
|
Concretely, ``polybar`` and ``polybar-msg`` use the
|
|
``$XDG_RUNTIME_DIR`` environment variable in accordance with the `XDG
|
|
Base Directory Specification`_ to determine where to find the socket
|
|
to communicate.
|
|
|
|
If ``polybar`` and ``polybar-msg`` don't have the same value for
|
|
``$XDG_RUNTIME_DIR``, they will likely not be able to communicate.
|
|
The variable may not be set if you use ``su`` or ``sudo`` to execute
|
|
``polybar-msg`` as a different user, often a full user session is
|
|
required.
|
|
|
|
.. _XDG Base Directory Specification: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
|
|
|
|
The ``<type>`` argument is either :ref:`action <ipc-actions>` or
|
|
:ref:`cmd <ipc-commands>`.
|
|
The allowed values for ``<payload>`` depend on the type.
|
|
|
|
Message Types
|
|
-------------
|
|
|
|
.. _ipc-commands:
|
|
|
|
Commands
|
|
^^^^^^^^
|
|
|
|
Using ``cmd`` for ``<type>``, you can control certain aspects of the bar.
|
|
|
|
Available values for ``<payload>`` are:
|
|
|
|
* ``quit``: Terminates the bar
|
|
* ``restart``: Restarts the bar in-place
|
|
* ``hide``: Hides the bar
|
|
* ``show``: Makes the bar visible again, if it was hidden
|
|
* ``toggle``: Toggles between the hidden and visible state.
|
|
|
|
.. _ipc-actions:
|
|
|
|
Module Actions
|
|
^^^^^^^^^^^^^^
|
|
|
|
For the ``<type>`` ``action``, ``polybar-msg`` can execute
|
|
:doc:`module actions <actions>` in the bar.
|
|
|
|
An action consists of the name of the target module, the name of the action and an optional data string:
|
|
|
|
::
|
|
|
|
#<modulename>.<actionname>[.<data>]
|
|
|
|
More information about action strings and available actions can be found in
|
|
:doc:`actions`
|
|
|
|
For example, if you have a date module named ``date``, you can toggle between
|
|
the regular and alternative label with:
|
|
|
|
.. code-block:: shell
|
|
|
|
polybar-msg action "#date.toggle"
|
|
|
|
As an example for an action with data, say you have a menu module named
|
|
``powermenu``, you can open the menu level 0 using:
|
|
|
|
.. code-block:: shell
|
|
|
|
polybar-msg action "#powermenu.open.0"
|
|
|
|
|
|
.. note::
|
|
|
|
For convenience, ``polybar-msg`` also allows you to pass the module name,
|
|
action name, and data as separate arguments:
|
|
|
|
.. code-block:: shell
|
|
|
|
polybar-msg action date toggle
|
|
polybar-msg action powermenu open 0
|
|
|
|
.. versionadded:: 3.6.0
|