mditab.h File Reference

MDI tab control (MC_WC_MDITAB). More...

Go to the source code of this file.

Data Structures
struct	MC_MTITEMW
	Structure for manipulating with the tab item (unicode variant). More...
struct	MC_MTITEMA
	Structure for manipulating with the tab item (ANSI variant). More...
struct	MC_MTITEMWIDTH
	Structure for messages MC_MTM_SETITEMWIDTH and MC_MTM_GETITEMWIDTH. More...
struct	MC_MTHITTESTINFO
	Structure for message MC_MTM_HITTEST. More...
struct	MC_NMMTSELCHANGE
	Structure for notification MC_MTN_SELCHANGE. More...
struct	MC_NMMTDELETEITEM
	Structure for notification MC_MTN_DELETEITEM. More...
struct	MC_NMMTCLOSEITEM
	Structure for notification MC_MTN_CLOSEITEM. More...

Initialization Functions
BOOL	mcMditab_Initialize (void)
void	mcMditab_Terminate (void)

Window Class
#define	MC_WC_MDITABW   L"mCtrl.mditab"
#define	MC_WC_MDITABA   "mCtrl.mditab"

Control Styles
#define	MC_MTS_CBONTOOLBAR   0x0000
	Show close button on right side of the control. This is default.
#define	MC_MTS_CBONEACHTAB   0x0001
	Not supported, reserved for future use.
#define	MC_MTS_CBONACTIVETAB   0x0002
	Not supported, reserved for future use.
#define	MC_MTS_CBNONE   0x0003
	Don't show close button.
#define	MC_MTS_CBMASK   0x0003
	This is not valid style, its bitmask of MC_MTS_CBxxx styles.
#define	MC_MTS_TLBALWAYS   0x0000
	Popup tab list button is shown always. This is default.
#define	MC_MTS_TLBONSCROLL   0x0004
	Popup tab list button is shown if scrolling is triggered on.
#define	MC_MTS_TLBNEVER   0x0008
	Popup tab list button is never displayed.
#define	MC_MTS_TLBMASK   0x000C
	This is not valid style, but bitmask of MC_NTS_TLBxxx styles.
#define	MC_MTS_SCROLLALWAYS   0x0010
	Always shows scrolling buttons.
#define	MC_MTS_CLOSEONMCLICK   0x0020
	Middle click closes a tab.
#define	MC_MTS_FOCUSONBUTTONDOWN   0x0040
	Mouse button down gains focus.
#define	MC_MTS_FOCUSNEVER   0x0080
	Never gains focus.
#define	MC_MTS_FOCUSMASK   0x00C0
	This is not valid style, but bitmask of MC_NTS_FOCUSxxx styles.
#define	MC_MTS_DOUBLEBUFFER   0x0100
	Enable painting with double buffering.

MC_MTITEM::dwMask Bits
#define	MC_MTIF_TEXT   (1 << 0)
	MC_MTITEMW::pszText or MC_MTITEMA::pszText is valid.
#define	MC_MTIF_IMAGE   (1 << 1)
	MC_MTITEMW::iImage or MC_MTITEMA::iImage is valid.
#define	MC_MTIF_PARAM   (1 << 2)
	MC_MTITEMW::lParam or MC_MTITEMA::lParam is valid.

MC_MTHITTESTINFO::flags bits
#define	MC_MTHT_NOWHERE   (1 << 0)
	The hit test coordinates are outside of any tabs.
#define	MC_MTHT_ONITEMICON   (1 << 1)
	The coordinates hit the tab on its icon.
#define	MC_MTHT_ONITEMLABEL   (1 << 2)
	The coordinates hit the tab, but its icon or close button.
#define	MC_MTHT_ONITEMCLOSEBUTTON   (1 << 3)
	The coordinates hit the tab on its close button.
#define	MC_MTHT_ONITEM   (MC_MTHT_ONITEMICON | MC_MTHT_ONITEMLABEL | MC_MTHT_ONITEMCLOSEBUTTON)
	The coordinates hit the tab anywhere in its rectangle.

Control Messages
#define	MC_MTM_GETITEMCOUNT   (MC_MTM_FIRST + 0)
	Gets count of tabs.
#define	MC_MTM_GETIMAGELIST   (MC_MTM_FIRST + 1)
	Gets imagelist.
