CMFCTabCtrl Class

The CMFCTabCtrl class provides functionality for a tab control. The tab control displays a dockable window with flat or three-dimensional tabs at its top or bottom. The tabs can display text and an image and can change color when active.

class CMFCTabCtrl : public CMFCBaseTabCtrl

The CMFCTabCtrl class supports:

• Tab control styles that include 3D, flat, and flat with a shared horizontal scroll bar.

• Tabs located at the top or the bottom of the window.

• Tabs that display text, images, or text and images.

• Tabs that change color when the tab is active.

• Border size changes for adjustable tabs.

• Detachable tabbed windows.

The CMFCTabCtrl class can be used with a dialog box, but is intended for applications that use docking control bars like Microsoft Excel and Visual Studio. For more information, see CDockablePane Class.

Follow these steps to add a resizable, docking tab control in your application:

1. Create an instance of CTabbedPane Class.

2. Call CDockablePane::Create.

3. Use CBaseTabbedPane::AddTab or CMFCBaseTabCtrl::InsertTab to add new tabs.

4. Call CBasePane::EnableDocking so that the current docking tab control can dock at the main frame window.

5. Call CFrameWndEx::DockPane to dock the tabbed window at the main frame.

For an example of how to create a tabbed window as a docking control bar, see CTabbedPane Class. To use CMFCTabCtrl as a non-docking control, create a CMFCTabCtrl object and then call CMFCTabCtrl::Create.

CObject

CCmdTarget

CWnd

CMFCBaseTabCtrl

CMFCTabCtrl

The following example demonstrates how to use various methods in the CMFCTabCtrl class to configure a CMFCTabCtrl object. The example explains how to add a tab, show the Close button on the active tab, enable editable tab labels, and display a pop-up menu of tabbed window labels. This example is part of the State Collection sample.

CMFCTabCtrl m_wndTabs;

// Attach list windows to tab:
// CListCtrl m_wndList1
// CListCtrl m_wndList2
// CListCtrl m_wndList3
m_wndTabs.AddTab(&m_wndList1, _T("Output 1"), (UINT)-1);
m_wndTabs.AddTab(&m_wndList2, _T("Output 2"), (UINT)-1);
m_wndTabs.AddTab(&m_wndList3, _T("Output 3"), (UINT)-1);

m_wndTabs.EnableActiveTabCloseButton();
m_wndTabs.EnableInPlaceEdit(true);
m_wndTabs.EnableTabDocumentsMenu();
m_wndTabs.SetActiveTab(1);
m_wndTabs.SetDrawFrame();
m_wndTabs.SetFlatFrame();

Header: afxtabctrl.h

Displays the specified tab of the current tab control and sets the focus on that tab.

void ActivateMDITab(int nTab = -1);

nTab
[in] The zero-based index of a tab to display, or -1 to specify the currently active tab.

For more detail, see the source code located in the mfc folder of your Visual Studio installation. For example, %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\VC\Tools\MSVC\14.29.30133\atlmfc\src\mfc.

virtual BOOL AllowDestroyEmptyTabbedPane() const;

Always TRUE.

Specifies whether the framework is to resize the client area of all tab control windows when a user interface element of the tab control changes.

void AutoSizeWindow(BOOL bAutoSize = TRUE);

bAutoSize
[in] TRUE to automatically resize tab control windows; otherwise, FALSE. The default value is TRUE.

Creates the tab control and attaches it to the CMFCTabCtrl object.

BOOL Create(
    Style style,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID,
    Location location=LOCATION_BOTTOM,
    BOOL bCloseBtn=FALSE);

style
[in] The style of the tab control. For more information, see Remarks.

rect
[in] A rectangle that bounds the tab control.

pParentWnd
[in] A pointer to a parent window. Must not be NULL.

nID
[in] The ID of the tab control.

location
[in] The location of tabs. The default value is LOCATION_BOTTOM. For more information, see Remarks.

bCloseBtn
[in] TRUE to display a close button on the tab; otherwise, FALSE. The default value is FALSE.

