Fichiers par défaut

Une application peut demander à GTK+ d'analyser un fichier RC spécifique en appelant  gtk_rc_parse(). En plus de cela, certains fichiers seront lus à la fin de gtk_init(). En dehors de toutes modifications, les fichiers recherchés seront  <SYSCONFDIR>/gtk-2.0/gtkrc et .gtkrc-2.0 dans le répertoire "home" des utilisateurs. (<SYSCONFDIR> par défaut pour /usr/local/etc. Cela peut être modifié avec les options --prefix ou --sysconfdir pendant la configuration de GTK+.) Notez que les noms de fichiers contiennent aussi le numéro de  version  2.0, tous les 2.x versions de GTK+ ressemblent à ces fichiers.

Nom de chemin d'accès et modèles

Un fichier ressource définit un nombre de styles et de touches de raccourci et les lie à des widgets particuliers. Ce lien est réalisé par les déclarations du widget,de la widget_class, et de  class. Comme exemple d'un tel rapport 

widget "mafenetre.*.GtkEntry" style "ma-classe-entree"

attache le style "ma-classe-entree" à tous les widgets pour lequel le chemin de widget associe le modèle "mafenetre.*.GtkEntry".C'est-à-dire, tous les widgets  GtkEntry qui font partie d'un GtkWindow  nommé "mafenetre".

Depuis  GTK+ 2.10 les chemins widget_class peuvent aussi contenir des sous-chaînes  <nomdeclasse>, qui associent la classe avec un nom donné et toute classe dérivée. Par exemple,

widget_class "*<GtkMenuItem>.GtkLabel" style "my-style"

L'association avec les classes est un peu différente. Le modèle associe tous les noms de classe dans la hiérarchie des classes de widgets (non pas le dispositif de hiérarchie) en séquence, ainsi le modèle :

class "GtkButton" style "my-style"

De plus, une priorité peut être spécifiée pour chaque modèle, et les styles pourront surclasser d'autres styles d'abord par priorité, puis par le type de modèle et puis par ordre des spécifications (later overrides earlier). Les priorités qui peuvent être spécifiées sont ( plus haut à  plus bas):

rc est le défaut pour les styles lus dans un fichier RC,  theme est le défaut pour les styles lus dans un fichier RC de thèmes, application doit être utilisé pour des styles qu'une application a défini, et gtk est utilisé pour les styles que  GTK+ a créé en interne.

Optimisation de Style RC Associé.

Chaque fois qu'un widget est  crée et ajouté à un dispositif de hiérarchie d'un GtkWindow ("ancré " pour être exact), une liste de styles RC associés  en dehors de tous les styles RC  read in so far is composed. Pour cela, tout  style RC est associé à des chemins de classe de widgets, au nom de chemin des widgets et à la hiérarchie d'héritage des widgets. Cela a pour conséquence un ralentissement significatif qui peut être causé par l'utilisation de beaucoup de styles RC et par l'utilisation de modèles de style RC  qui sont lents ou compliqués à associer à un widget donné. La liste qui suit fournit un certain nombre de conseils (par ordre d'efficacité)  pour réduire la performance overhead associée avec le style RC lié.

Déclarations de haut niveau

Un fichier RC est un fichier texte qui est composé de séquences de déclarations. Les caractères '#' délimitent les commentaires et la portion de ligne après un '#' est ignorée pendant l'analyse d'un fichier RC.

Les déclaration de haut niveau possibles sont :

Styles

Un style RC est spécifié par une déclaration de   style  dans un fichier RC, et ensuite il est relié aux widgets avec une déclaration de widget, de widget_class, ou de class. Tous les styles appliqués à un widget particulier sont  composité de telle façon  que les déclarations de widget dépassant les déclarations de classe de widget qui, à leur tour, dépassent les déclarations de classe. Dans chaque type de déclaration, les déclarations postérieures dépassent les précédentes.

Dans une déclaration de  style , les éléments possibles sont :

Les couleurs et les pixmaps de fond sont définits comme une fonction de l'état du widget. Les états sont :

Les couleurs peuvent être définies comme des chaînes contenant un nom de couleur (GTK+ connaît tous les noms des couleurs X de la base de donnée  /usr/lib/X11/rgb.txt), dans une des formes hexadécimal #rrrrggggbbbb, #rrrgggbbb, #rrggbb, ou #rgb, où r, g et b sont des chiffres hécadécimaux, ou ils peuvent être définit comme un triplet  { r, g, b}, où r, g et b sont des entiers compris entre 0 et65535 ou des floats compris entre  0.0 et 1.0.

Depuis 2.10, les couleurs peuvent aussi être définies en se référent à une couleur symbolique, comme ceci : @color-name, ou en utilisant  des expressions pour combiner les couleurs. Les expressions suivantes sont actuellement soutenues :

