Краткое описание

#include <gtk/gtk.h>


            GtkRcStyle;
enum        GtkRcFlags;
enum        GtkRcTokenType;
GScanner*   gtk_rc_scanner_new              (void);
GtkStyle*   gtk_rc_get_style                (GtkWidget *widget);
GtkStyle*   gtk_rc_get_style_by_paths       (GtkSettings *settings,
                                             const char *widget_path,
                                             const char *class_path,
                                             GType type);
void        gtk_rc_add_widget_name_style    (GtkRcStyle *rc_style,
                                             const gchar *pattern);
void        gtk_rc_add_widget_class_style   (GtkRcStyle *rc_style,
                                             const gchar *pattern);
void        gtk_rc_add_class_style          (GtkRcStyle *rc_style,
                                             const gchar *pattern);
void        gtk_rc_parse                    (const gchar *filename);
void        gtk_rc_parse_string             (const gchar *rc_string);
gboolean    gtk_rc_reparse_all              (void);
gboolean    gtk_rc_reparse_all_for_settings (GtkSettings *settings,
                                             gboolean force_load);
void        gtk_rc_reset_styles             (GtkSettings *settings);
void        gtk_rc_add_default_file         (const gchar *filename);
gchar**     gtk_rc_get_default_files        (void);
void        gtk_rc_set_default_files        (gchar **filenames);
guint       gtk_rc_parse_color              (GScanner *scanner,
                                             GdkColor *color);
guint       gtk_rc_parse_state              (GScanner *scanner,
                                             GtkStateType *state);
guint       gtk_rc_parse_priority           (GScanner *scanner,
                                             GtkPathPriorityType *priority);
gchar*      gtk_rc_find_module_in_path      (const gchar *module_file);
gchar*      gtk_rc_find_pixmap_in_path      (GtkSettings *settings,
                                             GScanner *scanner,
                                             const gchar *pixmap_file);
gchar*      gtk_rc_get_module_dir           (void);
gchar*      gtk_rc_get_im_module_path       (void);
gchar*      gtk_rc_get_im_module_file       (void);
gchar*      gtk_rc_get_theme_dir            (void);
GtkRcStyle* gtk_rc_style_new                (void);
GtkRcStyle* gtk_rc_style_copy               (GtkRcStyle *orig);
void        gtk_rc_style_ref                (GtkRcStyle *rc_style);
void        gtk_rc_style_unref              (GtkRcStyle *rc_style);

Иерархия объектов

  GObject
   +----GtkRcStyle

Описание

GTK+ имеет механизм ресурсных файлов для настройки различных аспектов действий программы GTK+ во время выполнения.

Файлы по умолчанию

Приложение может заставить GTK+ анализировать специальный RC файл вызвав gtk_rc_parse(). В дополнение к этому, определённые файлы будут прочитаны gtk_init()в конце. По умолчанию, поиск файлов будет производиться в <SYSCONFDIR>/gtk-2.0/gtkrc и .gtkrc-2.0 домашнем каталоге пользователя. (<SYSCONFDIR> - по умолчанию /usr/local/etc. Это значение можно изменить при помощи опций --prefix или --sysconfdir при конфигурировании GTK+.) Не смотря на то, что имена файлов содержат номер версии 2.0, все версии серии 2.x GTK+ будут просматривать эти файлы.

Установки по умолчанию этих файлов могут быть восстановлены с помощью gtk_rc_get_default_files() и изменены с помощью gtk_rc_add_default_file() и gtk_rc_set_default_files(). Дополнительно, переменная окруженияя GTK2_RC_FILES может быть установлена в G_SEARCHPATH_SEPARATOR_S – отдельный список файлов, перезаписывающий во время выполнения установленные по умолчанию файлы.

Для каждого RC файла, в дополнение к самому файлу, GTK+ будет искать специальные файлы локализации (locale-specific) для анализа после основного файла. Например, если переменная LANG установлена в ja_JP.ujis, когда загружен файл по умолчанию ~/.gtkrc , то GTK+ ищет ~/.gtkrc.ja_JP и ~/.gtkrc.ja, анализируя первый из найденных.

Имя пути и образцы

Ресурсные файлы определяют множество стилей и ключевых привязок, присоединяя их к специфическим виджетам. Присоединение выполняется декларацией widget, widget_class, и class. Как пример такого заявления:

