Класс QIcon

Класс QIcon предоставляет масштабируемые значки в различных режимах и состояниях. Подробнее...

• Список всех членов, включая унаследованные
• Устаревшие члены

Открытые типы

Открытые функции

Статические открытые члены

Связанные внешние члены

Подробное описание

Объект QIcon может генерировать меньшие, большие, активные и неактивные пиксельные карты из заданного набора пиксельных карт. Такие пиксельные карты используются виджетами Qt для отображения значка, представляющего определенное действие.

Простейшее использование QIcon — это создание объекта из файла или ресурса QPixmap, а затем его использование, позволяющее Qt определить все необходимые стили и размеры значка. Например:

QToolButton *button = new QToolButton;
button->setIcon(QIcon("open.xpm"));

Чтобы отменить действие QIcon, просто установите нулевой значок на его место:

button->setIcon(QIcon());

Используйте функции QImageReader::supportedImageFormats() и QImageWriter::supportedImageFormats() для получения полного списка поддерживаемых форматов файлов.

Когда вы получаете пиксельную карту с помощью pixmap(QSize, Mode, State), и ни одна пиксельная карта для данного размера, режима и состояния не была добавлена с помощью addFile() или addPixmap(), то QIcon сгенерирует её на лету. Эта генерация пиксельной карты происходит в QIconEngine. Двигатель по умолчанию уменьшает масштаб пиксельных карт, если это необходимо, но никогда не увеличивает, и он использует текущий стиль для вычисления неактивного вида. Используя пользовательские механизмы значков, вы можете настроить каждый аспект сгенерированных значков. С помощью QIconEnginePlugin можно регистрировать различные механизмы значков для различных суффиксов файлов, что позволяет сторонним разработчикам предоставлять дополнительные механизмы значков к тем, которые включены в Qt.

Примечание: Начиная с Qt 4.2, включен механизм значков, который поддерживает SVG.

Создание классов, использующих QIcon

Если вы пишете собственные виджеты, у которых есть опция установки небольшого растрового изображения, рассмотрите возможность разрешения установки QIcon для этого растрового изображения. Класс Qt QToolButton является примером такого виджета.

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

void MyWidget::drawIcon(QPainter *painter, QPoint pos)
{
    QPixmap pixmap = icon.pixmap(QSize(22, 22),
                                   isEnabled() ? QIcon::Normal
                                               : QIcon::Disabled,
                                   isChecked() ? QIcon::On
                                               : QIcon::Off);
    painter->drawPixmap(pos, pixmap);
}

Вы также можете использовать режим Active , возможно, сделав свой виджет Active при наведении курсора на виджет (см. QWidget::enterEvent()), при нажатой кнопке мыши в ожидании отпускания, которое активирует функцию, или когда это текущий выбранный элемент. Если виджет может быть переключен, режим «Включено» может использоваться для отображения другого значка.

Примечание: QIcon требует экземпляра QGuiApplication перед созданием значка.

Значки с высокой DPI

Существует два способа, которыми QIcon поддерживает значки с высокой DPI: через addFile() и fromTheme().

addFile() полезно, если у вас есть собственная структура каталогов и вам не нужно использовать спецификацию темы значков freedesktop.org. Значки, созданные с помощью этого подхода, используют синтаксис Qt «@nx» высокой DPI для "высокоразрешающих версий изображений".

Использование fromTheme() необходимо, если вы планируете следовать спецификации темы значков. Чтобы QIcon использовал высокоразрешающую версию изображения, добавьте дополнительную запись в соответствующий index.theme файл:

[Icon Theme]
Name=Test
Comment=Test Theme

Directories=32x32/actions,32x32@2/actions

[32x32/actions]
Size=32
Context=Actions
Type=Fixed

# High DPI version of the entry above.
[32x32@2/actions]
Size=32
Scale=2
Type=Fixed

Структура каталога вашей темы значков будет выглядеть примерно так:

├── 32x32
│   └── actions
│       └── appointment-new.png
├── 32x32@2
│   └── actions
│       └── appointment-new.png
└── index.theme

См. также Справочник по разработке графического интерфейса пользователя: Значковая метка и Пример значков.