TRUE if successful; otherwise, FALSE.

The following table describes the values you can specify for the style parameter.

The following table lists the values you can specify for the location parameter.

The following example demonstrates how to use the Create method in the CMFCTabCtrl class. This example is part of the State Collection sample.

CMFCTabCtrl m_wndTabs;

// Create tabs window:
// CRect rectDummy
// this is a pointer to a parent window
// fourth parameter is the id of the tab control
if (!m_wndTabs.Create (CMFCTabCtrl::STYLE_FLAT, rectDummy, this, 1))
{
    TRACE0("Failed to create output tab window\n");
    return -1;      // fail to create
}

Deflates the size of the specified tab area.

virtual void CalcRectEdit(CRect& rectEdit);

rectEdit
[in] A rectangle that specifies the area of a tab.

This method is called when you change the label of a tab. This method deflates the left and right sides of the specified rectangle by one-half the current tab height, and deflates the top and bottom by one unit.

Shows or hides a Close button ( X) on the active tab.

void EnableActiveTabCloseButton(BOOL bEnable=TRUE);

bEnable
[in] TRUE to display the Close button on the active tab; FALSE to display the Close button on the upper-right corner of the tab area. The default value is TRUE.

Enables or disables editable tab labels.

virtual void EnableInPlaceEdit(BOOL bEnable);

bEnable
[in] TRUE to enable editable tab labels; FALSE to disable editable tab labels.

Toggles between a user interface that uses two buttons to scroll the window tabs and an interface that displays a pop-up menu of tabbed windows.

void EnableTabDocumentsMenu(BOOL bEnable=TRUE);

bEnable
[in] TRUE to display a pop-up menu of tabbed window labels; FALSE to display forward and backward scroll buttons. The default value is TRUE.

When the user clicks a tab label, the framework displays the corresponding tabbed window. If the tab label is visible, the tabbed window is opened without changing its position. If the user selects a document from the pop-up menu and the corresponding tabbed window is off screen, the tabbed window becomes the first tab.

Ensures that a tab is visible.

virtual BOOL EnsureVisible(int iTab);

iTab
[in] The zero-based index of a tab.

TRUE if it's successful; FALSE if the iTab parameter index is invalid.

Use this method to guarantee that the specified tab is visible. The tab control will scroll if it's required.

Retrieves the image that is associated with a tab in a pop-up menu of tabbed windows.

static HICON __stdcall GetDocumentIcon(UINT nCmdID);

nCmdID
[in] The command ID of a tab in a pop-up menu of tabbed windows.

The handle of a bitmap image.

Retrieves the index of the first tab that is visible in the current tab control.

virtual int GetFirstVisibleTabNum() const;

The zero-based index of a tab in the tab control.

Use this method only when the tab control is displayed in the style of Microsoft OneNote. Use the CMFCTabCtrl::IsOneNoteStyle method to determine the style.

Retrieves a value that specifies how the current tab control can be resized.

ResizeMode GetResizeMode() const;

One of the CMFCTabCtrl::ResizeMode enumeration values that specifies how the tab control can be resized. For a list of possible values, see the Remarks section of the CMFCTabCtrl::SetResizeMode method.

Retrieves a pointer to the scroll bar object that is associated with the tab control.

CScrollBar* GetScrollBar();

A pointer to a scrollbar object, or a NULL if the tab control wasn't created by using the STYLE_FLAT_SHARED_HORZ_SCROLL style.

Use this method to access the tab control's embedded scroll bar. A scroll bar object is created only when the tab control has the STYLE_FLAT_SHARED_HORZ_SCROLL style.

Retrieves the bounding rectangle of the tab label area at the top or bottom of the tab control.

void GetTabArea(
    CRect& rectTabAreaTop,
    CRect& rectTabAreaBottom) const;

rectTabAreaTop
[out] When this method returns, this reference contains a rectangle that bounds the top tab label area. The rectangle is in client coordinates. This reference is empty if no tab label area exists at the top of the tab control.

