CLinkCtrl 类

项目
06/16/2023

提供 Windows 公共 SysLink 控件的功能。

语法

class CLinkCtrl : public CWnd

成员

公共构造函数

名称	描述
CLinkCtrl::CLinkCtrl	构造 `CLinkCtrl` 对象。

公共方法

名称	描述
CLinkCtrl::Create	创建链接控件并将其附加到 `CLinkCtrl` 对象。
CLinkCtrl::CreateEx	创建具有扩展样式的链接控件并将其附加到 `CLinkCtrl` 对象。
CLinkCtrl::GetIdealHeight	检索链接控件的理想高度。
CLinkCtrl::GetIdealSize	根据链接的指定宽度计算当前链接控件的链接文本的首选高度。
CLinkCtrl::GetItem	检索链接控件项的状态和属性。
CLinkCtrl::GetItemID	检索链接控件项的 ID。
CLinkCtrl::GetItemState	检索链接控件项的状态。
CLinkCtrl::GetItemUrl	检索链接控件项表示的 URL。
CLinkCtrl::HitTest	确定用户是否单击了指定链接。
CLinkCtrl::SetItem	设置链接控件项的状态和属性。
CLinkCtrl::SetItemID	设置链接控件项的 ID。
CLinkCtrl::SetItemState	设置链接控件项的状态。
CLinkCtrl::SetItemUrl	设置链接控件项表示的 URL。

备注

使用“链接控件”可以轻松地在窗口中嵌入超文本链接。实际控件是呈现标记文本的窗口，并在用户单击嵌入式链接时启动相应的应用程序。一个控件中支持多个可通过以零为基准的索引来访问的链接。

此控件（因此决定 CLinkCtrl 类）仅适用于在 Windows XP 及更高版本下运行的程序。

有关详细信息，请参阅 Windows SDK 中的 SysLink 控件。

继承层次结构

CObject

CCmdTarget

CWnd

CLinkCtrl

要求

标头： afxcmn.h

CLinkCtrl::CLinkCtrl

构造 CLinkCtrl 对象。

CLinkCtrl();

CLinkCtrl::Create

创建链接控件并将其附加到 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);

参数

lpszLinkMarkup
指向包含要显示的标记文本的以零结尾的字符串的指针。有关详细信息，请参阅主题 SysLink 控件概述中的“标记和链接访问”部分。

dwStyle
指定链接控件的样式。应用控件样式的任意组合。有关详细信息，请参阅 Windows SDK 中的通用控件样式。

rect
指定链接控件的大小和位置。它可以是 CRect 对象或 RECT 结构。

pParentWnd
指定链接控件的父窗口。不得为 NULL。

nID
指定链接控件的 ID。

返回值

如果初始化成功，则为 TRUE；否则为 FALSE。

备注

请分两步构造 CLinkCtrl 对象。首先，调用构造函数，然后调用 Create，这将创建链接控件并将其附加到 CLinkCtrl 对象。如果要将扩展窗口样式与控件一起使用，请调用 CLinkCtrl::CreateEx 而不是 Create。

Create 方法的第二种形式已停用。使用指定 lpszLinkMarkup 参数的第一种形式。

示例

第一个代码示例定义两个变量，名为 m_Link1 和 m_Link2，用于访问两个链接控件。

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;

下一个代码示例基于另一个链接控件的位置创建一个链接控件。资源加载程序会在应用程序启动时创建第一个链接控件。应用程序输入 OnInitDialog 方法时，基于第一个链接控件的位置创建第二个链接控件。然后，调整第二个链接控件的大小，以适配其显示的文本。

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

创建具有扩展样式的链接控件并将其附加到 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);

参数

lpszLinkMarkup
指向包含要显示的标记文本的以零结尾的字符串的指针。有关详细信息，请参阅主题 SysLink 控件概述中的“标记和链接访问”部分。

dwExStyle
指定链接控件的扩展样式。有关扩展 Windows 样式的列表，请参阅 Windows SDK 中 CreateWindowEx 的 dwExStyle 参数。

dwStyle
指定链接控件的样式。应用控件样式的任意组合。有关详细信息，请参阅 Windows SDK 中的通用控件样式。

rect
指定链接控件的大小和位置。它可以是 CRect 对象或 RECT 结构。

pParentWnd
指定链接控件的父窗口。不得为 NULL。

nID
指定链接控件的 ID。

返回值

如果初始化成功，则为 TRUE；否则为 FALSE。

备注

使用 CreateEx（而不是 Create）应用扩展的 Windows 样式常量。

CreateEx 方法的第二种形式已停用。使用指定 lpszLinkMarkup 参数的第一种形式。

CLinkCtrl::GetIdealHeight

检索链接控件的理想高度。

int GetIdealHeight() const;

返回值

控件的理想高度（以像素为单位）。

注解

此成员函数实现 Win32 消息 LM_GETIDEALHEIGHT 的行为，如 Windows SDK 中所述。

CLinkCtrl::GetIdealSize

根据链接的指定宽度计算当前链接控件的链接文本的首选高度。

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

参数

cxMaxWidth
[in] 链接的最大宽度（以像素为单位）。

pSize
[out] 指向 Windows SIZE 结构的指针。此方法返回时，SIZE 结构的 cy 成员包含 cxMaxWidth 指定的链接文本宽度的理想链接文本高度。结构的 cx 成员包含实际需要的链接文本宽度。