Документация типов членов

перечисление QIcon::Mode

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

перечисление QIcon::State

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

Документация функций-членов

QIcon::QIcon(QIconEngine *engine)

Создает значок с указанным движком значков engine. Значок принимает во владение движок.

QIcon::QIcon(const QString &fileName)

Конструирует значок из файла с заданным именем fileName. Файл будет загружен по требованию.

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

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

Используйте функции QImageReader::supportedImageFormats() и QImageWriter::supportedImageFormats() для получения полного списка поддерживаемых форматов файлов.

QIcon::QIcon(QIcon &&other)

Конструирует QIcon экземпляр, привязывая его к тому же объекту, на который ссылался other.

QIcon::QIcon(const QIcon &other)

Создает копию other. Это очень быстро.

QIcon::QIcon(const QPixmap &pixmap)

Создает значок из растрового изображения pixmap.

QIcon::QIcon()

Создает нулевой значок.

QIcon &QIcon::operator=(QIcon &&other)

Перемещающее присваивание other этому экземпляру QIcon.

Эта функция была добавлена в Qt 5.2.

QIcon &QIcon::operator=(const QIcon &other)

Присваивает значок other этому значку и возвращает ссылку на этот значок.

QIcon::~QIcon()

Удаляет значок.

QSize QIcon::actualSize(const QSize &size, QIcon::Mode mode = Normal, QIcon::State state = Off) const

Возвращает фактический размер значка для запрошенного размера size, режима mode и состояния state. Результат может быть меньше запрошенного, но никогда больше. Возвращаемый размер указан в независимых от устройства пикселях (это актуально для растровых изображений высокой DPI).

См. также pixmap() и paint().

QSize QIcon::actualSize(QWindow *window, const QSize &size, QIcon::Mode mode = Normal, QIcon::State state = Off) const

Возвращает фактический размер значка для запрошенного окна window, размера size, режима mode и состояния state.

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

Эта функция была добавлена в Qt 5.1.

См. также actualSize(), pixmap() и paint().

void QIcon::addFile(const QString &fileName, const QSize &size = QSize(), QIcon::Mode mode = Normal, QIcon::State state = Off)

Добавляет изображение из файла с заданным именем fileName в значок, как специализацию для размера size, режима mode и состояния state. Файл будет загружен по требованию. Примечание: пользовательские движки значков могут игнорировать дополнительные добавленные растровые образы.

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

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

Используйте функции QImageReader::supportedImageFormats() и QImageWriter::supportedImageFormats() для получения полного списка поддерживаемых форматов файлов.

Если существует высокоразрешающая версия изображения (определяемая суффиксом @2x в базовом имени), она автоматически загружается и добавляется с коэффициентом DPI устройства, установленным в значение 2. Это можно отключить, задав переменную окружения QT_HIGHDPI_DISABLE_2X_IMAGE_LOADING (см. QImageReader).

Примечание: Когда вы добавляете ненулевое имя файла в QIcon, значок становится ненулевым, даже если файла не существует или он содержит поврежденные данные.

См. также addPixmap() и QPixmap::devicePixelRatio().

void QIcon::addPixmap(const QPixmap &pixmap, QIcon::Mode mode = Normal, QIcon::State state = Off)

Добавляет pixmap в значок, как специализацию для mode и state.

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

См. также addFile().

QList<QSize> QIcon::availableSizes(QIcon::Mode mode = Normal, QIcon::State state = Off) const

Возвращает список доступных размеров значков для заданного режима mode и состояния state.

Эта функция была добавлена в Qt 4.5.

qint64 QIcon::cacheKey() const

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

Значение cacheKey() изменяется при изменении значка с помощью addPixmap() или addFile().

Ключи кэша в основном полезны в сочетании с кэшированием.

Функция была введена в Qt 4.3.

См. также QPixmap::cacheKey().

[static] QStringList QIcon::fallbackSearchPaths()

Возвращает пути поиска по умолчанию для значков.

Значение по умолчанию зависит от платформы.

Функция была введена в Qt 5.11.

