Compartir a través de

Clase CPen

  • Artículo

Encapsula un lápiz de la Interfaz de dispositivo gráfico (GDI) de Windows.

Sintaxis

class CPen : public CGdiObject

Miembros

Constructores públicos

Nombre Descripción
CPen::CPen Construye un objeto CPen.

Métodos públicos

Nombre Descripción
CPen::CreatePen Crea un lápiz cosmético o geométrico lógico con los atributos de estilo, ancho y pincel especificados y lo asocia al objeto CPen.
CPen::CreatePenIndirect Crea un lápiz con el estilo, el ancho y el color especificados en una estructura LOGPEN y lo asocia al objeto CPen.
CPen::FromHandle Devuelve un puntero a un objeto CPen cuando se especifica un HPEN de Windows.
CPen::GetExtLogPen Obtiene una estructura subyacente EXTLOGPEN.
CPen::GetLogPen Obtiene una estructura subyacente LOGPEN.

Operadores públicos

Nombre Descripción
CPen::operator HPEN Devuelve el controlador de Windows asociado al objeto CPen.

Comentarios

Para obtener más información sobre el uso de la clase CPen, consulte Objetos gráficos.

Jerarquía de herencia

CObject

CGdiObject

CPen

Requisitos

Encabezado: afxwin.h

CPen::CPen

Construye un objeto CPen.

CPen();

CPen(
    int nPenStyle,
    int nWidth,
    COLORREF crColor);

CPen(
    int nPenStyle,
    int nWidth,
    const LOGBRUSH* pLogBrush,
    int nStyleCount = 0,
    const DWORD* lpStyle = NULL);

Parámetros

nPenStyle
Especifica el estilo de lápiz. Este parámetro de la primera versión del constructor puede ser uno de los siguientes valores:

  • PS_SOLID crea un lápiz liso.

  • PS_DASH crea un lápiz discontinuo. Solo es válido cuando el ancho del lápiz es de 1 o menos en las unidades del dispositivo.

  • PS_DOT crea un lápiz punteado. Solo es válido cuando el ancho del lápiz es de 1 o menos en las unidades del dispositivo.

  • PS_DASHDOT crea un lápiz con guiones y puntos que se alternan. Solo es válido cuando el ancho del lápiz es de 1 o menos en las unidades del dispositivo.

  • PS_DASHDOTDOT crea un lápiz con guiones y dobles puntos que se alternan. Solo es válido cuando el ancho del lápiz es de 1 o menos en las unidades del dispositivo.

  • PS_NULL crea un lápiz NULL.

  • PS_INSIDEFRAME crea un lápiz que dibuja una línea dentro del marco de formas cerradas generado por las funciones de salida de la GDI de Windows que especifican un rectángulo de selección (por ejemplo, las funciones miembro Ellipse, Rectangle, RoundRect, Pie y Chord). Cuando este estilo se usa con funciones de salida de la GDI de Windows que no especifican un rectángulo de selección (por ejemplo, la función miembro LineTo), el área de dibujo del lápiz no está limitada por un marco.

La segunda versión del constructor CPen especifica una combinación de atributos de tipo, estilo, extremo y unión. Los valores de cada categoría se deben combinar mediante el operador bit a bit "or" (|). El tipo de lápiz puede ser uno de los valores siguientes:

  • PS_GEOMETRIC crea un lápiz geométrico.

  • PS_COSMETIC crea un lápiz cosmético.

    La segunda versión del constructor CPen agrega los siguientes estilos de lápiz para nPenStyle:

  • PS_ALTERNATE crea un lápiz que establece todos los demás píxeles. (Este estilo solo es aplicable a los lápices cosméticos).

  • PS_USERSTYLE crea un lápiz que usa una variedad de estilos proporcionada por el usuario.

    El extremo puede tener uno de los valores siguientes :

  • PS_ENDCAP_ROUND: los extremos son redondos.

  • PS_ENDCAP_SQUARE: los extremos son cuadrados.

  • PS_ENDCAP_FLAT: los extremos son planos.

    La unión puede tener uno de los valores siguientes:

  • PS_JOIN_BEVEL: las uniones se biselan.

  • PS_JOIN_MITER: las uniones forman un inglete cuando se encuentran dentro del límite actual establecido por la función SetMiterLimit. Si la unión supera este límite, se bisela.

  • PS_JOIN_ROUND: las uniones son redondas.

