 _________________
< Welcome to Helm >
 -----------------
    \
     \
                                   .::!!!!!!!:.
  .!!!!!:.                        .:!!!!!!!!!!!!
  ~~~~!!!!!!.                 .:!!!!!!!!!UWWW$$$
      :$$NWX!!:           .:!!!!!!XUWW$$$$$$$$$P
      $$$$$##WX!:      .<!!!!UW$$$$"  $$$$$$$$#
      $$$$$  $$$UX   :!!UW$$$$$$$$$   4$$$$$*
      ^$$$B  $$$$\     $$$$$$$$$$$$   d$$R"
        "*$bd$$$$      '*$$$$$$$$$$$o+#"
             """"          """""""


Introduction
------------

Helm is a system monitor released under GNU GPLv3.


Organization
------------

Basically Helm is a GTK+ window with root transparency. This window contain a
gtk.VBox. Each cell of this box contain a "widget" or a "view". A widget
contains a set of views. A view is the drawing of a "model". A model is the
information that we want to monitor.

There are various views. We can use any view to display any model. So we can
have an histogram for the cpu activity and a ring for the memory usage. Or vice
versa.


Configuration
-------------

If you want to customize helm, you must create the file
~/.config/helm/config.py. You can just copy the config.py provided with sources
and modify it. The default config import all the models/views/widgets and the
"run" method.

The sole purpose of this file is to call the "run" method with the width of the
GTK+ window and the list of widgets/views.

To instantiate a widget, you must give him a view class to use to display the
models.

To instantiate a view, you must give him a model instance.

The order in which you will give the widgets/views will establish the order in
which helm will display them.


Use another theme
-----------------


You must use the argument "theme" of the run() method.

Example:

  from helm.theme import GruikOPiou

  run(widgets=…, theme=GruikOPiou())


Create your own theme
---------------------

You must create a class which inherit from helm.thme.Theme and create the init
method. Then you can redifine all the colors used by the theme. If you do not
specify all the colors, helm will take the values of the default theme.

Here is a simple example:

class SimpleExample(Theme):
    def init(self):
        self.text.fg_color = BLACK
        self.text.bg_color = WHITE
        self.drawing.fg_color = Color('42aa4d')
        self.drawing.bg_color = RED
        self.drawing2.fg_color = YELLOW

self.text is the foreground and background color used to render text.
self.drawing is the foreground and background color used to draw.
self.drawing2 is the secondary foreground and background color used to draw. At
the moment there is only helm.views.histogram.Histogram which uses it.

As you can see, I did not touch to self.drawing2.bg_color. So helm will use
the default color (as I write these words, the default background color for
drawing2 is GREY56).

The Color class and all the colors can be found in helm/color.py.


Here is a less simple example:

class LessSimpleExample(Theme):
    def init(self):
        self.text.fg_color = BLACK
        self.text.bg_color = WHITE
        self.Bar.text.fg_color = BLUE
        self.Histogram.bg_color = WHITE
        self.Histogram.drawing.fg_color = CYAN

As you can see, we can define the text color for a very specific View. When
helm will draw the Bar widgets, it will use BLUE (self.Bar.text.fg_color) as
the text foreground color and WHITE (self.text.bg_color) as the text background
color. All other views will use BLACK (self.text.fg_color) as the text
foreground color.

So you can really control every color that will be used in helm. You only have
to blame yourself if your current theme sux. :D
(or you can use helm.theme.GruikOPiou ;)


Place and size the window
-------------------------

There are two ways to place the window and you can combine them.

The first is with the gravity. If you want to have the window in the top left
corner of your screen, you must use gravity NORTHWEST. If you want it in the
center right, you must use EAST. Etc. There are nine gravities: CENTER, NORTH,
EAST, SOUTH, WEST, NORTHEAST, SOUTHEAST, NORTHWEST and SOUTHWEST. You can find
them in helm.primitives. The default gravity is NORTHEAST.

The second way is to define a shift on both axis. The default shift is (0, 0).

Here an example:
  run(widgets=…, gravity=SOUTHWEST, dx=10, dy=-5)

As you can see, the window will be in the bottom left, upped by 5 pixels and
shifted to the right by 10 pixels.


If you do not want to bother yourself with the gravity thing, you just have to
set the gravity to NORTHWEST and set the exact position with dx and dy.


Please note that helm takes the window manager working area into account
(i.e. the window will not show up on a toolbar, like the taskbar).


About the window size, you can only choose the width. Indeed, it chooses itself
the height based on the widgets/views it should display.

Here is an example:
  run(widgets=…, width=70)

The default value is 60.


Create your own models/views/widgets
------------------------------------

This is currently out of the scope of this documentation. So I can just give
you an advice: read the source code of helm. ;)

Another advice: you can write your models/views/widgets directly in your
config.py or in any other file in ~/.config/helm/ and import it into your
config.py. You do not have to modify helm to do this. :)


Models, Views & Widgets
-----------------------

* Models
 - CPU
  Monitors the CPU activity.
 - FS
  Monitors the usage of a mounted filesystem.
 - Mem
  Monitors the RAM usage.
 - Network
  Monitors the network activity.
 - Swap
  Monitors the SWAP usage.
* Views
 - Bar
  Display an horizontal line and the name and the current value of the model.
 - Histogram
  Display a time histogram and the name of the model.
 - Ring
  Display an arc and the name of the model.
* Widgets
 - CPUs
  Discovers your cores.
 - FSs
  Discovers your mounted filesystems.
 - MemSwap
  Monitors your swap (if you have any) and your memory.
 - Networks
  Discovers your network interfaces.


Bugs
----

* TraceBack if we move the window off screen.
* We can minimize helm with gnome button to minimize all windows.


Contact
-------

Website: http://helm.last-exile.org/
Jabber room: last-exile@muc.last-exile.org