См. также setFallbackSearchPaths() и themeSearchPaths().

[static] QString QIcon::fallbackThemeName()

Возвращает имя темы значков по умолчанию.

В X11, если не задано, тема значков по умолчанию зависит от настроек рабочего стола. На других платформах она по умолчанию не задана.

Функция была введена в Qt 5.12.

См. также setFallbackThemeName() и themeName().

[static] QIcon QIcon::fromTheme(const QString &name)

Возвращает QIcon, соответствующий name в текущей теме значков.

Самая последняя версия спецификации значков freedesktop и спецификации именования доступна здесь:

• http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html
• http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html

Чтобы получить значок из текущей темы значков:

    QIcon undoicon = QIcon::fromTheme("edit-undo");

Примечание: По умолчанию только X11 будет поддерживать значки тем. Для использования значков тем на Mac и Windows вам необходимо включить совместимую тему в один из themeSearchPaths() и установить соответствующее themeName().

Примечание: Qt будет использовать кэш gtk-icon-theme.cache, если он присутствует, для ускорения поиска. Эти кэши могут быть сгенерированы с помощью gtk-update-icon-cache: https://developer.gnome.org/gtk3/stable/gtk-update-icon-cache.html.

Примечание: Если значок не найден в текущей теме, он будет искаться в fallbackSearchPaths() как значок без темы.

Функция была введена в Qt 4.6.

См. также themeName(), setThemeName(), themeSearchPaths(), и fallbackSearchPaths().

[static] QIcon QIcon::fromTheme(const QString &name, const QIcon &fallback)

Это перегруженная функция.

Возвращает QIcon, соответствующий name в текущей теме значков. Если такой значок не найден в текущей теме, возвращается fallback.

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

    QIcon undoicon = QIcon::fromTheme("edit-undo", QIcon(":/undo.png"));

[static] bool QIcon::hasThemeIcon(const QString &name)

Возвращает true, если для name доступен значок в текущей теме значков, в противном случае возвращает false.

Функция была введена в Qt 4.6.

См. также themeSearchPaths(), fromTheme(), и setThemeName().

bool QIcon::isMask() const

Возвращает true, если этот значок помечен как масовое изображение. Некоторые платформы отображают значки-маски по-другому (например, значки меню в macOS).

Функция была введена в Qt 5.6.

См. также setIsMask().

bool QIcon::isNull() const

Возвращает true, если значок пуст; в противном случае возвращает false.

Значок пуст, если у него нет ни пиксельмапа, ни имени файла.

Примечание: даже непустой значок может не создавать допустимые пиксельмапы, например, если файл не существует или не может быть прочитан.

QString QIcon::name() const

Возвращает имя, использованное для создания значка, если оно доступно.

В зависимости от способа создания значка, у него может быть связанное имя. Это справедливо для значков, созданных с помощью fromTheme() или значков, использующих QIconEngine, который поддерживает QIconEngine::IconNameHook.

Функция была введена в Qt 4.7.

См. также fromTheme() и QIconEngine.

void QIcon::paint(QPainter *painter, const QRect &rect, Qt::Alignment alignment = Qt::AlignCenter, QIcon::Mode mode = Normal, QIcon::State state = Off) const

Использует painter для рисования значка с заданным alignment, необходимым mode и state в прямоугольник rect.

См. также actualSize() и pixmap().

void QIcon::paint(QPainter *painter, int x, int y, int w, int h, Qt::Alignment alignment = Qt::AlignCenter, QIcon::Mode mode = Normal, QIcon::State state = Off) const

Это перегруженная функция.

Рисует значок в прямоугольник QRect(x, y, w, h).

QPixmap QIcon::pixmap(const QSize &size, QIcon::Mode mode = Normal, QIcon::State state = Off) const

Возвращает пиксельмап с запрошенными size, mode и state, создавая его при необходимости. Пиксельмап может быть меньше, чем запрашивается, но никогда больше.

Установка атрибута приложения Qt::AA_UseHighDpiPixmaps позволяет этой функции возвращать пиксельмапы, которые больше, чем запрашивается. Такие изображения будут иметь devicePixelRatio больше 1.

