Класс QPen

Класс 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, представляющий собой QList, должен быть задан как четное число элементов типа qreal, где элементы 1, 3, 5... — это тире, а 2, 4, 6... — это пробелы. Например, пользовательский шаблон, показанный выше, создается с помощью следующего кода:

QPen pen;
QList<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.

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

[since 5.4] QPen::QPen(QPen &&pen)

Создаёт перо, перемещённое из данного pen.

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

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

QPen::QPen(const QPen &pen)

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

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 QColor &color)

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

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

QPen::QPen(Qt::PenStyle style)

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

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

QPen::QPen()

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

[since 5.2] QPen &QPen::operator=(QPen &&other)

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

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

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

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

QPen::~QPen()

Уничтожает перо.

QBrush QPen::brush() const

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

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

Qt::PenCapStyle QPen::capStyle() const

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

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

QColor QPen::color() const

Возвращает цвет кисти этого пера.

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

qreal QPen::dashOffset() const

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

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

QList<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 QList<qreal> &pattern)

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

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

QPen pen; QList<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)

Устанавливает предел скругления (miter 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 и это перо. Эта операция очень быстрая и никогда не терпит неудачу.

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

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

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

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