Tab Control Reference

Tab Control Reference


This section contains information about the programming elements used with tab controls.

Tab Control Styles

Tab Control Extended Styles

Tab Control Item States

Messages
TCM_ADJUSTRECT
TCM_DELETEALLITEMS
TCM_DELETEITEM
TCM_DESELECTALL
TCM_GETCURFOCUS
TCM_GETCURSEL
TCM_GETEXTENDEDSTYLE
TCM_GETIMAGELIST
TCM_GETITEM
TCM_GETITEMCOUNT
TCM_GETITEMRECT
TCM_GETROWCOUNT
TCM_GETTOOLTIPS
TCM_GETUNICODEFORMAT
TCM_HIGHLIGHTITEM
TCM_HITTEST
TCM_INSERTITEM
TCM_REMOVEIMAGE
TCM_SETCURFOCUS
TCM_SETCURSEL
TCM_SETEXTENDEDSTYLE
TCM_SETIMAGELIST
TCM_SETITEM
TCM_SETITEMEXTRA
TCM_SETITEMSIZE
TCM_SETMINTABWIDTH
TCM_SETPADDING
TCM_SETTOOLTIPS
TCM_SETUNICODEFORMAT

Utility Macros
TabCtrl_AdjustRect
TabCtrl_DeleteAllItems
TabCtrl_DeleteItem
TabCtrl_DeselectAll
TabCtrl_GetCurFocus
TabCtrl_GetCurSel
TabCtrl_GetExtendedStyle
TabCtrl_GetImageList
TabCtrl_GetItem
TabCtrl_GetItemCount
TabCtrl_GetItemRect
TabCtrl_GetRowCount
TabCtrl_GetToolTips
TabCtrl_GetUnicodeFormat
TabCtrl_HighlightItem
TabCtrl_HitTest
TabCtrl_InsertItem
TabCtrl_RemoveImage
TabCtrl_SetCurFocus
TabCtrl_SetCurSel
TabCtrl_SetExtendedStyle
TabCtrl_SetImageList
TabCtrl_SetItem
TabCtrl_SetItemExtra
TabCtrl_SetItemSize
TabCtrl_SetMinTabWidth
TabCtrl_SetPadding
TabCtrl_SetToolTips
TabCtrl_SetUnicodeFormat

Notifications
NM_CLICK (tab)
NM_RCLICK (tab)
NM_RELEASEDCAPTURE (tab)
TCN_GETOBJECT
TCN_KEYDOWN
TCN_SELCHANGE
TCN_SELCHANGING

Structures
NMTCKEYDOWN
TC_HITTESTINFO
TC_ITEM
TC_ITEMHEADER
TC_KEYDOWN
TCHITTESTINFO
TCITEM
TCITEMHEADER

Tab Control Styles

Current tab control styles are supported, and the following styles have been added.
Value Description
TCS_BOTTOM Version 4.70. Tabs appear at the bottom of the control. This value equals TCS_RIGHT.
TCS_BUTTONS Specifies that tabs appear as buttons and no border is drawn around the display area.
TCS_FIXEDWIDTH Specifies that all tabs are the same width. This style cannot be combined with the TCS_RIGHTJUSTIFY style.
TCS_FLATBUTTONS Version 4.71. Selected tabs appear as being indented into the background while other tabs appear as being on the same plane as the background. This style only affects tab controls with the TCS_BUTTONS style.
TCS_FOCUSNEVER Specifies that the tab control never receives the input focus.
TCS_FOCUSONBUTTONDOWN Specifies that tabs receive the input focus when clicked.
TCS_FORCEICONLEFT Aligns icons with the left edge of each fixed-width tab. This style can only be used with the TCS_FIXEDWIDTH style.
TCS_FORCELABELLEFT Aligns labels with the left edge of each fixed-width tab; that is, it displays the label immediately to the right of the icon instead of centering it.

This style can only be used with the TCS_FIXEDWIDTH style, and it implies the TCS_FORCEICONLEFT style.

TCS_HOTTRACK Version 4.70. Items under the pointer are automatically highlighted.
TCS_MULTILINE Displays multiple rows of tabs, if necessary, so all tabs are visible at once.
TCS_MULTISELECT Version 4.70. Multiple tabs can be selected by holding down CTRL when clicking. This style must be used with the TCS_BUTTONS style.
TCS_OWNERDRAWFIXED Specifies that the parent window is responsible for drawing tabs.
TCS_RAGGEDRIGHT Does not stretch each row of tabs to fill the entire width of the control. This style is the default.
TCS_RIGHT Version 4.70. Tabs appear vertically on the right side of controls that use the TCS_VERTICAL style. This value equals TCS_BOTTOM.
TCS_RIGHTJUSTIFY Increases the width of each tab, if necessary, so that each row of tabs fills the entire width of the tab control.

