Класс QIcon

Класс 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 перед созданием значка.

Значки с высоким разрешением

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

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

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

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

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

enum QIcon::Mode

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

enum QIcon::State

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

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

QIcon::QIcon()

Создает пустой значок.

QIcon::QIcon(const QPixmap &pixmap)

Создает значок из pixmap.

QIcon::QIcon(const QIcon &other)

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

QIcon::QIcon(QIcon &&other)

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

QIcon::QIcon(const QString &fileName)

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

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

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

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

QIcon::QIcon(QIconEngine *engine)

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

QIcon::~QIcon()

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

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

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

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

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

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

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

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

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.

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

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

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

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

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