The format of the GTK file is illustrated in the example below. This is the testgtkrc file from the GTK distribution, but I've added a few comments and things. You may wish to include this explanation in your application to allow the user to fine tune his application.
There are several directives to change the attributes of a widget.
fg - Sets the foreground color of a widget.
bg - Sets the background color of a widget.
bg_pixmap - Sets the background of a widget to a tiled pixmap.
font - Sets the font to be used with the given widget.
In addition to this, there are several states a widget can be in, and you can set different colors, pixmaps and fonts for each state. These states are:
NORMAL - The normal state of a widget, without the mouse over top of it, and not being pressed, etc.
PRELIGHT - When the mouse is over top of the widget, colors defined using this state will be in effect.
ACTIVE - When the widget is pressed or clicked it will be active, and the attributes assigned by this tag will be in effect.
INSENSITIVE - When a widget is set insensitive, and cannot be activated, it will take these attributes.
SELECTED - When an object is selected, it takes these attributes.
When using the "fg" and "bg" keywords to set the colors of widgets, the format is:
fg[<STATE>] = { Red, Green, Blue }Where STATE is one of the above states (PRELIGHT, ACTIVE, etc), and the Red, Green and Blue are values in the range of 0 - 1.0, { 1.0, 1.0, 1.0 } being white. They must be in float form, or they will register as 0, so a straight "1" will not work, it must be "1.0". A straight "0" is fine because it doesn't matter if it's not recognized. Unrecognized values are set to 0.
bg_pixmap is very similar to the above, except the colors are replaced by a filename.
pixmap_path is a list of paths separated by ":"'s. These paths will be searched for any pixmap you specify.
The font directive is simply:
font = "<font name>"
The only hard part is figuring out the font string. Using xfontsel or a similar utility should help.
The "widget_class" sets the style of a class of widgets. These classes are listed in the widget overview on the class hierarchy.
The "widget" directive sets a specifically named set of widgets to a given style, overriding any style set for the given widget class. These widgets are registered inside the application using the gtk_widget_set_name() call. This allows you to specify the attributes of a widget on a per widget basis, rather than setting the attributes of an entire widget class. I urge you to document any of these special widgets so users may customize them.
When the keyword parent is used as an attribute, the widget will take on the attributes of its parent in the application.
When defining a style, you may assign the attributes of a previously defined style to this new one.
style "main_button" = "button"
{
font = "-adobe-helvetica-medium-r-normal--*-100-*-*-*-*-*-*"
bg[PRELIGHT] = { 0.75, 0, 0 }
}This example takes the "button" style, and creates a new "main_button" style simply by changing the font and prelight background color of the "button" style.
Of course, many of these attributes don't apply to all widgets. It's a simple matter of common sense really. Anything that could apply, should.