Класс 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.

Создание классов, использующих 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 поддерживает значки высокой плотности пикселей DPI: через addFile() и fromTheme().

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

Использование 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()

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

[since 5.2] 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. Результат может быть меньше запрошенного, но никогда больше. Возвращаемый размер указан в устройствах-независимых пикселях (Это актуально для значков высокой плотности пикселей.)

См. также 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 в базовом имени), она автоматически загружается и добавляется с коэффициентом плотности пикселей устройства, установленным в значение 2. Это можно отключить, установив переменную среды QT_HIGHDPI_DISABLE_2X_IMAGE_LOADING (см. QImageReader).

См. также 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.

qint64 QIcon::cacheKey() const

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

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

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

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

[static, since 5.11] QStringList QIcon::fallbackSearchPaths()

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

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

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

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

[static, since 5.12] 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");

См. также 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.

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

[since 5.6] bool QIcon::isMask() const

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

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

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

bool QIcon::isNull() const

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

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

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

QString QIcon::name() const

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

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

См. также 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, генерируя её при необходимости. Пиксельная карта может быть меньше запрошенного размера, но никогда больше, если только коэффициент масштаба устройства возвращаемой пиксельной карты не больше 1.

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

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

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

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

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

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

Возвращает пиксельную карту размера QSize(extent, extent). Пиксельная карта может быть меньше запрошенного размера, но никогда больше, если только коэффициент масштаба устройства возвращаемой пиксельной карты не больше 1.

[since 6.0] QPixmap QIcon::pixmap(const QSize &size, qreal devicePixelRatio, QIcon::Mode mode = Normal, QIcon::State state = Off) const

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[since 5.6] void QIcon::setIsMask(bool isMask)

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

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

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

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

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

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

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

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

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

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

void QIcon::swap(QIcon &other)

Меняет местами иконку other с текущей иконкой. Данная операция очень быстрая и никогда не приводит к ошибке.

[static] QString QIcon::themeName()

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

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

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

[static] QStringList QIcon::themeSearchPaths()

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

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

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

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

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

QVariant QIcon::operator QVariant() const

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