Classe CLinkCtrl

Artigo
08/04/2024

Fornece a funcionalidade do controle SysLink comum do Windows.

Sintaxe

class CLinkCtrl : public CWnd

Membros

Construtores públicos

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

Métodos públicos

Nome	Descrição
CLinkCtrl::Create	Cria um controle de link e o anexa a um objeto `CLinkCtrl`.
CLinkCtrl::CreateEx	Cria um controle de link com estilos estendidos e o anexa a um objeto `CLinkCtrl`.
CLinkCtrl::GetIdealHeight	Recupera a altura ideal do controle de link.
CLinkCtrl::GetIdealSize	Calcula a altura preferencial do texto do link para o controle de link atual, dependendo da largura especificada do link.
CLinkCtrl::GetItem	Recupera os estados e atributos de um item de controle de link.
CLinkCtrl::GetItemID	Recupera a ID de um item de controle de link.
CLinkCtrl::GetItemState	Recupera o estado do item de controle de link.
CLinkCtrl::GetItemUrl	Recupera o URL representado pelo item de controle de link.
CLinkCtrl::HitTest	Determina se o usuário clicou no link especificado.
CLinkCtrl::SetItem	Define os estados e atributos de um item de controle de link.
CLinkCtrl::SetItemID	Define a ID de um item de controle de link.
CLinkCtrl::SetItemState	Define o estado do item de controle de vínculo.
CLinkCtrl::SetItemUrl	Define o URL representado pelo item de controle de link.

Comentários

Um "controle de link" fornece uma maneira conveniente de inserir links de hipertexto em uma janela. O controle real é uma janela que renderiza o texto marcado e inicia aplicativos apropriados quando o usuário clica em um link inserido. Há suporte para vários links em um controle e podem ser acessados por um índice baseado em zero.

Esse controle (e, portanto, a classe CLinkCtrl) está disponível somente para programas em execução no Windows XP e versões posteriores.

Para obter mais informações, consulte Controle SysLink no SDK do Windows.

Hierarquia de herança

CObject

CCmdTarget

CWnd

CLinkCtrl

Requisitos

Cabeçalho: afxcmn.h

CLinkCtrl::CLinkCtrl

Constrói um objeto CLinkCtrl.

CLinkCtrl();

CLinkCtrl::Create

Cria um controle de link e o anexa a um objeto CLinkCtrl.

