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

#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.