                    Themes For GKrellM
                    ===================

=========================================================================
Theme changes in 0.7.4
------------------------------
* Added frame_side_border to gkrellmrc.  Should be more theme changes
  coming in 0.7.5

Theme changes in 0.7.1 - 0.7.3
------------------------------
* None

Theme changes in 0.7.0
----------------------
* New gkrellmrc author line so theme authors can be credited in the Themes
  configuration tab.  Just add a line to your gkrellmrc like:
    author = "yourname  email address"

* Added optional images data_in.xxx, data_in_etch.xxx, data_out.xxx,
  and data_out_etch.xxx.  If these images exist in the theme directory
  they will be used to plot data.  Otherwise use the colors specified in
  gkrellmrc.  Textured or 3D plotted data to go with your bg_chart.xxx
  is now possible (but is not noticeable with sparse data).

Theme changes in 0.6.8
----------------------
* I should have made a notice of this for release 0.6.7, but
  Maher Awamy has put up a GKrellM theme site at www.muhri.net.
  Check it out, there are some nice themes showing up.
* String values in gkrellmrc can have quotes around them.  So, font names
  can have spaces.
* New options in gkrellmrc: chart_width_ref, allow_scaling.
* Monitor label midpoint positions can now be specified as a percent
  of chart_width.

The above allows label positions to be offset to the left (right) of
center to make room to put both LED's to the right (left) of the label.
And the LED's size and position can be scaled as chart sizes are changed.

Theme changes in 0.6.5
----------------------
* Added a large font for the clock/calendar digits.  It uses time_color.

Theme changes in 0.6.1
----------------------
* I have warned that chart_labels.xxx is subject to change.  It has been
  done.  It no longer exists (likewise with meter_labels and digits).
  I draw with X fonts so you can specify fonts and label colors now.
* Two new optional images: frame_left.xxx and frame_right.xxx
* The gkrellmrc file is no longer overloaded to handle user preferences
  and theme settings.  Now user prefs are done in a gui popup and the
  gkrellmrc file is only for theme stuff.  For this reason, the
  ~/.gkrellm/gkrellmrc file is no longer read.  A gkrellmrc file is read
  only from theme directories specified in gkrellm_theme.cfg or on the
  command line.
* Some new settings in the gkrellmrc template.

=========================================================================
The Basics of Themes
------------------------
Excluding detail and optional images (see below), here is the basic set of
images required for a theme change in GKrellM (.png used as an example).

	f : frame_horizontal.png	(split in half and put on top and bottom)
	s : bg_spacer.png
	c : bg_chart.png
	b : bg_bordered.png
	  : frame_side.png
	  : chart_grid.png

This is a side section view of GKrellM showing how these images are used
to build the display.  frame_side and chart_grid are not shown.

         |<-------Charts--------------->|<--Meters--->|
         | CPU Chart |     PPP Chart    | Mem    Swap | uptm
  top|   | chart | p | chart  | p |  p  |  p   |   p  |   p  | bottom
     |   |       |   |        |   | t/b |      |      |      |
    oo---\______/-----\______/-----------\____/-\____/-\____/oo

   | |  |        |   |        |   |     |      |      |      | |
    f s     c      s     c      s    s      b      b      b   f

In the above diagram, not all monitors are shown.
A chart monitor has a chart where the data is plotted and a panel where
the label, LED's, and krells go.  A meter monitor has only a panel where
its label and krell go.  There are three background images associated
with these areas: bg_chart for the chart area, bg_panel for the chart
panel areas, and bg_meter for the meter panel areas.  Both bg_panel and
bg_meter are derived from general image clases bg_spacer and
bg_bordered respectively.  The above diagram shows the general image
classes being applied to the backgrounds.  The more specific images
bg_panel and bg_meter are optional and discussed below.
t/b is an extra panel in the ppp monitor containing its timer and button.


====================================================================
More Info on Image Naming
-------------------------
Almost all of the background areas can now have a custom qualifed
image substituted for the base level default image.  For a custom
image to take effect, it only has to exist in the theme directory.
For example, the cpu monitor can have a chart or panel background
different from the other monitors.  The memory meter can look different
from the swap meter.   You could disable labels and draw a custom
graphic on the backgrounds to identify monitor type.

Here is a table showing the image class structure.  Append .png,
.jpg, or .xpm to get the filename GKrellM looks for.

Base level       |      level 1     |  level 2
-------------------------------------------------------------------------
bg_chart         | bg_chart_cpu
                 | bg_chart_disk
                 | bg_chart_inet
                 | bg_chart_net
                 | bg_chart_proc
--------------------------------------------------------------------------
bg_spacer        | bg_panel         | bg_panel_cpu
                 |                  | bg_panel_disk
                 |                  | bg_panel_inet
                 |                  | bg_panel_net
                 |                  | bg_panel_proc
--------------------------------------------------------------------------
bg_bordered      | bg_meter         | bg_meter_apm
                 |                  | bg_meter_fs
                 |                  | bg_meter_mem
                 |                  | bg_meter_swap
