menubar.h File Reference

Go to the source code of this file.

Detailed Description

Menu bar control (MC_WC_MENUBAR).

The MC_WC_MENUBAR is implantation of a control generally known as Internet Explorer-Style Menu Bar. It is a control which can host a menu (here represented by a menu handle, HMENU), but which generally works as a tool-bar.

The standard menus take whole width of the window for their menu-bars, and there can only be used one menu in a top-level windows. Child windows cann ot have a menu at all (well, we are not talking about pop-up menus).

The MC_WC_MENUBAR offers solution to these problems. It has been designed with especially following use cases in mind:

• Embedding the menu into a standard ReBar control from COMCTL32.DLL.
• Positioning the control on other position or with different size then what is normally enforced for normal menu of a window or dialog.
• Possibility to create this control in child windows, or having multiple menu-bars in a single window.

Subclassed Tool Bar

Actually the MC_WC_MENUBAR is implemented as a subclass of the standard tool-bar (from COMCTL32.DLL) control, so you can use its style, and also some tool-bar messages.

Of course there are also differences: The menu-bar control automatically sets some tool-bar styles when created, as it sees fit for its purpose. Application still can reset it with SetWindowLong and GWL_STYLE.

Furthermore the menu-bar control does not support tool-bar messages which add, modify or remove tool-bar buttons. The control just manages them automatically to reflect the installed menu.

I.e. sending any of these tool-bar messages to the control always fails:

• TB_ADDBITMAP
• TB_ADDSTRING
• TB_ADDBUTTONS
• TB_BUTTONSTRUCTSIZE
• TB_CHANGEBITMAP
• TB_CUSTOMIZE
• TB_DELETEBUTTON
• TB_ENABLEBUTTON
• TB_HIDEBUTTON
• TB_INDETERMINATE
• TB_INSERTBUTTON
• TB_LOADIMAGES
• TB_MARKBUTTON
• TB_MOVEBUTTON
• TB_PRESSBUTTON
• TB_REPLACEBITMAP
• TB_SAVERESTORE
• TB_SETANCHORHIGHLIGHT
• TB_SETBITMAPSIZE
• TB_SETBOUNDINGSIZE
• TB_SETCMDID
• TB_SETDISABLEDIMAGELIST
• TB_SETHOTIMAGELIST
• TB_SETIMAGELIST
• TB_SETINSERTMARK
• TB_SETPRESSEDIMAGELIST
• TB_SETSTATE

Installing a Menu

To install a menu in the menu-bar, you may set parameter lpParam of CreateWindow or CreateWindowEx to the handle of the menu (HMENU). Or, after the menu-bar is created, you may install a menu with the message MC_MBM_SETMENU.

Either way the application is responsible to keep the menu handle valid as long as the menu-bar exists (or until other menu is installed in the menu-bar).

Note however that changes to the menu are not automatically reflected in the menu-bar. If application programatically changes top-level items of the menu (for example add new pop-ups, disable some of them etc.), it then has to send MC_MBM_REFRESH to reflect the changes.

Notifications

The control sends notifications of both, the tool-bar and menu.

To handle the actions corresponding to the menu items, application uses the notification WM_COMMAND as with a normal menu. It can also take use of WM_MENUSELECT and WM_INITMENU.

Tool-bar notifications are sent through WM_NOTIFY. For example, TBN_DROPDOWN or TBN_HOTITEMCHANGE are sent as any other notifications normal tool-bar fires.

All the notifications are sent by default to a window which was parent of the menu-bar when creating the menu-bar. One exception is if the parent is a ReBar control: Because it will often be the case and the ReBar control cannot handle the notifications properly, they are then sent to the grand-father of the menu-bar (i.e. parent of the ReBar).

Application can also explicitly set the target window of the notifications with the standard tool-bar message TB_SETPARENT.

Hot Keys

To work as intended, the control requires some cooperation with the application. The message loop in the application should call the function mcIsMenubarMessage to handle hot keys of the menu items and allow to activate the menu with the key F10.

Hence code of the message loop in applications using the menu-bar control should be similar to the example below:

MSG msg;
while(GetMessage(&msg, NULL, 0, 0)) {
    if(TranslateAccelerator(hWnd, hAccel, &msg))
        continue;
    if(mcIsMenubarMessage(hwndMenubar, &msg))
        continue;
    if(IsDialogMessage(hWnd, &msg))
        continue;

    TranslateMessage(&msg);
    DispatchMessage(&msg);
}

Standard Messages

These standard messages are handled by the control:

• CCM_SETNOTIFYWINDOW

These standard notifications are sent by the control:

• NM_OUTOFMEMORY

Initialization Functions
BOOL	mcMenubar_Initialize (void)
void	mcMenubar_Terminate (void)

Related Functions
BOOL	mcIsMenubarMessage (HWND hwndMenubar, LPMSG lpMsg)
	Determines whether a message is intended for the specified menu-bar control and, if it is, processes the message. More...

Window Class
#define	MC_WC_MENUBARW   L"mCtrl.menubar"
#define	MC_WC_MENUBARA   "mCtrl.menubar"

Control Messages
#define	MC_MBM_SETMENU   (MC_MBM_FIRST + 0)
	Install a menu into the menu-bar. More...
#define	MC_MBM_REFRESH   (MC_MBM_FIRST + 1)
	Updates the menu-bar to reflect changes in the installed menu. More...

Unicode Resolution
#define	MC_WC_MENUBAR   MCTRL_NAME_AW(MC_WC_MENUBAR)

Macro Definition Documentation

#define MC_WC_MENUBARW   L"mCtrl.menubar"

Window class name (Unicode variant).

#define MC_WC_MENUBARA   "mCtrl.menubar"

Window class name (ANSI variant).

#define MC_MBM_SETMENU   (MC_MBM_FIRST + 0)

Install a menu into the menu-bar.

Parameters

	wParam	Reserved, set to zero.
[in]	lParam	(HMENU) The menu to install.

Returns

(BOOL) TRUE on success, FALSE otherwise.

#define MC_MBM_REFRESH   (MC_MBM_FIRST + 1)

Updates the menu-bar to reflect changes in the installed menu.

Application has to send this messages after it changes the top-level menu items (e.g. adds or deleted a sub-menu, enables or disables a sub-menu etc.).

Parameters

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

Returns

(BOOL) TRUE on success, FALSE otherwise.

#define MC_WC_MENUBAR   MCTRL_NAME_AW(MC_WC_MENUBAR)

Unicode-resolution alias.

See Also

MC_WC_MENUBARW MC_WC_MENUBARA

Function Documentation

BOOL mcMenubar_Initialize

(

void

)

Registers window class of the control.

Returns

TRUE on success, FALSE on failure.

void mcMenubar_Terminate

(

void

)

Unregisters window class of the control.

BOOL mcIsMenubarMessage	(	HWND	hwndMenubar,
		LPMSG	lpMsg
	)

Determines whether a message is intended for the specified menu-bar control and, if it is, processes the message.

The application typically calls this function in main message loop.

Parameters

hwndMenubar	The menu-bar control.
lpMsg	The message.

Returns

TRUE, if the message has been processed; FALSE otherwise.