nWidth
Especifica el ancho del lápiz.

  • Para la primera versión del constructor, un valor de 0 se tratará de forma similar a un valor de 1, salvo que el ancho no se verá afectado por las operaciones de transformación de escala que estén en vigor para el objeto Graphics para el que se use el lápiz; el ancho siempre será de 1 píxel.

  • Para la segunda versión del constructor, si nPenStyle es PS_GEOMETRIC, el ancho se asignará en unidades lógicas. Si nPenStyle es PS_COSMETIC, el ancho debe establecerse en 1.

crColor
Contiene un color RGB para el lápiz.

pLogBrush
Apunta a una estructura LOGBRUSH. Si nPenStyle es PS_COSMETIC, el miembro lbColor de la estructura LOGBRUSH especifica el color del lápiz, y el miembro lbStyle de la estructura LOGBRUSH debe establecerse en BS_SOLID. Si nPenStyle es PS_GEOMETRIC, hay que usar todos los miembros para especificar los atributos de pincel del lápiz.

nStyleCount
Especifica la longitud, en unidades de doble palabra, de la matriz lpStyle. Si nPenStyle no es PS_USERSTYLE, este valor debe ser cero.

lpStyle
Apunta a una matriz de valores de doble palabra. 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. Si nPenStyle no es PS_USERSTYLE, este puntero debe ser NULL.

Comentarios

Si usa el constructor sin argumentos, debe inicializar el objeto CPen resultante con las funciones miembro CreatePen, CreatePenIndirect o CreateStockObject.

Si usa el constructor que toma argumentos, no es necesario llevar a cabo ninguna otra inicialización. El constructor con argumentos puede generar una excepción si se encuentran errores, mientras que el constructor sin argumentos siempre se ejecutará correctamente.

Ejemplo

// Create a solid red pen of width 2.
CPen myPen1(PS_SOLID, 2, RGB(255, 0, 0));

// Create a geometric pen.
LOGBRUSH logBrush;
logBrush.lbStyle = BS_SOLID;
logBrush.lbColor = RGB(0, 255, 0);
CPen myPen2(PS_DOT | PS_GEOMETRIC | PS_ENDCAP_ROUND, 2, &logBrush);

CPen::CreatePen

Crea un lápiz cosmético o geométrico lógico con los atributos de estilo, ancho y pincel especificados y lo asocia al objeto CPen.

BOOL CreatePen(
    int nPenStyle,
    int nWidth,
    COLORREF crColor);

BOOL CreatePen(
    int nPenStyle,
    int nWidth,
    const LOGBRUSH* pLogBrush,
    int nStyleCount = 0,
    const DWORD* lpStyle = NULL);

Parámetros

nPenStyle
Especifica el estilo del lápiz. Para ver una lista de valores posibles, consulte el parámetro nPenStyle en el constructor CPen.

nWidth
Especifica el ancho del lápiz.

  • Para la primera versión del CreatePen, un valor de 0 se tratará de forma similar a un valor de 1, salvo que el ancho no se verá afectado por las operaciones de transformación de escala que estén en vigor para el objeto Graphics para el que se use el lápiz; el ancho siempre será de 1 píxel.

  • Para la segunda versión de CreatePen, si nPenStyle es PS_GEOMETRIC, el ancho se asignará en unidades lógicas. Si nPenStyle es PS_COSMETIC, el ancho debe establecerse en 1.

crColor
Contiene un color RGB para el lápiz.

pLogBrush
Apunta a una estructura LOGBRUSH. Si nPenStyle es PS_COSMETIC, el miembro lbColor de la estructura LOGBRUSH especifica el color del lápiz, y el miembro lbStyle de la estructura LOGBRUSH debe establecerse en BS_SOLID. Si nPenStyle es PS_GEOMETRIC, hay que usar todos los miembros para especificar los atributos de pincel del lápiz.