This window style is ignored unless the TCS_MULTILINE style is also specified.

TCS_SCROLLOPPOSITE Version 4.70. Unneeded tabs scroll to the opposite side of the control when a tab is selected.
TCS_SINGLELINE Displays only one row of tabs. The user can scroll to see more tabs, if necessary. This style is the default.
TCS_TABS Specifies that tabs appear as tabs and that a border is drawn around the display area. This style is the default.
TCS_TOOLTIPS Specifies that the tab control has a tooltip control associated with it.
TCS_VERTICAL Version 4.70. Tabs appear at the left side of the control, with tab text displayed vertically. This style is valid only when used with the TCS_MULTILINE style. To make tabs appear on the right side of the control, also use the TCS_RIGHT style.

Tab Control Extended Styles

The tab control now supports extended styles. These styles are manipulated using the TCM_GETEXTENDEDSTYLE and TCM_SETEXTENDEDSTYLE messages and should not be confused with extended window styles which are passed to CreateWindowEx.
Value Description
TCS_EX_FLATSEPARATORS Version 4.71. The tab control will draw separators between the tab items. This extended style only affects tab controls that have the TCS_BUTTONS and TCS_FLATBUTTONS styles. By default, creating the tab control with the TCS_FLATBUTTONS style sets this extended style. If you do not require separators, you should remove this extended style after creating the control.
TCS_EX_REGISTERDROP Version 4.71. The tab control generates TCN_GETOBJECT notification messages to request a drop target object when an object is dragged over the tab items in the control. The application must call CoInitialize or OleInitialize before setting this style.

Tab Control Item States

Tab control items now support an item state to support the TCM_DESELECTALL message. Additionally, the TCITEM structure supports item state values.
Value Description
TCIS_BUTTONPRESSED Version 4.70. The tab control item is selected.
TCIS_HIGHLIGHTED Version 4.71. The tab control item is highlighted, and the tab and text are drawn using the current highlight color. When using high-color, this will be a true interpolation, not a dithered color.

Tab Control Messages

This section contains information about the messages used with tab controls.

TCM_ADJUSTRECT

TCM_ADJUSTRECT 
    wParam = (WPARAM) (BOOL) fLarger;
    lParam = (LPARAM) (LPRECT) prc;

Calculates a tab control's display area given a window rectangle, or calculates the window rectangle that would correspond to a specified display area. You can send this message explicitly or by using the TabCtrl_AdjustRect macro.

fLarger
Operation to perform. If this parameter is TRUE, prc specifies a display rectangle and receives the corresponding window rectangle. If this parameter is FALSE, prc specifies a window rectangle and receives the corresponding display area.
prc
Address of a RECT structure that specifies the given rectangle and receives the calculated rectangle.

TCM_DELETEALLITEMS

TCM_DELETEALLITEMS 
    wParam = 0;
    lParam = 0;

Removes all items from a tab control. You can send this message explicitly or by using the TabCtrl_DeleteAllItems macro.

TCM_DELETEITEM

TCM_DELETEITEM 
    wParam = (WPARAM) (int) iItem;
    lParam = 0;

Removes an item from a tab control. You can send this message explicitly or by using the TabCtrl_DeleteItem macro.

iItem
Index of the item to delete.

TCM_DESELECTALL

TCM_DESELECTALL
    wParam = (WPARAM) (DWORD) fExcludeFocus;
    lParam = 0;

Resets items in a tab control, clearing any that were set to the TCIS_BUTTONPRESSED state. You can send this message explicitly or by using the TabCtrl_DeselectAll macro.

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

Version 4.70

TCM_GETCURFOCUS

TCM_GETCURFOCUS 
    wParam = 0;
    lParam = 0;

Returns the index of the item that has the focus in a tab control. You can send this message explicitly or by using the TabCtrl_GetCurFocus macro.

The item that has the focus may be different than the selected item.

TCM_GETCURSEL

TCM_GETCURSEL 
    wParam = 0;
    lParam = 0;

Determines the currently selected tab in a tab control. You can send this message explicitly or by using the TabCtrl_GetCurSel macro.

TCM_GETEXTENDEDSTYLE

TCM_GETEXTENDEDSTYLE
    wParam = 0;
    lParam = 0;

Retrieves the extended styles that are currently in use for the tab control. You can send this message explicitly or by using the TabCtrl_GetExtendedStyle macro.

Version 4.71

TCM_GETIMAGELIST

TCM_GETIMAGELIST 
    wParam = 0;
    lParam = 0;

Retrieves the image list associated with a tab control. You can send this message explicitly or by using the TabCtrl_GetImageList macro.

TCM_GETITEM

TCM_GETITEM 
    wParam = (WPARAM) (int) iItem; 
    lParam = (LPARAM) (LPTCITEM) pitem; 

