Класс 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, являющийся 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(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!=().