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

#include <gtk/gtk.h>


            gtkiconinfo;
            gtkicontheme;
enum        gtkiconlookupflags;
#define     gtk_icon_theme_error
enum        gtkiconthemeerror;
gtkicontheme* gtk_icon_theme_new            (void);
gtkicontheme* gtk_icon_theme_get_default    (void);
gtkicontheme* gtk_icon_theme_get_for_screen (gdkscreen *screen);
void        gtk_icon_theme_set_screen       (gtkicontheme *icon_theme,
                                             gdkscreen *screen);
void        gtk_icon_theme_set_search_path  (gtkicontheme *icon_theme,
                                             const gchar *path[],
                                             gint n_elements);
void        gtk_icon_theme_get_search_path  (gtkicontheme *icon_theme,
                                             gchar **path[],
                                             gint *n_elements);
void        gtk_icon_theme_append_search_path
                                            (gtkicontheme *icon_theme,
                                             const gchar *path);
void        gtk_icon_theme_prepend_search_path
                                            (gtkicontheme *icon_theme,
                                             const gchar *path);
void        gtk_icon_theme_set_custom_theme (gtkicontheme *icon_theme,
                                             const gchar *theme_name);
gboolean    gtk_icon_theme_has_icon         (gtkicontheme *icon_theme,
                                             const gchar *icon_name);
gtkiconinfo* gtk_icon_theme_lookup_icon     (gtkicontheme *icon_theme,
                                             const gchar *icon_name,
                                             gint size,
                                             gtkiconlookupflags flags);
gdkpixbuf*  gtk_icon_theme_load_icon        (gtkicontheme *icon_theme,
                                             const gchar *icon_name,
                                             gint size,
                                             gtkiconlookupflags flags,
                                             gerror **error);
glist*      gtk_icon_theme_list_icons       (gtkicontheme *icon_theme,
                                             const gchar *context);
gint*       gtk_icon_theme_get_icon_sizes   (gtkicontheme *icon_theme,
                                             const gchar *icon_name);
char*       gtk_icon_theme_get_example_icon_name
                                            (gtkicontheme *icon_theme);
gboolean    gtk_icon_theme_rescan_if_needed (gtkicontheme *icon_theme);
void        gtk_icon_theme_add_builtin_icon (const gchar *icon_name,
                                             gint size,
                                             gdkpixbuf *pixbuf);
gtkiconinfo* gtk_icon_info_copy             (gtkiconinfo *icon_info);
void        gtk_icon_info_free              (gtkiconinfo *icon_info);
gint        gtk_icon_info_get_base_size     (gtkiconinfo *icon_info);
const gchar* gtk_icon_info_get_filename     (gtkiconinfo *icon_info);
gdkpixbuf*  gtk_icon_info_get_builtin_pixbuf
                                            (gtkiconinfo *icon_info);
gdkpixbuf*  gtk_icon_info_load_icon         (gtkiconinfo *icon_info,
                                             gerror **error);
void        gtk_icon_info_set_raw_coordinates
                                            (gtkiconinfo *icon_info,
                                             gboolean raw_coordinates);
gboolean    gtk_icon_info_get_embedded_rect (gtkiconinfo *icon_info,
                                             gdkrectangle *rectangle);
gboolean    gtk_icon_info_get_attach_points (gtkiconinfo *icon_info,
                                             gdkpoint **points,
                                             gint *n_points);
const gchar* gtk_icon_info_get_display_name (gtkiconinfo *icon_info);

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

  gobject
   +----gtkicontheme

сигналы

"changed"   void        user_function      (gtkicontheme *icon_theme,
                                            gpointer      user_data)       : run last

описание

gtkicontheme обеспечивает средство для поиска значков по названию и размеру. основная причина использования названия вместо просто определённого имени файла заключается в том, что позволяет другим значкам использоваться в зависимости от выбора icon theme польльзователя. режим темы значков в linux и unix следует из спецификации темы значков. есть тема значков по умолчанию, названная hicolor, где приложения должны устанавливать свои значки, но большинство дополнительных тем приложений могут быть установлены в зависимости от выбора пользователя или поставщика операционной системы.

именованные значки подобны средству themeable stock images(3) и различия между ними могут быть немного запутанными. имейте ввиду несколько вещей:

• заготовленные изображения обычно используются вместе с заготовками пунктов(3)., таких как gtk_stock_ok или gtk_stock_open. именованные значки проще установить и поэтому более полезны приложениям которые хотят добавить свои значки, такие как пиктограммы приложений или пиктограммы окон.

• заготовленные изображения могут загружаться только в символическом размере определённом перечислением gtkiconsize, или размером выбранным gtk_icon_size_register(), в то время как именованные значки более гибки и могут определяться любыми размерами.

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