rectTabAreaBottom
[out] When this method returns, this reference contains a rectangle that bounds the bottom tab label area. The rectangle is in client coordinates. This reference is empty if no tab label area exists at the bottom of the tab control.

Use this method to determine the size and position of the tab area in the tabbed window.

Retrieves the maximum width of a tab.

int GetTabMaxWidth() const;

Maximum width of a tab, in pixels. If the return value is 0, the tab width is unlimited.

Use the CMFCTabCtrl::SetTabMaxWidth method to set maximum tab width.

Retrieves the height of the tab area of the current tab control.

virtual int GetTabsHeight() const;

The height of the tab area if any tab is visible, or zero if no tab is visible.

Retrieves a rectangle that bounds the tab area of the current tab control.

virtual void GetTabsRect(CRect& rect) const;

rect
[out] When this method returns, the rect parameter contains a rectangle that bounds the tab area.

Retrieves the boundary of the client area of the current tab control.

void GetWndArea(CRect& rect) const;

rect
[in, out] When this method returns, this parameter contains a rectangle that bounds the current tab control.

Hides the horizontal scroll bar, if any, in the active window.

void HideActiveWindowHorzScrollBar();

Use this method to prevent the tab control from blinking when the user switches between tab control pages.

Specifies whether the framework displays inactive tab control windows.

void HideInactiveWindow(BOOL bHide = TRUE);

bHide
[in] TRUE not to display an inactive window; FALSE to display an inactive window. The default value is TRUE.

Enables or disables drawing of the tab area if there are no visible tabs.

void HideNoTabs(BOOL bHide=TRUE);

bHide
[in] TRUE to enable drawing the tab area; FALSE to disable drawing. The default value is TRUE.

Enables or disables tab drawing if there's a single tabbed window.

virtual void HideSingleTab(BOOL bHide=TRUE);

bHide
[in] TRUE to not draw a tab for a single tabbed window; FALSE to draw a single tab. The default value is TRUE.

Indicates whether the current tab of a tab control is the active tab in a multiple document interface tab group.

BOOL IsActiveInMDITabGroup() const;

TRUE if the current tab of a tab control is the active tab in an MDI tab group; otherwise, FALSE.

You can organize multiple document windows into either vertical or horizontal tab groups and easily shuffle documents from one tab group to another.

Indicates whether the text of the active tab is displayed using a bold font.

BOOL IsActiveTabBoldFont() const;

TRUE if the active tab is displayed using the bold font; otherwise, FALSE.

Use the CMFCTabCtrl::SetActiveTabBoldFont method to change the active tab font.

Indicates whether the Close button ( X) is displayed on an active tab or on the upper-right corner of the tab area.

virtual BOOL IsActiveTabCloseButton() const;

TRUE if the Close button is displayed on the active tab; FALSE if the Close button is displayed on the upper-right corner of the tab area.

Indicates whether the tabbed window draws a frame rectangle around embedded panes.

BOOL IsDrawFrame() const;

TRUE if a frame rectangle is drawn; otherwise, FALSE.

Use the CMFCTabCtrl::SetDrawFrame method to enable or disable drawing a frame rectangle.

Indicates whether the frame around the tab area is flat or 3D.

BOOL IsFlatFrame() const;

TRUE if the frame around the tab area is flat; FALSE if the frame is three-dimensional.

Use the CMFCTabCtrl::SetFlatFrame method to change how the frame is drawn.

Indicates whether the appearance of the tabs in the current tab control is flat or not.

virtual BOOL IsFlatTab() const;

TRUE if the appearance of the tabs in the current tab control is flat; otherwise, FALSE.

Indicates whether the appearance of the left and right side of a tab in the current tab control is rounded.

virtual BOOL IsLeftRightRounded() const;

TRUE if the sides of each tab are rounded; otherwise, FALSE.

Indicates whether the current tab control is contained in the client area of a multiple-document interface window.

virtual BOOL IsMDITabGroup() const;

TRUE if the current tab control is in an MDI client area window; otherwise, FALSE.

Indicates whether the current tab control is displayed in the style of Microsoft OneNote.