Voici quelques exemples d'expressions de couleurs :

 mix (0.5, "red", "blue")
shade (1.5, mix (0.3, "#0abbc0", { 0.3, 0.5, 0.9 }))
lighter (@foreground)

stock["mon-stock-item"] = 
{
  { "itemltr.png", LTR, *, * },
  { "itemrtl.png", RTL, *, * }
}

stock["mon-stock-item"] =
{
  { "itemltr.png", LTR },
  { "itemrtl.png", RTL }
}

stock["mon-stock-item"] = 
{
  { "itemmenusize.png", *, *, "gtk-menu" },
  { "itemtoolbarsize.png", *, *, "gtk-large-toolbar" }
  { "itemgeneric.png" } /* implicit *, *, * as a fallback  (comme un retour en arrière)*/
}

Il est aussi possible d'utiliser des icônes créées pour des état données, par exemple :

stock["my-stock-item"] =
{
  { "itemprelight.png", *, PRELIGHT },
  { "iteminsensitive.png", *, INSENSITIVE }, { "itemgeneric.png" } /* implicit *, *, * as a fallback */
}

Raccourcis Clavier

Les raccourcis clavier permettent à l'utilisateur de définir des actions qui seront envoyées en pressant sur des touches particulières. La forme de la définition de déclaration d'un raccourci  est :

binding name 
{
  bind key { nondusignal (param, ...)
  ...
  }
...
}

keyest une chaîne composée d'une série de modifieurs suivis pas le nom de la touche. Les modifieurs peuvent être :

<shft> est un alias pour  <shift>, <ctl> est un alias pour  <control>, et <alt>est un alias pour  <mod1>.

L'action qui est liée à la touche est une séquence de noms de signaux (chaînes) suivie par des paramètres pour chaque signal. Les signaux doivent êtres des signaux d'action. (voir g_signal_new()). Chaque paramètre peut être un float, un entier, une chaîne, ou une chaîne entre guillemets représentant une énumération. Les types des paramètres spécifiés doivent accorder les types de paramètres du signal.

Les configuration de raccourci sont connectés aux widgets de la même manière que les styles, avec une différence : les configurations de raccourci dépassent les autres  raccourcis définis en premier par le type de modèle, ensuite par priorité et enfin par ordre de spécification. Les priorités  peuvent être définies et leur valeurs par défaut sont les mêmes que pour les styles.

GtkRcStyle

typedef struct 
{
  gchar *name;
  gchar *bg_pixmap_name[5];
  PangoFontDescription *font_desc;
  GtkRcFlags color_flags[5];
  GdkColor fg[5];
  GdkColor bg[5];
  GdkColor text[5];
  GdkColor base[5];
  gint xthickness;
  gint ythickness;
} GtkRcStyle;

La structure  GtkRcStyle  est utilisée pour représenter un ensemble d'informations concernant l'apparence d'un widget. Elle peut ensuite être assemblée  avec d'autres sutructures  GtkRcStyle pour former un GtkStyle.

enum GtkRcFlags

typedef enum
{
  GTK_RC_FG = 1 << 0,
  GTK_RC_BG = 1 << 1,
  GTK_RC_TEXT = 1 << 2,
  GTK_RC_BASE = 1 << 3
} GtkRcFlags;

L'énumération GtkRcFlags  est utilisée comme un  bitmask pour spécifier quels champs d'un  GtkRcStyle  ont été définis pour chaque état.

enum GtkRcTokenType

typedef enum {
  GTK_RC_TOKEN_INVALID = G_TOKEN_LAST,
  GTK_RC_TOKEN_INCLUDE,
  GTK_RC_TOKEN_NORMAL,
  GTK_RC_TOKEN_ACTIVE,
  GTK_RC_TOKEN_PRELIGHT,
  GTK_RC_TOKEN_SELECTED,
  GTK_RC_TOKEN_INSENSITIVE,
  GTK_RC_TOKEN_FG,
  GTK_RC_TOKEN_BG,
  GTK_RC_TOKEN_TEXT,
  GTK_RC_TOKEN_BASE,
  GTK_RC_TOKEN_XTHICKNESS,
  GTK_RC_TOKEN_YTHICKNESS,
  GTK_RC_TOKEN_FONT,
  GTK_RC_TOKEN_FONTSET,
  GTK_RC_TOKEN_FONT_NAME,
  GTK_RC_TOKEN_BG_PIXMAP,
  GTK_RC_TOKEN_PIXMAP_PATH,
  GTK_RC_TOKEN_STYLE,
  GTK_RC_TOKEN_BINDING,
  GTK_RC_TOKEN_BIND,
  GTK_RC_TOKEN_WIDGET,
  GTK_RC_TOKEN_WIDGET_CLASS,
  GTK_RC_TOKEN_CLASS,
  GTK_RC_TOKEN_LOWEST,
  GTK_RC_TOKEN_GTK,
  GTK_RC_TOKEN_APPLICATION,
  GTK_RC_TOKEN_THEME,
  GTK_RC_TOKEN_RC,
  GTK_RC_TOKEN_HIGHEST,
  GTK_RC_TOKEN_ENGINE,
  GTK_RC_TOKEN_MODULE_PATH,
  GTK_RC_TOKEN_IM_MODULE_PATH,
  GTK_RC_TOKEN_IM_MODULE_FILE,
  GTK_RC_TOKEN_STOCK,
  GTK_RC_TOKEN_LTR,
  GTK_RC_TOKEN_RTL,
  GTK_RC_TOKEN_COLOR,
  GTK_RC_TOKEN_UNBIND,
  GTK_RC_TOKEN_LAST
} GtkRcTokenType;

