CTabCtrl Class

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CTabCtrl Class.

Provides the functionality of the Windows common tab control.

class CTabCtrl : public CWnd  

Public Constructors

NameDescription
CTabCtrl::CTabCtrlConstructs a CTabCtrl object.

Public Methods

NameDescription
CTabCtrl::AdjustRectCalculates a tab control's display area given a window rectangle, or calculates the window rectangle that would correspond to a given display area.
CTabCtrl::CreateCreates a tab control and attaches it to an instance of a CTabCtrl object.
CTabCtrl::CreateExCreates a tab control with the specified Windows extended styles and attaches it to an instance of a CTabCtrl object.
CTabCtrl::DeleteAllItemsRemoves all items from a tab control.
CTabCtrl::DeleteItemRemoves an item from a tab control.
CTabCtrl::DeselectAllResets items in a tab control, clearing any that were pressed.
CTabCtrl::DrawItemDraws a specified item of a tab control.
CTabCtrl::GetCurFocusRetrieves the tab with the current focus of a tab control.
CTabCtrl::GetCurSelDetermines the currently selected tab in a tab control.
CTabCtrl::GetExtendedStyleRetrieves the extended styles that are currently in use for the tab control.
CTabCtrl::GetImageListRetrieves the image list associated with a tab control.
CTabCtrl::GetItemRetrieves information about a tab in a tab control.
CTabCtrl::GetItemCountRetrieves the number of tabs in the tab control.
CTabCtrl::GetItemRectRetrieves the bounding rectangle for a tab in a tab control.
CTabCtrl::GetItemStateRetrieves the state of the indicated tab control item.
CTabCtrl::GetRowCountRetrieves the current number of rows of tabs in a tab control.
CTabCtrl::GetToolTipsRetrieves the handle of the tool tip control associated with a tab control.
CTabCtrl::HighlightItemSets the highlight state of a tab item.
CTabCtrl::HitTestDetermines which tab, if any, is at a specified screen position.
CTabCtrl::InsertItemInserts a new tab in a tab control.
CTabCtrl::RemoveImageRemoves an image from a tab control's image list.
CTabCtrl::SetCurFocusSets the focus to a specified tab in a tab control.
CTabCtrl::SetCurSelSelects a tab in a tab control.
CTabCtrl::SetExtendedStyleSets the extended styles for a tab control.
CTabCtrl::SetImageListAssigns an image list to a tab control.
CTabCtrl::SetItemSets some or all of a tab's attributes.
CTabCtrl::SetItemExtraSets the number of bytes per tab reserved for application-defined data in a tab control.
CTabCtrl::SetItemSizeSets the width and height of an item.
CTabCtrl::SetItemStateSets the state of the indicated tab control item.
CTabCtrl::SetMinTabWidthSets the minimum width of items in a tab control.
CTabCtrl::SetPaddingSets the amount of space (padding) around each tab's icon and label in a tab control.
CTabCtrl::SetToolTipsAssigns a tool tip control to a tab control.

A "tab control" is analogous to the dividers in a notebook or the labels in a file cabinet. By using a tab control, an application can define multiple pages for the same area of a window or dialog box. Each page consists of a set of information or a group of controls that the application displays when the user selects the corresponding tab. A special type of tab control displays tabs that look like buttons. Clicking a button should immediately perform a command instead of displaying a page.

This control (and therefore the CTabCtrl class) is available only to programs running under Windows 95/98 and Windows NT version 3.51 and later.

For more information on using CTabCtrl, see Controls and Using CTabCtrl.

CObject

CCmdTarget

CWnd

CTabCtrl

Header: afxcmn.h

Calculates a tab control's display area given a window rectangle, or calculates the window rectangle that would correspond to a given display area.

void AdjustRect(BOOL bLarger,   LPRECT lpRect);

Parameters

bLarger
Indicates which operation to perform. If this parameter is TRUE, lpRect specifies a display rectangle and receives the corresponding window rectangle. If this parameter is FALSE, lpRect specifies a window rectangle and receives the corresponding display rectangle.

lpRect
Pointer to a RECT structure that specifies the given rectangle and receives the calculated rectangle.

Example

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

Creates a tab control and attaches it to an instance of a CTabCtrl object.

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

Parameters

dwStyle
Specifies the tab control's style. Apply any combination of tab control styles, described in the Windows SDK. See Remarks for a list of window styles that you can also apply to the control.

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

pParentWnd
Specifies the tab control's parent window, usually a CDialog. It must not be NULL.

nID
Specifies the tab control's ID.

Return Value

TRUE if initialization of the object was successful; otherwise FALSE.

Remarks