Retrieves information about a tab in a tab control. You can send this message explicitly or by using the TabCtrl_GetItem macro.

iItem
Index of the tab.
pitem
Address of a TCITEM structure that specifies the information to retrieve and receives information about the tab. 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.

TCM_GETITEMCOUNT

TCM_GETITEMCOUNT 
    wParam = 0;
    lParam = 0;

Retrieves the number of tabs in the tab control. You can send this message explicitly or by using the TabCtrl_GetItemCount macro.

TCM_GETITEMRECT

TCM_GETITEMRECT 
    wParam = (WPARAM) (int) iItem;
    lParam = (LPARAM) (RECT FAR *) prc;

Retrieves the bounding rectangle for a tab in a tab control. You can send this message explicitly or by using the TabCtrl_GetItemRect macro.

iItem
Index of the tab.
prc
Address of a RECT structure that receives the bounding rectangle of the tab, in viewport coordinates.

TCM_GETROWCOUNT

TCM_GETROWCOUNT 
    wParam = 0;
    lParam = 0;

Retrieves the current number of rows of tabs in a tab control. You can send this message explicitly or by using the TabCtrl_GetRowCount macro.

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

TCM_GETTOOLTIPS

TCM_GETTOOLTIPS 
    wParam = 0;
    lParam = 0;

Retrieves the handle to the tooltip control associated with a tab control. You can send this message explicitly or by using the TabCtrl_GetToolTips macro.

A tab control creates a tooltip control if it has the TCS_TOOLTIPS style. You can also assign a tooltip control to a tab control by using the TCM_SETTOOLTIPS message.

TCM_GETUNICODEFORMAT

TCM_GETUNICODEFORMAT
    wParam = 0;
    lParam = 0;

Retrieves the UNICODE character format flag for the control. You can send this message explicitly or use the TabCtrl_GetUnicodeFormat macro.

See also TCM_SETUNICODEFORMAT

TCM_HIGHLIGHTITEM

TCM_HIGHLIGHTITEM
    wParam = (WPARAM) idItem;
    lParam = (LPARAM) MAKELONG(fHighlight,0);

Sets the highlight state of a tab item. You can send this message explicitly or by using the TabCtrl_HighlightItem macro.

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.

Version 4.71

TCM_HITTEST

TCM_HITTEST 
    wParam = 0;
    lParam = (LPARAM) (LPTCHITTESTINFO) pinfo;

Determines which tab, if any, is at a specified screen position. You can send this message explicitly or by using the TabCtrl_HitTest macro.

pinfo
Address of a TCHITTESTINFO structure that specifies the screen position to test.

TCM_INSERTITEM

TCM_INSERTITEM 
    wParam = (WPARAM) (int) iItem;
    lParam = (LPARAM) (const LPTCITEM) pitem;

Inserts a new tab in a tab control. You can send this message explicitly or by using the TabCtrl_InsertItem macro.

iItem
Index of the new tab.
pitem
Address of a TCITEM structure that specifies the attributes of the tab. The dwState and dwStateMask members of this structure are ignored by this message.

TCM_REMOVEIMAGE

TCM_REMOVEIMAGE 
    wParam = (WPARAM) (int) iImage;
    lParam = 0;

Removes an image from a tab control's image list. You can send this message explicitly or by using the TabCtrl_RemoveImage macro.

iImage
Index of the image to remove.

The tab control updates each tab's image index, so each tab remains associated with the same image as before. If a tab is using the image being removed, the tab will be set to have no image.

TCM_SETCURFOCUS

TCM_SETCURFOCUS 
    wParam = (WPARAM) (int) iItem;
    lParam = 0;

Sets the focus to a specified tab in a tab control. You can send this message explicitly or by using the TabCtrl_SetCurFocus macro.

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

If the tab control has the TCS_BUTTONS style (button mode), the tab with the focus may be different from the selected tab. For example, when a tab is selected, the user can press the arrow keys to set the focus to a different tab without changing the selected tab. In button mode, TCM_SETCURFOCUS sets the input focus to the button associated with the specified tab, but it does not change the selected tab.

If the tab control does not have the TCS_BUTTONS style, changing the focus also changes the selected tab. In this case, the tab control sends the TCN_SELCHANGING and TCN_SELCHANGE notification messages to its parent window.

See also TCM_GETCURFOCUS

TCM_SETCURSEL

TCM_SETCURSEL 
    wParam = (WPARAM) (int) iItem;
    lParam = 0;

Selects a tab in a tab control. You can send this message explicitly or by using the TabCtrl_SetCurSel macro.

iItem
Index of the tab to select.

A tab control does not send a TCN_SELCHANGING or TCN_SELCHANGE notification message when a tab is selected using this message.

TCM_SETEXTENDEDSTYLE

TCM_SETEXTENDEDSTYLE
    wParam = (WPARAM)dwExMask;
    lParam = (LPARAM)dwExStyle;