widget "mywindow.*.GtkEntry" style "my-entry-class"

прикрепляет стиль "my-entry-class" ко всем виджетам widget class соответствующих образцу "mywindow.*.GtkEntry".

Образцы даются в стандартном синтаксисе оболочки shell. Символ "?" соответствует любому символу, а символ "*" соответствует и любому символу и отсутствию такойвых. Существует три типа соответствия - путь виджета, путь класса (class path) и иерархия класса. И путь виджета и путь класса состоят из разделенного "." списка всех родительских виджетов и непосредственно виджета, от наиболее удалённого до самого внутреннего. Различие в том, что в пути виджета используется или название установленное gtk_widget_set_name(), или имя класса виджета, в то время как для пути класса всегда используется имя класса.

Таким образом, если вы имеете GtkEntry названный "myentry", внутри окна названного "mywindow", путь виджета будет: "mwindow.GtkHBox.myentry", в то время как путь класса: "GtkWindow.GtkHBox.GtkEntry".

Соответствие к классу немного различается. Образец соответствия выполнен ко всем именам класса в последовательности иерархии классов виджетов (не иерархия расположения), таким образом образец:

class "GtkButton" style "my-style"

будет соответствовать не только виджетам GtkButton, но так же виджетам GtkToggleButton и GtkCheckButton, так как их классы происходят от GtkButton.

Дополнительно, может быть определён приоритет для каждого образца, приоритет отмены стиля другим стилем, затем тип образца и потом порядок спецификации (позднее отменяет раннее). Приоритеты, могут быть определены (от высшего к низшему):

rc – по умолчанию для стилей прочитанных из RC файла, theme – по умолчанию для стилей прочитанных из RC файла темы, application – должно использоваться для стилей которые устанавливают приложения и gtk – используется для стилей созданных внутри GTK+.

Декларации высшего уровня

RC файл является обычным текстовым файлом, который составлен из последовательности деклараций. Знаками '#' начинаются строки комментарии, которые пропускаются при анализе файла.

Возможные декларации высшего уровня:

Стили

RC стиль определяется объявлением style в RC файле, затем виджеты с помощью объявления widget, widget_class, или class. Все стили применяются к специальному виджету с widget декларацией отменяющий декларацию widget_class, которая в свою очередь отменяет class декларацию. В пределах каждого типа декларации, более поздняя отменяет более раннюю.

В пределах style декларации, возможны элементы:

Цвета и фоновые изображения определяются как функции состояния виджета.

Состояния:

Цвета могут быть представлены как строки содержащие имя цвета(GTK+ поддерживает все имена цветов из базы данных X color database /usr/lib/X11/rgb.txt), в одной из шестнадцатиричных форм #rrrrggggbbbb, #rrrgggbbb, #rrggbb, или #rgb, где r, g и b шестнадцатиричные числа, или они могут быть определены как тройка { r, g, b}, где r, g и b являются или целыми числами в диапазоне 0-65535 или с плавающей точкой в диапазоне 0.0-1.0.

В stock определении, источники значков определены 4-кратно - имя файла изображения или имя значка, направление текста, состояние виджета, и размер, в соответствующем порядке. Каждый источник изображения определяет имя файла изображения или имя значка чтобы использовать с данным направлением, состоянием и размером. Имена файлов определены строками, например как "itemltr.png", в то время как имена значков (в текущемй теме значков), определяются с заглавным символом @, например @"item-ltr". Символ * может быть использован как шаблон, если направление/состояние/размер опущены то по умолчанию они *. Так например следующее, определяет различные значки используемые для направлений языков слева на право и наоборот:

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

Можно сократить следующим образом:

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

Вы можете определить выборочно значки для специальных размеров, как например:

stock["my-stock-item"] = 
{
  { "itemmenusize.png", *, *, "gtk-menu" },
  { "itemtoolbarsize.png", *, *, "gtk-large-toolbar" }
  { "itemgeneric.png" } /* implicit *, *, * as a fallback */
}

Непосредственно с GTK+ идут размеры "gtk-menu", "gtk-small-toolbar", "gtk-large-toolbar", "gtk-button", "gtk-dialog". Приложения могут устанавливать другие размеры.

Также возможно использование выборочного размера для данного состояния, например:

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