You construct a CTabCtrl object in two steps. First, call the constructor, and then call Create, which creates the tab control and attaches it to the CTabCtrl object.

In addition to tab control styles, you can apply the following window styles to a tab control:

  • WS_CHILD Creates a child window that represents the tab control. Cannot be used with the WS_POPUP style.

  • WS_VISIBLE Creates a tab control that is initially visible.

  • WS_DISABLED Creates a window that is initially disabled.

  • WS_GROUP Specifies the first control of a group of controls in which the user can move from one control to the next with the arrow keys. All controls defined with the WS_GROUP style after the first control belong to the same group. The next control with the WS_GROUP style ends the style group and starts the next group (that is, one group ends where the next begins).

  • WS_TABSTOP Specifies one of any number of controls through which the user can move by using the TAB key. The TAB key moves the user to the next control specified by the WS_TABSTOP style.

To create a tab control with extended window styles, call CTabCtrl::CreateEx instead of Create.

Example

   // 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.

Creates a control (a child window) and associates it with the CTabCtrl object.

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

Parameters

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

dwStyle
Specifies the tab control's style. Apply any combination of tab control styles, described in the Windows SDK. See Remarks in Create for a list of window styles that you can also apply to the control.

rect
A reference to a RECT structure describing the size and position of the window to be created, in client coordinates of pParentWnd.

pParentWnd
A pointer to the window that is the control's parent.

nID
The control's child-window ID.

Return Value

Nonzero if successful otherwise 0.

Remarks

Use CreateEx instead of Create to apply extended Windows styles, specified by the Windows extended style preface WS_EX_.

CreateEx creates the control with the extended Windows styles specified by dwExStyle. Set extended styles specific to a control using SetExtendedStyle. For example, use CreateEx to set such styles as WS_EX_CONTEXTHELP, but use SetExtendedStyle to set such styles as TCS_EX_FLATSEPARATORS. For more information, see the styles described in Tab Control Extended Styles in the Windows SDK.

Constructs a CTabCtrl object.

CTabCtrl();

Removes all items from a tab control.

BOOL DeleteAllItems();

Return Value

Nonzero if successful; otherwise 0.

Removes the specified item from a tab control.

BOOL DeleteItem(int nItem);

Parameters

nItem
Zero-based value of the item to delete.

Return Value

Nonzero if successful; otherwise 0.

Example

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

Resets items in a tab control, clearing any that were pressed.

void DeselectAll(BOOL fExcludeFocus);

Parameters

fExcludeFocus
Flag that specifies the scope of the item deselection. If this parameter is set to FALSE, all tab buttons will be reset. If it is set to TRUE, then all tab items except for the one currently selected will be reset.

Remarks

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

Called by the framework when a visual aspect of an owner-draw tab control changes.

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

Parameters

lpDrawItemStruct
A pointer to a DRAWITEMSTRUCT structure describing the item to be painted.

Remarks

The itemAction member of the DRAWITEMSTRUCT structure defines the drawing action that is to be performed.

By default, this member function does nothing. Override this member function to implement drawing for an owner-draw CTabCtrl object.

The application should restore all graphics device interface (GDI) objects selected for the display context supplied in lpDrawItemStruct before this member function terminates.

Retrieves the index of the tab with the current focus.

int GetCurFocus() const;  

Return Value

The zero-based index of the tab with the current focus.

Retrieves the currently selected tab in a tab control.

int GetCurSel() const;  

Return Value

Zero-based index of the selected tab if successful or – 1 if no tab is selected.

Retrieves the extended styles that are currently in use for the tab control.

DWORD GetExtendedStyle();

Return Value

Represents the extended styles currently in use for the tab control. This value is a combination of tab control extended styles, as described in the Windows SDK.

Remarks

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

Retrieves the image list that's associated with a tab control.

CImageList* GetImageList() const;  

Return Value

If successful, a pointer to the image list of the tab control; otherwise, NULL.

Retrieves information about a tab in a tab control.

BOOL GetItem(int nItem,   TCITEM* pTabCtrlItem) const;  

Parameters

nItem
Zero-based index of the tab.

pTabCtrlItem
Pointer to a TCITEM structure, used to specify the information to retrieve. Also used to receive information about the tab. This structure is used with the InsertItem, GetItem, and SetItem member functions.

Return Value

Returns TRUE if successful; FALSE otherwise.

Remarks

When the message is sent, the mask member specifies which attributes to return. If the mask member specifies the TCIF_TEXT value, the pszText member must contain the address of the buffer that receives the item text and the cchTextMax member must specify the size of the buffer.