Sets the extended styles that the tab control will use. You can send this message explicitly or by using the TabCtrl_SetExtendedStyle macro.

dwExMask
A DWORD value that indicates which styles in dwExStyle are to be affected. Only the extended styles in dwExMask will be changed. All other styles will be maintained as they are. If this parameter is zero, then all of the styles in dwExStyle will be affected.
dwExStyle
Value specifying the extended tab control styles. This value is a combination of tab control extended styles.

The dwExMask parameter allows you to modify one or more extended styles without having to retrieve the existing styles first. For example, if you pass TCS_EX_FLATSEPARATORS for dwExMask and 0 for dwExStyle, the TCS_EX_FLATSEPARATORS style will be cleared, but all other styles will remain the same.

For backward compatibility reasons, the TabCtrl_SetExtendedStyle macro has not been updated to use dwExMask.

Version 4.71

TCM_SETIMAGELIST

TCM_SETIMAGELIST 
    wParam = 0;
    lParam = (LPARAM) (HIMAGELIST) himl;

Assigns an image list to a tab control. You can send this message explicitly or by using the TabCtrl_SetImageList macro.

himl
Handle to the image list to assign to the tab control.

TCM_SETITEM

TCM_SETITEM 
    wParam = (WPARAM) (int) iItem;
    lParam = (LPARAM) (LPTCITEM) pitem;

Sets some or all of a tab's attributes. You can send this message explicitly or by using the TabCtrl_SetItem macro.

iItem
Index of the item.
pitem
Address of a TCITEM structure that contains the new item attributes. The mask member specifies which attributes to set.
If the mask member specifies the LVIF_TEXT value, the pszText member is the address of a null-terminated string and the cchTextMax member is ignored.

TCM_SETITEMEXTRA

TCM_SETITEMEXTRA 
    wParam = (WPARAM) (int) cb;
    lParam = 0;

Sets the number of bytes per tab reserved for application-defined data in a tab control. You can send this message explicitly or by using the TabCtrl_SetItemExtra macro.

cb
Number of extra bytes.

By default, the number of extra bytes is four. An application that changes the number of extra bytes cannot use the TCITEM structure to retrieve and set the application-defined data for a tab. Instead, you must define a new structure that consists of the TCITEMHEADER structure followed by application-defined members.

An application should only change the number of extra bytes when a tab control does not contain any tabs.

TCM_SETITEMSIZE

TCM_SETITEMSIZE 
    wParam = 0;
    lParam = MAKELPARAM(cx, cy);

Sets the width and height of tabs in a fixed-width or owner-drawn tab control. You can send this message explicitly or by using the TabCtrl_SetItemSize macro.

cx and cy
New width and height, in pixels.

TCM_SETMINTABWIDTH

TCM_SETMINTABWIDTH
    wParam = 0;
    lParam = (LPARAM) (INT) cx;

Sets the minimum width of items in a tab control. You can send this message explicitly or by using the TabCtrl_SetMinTabWidth macro.

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.

Version 4.70

TCM_SETPADDING

TCM_SETPADDING 
    wParam = 0;
    lParam = MAKELPARAM(cx, cy);

Sets the amount of space (padding) around each tab's icon and label in a tab control. You can send this message explicitly or by using the TabCtrl_SetPadding macro.

cx and cy
Amount of horizontal and vertical padding, in pixels.

TCM_SETTOOLTIPS

TCM_SETTOOLTIPS 
    wParam = (WPARAM) (HWND) hwndTT;
    lParam = 0;

Assigns a tooltip control to a tab control. You can send this message explicitly or by using the TabCtrl_SetToolTips macro.

hwndTT
Handle to the tooltip control.

You can get the tooltip control associated with a tab control by using the TCM_GETTOOLTIPS message.

TCM_SETUNICODEFORMAT

TCM_SETUNICODEFORMAT
    wParam = (WPARAM)(BOOL)fUnicode;
    lParam = 0;

Sets the UNICODE character format flag for the control. This message allows you to change the character set used by the control at run time rather than having to re-create the control. You can send this message explicitly or use the TabCtrl_SetUnicodeFormat macro.

fUnicode
Determines the character set that is used by the control. If this value is nonzero, the control will use UNICODE characters. If this value is zero, the control will use ANSI characters.

See also TCM_GETUNICODEFORMAT

Tab Control Macros

This section contains information about the utility macros used with tab controls.

TabCtrl_AdjustRect

VOID TabCtrl_AdjustRect(
    HWND hwnd, 		
    BOOL fLarger, 		
    RECT FAR *prc		
);		

Calculates a tab control's display area given a window rectangle, or calculates the window rectangle that would correspond to a specified display area. You can use this macro or send the TCM_ADJUSTRECT message explicitly.

