CPen Classe

Encapsula uma caneta de interface de dispositivo gráfico (GDI) do Windows.

Sintaxe

class CPen : public CGdiObject

Membros

Construtores Públicos

Métodos Públicos

Operadores Públicos

Observações

Para mais informações sobre a utilização CPende , veja Objetos Gráficos.

Hierarquia de herança

CObject

CGdiObject

CPen

Requerimentos

Cabeçalho:afxwin.h

CPen::CPen

Constrói um CPen objeto.

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. Este 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 apenas quando a largura da caneta é 1 ou menor, em unidades de dispositivo.

• PS_DOT Cria uma caneta pontilhada. Válido apenas quando a largura da caneta é 1 ou menor, em unidades de dispositivo.

• PS_DASHDOT Cria uma caneta com traços e pontos alternados. Válido apenas quando a largura da caneta é 1 ou menor, em unidades de dispositivo.

• PS_DASHDOTDOT Cria uma caneta com traços alternados e pontos duplos. Válido apenas quando a largura da caneta é 1 ou menor, em unidades de dispositivo.

• PS_NULL Cria uma caneta nula.

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

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

• PS_GEOMETRIC Cria uma caneta geométrica.

• PS_COSMETIC Cria uma caneta cosmética.

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

• PS_ALTERNATE Cria uma caneta que define cada dois píxeis. (Este estilo é aplicável apenas a canetas cosméticas.)

• PS_USERSTYLE Cria uma caneta que utiliza um array de estilo fornecido pelo utilizador.

  A tampa final pode ter um dos seguintes valores:

• PS_ENDCAP_ROUND As tampas finais são redondas.

• PS_ENDCAP_SQUARE As tampas das extremidades são quadradas.

• PS_ENDCAP_FLAT As tampas de extremidade são planas.

  A junção pode ter um dos seguintes valores:

• PS_JOIN_BEVEL As junções são chanfradas.

• PS_JOIN_MITER As uniões são em ingletação quando estão dentro do limite de corrente definido pela SetMiterLimit função. Se a junção ultrapassar esse limite, é chanfrada.

• PS_JOIN_ROUND As uniõ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 estejam em vigor para o objeto Gráficos para o qual a caneta é usada; a largura será sempre de 1 pixel.

• Para a segunda versão do construtor, se nPenStyle é PS_GEOMETRIC, a largura é dada em unidades lógicas. Se nPenStyle for PS_COSMETIC, a largura deve ser definida para 1.

crColor
Contém uma cor RGB para a caneta.

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

nStyleCount
Especifica o comprimento, em unidades de palavra dupla, do lpStyle array. Este valor deve ser zero se nPenStyle não PS_USERSTYLEfor .

lpStyle
Aponta para um conjunto de valores de palavras duplas. O primeiro valor especifica o comprimento do primeiro traço num estilo definido pelo utilizador, o segundo valor especifica o comprimento do primeiro espaço, e assim sucessivamente. Este indicador deve ser NULL se nPenStyle não PS_USERSTYLEfor .

Observações

Se usar o construtor sem argumentos, deve inicializar o objeto resultante CPen com as CreatePenfunções , CreatePenIndirect, ou CreateStockObject membros.

Se usar o construtor que aceita argumentos, então não é necessária mais inicialização. O construtor com argumentos pode lançar uma exceção se forem encontrados erros, enquanto o construtor sem argumentos terá sempre sucesso.

Example

// 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 o estilo, largura e atributos de pincel especificados, e anexa-a ao CPen objeto.

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 uma lista de valores possíveis, veja o nPenStyle parâmetro no CPen construtor.

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 estejam em vigor para o objeto Gráficos para o qual a caneta é usada; a largura será sempre 1 pixel.

• Para a segunda versão de CreatePen, se nPenStyle é PS_GEOMETRIC, a largura é dada em unidades lógicas. Se nPenStyle for PS_COSMETIC, a largura deve ser definida para 1.

crColor
Contém uma cor RGB para a caneta.

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