хорошее эмпирическое правило – если есть заготовленное изображение, для того что вы хотите, то используйте его, в любых других случаях используйте именованные значки. оказывается, что внутренне заготовленные изображения обычно определяются в терминах одного или более именованных значков. (пример более чем одного выбора значков зависящих от написанных инструкций; gtk_stock_go_forward использует два тематических значка "gtk-stock-go-forward-ltr" и "gtk-stock-go-forward-rtl".)

в некоторых случаях, именованные темы используются косвенно, через gtkimage или заготовленные пункты, но выполнить непосредственное определение значков тоже просто. объект gtkicontheme действует как база данных всех значков в текущемй теме. вы можете создавать новые объекты gtkicontheme, но намного эффективнее использовать стандартную тему значков для gdkscreen так, чтобы информация значка была доступна другим людям определяющим значки. в случае когда используется экран по умолчанию, определение значков может быть простым, как например:

gerror *error = null;
gtkicontheme *icon_theme;
gdkpixbuf *pixbuf;

icon_theme = gtk_icon_theme_get_default();
pixbuf = gtk_icon_theme_load_icon (icon_theme,
                                   "my-icon-name", /* имя значка */
                                   48, /* размер */
                                   0,  /* флаг */
                                   &error);
if (!pixbuf)
  {
    g_warning ("couldn't load icon: %s", error->message);
    g_error_free (message);
  }
else
  {
    /* использование pixbuf */
    g_object_unref (pixbuf);
  }

детали

gtkiconinfo

typedef struct _gtkiconinfo gtkiconinfo;

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

gtkicontheme

typedef struct _gtkicontheme gtkicontheme;

используется как база данных информации о теме значков. как правило, вы отыскиваете тему значка для специального отображения используя gtk_icon_theme_get_for_screen() и она будет вмещать информацию о текущемй теме значков для отображения, но ва также можете создать новый объект gtkicontheme и установить тему значков используя gtk_icon_theme_set_custom_theme().

перечень gtkiconlookupflags

typedef enum
{
  gtk_icon_lookup_no_svg = 1 << 0,
  gtk_icon_lookup_force_svg = 1 << 1,
  gtk_icon_lookup_use_builtin = 1 << 2
} gtkiconlookupflags;

использует специальные опции для gtk_icon_theme_lookup_icon()

gtk_icon_theme_error

#define gtk_icon_theme_error gtk_icon_theme_error_quark ()

перечень gtkiconthemeerror

typedef enum {
  gtk_icon_theme_not_found,
  gtk_icon_theme_failed
} gtkiconthemeerror;

коды ошибок для gtkicontheme операций.

gtk_icon_theme_new ()

gtkicontheme* gtk_icon_theme_new            (void);

создаёт новый объект темы значков. объект темы значков используется чтобы отыскать значок в специальной теме значков. обычно, используется gtk_icon_theme_get_default() или gtk_icon_theme_get_for_screen() вместо создания новых объектов темы значков с нуля.

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

gtk_icon_theme_get_default ()

gtkicontheme* gtk_icon_theme_get_default    (void);

делает тему значков отображаемой по умолчанию. смотрите gtk_icon_theme_get_for_screen().

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

gtk_icon_theme_get_for_screen ()

gtkicontheme* gtk_icon_theme_get_for_screen (gdkscreen *screen);

делает объект темы значков ассоциированным с screen; если эта функция не имела предварительного вызова для получаемого экрана, новый объект темы значков будет создан и ассоциирован с экраном. использование этой функции обычно лучший выбор чем вызов gtk_icon_theme_new() и настройка экрана самостоятельно; при использовании этой функции, единственный объект темы значков будет распределён между пользователями.

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

gtk_icon_theme_set_screen ()

void        gtk_icon_theme_set_screen       (gtkicontheme *icon_theme,
                                             gdkscreen *screen);

устанавливает экран для темы значка; чтобы проследить текущую в настоящее время тему значка пользователя, которая могла бы быть другой для различных экранов.

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

gtk_icon_theme_set_search_path ()

void        gtk_icon_theme_set_search_path  (gtkicontheme *icon_theme,
                                             const gchar *path[],
                                             gint n_elements);

устанавливает путь поиска объектов темы значков. просматривая темы значков, gtk+ будет искать, в одном или больше, подкаталогах обозначенного path каталога с именем как у темы значков. (многочисленные пути элементов тем скомбинированы, чтобы позволить темам быть расширенными добавлением значков из домашнего каталога пользователя.)

