Класс QIcon

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

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

Типы public

Функции public

Статические члены public

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

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

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

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

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

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

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()), пока нажата кнопка мыши в ожидании отпускания, которое активирует функцию, или когда это текущий выбранный элемент. Если виджет можно переключать, режим «Включено» может использоваться для рисования другой иконки.

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

Иконки высокой DPI

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

addFile() полезна, если у вас есть собственная структура каталогов и вам не нужно использовать Спецификацию темы иконок freedesktop.org. Иконки, созданные этим способом, используют синтаксис Qt для высокоразрешающих изображений «@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

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

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

enum QIcon::Mode

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

enum 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

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