Класс `CPen`

Статья
10/12/2023

Инкапсулирует перо интерфейса графических устройств Windows (GDI).

Синтаксис

class CPen : public CGdiObject

Участники

Открытые конструкторы

Имя	Описание
`CPen::CPen`	Формирует объект `CPen`.

Открытые методы

Имя	Описание
`CPen::CreatePen`	Создает логическую косметику или геометрическое перо с указанным стилем, шириной и атрибутами кисти и присоединяет его к объекту `CPen` .
`CPen::CreatePenIndirect`	Создает перо со стилем, шириной и цветом `LOGPEN` , заданным в структуре, и присоединяет его к объекту `CPen` .
`CPen::FromHandle`	Возвращает указатель на `CPen` объект при указании Windows HPEN.
`CPen::GetExtLogPen`	Возвращает базовую структуру `EXTLOGPEN` .
`CPen::GetLogPen`	Возвращает базовую структуру `LOGPEN` .

Открытые операторы

Имя	Описание
`CPen::operator HPEN`	Возвращает дескриптор Windows, подключенный к объекту `CPen` .

Замечания

Дополнительные сведения об использовании CPenсм. в разделе "Графические объекты".

Иерархия наследования

CObject

CGdiObject

CPen

Требования

Заголовок.afxwin.h

`CPen::CPen`

Формирует объект CPen.

CPen();

CPen(
    int nPenStyle,
    int nWidth,
    COLORREF crColor);

CPen(
    int nPenStyle,
    int nWidth,
    const LOGBRUSH* pLogBrush,
    int nStyleCount = 0,
    const DWORD* lpStyle = NULL);

Параметры

nPenStyle
Задает стиль пера. Этот параметр в первой версии конструктора может быть одним из следующих значений:

PS_SOLID Создает сплошное перо.
PS_DASH Создает дефисное перо. Допустимо только в том случае, если ширина пера составляет 1 или меньше, в единицах устройства.
PS_DOT Создает пунктирное перо. Допустимо только в том случае, если ширина пера составляет 1 или меньше, в единицах устройства.
PS_DASHDOT Создает перо с чередующимися тире и точками. Допустимо только в том случае, если ширина пера составляет 1 или меньше, в единицах устройства.
PS_DASHDOTDOT Создает перо с чередующимися дефисами и двойными точками. Допустимо только в том случае, если ширина пера составляет 1 или меньше, в единицах устройства.
PS_NULL Создает пустое перо.
PS_INSIDEFRAMEСоздает перо, которое рисует линию внутри кадра закрытых фигур, созданных выходными функциями Windows GDI, которые указывают ограничивающий прямоугольник (например, Ellipseфункции элементов , , RectangleRoundRectи ChordPieт. д.). Если этот стиль используется с выходными функциями Windows GDI, которые не указывают ограничивающий прямоугольник (например, LineTo функция-член), область рисования пера не ограничивается кадром.

Вторая версия конструктора задает сочетание типов, стиля, конечной CPen крышки и атрибутов соединения. Значения из каждой категории должны объединяться с помощью побитового оператора "или" (|). Тип пера может быть одним из следующих значений:

PS_GEOMETRIC Создает геометрическое перо.
PS_COSMETIC Создает косметический перо.

Вторая версия конструктора CPen добавляет следующие стили пера для nPenStyle:
PS_ALTERNATE Создает перо, которое задает каждый другой пиксель. (Этот стиль применим только для косметических перьев.)
PS_USERSTYLE Создает перо, использующее массив стилизации, предоставленный пользователем.

Конечное ограничение может быть одним из следующих значений:
PS_ENDCAP_ROUND Конечные крышки округляются.
PS_ENDCAP_SQUARE Конечные крышки являются квадратными.
PS_ENDCAP_FLAT Конечные крышки плоские.

Соединение может быть одним из следующих значений:
PS_JOIN_BEVEL Соединения разложены.
PS_JOIN_MITER Соединения митерируются, когда они находятся в пределах текущего ограничения, заданного SetMiterLimit функцией. Если соединение превышает это ограничение, оно выстроено.
PS_JOIN_ROUND Соединения округляются.