#define	MC_MTM_SETIMAGELIST   (MC_MTM_FIRST + 2)
	Sets imagelist.
#define	MC_MTM_DELETEALLITEMS   (MC_MTM_FIRST + 3)
	Delete all tab items.
#define	MC_MTM_INSERTITEMW   (MC_MTM_FIRST + 4)
	Inserts new tab into the tab control (unicode variant).
#define	MC_MTM_INSERTITEMA   (MC_MTM_FIRST + 5)
	Inserts new tab into the tab control (ANSI variant).
#define	MC_MTM_SETITEMW   (MC_MTM_FIRST + 6)
	Sets tab in the tab control (unicode variant).
#define	MC_MTM_SETITEMA   (MC_MTM_FIRST + 7)
	Sets tab in the tab control (ANSI variant).
#define	MC_MTM_GETITEMW   (MC_MTM_FIRST + 8)
	Gets tab data from the tab control (unicode variant).
#define	MC_MTM_GETITEMA   (MC_MTM_FIRST + 9)
	Gets tab data from the tab control (ANSI variant).
#define	MC_MTM_DELETEITEM   (MC_MTM_FIRST + 10)
	Deletes the item.
#define	MC_MTM_HITTEST   (MC_MTM_FIRST + 11)
	Tests which tab (and its part) is placed on specified position.
#define	MC_MTM_SETCURSEL   (MC_MTM_FIRST + 12)
	Selects a tab.
#define	MC_MTM_GETCURSEL   (MC_MTM_FIRST + 13)
	Gets indes of selected tab.
#define	MC_MTM_CLOSEITEM   (MC_MTM_FIRST + 14)
	Asks to close item.
#define	MC_MTM_SETITEMWIDTH   (MC_MTM_FIRST + 15)
	Sets default and minimal width for each tab.
#define	MC_MTM_GETITEMWIDTH   (MC_MTM_FIRST + 16)
	Gets default and minimal width for each tab.
#define	MC_MTM_INITSTORAGE   (MC_MTM_FIRST + 17)
	Preallocate enough memory for requested number of items.

Control Notifications
#define	MC_MTN_SELCHANGE   (MC_MTN_FIRST + 0)
	Fired when other tab has been selected.
#define	MC_MTN_DELETEITEM   (MC_MTN_FIRST + 1)
	Fired when a tab is being deleted.
#define	MC_MTN_DELETEALLITEMS   (MC_MTN_FIRST + 2)
	Fired when control processes MC_MTM_DELETEALLITEMS message or when it is being destroyed.
#define	MC_MTN_CLOSEITEM   (MC_MTN_FIRST + 3)
	Fired when user requests closing a tab item.

Unicode Resolution
#define	MC_WC_MDITAB   MCTRL_NAME_AW(MC_WC_MDITAB)
#define	MC_MTITEM   MCTRL_NAME_AW(MC_MTITEM)
#define	MC_MTM_INSERTITEM   MCTRL_NAME_AW(MC_MTM_INSERTITEM)
#define	MC_MTM_SETITEM   MCTRL_NAME_AW(MC_MTM_SETITEM)
#define	MC_MTM_GETITEM   MCTRL_NAME_AW(MC_MTM_GETITEM)

Detailed Description

MDI tab control (MC_WC_MDITAB).

This control is a replacement for standard multiple document interface (MDI), as that interface seems to be outdated, and does not reflect modern GUI requirements.

Instead this control provides user experience similar to the web browsers with tabbing support.

The control is very similar to the standard tab control from COMCTL32.DLL, both visually and from developer's point of view. There two main differences:

• MC_WC_MDITAB does not have the main bodyfor contents of the tab; i.e. the contents of the tab is not really rendered in child window of the MC_WC_MDITAB control.
• The contol laso provides few auxiliary buttons on it. They might be invisible depending on the control style and internal state. There is a button to close the current tab, to show pop-up menu of all tabs and finally buttons scrolling the tabs to left or right if there are too many.

Styles, messages and notifications the control supports mostly correspond to subset of messages and styles of the standard tab control. The counterparts have generally also the same names (differing only in prefix of the identifiers). If you are familiar with the standard tab control, you should be able to adopt MC_WC_MDITAB very quickly. However please note that the messages and styles are not interchangeable: The constants of styles and messages generally differ in their values.