mask
Value specifying which TCITEM structure members to retrieve or set. This member can be zero or a combination of the following values:

  • TCIF_TEXT The pszText member is valid.

  • TCIF_IMAGE The iImage member is valid.

  • TCIF_PARAM The lParam member is valid.

  • TCIF_RTLREADING The text of pszText is displayed using right-to-left reading order on Hebrew or Arabic systems.

  • TCIF_STATE The dwState member is valid.

pszText
Pointer to a null-terminated string containing the tab text if the structure contains information about a tab. If the structure is receiving information, this member specifies the address of the buffer that receives the tab text.

cchTextMax
Size of the buffer pointed to by pszText. This member is ignored if the structure is not receiving information.

iImage
Index into the tab control's image list, or – 1 if there is no image for the tab.

lParam
Application-defined data associated with the tab. If there are more than four bytes of application-defined data per tab, an application must define a structure and use it instead of the TCITEM structure. The first member of the application-defined structure must be a TCITEMHEADERstructure. The TCITEMHEADER structure is identical to the TCITEM structure, but without the lParam member. The difference between the size of your structure and the size of the TCITEMHEADER structure should equal the number of extra bytes per tab.

Example

// 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();
}

Retrieves the number of tabs in the tab control.

int GetItemCount() const;  

Return Value

Number of items in the tab control.

Example

See the example for CPropertySheet::GetTabControl.

Retrieves the bounding rectangle for the specified tab in a tab control.

BOOL GetItemRect(int nItem,   LPRECT lpRect) const;  

Parameters

nItem
Zero-based index of the tab item.

lpRect
Pointer to a RECT structure that receives the bounding rectangle of the tab. These coordinates use the viewport's current mapping mode.

Return Value

Nonzero if successful; otherwise 0.

Example

See the example for CPropertySheet::GetTabControl.

Retrieves the state of the tab control item identified by nItem.

DWORD GetItemState(
    int nItem,  
    DWORD dwMask) const;  

Parameters

nItem
The zero-based index number of the item for which to retrieve state information.

dwMask
Mask specifying which of the item's state flags to return. For a list of values, see the mask member of the TCITEM structure, as described in the Windows SDK.

Return Value

A reference to a DWORD value receiving the state information. Can be one of the following values:

ValueDescription
TCIS_BUTTONPRESSEDThe tab control item is selected.
TCIS_HIGHLIGHTEDThe tab control item is highlighted, and the tab and text are drawn using the current highlight color. When using highlight color, this will be a true interpolation, not a dithered color.

Remarks

An item's state is specified by the dwState member of the TCITEM structure.

Retrieves the current number of rows in a tab control.

int GetRowCount() const;  

Return Value

The number of rows of tabs in the tab control.

Remarks

Only tab controls that have the TCS_MULTILINE style can have multiple rows of tabs.

Retrieves the handle of the tool tip control associated with a tab control.

CToolTipCtrl* GetToolTips() const;  

Return Value

Handle of the tool tip control if successful; otherwise NULL.

Remarks

A tab control creates a tool tip control if it has the TCS_TOOLTIPS style. You can also assign a tool tip control to a tab control by using the SetToolTips member function.

Sets the highlight state of a tab item.

BOOL HighlightItem(int idItem,   BOOL fHighlight = TRUE);

Parameters

idItem
Zero-based index of a tab control item.

fHighlight
Value specifying the highlight state to be set. If this value is TRUE, the tab is highlighted; if FALSE, the tab is set to its default state.

Return Value

Nonzero if successful; otherwise zero.

Remarks

This member function implements the Win32 message TCM_HIGHLIGHTITEM, as described in the Windows SDK.

Determines which tab, if any, is at the specified screen position.

int HitTest(TCHITTESTINFO* pHitTestInfo) const;  

Parameters

pHitTestInfo
Pointer to a TCHITTESTINFO structure, as described in the Windows SDK, which specifies the screen position to test.

Return Value

Returns the zero-based index of the tab or – 1 if no tab is at the specified position.

Inserts a new tab in an existing tab control.

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

Parameters

nItem
Zero-based index of the new tab.

pTabCtrlItem
Pointer to a TCITEM structure that specifies the attributes of the tab.

lpszItem
Address of a null-terminated string that contains the text of the tab.

nImage
The zero-based index of an image to insert from an image list.

nMask
Specifies which TCITEM structure attributes to set. Can be zero or a combination of the following values:

  • TCIF_TEXT The pszText member is valid.

  • TCIF_IMAGE The iImage member is valid.

  • TCIF_PARAM The lParam member is valid.

  • TCIF_RTLREADING The text of pszText is displayed using right-to-left reading order on Hebrew or Arabic systems.

  • TCIF_STATE The dwState member is valid.

lParam
Application-defined data associated with the tab.