nWidth
Задает ширину пера.

Для первой версии конструктора значение 0 будет обрабатываться аналогично значению 1, за исключением того, что ширина не будет влиять на операции преобразования масштабирования, действующие для объекта графики, для которых используется перо; Ширина всегда будет иметь 1 пиксель.
Для второй версии конструктора, если nPenStyle есть PS_GEOMETRIC, ширина будет указана в логических единицах. В противном nPenStylePS_COSMETICслучае ширина должна иметь значение 1.

crColor
Содержит цвет RGB для пера.

pLogBrush
Указывает на структуру LOGBRUSH . Если nPenStyle есть PS_COSMETIC, lbColor элемент LOGBRUSH структуры указывает цвет пера и lbStyle элемент LOGBRUSH структуры должен иметь значение BS_SOLID. Если nPenStyle есть PS_GEOMETRIC, все элементы должны использоваться для указания атрибутов кисти пера.

nStyleCount
Задает длину в единицах двойного слова массива lpStyle . Это значение должно быть равно нулю, если nPenStyle это не PS_USERSTYLEтак.

lpStyle
Указывает на массив значений doubleword. Первое значение указывает длину первого тире в пользовательском стиле, второе значение указывает длину первого пробела и т. д. Этот указатель должен быть NULL , если nPenStyle это не PS_USERSTYLEтак.

Замечания

Если конструктор используется без аргументов, необходимо инициализировать результирующий CPen объект с CreatePenCreatePenIndirectпомощью функций-членов или CreateStockObject функций-членов.

Если вы используете конструктор, который принимает аргументы, то дальнейшая инициализация не требуется. Конструктор с аргументами может вызвать исключение, если возникают ошибки, в то время как конструктор без аргументов всегда будет выполнен успешно.

Пример

// Create a solid red pen of width 2.
CPen myPen1(PS_SOLID, 2, RGB(255, 0, 0));

// Create a geometric pen.
LOGBRUSH logBrush;
logBrush.lbStyle = BS_SOLID;
logBrush.lbColor = RGB(0, 255, 0);
CPen myPen2(PS_DOT | PS_GEOMETRIC | PS_ENDCAP_ROUND, 2, &logBrush);

`CPen::CreatePen`

Создает логическую косметику или геометрическое перо с указанным стилем, шириной и атрибутами кисти и присоединяет его к объекту CPen .

BOOL CreatePen(
    int nPenStyle,
    int nWidth,
    COLORREF crColor);

BOOL CreatePen(
    int nPenStyle,
    int nWidth,
    const LOGBRUSH* pLogBrush,
    int nStyleCount = 0,
    const DWORD* lpStyle = NULL);

Параметры

nPenStyle
Задает стиль пера. Список возможных значений см nPenStyle . в конструкторе CPen .

nWidth
Задает ширину пера.

Для первой версии CreatePenзначение 0 будет обрабатываться аналогично значению 1, за исключением того, что ширина не будет влиять на операции преобразования масштабирования, которые применяются для графического объекта, используемого пером; ширина всегда будет 1 пиксель.
Для второй версии CreatePen, если nPenStyle имеется PS_GEOMETRIC, ширина указана в логических единицах. В противном nPenStylePS_COSMETICслучае ширина должна иметь значение 1.

crColor
Содержит цвет RGB для пера.

pLogBrush
Указывает на структуру LOGBRUSH . Если nPenStyle есть PS_COSMETIC, lbColor элемент LOGBRUSH структуры указывает цвет пера и lbStyle элемент LOGBRUSH структуры должен иметь значение BS_SOLID. Если nPenStyle есть PS_GEOMETRIC, все элементы должны использоваться для указания атрибутов кисти пера.

Возвращаемое значение

Если метод выполнен успешно, или ноль, если метод завершается ошибкой.

Замечания

Первая версия инициализирует CreatePen перо с указанным стилем, шириной и цветом. Затем перо можно выбрать в качестве текущего пера для любого контекста устройства.