Although the purpose of the control is to provide a replacement for the MDI, the programmatic interfaces very differs. If you want to replace MDI with this control in an existing application, expect it will take some time.

• In MDI, the child MDI windows can be minimalized or restored so they would not cover whole MDI client window. MC_WC_MDITAB control does not provide any replacement for this (anyway only very few users rarely used this feature of MDI). If your application needs to allow access to multiple documents simultaneously, you need to develop in other way with the MC_WC_MDITAB (e.g. to allow having multiple top level windows, each with the MC_WC_MDITAB to manage the documents open in each particular window).
• MDI absolutely expects that the application has its submenu Window, with all the commands like Tile horizontally or vertically, or too select another MDI document. MC_WC_MDITAB control does not expect that (still you are free to implement any menu you like ;-)

These standard messages are handled by the control:

• WM_GETFONT
• WM_SETFONT
• WM_SETREDRAW
• CCM_SETNOTIFYWINDOW
• CCM_SETWINDOWTHEME

These standard notifications are sent by the control:

• NM_OUTOFMEMORY
• NM_RELEASEDCAPTURE

---

Data Structure Documentation

struct MC_MTITEMW

Structure for manipulating with the tab item (unicode variant).

Structures

See Also

MC_MTM_INSERTITEM MC_MTM_SETITEM MC_MTM_GETITEM

Data Fields
DWORD	dwMask	Bit mask indicating which members of the structure are valid. See MC_MTIF_xxxx.
LPWSTR	pszText	Text label of the tab.
int	cchTextMax	Number of characters in pszText. Used only on output.
int	iImage	Index into control image list. Set to MC_I_IMAGENONE if no image is associated with the item.
LPARAM	lParam	User data.

struct MC_MTITEMA

Structure for manipulating with the tab item (ANSI variant).

See Also

MC_MTM_INSERTITEM MC_MTM_SETITEM MC_MTM_GETITEM

Data Fields
DWORD	dwMask	Bit mask indicating which members of the structure are valid. See MC_MTIF_xxxx.
LPSTR	pszText	Text label of the tab.
int	cchTextMax	Number of characters in psxText. Used only on output.
int	iImage	Index into control image list. Set to MC_I_IMAGENONE if no image is associated with the item.
LPARAM	lParam	User data.

struct MC_MTITEMWIDTH

Structure for messages MC_MTM_SETITEMWIDTH and MC_MTM_GETITEMWIDTH.

The control sizes all tabs to the same width. Normally they all have the default width. But if the control contains to many tab items and not all of them can be visible at once, the control is allowed to resize them as much as the minimal width specifies, so more of them can be visible without using the scrolling buttons.

Data Fields
DWORD	dwDefWidth	Default width for tabs, in pixels.
DWORD	dwMinWidth	Minimal width for tabs, in pixels.

struct MC_MTHITTESTINFO

Structure for message MC_MTM_HITTEST.

Data Fields
POINT	pt	Coordinates to test.
UINT	flags	On output, set to the result of the test.

struct MC_NMMTSELCHANGE

Structure for notification MC_MTN_SELCHANGE.

Data Fields
NMHDR	hdr	Common notification structure header.
int	iItemOld	Index of previously selected tab.
LPARAM	lParamOld	Data of previously selected tab, or zero.
int	iItemNew	Index of newly selected tab
LPARAM	lParamNew	Data of newly selected tab, or zero.

struct MC_NMMTDELETEITEM

Structure for notification MC_MTN_DELETEITEM.

Data Fields
NMHDR	hdr	Common notification structure header.
int	iItem	Index of the item being deleted.
LPARAM	lParam	User data of the item being deleted.

struct MC_NMMTCLOSEITEM

Structure for notification MC_MTN_CLOSEITEM.

Data Fields
NMHDR	hdr	Common notification structure header.
int	iItem	Index of the item being closed.
LPARAM	lParam	User data of the control being closed.

Macro Definition Documentation

#define MC_WC_MDITABW   L"mCtrl.mditab"

Window class name (unicode variant).

#define MC_WC_MDITABA   "mCtrl.mditab"

Window class name (ANSI variant).

#define MC_MTS_CBONTOOLBAR   0x0000

Show close button on right side of the control. This is default.

#define MC_MTS_CBONEACHTAB   0x0001

