Compartilhar via

Classe CPen

  • Artigo

Encapsula uma caneta GDI (Graphics Device Interface) do Windows.

Sintaxe

class CPen : public CGdiObject

Membros

Construtores públicos

Nome Descrição
CPen::CPen Constrói um objeto CPen.

Métodos públicos

Nome Descrição
CPen::CreatePen Cria uma caneta lógica cosmética ou geométrica com os atributos de estilo, largura e pincel especificados e a anexa ao objeto CPen.
CPen::CreatePenIndirect Cria uma caneta com o estilo, a largura e a cor fornecidos em uma estrutura LOGPEN e a anexa ao objeto CPen.
CPen::FromHandle Retorna um ponteiro para um objeto CPen quando dado um HPEN do Windows.
CPen::GetExtLogPen Obtém uma estrutura EXTLOGPEN subjacente.
CPen::GetLogPen Obtém uma estrutura LOGPEN subjacente.

Operadores públicos

Nome Descrição
CPen::operator HPEN Retorna o identificador do Windows anexado ao objeto CPen.

Comentários

Para obter mais informações sobre como usar CPen, consulte Objetos Gráficos.

Hierarquia de herança

CObject

CGdiObject

CPen

Requisitos

Cabeçalhoafxwin.h:

CPen::CPen

Constrói um 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 o estilo da caneta. Esse parâmetro na primeira versão do construtor pode ser um dos seguintes valores:

  • PS_SOLID Cria uma caneta sólida.

  • PS_DASH Cria uma caneta tracejada. Válido somente quando a largura da caneta for 1 ou menos, em unidades do dispositivo.

  • PS_DOT Cria uma caneta pontilhada. Válido somente quando a largura da caneta for 1 ou menos, em unidades do dispositivo.

  • PS_DASHDOT Cria uma caneta com traços e pontos alternados. Válido somente quando a largura da caneta for 1 ou menos, em unidades do dispositivo.

  • PS_DASHDOTDOT Cria uma caneta com traços e pontos duplos alternados. Válido somente quando a largura da caneta for 1 ou menos, em unidades do dispositivo.

  • PS_NULL Cria uma caneta nula.

  • PS_INSIDEFRAMECria uma caneta que desenha uma linha dentro do quadro de formas fechadas produzidas pelas funções de saída GDI do Windows que especificam um retângulo delimitador (por exemplo, as funções de membro Ellipse, Rectangle, RoundRect, Pie e Chord, por exemplo). Quando esse estilo é usado com funções de saída GDI do Windows que não especificam um retângulo delimitador (por exemplo, a função de membro LineTo), a área de desenho da caneta não é limitada por um quadro.

A segunda versão do construtor CPen especifica uma combinação de atributos de tipo, estilo, limite final e junção. Os valores de cada categoria devem ser combinados usando o operador bit a bit "ou" (|). O tipo da caneta pode ser um dos valores a seguir:

  • PS_GEOMETRIC Cria uma caneta geométrica.

  • PS_COSMETIC Cria uma caneta cosmética.

    A segunda versão do construtor CPen adiciona os seguintes estilos de caneta para nPenStyle:

  • PS_ALTERNATE Cria uma caneta que define todos os outros pixels. (Esse estilo é aplicável somente a canetas cosméticas).

  • PS_USERSTYLE Cria uma caneta que usa uma matriz de estilo fornecida pelo usuário.

    O arremate de extremidade pode ser um dos valores a seguir:

  • 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 pode ser um dos valores a seguir:

  • 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 a junção exceder esse limite, ela será biselada.

  • PS_JOIN_ROUND As junções são redondas.

nWidth
Especifica a largura da caneta.

  • Para a primeira versão do construtor, um valor 0 será tratado de forma semelhante a um valor 1, exceto que a largura não será afetada por operações de transformação de escala que estão em vigor para o objeto Graphics para o qual a caneta é usada; a largura sempre será de 1 pixel.

  • Para a segunda versão do construtor, se nPenStyle for PS_GEOMETRIC, a largura será fornecida em unidades lógicas. Se nPenStyle for PS_COSMETIC, a largura deverá ser definida como 1.

crColor
Contém uma cor RGB para a caneta.

