Gtk+ Cube

Starting with version 3, GTK uses CSS (Cascading Style Sheets) for styling and although it's a subset of the CSS3 standard so not everything is supported, you can use it to greatly improve the look of your applications. CSS is used to style documents written in languages for web content creation such as HTML, XHTML, SVG, XUL, ect. The current version is CSS3 and is maintained by the W3C, (World Wide Web Consortium)

CSS is designed primarily to enable the separation of document content (written in HTML or a similar markup language) from document presentation, including elements such as the layout, colors, and fonts.
http://en.wikipedia.org/wiki/Cascading_Style_Sheets

Internal versus external CSS

There are two types of CSS, internal and external. With the internal type the CSS is defined in the code file, with external the CSS is in a separate file also called a style sheet. The style sheet version goes along with the idea of separating the content of the document from it's styling. You can use either. This first example will be internal.

The standard for CSS is to include one property per line for clarity and editing capability. So including CSS in your code can cause it to grow quickly especially if you have several things you want to style differently. One of the benefits of using a style sheet is that it keeps your code file as small as possible. Another benefit is that once you've created your content in the code file and compiled it, you don't need to recompile it after making changes in the style sheet. Just save the new version of the style sheet and run the program again. The code file will read any changes in the style sheet. This also lets other people make changes in the style sheet to create a custom look. They don't need to know C language or Python or whatever programming language you made your code file with only a little CSS. Of course if you don't want anyone to change the look of your program you should use internal CSS. However they can still change the theme on their computer (see below) which can affect how parts of your program will look.

Styling versus. Theming

The Linux operating system has many versions, called distributions or "distros" for short. Ubuntu; Debian, Mint. ect. These distros each have many revisions and codenames.
https://wiki.ubuntu.com/DevelopmentCodeNames
http://wiki.debian.org/DebianReleases#Release_statistics

Each can look quite different than the others. The Window Manager is the part of the operating system that has the finally say in what anything on the screen will look like. The Window Manager works by reading a piece of code and a CSS file. The CSS file contains information about the visually aspects such as colors, some shapes ect. The distros that I mentioned before each come with predefined "Themes". These can be changed by selecting a different one through a simple user setting.

Theming

When "Theming" you create your own CSS file and some code. The code instructs the Window Manger to read the CSS file and all the programs running on the computer will obey the rules in the CSS file. That is, they will use the colors and other visual properties that were written in the CSS file. Here your not creating any new programs. You're simply telling the existing programs how they should look.

Linux developers don't want you to write a program that differs in color from the theme that the user currently has selected for their system. The idea is to have a universal look to any program that runs on the system. This creates a familiar and user friendly interface for everyone. An exception would be a program that runs on a specialized computer called an embedded system which usually has a very small screen if it has does one at all. These are usually lower speed computers used for specific purposes sometimes in industrial settings. Recent advances in computers called SOC's (system on a chip) are changing things dramatically. Their being used for such applications as tablet computers, set-top boxes (Netflix on your TV) and energy monitoring (Plug-in electric cars). The prices of these systems are falling rapidly while their capabilities are continuing to increase. Two very popular boards are the Raspberry Pi and BeagleBone Black. Their small computers designed for Computer Science students and hobbyist programmers and can interface with various sensors through a variety of interfaces.
http://www.raspberrypi.org/
http://beagleboard.org/Products/BeagleBone

Theming won't be covered in this tutorial, maybe in the future. If you want to get more information about theming see:
http://worldofgnome.org/making-gtk3-themes-part-1-basics/
http://developer.gnome.org/gtk3/stable/GtkThemingEngine.html

Styling

Styling is when you use the new CSS capabilities in GTK3 to control some of the visual aspects of programs that YOU write. Any programs on the computer that you did not write won't be affected. Those other programs will obey the theme the Window Manger gives them. I said some of the visual aspects... because not all of the properties can be changed. Even some of the properties that you do change can be overridden by the Window Manger. (not many)

Colors

Gtk with CSS supports several ways to use colors, called color units. The units are: Basic color keywords, X11 extended, RGB, RGBA and hexadecimal. The simplest are the basic color keywords such as: red, blue, green ect. (*note) See: 4.1. Basic color keywords http://www.w3.org/TR/css3-color/#html4
*Note: For the following colors you must use either RGB, RGBA or hexadecimal:   aqua, fuchsia, lime, silver, olive, teal.

Gtk also supports all of the X11 extended color units (**See Note) No named color can contain spaces. Some X11 colors listed on Wikipedia and other sites contain spaces. They won't work. You need to remove any spaces or use one of the other color units listed below. Color names which have more then one word in them can have any combination of upper and lower case letters but can't contain spaces. For instance: Cadet Blue can be written as any of the following:

		CadetBlue
	cadetblue
	cadetBlue
	Cadetblue
	CADETBLUE
	CadETBLuE

