GKrellM Themes Reference

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

frame_top.png
The rendered height can be set with frame_top_height and a border specified with frame_top_border in gkrellmrc. Transparency is allowed.

frame_bottom.png
The rendered height can be set with frame_bottom_height and a border specified with frame_bottom_border in gkrellmrc. Transparency is allowed.

frame_left.png
The rendered width can be set with frame_left_width and a border specified with frame_left_border in gkrellmrc. Transparency is allowed.

frame_right.png
The rendered width can be set with frame_right_width and a border specified with frame_right_border in gkrellmrc. Transparency is allowed.

bg_chart.png
The background image for the chart area of a chart monitor. A border for this image can be set in the gkrellmrc. To provide custom backgrounds for specific chart monitors, theme subdirectories may have a custom version of this image.

bg_grid.png
This is a 1 or 2 pixel high image which is pasted onto a bg_chart background image to show grid lines. Use it to get nice etched grid lines. It should balance the requirement that it be visible yet not distract the eye from the data that is plotted on the chart. Monitor subdirectories may have a custom version of this image.

bg_separator
The user may optionally split Charts into data views. Data views on a chart will be separated by this image. It will be rendered to bg_separator_height (specified in the gkrellmrc), which should probably be 2 pixels high.

bg_panel.png
The background image for the panel area of a chart monitor. A border for this image can be set in the gkrellmrc. Monitor subdirectories may have a custom version of this image.

bg_meter.png
The background image for the meter areas of meter monitors. A border for this image can be set in the gkrellmrc. Meter monitor subdirectories may have a custom version of this image which for convenience may be named bg_panel.png.

Detail images
The default theme images will be used for any of these which do not exist in your theme directory.

button_panel_out.png
button_panel_in.png
These are images for a button type where the images for it are displayed only when the panel area where they exist has the mouse. When this button appears, it is an overlay on a label (or decal) to emphasize that the label has been assigned button status for launching a command. Since the button is an overlay, it ideally should be a 1 - 3 pixel highlighting border surrounding a transparent interior (see the default theme implementation), but it could be a semi-transparent special effect image depending on the theme. If these images do not exist in your theme then the button overlay will be constructed with a default gray color and may or may not look good with your theme. Set the border sizes for these images in the gkrellmrc with the button_panel_border option.

button_meter_out.png
button_meter_in.png
Same as for button_panel except for overlay buttons in a meter area. Set the border with the button_meter_border option in the gkrellmrc. If your bg_meter is similar to bg_panel, then these can be copies of the button_panel_in/out images.

krell_panel.png
A vertical stack of krell frames. See the Tips and Comments below. These are used in the bg_panel areas and are intended to be used as fast response indicators on chart monitors. The default depth is 4, although the middle two frames are identical. If you make a custom krell_panel, you must tell GKrellM the depth in the gkrellmrc file if it is different from the default. Chart monitor subdirectories may have a custom version of this image, which should be named krell.png

krell_meter.png
A vertical stack (default depth 1) of krells used in the bg_meter area of meter monitors. If you make a custom krell_meter, you must tell GKrellM the depth in the gkrellmrc file if it is different from the default. Meter monitor subdirectories may have a custom version of this image, which should be named krell.png

krell_slider.png
A vertical stack (default depth 7) of krells used in the bg_panel or bg_meter areas of chart or meter monitors. If you make a custom krell_slider, you must tell GKrellM the depth in the gkrellmrc file if it is different from the default.

decal_alarm.png
A vertical stack of images that are cycled through when an alarm is triggered. These images are usually placed behind a text decal to highlight the value that has triggered the alarm. If you don't have sensor voltage monitoring or the Battery monitor to play with, run "gkrellm -demo" and you will be able to set Battery alerts and see the decal_alarm and decal_warn in action. Set the number of frames this image has in the gkrellmrc:
decal_alarm_frames n

decal_warn.png
Same as decal_alarm.png, except it is triggered by a less serious warning event. Set the number of frames for this image in the gkrellmrc: decal_warn_frames n

decal_misc.png
A vertical stack of decals used for various monitors. I have tried to make these theme generic, but you could touch them up to better match your theme.

decal_button.png
A general purpose button image which monitors may scale to different sizes. There are two vertically stacked button image frames with the button out image on top of the button pressed image. This image is not used in GKrellM version 1.x.

Optional data plotting images

data_in.png
data_in_grid.png
data_out.png
data_out_grid.png
If these images exist they are used to plot data on the charts. You can have textured or 3D plotted data to go with your bg_chart. The data_in_grid and data_out_grid should be 1 or 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.

Optional spacer images
spacer_top.png
spacer_bottom.png
spacer_top_chart.png
spacer_bottom_chart.png
spacer_top_meter.png
spacer_bottom_meter.png
Spacer images form a visual separator between monitors. Spacers are rendered to a default height of 3 pixels unless set otherwise in the gkrellmrc. Borders for these images are set in the gkrellmrc with spacer_top_border and spacer_bottom_border lines. Spacer images can be set for all monitors, chart styled monitors only, meter styled only, Theme subdirectories may have a custom version of this image. For example, a meter monitor with two panels can be either of:
	    without spacers:              with spacers:
	---------------------         ---------------------    spacer_top
	|                   |         ---------------------
	|                   |         |                   |    bg_meter
	---------------------         ---------------------
	|                   |         |                   |    bg_meter
	|                   |         ---------------------
	---------------------         ---------------------    spacer_bottom
Optional cap images

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
Cap images are drawn on the left and right frames aligned to the top and bottom of each monitor. Left cap images are left adjusted in the left frame and right cap images are right adjusted in the right frame. They can be turned off for specific monitors. Meter monitors can be a single panel so it's probably difficult to design a theme with both top and bottom meter cap images. These images are not scaled.