pLogBrush
Aponta para uma estrutura LOGBRUSH. Se nPenStyle for PS_COSMETIC, o membro lbColor da estrutura LOGBRUSH especifica a cor da caneta e o membro lbStyle da estrutura LOGBRUSH deve ser definido como BS_SOLID. Se nPenStyle for PS_GEOMETRIC, todos os membros devem ser usados para especificar os atributos de pincel da caneta.

nStyleCount
Especifica o comprimento, em unidades de palavra dupla, da matriz lpStyle. Esse valor precisa ser zero se nPenStyle não for PS_USERSTYLE.

lpStyle
Aponta para uma matriz de valores de palavra dupla. 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 deve ser NULL se nPenStyle não for PS_USERSTYLE.

Comentários

Se você usar o construtor sem argumentos, deverá inicializar o objeto CPen resultante com as funções de membro CreatePen, CreatePenIndirect ou CreateStockObject.

Se você usar o construtor que usa argumentos, nenhuma inicialização adicional será necessária. O construtor com argumentos poderá gerar uma exceção se forem encontrados erros, enquanto o construtor sem argumentos sempre terá êxito.

Exemplo

// 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

Cria uma caneta lógica cosmética ou geométrica com os atributos de estilo, largura e pincel especificados e a anexa ao 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 o estilo da caneta. Para obter uma lista de valores possíveis, consulte o parâmetro nPenStyle no construtor CPen.

nWidth
Especifica a largura da caneta.

  • Para a primeira versão de CreatePen, um valor 0 será tratado de forma semelhante a um valor 1, exceto que a largura não será afetada por operações de transformação de escala que estão em vigor para o objeto Graphics para o qual a caneta é usada; a largura sempre será de 1 pixel.

  • Para a segunda versão do CreatePen, se nPenStyle for PS_GEOMETRIC, a largura será fornecida em unidades lógicas. Se nPenStyle for PS_COSMETIC, a largura deverá ser definida como 1.

crColor
Contém uma cor RGB para a caneta.

pLogBrush
Aponta para uma estrutura LOGBRUSH. Se nPenStyle for PS_COSMETIC, o membro lbColor da estrutura LOGBRUSH especifica a cor da caneta e o membro lbStyle da estrutura LOGBRUSH deve ser definido como BS_SOLID. Se nPenStyle for PS_GEOMETRIC, todos os membros devem ser usados para especificar os atributos de pincel da caneta.

nStyleCount
Especifica o comprimento, em unidades de palavra dupla, da matriz lpStyle. Esse valor precisa ser zero se nPenStyle não for PS_USERSTYLE.

lpStyle
Aponta para uma matriz de valores de palavra dupla. 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 deve ser NULL se nPenStyle não for PS_USERSTYLE.

Valor de Devolução

Diferente de zero se tiver êxito ou zero se o método falhar.

Comentários

A primeira versão de CreatePen inicializa uma caneta com o estilo, a largura e a cor especificados. A caneta pode ser selecionada posteriormente como a caneta atual para qualquer contexto de dispositivo.

Canetas com uma largura maior que 1 pixel sempre devem ter o estilo PS_NULL, PS_SOLID ou PS_INSIDEFRAME.

Se uma caneta tiver o estilo PS_INSIDEFRAME e uma cor que não corresponda a uma cor na tabela de cores lógicas, a caneta será desenhada com uma cor pontilhada. O PS_SOLID estilo de caneta não pode ser usado para criar uma caneta com uma cor distorcida. O estilo PS_INSIDEFRAME é idêntico ao PS_SOLID se a largura da caneta for menor ou igual a 1.

A segunda versão de CreatePen inicializa uma caneta cosmética ou geométrica lógica que tem os atributos de estilo, largura e pincel especificados. A largura de uma caneta cosmética é sempre 1; a largura de uma caneta geométrica é sempre especificada em unidades mundiais. Depois que um aplicativo cria uma caneta lógica, ele pode selecionar essa caneta em um contexto de dispositivo chamando a função CDC::SelectObject. Depois que uma caneta é selecionada em um contexto de dispositivo, ela pode ser usada para desenhar linhas e curvas.

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

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

  • Se nPenStyle for PS_ALTERNATE, a unidade de estilo é ignorada e todos os outros pixels são definidos.

