49c1465b65
make it possible to compile documentation via sphinx - main change is to use RST instead of MarkDown for most files.
160 lines
5 KiB
ReStructuredText
160 lines
5 KiB
ReStructuredText
How to write a new module
|
||
=========================
|
||
|
||
Introduction
|
||
------------
|
||
|
||
Adding a new module to ``bumblebee-status`` is straight-forward:
|
||
|
||
- Add a new Python module in ``modules/contrib/``. The name of the
|
||
module will be the name that the user needs to specify when invoking
|
||
``bumblebee-status`` (i.e. a module called
|
||
``modules/contrib/test.py`` will be loaded using
|
||
``bumblebee-status -m test``)
|
||
- See below for how to actually write the module
|
||
- Test (run ``bumblebee-status`` in the CLI)
|
||
- Make sure your changes don’t break anything: ``./coverage.sh``
|
||
- If you want to do me favour, run your module through
|
||
``black -t py34`` before submitting
|
||
|
||
Pull requests
|
||
-------------
|
||
|
||
The project **gladly** accepts PRs for bugfixes, new functionality, new
|
||
modules, etc. When you feel comfortable with what you’ve developed,
|
||
please just open a PR, somebody will look at it eventually :) Thanks!
|
||
|
||
Coding guidelines
|
||
-----------------
|
||
|
||
I’m pretty open to whatever style you use, but if it’s all the same to
|
||
you (and yes, I know that the current codebase is only slowly adapting
|
||
to this): - Please favour single quotes for strings (except for
|
||
docstrings, which are always """) - For private methods/variables,
|
||
please use a leading ``__`` (e.g. ``__output`` rather than ``_output``)
|
||
|
||
Hello world
|
||
-----------
|
||
|
||
This example will show “hello world” in the status bar:
|
||
|
||
.. code:: python
|
||
|
||
"""Short description"""
|
||
|
||
import core.module
|
||
import core.widget
|
||
|
||
class Module(core.module.Module):
|
||
def __init__(self, config):
|
||
super().__init__(config, core.widget.Widget(self.full_text))
|
||
|
||
def full_text(self, widgets):
|
||
return 'hello world'
|
||
|
||
# vim: tabstop=8 expandtab shiftwidth=4 softtabstop=4
|
||
|
||
Of modules and widgets
|
||
----------------------
|
||
|
||
There are two important concepts for module writers: - A module is
|
||
something that offers a single set of coherent functionality - A module
|
||
has 1 to n “widgets”, which translates to individual blocks in the i3bar
|
||
|
||
Very often, this is a 1:1 relationship, and a single module has a single
|
||
widget. If that’s the case for you, you can stop reading now :)
|
||
|
||
Otherwise, you have a number of ways to handle widgets: - During the
|
||
``super().init__(...)`` inside the module’s constructor, you can specify
|
||
a **list** of widgets, and those will comprise the widgets (in ordered
|
||
fashion) - During runtime, you can set a new list of widgets by using
|
||
the ``self.widgets(<new list>)`` method of the module
|
||
|
||
Adding widgets at runtime
|
||
-------------------------
|
||
|
||
If you want to add widgets during runtime, please use the
|
||
``add_widget()`` method of the module:
|
||
|
||
::
|
||
|
||
def do_something(self):
|
||
self.add_widget(full_text="my sample text", name="<optional name>")
|
||
|
||
TODO: expand on this
|
||
|
||
Periodic updates
|
||
----------------
|
||
|
||
``bumblebee-status`` modules have two different ways to update their
|
||
data: 1. Each interval, the callback registered when the widget was
|
||
created is called. You can do arbitrarily complex things there 2. Each
|
||
interval, **before** the widget’s callback is invoked, a generic
|
||
``update(self, widgets)`` method is called on the **module**
|
||
|
||
Largely, where you want to put your update code is up to you. My
|
||
observations: - If you want to change the widgets a module has, you
|
||
**have** to stick with ``update()`` - For simple modules, doing the data
|
||
update in the widget callback is simplest (see ``kernel``, for example)
|
||
|
||
Advanced topics
|
||
---------------
|
||
|
||
Event handlers
|
||
~~~~~~~~~~~~~~
|
||
|
||
The ``core.input`` module can be used to execute callbacks during mouse
|
||
events:
|
||
|
||
.. code:: python
|
||
|
||
import core.module
|
||
import core.widget
|
||
import core.input
|
||
|
||
class Module(core.module.Module):
|
||
@core.decorators.every(minutes=60, seconds=20)
|
||
def __init__(self, config):
|
||
super().__init__(config=config, widgets=<widgets>)
|
||
|
||
core.input.register(widget, button=core.input.LEFT_MOUSE, cmd=<cmd>)
|
||
|
||
The command can be either a CLI tool that will be directly executed
|
||
(e.g. ``cmd='shutdown -h now'``) or a method that will be executed. The
|
||
method’s signature needs to be: ``def <name>(self, event)``, where
|
||
“event” is the event data provided by i3wm.
|
||
|
||
The full list of possible bindings: - LEFT_MOUSE - RIGHT_MOUSE -
|
||
MIDDLE_MOUSE - WHEEL_UP - WHEEL_UP
|
||
|
||
Setting a default update interval
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
To change the default update interval, you can use a simple decorator:
|
||
|
||
.. code:: python
|
||
|
||
import core.module
|
||
import core.widget
|
||
import core.decorators
|
||
|
||
class Module(core.module.Module):
|
||
@core.decorators.every(minutes=60, seconds=20)
|
||
def __init__(self, config):
|
||
super().__init__(config=config, widgets=<widgets>)
|
||
|
||
**NOTE**: This makes the update interval of the module independent of
|
||
what the user configures via ``-i <interval>``! It is still possible to
|
||
override the module’s interval using ``-p <module>.interval=<value>``,
|
||
however.
|
||
|
||
TODOs
|
||
-----
|
||
|
||
- default update interval
|
||
- scrolling
|
||
- theme.minwidth
|
||
- scrolling decorator
|
||
- theme.exclude
|
||
- per module update interval -> nice string format
|
||
- update via events
|