Класс QPen

Класс QPen определяет, как QPainter должен рисовать линии и контуры фигур. Подробнее...

• Список всех членов, включая наследуемые

Открытые функции

Связанные внешние функции

Подробное описание

Класс QPen определяет, как QPainter должен рисовать линии и контуры фигур.

У пера есть стиль(), ширина(), кисть(), стиль окончания() и стиль соединения().

Стиль пера определяет тип линии. Кисть используется для заполнения штрихов, созданных пером. Используйте класс QBrush для указания стилей заполнения. Стиль окончания определяет окончания линий, которые могут быть нарисованы с помощью QPainter, в то время как стиль соединения описывает, как рисуются соединения между двумя линиями. Ширина пера может быть указана как в целых (width()), так и в числах с плавающей точкой (widthF()). Ширина линии равна нулю означает декоративное перо. Это означает, что ширина пера всегда рисуется шириной в один пиксель, независимо от преобразования, заданного в рисовальщике.

Различные настройки легко изменяются с помощью соответствующих функций setStyle(), setWidth(), setBrush(), setCapStyle() и setJoinStyle() (обратите внимание, что перо рисовальщика необходимо сбросить при изменении свойств пера).

Например:

QPainter painter(this);
QPen pen(Qt::green, 3, Qt::DashDotLine, Qt::RoundCap, Qt::RoundJoin);
painter.setPen(pen);

что эквивалентно

QPainter painter(this);
QPen pen;  // creates a default pen

pen.setStyle(Qt::DashDotLine);
pen.setWidth(3);
pen.setBrush(Qt::green);
pen.setCapStyle(Qt::RoundCap);
pen.setJoinStyle(Qt::RoundJoin);

painter.setPen(pen);

Перо по умолчанию — это сплошная черная кисть шириной 1, со стилем окончания Qt::SquareCap и стилем соединения Qt::BevelJoin.

Кроме того, QPen предоставляет удобные функции color() и setColor() для извлечения и установки цвета кисти пера соответственно. Перья также могут быть сравниваемы и передаваемы в поток.

Дополнительную информацию об отрисовке в целом см. в документации Системы отрисовки.

Стиль пера

Qt предоставляет несколько встроенных стилей, представленных перечислением Qt::PenStyle:

Qt::SolidLine	Qt::DashLine	Qt::DotLine
Qt::DashDotLine	Qt::DashDotDotLine	Qt::CustomDashLine

Просто используйте функцию setStyle(), чтобы преобразовать стиль пера в любой из встроенных стилей, за исключением стиля Qt::CustomDashLine, к которому мы вернёмся чуть позже. Установка стиля в Qt::NoPen сообщает рисовальщику не рисовать линии или контуры. По умолчанию стиль пера — Qt::SolidLine.

Начиная с Qt 4.1, также можно указать пользовательский шаблон пунктира с помощью функции setDashPattern(), которая неявно преобразует стиль пера в Qt::CustomDashLine. Аргумент pattern, являющийся QVector, должен быть указан как чётное число элементов qreal, где элементы 1, 3, 5... — это штрихи, а элементы 2, 4, 6... — это пробелы. Например, пользовательский шаблон, показанный выше, создаётся с помощью следующего кода:

QPen pen;
QVector<qreal> dashes;
qreal space = 4;

dashes << 1 << space << 3 << space << 9 << space
           << 27 << space << 9 << space;

pen.setDashPattern(dashes);

Обратите внимание, что шаблон пунктира указывается в единицах ширины пера, например, штрих длиной 5 при ширине 10 составляет 50 пикселей.

Текущую схему штриховки можно получить, используя функцию dashPattern(). Используйте функцию isSolid(), чтобы определить, имеет ли ручка сплошную заливку или нет.

Стиль наконечника

Стиль наконечника определяет, как отображаются конечные точки линий с помощью QPainter. Стиль наконечника применяется только к широким линиям, т. е. когда ширина составляет 1 или больше. Перечисление Qt::PenCapStyle предоставляет следующие стили:

Qt::SquareCap	Qt::FlatCap	Qt::RoundCap

Стиль Qt::SquareCap представляет собой квадратный конец линии, который покрывает конечную точку и простирается за неё на половину ширины линии. Стиль Qt::FlatCap представляет собой квадратный конец линии, который не покрывает конечную точку линии. А стиль Qt::RoundCap представляет собой закруглённый конец линии, покрывающий конечную точку.

По умолчанию используется Qt::SquareCap.

Отображаются ли конечные точки, когда ширина ручки равна 0 или 1, зависит от стиля наконечника. При использовании Qt::SquareCap или Qt::RoundCap они отображаются, при использовании Qt::FlatCap они не отображаются.

Стиль соединения

