CTabCtrl
类
提供 Windows 公共选项卡控件的功能。
语法
class CTabCtrl : public CWnd
成员
公共构造函数
名称 | 描述 |
---|---|
CTabCtrl::CTabCtrl |
构造 CTabCtrl 对象。 |
公共方法
备注
“选项卡控件”类似于笔记本中的分隔条或文件柜中的标签。 通过使用选项卡控件,应用程序可以为窗口或对话框的相同区域定义多个页。 每个页面由一组信息或控件组成,当用户选择相应的选项卡时,应用程序会显示这些信息或控件。一种特殊类型的选项卡控件显示类似于按钮的选项卡。 单击按钮应立即执行命令,而不是显示页面。
此控件(以及 CTabCtrl
类)仅适用于在 Windows 95/98 和 Windows NT 版本 3.51 及更高版本下运行的程序。
有关 CTabCtrl
的详细信息,请参阅控件和使用 CTabCtrl
。
继承层次结构
CTabCtrl
要求
标头:afxcmn.h
CTabCtrl::AdjustRect
计算给定窗口矩形的选项卡控件的显示区域,或计算对应于给定显示区域的窗口矩形。
void AdjustRect(BOOL bLarger, LPRECT lpRect);
参数
bLarger
指示要执行的操作。 如果此参数为 TRUE
,则 lpRect
指定一个显示矩形并接收相应的窗口矩形。 如果此参数为 FALSE
,则 lpRect
指定一个窗口矩形并接收相应的显示矩形。
lpRect
指向 RECT
结构的指针,该结构指定给定的矩形并接收计算出的矩形。
示例
void CTabDlg::OnSize(UINT nType, int cx, int cy)
{
CDialog::OnSize(nType, cx, cy);
if (m_TabCtrl.m_hWnd == NULL)
return; // Return if window is not created yet.
RECT rect;
// Get size of dialog window.
GetClientRect(&rect);
// Adjust the rectangle to fit the tab control into the
// dialog's client rectangle.
m_TabCtrl.AdjustRect(FALSE, &rect);
// Move the tab control to the new position and size.
m_TabCtrl.MoveWindow(&rect, TRUE);
}
CTabCtrl::Create
创建选项卡控件并将其附加到 CTabCtrl
对象的实例。
virtual BOOL Create(
DWORD dwStyle,
const RECT& rect,
CWnd* pParentWnd,
UINT nID);
参数
dwStyle
指定选项卡控件的样式。 应用 Windows SDK 中所述的选项卡控件样式的任意组合。 有关还可以应用于控件的窗口样式列表,请参阅“注解”。
rect
指定选项卡控件的大小和位置。 它可以是 CRect
对象或 RECT
结构。
pParentWnd
指定选项卡控件的父窗口,通常为 CDialog
。 不得为 NULL
。
nID
指定选项卡控件的 ID。
返回值
如果成功初始化对象,则为 TRUE
;否则为 FALSE
。
备注
请分两步构造 CTabCtrl
对象。 首先,调用构造函数,然后调用 Create
,这将创建选项卡控件并将其附加到 CTabCtrl
对象。
除了选项卡控件样式外,还可以将以下窗口样式应用于选项卡控件:
WS_CHILD
:创建表示选项卡控件的子窗口。 不能与 WS_POPUP 样式一起使用。WS_VISIBLE
:创建初始可见的选项卡控件。WS_DISABLED
:创建初始禁用的窗口。WS_GROUP
:指定一组控件中的第一个控件,用户可以在其中使用箭头键从一个控件移动到下一个控件。 在第一个控件之后使用WS_GROUP
样式定义的所有控件属于同一组。 具有WS_GROUP
样式的下一个控件结束样式组并开始下一个组(即,一个组在下一个开始的地方结束)。WS_TABSTOP
:指定任意数量的控件之一,用户可以使用 TAB 键在其中移动。 TAB 键将用户移动到由WS_TABSTOP
样式指定的下一个控件。
若要创建具有扩展窗口样式的选项卡控件,请调用 CTabCtrl::CreateEx
而不是 Create
。
示例
// Assuming you have a member variable m_TabCtrl, that is a CTabCtrl
// object, you can use the following to create a tab control.
m_TabCtrl.Create(TCS_TABS | TCS_FIXEDWIDTH | WS_CHILD | WS_VISIBLE,
rect, this, IDC_MYTAB);
// This creates a tab control with the given styles, and with
// an ID of IDC_MYTAB.
CTabCtrl::CreateEx
创建一个控件(子窗口)并将其与 CTabCtrl
对象相关联。
virtual BOOL CreateEx(
DWORD dwExStyle,
DWORD dwStyle,
const RECT& rect,
CWnd* pParentWnd,
UINT nID);
参数
dwExStyle
指定要创建的控件的扩展样式。 有关扩展 Windows 样式的列表,请参阅 Windows SDK 中 CreateWindowEx
的 dwExStyle
参数。
dwStyle
指定选项卡控件的样式。 应用 Windows SDK 中所述的选项卡控件样式的任意组合。 有关还可以应用于控件的窗口样式列表,请参阅 Create
中的“注解”。
rect
对 RECT
结构的引用,该结构描述了要在客户端坐标 pParentWnd
中创建的窗口的大小和位置。
pParentWnd
指向作为控件父级的窗口的指针。
nID
控件的子窗口 ID。
返回值
如果成功,则不为 0,否则为 0。
备注
使用 CreateEx
(而不是 Create
)应用由 Windows 扩展样式前缀 WS_EX_
指定的扩展 Windows 样式。
CreateEx
使用 dwExStyle
指定的扩展 Windows 样式创建控件。 使用 SetExtendedStyle
设置特定于控件的扩展样式。 例如,使用 CreateEx
将此类样式设置为 WS_EX_CONTEXTHELP
,但使用 SetExtendedStyle
将此类样式设置为 TCS_EX_FLATSEPARATORS
。 有关详细信息,请参阅 Windows SDK 的选项卡控件扩展样式中所述的样式。
CTabCtrl::CTabCtrl
构造 CTabCtrl
对象。
CTabCtrl();
CTabCtrl::DeleteAllItems
从选项卡控件中移除所有项。
BOOL DeleteAllItems();
返回值
如果成功,则不为 0;否则为 0。
CTabCtrl::DeleteItem
从选项卡控件中删除指定项。
BOOL DeleteItem(int nItem);
参数
nItem
要删除的项的从零开始的值。
返回值
如果成功,则不为 0;否则为 0。
示例
// This example assumes that there is a CTabCtrl member of the
// CTabDlg class named m_TabCtrl. On a button handler
// called OnDeleteItem of the dialog box the tab control will
// delete the 0 indexed item.
void CTabDlg::OnDeleteItem()
{
// Delete the first item in the tab control.
m_TabCtrl.DeleteItem(0);
}
CTabCtrl::DeselectAll
重置选项卡控件中的项,清除已按下的任何项。
void DeselectAll(BOOL fExcludeFocus);
参数
fExcludeFocus
指定项取消选择范围的标志。 如果此参数设置为 FALSE
,则将重置所有选项卡按钮。 如果设置为 TRUE
,则除当前已选定的选项卡项以外的所有选项卡项都将重置。
注解
此成员函数实现 Win32 消息 TCM_DESELECTALL
的行为,如 Windows SDK 中所述。
CTabCtrl::DrawItem
当所有者绘制的选项卡控件的可视特征发生变化时由框架调用。
virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);
参数
lpDrawItemStruct
指向描述要绘制的项的 DRAWITEMSTRUCT
结构的指针。
注解
DRAWITEMSTRUCT
结构的 itemAction
成员定义要执行的绘制操作。
默认情况下,此成员函数不执行任何操作。 替代此成员函数以实现所有者绘制 CTabCtrl
对象的绘制。
在此成员函数终止之前,应用程序应还原为 lpDrawItemStruct
中提供的显示上下文选择的所有图形设备接口 (GDI) 对象。
CTabCtrl::GetCurFocus
检索具有当前焦点的选项卡的索引。
int GetCurFocus() const;
返回值
具有当前焦点的选项卡的从零开始的索引。
CTabCtrl::GetCurSel
检索选项卡控件中当前选定的选项卡。
int GetCurSel() const;
返回值
如果成功,则为所选选项卡的从零开始的索引;如果未选择任何选项卡,则为 -1。
CTabCtrl::GetExtendedStyle
检索当前用于选项卡控件的扩展样式。
DWORD GetExtendedStyle();
返回值
表示当前用于选项卡控件的扩展样式。 此值是选项卡控件扩展样式的组合,如 Windows SDK 中所述。
备注
此成员函数实现 Win32 消息 TCM_GETEXTENDEDSTYLE
的行为,如 Windows SDK 中所述。
CTabCtrl::GetImageList
检索与选项卡控件关联的图像列表。
CImageList* GetImageList() const;
返回值
如果成功,则为指向选项卡控件的图像列表的指针;否则为 NULL
。
CTabCtrl::GetItem
检索有关选项卡控件中选项卡的信息。
BOOL GetItem(int nItem, TCITEM* pTabCtrlItem) const;
参数
nItem
选项卡的从零开始的索引。
pTabCtrlItem
指向 TCITEM
结构的指针,用于指定要检索的信息。 也用于接收有关选项卡的信息。此结构与 InsertItem
、GetItem
和 SetItem
成员函数一起使用。
返回值
如果成功,则返回 TRUE
;否则返回 FALSE
。
注解
发送消息时,mask
成员指定要返回的属性。 如果 mask
成员指定 TCIF_TEXT
值,则 pszText
成员必须包含接收项文本的缓冲区的地址,并且 cchTextMax
成员必须指定缓冲区的大小。
mask
指定要检索或设置的
TCITEM
结构成员的值。 此成员可以为零或以下值的组合:TCIF_TEXT
:成员pszText
有效。TCIF_IMAGE
:成员iImage
有效。TCIF_PARAM
:成员lParam
有效。TCIF_RTLREADING
:pszText
的文本在希伯来语或阿拉伯语系统上使用从右到左的阅读顺序显示。TCIF_STATE
:成员dwState
有效。
pszText
如果结构包含有关选项卡的信息,则为指向包含选项卡文本的以 null 结尾的字符串。如果结构正在接收信息,则此成员指定接收选项卡文本的缓冲区的地址。
cchTextMax
pszText
所指向的缓冲区大小。 如果结构未接收信息,则忽略此成员。iImage
选项卡控件图像列表中的索引,如果选项卡没有图像,则为 -1。lParam
与选项卡关联的应用程序定义数据。如果每个选项卡有超过 4 个字节的应用程序定义数据,应用程序必须定义一个结构并使用它而不是
TCITEM
结构。 应用程序定义结构的第一个成员必须是TCITEMHEADER
结构。TCITEMHEADER
结构与TCITEM
结构相同,但没有lParam
成员。 你的结构大小与TCITEMHEADER
结构大小之间的差异应等于每个选项卡的额外字节数。
示例
// In this example a CTabCtrl data member, m_TabCtrl, changes the
// text of the tabs in the tab control. A call to GetItem is used
// to get the current text, and then the text is changed. A call
// to SetItem is used to update the tab with the new text.
void CTabDlg::OnChangeItem()
{
TCITEM tcItem;
CString pszString;
// Get text for the tab item.
GetDlgItemText(IDC_ITEM_TEXT, pszString);
// Get the current tab item text.
TCHAR buffer[256] = {0};
tcItem.pszText = buffer;
tcItem.cchTextMax = 256;
tcItem.mask = TCIF_TEXT;
m_TabCtrl.GetItem(0, &tcItem);
TRACE(_T("Changing item text from %s to %s..."), tcItem.pszText, pszString);
// Set the new text for the item.
tcItem.pszText = pszString.LockBuffer();
// Set the item in the tab control.
m_TabCtrl.SetItem(0, &tcItem);
pszString.UnlockBuffer();
}
CTabCtrl::GetItemCount
检索选项卡控件中选项卡的数目。
int GetItemCount() const;
返回值
选项卡控件中的项数。
示例
请参阅 CPropertySheet::GetTabControl
的示例。
CTabCtrl::GetItemRect
检索选项卡控件中指定选项卡的边框。
BOOL GetItemRect(int nItem, LPRECT lpRect) const;
参数
nItem
该选项卡项的从零开始的索引。
lpRect
指向接收选项卡边框的 RECT
结构的指针。这些坐标使用视区的当前映射模式。
返回值
如果成功,则不为 0;否则为 0。
示例
请参阅 CPropertySheet::GetTabControl
的示例。
CTabCtrl::GetItemState
检索由 nItem
标识的选项卡控件项的状态。
DWORD GetItemState(
int nItem,
DWORD dwMask) const;
参数
nItem
要为其检索状态信息的项的从零开始的索引号。
dwMask
指定要返回的项状态标志的掩码。 有关值列表,请参阅 TCITEM
结构的掩码成员,如 Windows SDK 中所述。
返回值
对接收状态信息的 DWORD 值的引用。 可以是以下其中一个值:
值 | 说明 |
---|---|
TCIS_BUTTONPRESSED |
该选项卡控件项已选定。 |
TCIS_HIGHLIGHTED |
该选项卡控件项已突出显示,选项卡及文本使用当前突出显示颜色绘制。 使用突出显示颜色时,这将是一个真正的内插,而不是一种抖色。 |
备注
项的状态由 TCITEM
结构的 dwState
成员指定。
CTabCtrl::GetRowCount
检索选项卡控件中的当前行数。
int GetRowCount() const;
返回值
选项卡控件中的选项卡行数。
备注
只有具有 TCS_MULTILINE
样式的选项卡控件才能包含多行选项卡。
CTabCtrl::GetToolTips
检索与选项卡控件关联的工具提示控件的句柄。
CToolTipCtrl* GetToolTips() const;
返回值
如果成功,则为工具提示控件的句柄;否则为 NULL
。
备注
如果选项卡控件具有 TCS_TOOLTIPS
样式,则它会创建一个工具提示控件。 还可以使用 SetToolTips
成员函数将工具提示控件分配给选项卡控件。
CTabCtrl::HighlightItem
设置选项卡项的突出显示状态。
BOOL HighlightItem(int idItem, BOOL fHighlight = TRUE);
参数
idItem
选项卡控件项的从零开始的索引。
fHighlight
指定要设置的突出显示状态的值。 如果此值为 TRUE
,则突出显示该选项卡;如果为 FALSE
,则选项卡设置为其默认状态。
返回值
如果成功,则不为零,否则为零。
注解
此成员函数实现 Win32 消息 TCM_HIGHLIGHTITEM
,如 Windows SDK 中所述。
CTabCtrl::HitTest
确定哪个选项卡(如果有)位于指定的屏幕位置。
int HitTest(TCHITTESTINFO* pHitTestInfo) const;
参数
pHitTestInfo
指向 TCHITTESTINFO
结构的指针(如 Windows SDK 中所述),它指定要测试的屏幕位置。
返回值
返回选项卡的从零开始的索引,如果指定位置处没有选项卡,则返回 -1。
CTabCtrl::InsertItem
在现有选项卡控件中插入新选项卡。
LONG InsertItem(
int nItem,
TCITEM* pTabCtrlItem);
LONG InsertItem(
int nItem,
LPCTSTR lpszItem);
LONG InsertItem(
int nItem,
LPCTSTR lpszItem,
int nImage);
LONG InsertItem(
UINT nMask,
int nItem,
LPCTSTR lpszItem,
int nImage,
LPARAM lParam);
LONG InsertItem(
UINT nMask,
int nItem,
LPCTSTR lpszItem,
int nImage,
LPARAM lParam,
DWORD dwState,
DWORD dwStateMask);
参数
nItem
新选项卡的从零开始的索引。
pTabCtrlItem
指向指定选项卡属性的 TCITEM
结构的指针。
lpszItem
包含选项卡文本的以 null 结尾的字符串的地址。
nImage
要从图像列表中插入的图像的从零开始的索引。
nMask
指定要设置的 TCITEM
结构属性。 可以为零或以下值的组合:
TCIF_TEXT
:成员pszText
有效。TCIF_IMAGE
:成员iImage
有效。TCIF_PARAM
:成员lParam
有效。TCIF_RTLREADING
:pszText
的文本在希伯来语或阿拉伯语系统上使用从右到左的阅读顺序显示。TCIF_STATE
:成员dwState
有效。
lParam
与选项卡关联的应用程序定义数据。
dwState
指定项状态的值。 有关详细信息,请参阅 Windows SDK 中的 TCITEM
。
dwStateMask
指定要设置的状态。 有关详细信息,请参阅 Windows SDK 中的 TCITEM
。
返回值
如果成功,则为新选项卡的从零开始的索引;否则为 -1。
示例
TCITEM tcItem;
tcItem.mask = TCIF_TEXT;
tcItem.pszText = _T("Tab #1");
m_TabCtrl.InsertItem(0, &tcItem);
CTabCtrl::RemoveImage
从选项卡控件的图像列表中移除指定的图像。
void RemoveImage(int nImage);
参数
nImage
要移除的图像的从零开始的索引。
注解
选项卡控件更新每个选项卡的图像索引,以便每个选项卡保持与同一图像相关联。
CTabCtrl::SetCurFocus
将焦点设置为选项卡控件中的指定选项卡。
void SetCurFocus(int nItem);
参数
nItem
指定用于获取焦点的选项卡的索引。
备注
此成员函数实现 Win32 消息 TCM_SETCURFOCUS
的行为,如 Windows SDK 中所述。
CTabCtrl::SetCurSel
在选项卡控件中选择一个选项卡。
int SetCurSel(int nItem);
参数
nItem
要选择的项的从零开始的索引。
返回值
如果成功,则为先前选择的选项卡的从零开始的索引,否则为 -1。
备注
使用此函数选择选项卡时,选项卡控件不会发送 TCN_SELCHANGING
或 TCN_SELCHANGE
通知消息。 当用户单击或使用键盘更改选项卡时,将使用 WM_NOTIFY
发送这些通知。
CTabCtrl::SetExtendedStyle
设置选项卡控件的扩展样式。
DWORD SetExtendedStyle(DWORD dwNewStyle, DWORD dwExMask = 0);
参数
dwNewStyle
指定选项卡控件扩展样式的组合的值。
dwExMask
DWORD 值,该值指示 dwNewStyle
中将受影响的样式。 仅会更改 dwExMask
中的扩展样式。 所有其他样式将按原样保留。 如果此参数为零,则 dwNewStyle
中的所有样式都将受到影响。
返回值
DWORD 值,包含以前的选项卡控件扩展样式,如 Windows SDK 中所述。
备注
此成员函数实现 Win32 消息 TCM_SETEXTENDEDSTYLE
的行为,如 Windows SDK 中所述。
CTabCtrl::SetImageList
将图像列表分配给选项卡控件。
CImageList* SetImageList(CImageList* pImageList);
参数
pImageList
指向要分配给选项卡控件的图像列表的指针。
返回值
返回指向上一个图像列表的指针,如果没有上一个图像列表,则返回 NULL
。
CTabCtrl::SetItem
设置选项卡的部分或全部属性。
BOOL SetItem(int nItem, TCITEM* pTabCtrlItem);
参数
nItem
该项的从零开始的索引。
pTabCtrlItem
指向包含新项属性的 TCITEM
结构的指针。 mask
成员指定要设置的属性。 如果 mask
成员指定 TCIF_TEXT
值,则 pszText
成员是以 null 结尾的字符串的地址,并且 cchTextMax
成员将被忽略。
返回值
如果成功,则不为 0;否则为 0。
示例
请参阅 GetItem
的示例。
CTabCtrl::SetItemExtra
设置选项卡控件中为应用程序定义数据保留的每个选项卡的字节数。
BOOL SetItemExtra(int nBytes);
参数
nBytes
要设置的额外字节数。
返回值
如果成功,则不为零,否则为零。
备注
此成员函数实现 Win32 消息 TCM_SETITEMEXTRA
的行为,如 Windows SDK 中所述。
CTabCtrl::SetItemSize
设置选项卡控件项的宽度和高度。
CSize SetItemSize(CSize size);
参数
size
选项卡控件项的新宽度和高度(以像素为单位)。
返回值
返回选项卡控件项的旧宽度和高度。
CTabCtrl::SetItemState
设置由 nItem
标识的选项卡控件项的状态。
BOOL SetItemState(
int nItem,
DWORD dwMask,
DWORD dwState);
参数
nItem
要为其设置状态信息的项的从零开始的索引号。
dwMask
指定要设置的项状态标志的掩码。 有关值列表,请参阅 TCITEM
结构的掩码成员,如 Windows SDK 中所述。
dwState
对包含状态信息的 DWORD 值的引用。 可以是以下其中一个值:
值 | 说明 |
---|---|
TCIS_BUTTONPRESSED |
该选项卡控件项已选定。 |
TCIS_HIGHLIGHTED |
该选项卡控件项已突出显示,选项卡及文本使用当前突出显示颜色绘制。 使用突出显示颜色时,这将是一个真正的内插,而不是一种抖色。 |
返回值
如果成功,则不为 0;否则为 0。
CTabCtrl::SetMinTabWidth
设置选项卡控件中项的最小宽度。
int SetMinTabWidth(int cx);
参数
cx
要为选项卡控件项设置的最小宽度。 如果此参数设置为 -1,则控件将使用默认选项卡宽度。
返回值
上一个最小选项卡宽度。
备注
此成员函数实现 Win32 消息 TCM_SETMINTABWIDTH
的行为,如 Windows SDK 中所述。
CTabCtrl::SetPadding
设置选项卡控件中每个选项卡图标和标签周围的空间量(填充)。
void SetPadding(CSize size);
参数
size
设置选项卡控件中每个选项卡图标和标签周围的空间量(填充)。
CTabCtrl::SetToolTips
将工具提示控件分配给选项卡控件。
void SetToolTips(CToolTipCtrl* pWndTip);
参数
pWndTip
工具提示控件的句柄。
注解
可以通过调用 GetToolTips
来获取与选项卡控件关联的工具提示控件。
示例
请参阅 CPropertySheet::GetTabControl
的示例。