кроме того, если искомый значок не найден в текущемй теме или теме значков по умолчанию, а файл изображения с правильным именем найден непосредственно в одном из элементов path, то это изображение будет использовано для именованного значка. (это особенность наследования и новые значки должны быть помещены в тему значков по умолчанию с названием default_theme_name, а не непосредственно в путь значка.)

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

gtk_icon_theme_get_search_path ()

void        gtk_icon_theme_get_search_path  (gtkicontheme *icon_theme,
                                             gchar **path[],
                                             gint *n_elements);

выполняет текущий поиск пути. смотрите gtk_icon_theme_set_search_path().

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

gtk_icon_theme_append_search_path ()

void        gtk_icon_theme_append_search_path
                                            (gtkicontheme *icon_theme,
                                             const gchar *path);

добавляет каталог в путь поиска. смотрите gtk_icon_theme_set_search_path().

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

gtk_icon_theme_prepend_search_path ()

void        gtk_icon_theme_prepend_search_path
                                            (gtkicontheme *icon_theme,
                                             const gchar *path);

устанавливает каталог первичным в пути поиска. смотрите gtk_icon_theme_set_search_path().

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

gtk_icon_theme_set_custom_theme ()

void        gtk_icon_theme_set_custom_theme (gtkicontheme *icon_theme,
                                             const gchar *theme_name);

устанавливает имя темы значков как объект gtkicontheme используемый главной системной конфигурацией. эта функция не будет вызвана объектами темы значков, возвращённых из gtk_icon_theme_get_default() и gtk_icon_theme_get_for_screen().

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

gtk_icon_theme_has_icon ()

gboolean    gtk_icon_theme_has_icon         (gtkicontheme *icon_theme,
                                             const gchar *icon_name);

проверяет наличие специфического имени значка в теме значков.

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

gtk_icon_theme_lookup_icon ()

gtkiconinfo* gtk_icon_theme_lookup_icon     (gtkicontheme *icon_theme,
                                             const gchar *icon_name,
                                             gint size,
                                             gtkiconlookupflags flags);

находит именованный значок и возвращает структуру содержащую информацию такую как имя файла значка. значок может быть передан в pixbuf используя gtk_icon_info_load_icon(). (gtk_icon_theme_load_icon() комбинирует эти два шага если всё что вам нужно это pixbuf.)

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

gtk_icon_theme_load_icon ()

gdkpixbuf*  gtk_icon_theme_load_icon        (gtkicontheme *icon_theme,
                                             const gchar *icon_name,
                                             gint size,
                                             gtkiconlookupflags flags,
                                             gerror **error);

находит значок в теме значков, масштабируя к заданному размеру и передаёт в pixbuf. если нужно больше деталей о значке, используйте gtk_icon_theme_lookup_icon() сопровождаемую gtk_icon_info_load_icon().

отметьте, что вам вероятно нужно посмотреть изменения темы значков и обновить значок. это удобно делать подключившись к gtkwidget::style-set сигналу. если по некоторым причинам вы не хотите обновлять значок когда изменяется тема значков, то вы можете использовать gdk_pixbuf_copy() для создания частной копии pixbuf возвращаемой этой функцией. иначе gtk+ возможно оставит старую тему значков загруженной, что было бы не нужной тратой памяти.

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

gtk_icon_theme_list_icons ()

glist*      gtk_icon_theme_list_icons       (gtkicontheme *icon_theme,
                                             const gchar *context);

перечисляет значки в текущемй теме значков. только подмножество значков может быть перечислено обеспечивая содержимое строки. набор значений для содержимого строки системно зависим, но обычно будут включены, такие значения как 'apps' и 'mimetypes'.

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

gtk_icon_theme_get_icon_sizes ()

gint*       gtk_icon_theme_get_icon_sizes   (gtkicontheme *icon_theme,
                                             const gchar *icon_name);

возвращает массив целых чисел, в которых значок доступен без масштабирования. размер -1 означает доступность масштабирования значка. массив заканчивается 0 (zero-terminated).

начиная с версии 2.6

gtk_icon_theme_get_example_icon_name ()

char*       gtk_icon_theme_get_example_icon_name
                                            (gtkicontheme *icon_theme);

получает название значка, который представлен текущемй темой (например, используется когда представляется список тем пользователю.)

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

gtk_icon_theme_rescan_if_needed ()

gboolean    gtk_icon_theme_rescan_if_needed (gtkicontheme *icon_theme);

выясняет, изменилась ли тема значка; если да, то любая кэширующая информация в текущеме время отбрасывается и будет перезагружена в следующий раз доступа к icon_theme.

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

gtk_icon_theme_add_builtin_icon ()

void        gtk_icon_theme_add_builtin_icon (const gchar *icon_name,
                                             gint size,
                                             gdkpixbuf *pixbuf);

