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

Устанавливает предел сглаживания для этой линии на заданное значение 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 в пикселях с целочисленной точностью.

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

Установка ширины линии с отрицательным значением не поддерживается.

См. также setWidthF() и width().

void QPen::setWidthF(qreal width)

Устанавливает ширину линии на заданное значение width в пикселях с плавающей точкой.

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

Установка ширины линии с отрицательным значением не поддерживается.

См. также 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!=().