Класс 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.

Значки с высокой 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()

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

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

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

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

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

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

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

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

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

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

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

См. также addFile().

QList<QSize> QIcon::availableSizes(QIcon::Mode mode = Normal, QIcon::State state = Off) const

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

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

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

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

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

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

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