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

Статья
08/27/2023

Функция ExtCreatePen создает логическое косметическое или геометрическое перо с указанными атрибутами стиля, ширины и кисти.

Синтаксис

HPEN ExtCreatePen(
  [in] DWORD          iPenStyle,
  [in] DWORD          cWidth,
  [in] const LOGBRUSH *plbrush,
  [in] DWORD          cStyle,
  [in] const DWORD    *pstyle
);

Параметры

[in] iPenStyle

Сочетание атрибутов type, style, end cap и join. Значения из каждой категории объединяются с помощью побитового оператора OR ( | ).

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

Значение	Значение
PS_GEOMETRIC	Перо геометрическое.
PS_COSMETIC	Ручка косметическая.

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

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

Конец задается только для геометрических перьев. Конечное ограничение может иметь одно из следующих значений.

Значение	Значение
PS_ENDCAP_ROUND	Концевая крышка круглая.
PS_ENDCAP_SQUARE	Конечные крышки квадратные.
PS_ENDCAP_FLAT	Концевая крышка плоская.

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

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

[in] cWidth

Ширина пера. Если параметр dwPenStyle имеет PS_GEOMETRIC, ширина задается в логических единицах. Если параметр dwPenStyle имеет PS_COSMETIC, ширина должна быть равна 1.

[in] plbrush

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

[in] cStyle

Длина массива lpStyle в единицах DWORD. Это значение должно быть равно нулю, если параметр dwPenStyle не является PS_USERSTYLE.

Количество стилей ограничено 16.

[in] pstyle

Указатель на массив. Первое значение указывает длину первого дефиса в пользовательском стиле, второе — длину первого пробела и т. д. Этот указатель должен иметь значение NULL , если dwPenStyle не является PS_USERSTYLE.

Если массив lpStyle превышен во время рисования линий, указатель сбрасывается в начало массива. Если это происходит и dwStyleCount является четным числом, шаблон дефисов и пробелов повторяется. Однако если dwStyleCount является нечетным, то при сбросе указателя шаблон будет меняться— первый элемент lpStyle теперь ссылается на пробелы, второй — на дефисы и т. д.

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

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

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

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

Ширина геометрического пера всегда указывается в единицах мира. Ширина косметической ручки всегда равна 1.

Конечные крышки и соединения указываются только для геометрических перьев.

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

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

Если параметр dwPenStyle PS_GEOMETRIC и PS_USERSTYLE, записи в массиве lpStyle указывают длину дефисов и пробелов в логических единицах.

Если параметр dwPenStyle PS_ALTERNATE, единица стиля игнорируется, а все остальные пиксели задаются.

Если элемент lbStyle структуры LOGBRUSH , на который указывает lplb , BS_PATTERN, то растровое изображение, на которое указывает элемент lbHatch этой структуры, не может быть разделом DIB. Раздел DIB — это растровое изображение, созданное createDIBSection. Если это растровое изображение является разделом DIB, функция ExtCreatePen завершается ошибкой .

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

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

Примеры

Пример см. в разделе Использование перьев.

Требования


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