Themes

This page describes plans for including theme support into Freeciv.
== Theme definition ==
Theme is a portion of client data, which for following reasons should be separated from a tileset:
* It may be not only graphic-related.
* Theme can be changed independently from tileset.
* Theme is gui specific and some themes can not be shared between different guis.
Theme is recognized by its name.
== File system organization ==
Theme is stored in a directory called like the theme. The directory contains some data files.
Each gui defines its own format in the get_useable_themes_in_directory() function.
The Freeciv client searches for usable themes in following directories:
* ./themes
* data/themes
* ~/.freeciv/themes
* {prefix}/share/freeciv/themes
* ~/.themes
* /usr/share/themes
Last two directories are gui-gtk2 specific.
This lookup is done in the common client code in the init_themes() function at client startup.
== Loading a theme ==
You can load a theme with the load_theme(const char* theme_name) function.
It searches for a first theme with a matching name in above directories list. You should call init_themes() function before calling load_theme(). load_theme() calls gui specific function void gui_load_theme(const char *directory, const char *theme_name) which does the real work.
A list of useable themes is available through the get_themes_list() function.
== GTK 2 part ==
Gtk theme is a directory containing subdirectory gtk-2.0 with gtkrc file. The gtkrc file is a gtk resource file in the format recognized by gtk_rc_parse() function.
The gui_load_theme() function calls gtk_rc_set_default_files() with only one default file - the gtkrc file of the theme.
The gtk-2.0 gui defines following directories as gui-specific places where the client should look for themes:
* ~/.themes
* The return value of gtk_rc_get_theme_dir() which is /usr/share/themes on Unixes.
If you want to tell a theme that some widget should be drawed in a special way, you should use the 
gtk_widget_set_name() function
Gtk Resource Files API
== SDL part ==
The SDL client looks for its themes in the "gui-sdl" subdirectory within any of the Freeciv theme directories (see File system organization).
The themes are recognized by the "theme.themespec" file which contains the main theme description in a format very similar to the tilespec format (in fact, the theme code in the SDL client was derived directly from the tileset code).
At this time, there are two themes for the SDL client available: Human and Deluxe. As of version 2.1.0-beta3, the game is shipped with the Human theme. For older versions of the game, use the Deluxe theme. This theme is not distributed on freeciv.org, but can be fetched from:
Freeciv version	tar.bz2 for all platforms(untar to ~/.freeciv)	zip for win32(unzip to the directory where Freeciv is installed)
2.1.0-beta1 	deluxe_theme-2.1.0-beta1-2006-07-28.tar.bz2 	deluxe_theme-2.1.0-beta1-2006-07-28.zip
2.1.0-beta2 	deluxe2_theme-2.1.0-beta2-2006-08-11.tar.bz2 	deluxe2_theme-2.1.0-beta2-2006-08-11.zip
dev 	deluxe2_theme-dev-2006-08-21.tar.bz2 	deluxe2_theme-dev-2006-08-21.zip
These links are obsolete
TODO:
* find out who the exact authors of each graphic in the "deluxe" theme are to be sure that all graphics are really free.I already found the origins of most of them and some graphics I couldn't find anywhere else on the net so far have been replaced in the "deluxe2" packages. See also here. --cproc 14:53, 11 August 2006 (PDT)
* write a more detailed description regarding the theme format
== Ideas ==
* Each city style could have a list of preferred themes.
* User could change a theme when he wants, something that would be especially useful for theme developers. There is a patch in the RT which demonstrates this concept.
== Tilesets ==
A tileset can specify list of prefered themes using the following line in a tileset.tilespec file:
prefered_themes = "theme1", "theme2", "theme3"
Category:Projects