Функция CreatePen (wingdi.h)

Статья
08/27/2023

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

Синтаксис

HPEN CreatePen(
  [in] int      iStyle,
  [in] int      cWidth,
  [in] COLORREF color
);

Параметры

[in] iStyle

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

Значение	Значение
PS_SOLID	Ручка сплошная.
PS_DASH	Ручка пунктирная. Этот стиль действителен, только если ширина пера составляет один или меньше в единицах устройства.
PS_DOT	Ручка пунктирная. Этот стиль действителен, только если ширина пера составляет один или меньше в единицах устройства.
PS_DASHDOT	Перо имеет чередующиеся дефисы и точки. Этот стиль действителен, только если ширина пера составляет один или меньше в единицах устройства.
PS_DASHDOTDOT	Перо имеет чередующиеся дефисы и двойные точки. Этот стиль действителен, только если ширина пера составляет один или меньше в единицах устройства.
PS_NULL	Ручка невидимая.
PS_INSIDEFRAME	Ручка сплошная. При использовании этого пера в любой функции рисования GDI, которая принимает ограничивающий прямоугольник, размеры фигуры сужаются таким образом, что она полностью помещается в ограничивающий прямоугольник с учетом ширины пера. Это относится только к геометрическим ручкам.

[in] cWidth

Ширина пера в логических единицах. Если nWidth равно нулю, перо имеет ширину в один пиксель, независимо от текущего преобразования.

CreatePen возвращает перо с указанной шириной, но со стилем PS_SOLID, если указать ширину больше единицы для следующих стилей: PS_DASH, PS_DOT, PS_DASHDOT PS_DASHDOTDOT.

[in] color

Ссылка на цвет пера. Чтобы создать структуру COLORREF , используйте макрос RGB .

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

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

Если функция завершается сбоем, возвращается значение NULL.

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

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

Если значение, заданное параметром nWidth , больше 1, параметр fnPenStyle должен быть PS_NULL, PS_SOLID или PS_INSIDEFRAME.

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

Если значение, заданное параметром nWidth , больше 1, то fnPenStyle PS_INSIDEFRAME, а цвет, заданный параметром crColor , не соответствует ни одной из записей в логической палитре, система рисует линии с помощью помежевого цвета. Сплошные ручки недоступны для нитейных цветов.

При использовании параметра iStyle PS_DASH, PS_DOT, PS_DASHDOT или PS_DASHDOTDOT, чтобы сделать разрывы между дефисами или точками прозрачными, используйте SetBkMode , чтобы установить режим TRANSPARENT.

Если перо больше не требуется, вызовите функцию DeleteObject , чтобы удалить ее.

ICM: При создании не выполняется управление цветом. Однако управление цветом выполняется при выборе пера в контексте устройства с поддержкой ICM.

Примеры

Пример см. в разделе Создание цветных перьев и кистей.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	wingdi.h (включая Windows.h)
Библиотека	Gdi32.lib
DLL	Gdi32.dll