icon-runner Files

IconRunner Usage
****************

Copyright (C) 2010 Oleg Gryb

Purpose
=======

This Ruby application will display status icons for different objects like network 
interfaces, daemons, memory, etc. The base class is universal enough
and can be used for various purposes by writing a custom function that monitors 
states of an object (see IconRunner Data Model).

Ready to use executables
========================

The utilities built by setup.rb installer allow running the status icons 
from a command line, e.g. to see memory, process and network interface 
statuses. To see memory utilization, process and network interface statuses you can
run something like this:

   ir_mem_proc_net_stat.rb nessusd:apache2:mysqld \ 
   /usr/share/pixmaps/nessusd.xpm:/usr/share/pixmaps/Apache.xpm:/usr/share/pixmaps/mysql.xpm ppp0 \
   /usr/share/icons/gnome/32x32/devices/nm-device-wireless.png &


More examples and installation instructions are available in INSTALL file.

IconRunner Data Model
====================

Each object in IconRunner is considered as a set of states. A state can be anything as soon
as you implemented a function that can identify the state by returning "true" when an object is in
this state. Examples of state: process is running (or not running), network interface is up 
(or down) or memory utilization is 50%. For all of the examples above the functions that identify 
the states are provided in StatusIcons class and could be used as templates for other similar
functions.

Each state can have one or more icons associated with it. These icons are visual 
representation of the state. If more than one icon is assigned to a state, IconRunner
will rotate them and that can be used for animation effects (see ir_net_stat_anim.rb 
for details).

You initialize the IconRunner class with states_array, which is an array of
state arrays. It means that a single instance of IconRunner can handle multiple 
objects. Thus relationship model for IconRunner class looks as follows:

               Contains
IconRunner     -------> states_array.
states_array   -------> states for multiple objects.
state          -------> set of icons.
icon           -------> content, type, tooltip. 

The following icon types are supported:

   FILE     icon is stored in a file, content is a path.
   NAME     icon is a name that Linux is aware of (e.g. it's a file in /usr/share/pixmaps dir).
   PIXBUF   icon is a buffer of pixels, content is a buffer.
   REGEXP   multiple icons stored in files represented by a regular expression stored in 'content'.
   STOCK    icon is a stock object (check Gtk::Image for details), content is a stock id.
   EMPTY    an empty invisible icon, content is ignored.