dwState
Specifies values for the item's states. For more information, see TCITEM in the Windows SDK.

dwStateMask
Specifies which states are to be set. For more information, see TCITEM in the Windows SDK.

Return Value

Zero-based index of the new tab if successful; otherwise – 1.

Example

   TCITEM tcItem;
   tcItem.mask = TCIF_TEXT;
   tcItem.pszText = _T("Tab #1");

   m_TabCtrl.InsertItem(0, &tcItem);

Removes the specified image from a tab control's image list.

void RemoveImage(int nImage);

Parameters

nImage
Zero-based index of the image to remove.

Remarks

The tab control updates each tab's image index so that each tab remains associated with the same image.

Sets the focus to a specified tab in a tab control.

void SetCurFocus(int nItem);

Parameters

nItem
Specifies the index of the tab that gets the focus.

Remarks

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

Selects a tab in a tab control.

int SetCurSel(int nItem);

Parameters

nItem
The zero-based index of the item to be selected.

Return Value

Zero-based index of the previously selected tab if successful, otherwise – 1.

Remarks

A tab control does not send a TCN_SELCHANGING or TCN_SELCHANGE notification message when a tab is selected using this function. These notifications are sent, using WM_NOTIFY, when the user clicks or uses the keyboard to change tabs.

Sets the extended styles for a tab control.

DWORD SetExtendedStyle(DWORD dwNewStyle,   DWORD dwExMask = 0);

Parameters

dwNewStyle
Value specifying a combination of tab control extended styles.

dwExMask
A DWORD value that indicates which styles in dwNewStyle are to be affected. Only the extended styles in dwExMask will be changed. All other styles will be maintained as is. If this parameter is zero, then all of the styles in dwNewStyle will be affected.

Return Value

A DWORD value that contains the previous tab control extended styles, as described in the Windows SDK.

Return Value

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

Assigns an image list to a tab control.

CImageList* SetImageList(CImageList* pImageList);

Parameters

pImageList
Pointer to the image list to be assigned to the tab control.

Return Value

Returns a pointer to the previous image list or NULL if there is no previous image list.

Sets some or all of a tab's attributes.

BOOL SetItem(int nItem,   TCITEM* pTabCtrlItem);

Parameters

nItem
Zero-based index of the item.

pTabCtrlItem
Pointer to a TCITEM structure that contains the new item attributes. The mask member specifies which attributes to set. If the mask member specifies the TCIF_TEXT value, the pszText member is the address of a null-terminated string and the cchTextMax member is ignored.

Return Value

Nonzero if successful; otherwise 0.

Example

See the example for GetItem.

Sets the number of bytes per tab reserved for application-defined data in a tab control.

BOOL SetItemExtra(int nBytes);

Parameters

nBytes
The number of extra bytes to set.

Return Value

Nonzero if successful; otherwise zero.

Remarks

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

Sets the width and height of the tab control items.

CSize SetItemSize(CSize size);

Parameters

size
The new width and height, in pixels, of the tab control items.

Return Value

Returns the old width and height of the tab control items.

Sets the state of the tab control item identified by nItem.

BOOL SetItemState(
    int nItem,
    DWORD dwMask,
    DWORD dwState);

Parameters

nItem
The zero-based index number of the item for which to set state information.

dwMask
Mask specifying which of the item's state flags to set. For a list of values, see the mask member of the TCITEM structure, as described in the Windows SDK.

dwState
A reference to a DWORD value containing the state information. Can be one of the following values:

ValueDescription
TCIS_BUTTONPRESSEDThe tab control item is selected.
TCIS_HIGHLIGHTEDThe tab control item is highlighted, and the tab and text are drawn using the current highlight color. When using highlight color, this will be a true interpolation, not a dithered color.

Return Value

Nonzero if successful; otherwise 0.

Sets the minimum width of items in a tab control.

int SetMinTabWidth(int cx);

Parameters

cx
Minimum width to be set for a tab control item. If this parameter is set to -1, the control will use the default tab width.

Return Value

The previous minimum tab width.

Return Value

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

Sets the amount of space (padding) around each tab's icon and label in a tab control.

void SetPadding(CSize size);

Parameters

size
Sets the amount of space (padding) around each tab's icon and label in a tab control.

Assigns a tool tip control to a tab control.

void SetToolTips(CToolTipCtrl* pWndTip);

Parameters

pWndTip
Handle of the tool tip control.

Remarks

You can get the tool tip control associated with a tab control by making a call to GetToolTips.

Example

See the example for CPropertySheet::GetTabControl.

CWnd Class
Hierarchy Chart
CHeaderCtrl Class
CListCtrl Class

Show: