mirror of https://github.com/polybar/polybar.git
doc(tray): Initial experiments
This commit is contained in:
patrick96
Patrick Ziegler
parent
df32703a22
commit
c6eb3f88ea
|
|
@ -13,6 +13,7 @@
|
|||
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||
#
|
||||
import os
|
||||
import sys
|
||||
from pathlib import Path
|
||||
import datetime
|
||||
import sphinx
|
||||
|
|
@ -110,6 +111,8 @@ highlight_language = 'none'
|
|||
|
||||
smartquotes = False
|
||||
|
||||
primary_domain = 'polybar'
|
||||
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
|
||||
|
|
@ -240,6 +243,9 @@ if packaging.version.parse(sphinx.__version__) >= packaging.version.parse("1.8.5
|
|||
app.add_directive('deprecated', VersionDirective)
|
||||
app.add_directive('versionadded', VersionDirective)
|
||||
app.add_directive('versionchanged', VersionDirective)
|
||||
sys.path.insert(0, os.path.abspath(doc_path))
|
||||
from configdomain import myDomain
|
||||
app.add_domain(myDomain)
|
||||
|
||||
class VersionDirective(VersionChange):
|
||||
"""
|
||||
|
|
|
|||
|
|
@ -0,0 +1,48 @@
|
|||
# -*- coding: utf-8 -*-
|
||||
"""
|
||||
configdomain
|
||||
~~~~~~~~~~~~
|
||||
|
||||
TODO document
|
||||
"""
|
||||
|
||||
from sphinxcontrib.domaintools import custom_domain
|
||||
from sphinx.util.docfields import Field, GroupedField
|
||||
|
||||
__version__ = "0.1.0"
|
||||
# for this module's sphinx doc
|
||||
release = __version__
|
||||
version = release.rsplit('.', 1)[0]
|
||||
|
||||
|
||||
myDomain = custom_domain('PolybarConfigDomain',
|
||||
name='polybar',
|
||||
label="Polybar Configuration",
|
||||
|
||||
elements=dict(
|
||||
setting=dict(
|
||||
objname="Config Setting",
|
||||
fields=[
|
||||
Field('type',
|
||||
label="Type",
|
||||
names=['type'],
|
||||
has_arg=False,
|
||||
),
|
||||
Field('tags',
|
||||
label="Available Tags",
|
||||
names=['tags'],
|
||||
has_arg=False,
|
||||
),
|
||||
Field('tokens',
|
||||
label="Supported Tokens",
|
||||
names=['tokens'],
|
||||
has_arg=False,
|
||||
),
|
||||
Field('default',
|
||||
label="Default Value",
|
||||
names=['default'],
|
||||
has_arg=False,
|
||||
),
|
||||
]
|
||||
),
|
||||
))
|
||||
|
|
@ -15,6 +15,12 @@ Welcome to the official polybar documentation.
|
|||
user/actions
|
||||
user/ipc
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: Modules:
|
||||
|
||||
user/modules/tray
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: Manual Pages:
|
||||
|
|
|
|||
|
|
@ -0,0 +1 @@
|
|||
sphinxcontrib-domaintools
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
.. highlight:: ini
|
||||
|
||||
..
|
||||
Substitutions for quickly referencing different config value types
|
||||
|
||||
.. |type-format| replace:: `format <type-format_>`_
|
||||
.. |type-extent| replace:: `extent <type-extent_>`_
|
||||
.. |type-pwo| replace:: `percentage with offset <type-pwo_>`_
|
||||
.. |type-color| replace:: color
|
||||
|
||||
.. _type-format: https://github.com/polybar/polybar/wiki/Formatting#formats
|
||||
.. _type-extent: https://github.com/polybar/polybar/wiki/Formatting#extent
|
||||
.. _type-pwo: https://github.com/polybar/polybar/wiki/Formatting#percentage-with-offset
|
||||
|
|
@ -0,0 +1,112 @@
|
|||
.. include:: defs.rst
|
||||
|
||||
Tray Module
|
||||
===========
|
||||
|
||||
.. versionadded:: 3.7.0
|
||||
|
||||
The tray module displays system tray application icons on the bar.
|
||||
|
||||
This module is a bit different from the other modules.
|
||||
The tray icons (also called clients) are individual windows managed by their
|
||||
respective application (e.g. the Dropbox tray icon is created and managed by
|
||||
the Dropbox application).
|
||||
Polybar is only responsible for embedding the windows in the bar and
|
||||
positioning them correctly.
|
||||
|
||||
.. note::
|
||||
|
||||
Only a single instance of this module can be active at the same time (across
|
||||
all polybar instances).
|
||||
|
||||
The way the `system tray protocol <systray-spec_>`_ works, at most one tray
|
||||
can exist at any time.
|
||||
Polybar will produce a warning if additional tray instances are created.
|
||||
|
||||
For transparent background colors, the tray will use pseudo-transparency, true
|
||||
transparency is not possible for the tray icons.
|
||||
|
||||
TODO mention the ``type`` setting somewhere
|
||||
|
||||
Formats
|
||||
-------
|
||||
|
||||
The module only has a single format:
|
||||
|
||||
.. setting:: format
|
||||
|
||||
:type: |type-format|
|
||||
:tags: ``<tray>``: Shows tray icons
|
||||
:default: ``<tray>``
|
||||
|
||||
Settings
|
||||
--------
|
||||
|
||||
.. setting:: tray-spacing
|
||||
|
||||
Space added between tray icons
|
||||
|
||||
:type: |type-extent|, non-negative
|
||||
:default: ``0px``
|
||||
|
||||
.. setting:: tray-padding
|
||||
|
||||
Space added before and after each tray icon
|
||||
|
||||
:type: |type-extent|, non-negative
|
||||
:default: ``0px``
|
||||
|
||||
.. setting:: tray-size
|
||||
|
||||
Size of individual tray icons
|
||||
|
||||
Relative to bar height
|
||||
|
||||
:type: |type-pwo|, non-negative
|
||||
:default: 66%
|
||||
|
||||
.. setting:: tray-background
|
||||
|
||||
Background color of tray icons
|
||||
|
||||
.. note::
|
||||
This only affects the color of the individual icons and not the space in
|
||||
between, changing this setting will likely not look good.
|
||||
|
||||
:type: |type-color|
|
||||
:default: ``${root.background}``
|
||||
|
||||
.. setting:: tray-foreground
|
||||
|
||||
Tray icon color hint
|
||||
|
||||
This serves as a hint to the tray icon application what color to use for the
|
||||
icon.
|
||||
|
||||
This is not guaranteed to have any effect (likely only in GTK3) because it
|
||||
targets a non-standard part of the `system tray protocol <systray-spec_>`_ by
|
||||
setting the ``_NET_SYSTEM_TRAY_COLORS`` atom on the tray window.
|
||||
|
||||
:type: |type-color|
|
||||
:default: ``${tray-foreground}``
|
||||
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
::
|
||||
|
||||
[module/tray]
|
||||
type = internal/tray
|
||||
|
||||
format-margin = 8px
|
||||
tray-spacing = 8px
|
||||
|
||||
References
|
||||
----------
|
||||
|
||||
* `System Tray Protocol Specification <systray-spec_>`_
|
||||
* `XEmbed Protocol Specification <xembed_>`_
|
||||
|
||||
.. _systray-spec: https://specifications.freedesktop.org/systemtray-spec/systemtray-spec-latest.html
|
||||
.. _xembed: https://specifications.freedesktop.org/xembed-spec/xembed-spec-latest.html
|
||||
Loading…
Reference in New Issue