Класс 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 использовать версию изображения высокой DPI, добавьте дополнительную запись в соответствующий 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-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 = Normal, QIcon::State state = Off) const

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

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

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

QPixmap QIcon::pixmap(int extent, QIcon::Mode mode = Normal, QIcon::State state = Off) 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, описывающий его содержимое.

Примечание: Это следует сделать до создания QGuiApplication, чтобы обеспечить правильную инициализацию.

Эта функция была добавлена в 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.