Стиль соединения определяет, как могут быть нарисованы соединения между двумя соединёнными линиями с помощью QPainter. Стиль соединения применяется только к широким линиям, т. е. когда ширина составляет 1 или больше. Перечисление Qt::PenJoinStyle предоставляет следующие стили:

Qt::BevelJoin	Qt::MiterJoin	Qt::RoundJoin

Стиль Qt::BevelJoin заполняет треугольный вырез между двумя линиями. Стиль Qt::MiterJoin продлевает линии до пересечения под углом. А стиль Qt::RoundJoin заполняет дугу окружности между двумя линиями.

По умолчанию используется Qt::BevelJoin.

При применении стиля Qt::MiterJoin, можно использовать функцию setMiterLimit(), чтобы указать, насколько далеко соединение митр может простираться от точки соединения. miterLimit() используется для уменьшения артефактов между соединениями линий, где линии близки к параллельным.

Значение miterLimit() должно быть указано в единицах ширины ручки, например, предел митр 5 при ширине 10 — это 50 пикселей в длину. По умолчанию предел митр равен 2, т. е. вдвое больше ширины ручки в пикселях.

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

См. также QPainter, QBrush, Пример рисования по траекториям и Пример Scribble.

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

QPen::QPen()

Создаёт ручку по умолчанию — чёрную сплошную линию шириной 1.

QPen::QPen(Qt::PenStyle style)

Создаёт черную ручку шириной 1 и заданным стилем style.

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

QPen::QPen(const QColor &color)

Создаёт ручку сплошной линии шириной 1 и заданным цветом color.

См. также setBrush() и setColor().

QPen::QPen(const QBrush &brush, qreal width, Qt::PenStyle style = Qt::SolidLine, Qt::PenCapStyle cap = Qt::SquareCap, Qt::PenJoinStyle join = Qt::BevelJoin)

Создаёт ручку с заданной brush, width, стилем линии style, стилем наконечника cap и стилем соединения join.

См. также setBrush(), setWidth(), setStyle(), setCapStyle() и setJoinStyle().

QPen::QPen(const QPen &pen)

Создаёт ручку, являющуюся копией заданной pen.

QPen::QPen(QPen &&pen)

Создаёт ручку, перемещаемую из заданной pen.

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

Эта функция была представлена в Qt 5.4.

QPen::~QPen()

Уничтожает ручку.

QBrush QPen::brush() const

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

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

Qt::PenCapStyle QPen::capStyle() const

Возвращает стиль наконечника ручки.

См. также setCapStyle() и Стиль наконечника.

QColor QPen::color() const

Возвращает цвет кисти этой ручки.

См. также brush() и setColor().

qreal QPen::dashOffset() const

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

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

QVector<qreal> QPen::dashPattern() const

Возвращает схему штриховки этой ручки.

См. также setDashPattern(), style() и isSolid().

bool QPen::isCosmetic() const

Возвращает true если ручка косметическая; в противном случае возвращает false.

Косметические ручки используются для рисования штрихов, которые имеют постоянную ширину независимо от каких-либо преобразований, применённых к QPainter, с которыми они используются. Рисование фигуры с косметической ручкой гарантирует, что её контур будет иметь одинаковую толщину при различных коэффициентах масштабирования.

Ручка нулевой ширины по умолчанию является косметической.

См. также setCosmetic() и widthF().

bool QPen::isSolid() const

Возвращает true если ручка имеет сплошную заливку, в противном случае возвращает false.

См. также style() и dashPattern().

Qt::PenJoinStyle QPen::joinStyle() const

Возвращает стиль соединения ручки.

См. также setJoinStyle() и Стиль соединения.

qreal QPen::miterLimit() const

Возвращает предел митр ручки. Предел митр имеет значение только в том случае, если стиль соединения задан как Qt::MiterJoin.

См. также setMiterLimit() и Стиль соединения.

void QPen::setBrush(const QBrush &brush)

Устанавливает кисть, используемую для заполнения штрихов, созданных с помощью этой ручки, на заданную brush.

См. также brush() и setColor().

void QPen::setCapStyle(Qt::PenCapStyle style)

Устанавливает стиль наконечника ручки на заданный style. Значение по умолчанию — Qt::SquareCap.

См. также capStyle() и Стиль наконечника.

void QPen::setColor(const QColor &color)

Устанавливает цвет кисти этой ручки на заданный color.

См. также setBrush() и color().

void QPen::setCosmetic(bool cosmetic)

Устанавливает ручку как косметическую или некосметическую в зависимости от значения cosmetic.

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

void QPen::setDashOffset(qreal offset)

Устанавливает смещение штриховки (начальную точку на схеме штриховки) для этой ручки на заданное offset. Смещение измеряется в единицах, используемых для указания схемы штриховки.

