GKrellM Themes Reference

Changelog-themes

Intro

The GKrellM structure is a framed stack of monitors and there are two monitor types, Charts and Meters, which have background images applied to drawing areas. Charts have two drawing areas, the chart area and the panel area. Meters have one drawing area, the meter area. Most theme images and options are applied at this level and many can be specified to apply to a particular Chart or Meter monitor. 
      _______________________
      |_____________________|<- frame
      | |                 | |
       .                   .
      | |-----------------| |
      | |                 | |  Chart Monitor
      | |   chart area    | |
      | |                 | |
      | |-----------------| |
      | |   panel area    | |
      | |-----------------| |
       .                   .
       .                   .
      | |-----------------| |
      | |   meter area    | |  Meter Monitor
      | |-----------------| |
       .                   .
      |_|_________________|_|
      |_____________________|
A theme is a directory containing theme images. A theme directory may be any of several locations: 
	~/.gkrellm2/themes/THEME_NAME/
	/usr/local/share/gkrellm2/themes/THEME_NAME/
	/usr/share/gkrellm2/themes/THEME_NAME/
	/usr/share/themes/THEME_NAME/gkrellm2/
	~/.themes/THEME_NAME/gkrellm2/
The last two locations require gkrellm >= 2.1.16 and are compatible with gtk2 theme locations. They are convenient for installation when making a meta theme including gtk2, gkrellm2, and possibly other themes. The /usr/share/themes/ directory component may actually be something different depending on how gtk2 was installed.

If a "gkrellmrc" file exists in a theme directory, it is parsed for theme specific settings such as borders, margins, colors, and krell parameters. The theme directory also has images for the frame, background images for each of the drawing areas, and detail images (decals and krells) which are drawn on panel and meter areas.

Terminology

Chart monitor - A monitor type which has two background areas - a chart area with a bg_chart image as a background, and a panel area with a bg_panel image as a background. Labels, decals, and krells are drawn in panel areas.

Meter monitor - A monitor type which has a single background area type - a meter area with a bg_meter image as a background. Labels, decals, and krells are also drawn in meter areas. A meter monitor may have multiple meter areas vertically stacked.

Decals are pixmap graphics or text elements such as LEDs, button images, toggling labels, etc. usually placed in fixed locations in panel or meter areas. These may have transparency and may overlap.

Krells are pixmap graphics which are programatically moved horizontally across the face of a panel or meter area. They implement meter indicator movements, moving animations, and slider controls. Krells may have transparency and they usually move over decals.

Image Structure

All theme images are either base level images which are in the toplevel of the theme directory, or monitor specific theme images which are placed in subdirectories of the toplevel. All base level images have a default which will be used if it is not provided in a theme.

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

	F : frame_top.png
	f : frame_bottom.png
	  : frame_left.png
	  : frame_right.png
	c : bg_chart.png           a chart area background
	p : bg_panel.png           a panel area background
	m : bg_meter.png           a meter area background
	  : bg_grid.png            a chart area background grid line
	  : bg_separator.png       a chart area data view separator
This is a side section view showing how these images are used to build GKrellM. frame_left/right and bg_grid are not shown and not all monitors are shown. 

   |<--Meters->|<--------Charts----------|<--------Meters---------->|
 | | Cal | Clk | CPU Chart  |  PPP Chart |Timer|  Mem | Swap |  FS  | |
 | |     |     |        |   |        |   |     |      |      |      | |
 o-o\___/-\___/-\______/-----\______/-----\___/-\____/-\____/-\____/o-o
 | |     |     |        |   |        |   |     |      |      |      | |
  F   m     m      c      p     c      p    m      m      m      m   f
The last row shows where background images are applied to the monitors.

Theme Image Names

The background areas, krells, or some monitor detail images can have a monitor specific custom image substituted for the base level default image. For a custom image to take effect, it only has to exist in the monitor specific subdirectory.

Here is a list showing the image naming structure in a theme directory. Images may be .png as shown or .jpg or .xpm.

Base level images in the top level of the theme directory

frame_top.png
frame_bottom.png
frame_left.png
frame_right.png
--------------------
bg_chart.png
bg_grid.png
bg_separator.png
bg_panel.png
bg_meter.png
--------------------
button_panel_in.png
button_panel_out.png
button_meter_in.png
button_meter_out.png
--------------------
krell_panel.png
krell_meter.png
krell_slider.png
--------------------
decal_misc.png
decal_button.png
--------------------
   (optional images for plotting data)
data_in.png
data_in_grid.png
data_out.png
data_out_grid.png
--------------------
   (optional images separating monitors)
   (Spacer images in the top level dir is new in GKrellM 2.1.0 and 1.3.0)
spacer_top.png
spacer_bottom.png
spacer_top_chart.png
spacer_bottom_chart.png
spacer_top_meter.png
spacer_bottom_meter.png
--------------------
   (optional frame images aligned with the top and bottom of monitors)
   (These are new in GKrellM version 2.1.0 and 1.3.0)
cap_top_left_chart.png
cap_bottom_left_chart.png
cap_top_right_chart.png
cap_bottom_right_chart.png
cap_top_left_meter.png
cap_bottom_left_meter.png
cap_top_right_meter.png
cap_bottom_right_meter.png

Custom images in the theme subdirectories

Builtin Chart monitor theme subdirectories are:
        cpu, disk, inet, net, proc
Builtin Meter monitor theme subdirectories are:
        apm, cal, clock, fs, host, mail, mem, timer, uptime
The Battery monitor was originally named APM and the theme subdirectory for it remains "apm" to avoid breaking themes.

Plugins will each have their own theme subdirectory which can be determined from the plugin documentation.

All builtin or plugin Chart monitor theme subdirectories may have the custom images: 

	bg_chart.png
	bg_grid.png
	bg_panel.png
	krell.png
	spacer_top.png
	spacer_bottom.png
All builtin or plugin Meter monitor theme subdirectories may have the custom images (however, not all may use the krell.png): 
	bg_meter.png	(bg_panel.png is accepted for convenience)
	krell.png
	spacer_top.png
	spacer_bottom.png
In addition to the above custom images, each builtin or plugin may have additional images which are extension to the theme. And they may also accept custom Style, integer, string, or image border settings in the gkrellmrc. Plugins should document what these images and custom settings are and how they are used. The builtin theme gkrellmrc settings will be listed later in the gkrellmrc section, while the builtin image extensions are listed here: 
cpu:
	cpu/nice.png
	cpu/nice_grid.png

net:
	net/decal_net_leds.png

mail:
	mail/decal_mail.png
	mail/krell_penguin.png

mem:
	mem/krell_buffers.png
	mem/krell_cache.png

sensors:
	sensors/bg_volt.png

timer:
	timer/decal_timer_button.png
	timer/bg_timer.png

Theme Image Descriptions

Background images