См. также actualSize() и paint().

QPixmap QIcon::pixmap(int w, int h, QIcon::Mode mode = ..., QIcon::State state = ...) const

Это перегруженная функция.

Возвращает пиксельмап размера QSize(w, h). Пиксельмап может быть меньше, чем запрашивается, но никогда больше.

Установка атрибута приложения Qt::AA_UseHighDpiPixmaps позволяет этой функции возвращать пиксельмапы, которые больше, чем запрашивается. Такие изображения будут иметь devicePixelRatio больше 1.

QPixmap QIcon::pixmap(int extent, QIcon::Mode mode = ..., QIcon::State state = ...) const

Это перегруженная функция.

Возвращает пиксельмап размера QSize(extent, extent). Пиксельмап может быть меньше, чем запрашивается, но никогда больше.

Установка атрибута приложения Qt::AA_UseHighDpiPixmaps позволяет этой функции возвращать пиксельмапы, которые больше, чем запрашивается. Такие изображения будут иметь devicePixelRatio больше 1.

QPixmap QIcon::pixmap(QWindow *window, const QSize &size, QIcon::Mode mode = Normal, QIcon::State state = Off) const

Возвращает пиксельмап с запрошенным window, size, mode и state, создавая его при необходимости.

Пиксельмап может быть меньше, чем запрашиваемый размер. Если window находится на экране с высоким разрешением, пиксельмап может быть больше. В этом случае он будет иметь devicePixelRatio больше 1.

Функция была введена в Qt 5.1.

См. также actualSize() и paint().

[static] void QIcon::setFallbackSearchPaths(const QStringList &paths)

Устанавливает пути поиска по умолчанию для значков на paths.

Примечание: Чтобы добавить путь без замены существующих:

    QIcon::setFallbackSearchPaths(QIcon::fallbackSearchPaths() << "my/search/path");

Функция была введена в Qt 5.11.

См. также fallbackSearchPaths() и setThemeSearchPaths().

[static] void QIcon::setFallbackThemeName(const QString &name)

Устанавливает тему значка по умолчанию в name.

name должна соответствовать имени каталога в themeSearchPath(), содержащему файл index.theme, описывающий его содержимое.

Функция была добавлена в Qt 5.12.

См. также fallbackThemeName(), themeSearchPaths() и themeName().

void QIcon::setIsMask(bool isMask)

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

Функция была добавлена в Qt 5.6.

См. также isMask().

[static] void QIcon::setThemeName(const QString &name)

Устанавливает текущую тему значка в name.

name должна соответствовать имени каталога в themeSearchPath(), содержащему файл index.theme, описывающий его содержимое.

Функция была добавлена в Qt 4.6.

См. также themeSearchPaths() и themeName().

[static] void QIcon::setThemeSearchPaths(const QStringList &paths)

Устанавливает пути поиска тем значков в paths.

Функция была добавлена в Qt 4.6.

См. также themeSearchPaths(), fromTheme() и setThemeName().

void QIcon::swap(QIcon &other)

Меняет местами значки other и этот значок. Эта операция очень быстрая и никогда не приводит к ошибкам.

Функция была добавлена в Qt 4.8.

[static] QString QIcon::themeName()

Возвращает имя текущей темы значков.

В X11 текущая тема значков зависит от настроек вашего рабочего стола. На других платформах она не установлена по умолчанию.

Функция была добавлена в Qt 4.6.

См. также setThemeName(), themeSearchPaths(), fromTheme() и hasThemeIcon().

[static] QStringList QIcon::themeSearchPaths()

Возвращает пути поиска тем значков.

Значение по умолчанию зависит от платформы:

В X11 путь поиска использует переменную среды XDG_DATA_DIRS, если она доступна.

По умолчанию на всех платформах каталогом ресурсов :\icons будет служить резервным вариантом. Вы можете использовать "rcc -project", чтобы сгенерировать файл ресурсов из вашей темы значков.

Функция была добавлена в Qt 4.6.

См. также setThemeSearchPaths(), fromTheme() и setThemeName().

QVariant QIcon::operator QVariant() const

Возвращает значок как QVariant.