Класс 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) и типом соединения bevel (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 , если перо имеет сплошную заливку, в противном случае — ложь.

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