CLinkCtrl 類別

文章
08/04/2024

提供 Windows 通用 SysLink 控制項的功能。

語法

class CLinkCtrl : public CWnd

成員

公用建構函式

名稱	描述
CLinkCtrl：：CLinkCtrl	建構 `CLinkCtrl` 物件。

公用方法

名稱	描述
CLinkCtrl：：Create	建立連結控件，並將它附加至 `CLinkCtrl` 物件。
CLinkCtrl：：CreateEx	建立具有擴充樣式的連結控件，並將它附加至 `CLinkCtrl` 物件。
CLinkCtrl：：GetIdealHeight	擷取連結控件的理想高度。
CLinkCtrl：：GetIdealSize	根據連結的指定寬度，計算目前連結控件的連結文字慣用高度。
CLinkCtrl：：GetItem	擷取連結控件專案的狀態和屬性。
CLinkCtrl：：GetItemID	擷取連結控件項目的標識碼。
CLinkCtrl：：GetItemState	擷取連結控件項目的狀態。
CLinkCtrl：：GetItemUrl	擷取連結控件專案所代表的URL。
CLinkCtrl：：HitTest	判斷使用者是否按下指定的連結。
CLinkCtrl：：SetItem	設定連結控制項項目的狀態和屬性。
CLinkCtrl：：SetItemID	設定連結控制項項目的識別碼。
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
指定連結控制件的識別碼。

傳回值

如果初始化成功，則為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
指定連結控制件的識別碼。

傳回值

如果初始化成功，則為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 結構的指標。當這個方法傳回時，結構的 cy 成員SIZE會包含 cxMaxWidth 所指定連結文字寬度的理想連結文字高度。結構的 cx 成員包含實際需要的連結文字寬度。

傳回值

連結文字的慣用高度，以像素為單位。傳回值與結構 cy 成員SIZE的值相同。

備註

如需方法GetIdealSize的範例，請參閱 CLinkCtrl：：Create 中的範例。

這個方法會傳送 windows SDK 中所述的 LM_GETIDEALSIZE訊息。

CLinkCtrl：：GetItem

擷取連結控件專案的狀態和屬性。

BOOL GetItem(PLITEM pItem) const;

參數

pItem
要接收專案資訊的 LITEM 結構的指標。

傳回值

在成功時傳回 TRUE，失敗時傳回 FALSE。

備註

此成員函式會實作 Win32 訊息 LM_GETITEM的行為，如 Windows SDK 中所述。

CLinkCtrl：：GetItemID

擷取連結控件項目的標識碼。

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

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

參數

iLink
連結控制件專案的索引。

strID
包含指定專案識別碼的 CStringT 物件。

szID
包含指定專案識別碼的 Null 終止字串。

cchID
szID 緩衝區的字元大小。

傳回值

在成功時傳回 TRUE，失敗時傳回 FALSE。

注意

如果 szID 或 strID 的緩衝區小於 MAX_LINKID_TEXT，則此函式也會傳回 FALSE。

備註

擷取特定連結控制項專案的識別碼。如需詳細資訊，請參閱 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
CStringT 物件，包含指定專案所代表的 URL

szUrl
以 Null 結束的字串，包含指定專案所表示的 URL

cchUrl
szURL 緩衝區的字元大小。

傳回值

在成功時傳回 TRUE，失敗時傳回 FALSE。

注意

如果 szUrl 或 strUrl 的緩衝區小於 MAX_LINKID_TEXT，則此函式也會傳回 FALSE。

備註

擷取指定連結控制項專案所代表的網址。如需詳細資訊，請參閱 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

擷取連結控件項目的標識碼。

BOOL SetItemID(
    int iLink,
    LPCWSTR szID);

參數

iLink
連結控制件專案的索引。

szID
包含指定專案識別碼的 Null 終止字串。

傳回值

在成功時傳回 TRUE，失敗時傳回 FALSE。

備註

設定特定連結控制件專案的識別碼。如需詳細資訊，請參閱 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
以 Null 結束的字串，包含指定專案所表示的 URL

傳回值

在成功時傳回 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

參數

傳回值

備註

另請參閱

意見反映

更多資源