virtual BOOL Create(
    LPCTSTR lpszLinkMarkup,
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

virtual BOOL Create(DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

Parâmetros

lpszLinkMarkup
Ponteiro para uma cadeia de caracteres com término zero que contém o texto marcado a ser exibido. Para obter mais informações, consulte a seção "Marcação e acesso ao link" na Visão geral do tópico dos controles SysLink.

dwStyle
Especifica o estilo do controle de link. Aplique qualquer combinação de estilos de controle. Confira Estilos de controle comuns no Windows SDK para obter mais informações.

rect
Especifica o tamanho e a posição do controle de link. Pode ser um objeto CRect ou uma estrutura RECT.

pParentWnd
Especifica a janela pai do controle de link. Não pode ser NULL.

Nid
Especifica a ID do controle de link.

Valor de retorno

TRUE se a inicialização for bem-sucedida, caso contrário, FALSE.

Comentários

Um objeto CLinkCtrl é construído em duas etapas. Primeiro, chame o construtor e, em seguida, chame Create, que cria o controle de link e o anexa ao objeto CLinkCtrl. Se quiser usar estilos de janela estendidos com o controle, chame CLinkCtrl::CreateEx em vez de Create.

A segunda forma do método Create foi preterida. Use o primeiro formulário que especifica o parâmetro lpszLinkMarkup.

Exemplo

O primeiro exemplo de código define duas variáveis, nomeadas m_Link1 e m_Link2, que são usadas para acessar dois controles de link.

afx_msg void OnNMClickSyslink1(NMHDR *pNMHDR, LRESULT *pResult);
afx_msg void OnNMClickSyslink2(NMHDR *pNMHDR, LRESULT *pResult);
// Link variable associated with resource editor CLinkCtrl control.
CLinkCtrl m_Link1;
// Link variable associated with programmatic CLinkCtrl control.
CLinkCtrl m_Link2;

O próximo exemplo de código cria um controle de link com base no local de outro controle de link. O carregador de recursos cria o primeiro controle de link quando o aplicativo é iniciado. Quando o aplicativo insere o método OnInitDialog, você cria o segundo controle de link em relação à posição do primeiro controle de link. Em seguida, redimensione o segundo controle de link para ajustar o texto exibido.

CRect rect1, rect2;
int height = 0;
SIZE sz = {0};
PTCHAR url =
    _T("Link 2)  ")
    _T("<A HREF=\"https://visualstudio.microsoft.com\">")
    _T("Microsoft VC++ Home")
    _T("</A>");
m_Link1.GetWindowRect(&rect1);
m_Link2.Create(url,
               (WS_VISIBLE | WS_TABSTOP | WS_CHILD | WS_BORDER),
               CRect(
                   rect1.left, rect1.bottom + rect1.Height(),
                   rect1.right, rect1.bottom + (2 * rect1.Height())),
               this,
               IDC_SYSLINK2);
m_Link2.GetClientRect(&rect2);
// The return value of GetIdealSize() is the same as sz.cy
height = m_Link2.GetIdealSize(
    rect2.Width(), &sz);
if ((sz.cx != 0) && (sz.cy != 0))
{
   int rc = m_Link2.SetWindowPos(
       this,
       0, 0, sz.cx, sz.cy,
       (SWP_NOMOVE | SWP_NOZORDER | SWP_NOREPOSITION | SWP_NOACTIVATE));
}

CLinkCtrl::CreateEx

Cria um controle de link com estilos estendidos e o anexa a um objeto CLinkCtrl.

virtual BOOL CreateEx(
    LPCTSTR lpszLinkMarkup,
    DWORD dwExStyle,
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

virtual BOOL CreateEx(DWORD  dwExStyle,
    DWORD  dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT  nID);

Parâmetros

dwExStyle
Especifica o estilo estendido do controle de link. Para obter uma lista de estilos estendidos do Windows, confira o parâmetro dwExStyle para CreateWindowEx no SDK do Windows.

dwStyle
Especifica o estilo do controle de link. Aplique qualquer combinação de estilos de controle. Confira Estilos de controle comuns no SDK do Windows para obter mais informações.

rect
Especifica o tamanho e a posição do controle de link. Pode ser um objeto CRect ou uma estrutura RECT.

pParentWnd
Especifica a janela pai do controle de link. Não pode ser NULL.

Nid
Especifica a ID do controle de link.

Valor de retorno

TRUE se a inicialização for bem-sucedida, caso contrário, FALSE.

Comentários

Use CreateEx em vez de Criar para aplicar constantes de estilo estendidas do Windows.

A segunda forma do método CreateEx foi preterida. Use o primeiro formulário que especifica o parâmetro lpszLinkMarkup.

CLinkCtrl::GetIdealHeight

Recupera a altura ideal do controle de link.

int GetIdealHeight() const;

Valor de retorno

A altura ideal do controle, em pixels.

Comentários

Essa função membro implementa o comportamento da mensagem LM_GETIDEALHEIGHT do Win32, conforme descrito no SDK do Windows.

CLinkCtrl::GetIdealSize

Calcula a altura preferencial do texto do link para o controle de link atual, dependendo da largura especificada do link.

int GetIdealSize(
    int cxMaxWidth,
    SIZE* pSize) const;

Parâmetros

cxMaxWidth
[entrada] A largura máxima do link, em pixels.

pSize
[saída] Um ponteiro para uma estrutura SIZE do Windows. Quando esse método retorna, o membro cy da estrutura SIZE contém a altura de texto do link ideal para a largura do texto do link especificada por cxMaxWidth. O membro cx da estrutura contém a largura do texto do link que é realmente necessária.

Valor de retorno

A altura preferencial do texto do link, em pixels. O valor retornado é o mesmo que o valor do membro cy da estrutura SIZE.

Comentários

Para obter um exemplo do método GetIdealSize, consulte o exemplo em CLinkCtrl::Create.

Esse método envia a mensagem LM_GETIDEALSIZE, que é descrita no SDK do Windows.

CLinkCtrl::GetItem

Recupera os estados e atributos de um item de controle de link.

BOOL GetItem(PLITEM pItem) const;

Parâmetros

pItem
Um ponteiro para uma estrutura LITEM para receber informações do item.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

Essa função membro implementa o comportamento da mensagem LM_GETITEM do Win32, conforme descrito no SDK do Windows.

CLinkCtrl::GetItemID

Recupera a ID de um item de controle de link.

BOOL GetItemID(
    int iLink,
    CString& strID) const;

BOOL GetItemID(
    int iLink,
    LPWSTR szID,
    UINT cchID) const;

Parâmetros

iLink
O índice de um item de controle de link.

strID
Um objeto CStringT que contém a ID do item especificado.

szID
Uma cadeia de caracteres com término nulo que contém a ID do item especificado.

cchID
O tamanho em caracteres do buffer de szID.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Observação

Essa função também retornará FALSE se o buffer de szID ou strID for menor que MAX_LINKID_TEXT.

Comentários

Recupera a ID de um item de controle de link. Para obter mais informações, consulte a mensagem LM_GETITEM do Win32 no SDK do Windows.

CLinkCtrl::GetItemState

Recupera o estado do item de controle de link.

BOOL GetItemState(
    int iLink,
    UINT* pnState,
    UINT stateMask = LIS_FOCUSED | LIS_ENABLED | LIS_VISITED) const;

Parâmetros

iLink
O índice de um item de controle de link.

pnState
O valor do item de estado especificado.

stateMask
Combinação de sinalizadores que descrevem qual item de estado obter. Para obter uma lista de valores, consulte a descrição do membro state na estrutura LITEM. Os itens permitidos são idênticos aos permitidos em state.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

Recupera o valor do item de estado especificado de um item de controle de link específico. Para obter mais informações, consulte a mensagem LM_GETITEM do Win32 no SDK do Windows.

CLinkCtrl::GetItemUrl

Recupera o URL representado pelo item de controle de link.

BOOL GetItemUrl(
    int iLink,
    CString& strUrl) const;

BOOL GetItemUrl(
    int iLink,
    LPWSTR szUrl,
    UINT cchUrl) const;

Parâmetros

iLink
O índice de um item de controle de link.

strUrl
Um objeto CStringT que contém o URL representado pelo item especificado

szUrl
Uma cadeia de caracteres com término nulo que contém o URL representado pelo item especificado

cchUrl
O tamanho em caracteres do buffer de szURL.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Observação

Essa função também retornará FALSE se o buffer de szUrl ou strUrl for menor que MAX_LINKID_TEXT.

Comentários

Recupera o URL representado pelo item de controle de link especificado. Para obter mais informações, consulte a mensagem LM_GETITEM do Win32 no SDK do Windows.

CLinkCtrl::HitTest

Determina se o usuário clicou no link especificado.

BOOL HitTest(PLHITTESTINFO phti) const;

Parâmetros

phti
Ponteiro para uma estrutura LHITTESTINFO que contém qualquer informação sobre o link que o usuário clicou.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

Essa função membro implementa o comportamento da mensagem LM_HITTEST do Win32, conforme descrito no SDK do Windows.

CLinkCtrl::SetItem

Define os estados e atributos de um item de controle de link.

BOOL SetItem(PLITEM pItem);

Parâmetros

pItem
Um ponteiro para uma estrutura LITEM que contém as informações a serem definidas.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

Essa função membro implementa o comportamento da mensagem LM_SETITEM do Win32, conforme descrito no SDK do Windows.

CLinkCtrl::SetItemID

Recupera a ID de um item de controle de link.

BOOL SetItemID(
    int iLink,
    LPCWSTR szID);

Parâmetros

iLink
O índice de um item de controle de link.

szID
Uma cadeia de caracteres com término nulo que contém a ID do item especificado.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

Define a ID de um item de controle de link. Para obter mais informações, consulte a mensagem do Win32 LM_SETITEM no SDK do Windows.

CLinkCtrl::SetItemState

Recupera o estado do item de controle de link.

BOOL SetItemState(
    int iLink,
    UINT state,
    UINT stateMask = LIS_FOCUSED | LIS_ENABLED | LIS_VISITED);

Parâmetros

iLink
O índice de um item de controle de link.

pnState
O valor do item de estado especificado que está sendo definido.

stateMask
Combinação de sinalizadores que descrevem o item de estado que está sendo definido. Para obter uma lista de valores, consulte a descrição do membro state na estrutura LITEM. Os itens permitidos são idênticos aos permitidos em state.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

Define o valor do item de estado especificado de um item de controle de link específico. Para obter mais informações, consulte a mensagem do Win32 LM_SETITEM no SDK do Windows.

CLinkCtrl::SetItemUrl

Define o URL representado pelo item de controle de link.

BOOL SetItemUrl(
    int iLink,
    LPCWSTR szUrl);

Parâmetros

iLink
O índice de um item de controle de link.

szUrl
Uma cadeia de caracteres com término nulo que contém o URL representado pelo item especificado

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

Define o URL representado pelo item de controle de link especificado. Para obter mais informações, consulte a mensagem do Win32 LM_SETITEM no SDK do Windows.

Confira também

Gráfico da hierarquia
Classe CWnd

Partilhar via

Classe CLinkCtrl

Sintaxe

Membros

Construtores públicos

Métodos públicos

Comentários

Hierarquia de herança

Requisitos

CLinkCtrl::CLinkCtrl

CLinkCtrl::Create

Parâmetros

Valor de retorno

Comentários

Exemplo

CLinkCtrl::CreateEx

Parâmetros

Valor de retorno

Comentários

CLinkCtrl::GetIdealHeight

Valor de retorno

Comentários

CLinkCtrl::GetIdealSize

Parâmetros

Valor de retorno

Comentários

CLinkCtrl::GetItem

Parâmetros

Valor de retorno

Comentários

CLinkCtrl::GetItemID

Parâmetros

Valor de retorno

Comentários

CLinkCtrl::GetItemState

Parâmetros

Valor de retorno

Comentários

CLinkCtrl::GetItemUrl

Parâmetros

Valor de retorno

Comentários

CLinkCtrl::HitTest

Parâmetros

Valor de retorno

Comentários

CLinkCtrl::SetItem

Parâmetros

Valor de retorno

Comentários

CLinkCtrl::SetItemID

Parâmetros

Valor de retorno

Comentários

CLinkCtrl::SetItemState

Parâmetros

Valor de retorno

Comentários

CLinkCtrl::SetItemUrl

Parâmetros

Valor de retorno

Comentários

Confira também

Comentários

Recursos adicionais