Класс 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, Режим, Состояние), и ни одно пиксельное изображение для данного размера, режима и состояния не было добавлено с помощью 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

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

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

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

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

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

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

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

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.