Quando um aplicativo não exige mais uma determinada caneta, ele deve chamar a função membro CGdiObject::DeleteObject ou destruir o objeto CPen para que o recurso não possa mais ser usado. Um aplicativo não deve excluir uma caneta quando ela é selecionada em um contexto de dispositivo.

Exemplo

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 uma caneta que tem o estilo, a largura e a cor dados na estrutura apontada por lpLogPen.

BOOL CreatePenIndirect(LPLOGPEN lpLogPen);

Parâmetros

lpLogPen
Aponta para a estrutura LOGPEN do Windows que contém informações sobre a caneta.

Valor de Devolução

Diferente de zero se a função for bem-sucedida; caso contrário, 0.

Comentários

Canetas com uma largura maior que 1 pixel sempre devem ter o estilo PS_NULL, PS_SOLID ou PS_INSIDEFRAME.

Se uma caneta tiver o estilo PS_INSIDEFRAME e uma cor que não corresponda a uma cor na tabela de cores lógicas, a caneta será desenhada com uma cor pontilhada. O estilo PS_INSIDEFRAME é idêntico ao PS_SOLID se a largura da caneta for menor ou igual a 1.

Exemplo

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

Retorna um ponteiro para um objeto CPen, dado um identificador para um objeto de caneta GDI do Windows.

static CPen* PASCAL FromHandle(HPEN hPen);

Parâmetros

hPen
HPEN Identificador da caneta GDI do Windows.

Valor de Devolução

Um ponteiro para um objeto CPen se tiver êxito; caso contrário, NULL.

Comentários

Se um objeto CPen não estiver anexado ao identificador, um objeto temporário CPen será criado e anexado. Esse objeto temporário CPen é válido somente até a próxima vez que o aplicativo tiver tempo ocioso em seu loop de eventos, momento em que todos os objetos gráficos temporários são excluídos. Em outras palavras, o objeto temporário somente será válido durante o processamento de uma mensagem de janela.

Exemplo

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

CPen::GetExtLogPen

Obtém uma estrutura EXTLOGPEN subjacente.

int GetExtLogPen(EXTLOGPEN* pLogPen);

Parâmetros

pLogPen
Aponta para uma estrutura EXTLOGPEN que contém informações sobre a caneta.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

A estrutura EXTLOGPEN define os atributos de estilo, largura e pincel de uma caneta. Por exemplo, chame GetExtLogPen para corresponder ao estilo específico de uma caneta.

Consulte os seguintes tópicos no SDK do Windows para obter informações sobre atributos de caneta:

Exemplo

O exemplo de código a seguir demonstra a chamada de GetExtLogPen para recuperar os atributos de uma caneta e, em seguida, criar uma caneta cosmética nova com a mesma cor.

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

CPen::GetLogPen

Obtém uma estrutura LOGPEN subjacente.

int GetLogPen(LOGPEN* pLogPen);

Parâmetros

pLogPen
Aponta para uma estrutura LOGPEN para conter informações sobre a caneta.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

A estrutura LOGPEN define o estilo, a cor e o padrão de uma caneta.

Por exemplo, chame GetLogPen para corresponder ao estilo específico de caneta.

Consulte os seguintes tópicos no SDK do Windows para obter informações sobre atributos de caneta:

Exemplo

O exemplo de código a seguir demonstra a chamada de GetLogPen para recuperar um caractere de caneta e, em seguida, criar uma caneta sólida e nova com a mesma cor.

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

CPen::operator HPEN

Obtém o identificador do Windows GDI anexado do objeto CPen.

operator HPEN() const;

Valor de Devolução

Se tiver êxito, um identificador para o objeto GDI do Windows representado pelo objeto CPen; caso contrário, NULL.

Comentários

Esse operador é um operador de conversão, que dá suporte ao uso direto de um objeto HPEN.

Para obter mais informações sobre como usar objetos gráficos, consulte o artigo Objetos Gráficos no SDK do Windows.

Exemplo

// 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;

Confira também

Classe CGdiObject
Gráfico da hierarquia
Classe CBrush