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
      | |-----------------| |
       .                   .
      |_|_________________|_|
      |_____________________|
For GKrellM version 1.x, a theme is a directory in one of the locations: ~/.gkrellm/themes, /usr/local/share/gkrellm/themes or /usr/share/gkrellm/themes. For GKrellM version 2.x, the directories are ~/.gkrellm2/themes, /usr/local/share/gkrellm2/themes or /usr/share/gkrellm2/themes. 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
	mem/bg_swap.png
	mem/krell_swap.png

sensors:
	sensors/bg_volt.png

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

Theme Image Descriptions

Background images

Detail images

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

Optional data plotting images

Optional spacer images

Optional cap images

Builtin monitor custom images

Notes on making a GKrellM theme

  1. 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.
  2. Detail images are drawn on bg_panel or bg_meter backgrounds as layers and each image may have transparency.
  3. 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 renderering 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 only a fractional part of its width is drawn. The draw is from the krell left margin to a right position between the left and right margins that corresponds to the current krell value. The left expanded krell position is moved so its x_hot spot is placed on a panel at a position corresponding to its current krell value. The entire krell width is drawn but will be clipped at the krell left and right margins.
  4. Run "gkrellm -demo" to see some less frequently used features you may not have available or enabled, such as cpu temps or the battery monitor.

Theme Alternatives

If there is a line in your gkrellmrc: 
    theme_alternatives = N
then you can have 1 to N different gkrellmrc and image alternatives that can be selected in the Themes tab. For each alternative N, you can have an optional gkrellmrc_N whose options will override any set in the base level gkrellmrc. If any image_N.png exists, it will be used in place of the base image.png. This can be used to give some flexibility to your theme. You could have more than one frame style or different font colors and sizes. For example if you have 
    theme_alternatives = 2
Then you would have 3 gkrellmrc files: 
	gkrellmrc        (always applied)
	gkrellmrc_1      (applied after gkrellmrc for theme alternative 1)
	gkrellmrc_2      (applied after gkrellmrc for theme alternative 2)
And you can have alternative images selectively applied depending on the alternative selected. If you had these images: 
	bg_meter.png
	krell.png
	krell_1.png
	fs/krell.png
	fs/bg_meter_2.png
then, these images would be used: 
Default Alternative 0:
	Base images: bg_meter krell    fs monitor images: fs/krell bg_meter
Alternative 1:
	Base images: bg_meter krell_1  fs monitor images: fs/krell bg_meter
Alternative 2:
	Base images: bg_meter krell    fs monitor images: fs/krell fs/bg_meter_2

The gkrellmrc file

Adjustments to label positions, margins, label colors/fonts, image borders, krell parameters, frame rendering, etc are made in the gkrellmrc file. Setting these values may have a variable effect on different monitors because the programmer may use the values to differing degrees. For example, margins may affect a label or some text decal but not affect other text decals because the programmer explicitely centers the decal.

The possible gkrellmrc lines are listed here.

The author line credits the theme maker. This will appear in the Themes configuration window. 

	author = "yourname  email address"
Theme alternatives are possible, see above. 
    theme_alternatives = N
If allow_scaling is true, then net LED position and size is scaled according to the chart_width/chart_width_ref ratio. chart_width_ref is the width you use for designing images and placing LEDs. 
	chart_width_ref  = w
	allow_scaling    = {true | false}

Frames

Frames can be rendered to heights and widths different from the drawn image sizes. 0 means use the drawn image width or height. 
	frame_top_height  = h
	frame_bottom_height  = h
	frame_left_width  = w
	frame_right_width  = w