Выбирая источник значков для использования, GTK+ первым по важности рассматривает направление текста, вторым состояние виджета и третим размер. Она выберет лучшее соответствие основанное на трёх критериях. Если атрибут соответствует точно (например вы определили PRELIGHT или определенный размер), GTK+ не будет изменять изображение; если атрибут соответствует шаблону, GTK+ масштабирует или изменяет изображение до соответствия запросу пользователя.

Привязки клавиш

Привязки клавиш позволяют пользователю определять действие воспроизводимое при нажатии определенных клавиш. Форма декларации установки привязки:

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

key – это строка содержащая ряд модификаторов сопровождаемых именем клавиши. Модификаторы могут быть следующими:

<shft> псевдоним для <shift>, а <alt> псевдоним для <mod1>.

Действие привязанное к ключу – это последовательность имён сигналов сопровождаемая параметрами для каждого сигнала. Сигналы должны быть сигналами действия. (См. g_signal_new()). Каждый параметр может быть десятичным, целым, строкой, или не цитируемой строкой представляющей перечисленные значения. Типы определенных параметров должны соответствовать типам параметров сигнала.

Наборы привязок соединяются с виджетами в той же манере как и стили, с одним различием: Наборы привязок отменяют другие наборы привязок сначала по образцу типа, затем по приоритету и потом по порядку определения. Приоритеты могут быть определенными и их значения по умолчанию такие же как для стилей.

Детали

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;

Структура GtkRcStyle используется для представления ряда информации о внешнем виде виджета. Она может быть позже совмещена с другими структурами GtkRcStyle, чтобы сформировать 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;

Перечисление GtkRcFlags используется как битовая маска (bitmask), чтобы определить какие поля GtkRcStyle были установлены для каждого состояния.

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_LAST
} GtkRcTokenType;

Перечисление GtkRcTokenType представляет символы в RC файлах. Они выставлены так чтобы движки темы могли многократно использовать эти символы когда анализируются определенные движком темы (theme-engine) части RC файла.

gtk_rc_scanner_new ()

GScanner*   gtk_rc_scanner_new              (void);

gtk_rc_get_style ()

GtkStyle*   gtk_rc_get_style                (GtkWidget *widget);

Находит все соответствующие RC стили для данного виджета, соединяет их вместе и создаёт GtkStyle представляющий совмещенный внешний вид. (GTK+ фактически содержит кэш предварительно созданных стилей, таким образом новый стиль не создаётся.)

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);

Создаёт GtkStyle поверх стилей определённых в RC файле, обеспечивая исходные компоненты используемые соответственно. Эта функция может быть полезна при создании псевдо-виджетов, которые должны быть как виджеты темы, но фактически не имеют соответствующих GTK+ виджетов. Например пункты внутри GNOME canvas widget.

Действие gtk_rc_get_style() подобно:

 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);

Внимание

gtk_rc_add_widget_name_style устарела и её не нужно использовать во вновь создаваемом коде.

Добавляет GtkRcStyle который будет при поиске сравниваться с именем пути виджетов. Это эквивалентно: widget PATTERN style STYLE заявлению в RC файле.

gtk_rc_add_widget_class_style ()

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

Внимание

gtk_rc_add_widget_class_style устарела и её не нужно использовать во вновь создаваемом коде.

Добавляет GtkRcStyle который будет при поиске сравниваться с именем пути класса. Это эквивалентно: widget_class PATTERN style STYLE заявлению в RC файле.

gtk_rc_add_class_style ()

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

Внимание

gtk_rc_add_class_style устарела и её не нужно использовать во вновь создаваемом коде.

Добавляет GtkRcStyle который будет при поиске сравниваться с иерархией класса виджета. Это эквивалентно: class PATTERN style STYLE заявлению в RC файле.

gtk_rc_parse ()

void        gtk_rc_parse                    (const gchar *filename);

Анализирует полученные ресурсные файлы.

gtk_rc_parse_string ()

void        gtk_rc_parse_string             (const gchar *rc_string);

Анализирует ресурсную информацию непосредственно из строки.

gtk_rc_reparse_all ()

gboolean    gtk_rc_reparse_all              (void);

Если время модификации на любом предварительно прочитанном файле для GtkSettings по умолчанию было изменено, бракуется вся информация стиля и перечитываются все предварительно прочитанные RC файлы.