Например, шаблон, где каждый штрих имеет длину четыре единицы, а зазор — две единицы, начнётся со штриха при отрисовке в виде линии. Однако, если смещение пунктира установлено в 4.0, любая отрисованная линия начнётся с зазора. Значения смещения до 4.0 приведут к тому, что часть штриха будет нарисована первой, а значения смещения между 4.0 и 6.0 приведут к тому, что линия начнётся с части зазора.

Примечание: Это неявно преобразует стиль пера в Qt::CustomDashLine.

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

void QPen::setDashPattern(const QVector<qreal> &pattern)

Устанавливает шаблон пунктира для этого пера на заданный pattern. Это неявно преобразует стиль пера в Qt::CustomDashLine.

Шаблон должен быть задан как чётное число положительных значений, где значения 1, 3, 5... — это штрихи, а 2, 4, 6... — это пробелы. Например:

QPen pen; QVector<qreal> dashes; qreal space = 4; dashes << 1 << space << 3 << space << 9 << space << 27 << space << 9 << space; pen.setDashPattern(dashes);

Шаблон пунктира задаётся в единицах ширины пера; например, штрих длиной 5 при ширине 10 имеет длину 50 пикселей. Обратите внимание, что перо с нулевой шириной эквивалентно косметическому перу с шириной 1 пиксель.

Каждый штрих также подвержен стилям обрезки, поэтому штрих длиной 1 с квадратной обрезкой будет расширяться на 0,5 пикселя в каждом направлении, что приведёт к общей ширине 2.

Обратите внимание, что стиль обрезки по умолчанию — Qt::SquareCap, что означает, что квадратный конец линии покрывает конечную точку и выходит за неё на половину ширины линии.

См. также setStyle(), dashPattern(), setCapStyle() и setCosmetic().

void QPen::setJoinStyle(Qt::PenJoinStyle style)

Устанавливает стиль соединения пера на заданный style. Значение по умолчанию — Qt::BevelJoin.

См. также joinStyle() и Стиль соединения.

void QPen::setMiterLimit(qreal limit)

Устанавливает предел среза этого пера на заданный limit.

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

Это значение имеет эффект только при установке стиля пера в Qt::MiterJoin. Значение указывается в единицах ширины пера, например, предел среза 5 при ширине 10 составляет 50 пикселей. Предел среза по умолчанию — 2, то есть в два раза больше ширины пера в пикселях.

См. также miterLimit(), setJoinStyle() и Стиль соединения.

void QPen::setStyle(Qt::PenStyle style)

Устанавливает стиль пера на заданный style.

Список доступных стилей см. в документации Qt::PenStyle. С Qt 4.1 также можно задавать пользовательские шаблоны пунктира с помощью функции setDashPattern(), которая неявно преобразует стиль пера в Qt::CustomDashLine.

Примечание: Эта функция сбрасывает смещение пунктира до нуля.

См. также style() и Стиль пера.

void QPen::setWidth(int width)

Устанавливает ширину пера на заданное значение width в пикселях с целочисленной точностью.

Ширина линии, равная нулю, указывает на косметическое перо. Это означает, что ширина пера всегда рисуется шириной в один пиксель, независимо от преобразования, установленного в рисовальщике.

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

См. также setWidthF() и width().

void QPen::setWidthF(qreal width)

Устанавливает ширину пера на заданное значение width в пикселях с плавающей точкой.

Ширина линии, равная нулю, указывает на косметическое перо. Это означает, что ширина пера всегда рисуется шириной в один пиксель, независимо от преобразования в рисовальщике.

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

См. также setWidth() и widthF().

Qt::PenStyle QPen::style() const

Возвращает стиль пера.

См. также setStyle() и Стиль пера.

void QPen::swap(QPen &other)

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

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

int QPen::width() const

Возвращает ширину пера с целочисленной точностью.

См. также setWidth() и widthF().

qreal QPen::widthF() const

Возвращает ширину пера с плавающей точкой.

См. также setWidthF() и width().

QPen::operator QVariant() const

Возвращает перо как QVariant.

bool QPen::operator!=(const QPen &pen) const

Возвращает true если перо отличается от заданного pen; в противном случае — false. Два пера отличаются, если они имеют разные стили, ширины или цвета.

См. также operator==().

QPen &QPen::operator=(const QPen &pen)

Присваивает заданное pen этому перу и возвращает ссылку на это перо.

QPen &QPen::operator=(QPen &&other)

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

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

bool QPen::operator==(const QPen &pen) const

Возвращает true если перо равно заданному pen; в противном случае — false. Два пера равны, если они имеют одинаковые стили, ширины и цвета.

См. также operator!=().