mCtrl  0.9.2
menubar.h File Reference

Menu bar control (MC_WC_MENUBAR). More...

Go to the source code of this file.

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 menubar 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 menubar. More...
 
#define MC_MBM_REFRESH   (MC_MBM_FIRST + 1)
 Updates the menubar to reflect changes in the installed menu. More...
 

Unicode Resolution

#define MC_WC_MENUBAR   MCTRL_NAME_AW(MC_WC_MENUBAR)
 

Detailed Description

Menu bar control (MC_WC_MENUBAR).

The MC_WC_MENUBAR is implentation 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 toolbar.

The standard menus take whole width of the window for their menubars, 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 popup menus).

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

Subclassed Toolbar

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

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

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

I.e. sending any of these toolbar messages to the control always fails:

Installing a Menu

To install a menu in the menubar, you may set parameter lpParam of CreateWindow or CreateWindowEx to the handle of the menu (HMENU). Or, after the menubar 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 menubar exists (or until other menu is installed in the menubar).

Note however that changes to the menu are not automatically rflected in the menubar. If application programatically changes top-level items of the menu (for example add new popups, 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 toolbar 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.

Toolbar notifications are sent through WM_NOTIFY. For example, TBN_DROPDOWN or TBN_HOTITEMCHANGE are sent as any other notifications normal toolbar fires.

All the notifications are sent by default to a window which was parent of the menubar when creating the menubar. 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 propperly, they are then sent to the grand-father of the menubar (i.e. parent of the ReBar).

Application can also explicitly set the target window of the notifications with the standard toolbar 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 menubar 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:

These standard notifications are sent by the control:

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 menubar.

Parameters
wParamReserved, 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 menubar 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 submenu, enables or disables a submenu etc.).

Parameters
wParamReserved, set to zero.
lParamReserved, 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 menubar control and, if it is, processes the message.

The application typically calls this function in main message loop.

Parameters
hwndMenubarThe menubar control.
lpMsgThe message.
Returns
TRUE, if the message has been processed; FALSE otherwise.