--------------------------------------------------------------------------
bg_timer (optional)
--------------------------------------------------------------------------
chart_grid       | chart_grid_cpu
                 | chart_grid_disk
                 | chart_grid_inet
                 | chart_grid_net
                 | chart_grid_proc
--------------------------------------------------------------------------
krell_panel      | krell_panel_cpu
                 | krell_panel_disk
                 | krell_panel_inet
                 | krell_panel_net
                 | krell_panel_proc
--------------------------------------------------------------------------
krell_meter      | krell_meter_apm
                 | krell_meter_fs
                 | krell_meter_mem
                 | krell_meter_swap
krell_meter_mail | krell_meter_mail
--------------------------------------------------------------------------
frame_side       | frame_left
                 | frame_right
--------------------------------------------------------------------------
frame_horizontal | frame_top
                 | frame_bottom
--------------------------------------------------------------------------
net_leds
ppp_button

   (optional images for plotting data)
data_in
data_in_etch
data_out
data_out_etch
--------------------------------------------------------------------------

For example, Memory, Swap, Uptime, Clock/Cal, fs and apm start off with the
same background bg_bordered. You can create a bg_meter for Memory and
Swap without affecting Uptime or Clock/Cal, which always stay in bg_bordered.
The default theme uses a custom bg_meter_fs to break up the meter panels
into visually distinctive groups.

The bg_timer is special.  If it exists, it is used as a border around
the PPP timer only.  If it does not exists, then bordering in the t/b
panel is controlled by a gkrellmrc config option ppp_border_mode.
Bordering can be none (bg_spacer is used) or the timer alone can
be put in bg_bordered, or both the timer and button can go in bg_bordered.

I intend for any monitor ever added to GKrellM to have a background
parented to one of above base level images.  Something may be drawn
on top of that, but at least themes won't just break.  


=======================================================================
Tips & Comments for anyone making a GKrellM theme
-------------------------------------------------

0) First some general theory of operation stuff. 
   * Borders can be used to put padding around labels and timer digits.
     In the default theme, a border makes room above labels for the krells.
   * Panels are where the Net LED's, all krells, and labels live.
     Images are drawn as layers with transparency.  Top layer is krell,
     middle is LED, bottom is the background with the label drawn
     on it.  Mask bits for the LED on / LED off images need not be the same.
   * Krells have depth.  To build one, vertically stack krell images in
     a krell_panel or krell_meter image.   Put a chart.krell_depth or
     meter.krell_depth line in the gkrellmrc.  The frame displayed will
     be a function of the depth and horizontal x position of the krell:
       Depth 1: Obvious
             2: Display frame 0 at x = 0, frame 1 at all other positions.
           > 2: Display frame 0 at x = 0, frame 2 at x = full_scale, and
                remaining frames at positions proportional to x/full_scale.

1) I fear it will be difficult to make good looking krells because the
   small panel areas get crowded with their label, and krell movement is
   jerky.  I recommend you build a theme with the basic background
   images and then just go with the default krells if they look OK.
	
2) As you modify a bg_chart, bg_panel, krell_panel, etc, you can easily
   compare your progress by naming a reference version bg_chart.xxx and
   a working version bg_chart_disk.xxx, for example.  Now you just
   run through the cycle:
		Modify and save bg_chart_disk.xxx
		gkrellm --theme .
   And on a single gkrellm run you can directly compare the two versions.

4) When you first begin a new theme, it is not necessary to create new
   versions of all your images before you check your progress.  Just make
   a working directory and start making images.  Run after each image
		gkrellm --theme .
   and all images present will be pasted in.  Immediate feedback.

5) I don't actually expect that anyone will use all the image levels,
   and I think something like the default krells would be fine for
   most themes (although you might touch them up with a different color).
   The real intent is to be able to make minor adjustments for differing
   requirements for the different monitors, not to be able to make
   a wild psycho skin.
   The default theme uses only bg_panel and bg_timer beyond the basic
   set of background images.  Bg_panel so that the krells can have
   a simple background scale to move across, and bg_timer because
   I have a gradient and bg_bordered did not look good when rendered
   to less than full chart width.

==========================================================================
Theme Details
-------------

A theme directory can be specified on the command line
	gkrellm -theme theme_dir
or in the file ~/.gkrellm/gkrellm_theme.cfg which contains the theme
directory pathname in a single line.  If a gkrellmrc file exists in the
theme directory, it is parsed for theme specific settings.
Theme directories can exist anywhere for development purposes, but
install final versions in subdirectories under ~/.gkrellm so that the
Themes configuration tab will pick it up.
A documented template gkrellmrc file is in the source tar file or in
the document directory a .deb or .rpm.

--------------------------------------------------------------------------
--- Base set of background images---------------------------------------

frame_horizontal.png
	This image is split in half with the top half rendered onto the top
	of the GKrellM window and the bottom half rendered onto the bottom of the
	GKrellM window, unless the optional frame_top and frame_bottom images
	exist.  This image should not have been implemented.  It is better to make
	the frame_top and frame_bottom images.

frame_side.png
	Used for both the left and right frames unless the optional
	frame_left and frame_right images exist.

bg_chart.png
	This is the background image for the charts.  It will be rendered to
	the size of the charts specified in the gkrellmrc file.  Name qualified
	images allowed.