gtk_rc_reparse_all_for_settings ()

gboolean    gtk_rc_reparse_all_for_settings (GtkSettings *settings,
                                             gboolean force_load);

Если время модификации на любом предварительно прочитанном файле для полученного GtkSettings было изменено, бракуется вся информация стиля и перечитываются все предварительно прочитанные RC файлы.

gtk_rc_reset_styles ()

void        gtk_rc_reset_styles             (GtkSettings *settings);

Эта функция повторно загружает все стили для виджетов использующих специальный объект GtkSettings. (Есть один объект GtkSettings в GdkScreen, см. gtk_settings_get_for_screen()); Она полезна когда некоторый глобальный параметр изменен, что затрагивает внешний вид всех виджетов, потому что когда виджет получает новый стиль, она повторно перерисует и вычислит любую информацию в кэше о внешнем виде. Как пример, она используется когда размер шрифта по умолчанию операционной системы изменяется. Заметьте, эта функция не затрагивает виджеты которые имеют стиль явно определенный функцией gtk_widget_set_style().

Начиная с версии 2.4

gtk_rc_add_default_file ()

void        gtk_rc_add_default_file         (const gchar *filename);

Добавляет файл в список файлов анализируемых в конце gtk_init().

gtk_rc_get_default_files ()

gchar**     gtk_rc_get_default_files        (void);

Восстанавливает текущий список RC файлов, который будет анализироваться в конце gtk_init().

gtk_rc_set_default_files ()

void        gtk_rc_set_default_files        (gchar **filenames);

Устанавливает список файлов которые GTK+ прочтёт в конце gtk_init().

gtk_rc_parse_color ()

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

Анализирует цвет в формате применяемом в RC файле.

gtk_rc_parse_state ()

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

Анализирует переменную GtkStateType в формате применяемом в RC файле.

gtk_rc_parse_priority ()

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

Анализирует переменную GtkPathPriorityType в формате применяемом в RC файле.

gtk_rc_find_module_in_path ()

gchar*      gtk_rc_find_module_in_path      (const gchar *module_file);

Поисковик движка темы в GTK+ ищет путь. Эта функция не полезна для приложений и не должна использоваться.

gtk_rc_find_pixmap_in_path ()

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

Ищет файл в пути изображения для определенного GtkSettings. Если файл не найден, она выдаст предупреждающее сообщение используя g_warning() и возвратит NULL.

gtk_rc_get_module_dir ()

gchar*      gtk_rc_get_module_dir           (void);

Возвращает каталог в котором GTK+ ищет движки тем. Для полной информации о поиске движков тем, смотрите документацию для GTK_PATH в Running GTK+ Applications(3).

gtk_rc_get_im_module_path ()

gchar*      gtk_rc_get_im_module_path       (void);

Получает путь для поиска модулей IM. Смотрите документацию по переменной окруженияя GTK_PATH для более полной информации о поиске модулей. Эта функция используется для утилит GTK+ и не должна использоваться в нормальных ситуациях.

gtk_rc_get_im_module_file ()

gchar*      gtk_rc_get_im_module_file       (void);

Получает путь к файлу модулей IM. Для подробной информации смотрите документацию по переменной окруженияя GTK_IM_MODULE_FILE.

gtk_rc_get_theme_dir ()

gchar*      gtk_rc_get_theme_dir            (void);

Возвращает стандартный каталог для установки тем. (GTK+ фактически не использует этот каталог непосредственно.)

gtk_rc_style_new ()

GtkRcStyle* gtk_rc_style_new                (void);

Создаёт новый GtkRcStyle без набора полей и счетом ссылок равным 1.

gtk_rc_style_copy ()

GtkRcStyle* gtk_rc_style_copy               (GtkRcStyle *orig);

Создаёт копию определенного GtkRcStyle. Эта функция корректно копирует RC стиль который является членом класса полученного из GtkRcStyle.

gtk_rc_style_ref ()

void        gtk_rc_style_ref                (GtkRcStyle *rc_style);

Увеличивает счет ссылки GtkRcStyle.

gtk_rc_style_unref ()

void        gtk_rc_style_unref              (GtkRcStyle *rc_style);

Уменьшает счет ссылки GtkRcStyle и освобождает если результат 0.