QtPixmap GTK Engine
-------------------
The QtPixmap engine is a hacked/modifed version of GTK's standard pixmap engines. A GTK engine
is the program code used to actually style a GTK widget. A GTK theme is a gtkrc file that uses
one or more GTK engines and tells the engine which widgets to style, in what colour, size, etc.
The QtPixmap engine differs from the pixmap engine in that it will read your ~/.qt/qtrc file
(which is controlled via KControl or qtconfig) to ascertain the colours and font to be used.
QtPixmap adds the following extra keywords to a pixmap gtkrc file.
Per "image" settings:
---------------------
These are all specified within an ' image { ... } ' block. e.g.
style "Wibble"
{
engine "qtpixmap"
{
image
{
file = "selected_button.png"
file_color = "button"
...
}
}
}
* file_color
Colour to be applied to the image file. This is specified is specified as a string, and can
have 1 of the following values:
background
button
selected
window
foreground
text_selected
mid
i.e. specifying ' file_color = "button" ' (without single quotes!) would cause the image
(specified with ' file = "image.png" ') to be coloured with KDE's "button" colour setting.
* gap_file_color
* gap_start_file_color
* gap_end_file_color
* overlay_file_color
These are the same as "file_color", but affect the corresponding image.
e.g. "gap_file_color" is for "gap_file", etc.
* file_color_mod
If after specifying "file_color" the colour is to dark or lighten, you can use this to darken
or lighten the colour used. This is in -255 -> +255 range. e.g. ' file_color_mod = 25 ' would
add the number 25 to each of the RGB values - these are in 8-bit quantities (hence the
-255 -> +255 range). Because of a weird quirk of GTK, to specify a negative number, you have
to supply this as a string (e.g. ' file_color_mod = "-25" ')
* gap_file_color_mod
* gap_start_file_color_mod
* gap_end_file_color_mod
* overlay_file_color_mod
Ditto, but for the relevant file.
* overlay_min_size
If you have specified an "overlay_file", then this would specify the minimum size of the
widget that this can be used on - specified as "w, h". Overlay files are used to place one
pixmap on-top of another - such as the series of lines that appear in the middle of Keramik's
scrollbars, Geramik achieves this via an overlay_file. If the widget is less than the width
or height specified here, then the overlay file is not applied. (If you notice Keramik will
only draw the lines on the scrollbar if it is large enough).
large enough).
* stretch
Not really a new keyword, however I've modifed it to accept "height" and "width" as well
as TRUE and FALSE. This indicates if the engine should stretch the pixmap to fill the area
covered by the widget. Geramik uses the "height" for progress bars - i.e. the dark and
light striped bar. If I just used "stretch = TRUE", then the engine would resize the pixmap
each time the progress changed - so the stripes would get bigger. What I've done is supply
a really long pixmap (1024 pixels?) so that it doesn't need to be stretched width wise, and
the stripes stay the same size.
Notes:
1. images to be used with QtPixmap should all be grey scale. QtPixmap will then re-colour
these using the settings above. Using coloured images will give strange results.
2. The GTK1 engine does not support alpha channel. This is why in Geramik there are some
different pixmaps between the GTK1 and GTK2 versions. (For example Geramik's GTK2
pushbuttons contain an alpha channel that allows for better blending)
Per "style" settings
--------------------
GTK2 allows you to specify the x and y thickness of the outside box of a widget - i.e the space
around the text of a menu-entry. This is done via specifying "xthickness" or "ythickness".
To achieve the same for GTK1 I added the "xthickness" and "ythickness" parameters.
In GTK2 you would use these as follows:
style "Wibble"
{
xthickness = 1
ythickness = 1
engine "qtpixmap"
{
image
{
...
}
}
}
To achieve the same in GTK1 you would do:
style "Wibble"
{
engine "qtpixmap"
{
xthickness = 1
ythickness = 1
image
{
...
}
}
}
Note that the GTK1 version has these within the ' engine "qtpixmap" { ... } ' block - as it is
the QtPixmap engine reading these, and not the standard GTK style, as per GTK2.
Global settings
---------------
These settings are not specified per-image, but globally. To use them, just add an entry as
follows to the start of your gtkrc file:
style "Settings" {
engine "ENGINE" {
button_x_offset = 0
button_y_offset = 1
tb_button_x_offset = 1
tb_button_y_offset = 1
button_focus_mod = { 4, 2, "-7", "-4" }
combo_focus_mod = { 5, 5, "-35", "-8" }
radio_check_focus_mod = { 16, 0, "-16", 0 }
no_radio_check_highlight = TRUE
}
}
(Note this "style" is never assigned to any widgets)
* button_x_offset
* button_y_offset
These 2 are GTK1 *only*. These supply the number of pixels the text on a button should move
when it is depressed - to give the feeling that the button has actually been pressed. The
above example is from Geramik, and would mean "move text 1 pixel down" - as this is what
happens when Keramik's push-buttons are pressed.
* tb_button_x_offset
* tb_button_y_offset
As above, but for toolbar buttons. Again, GTK1 *only*.
* button_focus_mod
* combo_focus_mod
* radio_check_focus_mod (GTK1 only, not needed for GTK2)
These three modify how the focus rectangle (the dotted lines) are shown around the
corresponding widget type. The values are "x, y, w, h".
GTK normally draws the focus rectangle around a radio buttons pixmap and its text - but KDE
does not. Using:
radio_check_focus_mod = { 16, 0, "-16", 0 }
Would cause the focus rectangle to be shifted right by 16 pixels, and be 16 pixels smaller (i.e.
w -16). (Note the quotes around negative numbers).
* no_radio_check_highlight
Most GTK styles "brighten" the radio and check buttons (and their text) when the mouse hovers
over them. However most KDE styles do not. Setting this to TRUE will prevent the standard
"highlighting"
Default: TRUE
* use_selected_for_menu_item
Indicates if the SELECTED text colour should be used for a selected menu item. Most menu items
have black text, and when the item is selected this usually turns white.
Default: TRUE
* use_selected_for_menu
Similar to the above, but applies to the menu headings. On most styles these are usually the
same colour - hence the default of FALSE.
Default: FALSE
Examples
--------
The best example to use would be Geramik's gtkrc files - after all this engine was primarily
created for Geramik. You will also notice that Geramik's gtk and gtk-2.0 gtkrc files differ
from each other.
The easiest way to use this engine in your theme is to probably base your theme on Geramik's
gtkrc files and pixmaps. The replace these one-by-one. For example the pixmaps used to draw
can probably be used as is.
Anyway, here some examples for Geramik's gtkrc files...
.....................................
The following example creates a style named "ToolbarButton". The style names are arbitrary.
The ' engine "qtpixmap" ' informs GTK that the section enclosed in the following {} applies
to the "qtpixmap" engine.
style "ToolbarButton" {
engine "qtpixmap" {
xthickness = 3 # xthickness/ythickness effectively give the button
ythickness = 3 # a 3 pixel border. Use these if your buttons appear too thin.
# The following section defines for what widget, and widget state, a pixmap
# should be used.
image
{
function = BOX # Indicates that when GTK wants to draw a "box" it
# can use this pixmap
state = PRELIGHT # => mouse over
shadow = IN # This would be when the button is pressed
file = "tbar_btn_hl.png" # The pixmap to be used
file_color = "button" # Tells QtPixmap to recolour "tbar_btn_hl.png"
# Using Qt/KDE's "button" colour
file_color_mod = 40 # I found the above looked too dark, so this
# value is used to lighten it a bit
border = { 2, 2, 2, 2 } # Tells the engine not to stretch the border
# specified here, only the inside.
}
image
{
function = BOX
state = PRELIGHT
shadow = OUT # This time the button is not pressed => mouse over
file = "tbar_btn_hl.png"
file_color = "button"
file_color_mod = 40
border = { 2, 2, 2, 2 }
}
image
{
function = BOX
state = ACTIVE # Button is pressed
shadow = IN
file = "tbar_btn_d.png"
file_color = "button"
file_color_mod = 25
border = { 2, 2, 2, 2 }
}
}
}
widget_class "*Toolbar*GtkButton" style "ToolbarButton"
widget_class "*ToolBox*Table*Button*" style "ToolbarButton"
The "widget_class" lines above now tell GTK that for any "GtkButton" that is a child, or
grand-child, etc, of a "Toolbar", that it should use the "ToolbarButton" style. Also for
any "Button" ("GtkButton", "GtkRadioButton", etc) that is a child, etc, of a "Table", that is
in a "ToolBox", use this style.
This is how Geramik manages to use different pixmaps for its pushbuttons, toolbar buttons, and
list-view headers. -> I specify each manually. Most GTK pixmap themes do not, hence the weird
looking list view headers.
.....................................
Geramik's scrollbars are composed as follows:
style "Default" {
engine "qtpixmap" {
# Scrollbars...
image {
function = BOX
detail = "slider"
state = PRELIGHT
file = "sbar_h_hl.png"
file_color = "selected"
border = { 6, 6, 6, 6 }
orientation = HORIZONTAL
overlay_file = "sbar_h_thm_hl.png"
overlay_file_color = "selected"
overlay_stretch = FALSE
overlay_min_size = { 36, 0 }
file_color_mod = 70
overlay_file_color_mod = 70
}
...
This style "Default" is applied to the base Gtk style via ' class "GtkWidget" style "Default" '
The line ' detail = "slider" ' indicates that the image {} section is for a "slider". (Gtk
will call a draw_box() function within the Gtk engine, and pass the string "slider" (for a
slider))
The above also demonstrates how the overlay file is used to create the scrollbar "thumb" - but
only if the scrollbar is at least 36 pixels.
.....................................
In the gtkrc files you can assign styles with either
class "<GtkClass>" = "<style>" to assign to a particular Gtk class
or
widget_class "<Gtk heirarchy>" to assign to a particular heirarchy. i.e. to a pushbutton
that is on a menu, etc.
.....................................
Please note the guides to the Gtk stuff above is only what I have been able to gather from
looking at others' gtkrc files. Geramik is the first Gtk theme I ever created, so somethings
are probably sub-optimal. However, it seems to work for me.
