Класс 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 сгенерирует её на лету. Эта генерация пикчи происходит в QIconEngineV2. По умолчанию движок масштабирует пикчи вниз, но никогда не вверх, и использует текущий стиль для расчета отключенного вида. Используя настраиваемые движки значков, вы можете настроить каждый аспект сгенерированных значков. С помощью QIconEnginePluginV2 можно регистрировать различные движки значков для различных расширений файлов, что позволяет сторонним разработчикам предоставлять дополнительные движки значков помимо тех, которые включены с 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 перед созданием значка.

См. также Справочник по проектированию графического интерфейса: значковая метка и Пример использования значков.

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

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

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

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

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

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

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

Эта функция была добавлена в 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 в базовом имени), она автоматически загружается и добавляется с коэффициентом масштабирования устройства, установленным в значение 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

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

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

qint64 QIcon::cacheKey() const

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

cacheKey() изменится, когда иконка будет изменена с помощью addPixmap() или addFile().

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

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

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

[static] QIcon QIcon::fromTheme(const QString &name, const QIcon &fallback = QIcon())

Возвращает QIcon, соответствующую name в текущей теме иконок. Если такая иконка не найдена в текущей теме, возвращается fallback вместо неё.

Самая последняя версия спецификации иконок 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");

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

    QIcon undoicon = QIcon::fromTheme("edit-undo", QIcon(":/undo.png"));

Примечание: По умолчанию, только X11 будет поддерживать темы иконок. Для использования тем иконок на Mac и Windows, вам нужно будет включить совместимую тему в один из themeSearchPaths() и установить соответствующее themeName().

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

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

[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, который поддерживает QIconEngineV2::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)

Указывает, что этот значок является изображением маски и, следовательно, может быть потенциально изменён в зависимости от места отображения.

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

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

void QIcon::setThemeName(const QString &name)

Устанавливает текущую тему значков на name.

name должен соответствовать имени каталога в themeSearchPath(), содержащему файл index.theme, описывающий его содержимое.

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

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

void QIcon::setThemeSearchPaths(const QStringList &paths)

Устанавливает пути поиска тем значков на paths.

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

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

void QIcon::swap(QIcon &other)

Меняет местами значок other с этим значком. Эта операция очень быстрая и никогда не завершается ошибкой.

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

QString QIcon::themeName()

Возвращает имя текущей темы значков.

В X11 текущая тема значков зависит от настроек вашего рабочего стола. На других платформах она по умолчанию не задаётся.

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

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

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.