chart_grid.png
	This is a 2 pixel high image which is pasted onto the chart background
	image to show grid lines.  Use it to get nice etched grid lines.

bg_spacer.png
	The default non-bordered background.  It will be cloned into bg_panel
	if bg_panel does not exist in the theme directory.  It will be used
	for the ppp t/b (timer/button) panel in various combinations with
	bg_timer (if it exists) and bg_bordered (if asked for, see gkrellmrc).

bg_bordered.png
	The default bordered background.  It will be cloned into bg_meter if
	bg_meter does not exist in the theme directory.  It is used for the
	uptime monitor background, and for the ppp aux panel.  The aux
	panel is shown when the ppp interface is down.

--------------------------------------------------------------------------
--- Optional set of background images ------------------------------------

frame_left.png
	Optional.  If this image does not exists, then frame_side will be
	cloned and used for the left frame.

frame_right.png
	Optional.  If this image does not exists, then frame_side will be
	cloned and used for the right frame.

frame_top.png
	Optional.  If this image does not exists, then frame_horizontal is
	used as decribed above.

frame_bottom.png
	Optional.  If this image does not exists, then frame_horizontal is
	used as decribed above.

bg_panel.png
	Optional. If this image does not exist, then bg_spacer will be cloned
	and used for Chart panel backgrounds.  Name qualification is possible.
	The default theme uses a bg_panel to get some background scale
	markings for the krell to move over.  If you do not want something
	like this, then there is no reason to make bg_panel, just let
	bg_spacer be used.

bg_meter.png
	Optional. If this image does not exist, then bg_bordered will be cloned
	and used for meter panel backgrounds.  Name qualification is possible.
	The default theme uses bg_bordered except for the file system monitor
	panels where bg_meter_fs is used.

bg_timer.png
	Optional.  Make one of these if you have gradients and you want a
	border around the timer alone (not including the ppp button).
	In this case, the general purpose bg_bordered when rendered may
	not blend well.  To get a theme going, I recomend you set up
	gkrellmrc to use bg_bordered around the timer and/or button and then
	worry about this image only if you need to.

--------------------------------------------------------------------------
--- Detail images -------------------------------------------------------

net_leds.png
	A vertical stack of 4 leds in the order:
			rx_off, rx_on, tx_off, tx_on
	LEDs are stenciled onto their panel background.  So you may have
	non rectangular shapes with transparency.

decals.png
	A vertical stack of decals used for various monitors.  This is currently
	undergoing change, so you should probably not roll your own for now.

ppp_button.png
	The  2 images for the PPP on/off button vertically stacked with the
	off image on top. Note that the actual button size will be the image
	size plus a typical Gtk theme 3 pixel surrounding border.  The height
	is cf this image should be 4 (2 pixels each for on/off images).  About
	all you can do with this is make a horizontal colored LED like image.

krell_panel.png
	A vertical stack of krell frames.  See the above
	Tips and Comments.  These are used in the panel areas and are
	intended to be used as fast response indicators.  The default
	krell images are fairly clean and should go well with just about
	any theme.  If you decide to try your own, you must tell GKrellM
	the depth you chose in gkrellmrc if different from the default.
	The default depth is 4, although the middle two frames are identical.

krell_meter.png
	A vertical stack (default is depth 1) of krells used for
	the memory and swap meters.  Again, the default should be usable
	for most themes.

krell_meter_mail.png
	This is the multi frame penguin animation for new mail notification.
	The depth must be specified in the gkrellmrc file.  Frame 0 should
	be left blank and the last frame is not used because it would not be
	fully displayed.  So a new mail count increase triggers the
	display of frames 1 through depth-2 as an animation moving across
	the width of the mailcheck panel.

decal_mail.png
	This is the stationary envelope animation in the mailcheck panel.
	If envelope animation is enabled, frame 1 is shown by default and
	a new mail count increase triggers frames 1 through depth-1 to be
	shown as an animation.
	If envelope animation is disabled, frame 1 is shown by default and
	frame 0 is shown when a new mail count increase is detected.
	The number of frames in this image must be specified in the gkrellmrc file.

--------------------------------------------------------------------------
--- Optional data plotting  images ---------------------------------------
data_in.png
data_in_etch.png
data_out.png
data_out_etch.png
	If these images exist they are used to plot data in the charts.  You
	can have textured or 3D plotted data to go with your bg_chart.png.
	The data_in_etch and data_out_etch should be 2 pixel high images and
	are drawn where the plotted data crosses a chart grid line.
	If any of these do not exist data plotting falls back to using the in_color
	and out_color specified in gkrellmrc.  Any shading effect you
	put into a data image should probably track shading on your bg_chart.
	Shading effects are not very apparent on low data density charts,
	so get a big compile or net download going to see the effects.

==========================================================================

BUGS
====
* Style setting has a bug.  Set a sub style, then later style
	settings for the parent class have no effect on the sub class.
	Example:

	style chart.cpu.panel_border = x,x,x,x
	style chart.label = none

	The label still appears for the cpu chart.  So, do more general
	style settings first.