Regions of the bg_chart, bg_panel, or bg_meter images may be overlapped onto the left and right frames. A simple use would be to overlap some bg_chart pixels so a chart can have a surrounding bevel outside of the active chart drawing area. This would be used in conjunction with giving the chart a top and bottom margin (with StyleChart *.margins) since a top and bottom chart margin is converted to a spacer that is also outside the active drawing area. The panel overlap values are used for bg_panel, bg_meter, space_top, and spacer_bottom images. These are new in GKrellM version 2.1.0 and 1.3.0. 
	frame_left_chart_overlap = n
	frame_right_chart_overlap = n
	frame_left_panel_overlap = n
	frame_right_panel_overlap = n
Spacers can also overlap the left and right frames. The overlap values are applied to all spacers, but overlapping can be turned off for specific monitors. These are new in GKrellM version 2.1.0 and 1.3.0. 
	frame_left_spacer_overlap = l
	frame_right_spacer_overlap = r
	spacer_overlap_off monitor-name
Cap images drawn in the left and right frames can be turned off for specific monitors. This is new in GKrellM version 2.1.0 and 1.3.0. 
	cap_images_off monitor-name

Borders

Borders for images are specified with comma separated numbers in the order:
      left border, right border, top border, bottom border

Borders for the main GKrellM window frame images. 

	frame_top_border = l,r,t,b
	frame_bottom_border = l,r,t,b
	frame_left_border = l,r,t,b
	frame_right_border = l,r,t,b
Borders for the spacer images. Only the left and right values are used. These are new in GKrellM version 2.1.0 and 1.3.0. 
	spacer_top_border = l,r,x,x
	spacer_bottom_border = l,r,x,x
Borders for the frame overlap areas. Only the top and bottom values are used. These are new in GKrellM version 2.1.0 and 1.3.0. 
	frame_left_chart_border = x,x,t,b
	frame_right_chart_border = x,x,t,b
	frame_left_panel_border = x,x,t,b
	frame_right_panel_border = x,x,t,b

Chart data colors