L'énumeration GtkRcTokenType  représente des mots-clés dans le fichier RC. Elle est exposé de tel façon que les moteurs de thèmes peuvent réutiliser des mots-clés pendant l'analyse des portions spécifiques  du theme-engine  du fichier RC.

gtk_rc_scanner_new ()

GScanner* 		gtk_rc_scanner_new 		(void);

gtk_rc_get_style ()

GtkStyle* 		gtk_rc_get_style 		(GtkWidget *widget);

Trouve tous les styles RC associés à un widget donné, elle les  sont assemble, et enfin elle crée un  GtkStyle représentant un aspect composé. (GTK+ généralement conserve un cache des styles préalablement créés, ainsi un nouveau style ne peut pas être créé.)

gtk_rc_get_style_by_paths ()

GtkStyle* 		gtk_rc_get_style_by_paths 		(GtkSettings *settings,
								 const char *widget_path,
								 const char *class_path,
								 GType type);

Créé un  GtkStyle à partir de styles définies dans un fichier RC en fournissant les composants bruts utilisés dans l'association. Cette fonction peut être utile pendant la création de pseudo-widgets auxquels on associe un thème comme pour les widgets mais qui n'ont pas réellement de widgets correspondants dans GTK+. Un exemple de cela serait les items à l'intérieur d'un widget canevas de GNOME.  

L'action de  gtk_rc_get_style() est semblable à :

gtk_widget_path (widget, NULL, &path, NULL);
gtk_widget_class_path (widget, NULL, &class_path, NULL);
gtk_rc_get_style_by_paths (gtk_widget_get_settings (widget), path, class_path,
			   G_OBJECT_TYPE (widget));

gtk_rc_add_widget_name_style ()

void 		gtk_rc_add_widget_name_style 		(GtkRcStyle *rc_style,
							 const gchar *pattern);

Ajoute un  GtkRcStyle qui sera recherché par  son association avec un nom de chemin de widget. c'est équivalent à un état : widget PATTERN style STYLE dans un fichier RC.

gtk_rc_add_widget_class_style ()

void 		gtk_rc_add_widget_class_style 		(GtkRcStyle *rc_style,
							 const gchar *pattern);

Ajoute un GtkRcStyle qui sera recherché par une association avec le nom de chemin de classe du widget. C'est équivalent à un état : widget_class PATTERN style STYLE dans un fichier RC.

gtk_rc_add_class_style ()

void 		gtk_rc_add_class_style 		(GtkRcStyle *rc_style,
						 const gchar *pattern);

Ajoute un  GtkRcStyle qui sera recherché par une association avec la hiérarchie de classe d'un widget. C'est l'équivalent de l'état : class PATTERN style STYLE dans un fichier RC.

gtk_rc_parse ()

void 		gtk_rc_parse 		(const gchar *filename);

Analyse le fichier ressource donné.

gtk_rc_parse_string ()

void 		gtk_rc_parse_string 		(const gchar *rc_string);

Analyse l'information ressource directement à partir d'une chaîne.

gtk_rc_reparse_all ()

gboolean 		gtk_rc_reparse_all		 (void);

Si le temps de modification ? ( modification time )  sur n'importe quel fichier lu précédemment pour le  GtkSettings par défaut a changé, cette fonction supprime toute information du style et ensuite relit tous les fichiers RC lus prédédemment .

gtk_rc_reparse_all_for_settings ()

gboolean 		gtk_rc_reparse_all_for_settings 		(GtkSettings *settings,
									 gboolean force_load);

Si le temps de modification ? ( modification time )  sur n'importe quel fichier lu précédemment pour le  GtkSettings donné a changé, cette fonction supprime toute information du style et ensuite relit tous les fichiers RC lus prédédemment .

gtk_rc_reset_styles ()

void 		gtk_rc_reset_styles 		(GtkSettings *settings);