nStyleCount
Especifica la longitud, en unidades de doble palabra, de la matriz lpStyle. Si nPenStyle no es PS_USERSTYLE, este valor debe ser cero.

lpStyle
Apunta a una matriz de valores de doble palabra. 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. Si nPenStyle no es PS_USERSTYLE, este puntero debe ser NULL.

Valor devuelto

Será distinto de cero si se ejecuta correctamente o cero si se produce un error en el método.

Comentarios

La primera versión de CreatePen inicializa un lápiz con el estilo, el ancho y el color especificados. El lápiz se puede seleccionar posteriormente como el lápiz actual para cualquier contexto de dispositivo.

Los lápices que tienen un ancho superior a 1 píxel siempre deben tener el estilo PS_NULL, PS_SOLID o PS_INSIDEFRAME.

Si un lápiz tiene el estilo PS_INSIDEFRAME y un color que no coincide con un color en la tabla de colores lógicos, el lápiz se dibujará con un color difuminado. El PS_SOLID estilo del lápiz no se puede usar para crear un lápiz con un color dithered. El estilo PS_INSIDEFRAME es idéntico a PS_SOLID si el ancho del lápiz es menor o igual que 1.

La segunda versión de CreatePen inicializa un lápiz cosmético o geométrico lógico que tiene los atributos de estilo, ancho y pincel especificados. El ancho de un lápiz cosmético es siempre 1; el ancho de un lápiz geométrico siempre se especifica en unidades del mundo real. 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 CDC::SelectObject. Después de seleccionar un lápiz en un contexto de dispositivo, se puede usar para dibujar líneas y curvas.

  • Si nPenStyle es PS_COSMETIC y PS_USERSTYLE, las entradas de la matriz lpStyle especifican longitudes de guiones y espacios en unidades de estilo. El dispositivo en el que se usa el lápiz para dibujar una línea define una unidad de estilo.

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

  • Si nPenStyle es PS_ALTERNATE, se omite la unidad de estilo y se establecen todos los demás píxeles.

Cuando una aplicación ya no requiere un lápiz determinado, debe llamar a la función miembro CGdiObject::DeleteObject o destruir el objeto CPen para que el recurso deje de estar en uso. Una aplicación no debe eliminar un lápiz cuando este se selecciona en un contexto de dispositivo.

Ejemplo

CPen myPen1, myPen2;

// Create a solid red pen of width 2.
myPen1.CreatePen(PS_SOLID, 2, RGB(255, 0, 0));

// Create a geometric pen.
LOGBRUSH logBrush;
logBrush.lbStyle = BS_SOLID;
logBrush.lbColor = RGB(0, 255, 0);
myPen2.CreatePen(PS_DOT | PS_GEOMETRIC | PS_ENDCAP_ROUND, 2, &logBrush);

CPen::CreatePenIndirect

Inicializa un lápiz que tiene el estilo, el ancho y el color especificados en la estructura a la que lpLogPen apunta.

BOOL CreatePenIndirect(LPLOGPEN lpLogPen);

Parámetros

lpLogPen
Apunta a la estructura LOGPEN de Windows que contiene información sobre el lápiz.

Valor devuelto

Es distinto de cero si la función se realiza correctamente; de lo contrario, es 0.

Comentarios

Los lápices que tienen un ancho superior a 1 píxel siempre deben tener el estilo PS_NULL, PS_SOLID o PS_INSIDEFRAME.

Si un lápiz tiene el estilo PS_INSIDEFRAME y un color que no coincide con un color en la tabla de colores lógicos, el lápiz se dibujará con un color difuminado. El estilo PS_INSIDEFRAME es idéntico a PS_SOLID si el ancho del lápiz es menor o igual que 1.

Ejemplo

LOGPEN logpen;
CPen   cMyPen;

