Класс 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 поддерживает иконки высокой чёткости: через 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

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

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

перечисление 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().

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

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

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

Если существует версия изображения высокой чёткости (определяется суффиксом @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

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

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");

Примечание: По умолчанию только 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() как значок без темы.

См. также 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, описывающий его содержимое.

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

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