Пера, имеющие ширину больше 1 пикселя, всегда должны иметь PS_NULLлибо стиль, PS_SOLIDPS_INSIDEFRAME либо стиль.

Если перо имеет PS_INSIDEFRAME стиль и цвет, который не соответствует цвету в логической таблице цветов, перо рисуется с тронутыми цветами. Стиль PS_SOLID пера нельзя использовать для создания пера с тротым цветом. Стиль PS_INSIDEFRAME идентичен PS_SOLID , если ширина пера меньше или равна 1.

Вторая версия инициализирует CreatePen логическую косметику или геометрическое перо, которое имеет указанный стиль, ширину и атрибуты кисти. Ширина косметического пера всегда равна 1; Ширина геометрического пера всегда указывается в единицах мира. После создания логического пера приложение может выбрать его в контекст устройства, вызвав функцию CDC::SelectObject . После выбора пера в контексте устройства его можно использовать для рисования линий и кривых.

Если nPenStyle есть PS_COSMETIC и PS_USERSTYLE, записи в массиве lpStyle указывают длину дефисов и пробелов в единицах стиля. Единица стиля определяется устройством, в котором перо используется для рисования линии.
Если nPenStyle есть PS_GEOMETRIC и PS_USERSTYLE, записи в массиве lpStyle указывают длину дефисов и пробелов в логических единицах.
Если nPenStyle это PS_ALTERNATEтак, единица стиля игнорируется и задается каждый другой пиксель.

Если приложению больше не требуется заданное перо, он должен вызывать CGdiObject::DeleteObject функцию-член или уничтожать CPen объект, чтобы ресурс больше не использовался. Приложение не должно удалять перо при выборе пера в контексте устройства.

Пример

CPen myPen1, myPen2;

// Create a solid red pen of width 2.
myPen1.CreatePen(PS_SOLID, 2, RGB(255, 0, 0));

// Create a geometric pen.
LOGBRUSH logBrush;
logBrush.lbStyle = BS_SOLID;
logBrush.lbColor = RGB(0, 255, 0);
myPen2.CreatePen(PS_DOT | PS_GEOMETRIC | PS_ENDCAP_ROUND, 2, &logBrush);

`CPen::CreatePenIndirect`

Инициализирует перо, которое имеет стиль, ширину и цвет, заданный в структуре, lpLogPenна которую указывает.

BOOL CreatePenIndirect(LPLOGPEN lpLogPen);

Параметры

lpLogPen
Указывает на структуру Windows LOGPEN , содержащую сведения о пере.

Возвращаемое значение

Ненулевое значение, если функция выполнена успешно; в противном случае — 0.

Замечания

Пера, имеющие ширину больше 1 пикселя, всегда должны иметь PS_NULLлибо стиль, PS_SOLIDPS_INSIDEFRAME либо стиль.

Если перо имеет PS_INSIDEFRAME стиль и цвет, который не соответствует цвету в логической таблице цветов, перо рисуется с тронутыми цветами. Стиль PS_INSIDEFRAME идентичен PS_SOLID , если ширина пера меньше или равна 1.

Пример

LOGPEN logpen;
CPen   cMyPen;

// Get the LOGPEN of an existing pen.
penExisting.GetLogPen(&logpen);

// Change the color to red and the width to 2.
logpen.lopnWidth.x = 2;
logpen.lopnColor = RGB(255, 0, 0);

// Create my pen using the new settings.
cMyPen.CreatePenIndirect(&logpen);

`CPen::FromHandle`

Возвращает указатель на CPen объект, заданный дескриптором пера Windows GDI.

static CPen* PASCAL FromHandle(HPEN hPen);

Параметры

hPen
HPEN дескриптор пера GDI Для Windows.

Возвращаемое значение

Указатель на объект в случае успешного CPen выполнения; в противном случае NULL.

Замечания

CPen Если объект не присоединен к дескриптору, создается и присоединяется временный CPen объект. Этот временный объект действителен только в следующий раз, когда приложение имеет время простоя CPen в цикле событий, в то время как все временные графические объекты удаляются. Другими словами, временный объект действителен только во время обработки одного сообщения окна.