hwnd
Handle to the tab control.
fLarger
Operation to perform. If this parameter is TRUE, prc specifies a display rectangle and receives the corresponding window rectangle. If this parameter is FALSE, prc specifies a window rectangle and receives the corresponding display area.
prc
Address of a RECT structure that specifies the given rectangle and receives the calculated rectangle.

TabCtrl_DeleteAllItems

BOOL TabCtrl_DeleteAllItems(
    HWND hwnd		
);		

Removes all items from a tab control. You can use this macro or send the TCM_DELETEALLITEMS message explicitly.

hwnd
Handle to the tab control.

TabCtrl_DeleteItem

BOOL TabCtrl_DeleteItem(
    HWND hwnd, 		
    int iItem		
);		

Removes an item from a tab control. You can use this macro or send the TCM_DELETEITEM message explicitly.

hwnd
Handle to the tab control.
iItem
Index of the item to delete.

TabCtrl_DeselectAll

void TabCtrl_DeselectAll(
    HWND hwndTab,
    UINT fExcludeFocus
);

Resets items in a tab control, clearing any that were set to the TCIS_BUTTONPRESSED state. You can use this macro or send the TCM_DESELECTALL message explicitly.

hwndTab
Handle to the tab control.
fExcludeFocus
Flag value that specifies the scope of the item deselection. If this parameter is set to FALSE, all tab items will be reset. If it is set to TRUE, all but the currently selected tab item will be reset.

Version 4.70

TabCtrl_GetCurFocus

int TabCtrl_GetCurFocus(
    HWND hwnd		
);		

Returns the index of the item that has the focus in a tab control. You can use this macro or send the TCM_GETCURFOCUS message explicitly.

hwnd
Handle to the tab control.

The item that has the focus may be different than the selected item.

TabCtrl_GetCurSel

int TabCtrl_GetCurSel(
    HWND hwnd		
);		

Determines the currently selected tab in a tab control. You can use this macro or send the TCM_GETCURSEL message explicitly.

hwnd
Handle to the tab control.

TabCtrl_GetExtendedStyle

DWORD TabCtrl_GetExtendedStyle(
    HWND hwndTab
);

Retrieves the extended styles that are currently in use for the tab control. You can use this macro or send the TCM_GETEXTENDEDSTYLE message explicitly.

hwndTab
Handle to the tab control.

Version 4.71

TabCtrl_GetImageList

HIMAGELIST TabCtrl_GetImageList(
    HWND hwnd		
);		

Retrieves the image list associated with a tab control. You can use this macro or send the TCM_GETIMAGELIST message explicitly.

TabCtrl_GetItem

BOOL TabCtrl_GetItem(
    HWND hwnd, 		
    int iItem, 		
    LPTCITEM pitem		
);		

Retrieves information about a tab in a tab control. You can use this macro or send the TCM_GETITEM message explicitly.

hwnd
Handle to the tab control.
iItem
Index of the tab.
pitem
Address of a TCITEM structure that specifies the information to retrieve and receives information about the tab. 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.

TabCtrl_GetItemCount

int TabCtrl_GetItemCount(
    HWND hwnd		
);		

Retrieves the number of tabs in the tab control. You can use this macro or send the TCM_GETITEMCOUNT message explicitly.

hwnd
Handle to the tab control.

TabCtrl_GetItemRect

BOOL TabCtrl_GetItemRect(
    HWND hwnd, 		
    int iItem, 		
    RECT FAR *prc		
);		

Retrieves the bounding rectangle for a tab in a tab control. You can use this macro or send the TCM_GETITEMRECT message explicitly.

hwnd
Handle to the tab control.
iItem
Index of the tab.
prc
Address of a RECT structure that receives the bounding rectangle of the tab, in viewport coordinates.

TabCtrl_GetRowCount

int TabCtrl_GetRowCount(
    HWND hwnd		
);		

Retrieves the current number of rows of tabs in a tab control. You can use this macro or send the TCM_GETROWCOUNT message explicitly.

hwnd
Handle to the tab control.

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

TabCtrl_GetToolTips

int TabCtrl_GetToolTips(
    HWND hwnd		
);		

Retrieves the handle to the tooltip control associated with a tab control. You can use this macro or send the TCM_GETTOOLTIPS message explicitly.

hwnd
Handle to the tab control.

A tab control creates a tooltip control if it has the TCS_TOOLTIPS style. You can also assign a tooltip control to a tab control by using the TCM_SETTOOLTIPS message.

TabCtrl_GetUnicodeFormat

BOOL TabCtrl_GetUnicodeFormat(
    HWND hwnd
);

Retrieves the UNICODE character format flag for the control. You can use this macro or send the TCM_GETUNICODEFORMAT message explicitly.

hwnd
Handle to the control.

See also TabCtrl_SetUnicodeFormat

TabCtrl_HighlightItem

