CLinkCtrl Class

Article
08/06/2021

Provides the functionality of the Windows common SysLink control.

Syntax

class CLinkCtrl : public CWnd

Members

Public Constructors

Name	Description
CLinkCtrl::CLinkCtrl	Constructs a `CLinkCtrl` object.

Public Methods

Name	Description
CLinkCtrl::Create	Creates a link control and attaches it to a `CLinkCtrl` object.
CLinkCtrl::CreateEx	Creates a link control with extended styles and attaches it to a `CLinkCtrl` object.
CLinkCtrl::GetIdealHeight	Retrieves the ideal height of the link control.
CLinkCtrl::GetIdealSize	Calculates the preferred height of the link text for the current link control, depending on the specified width of the link.
CLinkCtrl::GetItem	Retrieves the states and attributes of a link control item.
CLinkCtrl::GetItemID	Retrieves the ID of a link control item.
CLinkCtrl::GetItemState	Retrieves the state of the link control item.
CLinkCtrl::GetItemUrl	Retrieves the URL represented by the link control item.
CLinkCtrl::HitTest	Determines whether the user clicked the specified link.
CLinkCtrl::SetItem	Sets the states and attributes of a link control item.
CLinkCtrl::SetItemID	Sets the ID of a link control item.
CLinkCtrl::SetItemState	Sets the state of the link control item.
CLinkCtrl::SetItemUrl	Sets the URL represented by the link control item.

Remarks

A "link control" provides a convenient way to embed hypertext links in a window. The actual control is a window that renders marked-up text and launches appropriate applications when the user clicks an embedded link. Multiple links are supported within one control and can be accessed by a zero-based index.

This control (and therefore the CLinkCtrl class) is available only to programs running under Windows XP and later.

For more information, see SysLink Control in the Windows SDK.

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CLinkCtrl

Requirements

Header: afxcmn.h

CLinkCtrl::CLinkCtrl

Constructs a CLinkCtrl object.

CLinkCtrl();

CLinkCtrl::Create

Creates a link control and attaches it to a CLinkCtrl object.

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

Parameters

lpszLinkMarkup
Pointer to a zero-terminated string that contains the marked up text to display. For more information, see the section "Markup and Link Access" in the topic Overview of SysLink Controls.

dwStyle
Specifies the link control's style. Apply any combination of control styles. See Common Control Styles in the Windows SDK for more information.

rect
Specifies the link control's size and position. It can be either a CRect object or a RECT structure.

pParentWnd
Specifies the link control's parent window. It must not be NULL.

nID
Specifies the link control's ID.

Return Value

TRUE if initialization was successful; otherwise FALSE.

Remarks

You construct a CLinkCtrl object in two steps. First, call the constructor and then call Create, which creates the link control and attaches it to the CLinkCtrl object. If you want to use extended windows styles with your control, call CLinkCtrl::CreateEx instead of Create.

The second form of the Create method is deprecated. Use the first form that specifies the lpszLinkMarkup parameter.

Example

The first code example defines two variables, named m_Link1 and m_Link2, that are used to access two link controls.

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;

The next code example creates one link control based on the location of another link control. The resource loader creates the first link control when your application starts. When your application enters the OnInitDialog method, you create the second link control relative to the position of the first link control. Then you resize the second link control to fit the text that it displays.

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

Creates a link control with extended styles and attaches it to a CLinkCtrl object.

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

Parameters

dwExStyle
Specifies the extended style of the link control. For a list of extended Windows styles, see the dwExStyle parameter for CreateWindowEx in the Windows SDK.

dwStyle
Specifies the link control's style. Apply any combination of control styles. For more information, see Common Control Styles in the Windows SDK.

rect
Specifies the link control's size and position. It can be either a CRect object or a RECT structure.

pParentWnd
Specifies the link control's parent window. It must not be NULL.

nID
Specifies the link control's ID.

Return Value

TRUE if initialization was successful; otherwise FALSE.

Remarks

Use CreateEx instead of Create to apply extended Windows style constants.

The second form of the CreateEx method is deprecated. Use the first form that specifies the lpszLinkMarkup parameter.

CLinkCtrl::GetIdealHeight

Retrieves the ideal height of the link control.

int GetIdealHeight() const;

Return Value

The ideal height of the control, in pixels.

Remarks

This member function implements the behavior of the Win32 message LM_GETIDEALHEIGHT, as described in the Windows SDK.

CLinkCtrl::GetIdealSize

Calculates the preferred height of the link text for the current link control, depending on the specified width of the link.

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

Parameters

cxMaxWidth
[in] The maximum width of the link, in pixels.

pSize
[out] A pointer to a Windows SIZE structure. When this method returns, the cy member of the SIZE structure contains the ideal link text height for the link text width that is specified by cxMaxWidth. The cx member of the structure contains the link text width that is actually needed.

Return Value

The preferred height of the link text, in pixels. The return value is the same as the value of the cy member of the SIZE structure.

Remarks

For an example of the GetIdealSize method, see the example in CLinkCtrl::Create.