返回值

链接文本的首选高度（以像素为单位）。返回值与 SIZE 结构的 cy 成员的值相同。

备注

有关 GetIdealSize 方法的示例，请参阅 CLinkCtrl::Create 中的示例。

此方法将发送 LM_GETIDEALSIZE 消息，如 Windows SDK 中所述。

CLinkCtrl::GetItem

检索链接控件项的状态和属性。

BOOL GetItem(PLITEM pItem) const;

参数

pItem
指向 LITEM 结构的指针，用于接收项信息。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

注解

此成员函数实现 Win32 消息 LM_GETITEM 的行为，如 Windows SDK 中所述。

CLinkCtrl::GetItemID

检索链接控件项的 ID。

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

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

参数

iLink
链接控件项的索引。

strID
包含指定项 ID 的 CStringT 对象。

szID
包含指定项 ID 的以 null 结尾的字符串。

cchID
szID 缓冲区的大小（以字符为单位）。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

注意

如果 szID 或 strID 的缓冲区小于 MAX_LINKID_TEXT，此函数也会返回 FALSE。

注解

检索特定链接控件项的 ID。有关详细信息，请参阅 Windows SDK 中的 Win32 消息 LM_GETITEM。

CLinkCtrl::GetItemState

检索链接控件项的状态。

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

参数

iLink
链接控件项的索引。

pnState
指定状态项的值。

stateMask
描述要获取哪个状态项的标记组合。有关值列表，请参阅 LITEM 结构中 state 成员的说明。允许的项与 state 中允许的项相同。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

备注

检索特定链接控件项的指定状态项的值。有关详细信息，请参阅 Windows SDK 中的 Win32 消息 LM_GETITEM。

CLinkCtrl::GetItemUrl

检索链接控件项表示的 URL。

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

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

参数

iLink
链接控件项的索引。

strUrl
包含指定项所表示的 URL 的 CStringT 对象

szUrl
包含指定项所表示的 URL 的以 null 结尾的字符串

cchUrl
szURL 缓冲区的大小（以字符为单位）。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

注意

如果 szUrl 或 strUrl 的缓冲区小于 MAX_LINKID_TEXT，此函数也会返回 FALSE。

注解

检索指定链接控件项表示的 URL。有关详细信息，请参阅 Windows SDK 中的 Win32 消息 LM_GETITEM。

CLinkCtrl::HitTest

确定用户是否单击了指定链接。

BOOL HitTest(PLHITTESTINFO phti) const;

参数

phti
指向 LHITTESTINFO 结构的指针，其中包含有关用户单击的链接的所有信息。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

注解

此成员函数实现 Win32 消息 LM_HITTEST 的行为，如 Windows SDK 中所述。

CLinkCtrl::SetItem

设置链接控件项的状态和属性。

BOOL SetItem(PLITEM pItem);

参数

pItem
指向 LITEM 结构的指针，其中包含要设置的信息。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

注解

此成员函数实现 Win32 消息 LM_SETITEM 的行为，如 Windows SDK 中所述。

CLinkCtrl::SetItemID

检索链接控件项的 ID。

BOOL SetItemID(
    int iLink,
    LPCWSTR szID);

参数

iLink
链接控件项的索引。

szID
包含指定项 ID 的以 null 结尾的字符串。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

备注

设置特定链接控件项的 ID。有关详细信息，请参阅 Windows SDK 中的 Win32 消息 LM_SETITEM。

CLinkCtrl::SetItemState

检索链接控件项的状态。

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

参数

iLink
链接控件项的索引。

pnState
要设置的指定状态项的值。

stateMask
描述要设置的状态项的标记组合。有关值列表，请参阅 LITEM 结构中 state 成员的说明。允许的项与 state 中允许的项相同。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

备注

设置特定链接控件项的指定状态项的值。有关详细信息，请参阅 Windows SDK 中的 Win32 消息 LM_SETITEM。

CLinkCtrl::SetItemUrl

设置链接控件项表示的 URL。

BOOL SetItemUrl(
    int iLink,
    LPCWSTR szUrl);

参数

iLink
链接控件项的索引。

szUrl
包含指定项所表示的 URL 的以 null 结尾的字符串

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

注解

设置指定链接控件项表示的 URL。有关详细信息，请参阅 Windows SDK 中的 Win32 消息 LM_SETITEM。

另请参阅

层次结构图
 CWnd 类

通过

CLinkCtrl 类

语法

成员

公共构造函数

公共方法

备注

继承层次结构

要求

CLinkCtrl::CLinkCtrl

CLinkCtrl::Create

参数

返回值

备注

示例

CLinkCtrl::CreateEx

参数

返回值

备注

CLinkCtrl::GetIdealHeight

返回值

注解

CLinkCtrl::GetIdealSize

参数

返回值

备注

CLinkCtrl::GetItem

参数

返回值

注解

CLinkCtrl::GetItemID

参数

返回值

注解

CLinkCtrl::GetItemState

参数

返回值

备注

CLinkCtrl::GetItemUrl

参数

返回值

注解

CLinkCtrl::HitTest

参数

返回值

注解

CLinkCtrl::SetItem

参数

返回值

注解

CLinkCtrl::SetItemID

参数

返回值

备注

CLinkCtrl::SetItemState

参数

返回值

备注

CLinkCtrl::SetItemUrl

参数

返回值

注解

另请参阅

反馈

其他资源