Cette fonction recalcule les styles pour tous les widgets qui utilisent un objet  GtkSettings particulier. (Il y a un objet  GtkSettings par  GdkScreen, voir gtk_settings_get_for_screen()); C'est utile quand un paramètre global a changé en affectant l'apparence de tous les widgets, parce que quand un widget prend un nouveau style, elle va redessiner et recalculer toutes les informations sur l'apparence placées dans un cache. Par exemple, elle est utilisée quand la taille de la police par défaut, définie par le système d'exploitation, change. Notez que cette fonction n'a pas d'effet sur les widgets qui ont un style défini explicitement pour eux avec gtk_widget_set_style().

Depuis 2.4

gtk_rc_add_default_file ()

void 		gtk_rc_add_default_file 		(const gchar *filename);

Ajoute un fichier à la liste des fichiers à analyser à la fin de gtk_init().

gtk_rc_get_default_files ()

gchar** 		gtk_rc_get_default_files 		(void);

Recherche la liste courante des fichiers RC qui seront analysés à la fin de gtk_init().

gtk_rc_set_default_files ()

void 		gtk_rc_set_default_files 		(gchar **filenames);

Définit la liste des fichiers que  GTK+ lira à la fin de gtk_init().

gtk_rc_parse_color ()

guint 		gtk_rc_parse_color 		(GScanner *scanner,
						 GdkColor *color);

Analyse une couleur dans le format prévu dans le fichier RC.

gtk_rc_parse_state ()

guint 		gtk_rc_parse_state 		(GScanner *scanner,
						 GtkStateType *state);

Analyse une variable  GtkStateType  pour  le  format prévu dans le fichier RC.

gtk_rc_parse_priority ()

guint 		gtk_rc_parse_priority 		(GScanner *scanner,
						 GtkPathPriorityType *priority);

Analyse une variable  GtkPathPriorityType  pour le format prévu dans le fichier RC.

gtk_rc_find_module_in_path ()

gchar* 		gtk_rc_find_module_in_path 		(const gchar *module_file);

Cherche un moteur de thème (a theme engine)dans le chemin de recherche de GTK+. Cette fonction n'est pas utile pour les applications et ne doit pas être utilisée.

gtk_rc_find_pixmap_in_path ()

gchar* 		gtk_rc_find_pixmap_in_path 		(GtkSettings *settings,
							 GScanner *scanner,
							 const gchar *pixmap_file);

Cherche le fichier dans le chemin de pixmap pour le  GtkSettings spécifié. Si le fichier n'est pas trouvé, la fonction envoie un message d'alerte en utilisant g_warning() et retourne  NULL.

gtk_rc_get_module_dir ()

gchar* 		gtk_rc_get_module_dir 		(void);

Retourne un répertoire dans lequel GTK+ cherche des moteurs de thème. Pour plus d'information au sujet de la recherche de moteurs de thèmes, voir la documentation pour GTK_PATH in Exécuter les application GTK+(3).

gtk_rc_get_im_module_path ()

gchar* 		gtk_rc_get_im_module_path 		(void);

Obtient le chemin dans lequel chercher des modules IM. Voir la documentation sur la variable d'environnement GTK_PATH  pour plus de détails sur de la recherche de module. Cette fonction est utile seulement pour les utilitaires fournis  avec  GTK+ et ne devrait pas être utilisée par les applications dans des circonstances normales.

gtk_rc_get_im_module_file ()

gchar* 		gtk_rc_get_im_module_file 		(void);

Obteint le chemin pour le  fichier de modules IL. Voir la documentation de la variable d'environnement  GTK_IM_MODULE_FILE  pour plus de détails.

gtk_rc_get_theme_dir ()

gchar* 		gtk_rc_get_theme_dir 		(void);

Retourne me répertoire standard dans lequel les thèmes devraient être installés. (GTK+ n'utilse pas réellement ce répertoire elle-même).

gtk_rc_style_new ()

GtkRcStyle* 		gtk_rc_style_new 		(void);

Crée un nouveau GtkRcStyle avec aucune définition des champs et une référence de compteur à 1.

gtk_rc_style_copy ()

GtkRcStyle* 		gtk_rc_style_copy 		(GtkRcStyle *orig);

Fait une copie d'un GtkRcStyle  spécifié. Cette fonction copiera correctement un style RC qui est un membre d'une classe dérivée de GtkRcStyle.

gtk_rc_style_ref ()

void 		gtk_rc_style_ref 		(GtkRcStyle *rc_style);

Incrémente le compteur de référence d'un GtkRcStyle.

gtk_rc_style_unref ()

void 		gtk_rc_style_unref 		(GtkRcStyle *rc_style);

Décrémente le compteur de référence d'un GtkRcStyle et libère si le résultat est  0.