Función ExtCreatePen (wingdi.h)

Artículo
08/27/2023

La función ExtCreatePen crea un lápiz cosmético lógico o geométrico que tiene los atributos de estilo, ancho y pincel especificados.

Sintaxis

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

Parámetros

[in] iPenStyle

Combinación de atributos de tipo, estilo, extremo final y combinación. Los valores de cada categoría se combinan mediante el operador OR bit a bit ( | ).

El tipo de lápiz puede ser uno de los valores siguientes.

Valor	Significado
PS_GEOMETRIC	El lápiz es geométrico.
PS_COSMETIC	El lápiz es cosmético.

El estilo de lápiz puede ser uno de los valores siguientes.

Valor	Significado
PS_ALTERNATE	El lápiz establece cada otro píxel. (Este estilo solo es aplicable a los lápices cosméticos).
PS_SOLID	El lápiz es sólido.
PS_DASH	El lápiz está discontinuo.
PS_DOT	El lápiz está punteado.
PS_DASHDOT	El lápiz tiene guiones y puntos alternativos.
PS_DASHDOTDOT	El lápiz tiene guiones alternativos y puntos dobles.
PS_NULL	El lápiz es invisible.
PS_USERSTYLE	El lápiz usa una matriz de estilos proporcionada por el usuario.
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.

La tapa final solo se especifica para los lápices geométricos. El límite final puede ser uno de los siguientes valores.

Valor	Significado
PS_ENDCAP_ROUND	: los extremos son redondos.
PS_ENDCAP_SQUARE	: los extremos son cuadrados.
PS_ENDCAP_FLAT	: los extremos son planos.

La combinación solo se especifica para los lápices geométricos. La combinación puede ser uno de los valores siguientes.

Valor	Significado
PS_JOIN_BEVEL	: las uniones se biselan.
PS_JOIN_MITER	Las combinaciones se miteran cuando se encuentran dentro del límite actual establecido por la función SetMiterLimit . Si supera este límite, se biseliza la combinación.
PS_JOIN_ROUND	: las uniones son redondas.

[in] cWidth

Ancho del lápiz. Si el parámetro dwPenStyle es PS_GEOMETRIC, el ancho se asigna en unidades lógicas. Si dwPenStyle es PS_COSMETIC, el ancho debe establecerse en 1.

[in] plbrush

Puntero a una estructura LOGBRUSH . Si dwPenStyle es PS_COSMETIC, el miembro lbColor especifica el color del lápiz y el miembro lpStyle debe establecerse en BS_SOLID. Si dwPenStyle es PS_GEOMETRIC, todos los miembros deben usarse para especificar los atributos de pincel del lápiz.

[in] cStyle

Longitud, en unidades DWORD , de la matriz lpStyle . Este valor debe ser cero si dwPenStyle no es PS_USERSTYLE.

El número de estilos está limitado a 16.

[in] pstyle

Puntero a una matriz. El primer valor especifica la longitud del primer guión en un estilo definido por el usuario, el segundo valor especifica la longitud del primer espacio, etc. Este puntero debe ser NULL si dwPenStyle no es PS_USERSTYLE.

Si se supera la matriz lpStyle durante el dibujo de líneas, el puntero se restablece al principio de la matriz. Cuando esto sucede y dwStyleCount es un número par, el patrón de guiones y espacios se repite. Sin embargo, si dwStyleCount es impar, el patrón invierte cuando se restablece el puntero, el primer elemento de lpStyle ahora hace referencia a espacios, el segundo hace referencia a guiones, etc.

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 cero.

Comentarios

Un lápiz geométrico puede tener cualquier ancho y puede tener cualquiera de los atributos de un pincel, como los dithers y los patrones. Un lápiz cosmético solo puede ser un píxel ancho y debe ser un color sólido, pero los lápices cosméticos suelen ser más rápidos que los lápices geométricos.

El ancho de un lápiz geométrico siempre se especifica en unidades del mundo. El ancho de un lápiz cosmético siempre es 1.

Los extremos y las combinaciones solo se especifican para los lápices geométricos.

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 dwPenStyle es PS_COSMETIC y PS_USERSTYLE, las entradas de la matriz lpStyle especifican longitudes de guiones y espacios en unidades de estilo. El dispositivo define una unidad de estilo donde se usa el lápiz para dibujar una línea.

Si dwPenStyle es PS_GEOMETRIC y PS_USERSTYLE, las entradas de la matriz lpStyle especifican longitudes de guiones y espacios en unidades lógicas.

Si dwPenStyle es PS_ALTERNATE, se omite la unidad de estilo y se establece cada otro píxel.

Si el miembro lbStyle de la estructura LOGBRUSH a la que apunta lplb es BS_PATTERN, el mapa de bits al que apunta el miembro lbHatch de esa estructura no puede ser una sección DIB. Una sección DIB es un mapa de bits creado por CreateDIBSection. Si ese mapa de bits es una sección DIB, se produce un error en la función ExtCreatePen .

Cuando una aplicación ya no requiere un lápiz especificado, debe llamar a la función DeleteObject para eliminar el lápiz.

ICM: No se realiza ninguna administración de colores en la creación del lápiz. 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, consulte Uso de lápices.

Requisitos


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