Função ExtCreatePen (wingdi.h)

Artigo
08/27/2023

A função ExtCreatePen cria uma caneta cosmética ou geométrica lógica que tem os atributos de estilo, largura e pincel especificados.

Sintaxe

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

Parâmetros

[in] iPenStyle

Uma combinação de atributos de tipo, estilo, limite final e junção. Os valores de cada categoria são combinados usando o operador OR bit a bit ( | ).

O tipo de caneta pode ser um dos valores a seguir.

Valor	Significado
PS_GEOMETRIC	A caneta é geométrica.
PS_COSMETIC	A caneta é cosmética.

O estilo da caneta pode ser um dos valores a seguir.

Valor	Significado
PS_ALTERNATE	A caneta define todos os outros pixels. (Esse estilo é aplicável somente a canetas cosméticas).
PS_SOLID	A caneta é sólida.
PS_DASH	A caneta está tracejada.
PS_DOT	A caneta está pontilhada.
PS_DASHDOT	A caneta tem traços e pontos alternados.
PS_DASHDOTDOT	A caneta tem traços alternados e pontos duplos.
PS_NULL	A caneta é invisível.
PS_USERSTYLE	A caneta usa uma matriz de estilo fornecida pelo usuário.
PS_INSIDEFRAME	A caneta é sólida. Quando essa caneta é usada em qualquer função de desenho GDI que usa um retângulo delimitador, as dimensões da figura são reduzidas para que ela se encaixe inteiramente no retângulo delimitador, levando em conta a largura da caneta. Isso se aplica somente a canetas geométricas.

A tampa final só é especificada para canetas geométricas. O limite final pode ser um dos valores a seguir.

Valor	Significado
PS_ENDCAP_ROUND	Os arremates de extremidade são redondos.
PS_ENDCAP_SQUARE	Os arremates de extremidade são quadrados.
PS_ENDCAP_FLAT	Os arremates de extremidade são planos.

A junção só é especificada para canetas geométricas. A junção pode ser um dos valores a seguir.

Valor	Significado
PS_JOIN_BEVEL	As junções são biseladas.
PS_JOIN_MITER	As junções são miteradas quando estão dentro do limite atual definido pela função SetMiterLimit . Se exceder esse limite, a junção será biselada.
PS_JOIN_ROUND	As junções são redondas.

[in] cWidth

A largura da caneta. Se o parâmetro dwPenStyle for PS_GEOMETRIC, a largura será fornecida em unidades lógicas. Se dwPenStyle for PS_COSMETIC, a largura deverá ser definida como 1.

[in] plbrush

Um ponteiro para uma estrutura LOGBRUSH . Se dwPenStyle for PS_COSMETIC, o membro lbColor especificará a cor da caneta e o membro lpStyle deverá ser definido como BS_SOLID. Se dwPenStyle for PS_GEOMETRIC, todos os membros deverão ser usados para especificar os atributos de pincel da caneta.

[in] cStyle

O comprimento, em unidades DWORD , da matriz lpStyle . Esse valor deverá ser zero se dwPenStyle não for PS_USERSTYLE.

A contagem de estilos é limitada a 16.

[in] pstyle

Um ponteiro para uma matriz. O primeiro valor especifica o comprimento do primeiro traço em um estilo definido pelo usuário, o segundo valor especifica o comprimento do primeiro espaço e assim por diante. Esse ponteiro deverá ser NULL se dwPenStyle não for PS_USERSTYLE.

Se a matriz lpStyle for excedida durante o desenho de linha, o ponteiro será redefinido para o início da matriz. Quando isso acontece e dwStyleCount é um número par, o padrão de traços e espaços se repete. No entanto, se dwStyleCount for ímpar, o padrão inverte quando o ponteiro é redefinido – o primeiro elemento de lpStyle agora se refere a espaços, o segundo se refere a traços e assim por diante.

Valor retornado

Se a função for bem-sucedida, o valor retornado será um identificador que identifica uma caneta lógica.

Se a função falhar, o valor retornado será zero.

Comentários

Uma caneta geométrica pode ter qualquer largura e pode ter qualquer um dos atributos de um pincel, como dithers e padrões. Uma caneta cosmética só pode ter um único pixel de largura e deve ser uma cor sólida, mas canetas cosméticas geralmente são mais rápidas que canetas geométricas.

A largura de uma caneta geométrica é sempre especificada em unidades mundiais. A largura de uma caneta cosmética é sempre 1.

As extremidades e junções são especificadas apenas para canetas geométricas.

Depois que um aplicativo cria uma caneta lógica, ele pode selecionar essa caneta em um contexto de dispositivo chamando a função SelectObject . Depois que uma caneta é selecionada em um contexto de dispositivo, ela pode ser usada para desenhar linhas e curvas.

Se dwPenStyle for PS_COSMETIC e PS_USERSTYLE, as entradas na matriz lpStyle especificarão comprimentos de traços e espaços em unidades de estilo. Uma unidade de estilo é definida pelo dispositivo em que a caneta é usada para desenhar uma linha.

Se dwPenStyle for PS_GEOMETRIC e PS_USERSTYLE, as entradas na matriz lpStyle especificarão comprimentos de traços e espaços em unidades lógicas.

Se dwPenStyle for PS_ALTERNATE, a unidade de estilo será ignorada e todos os outros pixels serão definidos.

Se o membro lbStyle da estrutura LOGBRUSH apontada por lplb for BS_PATTERN, o bitmap apontado pelo membro lbHatch dessa estrutura não poderá ser uma seção DIB. Uma seção DIB é um bitmap criado por CreateDIBSection. Se esse bitmap for uma seção DIB, a função ExtCreatePen falhará.

Quando um aplicativo não requer mais uma caneta especificada, ele deve chamar a função DeleteObject para excluir a caneta.

ICM: Nenhum gerenciamento de cores é feito na criação da caneta. No entanto, o gerenciamento de cores é executado quando a caneta é selecionada em um contexto de dispositivo habilitado para ICM.

Exemplos

Para obter um exemplo, consulte Usando canetas.

Requisitos


Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	wingdi.h (inclua Windows.h)
Biblioteca	Gdi32.lib
DLL	Gdi32.dll