// Get the LOGPEN of an existing pen.
penExisting.GetLogPen(&logpen);

// Change the color to red and the width to 2.
logpen.lopnWidth.x = 2;
logpen.lopnColor = RGB(255, 0, 0);

// Create my pen using the new settings.
cMyPen.CreatePenIndirect(&logpen);

CPen::FromHandle

Este método se usa para devolver un puntero que apunta a un objeto CPen si se especifica el manipulador de un objeto de lápiz de la GDI de Windows.

static CPen* PASCAL FromHandle(HPEN hPen);

Parámetros

hPen
Manipulador HPEN de lápiz de la GDI de Windows.

Valor devuelto

Un puntero a un objeto CPen si se realiza correctamente; de lo contrario, NULL.

Comentarios

Si un objeto CPen no está asociado al identificador, se creará y asociará un objeto CPen temporal. Este objeto CPen temporal solo es válido hasta la próxima vez que la aplicación tenga tiempo de inactividad en su bucle de eventos, momento en el que se eliminan todos los objetos gráficos temporales. Es decir, el objeto temporal solo es válido durante el procesamiento de un mensaje de ventana.

Ejemplo

// Convert an HPEN to a CPen*.
// NOTE: hPen is a valid pen handle.
CPen* pPen = CPen::FromHandle(hPen);

CPen::GetExtLogPen

Obtiene una estructura subyacente EXTLOGPEN.

int GetExtLogPen(EXTLOGPEN* pLogPen);

Parámetros

pLogPen
Apunta a una estructura EXTLOGPEN que contiene información sobre el lápiz.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Comentarios

La estructura EXTLOGPEN define los atributos de estilo, ancho y pincel de un lápiz. Por ejemplo, llame a GetExtLogPen para que coincida con el estilo de un lápiz en particular.

Consulte los temas siguientes en Windows SDK para obtener información sobre los atributos de lápiz:

Ejemplo

En el ejemplo de código siguiente se muestra cómo llamar a GetExtLogPen para recuperar los atributos de un lápiz y, después, crear un lápiz cosmético con el mismo color.

EXTLOGPEN extlogpen;
penExisting.GetExtLogPen(&extlogpen);
CPen penOther;
LOGBRUSH LogBrush = { extlogpen.elpBrushStyle, extlogpen.elpColor,
   extlogpen.elpHatch };
penOther.CreatePen(PS_COSMETIC, 1, &LogBrush);

CPen::GetLogPen

Obtiene una estructura subyacente LOGPEN.

int GetLogPen(LOGPEN* pLogPen);

Parámetros

pLogPen
Apunta a una estructura LOGPEN para contener información sobre el lápiz.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Comentarios

La estructura LOGPEN define el estilo, el color y el patrón de un lápiz.

Por ejemplo, llame a GetLogPen para que coincida con el estilo de un lápiz en particular.

Consulte los temas siguientes en Windows SDK para obtener información sobre los atributos de lápiz:

Ejemplo

En el ejemplo de código siguiente se muestra cómo llamar a GetLogPen para recuperar un carácter de lápiz y, después, crear un lápiz liso con el mismo color.

LOGPEN logpen;
penExisting.GetLogPen(&logpen);
CPen penOther(PS_SOLID, 0, logpen.lopnColor);

CPen::operator HPEN

Obtiene el identificador de la GDI de Windows asociado al objeto CPen.

operator HPEN() const;

Valor devuelto

Si se ejecuta correctamente, un manipulador del objeto de la GDI de Windows representado por el objeto CPen; de lo contrario, NULL.

Comentarios

Este operador es un operador de conversión que admite el uso directo de un objeto HPEN.

Para obtener más información sobre el uso de objetos gráficos, consulte el artículo Objetos gráficos en Windows SDK.

Ejemplo

// Create a solid red pen of width 2.
CPen myPen(PS_SOLID, 2, RGB(255, 0, 0));

// Get the handle of the pen object.
HPEN hPen = (HPEN)myPen;

Vea también

CGdiObject (clase)
Gráfico de jerarquías
CBrush (clase)