Builtin monitor custom images
cpu/nice.png
cpu/nice_grid.png
Used to plot the cpu nice time data in a color different from either the data_in or data_out colors. If these images don't exist and the cpu_nice_color and cpu_nice_grid_color strings are not set in the gkrellmrc, cpu nice time will use the data_in color.
mail/krell_penguin.png
This is the multi frame penguin animation for new mail notification. However, it does not have to be a penguin - any alternative will do. Frame 0 is displayed when there is no new mail to announce and so should be left blank. When the penguin animation is enabled, new mail to announce triggers the display of frames 1 through depth-2 as an animation moving across the width of the mail monitor panel. Since frame depth-1 is not fully visible, it is not displayed and is left blank. The depth must be specified in the gkrellmrc: StyleMeter mail.krell_depth = d
mail/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. This image is applied by default to all themes. The number of frames is specified in the gkrellmrc file: decal_mail_frames n
mem/krell_buffers.png
An extra krell in the mem panel which shows kernel buffers usage. It should probably be de-emphasized with respect to the main panel krell. Offset and depth parameters for it can be set in the gkrellmrc (see "Notes on making a GKrellM theme" for expand-mode options):
	    set_integer mem_krell_buffers_yoff y
	    set_integer mem_krell_buffers_depth d
	    set_integer mem_krell_buffers_x_hot x
	    set_string  mem_krell_buffers_expand expand-mode
mem/krell_cache.png
An extra krell in the mem panel which shows kernel buffers usage. It should probably be de-emphasized with respect to the main panel krell. Offset and depth parameters for it can be set in the gkrellmrc (see "Notes on making a GKrellM theme" for expand-mode options):
	    set_integer mem_krell_cache_yoff y
	    set_integer mem_krell_cache_depth d
	    set_integer mem_krell_cache_x_hot x
	    set_string  mem_krell_cache_expand expand-mode
net/decal_net_leds.png
A vertical stack of 4 leds in the order:
			rx_off, rx_on, tx_off, tx_on
The net LEDs are stenciled onto the bg_panel backgrounds of Net chart monitors. They may have non rectangular shapes with transparency. The rx and tx LEDs may overlap in complex ways because they are individually stenciled onto the net bg_panels.
timer/bg_timer.png
This is a background for the timer part of the TimerButton meter monitor and is superimposed on top of its bg_meter. It can be used to highlight the timer and visually separate it from the button. A border can be set for it in the gkrellmrc:
		set_image_border timer_bg_timer l,r,t,b
sensors/bg_volt.png
A framing background for the voltage values of the voltage sensor monitor. Run "gkrellm -demo" using the default theme to see it if you don't have hardware sensor monitoring. You can also set a border for this image in the gkrellmrc:
		set_image_border sensors_bg_volt l,r,t,b
Probably the top and bottom border should be only 1 or 2.
timer/decal_timer_button.png
This is a vertical stack of button images for the button in the TimerButton monitor. There are 4 frames in the order:
		off, pressed, standby, on

Notes on making a GKrellM theme

A theme directory can exist anywhere for development purposes and can be specified on the command line:
       gkrellm -t theme_dir
Hit the F5 key to reload a theme as you make changes.
Detail images are drawn on bg_panel or bg_meter backgrounds as layers and each image may have transparency.
Krells have several style parameters which you can set in the gkrellmrc. But note: it is possible for a plugin coder to write code such that his krell will not honor these settings.
krell_yoff
Adjusts a krell's vertical offset into a panel or meter area.
krell_depth
To build a krell with depth, vertically stack krell images in a krell_panel or krell_meter image and specify the number of frames in a 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: One frame displayed at all positions.
             2: Display frame 0 at x = 0, frame 1 at all other positions.
         n > 2: Display frame 0 at x = 0, frame n-1 at x = full_scale, and
                remaining frames at positions proportional to x/full_scale.
krell_x_hot
This is an offset in pixels from the left edge of a krell image. Krell images are drawn so that the krell x_hot spot is drawn at the current krell position in a panel or meter area (except for bar-mode krells, see below).
krell_left_margin & krell_right_margin
The range of krell motion across a panel width may be constrained between a left and right margin where the margins are number of pixels from the left or right panel edge respectively. These style setings are new in GKrellM version 1.2.9.
krell_expand
The default is for a krell to be drawn at the same size as its original image. But, if a krell_expand value is set, the krell width will be rendered to match the width of the GKrellM window. The krell_expand values are:

left
The krell image area from the left edge to the x_hot spot is rendered to fit the GKrellM monitor width. Look at the GKrellMSS plugin's VU meter krells for examples of this krell type.
right
The krell image area from the x_hot spot to the right edge is rendered to fit the GKrellM monitor width. This may not be useful.
bar-mode
The total krell image width is rendered to fit the GKrellM monitor width. Additionally, the krell x_hot spot is ignored. Instead, the krell position is indicated by drawing only the portion of the rendered krell image from its left edge to the current krell position. The visual appearance is then a static "bar" across the panel width with only the left portion up to the current krell position visible. This is new in version 1.2.5.
left-scaled, right-scaled, bar-mode-scaled
Same as above except the rendering of the krell width is scaled to fit the width between the krell left and right margins. If both krell_left_margin and krell_right_margin are zero, these modes are equivalent to left, right, and bar-mode respectively. These are new in version 1.2.9
To sumarize the difference between a bar-mode and left expanded krell:
The bar-mode krell position is fixed on a panel and on