This method sends the LM_GETIDEALSIZE message, which is described in the Windows SDK.

CLinkCtrl::GetItem

Retrieves the states and attributes of a link control item.

BOOL GetItem(PLITEM pItem) const;

Parameters

pItem
A pointer to a LITEM structure to receive item information.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

This member function implements the behavior of the Win32 message LM_GETITEM, as described in the Windows SDK.

CLinkCtrl::GetItemID

Retrieves the ID of a link control item.

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

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

Parameters

iLink
The index of a link control item.

strID
A CStringT object containing the ID of the specified item.

szID
A null-terminated string containing the ID of the specified item.

cchID
The size in characters of the szID buffer.

Return Value

Returns TRUE on success, FALSE on failure.

Note

This function also returns FALSE if the buffer of szID or strID is smaller than MAX_LINKID_TEXT.

Remarks

Retrieves the ID of a specific link control item. For more information, see the Win32 message LM_GETITEM in the Windows SDK.

CLinkCtrl::GetItemState

Retrieves the state of the link control item.

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

Parameters

iLink
The index of a link control item.

pnState
The value of the specified state item.

stateMask
Combination of flags describing which state item to get. For a list of values, see the description of the state member in the LITEM structure. Allowable items are identical to those allowed in state.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

Retrieves the value of the specified state item of a specific link control item. For more information, see the Win32 message LM_GETITEM in the Windows SDK.

CLinkCtrl::GetItemUrl

Retrieves the URL represented by the link control item.

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

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

Parameters

iLink
The index of a link control item.

strUrl
A CStringT object containing the URL represented by the specified item

szUrl
A null-terminated string containing the URL represented by the specified item

cchUrl
The size in characters of the szURL buffer.

Return Value

Returns TRUE on success, FALSE on failure.

Note

This function also returns FALSE if the buffer of szUrl or strUrl is smaller than MAX_LINKID_TEXT.

Remarks

Retrieves the URL represented by the specified link control item. For more information, see the Win32 message LM_GETITEM in the Windows SDK.

CLinkCtrl::HitTest

Determines if the user clicked the specified link.

BOOL HitTest(PLHITTESTINFO phti) const;

Parameters

phti
Pointer to a LHITTESTINFO structure containing any information about the link the user clicked.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

This member function implements the behavior of the Win32 message LM_HITTEST, as described in the Windows SDK.

CLinkCtrl::SetItem

Sets the states and attributes of a link control item.

BOOL SetItem(PLITEM pItem);

Parameters

pItem
A pointer to a LITEM structure containing the information to set.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

This member function implements the behavior of the Win32 message LM_SETITEM, as described in the Windows SDK.

CLinkCtrl::SetItemID

Retrieves the ID of a link control item.

BOOL SetItemID(
    int iLink,
    LPCWSTR szID);

Parameters

iLink
The index of a link control item.

szID
A null-terminated string containing the ID of the specified item.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

Sets the ID of a specific link control item. For more information, see the Win32 message LM_SETITEM in the Windows SDK.

CLinkCtrl::SetItemState

Retrieves the state of the link control item.

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

Parameters

iLink
The index of a link control item.

pnState
The value of the specified state item being set.

stateMask
Combination of flags describing the state item being set. For a list of values, see the description of the state member in the LITEM structure. Allowable items are identical to those allowed in state.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

Sets the value of the specified state item of a specific link control item. For more information, see the Win32 message LM_SETITEM in the Windows SDK.

CLinkCtrl::SetItemUrl

Sets the URL represented by the link control item.

BOOL SetItemUrl(
    int iLink,
    LPCWSTR szUrl);

Parameters

iLink
The index of a link control item.

szUrl
A null-terminated string containing the URL represented by the specified item

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

Sets the URL represented by the specified link control item. For more information, see the Win32 message LM_SETITEM in the Windows SDK.

CLinkCtrl Class

Syntax

Members

Public Constructors

Public Methods

Remarks

Inheritance Hierarchy

Requirements

CLinkCtrl::CLinkCtrl

CLinkCtrl::Create

Parameters

Return Value

Remarks

Example

CLinkCtrl::CreateEx

Parameters

Return Value

Remarks

CLinkCtrl::GetIdealHeight

Return Value

Remarks

CLinkCtrl::GetIdealSize

Parameters

Return Value

Remarks

CLinkCtrl::GetItem

Parameters

Return Value

Remarks

CLinkCtrl::GetItemID

Parameters

Return Value

Remarks

CLinkCtrl::GetItemState

Parameters

Return Value

Remarks

CLinkCtrl::GetItemUrl

Parameters

Return Value

Remarks

CLinkCtrl::HitTest

Parameters

Return Value

Remarks

CLinkCtrl::SetItem

Parameters

Return Value

Remarks

CLinkCtrl::SetItemID

Parameters

Return Value

Remarks

CLinkCtrl::SetItemState

Parameters

Return Value

Remarks

CLinkCtrl::SetItemUrl

Parameters

Return Value

Remarks

See also

Feedback

Feedback

Additional resources