virtual BOOL IsOneNoteStyle() const;

TRUE if the tab control is displayed in the style of Microsoft OneNote; otherwise, FALSE.

Indicates whether the current tab control has a scroll bar that can scroll its tabs as a group.

BOOL IsSharedScroll() const;

TRUE if the tab control has a shared scroll bar; otherwise, FALSE.

This method returns TRUE if the style parameter of the CMFCTabCtrl::Create method is STYLE_FLAT_SHARED_HORZ_SCROLL.

Indicates whether the tab control displays scroll buttons or a button that displays a menu of tabbed windows.

BOOL IsTabDocumentsMenu() const;

TRUE if tabbed windows are scrolled using a popup menu of tabbed window labels; FALSE if tabbed windows are scrolled using forward and backward scroll buttons.

Use the CMFCTabCtrl::EnableTabDocumentsMenu method to specify the method of scrolling tabbed windows.

Indicates whether tabs are drawn using the style of Visual Studio 2005.

virtual BOOL IsVS2005Style() const;

TRUE if tabs are drawn using the style of Visual Studio 2005; otherwise, FALSE.

Use the style parameter of the CMFCTabCtrl::Create method to specify how tabs are drawn.

Prevents the active view from losing focus when a new tab is inserted and enabled.

static BOOL m_bEnableActivate;

The focus is usually taken by a new tabbed window when the tab is inserted and made active. Set the CMFCTabCtrl::m_bEnableActivate member variable to FALSE to retain the original focus. The default value is TRUE.

Specifies the appearance of tabs in the current tab control.

BOOL ModifyTabStyle(Style style);

style
[in] One of the enumeration values that specifies the appearance of the tab control. For more information, see the table in Remarks.

Always TRUE.

The value of the style parameter can be one of the following CMFCTabCtrl::Style enumerations.

Called by the framework during a drag-and-drop operation when the cursor first enters the window of the current tab control.

virtual DROPEFFECT OnDragEnter(
    COleDataObject* pDataObject,
    DWORD dwKeyState,
    CPoint point);

pDataObject
[in] Points to a data object that contains data that the user drags.

dwKeyState
[in] Contains the state of the modifier keys. This parameter is a bitwise combination "or" (|) of the following values: MK_CONTROL, MK_SHIFT, MK_ALT, MK_LBUTTON, MK_MBUTTON, and MK_RBUTTON. For more information, see the Message Parameters section of About Mouse Input.

point
[in] Contains the current location of the cursor in client coordinates.

Always DROPEFFECT_NONE, which means that the drop target can't accept the data.

Use this method to support a drag-and-drop operation. Override this method to implement your own custom behavior.

By default, this method only calls CMFCTabCtrl::OnDragOver, which always returns DROPEFFECT_NONE.

Called by the framework during a drag operation when the mouse is moved over the drop target window.

virtual DROPEFFECT OnDragOver(
    COleDataObject* pDataObject,
    DWORD dwKeyState,
    CPoint point);

pDataObject
[in] Pointer to a COleDataObject object that is being dragged over the drop target.

dwKeyState
[in] The state of the modifier keys, which is a bitwise combination "or" (|) of MK_CONTROL, MK_SHIFT, MK_ALT, MK_LBUTTON, MK_MBUTTON, and MK_RBUTTON. For more information, see "Message Parameters" in About Mouse Input.

point
[in] The current mouse position.

Always DROPEFFECT_NONE.

Override this method with your custom implementation. For more information, see the CView::OnDragOver method.

Displays a pop-up menu of tabbed windows, waits until the user selects a tab, and makes the selected tab the active tab.

virtual void OnShowTabDocumentsMenu(CPoint point);

point
[in] The coordinates of where to display the pop-up menu.

Sets the current tab of a tab control as the active tab in a multiple document interface tab group.

void SetActiveInMDITabGroup(BOOL bActive);

bActive
[in] TRUE to make the current tab the active tab; FALSE to make the current tab inactive.