Not supported, reserved for future use.

#define MC_MTS_CBONACTIVETAB   0x0002

Not supported, reserved for future use.

#define MC_MTS_CBNONE   0x0003

Don't show close button.

#define MC_MTS_CBMASK   0x0003

This is not valid style, its bitmask of MC_MTS_CBxxx styles.

#define MC_MTS_TLBALWAYS   0x0000

Popup tab list button is shown always. This is default.

#define MC_MTS_TLBONSCROLL   0x0004

Popup tab list button is shown if scrolling is triggered on.

#define MC_MTS_TLBNEVER   0x0008

Popup tab list button is never displayed.

#define MC_MTS_TLBMASK   0x000C

This is not valid style, but bitmask of MC_NTS_TLBxxx styles.

#define MC_MTS_SCROLLALWAYS   0x0010

Always shows scrolling buttons.

#define MC_MTS_CLOSEONMCLICK   0x0020

Middle click closes a tab.

#define MC_MTS_FOCUSONBUTTONDOWN   0x0040

Mouse button down gains focus.

#define MC_MTS_FOCUSNEVER   0x0080

Never gains focus.

#define MC_MTS_FOCUSMASK   0x00C0

This is not valid style, but bitmask of MC_NTS_FOCUSxxx styles.

#define MC_MTS_DOUBLEBUFFER   0x0100

Enable painting with double buffering.

It prevents flickering when the control is being continuously resized.

#define MC_MTIF_TEXT   (1 << 0)

MC_MTITEMW::pszText or MC_MTITEMA::pszText is valid.

#define MC_MTIF_IMAGE   (1 << 1)

MC_MTITEMW::iImage or MC_MTITEMA::iImage is valid.

#define MC_MTIF_PARAM   (1 << 2)

MC_MTITEMW::lParam or MC_MTITEMA::lParam is valid.

#define MC_MTHT_NOWHERE   (1 << 0)

The hit test coordinates are outside of any tabs.

#define MC_MTHT_ONITEMICON   (1 << 1)

The coordinates hit the tab on its icon.

#define MC_MTHT_ONITEMLABEL   (1 << 2)

The coordinates hit the tab, but its icon or close button.

#define MC_MTHT_ONITEMCLOSEBUTTON   (1 << 3)

The coordinates hit the tab on its close button.

#define MC_MTHT_ONITEM   (MC_MTHT_ONITEMICON | MC_MTHT_ONITEMLABEL | MC_MTHT_ONITEMCLOSEBUTTON)

The coordinates hit the tab anywhere in its rectangle.

#define MC_MTM_GETITEMCOUNT   (MC_MTM_FIRST + 0)

Gets count of tabs.

Parameters

wParam	Reserved, set to zero.
lParam	Reserved, set to zero.

Returns

(int) Count of tabs.

#define MC_MTM_GETIMAGELIST   (MC_MTM_FIRST + 1)

Gets imagelist.

Parameters

wParam	Reserved, set to zero.
lParam	Reserved, set to zero.

Returns

(HIMAGELIST) The image list, or NULL.

See Also

MC_MTM_SETIMAGELIST

#define MC_MTM_SETIMAGELIST   (MC_MTM_FIRST + 2)

Sets imagelist.

The tab items can refer to the images in the list with MC_MTITEM::iImage.

Parameters

	wParam	Reserved, set to zero.
[in]	lParam	(HIMAGELIST) The imagelist.

Returns

(HIMAGELIST) Old image list, or NULL.

See Also

MC_MTM_GETIMAGELIST

#define MC_MTM_DELETEALLITEMS   (MC_MTM_FIRST + 3)

Delete all tab items.

The control sends MC_MTN_DELETEALLITEMS notification. Depending on the return value from the notifications, it may also send notification MC_MTN_DELETEITEM for each tab being deleted.

Parameters

wParam	Reserved, set to zero.
lParam	Reserved, set to zero.

Returns

(BOOL) TRUE on success, FALSE otherwise.

See Also

MC_MTM_DELETEITEM

#define MC_MTM_INSERTITEMW   (MC_MTM_FIRST + 4)

Inserts new tab into the tab control (unicode variant).

Parameters

[in]	wParam	(int) Index of the new item.
[in]	lParam	(MC_MTITEM*) Pointer to detailed data of the new tab.