регистрирует встроенный значок для поиска темы. идея встроенных значков позволяет приложениям или библиотекам использовать тематические значки в функциях требующих представления файлов в файловой системе. например, по умолчанию изображения для всех заготовленных значков gtk+'s имеют регистрацию как встроенные значки.

вообще, если вы используете gtk_icon_theme_add_builtin_icon(), вы также должны установить значок в тему значков, чтобы значок был обще-доступен.

эта функция будет использоваться с pixbufs, загруженным через gdk_pixbuf_new_from_inline().

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

gtk_icon_info_copy ()

gtkiconinfo* gtk_icon_info_copy             (gtkiconinfo *icon_info);

создаёт копию gtkiconinfo.

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

gtk_icon_info_free ()

void        gtk_icon_info_free              (gtkiconinfo *icon_info);

освобождает gtkiconinfo и ассоциированную информацию

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

gtk_icon_info_get_base_size ()

gint        gtk_icon_info_get_base_size     (gtkiconinfo *icon_info);

выдаёт основной размер значка. основной размер, это размер значка определённый создателем темы значков. он может отличаться от реального размера изображения; например маленькая эмблема значка может быть прикреплена к большому значку. эти значки будут получать тот же самый основной размер, как и большие значки к которым они прикреплены.

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

gtk_icon_info_get_filename ()

const gchar* gtk_icon_info_get_filename     (gtkiconinfo *icon_info);

выдаёт имя файла для значка. если установлен флаг gtk_icon_lookup_use_builtin в gtk_icon_theme_lookup_icon(), она может не вернуть имя файла для встроенного значка; в этом случае, вы должны использовать gtk_icon_info_get_builtin_pixbuf().

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

gtk_icon_info_get_builtin_pixbuf ()

gdkpixbuf*  gtk_icon_info_get_builtin_pixbuf
                                            (gtkiconinfo *icon_info);

выдаёт встроенное изображение для этого значка. позволяет gtk+ использовать встроенные значки изображений, вы можете поместить gtk_icon_lookup_use_builtin в gtk_icon_theme_lookup_icon().

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

gtk_icon_info_load_icon ()

gdkpixbuf*  gtk_icon_info_load_icon         (gtkiconinfo *icon_info,
                                             gerror **error);

предоставляет значок, предварительно найденный в теме значков, используя gtk_icon_theme_lookup_icon(); размер будет базироваться на размере помещенном в gtk_icon_theme_lookup_icon(). отметьте, что результирующий pixbuf может не быть именно этого размера; тема значков может иметь значки отличающиеся немного от номинального размера, а кроме того gtk+ позволит масштабирование значков, которые достаточно близки к запрошенному размеру или для которых исходное изображение должно было бы масштабироваться слишком сильно. (это улучшает резкость.)

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

gtk_icon_info_set_raw_coordinates ()

void        gtk_icon_info_set_raw_coordinates
                                            (gtkiconinfo *icon_info,
                                             gboolean raw_coordinates);

устанавливает должны ли координаты возвращённые gtk_icon_info_get_embedded_rect() и gtk_icon_info_get_attach_points() быть возвращены в их оригинальной форме как определено в теме значков, вместо масштабируемого соответственно для pixbuf возвращенного gtk_icon_info_load_icon().

не обработанные координаты немного странные; они определены быть не масштабируемыми относительно pixmap для png и xpm значков, но для svg значков, они имеют координатное пространство 1000x1000 которое масштабируется к законченному размеру значка. вы можете определить является ли значок svg значком, используя gtk_icon_info_get_filename(), и посмотрев если он не-null и имеет окончание '.svg'.

эта функция обеспечивает первичную совместимость оболочек для старого api's, и не очень полезна для приложений.

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

gtk_icon_info_get_embedded_rect ()

gboolean    gtk_icon_info_get_embedded_rect (gtkiconinfo *icon_info,
                                             gdkrectangle *rectangle);

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

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

gtk_icon_info_get_attach_points ()

gboolean    gtk_icon_info_get_attach_points (gtkiconinfo *icon_info,
                                             gdkpoint **points,
                                             gint *n_points);

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

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

gtk_icon_info_get_display_name ()

const gchar* gtk_icon_info_get_display_name (gtkiconinfo *icon_info);

выдаёт название отображения для значка. имя отображения, это строка для использования вместо имени значка в визуальном пользовательском контексте, например как список значков.

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

детали сигналов

сигнал "changed"

void        user_function                  (gtkicontheme *icon_theme,
                                            gpointer      user_data)       : run last

создаётся когда текущая тема значков переключена или gtk+ определил что произошли изменения в текущемй теме значков.