Класс 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().

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