Returns

(int) index of the new tab, or -1 on failure.

#define MC_MTM_INSERTITEMA   (MC_MTM_FIRST + 5)

Inserts new tab into the tab control (ANSI variant).

Parameters

[in]	wParam	(int) Index of the new item.
[in]	lParam	(MC_MTITEM*) Pointer to detailed data of the new tab.

Returns

(int) index of the new tab, or -1 on failure.

#define MC_MTM_SETITEMW   (MC_MTM_FIRST + 6)

Sets tab in the tab control (unicode variant).

Parameters

[in]	wParam	(int) Index of the item.
[in]	lParam	(MC_MTITEMW*) Pointer to detailed data of the tab.

Returns

(BOOL) TRUE on success, FALSE otherwise.

#define MC_MTM_SETITEMA   (MC_MTM_FIRST + 7)

Sets tab in the tab control (ANSI variant).

Parameters

[in]	wParam	(int) Index of the item.
[in]	lParam	(MC_MTITEMA*) Pointer to detailed data of the tab.

Returns

(BOOL) TRUE on success, FALSE otherwise.

#define MC_MTM_GETITEMW   (MC_MTM_FIRST + 8)

Gets tab data from the tab control (unicode variant).

Application has to set MC_MTITEM::dwMask prior sending the message to indicate what attributes of the item to retrieve. If the application uses MC_MTIF_TEXT, then it also has to set MC_MTITEM::pszText to point to a buffer where the text will be stored and set MC_MTITEM::cchTextMax to specify size of the buffer.

Parameters

[in]	wParam	(int) Index of the item.
[out]	lParam	(MC_MTITEMW*) Pointer to detailed data of the tab, receiving the data according to MC_MTITEM::dwMask.

Returns

(BOOL) TRUE on success, FALSE otherwise.

#define MC_MTM_GETITEMA   (MC_MTM_FIRST + 9)

Gets tab data from the tab control (ANSI variant).

Application has to set MC_MTITEM::dwMask prior sending the message to indicate what attributes of the item to retrieve. If the application uses MC_MTIF_TEXT, then it also has to set MC_MTITEM::pszText to point to a buffer where the text will be stored and set MC_MTITEM::cchTextMax to specify size of the buffer.

Parameters

[in]	wParam	(int) Index of the item.
[in,out]	lParam	(MC_MTITEMA*) Pointer to detailed data of the tab, receiving the data according to MC_MTITEM::dwMask.

Returns

(BOOL) TRUE on success, FALSE otherwise.

#define MC_MTM_DELETEITEM   (MC_MTM_FIRST + 10)

Deletes the item.

Sends MC_MTN_DELETEITEM notification to parent window.

Parameters

[in]	wParam	(int) Index of tab to be deleted.
	lParam	Reserved, set to zero.

Returns

(BOOL) TRUE on success, FALSE otherwise.

#define MC_MTM_HITTEST   (MC_MTM_FIRST + 11)

Tests which tab (and its part) is placed on specified position.

Parameters

	wParam	Reserved, set to zero.
[in,out]	lParam	(MC_MTHITTESTINFO*) Pointer to a hit test structure. Set MC_MTHITTESTINFO::pt on input.

Returns

(int) Index of the hit tab, or -1.

#define MC_MTM_SETCURSEL   (MC_MTM_FIRST + 12)

Selects a tab.

Parameters

[in]	wParam	(int) Index of the tab to select.
	lParam	Reserved, set to zero.

Returns

(int) Index of previously selected tab, or -1.

#define MC_MTM_GETCURSEL   (MC_MTM_FIRST + 13)

Gets indes of selected tab.

Parameters

wParam	Reserved, set to zero.
lParam	Reserved, set to zero.

Returns

(int) Index of selected tab, or -1.

#define MC_MTM_CLOSEITEM   (MC_MTM_FIRST + 14)

Asks to close item.

It causes to send MC_MTN_CLOSEITEM notification and depening on its return value it then can cause deleteing the item.

Parameters

[in]	wParam	(int) Index of the item to be closed.
	lParam	Reserved, set to zero.

Returns

(BOOL) TRUE on success, FALSE otherwise.

#define MC_MTM_SETITEMWIDTH   (MC_MTM_FIRST + 15)