nStyleCount
Especifica o comprimento, em unidades de palavra dupla, do lpStyle array. Este valor deve ser zero se nPenStyle não PS_USERSTYLEfor .

lpStyle
Aponta para um conjunto de valores de palavras duplas. O primeiro valor especifica o comprimento do primeiro traço num estilo definido pelo utilizador, o segundo valor especifica o comprimento do primeiro espaço, e assim sucessivamente. Este indicador deve ser NULL se nPenStyle não PS_USERSTYLEfor .

Valor de retorno

Não nulo se for bem-sucedido, ou zero se o método falhar.

Observações

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

As canetas com largura superior a 1 píxel devem sempre ter ou o PS_NULL, PS_SOLID, ou PS_INSIDEFRAME style.

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

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

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

• Se nPenStyle for PS_GEOMETRIC e PS_USERSTYLE, as entradas no lpStyle array especificam comprimentos de traços e espaços em unidades lógicas.

• Se nPenStyle for PS_ALTERNATE, a unidade de estilo é ignorada e cada outro píxel é definido.

Quando uma aplicação já não requer uma determinada caneta, deve chamar a CGdiObject::DeleteObject função membro ou destruir o CPen objeto para que o recurso deixe de ser utilizado. Uma aplicação não deve apagar uma caneta quando esta é selecionada no contexto de um dispositivo.

Example

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 cujo estilo, largura e cor são dados na estrutura apontada por lpLogPen.

BOOL CreatePenIndirect(LPLOGPEN lpLogPen);

Parâmetros

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

Valor de retorno

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

Observações

As canetas com largura superior a 1 píxel devem sempre ter ou o PS_NULL, PS_SOLID, ou PS_INSIDEFRAME style.

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

Example

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

Devolve um ponteiro para um CPen objeto dado um handle a um objeto da caneta GDI do Windows.

static CPen* PASCAL FromHandle(HPEN hPen);

Parâmetros

hPen
HPEN handle para a caneta Windows GDI.

Valor de retorno

Um ponteiro para um CPen objeto, se bem-sucedido, caso contrário NULL.

Observações

Se um CPen objeto não estiver anexado à alça, um objeto temporário CPen será criado e anexado. Este objeto temporário CPen é válido apenas até à próxima vez que a aplicação tiver tempo de inatividade no seu ciclo de eventos, altura em que todos os objetos gráficos temporários são eliminados. Ou seja, o objeto temporário só é válido durante o processamento de uma mensagem de janela.

Example

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

CPen::GetExtLogPen

Ganha uma EXTLOGPEN estrutura subjacente.

int GetExtLogPen(EXTLOGPEN* pLogPen);

Parâmetros

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

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0.

Observações

A EXTLOGPEN estrutura define o estilo, largura e atributos de 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 informações sobre atributos de caneta:

• GetObject

• EXTLOGPEN

• LOGPEN

• ExtCreatePen

Example

O exemplo de código seguinte demonstra a chamada GetExtLogPen para recuperar atributos de uma caneta e depois criar uma nova caneta cosmética 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

Ganha uma LOGPEN estrutura subjacente.

int GetLogPen(LOGPEN* pLogPen);

Parâmetros

pLogPen
Aponta para uma LOGPEN estrutura que contém informação sobre a caneta.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0.

Observações

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

Por exemplo, ligue GetLogPen para corresponder ao estilo específico da caneta.

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

• GetObject

• LOGPEN

Example

O exemplo de código seguinte demonstra a chamada GetLogPen para recuperar um carácter de caneta e depois criar uma nova caneta sólida com a mesma cor.

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

CPen::operator HPEN

Obtém o handle do Windows GDI associado ao CPen objeto.

operator HPEN() const;

Valor de retorno

Se for bem-sucedido, um handle para o objeto Windows GDI representado pelo CPen objeto; caso contrário NULL.

Observações

Este operador é um operador de casting, que suporta o uso direto de um HPEN objeto.

Para mais informações sobre o uso de objetos gráficos, consulte o artigo Objetos Gráficos no Windows SDK.

Example

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

Consulte também

CGdiObject Classe
Gráfico de Hierarquia
CBrush Classe