Função CreatePen (wingdi.h)

Artigo
03/04/2024

A função CreatePen cria uma caneta lógica que tem o estilo, a largura e a cor especificados. A caneta pode ser selecionada posteriormente em um contexto de dispositivo e usada para desenhar linhas e curvas.

Sintaxe

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

Parâmetros

[in] iStyle

O estilo da caneta. Pode ser qualquer um dos valores a seguir.

Valor	Significado
PS_SOLID	A caneta é sólida.
PS_DASH	A caneta está tracejada. Esse estilo só é válido quando a largura da caneta é uma ou menos em unidades de dispositivo.
PS_DOT	A caneta está pontilhada. Esse estilo só é válido quando a largura da caneta é uma ou menos em unidades de dispositivo.
PS_DASHDOT	A caneta tem traços e pontos alternados. Esse estilo só é válido quando a largura da caneta é uma ou menos em unidades de dispositivo.
PS_DASHDOTDOT	A caneta tem traços alternados e pontos duplos. Esse estilo só é válido quando a largura da caneta é uma ou menos em unidades de dispositivo.
PS_NULL	A caneta é invisível.
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.

[in] cWidth

A largura da caneta, em unidades lógicas. Se nWidth for zero, a caneta será de um único pixel de largura, independentemente da transformação atual.

CreatePen retorna uma caneta com a largura especificada, mas com o estilo PS_SOLID se você especificar uma largura maior que uma para os seguintes estilos: PS_DASH, PS_DOT, PS_DASHDOT PS_DASHDOTDOT.

[in] color

Uma referência de cor para a cor da caneta. Para gerar uma estrutura COLORREF , use a macro RGB .

Retornar valor

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á NULL.

Comentários

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 o valor especificado pelo parâmetro nWidth for zero, uma linha desenhada com a caneta criada sempre terá um único pixel de largura, independentemente da transformação atual.

Se o valor especificado por nWidth for maior que 1, o parâmetro fnPenStyle deverá ser PS_NULL, PS_SOLID ou PS_INSIDEFRAME.

Se o valor especificado por nWidth for maior que 1 e fnPenStyle for PS_INSIDEFRAME, a linha associada à caneta será desenhada dentro do quadro de todos os primitivos, exceto polígonos e polilinha.

Se o valor especificado por nWidth for maior que 1, fnPenStyle será PS_INSIDEFRAME e a cor especificada pelo parâmetro crColor não corresponder a uma das entradas na paleta lógica, o sistema desenhará linhas usando uma cor dithered. As cores dithered não estão disponíveis com canetas sólidas.

Ao usar um parâmetro iStyle de PS_DASH, PS_DOT, PS_DASHDOT ou PS_DASHDOTDOT, para tornar transparentes as lacunas entre os traços ou pontos, use SetBkMode para definir o modo como TRANSPARENT.

Quando você não precisar mais da caneta, chame a função DeleteObject para excluí-la.

ICM: Nenhum gerenciamento de cores é feito na criação. 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 Criando canetas e pincéis coloridos.

Requisitos

Requisito	Valor
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