Пример

// Convert an HPEN to a CPen*.
// NOTE: hPen is a valid pen handle.
CPen* pPen = CPen::FromHandle(hPen);

`CPen::GetExtLogPen`

Возвращает базовую структуру EXTLOGPEN .

int GetExtLogPen(EXTLOGPEN* pLogPen);

Параметры

pLogPen
Указывает на структуру EXTLOGPEN , содержащую сведения о пере.

Возвращаемое значение

Имеет ненулевое значение в случае успешного выполнения, иначе — 0.

Замечания

Структура EXTLOGPEN определяет стиль, ширину и атрибуты кисти пера. Например, вызов GetExtLogPen для сопоставления определенного стиля пера.

Дополнительные сведения об атрибутах пера см. в следующих разделах пакета SDK для Windows.

Пример

В следующем примере кода показано, как получить GetExtLogPen атрибуты пера, а затем создать новый косметический перо с тем же цветом.

EXTLOGPEN extlogpen;
penExisting.GetExtLogPen(&extlogpen);
CPen penOther;
LOGBRUSH LogBrush = { extlogpen.elpBrushStyle, extlogpen.elpColor,
   extlogpen.elpHatch };
penOther.CreatePen(PS_COSMETIC, 1, &LogBrush);

`CPen::GetLogPen`

Возвращает базовую структуру LOGPEN .

int GetLogPen(LOGPEN* pLogPen);

Параметры

pLogPen
Указывает на LOGPEN структуру, содержащую сведения о перо.

Возвращаемое значение

Имеет ненулевое значение в случае успешного выполнения, иначе — 0.

Замечания

Структура LOGPEN определяет стиль, цвет и шаблон пера.

Например, вызов GetLogPen для сопоставления определенного стиля пера.

Дополнительные сведения об атрибутах пера см. в следующих разделах пакета SDK для Windows.

Пример

В следующем примере кода показано, как получить GetLogPen символ пера, а затем создать новое сплошное перо с одинаковым цветом.

LOGPEN logpen;
penExisting.GetLogPen(&logpen);
CPen penOther(PS_SOLID, 0, logpen.lopnColor);

`CPen::operator HPEN`

Возвращает присоединенный дескриптор CPen GDI Windows объекта.

operator HPEN() const;

Возвращаемое значение

В случае успешного выполнения дескриптор объекта GDI Windows, представленного CPen объектом; в противном случае NULL.

Замечания

Этот оператор является оператором приведения, который поддерживает прямое использование HPEN объекта.

Дополнительные сведения об использовании графических объектов см. в статье "Графические объекты " в пакете SDK для Windows.

Пример

// Create a solid red pen of width 2.
CPen myPen(PS_SOLID, 2, RGB(255, 0, 0));

// Get the handle of the pen object.
HPEN hPen = (HPEN)myPen;

См. также

CGdiObject Класса
Диаграмма иерархии
CBrush Класса

Класс CPen

Синтаксис

Участники

Открытые конструкторы

Открытые методы

Открытые операторы

Замечания

Иерархия наследования

Требования

CPen::CPen

Параметры

Замечания

Пример

CPen::CreatePen

Параметры

Возвращаемое значение

Замечания

Пример

CPen::CreatePenIndirect

Параметры

Возвращаемое значение

Замечания

Пример

CPen::FromHandle

Параметры

Возвращаемое значение

Замечания

Пример

CPen::GetExtLogPen

Параметры

Возвращаемое значение

Замечания

Пример

CPen::GetLogPen

Параметры

Возвращаемое значение

Замечания

Пример

CPen::operator HPEN

Возвращаемое значение

Замечания

Пример

См. также

Обратная связь

Обратная связь

Дополнительные ресурсы

Класс `CPen`

`CPen::CPen`

`CPen::CreatePen`

`CPen::CreatePenIndirect`

`CPen::FromHandle`

`CPen::GetExtLogPen`

`CPen::GetLogPen`

`CPen::operator HPEN`