See: 4.3. Extended color keywords http://www.w3.org/TR/css3-color/#svg-color

RGB

One of the most used color units is RGB, which stand for: red, green, and blue. The values can be either integers between 0 and 255 or percentages.
Examples:

		rgb (0, 0, 255);
	rgb (20%, 30%, 0%);

RGBA

You can also use RGBA. The "A" in RGBA means "Alpha" which is another way of saying transparency.

Hexidecimal

See: Hex triplet http://en.wikipedia.org/wiki/Web_colors

Getting the color values

You can use online "color pickers" as well as almost any image manipulation program to get these colors. I recommend Inkscape since it supports RGBA, it's free and works on Linux, Mac and Windows. For the full list of color units and more examples, See: The various ways to express colors in GTK+ CSS are:
http://developer.gnome.org/gtk3/stable/GtkCssProvider.html (same for all version of Gtk3)

Color Gradients

Gtk also allows you to create a color gradient. A color gradient is color that progress from one color to another. There are two types of color gradients: linear and radial. The syntax for linear gradient is:

		-gtk-gradient (linear,<br> 
	start_x start_y, end_x end_y,<br>
        color-stop (position, color),<br>
        ...)

start_x, start_y   Are either a floating point number between 0 and 1 or one of the special values 'left', 'right' or 'center'
end_x, end_y   Are either a floating point number between 0 and 1 or one of the special values 'top', 'bottom' or 'center'
position:   A floating point number between 0 and 1 and color is a color expression.
color-stop,   Can be repeated multiple times to add more than one color stop.
'from (color)' and 'to (color)' can be used as abbreviations for color stops with position 0 and 1, respectively.

