Класс 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 до создания значка.

Значки высокого разрешения

Существует два способа, которыми 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, Mode mode = Normal, State state = Off) const

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

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

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

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

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

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

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

void QIcon::addFile(const QString &fileName, const QSize &size = QSize(), Mode mode = Normal, State state = Off)

Добавляет изображение из файла с заданным именем fileName в значок в качестве специализации для size, mode и state. Файл загружается по требованию. Примечание: пользовательские движки значков могут игнорировать дополнительно добавленные пиксели.

Если 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, Mode mode = Normal, State state = Off)

Добавляет pixmap в значок в качестве специализации для mode и state.

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

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

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

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

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

qint64 QIcon::cacheKey() const

Возвращает число, которое идентифицирует содержимое этого объекта QIcon. Разные объекты QIcon могут иметь одинаковый ключ, если они ссылаются на одно и то же содержимое.

Ключ кэширования (cacheKey) изменяется при изменении значка с помощью addPixmap() или addFile().

Ключи кэширования в основном полезны в сочетании с кэшированием.

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

См. также QPixmap::cacheKey().

[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.

Данная функция была введена в Qt 4.6.

См. также themeName(), setThemeName(), и themeSearchPaths().

[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, Mode mode = Normal, 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, Mode mode = Normal, State state = Off) const

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

Отображает иконку в прямоугольник QRect(x, y, w, h).

QPixmap QIcon::pixmap(const QSize &size, Mode mode = Normal, State state = Off) const

Возвращает пиксельную карту с запрошенными size, mode и state, генерируя её при необходимости. Пиксельная карта может быть меньше, чем запрашивается, но никогда больше.

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

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

QPixmap QIcon::pixmap(int w, int h, Mode mode = Normal, State state = Off) const

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

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

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

QPixmap QIcon::pixmap(int extent, Mode mode = Normal, State state = Off) const

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

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

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

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

Возвращает пиксельную карту с запрошенными параметрами window, size, mode и state, генерируя её при необходимости.

Пиксельная карта может быть меньше запрошенного размера. Если window находится на дисплее с высокой плотностью пикселей, пиксельная карта может быть больше. В этом случае она будет иметь devicePixelRatio больше 1.

Данная функция была введена в Qt 5.1.

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

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.

Значение по умолчанию будет зависеть от платформы:

В X11 путь поиска будет использовать переменную среды XDG_DATA_DIRS, если она доступна.

По умолчанию для всех платформ каталог ресурсов :\icons будет использоваться в качестве резервного варианта. Вы можете использовать "rcc -project", чтобы сгенерировать файл ресурсов из вашей темы иконок.

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

QIcon::operator QVariant() const

Возвращает иконку как QVariant.

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

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

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

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

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