Класс QPen

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

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

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

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

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

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

Перо имеет style(), width(), brush(), capStyle() и joinStyle().

Стиль пера определяет тип линии. Кисть используется для заполнения штрихов, созданных пером. Используйте класс 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().

QVariant 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!=().