Prev

Up

Home

GTK+ Reference Manual

Next

Top  |  Description  |  Object Hierarchy  |  Signals

GtkIconTheme

GtkIconTheme Определение значка по имени.

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

#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) и различия между ними могут быть немного запутанными. Имейте ввиду несколько вещей:

Хорошее эмпирическое правило если есть заготовленное изображение, для того что вы хотите, то используйте его, в любых других случаях используйте именованные значки. Оказывается, что внутренне заготовленные изображения обычно определяются в терминах одного или более именованных значков. (пример более чем одного выбора значков зависящих от написанных инструкций; 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_LOOKUP_NO_SVG

Никогда не возвращает SVG значки, даже если gdk-pixbuf поддерживает их. Не может использоваться вместе с GTK_ICON_LOOKUP_FORCE_SVG.

GTK_ICON_LOOKUP_FORCE_SVG

Возвращает SVG значки, даже если gdk-pixbuf не поддерживает их. Не должен использоваться вместе с GTK_ICON_LOOKUP_NO_SVG.

GTK_ICON_LOOKUP_USE_BUILTIN

Когда помещён в gtk_icon_theme_lookup_icon() включает встроенные значки также как и файлы. Для встроенных значков, gtk_icon_info_get_filename() возвращает NULL и вам нужно вызвать gtk_icon_info_get_builtin_pixbuf().


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_NOT_FOUND

Определенный значок не существует в теме

GTK_ICON_THEME_FAILED

Произошла не установленная ошибка.


gtk_icon_theme_new ()

GtkIconTheme* gtk_icon_theme_new            (void);

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

Возвращает :

вновь созданный объект GtkIconTheme.

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


gtk_icon_theme_get_default ()

GtkIconTheme* gtk_icon_theme_get_default    (void);

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

Возвращает :

Уникальный GtkIconTheme ассоциированный с экраном по умолчанию. Эта тема значков ассоциированная с экраном используется до тех пор пока экран открыт.

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


gtk_icon_theme_get_for_screen ()

GtkIconTheme* gtk_icon_theme_get_for_screen (GdkScreen *screen);

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

screen :

GdkScreen

Возвращает :

Уникальный GtkIconTheme связанный с полученным экраном. Может использоваться всё время пока открыт экран.

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


gtk_icon_theme_set_screen ()

void gtk_icon_theme_set_screen (GtkIconTheme *icon_theme, GdkScreen *screen);

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

icon_theme :

GtkIconTheme

screen :

GdkScreen

Начиная с версии 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, а не непосредственно в путь значка.)

icon_theme :

GtkIconTheme

path :

Массив каталогов в которых происходит поиск значков тем.

n_elements :

Число элементов в path.

Начиная с версии 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().

icon_theme :

GtkIconTheme

path :

Расположение сохраненного списка каталогов тем значков или NULL. Сохранённое значение должно быть освобождено с помощью g_strfreev().

n_elements :

Расположение сохраняемого числа элементов в path, или NULL

Начиная с версии 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().

icon_theme :

GtkIconTheme

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().

icon_theme :

GtkIconTheme

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().

icon_theme :

GtkIconTheme

theme_name :

Имя темы значков используемая вместо сконфигурированной темы, или NULL чтобы сбросить предварительно установленную тему

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


gtk_icon_theme_has_icon ()

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

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

icon_theme :

GtkIconTheme

icon_name :

Имя значка

Возвращает :

TRUE если icon_theme включает значки для 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.)

icon_theme :

GtkIconTheme

icon_name :

Именованный значок, который необходимо найти

size :

Желательный размер значка

flags :

Флаг изменяющий поведение поиска значка

Возвращает :

GtkIconInfo структура вмещающая информацию о значке, или NULL если значок не найден. Освобождается при помощи gtk_icon_info_free()

Начиная с версии 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+ возможно оставит старую тему значков загруженной, что было бы не нужной тратой памяти.

icon_theme :

GtkIconTheme

icon_name :

Искомый именованный значок

size :

Желаемый размер значка. Результат может не точно соответствовать желаемому размеру; смотрите gtk_icon_info_load_icon().

flags :

Флаг изменяющий поведение поиска значка

error :

Расположение информации об ошибках при неудачах, или NULL.

Возвращает :

значок; это может быть вновь созданный значок или новые свойства внутреннего значка, таким образом вы не должны изменять значок. Используйте g_object_unref() для реализации ваших свойств значка. NULL если значок не найден.

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


gtk_icon_theme_list_icons ()

GList* gtk_icon_theme_list_icons (GtkIconTheme *icon_theme, const gchar *context);

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