BOOL TabCtrl_HighlightItem(
    HWND hwndTab,
    INT idItem,
    WORD fHighlight
); 

Sets the highlight state of a tab item. You can use this macro or send the TCM_HIGHLIGHTITEM message explicitly.

hwndTab
Handle to the tab control.
idItem
Zero-based index of a tab control item.
fHighlight
Value specifying the highlight state to be set. If this value is nonzero, the tab is highlighted. If this value is zero, the tab is set to its default state.

Version 4.71

TabCtrl_HitTest

int TabCtrl_HitTest(
    HWND hwnd, 		
    LPTCHITTESTINFO pinfo		
);		

Determines which tab, if any, is at a specified screen position. You can use this macro or send the TCM_HITTEST message explicitly.

hwnd
Handle to the tab control.
pinfo
Address of a TCHITTESTINFO structure that specifies the screen position to test.

TabCtrl_InsertItem

int TabCtrl_InsertItem(
    HWND hwnd, 		
    int iItem, 		
    const LPTCITEM pitem		
);		

Inserts a new tab in a tab control. You can use this macro or send the TCM_INSERTITEM message explicitly.

hwnd
Handle to the tab control.
iItem
Index of the new tab.
pitem
Address of a TCITEM structure that specifies the attributes of the tab. The dwState and dwStateMask members of this structure are ignored by this message.

TabCtrl_RemoveImage

void TabCtrl_RemoveImage(
    HWND hwnd, 		
    int iImage		
);		

Removes an image from a tab control's image list. You can use this macro or send the TCM_REMOVEIMAGE message explicitly.

hwnd
Handle to the tab control.
iImage
Index of the image to remove.

The tab control updates each tab's image index, so each tab remains associated with the same image as before. If a tab is using the image being removed, the tab will be set to have no image.

TabCtrl_SetCurFocus

VOID TabCtrl_SetCurFocus(
    HWND hwnd,
    int  iItem
);		

Sets the focus to a specified tab in a tab control. You can use this macro or send the TCM_SETCURFOCUS message explicitly.

hwnd
Handle to the tab control.
iItem
Specifies the zero-based index of the tab that gets the focus.

If the tab control has the TCS_BUTTONS style (button mode), the tab with the focus may be different from the selected tab. For example, when a tab is selected, the user can press the arrow keys to set the focus to a different tab without changing the selected tab. In button mode, the TabCtrl_SetCurFocus macro sets the input focus to the button associated with the specified tab, but it does not change the selected tab.

If the tab control does not have the TCS_BUTTONS style, changing the focus also changes the selected tab. In this case, the tab control sends the TCN_SELCHANGING and TCN_SELCHANGE notification messages to its parent window.

See also TabCtrl_GetCurFocus, TCM_GETCURFOCUS

TabCtrl_SetCurSel

int TabCtrl_SetCurSel(
    HWND hwnd, 		
    int iItem		
);		

Selects a tab in a tab control. You can use this macro or send the TCM_SETCURSEL message explicitly.

hwnd
Handle to the tab control.
iItem
Index of the tab to select.

A tab control does not send a TCN_SELCHANGING or TCN_SELCHANGE notification message when a tab is selected using the TCM_SETCURSEL message.

TabCtrl_SetExtendedStyle

DWORD TabCtrl_SetExtendedStyle(
    HWND hwndTab,
    DWORD dwExStyle
);

Sets the extended styles that the tab control will use. You can use this macro or send the TCM_SETEXTENDEDSTYLE message explicitly.

hwndTab
Handle to the tab control.
dwExStyle
Value that contains the new tab control extended styles. This value is a combination of tab control extended styles.

Version 4.71

TabCtrl_SetImageList

BOOL TabCtrl_SetImageList(
    HWND hwnd, 		
    HIMAGELIST himl		
);		

Assigns an image list to a tab control. You can use this macro or send the TCM_SETIMAGELIST message explicitly.

hwnd
Handle to the tab control.
himl
Handle to the image list to assign to the tab control.

TabCtrl_SetItem

BOOL TabCtrl_SetItem(
    HWND hwnd, 		
    int iItem, 		
    LPTCITEM pitem		
);		

Sets some or all of a tab's attributes. You can use this macro or send the TCM_SETITEM message explicitly.

hwnd
Handle to the tab control.
iItem
Index of the item.
pitem
Address of a TCITEM structure that contains the new item attributes. The mask member specifies which attributes to set.
If the mask member specifies the LVIF_TEXT value, the pszText member is the address of a null-terminated string and the cchTextMax member is ignored.

TabCtrl_SetItemExtra

BOOL TabCtrl_SetItemExtra(
    HWND hwnd, 		
    int cb		
);		

Sets the number of bytes per tab reserved for application-defined data in a tab control. You can use this macro or send the TCM_SETITEMEXTRA message explicitly.

