Класс QPen

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

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

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

Связанные нечлены

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

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

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

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

Различные настройки легко можно изменить, используя соответствующие функции 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) и стилем соединения bevel (Qt::BevelJoin).

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

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

Стиль пера

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

Просто используйте функцию 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, Пример рисования контуров и Пример рисования.

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

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.

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

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

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

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

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