icon_theme :

GtkIconTheme

context :

Строка идентифицирующая специальный тип значка, или NULL для списка всех значков.

Возвращает :

GList список содержащий имена всех значков в теме. Вы должны в первую очередь освободить каждый элемент в списке с помощью g_free(), потом освободить сам список с помощью g_list_free().

Начиная с версии 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).

icon_theme :

GtkIconTheme

icon_name :

Именованный значок

Возвращает :

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

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


gtk_icon_theme_get_example_icon_name ()

char* gtk_icon_theme_get_example_icon_name (GtkIconTheme *icon_theme);

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

icon_theme :

GtkIconTheme

Возвращает :

Название значка примера или NULL. Освобождается с помощью g_free().

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


gtk_icon_theme_rescan_if_needed ()

gboolean    gtk_icon_theme_rescan_if_needed (GtkIconTheme *icon_theme);

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

icon_theme :

GtkIconTheme

Возвращает :

TRUE если тема значков была изменена и требуется перезагрузка.

Начиная с версии 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().

icon_name :

Имя регистрируемого значка

size :

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

pixbuf :

GdkPixbuf содержит изображение используемое для icon_name.

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


gtk_icon_info_copy ()

GtkIconInfo* gtk_icon_info_copy             (GtkIconInfo *icon_info);

Создаёт копию GtkIconInfo.

icon_info :

GtkIconInfo

Возвращает :

новый GtkIconInfo

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


gtk_icon_info_free ()

void        gtk_icon_info_free              (GtkIconInfo *icon_info);

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

icon_info :

GtkIconInfo

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


gtk_icon_info_get_base_size ()

gint        gtk_icon_info_get_base_size     (GtkIconInfo *icon_info);

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

icon_info :

GtkIconInfo

Возвращает :

Основной размер, или 0, если нет основного размера значка.

Начиная с версии 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().

icon_info :

GtkIconInfo

Возвращает :

Имя файла для значка, или NULL если должна быть использована gtk_icon_info_get_builtin_pixbuf(). Возвращаемым значением владеет GTK+ и оно не должно изменяться или становиться недоступным.

Начиная с версии 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().

icon_info :

структура GtkIconInfo

Возвращает :

Встроенное изображение pixbuf, или NULL. Не расширяет справочную информацию добавляемую к возвращаемому pixbuf, поэтому если вам это нужно, используйте g_object_ref(). Возвращаемое изображение не может изменяться.

Начиная с версии 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+ позволит масштабирование значков, которые достаточно близки к запрошенному размеру или для которых исходное изображение должно было бы масштабироваться слишком сильно. (это улучшает резкость.)

icon_info :

Структура GtkIconInfo из gtk_icon_theme_lookup_icon()

error :

Расположение сохранённых ошибок информирующих о неудачах, или NULL.

Возвращает :

Предоставляет значок; это может быть вновь-созданный значок или новая информация внутреннего значка, поэтому вы не должны изменять значок. Используйте g_object_unref() для освободить справочную информацию о значке.

Начиная с версии 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, и не очень полезна для приложений.

icon_info :

GtkIconInfo

raw_coordinates :

Должны ли координаты возвращаться в их оригинальной (не масштабируемой) форме.

Начиная с версии 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() для дальнейшей информации о координатной системе.

icon_info :

GtkIconInfo

rectangle :

GdkRectangle в которой сохраняются внутренние координаты прямоугольника, только когда функция возвращает TRUE.

Возвращает :

TRUE если значок имеет внедрённый прямоугольник

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


gtk_icon_info_get_attach_points ()

gboolean gtk_icon_info_get_attach_points (GtkIconInfo *icon_info, GdkPoint **points, gint *n_points);

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

icon_info :

GtkIconInfo

points :

Расположение для хранения указателя на массив точек, или NULL освобождающий массив точек с помощью g_free().

n_points :

Расположение сохраняющее число точек в points, или NULL

Возвращает :

TRUE если есть любые прикрепленные точки для значка.

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


gtk_icon_info_get_display_name ()

const gchar* gtk_icon_info_get_display_name (GtkIconInfo *icon_info);

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

icon_info :

GtkIconInfo

Возвращает :

Имя отображения для значка или NULL, если значок не имеет специального имени отображения. Этим значением владеет icon_info и оно не может быть изменено или освобождено.

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

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

Сигнал "changed"

void user_function (GtkIconTheme *icon_theme, gpointer user_data) : Run last

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

icon_theme :

Тема значков

user_data :

Пользовательские данные установленные когда подключен обработчик сигнала.