hwnd
Handle to the tab control.
cb
Number of extra bytes.

By default, the number of extra bytes is four. An application that changes the number of extra bytes cannot use the TCITEM structure to retrieve and set the application-defined data for a tab. Instead, you must define a new structure that consists of the TCITEMHEADER structure followed by application-defined members.

An application should only change the number of extra bytes when a tab control does not contain any tabs.

TabCtrl_SetItemSize

DWORD TabCtrl_SetItemSize(
    HWND hwnd, 		
    int cx, 		
    int cy		
);		

Sets the width and height of tabs in a fixed-width or owner-drawn tab control. You can use this macro or send the TCM_SETITEMSIZE message explicitly.

hwnd
Handle to the tab control.
cx and cy
New width and height, in pixels.

TabCtrl_SetMinTabWidth

int TabCtrl_SetMinTabWidth(
    HWND hwndTab,
    INT cx
);

Sets the minimum width of items in a tab control. You can use this macro or send the TCM_SETMINTABWIDTH message explicitly.

hwndTab
Handle to the tab control.
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.

Version 4.70

TabCtrl_SetPadding

void TabCtrl_SetPadding(
    HWND hwnd, 		
    int cx, 		
    int cy		
);		

Sets the amount of space (padding) around each tab's icon and label in a tab control. You can use this macro or send the TCM_SETPADDING message explicitly.

hwnd
Handle to the tab control.
cx and cy
Amount of horizontal and vertical padding, in pixels.

TabCtrl_SetToolTips

void TabCtrl_SetToolTips(
    HWND hwndTab, 		
    HWND hwndTT		
);		

Assigns a tooltip control to a tab control. You can use this macro or send the TCM_SETTOOLTIPS message explicitly.

hwndTab
Handle to the tab control.
hwndTT
Handle to the tooltip control.

You can get the tooltip control associated with a tab control by using the TCM_GETTOOLTIPS message.

TabCtrl_SetUnicodeFormat

BOOL TabCtrl_SetUnicodeFormat(
    HWND hwnd,
    BOOL fUnicode
);

Sets the UNICODE character format flag for the control. This message allows you to change the character set used by the control at run time rather than having to re-create the control. You can use this macro or send the TCM_SETUNICODEFORMAT message explicitly.

hwnd
Handle to the control.
fUnicode
Determines the character set that is used by the control. If this value is nonzero, the control will use UNICODE characters. If this value is zero, the control will use ANSI characters.

See also TabCtrl_GetUnicodeFormat

Tab Control Notification Messages

This section contains information about the notification messages sent by tab controls.

NM_CLICK (tab)

NM_CLICK 
    lpnmh = (LPNMHDR) lParam; 

Notifies a tab control's parent window that the user has clicked the left mouse button within the control. NM_CLICK is sent in the form of a WM_NOTIFY message.

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

NM_RCLICK (tab)

NM_RCLICK 
    lpnmh = (LPNMHDR) lParam; 

Notifies a tab control's parent window that the user has clicked the right mouse button within the control. NM_RCLICK is sent in the form of a WM_NOTIFY message.

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

NM_RELEASEDCAPTURE (tab)

NM_RELEASEDCAPTURE
    lpnmh = (LPNMHDR) lParam; 

Notifies a tab control's parent window that the control is releasing mouse capture. This notification is sent in the form of a WM_NOTIFY message.

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Version 4.71.

TCN_GETOBJECT

TCN_GETOBJECT
    lpnmon = (LPNMOBJECTNOTIFY) lParam;

Sent by a tab control when it has the TCS_EX_REGISTERDROP extended style and an object is dragged over a tab item in the control. This notification message is sent in the form of a WM_NOTIFY message.

lpnmon
Address of an NMOBJECTNOTIFY structure that contains information about the tab item the object is dragged over and receives data the application returns in response to this message.

Version 4.71

TCN_KEYDOWN

TCN_KEYDOWN 
    pnm = (NMTCKEYDOWN FAR *) lParam; 

Notifies a tab control's parent window that a key has been pressed. This message is sent in the form of a WM_NOTIFY message.

pnm
Address of an NMTCKEYDOWN structure.

TCN_SELCHANGE

TCN_SELCHANGE 
    lpnmhdr = (LPNMHDR) lParam; 

Notifies a tab control's parent window that the currently selected tab has changed. This message is sent in the form of a WM_NOTIFY message.

lpnmhdr
Address of an NMHDR structure. The hwndFrom member is the handle to the tab control. The idFrom member is the child window identifier of the tab control. The code member is TCN_SELCHANGE.

To determine the currently selected tab, use the TabCtrl_GetCurSel macro.

See also TCN_SELCHANGING

TCN_SELCHANGING

TCN_SELCHANGING 
    lpnmhdr = (LPNMHDR) lParam; 