The syntax for CSS3 linear gradients differs slightly between web browsers and color-stop for GTK+ follows the CSS model for the Safari web browser except, position is given as a decimal instead of percent: color-stop(0.50, blue) Means the gradient should gradually fade from the previous color to blue. It finally becomes the color blue at the point 50% of the width's container. If you defined this external css gradient (for Unico on Ubuntu, See the section: Compatibility Notes)

		GtkWindow {
	background-image: -gtk-gradient (linear,
                                 	center top, center bottom,
                                 	color-stop(0.5,green),
                                 	color-stop(0.5,blue),   
	}

You would get:
top 50% green, bottom 50% blue

Before you look at the GTK manual example's for gradients, the syntax: @name should be explained. This is used to create a unique name for a color. This is useful because you only need to define the color once then use it as many times as you want. That way you only need to change the definition of the color and everywhere you've used the unique name will reflect the change. For colors you use: @define-color, followed by your own unique name, then a value given in one of the supported color units. For instance, if you were changing the background color you might use the following as your unique name: bg_color1. Once you define it, then you use your unique name with the character @ in front of it. A linear gradient for external css, would be created with the following: (See compatibility note for Unico in Ubuntu)

		@define-color bg_color1 rgb (255, 0, 0);
	@define-color bg_color2 rgb (71, 71, 229);

	GtkWindow {
  	background-image: -gtk-gradient (linear,
  	left top,
  	right bottom,
  	from(@bg_color1),
  	to(@bg_color2));
	}

The quickest, simplest way to get linear gradient color values is to use on-line tools that are available. I've listed some in the references section at the end of this post, or just Google "CSS gradient creator" Copy and paste the Safari web browser version of the code it generates for you. Then just change background to background-image then -webkit-gradient to -gtk-gradient and the percent values to decimal. (See compatibility note for Unico in Ubuntu) For instance you should get something like this:

	background: -webkit-gradient(linear, left top, left bottom, color-stop(0%,#1e5799), color-stop(39%,#2989d8), color-stop(56%,#207cca), color-stop(100%,#7db9e8)); /* Chrome,Safari4+ *

		@define-color bg_color1 rgb (255, 0, 0);
	@define-color bg_color2 rgb (71, 71, 229);

	GtkWindow {
  	background-image: -gtk-gradient (linear,
        	                         left top,
                	                 right bottom,
                        	         from(@bg_color1),
                                	 to(@bg_color2));
	}

I won't go into radial gradients. To read about them and more linear gradient examples, See: Gradients http://developer.gnome.org/gtk3/stable/GtkCssProvider.html
(same for all version of Gtk3)

There are four other more complicated color units: mix, shade, lighter, darker

	 	mix(color1, color2, f) /* A linear combination of color1 and color2, f is a floating point number between 0 and 1. */
	shade(color, f)        /* A lighter or darker variant of color, f is a floating point number  */
	lighter(color)         /* A lighter variant of color */
	darker(color)          /* A darker variant of color*/
	

mix: "f" is the brightness that I described previously, only in CSS for Gtk, it's a floating point number between 0.0 and 1.0. A value of 0.5 would be 50%, 0.6 would be 60%.

shade: f is the brightness that I described previously, but here it's between 0.0 and 2.0. If you set a color using one of the basic color keywords, say blue, then on the next line use: shade(blue, 1.0) it will not change. But if you set: shade(blue, 0.0) then you'll get black. If you use: shade(blue, 2.0) you'll get white.

lighter: If you set the background color using: blue, then use: lighter(blue) it will result in a 30% reduction in the saturation property of the HSV color space. This is equivalent to selecting the Ubuntu appearance settings as rgb: 0,0,255 then changing the "S" property in the HSV settings from 100 to 70. This isn't additive, meaning you can't apply an additional lighter and get even lighter version of the color you started with.

darker: This works opposite of lighter and again, it can't be repeated for even darker versions of your starting color. I won't go into mix, but I will say, lighter, darker and shade can be useful when styling the different states of a button. For instance when you're cursor is over it.

Images:

You can also use images with CSS. GTK accepts the image types:   .gif   .jpeg   .png   .svg
In the following code just replace the line:   " background-color: shade(blue, 1.0);\n"
With the following:   " background-image: url(/files/theme/PATH);\n"
For example once you've created or downloaded your image, lets say I downloaded the GTK cube image at the top of this web page and saved it as GtkCube.svg to a folder called: "Pictures", I would use:   " background-image: url('/home/me/Pictures/GtkCube.svg');\n"

So you can resize the window to fit the image. By change the line:  gtk_window_set_default_size(GTK_WINDOW(window), 500, 300);
To the following:   gtk_window_set_default_size(GTK_WINDOW(window), 1024, 1024);

Compatibility Notes:

For Unico, the default GTK3 Theme Engine in Ubuntu 12.04 (Precise Pangolin) or Ubuntu 12.10 (Quantal Quetzal):
If your setting the background color or background image of a window, you can use either background or background-image. But when setting the background color of a button, which is in a upcoming tutorial, you must use background. For this reason it's best to be consistent and just use background when setting background colors and background images for all widgets. As of GTK 3.4 you must use units in the CSS (unless the value is zero) or you'll receive the warning:
Not using units is deprecated. Assuming 'px'.

Also there must not be any space between the value and the units or you'll receive the same warning. You can use any of the standard CSS units of measurement: http://www.w3schools.com/cssref/css_units.asp
As an example, the code in the following line:   " padding: 2;\n"
Would become:   " padding: 2px;\n"

Style Properities: Important

There are two types of style properties. Standard CSS properities and widget specific properties.

Standard CSS properties

Standard CSS properties are those that follow (generally) the CSS3 standard and are listed in official GTK documentation. Make sure your viewing the manual for the version of gtk YOUR using because there are differences between versions. For instance, gtk version 3.1 introduces several new CSS properities including: "text-shadow"; "box-shadow" and individual border colors. Just change "3.4" in the link below to your version. See: Supported properties: http://developer.gnome.org/gtk3/3.4/GtkCssProvider.html

Widget specific properties

The widget specific properties are those that can be unique to each widget. (GtkButton, GtkComboBox, ect.) Some widgets share these properties. Unless it's a standard CSS property, In order to use the style properties listed in the GTK documentation for a particular widget they must be preceded by: -NameOfWidget- For example to use the GtkCheckButton style property, "indicator-size" you would use: -GtkCheckButton-indicator-size: value Where value is an integer greater then or equal to zero as mentioned in the documentation.

  1. Go to the main page of the documentation for the widget your trying to style.
  2. Click on the style property you want.
  3. In your code use the style property proceeded by -NameOfWidget- as described above.

(See the references section at the bottom of this tutorial for links to the official documentation.)

Object Hierarchy

There's a object hierarchy to everything in GTK. When your at the top of documentation page for the widget your trying to style click on "Object Hierarchy" Anything that falls below GtkWidget in the object hierarchy can be styled with GtkWidget style properties assuming it has that feature.
http://developer.gnome.org/gtk3/stable/GtkWidget.html#GtkWidget.style-properties

Say you want to change the cursor color in a GtkTextView, but if you look at the style properties for GtkTextView there's no such property listed. However if you look at the style properties for GtkWidget there is a cursor-color property listed and since GtkWidget is above GtkTextVew in the hierarchy, you can use that to change the cursor color in GtkTextView with: -GtkWidget-cursor-color. If a widget doesn't have a cursor, like a GtkButton, you're obviously not going to be able to style it. But the property focus-line-width is common to several widgets. It's a indicator line on widgets like buttons which shows there's an area that can be clicked. So if your styling a GtkButton you can change this property by using:   -GtkWidget-focus-line-width. You don't use: -GtkButton-focus-line-width because focus-line-width is listed in the style properties of GtkWidget not GtkButton. There's an example of the focus-line-width in the sample code below and a example of cursor-color in the GtkTextView tutorial I've posted.

CODE NOTES

Here's an example of changing the background color of a window using internal CSS in Gtk3. I'm using Gtk+-3.2.3 on Ubuntu 11.04 (Natty Narwhal). I've defined the background color using 5 different color units just for illustration. Each statement overrides the previous one, so the end result is the same, a blue background is produced. You could delete any 4 of the 5 and still get a blue background. After the code are a few good references.

/* Compile with: 
*       gcc -Wall -o csswindow `pkg-config --cflags --libs gtk+-3.0` csswindow.c                           
*/
#include gtk/gtk.h

int main (int argc, char *argv[])
{
  GtkWidget *window;
/*--- CSS -----------------*/
  GtkCssProvider *provider;
  GdkDisplay *display;
  GdkScreen *screen;
/*-------------------------*/
  gtk_init (&argc, &argv);

  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);

  gtk_window_set_default_size (GTK_WINDOW(window),
                               500, 300);

  g_signal_connect (GTK_WIDGET(window),
                    "destroy",
                    G_CALLBACK (gtk_main_quit),
                    NULL);

/*------  CSS  ---------------------------------------------------------------------------------------------------------------*/
  provider = gtk_css_provider_new ();
  display = gdk_display_get_default ();
  screen = gdk_display_get_default_screen (display);

  gtk_style_context_add_provider_for_screen (screen,
                                 GTK_STYLE_PROVIDER (provider),
                                 GTK_STYLE_PROVIDER_PRIORITY_APPLICATION);

  gtk_css_provider_load_from_data (GTK_CSS_PROVIDER(provider),
                                   " GtkWindow {\n"
                                   "   -GtkWidget-focus-line-width: 0;\n"
                                   "   -GtkWindow-resize-grip-height: 0;\n"    /* not guaranteed, can be overridden by window manger */
                                   "   -GtkWindow-resize-grip-width: 0;\n"     /* not guaranteed, can be overridden by window manger */                       
                                   "   background-color: blue;\n"              /* named color units */
                                   "   background-color: rgb (0, 0, 255);\n"   /* rgb color units, overrides the previous "background-color" assignment */
                                   "   background-color: rgba (0,0,255,1);\n"  /* rgba color units, overrides the previous "background-color" assignment */
                                   "   background-color: #0000FF;\n"           /* hexadecimal color units, overrides the previous "background-color" assignment */
                                   "   background-color: shade(blue, 1.0);\n"  /* overrides previous color assignment */   
                                   "}\n", -1, NULL);
  g_object_unref (provider);
/*----------------------------------------------------------------------------------------------------------------------------*/

  gtk_widget_show_all (window);
  gtk_main ();
return (0);
}

References

Official (gtk3) "Getting Started with GTK+"
http://developer.gnome.org/gtk3/stable/gtk-getting-started.html
Official GTK+3.x "Tutorials, code samples, and platform demos in C"
http://developer.gnome.org/gnome-devel-demos/3.5/c.html.en

Official GTK3 reference manuals online:
http://gtk+-3.0 http://developer.gnome.org/gtk3/3.0/
http://gtk+-3.1 http://developer.gnome.org/gtk3/3.1/   (introduces several new css properities, "text-shadow", "box-shadow" individual border colors, ect.)
http://gtk+-3.2 http://developer.gnome.org/gtk3/3.2/
...I think you can see the pattern. Just change 3.2 to your version
http://developer.gnome.org/gtk3/   (gtk3.x series manual downloads for those that prefer offline use.)
"inofficial" and yet experimental doxygen-generated source code documentation. (Downloadable and online)
http://fossies.org/dox/all.html#G   (search the page for "gtk" to find several versions. This is a Nice resource.)

CSS specific
http://gnomejournal.org/article/107/styling-gtk-with-css
http://blogs.gnome.org/carlosg/2010/08/23/css-like-styling-for-gtk/
http://kalmbach.wordpress.com/2011/03/12/gtk-3-0-client-side-theme/
http://developer.gnome.org/gtk3/3.0/migrating.html
http://www.w3.org/TR/css3-color/
http://maettig.com/?page=PHP/CSS_Color_Converter (Very nice online color conversion tool)
For quick design of color gradients:
http://www.colorzilla.com/gradient-editor/
http://gradients.glrzad.com/