The data colors plotted on the charts are plotted in two different ways. If the images data_in.xxx, data_in_grid.xxx, data_out.xxx, and data_out_grid.xxx exist in the theme dir, they are used to plot data. If they do not exist, then the colors set here are used. Grid colors are drawn where the plotted data crosses a grid line. This allows grid lines to "show through" on high density charts. Colors are hex triplets ( #rrggbb ) or rgb.txt color names. Put quotes around two word rgb_color_names. 
	chart_in_color       = { #rrggbb | rgb_color_name }
	chart_in_color_grid  = { #rrggbb | rgb_color_name }
	chart_out_color      = { #rrggbb | rgb_color_name }
	chart_out_color_grid = { #rrggbb | rgb_color_name }

Chart view and grid

The height of the bg_separator image that separates chart data views. 
	bg_separator_height = 2
Some tweaking on drawing the background grid lines. 0 is normal and 1 inhibits grid line drawing at the top and bottom of charts. This is useful for bg_chart pixmaps that have 3D shading at the top and bottom and is a cosmetic effect. 
	bg_grid_mode = {0,1}

Net monitor LEDS

Negative x values here mean justify |x| pixels from right frame. Positive x values mean justify x pixels from left frame. Where to put the LEDs of each net interface monitor in its panel: 
	rx_led_x = x
	rx_led_y = y
	tx_led_x = -x
	tx_led_y = y

Animated mail decal

Number of frames in the stationary animated mail decal. Delay is number of update ticks between each frame. Set these if you replace the default mail decal envelope animation. 
	decal_mail_frames = 18
	decal_mail_delay = 1

Alert decals

Number of frames in the alarm and warn decal animation. Set these if you have custom decal_alarm.png or decal_warn.png images. 
	decal_alarm_frames = 10
	decal_warn_frames = 10

Slider krell

There is a krell image used as a slider control. Set its depth and x_hot if you replace the default. You can have a bar mode krell slider if you set krell_slider_expand to "bar-mode" (for this depth should be 1). There is one slider krell for all meter areas and panel areas, so positioning style settings can be applied only if a monitor has programmed the ability and this would be documented elsewhere. 
	krell_slider_depth = d
	krell_slider_x_hot = x
	krell_slider_expand = {left | right | bar-mode}  # New in 1.2.5

Panel buttons

Borders for the panel and meter buttons. 
	button_panel_border = l,r,t,b
	button_meter_border = l,r,t,b

Fonts

Use the large/normal/small font names in style settings below to change the default font assigned to any text. 
	large_font  = "-adobe-courier-medium-r-normal-*-*-120-*-*-m-*-iso8859-*"
	normal_font = "-adobe-courier-medium-r-normal-*-*-100-*-*-m-*-iso8859-*"
	small_font  = "-adobe-helvetica-medium-r-normal-*-*-80-*-*-p-*-iso8859-*"

Spacer height

If you use any top or bottom spacer images for monitors you can set something other than the default 3 pixel height. The height of the spacers may be set for all monitors, or independently for chart and meter monitor types, or specifically for individual monitors. "mon" is a chart or meter monitor style name as listed below for styles (eg, clock, fs, gkrellmms, etc). 
	spacer_top_height = h               # set for all monitors
	spacer_bottom_height = h

	spacer_top_height_chart = h         # set for chart type monitors
	spacer_bottom_height_chart = h

	spacer_top_height_meter = h         # set for meter type monitors
	spacer_bottom_height_meter = h

	spacer_top_height mon = h           # set only for monitor "mon"
	spacer_bottom_height mon = h

Extension hooks

These are ways to get options set for image or feature extensions which plugins will use. Builtins may also use these hooks to set parameters.

If a monitor uses a background image in addition to the standard bg_panel or bg_chart and its code allows for the image to be themed, a hook to set the border for that image may have been provided. It will be necessary to check plugin documentation to find the names, but for example, say a plugin "frump" uses an additional background image "bg_special.png" and for setting its border has added an image border hook "frump_bg_special". Then if you have made a theme image frump/bg_special.png for this plugin, you can set the image border with: 

	set_image_border  frump_bg_special = l,r,t,b
Plugins also have a way to request integer or string initialization values from the gkrellmrc. Again, check for plugin Theme file documentation. There could be options like: 
	set_integer frump_some_integer = n
	set_string  frump_some_color_string = "deep sky blue"
New in version 1.2.9, monitors may also define custom styles by adding a custom style name field to the StyleMeter or StylePanel lines. These are probably most useful when a monitor has additional krells. If these exist they should be documented in a plugin's Themes or README file. For example, if the frump plugin has a standard default krell and one extension krell which the plugin writer has named "gas-gauge", then the gkrellmrc can first set values for the standard krell: 
    StyleMeter  frump.krell_depth = 5
    StyleMeter  frump.krell_yoff = 2
    StyleMeter  frump.krell_expand = bar-mode-scaled
The extension gas-gauge krell will use plugin defaults if you do not set any of its style values. But when you set its first style value, it will be initialized to the currently set standard krell values. So you only need to specify values that are different from the standard krell, eg: 
    StyleMeter  frump.gas-gauge.krell_yoff = 10
    StyleMeter  frump.gas-gauge.krell_expand = none
*Note: if you theme a plugin, it is a good idea to include all of its themable parameters in your gkrellmrc in case the plugin's default values change and break your theme. Do not rely on the default values.

Builtin monitor extension hooks

CPU monitor nice data color: 
	set_string cpu_nice_color color_string
	set_string cpu_nice_grid_color color_string
Net timer monitor border for the optional bg_timer.png image. If bg_timer.png exists, it will be placed inside the top margin and bottom margin and at the left margin of the timer panel. The timer display will be placed inside of the borders. 
	set_image_border timer_bg_timer 1,1,2,2
Memory monitor krell_buffers optional image: 
	set_integer mem_krell_buffers_yoff 0
	set_integer mem_krell_buffers_depth 1
	set_integer mem_krell_buffers_x_hot -1
	set_string  mem_krell_buffers_expand none   # New in 1.2.5
Memory monitor krell_cache optional image: 
	set_integer mem_krell_cache_yoff 0
	set_integer mem_krell_cache_depth 1
	set_integer mem_krell_cache_x_hot -1
	set_string  mem_krell_cache_expand none     # New in 1.2.5

Style settings for the monitors

Some options can be set to apply globally to areas of all similar monitors, or can be set to individually apply only to an area of a specific monitor. This is done with Style lines which can have a global '*' scope name or a specific monitor name. Since these theme specifications begin at the monitor drawing area level, there are Style lines for each area. There are StyleChart and StylePanel lines for the chart and panel areas in the Chart monitors, and a StyleMeter line for the meter areas in the Meter monitors.

The builtin Chart monitors are: cpu, proc, disk, inet, net.
To apply a setting to a particular monitor, replace the '*' with the monitor name. Plugin Chart monitor style names may be available which can also be used in place of the '*'.

The builtin Meter monitors are: apm, cal, clock, fs, host, mail, mem, swap, timer, sensors, uptime.
Where for backward compatibility, "apm" is used for the Battery monitor. To apply a setting to a particular monitor, replace the '*' with the monitor name. Plugin Meter monitor style names may be available which can also be used in place of the '*'.

Notes about Style settings for chart, panel, and meter areas:

Notes about Style settings for panel or meter areas only:

Style settings applicable to the chart areas of Chart monitors

	StyleChart	*.border = l,r,t,b
	StyleChart	*.margins = x,x,t,b
	StyleChart	*.textcolor = #rrggbb #rrggbb {shadow | none}
	StyleChart	*.alt_textcolor = #rrggbb #rrggbb {shadow | none}
	StyleChart	*.font = {large_font | normal_font | small_font}
	StyleChart	*.transparency = { 1 | 2 }

Style settings applicable to the panel areas of Chart monitors

	StylePanel	*.border = l,r,t,b
	StylePanel	*.label_position = { 0-100 | center | none }
	StylePanel	*.margins = l,r,t,b
	StylePanel	*.left_margin = m
	StylePanel	*.right_margin = m
	StylePanel	*.top_margin = m
	StylePanel	*.bottom_margin = m
	StylePanel	*.textcolor = #rrggbb #rrggbb {shadow | none}
	StylePanel	*.alt_textcolor = #rrggbb #rrggbb {shadow | none}
	StylePanel	*.font = {large_font | normal_font | small_font}
	StylePanel	*.alt_font = {large_font | normal_font | small_font}
	StylePanel	*.krell_depth  = d
	StylePanel	*.krell_x_hot  = x
	StylePanel	*.krell_yoff  = y
	StylePanel	*.krell_expand  = none
	StylePanel	*.krell_left_margin  = 0
	StylePanel	*.krell_right_margin  = 0
	StylePanel	*.transparency = { 1 | 2 }

Style settings applicable to the meter areas of Meter monitors

	StyleMeter	*.border = l,r,t,b
	StyleMeter	*.label_position = { 0-100 | center | none }
	StyleMeter	*.margins = l,r,t,b
	StyleMeter	*.left_margin = m
	StyleMeter	*.right_margin = m
	StyleMeter	*.top_margin = m
	StyleMeter	*.bottom_margin = m
	StyleMeter	*.textcolor = #rrggbb #rrggbb {shadow | none}
	StyleMeter	*.alt_textcolor = #rrggbb #rrggbb {shadow | none}
	StyleMeter	*.font = {large_font | normal_font | small_font}
	StyleMeter	*.alt_font = {large_font | normal_font | small_font}
	StyleMeter	*.krell_depth  = d
	StyleMeter	*.krell_x_hot  = x
	StyleMeter	*.krell_yoff  = y
	StyleMeter	*.krell_expand  = none
	StyleMeter	*.krell_left_margin  = 0
	StyleMeter	*.krell_right_margin  = 0
	StyleMeter	*.transparency = { 1 | 2 }