Sets default and minimal width for each tab.

If there is enough space, all tabs have the default width. When there are too many widths, they are made narrower so more tabs fit into the visible space area, but never narrower then the minimal width.

Parameters

	wParam	Reserved, set to zero.
[in]	lParam	(MC_MTITEMWIDTH*) Pointer to a structure specifying the default and minimal widths. When NULL is passed, the values are reset to built-in defaults.

Returns

(BOOL) TRUE on success, FALSE otherwise.

See Also

MC_MTM_GETITEMWIDTH

#define MC_MTM_GETITEMWIDTH   (MC_MTM_FIRST + 16)

Gets default and minimal width for each tab.

Parameters

	wParam	Reserved, set to zero.
[out]	lParam	(MC_MTITEMWIDTH*) Pointer to a structure where the current widths will be set.

Returns

(BOOL) TRUE on success, FALSE otherwise.

See Also

MC_MTM_SETITEMWIDTH

#define MC_MTM_INITSTORAGE   (MC_MTM_FIRST + 17)

Preallocate enough memory for requested number of items.

You may want to use this message before adding higher number of items into the controls to speed it up by avoiding multiple reallocations.

Parameters

[in]	wParam	(UINT) The number of items to add.
	lParam	Reserved, set to zero.

Returns

(BOOL) TRUE on success, FALSE otherwise.

#define MC_MTN_SELCHANGE   (MC_MTN_FIRST + 0)

Fired when other tab has been selected.

Parameters

[in]	wParam	(int) Id of the control sending the notification.
[in]	lParam	(MC_NMMTSELCHANGE*) Pointer to a structure specifying details about the selection change.

Returns

Application should return zero, if it processes the message.

#define MC_MTN_DELETEITEM   (MC_MTN_FIRST + 1)

Fired when a tab is being deleted.

Parameters

[in]	wParam	(int) Id of the control sending the notification.
[in]	lParam	(MC_NMMTDELETEITEM*) Pointer to a structure specifying details about the item being deleted.

Returns

Application should return zero if it processes the notification.

#define MC_MTN_DELETEALLITEMS   (MC_MTN_FIRST + 2)

Fired when control processes MC_MTM_DELETEALLITEMS message or when it is being destroyed.

Depending on the value returned from the notification, calling MC_MTN_DELETEITEM notifications for all the items can be supressed.

Parameters

[in]	wParam	(int) Id of the control sending the notification.
[in]	lParam	(NMHDR*)

Returns

Application should return FALSE to receive subsequent MC_MTN_DELETEITEM for each item; or TRUE to supress sending them.

#define MC_MTN_CLOSEITEM   (MC_MTN_FIRST + 3)

Fired when user requests closing a tab item.

Parameters

[in]	wParam	(int) Id of the control sending the notification.
[in]	lParam	(MC_NMMTCLOSEITEM*) Pointer to a structure specifying details about the item being closed.

Returns

Application should return FALSE to remove the tab (the tab is then deleted and MC_MTN_DELETEITEM notification is sent); or TRUE to cancel the tab closure.

#define MC_WC_MDITAB   MCTRL_NAME_AW(MC_WC_MDITAB)

Unicode-resolution alias.

See Also

MC_WC_MDITABW MC_WC_MDITABA

#define MC_MTITEM   MCTRL_NAME_AW(MC_MTITEM)

Unicode-resolution alias.

See Also

MC_MTITEMW MC_MTITEMA

#define MC_MTM_INSERTITEM   MCTRL_NAME_AW(MC_MTM_INSERTITEM)

Unicode-resolution alias.

See Also

MC_MTM_INSERTITEMW MC_MTM_INSERTITEMA

#define MC_MTM_SETITEM   MCTRL_NAME_AW(MC_MTM_SETITEM)

Unicode-resolution alias.

See Also

MC_MTM_SETITEMW MC_MTM_SETITEMA

#define MC_MTM_GETITEM   MCTRL_NAME_AW(MC_MTM_GETITEM)

Unicode-resolution alias.

See Also

MC_MTM_GETITEMW MC_MTM_GETITEMA

Function Documentation

BOOL mcMditab_Initialize

(

void

)

Registers window class of the control.

Returns

TRUE on success, FALSE on failure.

void mcMditab_Terminate

(

void

)

Unregisters window class of the control.