Función CreatePen (wingdi.h)

Artículo
03/13/2024

La función CreatePen crea un lápiz lógico que tiene el estilo, el ancho y el color especificados. Posteriormente, el lápiz se puede seleccionar en un contexto de dispositivo y usarse para dibujar líneas y curvas.

Sintaxis

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

Parámetros

[in] iStyle

Estilo de lápiz. Puede ser cualquiera de los valores siguientes.

Valor	Significado
PS_SOLID	El lápiz es sólido.
PS_DASH	El lápiz está discontinuo. Este estilo solo es válido cuando el ancho del lápiz es uno o menos en unidades de dispositivo.
PS_DOT	El lápiz está punteado. Este estilo solo es válido cuando el ancho del lápiz es uno o menos en unidades de dispositivo.
PS_DASHDOT	El lápiz tiene guiones y puntos alternativos. Este estilo solo es válido cuando el ancho del lápiz es uno o menos en unidades de dispositivo.
PS_DASHDOTDOT	El lápiz tiene guiones alternativos y puntos dobles. Este estilo solo es válido cuando el ancho del lápiz es uno o menos en unidades de dispositivo.
PS_NULL	El lápiz es invisible.
PS_INSIDEFRAME	El lápiz es sólido. Cuando este lápiz se usa en cualquier función de dibujo GDI que toma un rectángulo delimitador, las dimensiones de la figura se reducen para que se ajuste completamente al rectángulo delimitador, teniendo en cuenta el ancho del lápiz. Esto solo se aplica a los lápices geométricos.

[in] cWidth

Ancho del lápiz, en unidades lógicas. Si nWidth es cero, el lápiz es un solo píxel ancho, independientemente de la transformación actual.

CreatePen devuelve un lápiz con el ancho especificado, pero con el estilo PS_SOLID si especifica un ancho mayor que uno para los siguientes estilos: PS_DASH, PS_DOT, PS_DASHDOT, PS_DASHDOTDOT.

[in] color

Referencia de color para el color del lápiz. Para generar una estructura COLORREF , use la macro RGB .

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es un identificador que identifica un lápiz lógico.

Si la función no se realiza correctamente, el valor devuelto es NULL.

Comentarios

Una vez que una aplicación crea un lápiz lógico, puede seleccionar ese lápiz en un contexto de dispositivo llamando a la función SelectObject . Después de seleccionar un lápiz en un contexto de dispositivo, se puede usar para dibujar líneas y curvas.

Si el valor especificado por el parámetro nWidth es cero, una línea dibujada con el lápiz creado siempre es un solo píxel ancho independientemente de la transformación actual.

Si el valor especificado por nWidth es mayor que 1, el parámetro fnPenStyle debe ser PS_NULL, PS_SOLID o PS_INSIDEFRAME.

Si el valor especificado por nWidth es mayor que 1 y fnPenStyle es PS_INSIDEFRAME, la línea asociada con el lápiz se dibuja dentro del marco de todos los primitivos excepto polígonos y polilíneas.

Si el valor especificado por nWidth es mayor que 1, fnPenStyle se PS_INSIDEFRAME y el color especificado por el parámetro crColor no coincide con una de las entradas de la paleta lógica, el sistema dibuja líneas mediante un color dithered. Los colores ditherados no están disponibles con lápices sólidos.

Cuando se usa un parámetro iStyle de PS_DASH, PS_DOT, PS_DASHDOT o PS_DASHDOTDOT, con el fin de que los guiones o puntos sean transparentes, use SetBkMode para establecer el modo en TRANSPARENT.

Cuando ya no necesite el lápiz, llame a la función DeleteObject para eliminarla.

ICM: No se realiza ninguna administración de colores durante la creación. Sin embargo, la administración de colores se realiza cuando el lápiz se selecciona en un contexto de dispositivo habilitado para ICM.

Ejemplos

Para obtener un ejemplo, vea Creating Colored Pens and Brushes.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	wingdi.h (incluye Windows.h)
Library	Gdi32.lib
Archivo DLL	Gdi32.dll