Edit

CTabCtrl Class

  • Article

Provides the functionality of the Windows common tab control.

Syntax

class CTabCtrl : public CWnd

Members

Public constructors

Name Description
CTabCtrl::CTabCtrl Constructs a CTabCtrl object.

Public methods

Name Description
CTabCtrl::AdjustRect Calculates a tab control's display area given a window rectangle, or calculates the window rectangle that would correspond to a given display area.
CTabCtrl::Create Creates a tab control and attaches it to an instance of a TabCtrl object
CTabCtrl::CreateEx Creates a tab control with the specified Windows extended styles and attaches it to an instance of a CTabCtrl object.
CTabCtrl::DeleteAllItems Removes all items from a tab control.
CTabCtrl::DeleteItem Removes an item from a tab control.
CTabCtrl::DeselectAll Resets items in a tab control, clearing any that were pressed.
CTabCtrl::DrawItem Draws a specified item of a tab control.
CTabCtrl::GetCurFocus Retrieves the tab with the current focus of a tab control.
CTabCtrl::GetCurSel Determines the currently selected tab in a tab control.
CTabCtrl::GetExtendedStyle Retrieves the extended styles that are currently in use for the tab control.
CTabCtrl::GetImageList Retrieves the image list associated with a tab control.
CTabCtrl::GetItem Retrieves information about a tab in a tab control.
CTabCtrl::GetItemCount Retrieves the number of tabs in the tab control.
CTabCtrl::GetItemRect Retrieves the bounding rectangle for a tab in a tab control.
CTabCtrl::GetItemState Retrieves the state of the indicated tab control item.
CTabCtrl::GetRowCount Retrieves the current number of rows of tabs in a tab control.
CTabCtrl::GetToolTips Retrieves the handle of the tool tip control associated with a tab control.
CTabCtrl::HighlightItem Sets the highlight state of a tab item.
CTabCtrl::HitTest Determines which tab, if any, is at a specified screen position.
CTabCtrl::InsertItem Inserts a new tab in a tab control.
CTabCtrl::RemoveImage Removes an image from a tab control's image list.
CTabCtrl::SetCurFocus Sets the focus to a specified tab in a tab control.
CTabCtrl::SetCurSel Selects a tab in a tab control.
CTabCtrl::SetExtendedStyle Sets the extended styles for a tab control.
CTabCtrl::SetImageList Assigns an image list to a tab control.
CTabCtrl::SetItem Sets some or all of a tab's attributes.
CTabCtrl::SetItemExtra Sets the number of bytes per tab reserved for application-defined data in a tab control.
CTabCtrl::SetItemSize Sets the width and height of an item.
CTabCtrl::SetItemState Sets the state of the indicated tab control item.
CTabCtrl::SetMinTabWidth Sets the minimum width of items in a tab control.
CTabCtrl::SetPadding Sets the amount of space (padding) around each tabs icon and label in a tab control.
CTabCtrl::SetToolTips Assigns a tool tip control to a tab control.

Remarks

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 about CTabCtrl, see Controls and Using CTabCtrl.

Inheritance hierarchy

CObject
CCmdTarget
CWnd

CTabCtrl

Requirements

Header: afxcmn.h

CTabCtrl::AdjustRect

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

CTabCtrl::Create

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.

CTabCtrl::CreateEx

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.

CTabCtrl::CTabCtrl

Constructs a CTabCtrl object.

CTabCtrl();

CTabCtrl::DeleteAllItems

Removes all items from a tab control.

BOOL DeleteAllItems();

Return Value

Nonzero if successful; otherwise 0.

CTabCtrl::DeleteItem

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

CTabCtrl::DeselectAll

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's 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.

CTabCtrl::DrawItem

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 to do.

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.

CTabCtrl::GetCurFocus

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.

CTabCtrl::GetCurSel

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.

CTabCtrl::GetExtendedStyle

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.

CTabCtrl::GetImageList

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.

CTabCtrl::GetItem

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

CTabCtrl::GetItemCount

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.

CTabCtrl::GetItemRect

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.

CTabCtrl::GetItemState

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:

Value Description
TCIS_BUTTONPRESSED The tab control item is selected.
TCIS_HIGHLIGHTED The 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.

CTabCtrl::GetRowCount

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.

CTabCtrl::GetToolTips

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.

CTabCtrl::HighlightItem

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.

CTabCtrl::HitTest

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.

CTabCtrl::InsertItem

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

CTabCtrl::RemoveImage

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.

CTabCtrl::SetCurFocus

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.

CTabCtrl::SetCurSel

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.

CTabCtrl::SetExtendedStyle

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.

Remarks

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

CTabCtrl::SetImageList

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.

CTabCtrl::SetItem

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.

CTabCtrl::SetItemExtra

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.

CTabCtrl::SetItemSize

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.

CTabCtrl::SetItemState

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:

Value Description
TCIS_BUTTONPRESSED The tab control item is selected.
TCIS_HIGHLIGHTED The 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.

CTabCtrl::SetMinTabWidth

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.

Remarks

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

CTabCtrl::SetPadding

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.

CTabCtrl::SetToolTips

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.

See also

CWnd Class
CHeaderCtrl Class
CListCtrl Class
Hierarchy Chart