Notifies a tab control's parent window that the currently selected tab is about to change. This message is sent in the form of a WM_NOTIFY message.

lpnmhdr
Address of an NMHDR structure. The hwndFrom member is the handle to the tab control. The idFrom member is the child window identifier of the tab control. The code member is TCN_SELCHANGING.

To determine the currently selected tab, use the TabCtrl_GetCurSel macro.

See also TCN_SELCHANGE

Tab Control Structures

This section contains information about the structures used with tab controls.

NMTCKEYDOWN

typedef struct tagNMTCKEYDOWN {
    NMHDR hdr;
    WORD wVKey;
    UINT flags;
} NMTCKEYDOWN;

Contains information about a key press in a tab control. It is used with the TCN_KEYDOWN notification message. This structure supersedes the TC_KEYDOWN structure.

hdr
NMHDR structure that contains information about the notification message.
wVKey
Virtual key code.
flags
Value that is identical to the lParam parameter of the WM_KEYDOWN message.

TCHITTESTINFO

typedef struct tagTCHITTESTINFO { 
    POINT pt; 
    UINT  flags; 
} TCHITTESTINFO, FAR * LPTCHITTESTINFO; 
 

Contains information about a hit test. This structure supersedes the TC_HITTESTINFO structure.

pt
Position to hit test, in client coordinates.
flags
Variable that receives the results of a hit test. The tab control sets this member to one of the following values:
TCHT_NOWHERE The position is not over a tab.
TCHT_ONITEM The position is over a tab but not over its icon or its text. For owner-drawn tab controls, this value is specified if the position is anywhere over a tab.
TCHT_ONITEMICON The position is over a tab's icon.
TCHT_ONITEMLABEL The position is over a tab's text.
TCHT_ONITEM is a bitwise-OR operation on TCHT_ONITEMICON and TCHT_ONITEMLABEL.

See also TCM_HITTEST

TCITEM

typedef struct tagTCITEM {  
    UINT mask;
#if (_WIN32_IE >= 0x0300)
    DWORD dwState;
    DWORD dwStateMask;
#else
    UINT lpReserved1;
    UINT lpReserved2;
#endif
    LPTSTR pszText;
    int cchTextMax;
    int iImage;
    LPARAM lParam;
} TCITEM, FAR *LPTCITEM; 

Specifies or receives the attributes of a tab item. It is used with the TCM_INSERTITEM, TCM_GETITEM, and TCM_SETITEM messages. This structure supersedes the TC_ITEM structure.

mask
Value that specifies which members to retrieve or set. This member can be a combination of the following values:
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 Version 4.70. The dwState member is valid.
TCIF_TEXT The pszText member is valid.
dwState
Version 4.70. Specifies the item's current state if information is being retrieved. If item information is being set, this member contains the state value to be set for the item. For a list of valid tab control item states, see Tab Control Item States. This member is ignored in the TCM_INSERTITEM message.
dwStateMask
Version 4.70. Specifies which bits of the dwState member contain valid information. This member is ignored in the TCM_INSERTITEM message.
lpReserved1
Version 4.00. Not used.
lpReserved2
Version 4.00. Not used.
pszText
Address of a null-terminated string that contains the tab text when item information is being set. If item information is being retrieved, this member specifies the address of the buffer that receives the tab text.
cchTextMax
Size of the buffer pointed to by the pszText member. If the structure is not receiving information, this member is ignored.
iImage
Index in the tab control's image list, or -1 if there is no image for the tab.
lParam
Application-defined data associated with the tab control item. If more or less than 4 bytes of application-defined data exist 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 TCITEMHEADER structure.

TCITEMHEADER

typedef struct tagTCITEMHEADER{
    UINT   mask;
    UINT   lpReserved1;
    UINT   lpReserved2;
    LPTSTR pszText;
    int    cchTextMax;
    int    iImage;
} TCITEMHEADER, FAR *LPTCITEMHEADER;

Specifies or receives the attributes of a tab. It is used with the TCM_INSERTITEM, TCM_GETITEM, and TCM_SETITEM messages. This structure supersedes the TC_ITEMHEADER structure.

mask
Value that specifies which members to retrieve or set. This member can be a combination of the following values:
TCIF_IMAGE The iImage member is valid.
TCIF_RTLREADING The text of pszText is displayed using right-to-left reading order on Hebrew or Arabic systems.
TCIF_TEXT The pszText member is valid.
lpReserved1
Reserved member. Do not use.
lpReserved2
Reserved member. Do not use.
pszText
Address of a null-terminated string that contains the tab text if item information is being set. If item information is being retrieved, this member specifies the address of the buffer that receives the tab text.
cchTextMax
Size of the buffer pointed to by the pszText member. If the structure is not receiving information, this member is ignored.
iImage
Index into the tab control's image list, or -1 if there is no image for the tab.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.