Класс QPen

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

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

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

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

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

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

Для изменения стиля пера на любой из встроенных стилей, кроме Qt::CustomDashLine (к которому мы вернёмся чуть позже), используется функция setStyle(). Установка стиля 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 в пикселях с целочисленной точностью.

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

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

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

void QPen::setWidthF(qreal width)

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

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

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

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

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