You can organize multiple document windows into either vertical or horizontal tab groups and easily shuffle documents from one tab group to another.

Activates a tab.

virtual BOOL SetActiveTab(int iTab);

iTab
[in] Specifies the zero-based index of the tab to activate.

TRUE if the specified tab was made active; FALSE if the specified iTab parameter value is invalid.

This sends the AFX_WM_CHANGE_ACTIVE_TAB notification to the parent window and the parent's frame of the tab control.

The SetActiveTab method automatically calls the CMFCTabCtrl::HideActiveWindowHorzScrollBar method to prevent the screen from blinking.

Enables or disables use of a bold font on active tabs.

void SetActiveTabBoldFont(BOOL bIsBold=TRUE);

bIsBold
[in] TRUE to use a bold font to display the label of the active tab; FALSE to use the standard font to display the label. The default value is TRUE.

Specifies whether a frame rectangle is drawn around an embedded bar.

void SetDrawFrame(BOOL bDraw=TRUE);

bDraw
[in] TRUE to display a frame rectangle around an embedded bar; otherwise, FALSE. The default value is TRUE.

Specifies whether to draw a flat or a 3D frame around the tab area.

void SetFlatFrame(
    BOOL bFlat=TRUE,
    BOOL bRepaint=TRUE);

bFlat
[in] TRUE to draw a flat (2D) frame around the tab area; FALSE to draw a three-dimensional (3D) frame. The default value is TRUE.

bRepaint
[in] TRUE to redraw the window immediately; otherwise, FALSE. The default value is TRUE.

Specifies an image list.

virtual BOOL SetImageList(
    UINT uiID,
    int cx=15,
    COLORREF clrTransp=RGB(255, 0, 255));

virtual BOOL SetImageList(HIMAGELIST hImageList);

uiID
[in] The ID of a bitmap resource that contains the image list.

cx
[in] The width of each image, in pixels. The default value is 15.

clrTransp
[in] The transparent image color. The parts of the image that are this color will be transparent. The default value is the color magenta, RGB(255,0,255).

hImageList
[in] A handle to a preloaded image list.

TRUE if this method is successful. FALSE if the tab control is created by using a flat style or if the first method overload can't load the bitmap that is specified by the uiID parameter.

Use this method to set an image list for the tab control. The images from the image list are displayed next to the tab label. This method recalculates the tab height so that the tab is sized to contain both the image and the text.

Use the CMFCBaseTabCtrl::AddTab method that is inherited by the tab control to specify the index of the image to display.

Specifies how the current tab control can be resized and then redisplays the control.

void SetResizeMode(ResizeMode resizeMode);

resizeMode
[in] One of the CMFCTabCtrl::ResizeMode enumeration values that specifies how the tab control can be resized. For a list of possible values, see the table in Remarks.

The resizeMode parameter can be one of the following ResizeMode enumeration values.

Specifies the maximum tab width in a tabbed window.

void SetTabMaxWidth(int nTabMaxWidth);

nTabMaxWidth
[in] The maximum tab width, in pixels.

Use this method to limit the width of each tab in a tabbed window. This method is useful if tabs have very long labels. The CMFCTabCtrl class constructor initializes the maximum tab width to 0, which actually means that the width isn't limited.

Terminates the current resize operation on the tab control.

void StopResize(BOOL bCancel);

bCancel
[in] TRUE to abandon the current resize operation; FALSE to complete the current resize operation. In either case, the framework stops drawing the resize rectangle.

Draws a horizontal scroll bar on a tab control that displays flat tabs.

BOOL SynchronizeScrollBar(SCROLLINFO* pScrollInfo = NULL);

pScrollInfo
[out] Pointer to a SCROLLINFO structure or NULL. When this method returns, and if this parameter isn't NULL, the structure contains all the parameters of the scroll bar. The default value is NULL.

TRUE if this method succeeds; otherwise, FALSE.

This method affects only a tab control that displays flat tabs. The scroll bar influences all the tabs at the same time.

Hierarchy Chart
Classes
CDockablePane Class
CMFCBaseTabCtrl Class