9. The special types of menu and their implementation in mfc

9.1 The description of special menu styles

This section is devoted to the two stand-alone types of falling menus: dynamic and floating. They provide incredibly more possibilities on control and usage of menus in applications. But first of all, it’s need to have a view on important type of functions, presented in MFC – the handlers of menu changing, using which it’s possible to control the state of menu elements.

The handlers of changing define the status of menu elements display. In MFC-program, there is a special processing level, executing in time, then the falling menu is activated, but isn’t displayed on the display yet. Between these two events, there is called the set of handlers, switched to that menu. For every element of falling menu there is own handler of changing, defining is the selected element accessed or no. This handler can also set the label of selection with the name of element and change the text of title. The menu is displayed, when all the handlers are executed. Therefore, the handlers of changing are used for a definite state of falling menu on every it’s displaying.

There is the question: why we haven’t said anything about the handlers of changing earlier, because they are fundamental in working with MFC. Answer is simple; all the menus are linked to the in-built handlers of changing, containing in MFC. But on increasing of our program difficulty, we need control that process.

The mechanism to make changes in menus

On falling menu activation, the program is sent by WM_INITMENUPOPUP. That message is automatically intercepted by MFC and transformed to the call of corresponding handler of changing. As it was already said, every element of falling menu is linked to own handler of changing. If for some element it isn’t defined in the program, there is called the corresponding handler.

The standard handlers of changing, implemented in MFC, provide the simple but effective way to control the menu. Their work is organized in the following way: every element of falling menu, which is referenced by macro-command ON_COMMAND() in the messages map, is accessible, but the elements, which have no such macro commands have no access.

Any actions, made with menu, can be overfilled by actions of standard handlers of changing, because these handlers always executed the last. For example, if to declare any menu element as inaccessible, that declaration will not be active, if for the considered element the macro command ON_COMMAND is included to the messages map. In that case, the standard handler of changing automatically makes elements accessible, and there is no difference, what actions were fulfilled before.

The mechanism of automatic change making in the menu can be switched off. To make that, it’s need the variable m_pAutoMenuEnable of class CFrameWnd setting to FALSE. In that case, all the actions, provided in the program, will actually provided. That means, there is need to make the software engine to control the elements of menu (that way is used really seldom, because it’s more simple to implement own handlers).

The definition for handlers of changing

To define the own handler of changing is easy enough. It’s really need to make two steps. Firstly, you need for every processed menu element, to include the macro-command ON_UPDATE_COMMAND_UI() to the messages map. After you need to implement the handler. Macro ON_UPDATE_COMMAND_UI() has the following view:

ON_UPDATE_COMMAND_UI(ID, Handler)

Here, the ID is identity of processed menu element, Handler is the name of corresponding handler. Every handler of changing have to be of the following prototype:

afx_msg void Handler(CCmdUI *UIOb);

Here, the parameter UIOb is a pointer to CCmdUI class object.

CCmdUI is a special class, existing exclusively to support the mechanism of changing make in the menu. It isn’t part of MFC, so isn’t derived from CObject. It is used to define the types of parameters only. Class CCmdUI contains a number of functions to control the elements of menu. One of them is Enable() function. It’s has the following prototype:

void CCmdUI::Enable( BOOL bOn = TRUE );

Parameters: bOn   TRUE to enable the item, FALSE to disable it.

Also, the functions of CCmdUi class provide the label of choice selection for menu items.

When, every of two actions are provided, the handler of changing will be call in place of standard handler. Remember, that you needn’t define the all handlers for menu item. Some of them are provided automatically.

The Dynamic menus

While the most of simple programs in Windows use the static menu definition, the complex programs often require dynamically to insert or to delete the elements of menu directly in time of application working on some conditions/ For example, in the text editors, there can be different commands, in dependence of file type. The menu, context of which can change in time of application work is usually called dynamic menu.

Adding elements to the menu

To add the elements in time of application execution there is used InsertItem() function with such prototypes:

BOOL CMenu::InsertMenu(UINT nPosition, UINT nFlags, UINT nIDNewItem = 0, LPCTSTR lpszNewItem = NULL );

BOOL CMenu::InsertMenu(UINT nPosition, UINT nFlags, UINT nIDNewItem, const CBitmap* pBmp );

Parameters

nPosition   Specifies the menu item before which the new menu item is to be inserted. The nFlags parameter can be used to interpret nPosition in the following ways:

nFlags	Interpretation of nPosition
MF_BYCOMMAND	Specifies that the parameter gives the command ID of the existing menu item. This is the default if neither MF_BYCOMMAND nor MF_BYPOSITION is set.
MF_BYPOSITION	Specifies that the parameter gives the position of the existing menu item. The first item is at position 0. If nPosition is –1, the new menu item is appended to the end of the menu.

nFlags   Specifies how nPosition is interpreted and specifies information about the state of the new menu item when it is added to the menu. For a list of the flags that may be set, see the AppendMenu member function. To specify more than one value, use the bitwise OR operator to combine them with the MF_BYCOMMAND or MF_BYPOSITION flag.

nIDNewItem   Specifies either the command ID of the new menu item or, if nFlags is set to MF_POPUP, the menu handle (HMENU) of the pop-up menu. The nIDNewItem parameter is ignored (not needed) if nFlags is set to MF_SEPARATOR.

lpszNewItem   Specifies the content of the new menu item. nFlags can be used to interpret lpszNewItem in the following ways:

nFlags	Interpretation of lpszNewItem
MF_OWNERDRAW	Contains an application-supplied 32-bit value that the application can use to maintain additional data associated with the menu item. This 32-bit value is available to the application in the itemData member of the structure supplied by the WM_MEASUREITEM and WM_DRAWITEM messages. These messages are sent when the menu item is initially displayed or is changed.
MF_STRING	Contains a long pointer to a null-terminated string. This is the default interpretation.
MF_SEPARATOR	The lpszNewItem parameter is ignored (not needed).

pBmp   Points to a CBitmap object that will be used as the menu item.

To append the new element to the end of menu, there can be used CMenu::AppendMenu() function. It’s definition in MFC:

Начало формы

Конец формы

BOOL CMenu::AppendMenu( UINT nFlags, UINT nIDNewItem = 0, LPCTSTR lpszNewItem = NULL );

BOOL CMenu::AppendMenu( UINT nFlags, UINT nIDNewItem, const CBitmap* pBmp );

Return Value : Nonzero if the function is successful; otherwise 0.

Parameters:

nFlags   Specifies information about the state of the new menu item when it is added to the menu. It consists of one or more of the values listed in the Remarks section.

nIDNewItem   Specifies either the command ID of the new menu item or, if nFlags is set to MF_POPUP, the menu handle (HMENU) of a pop-up menu. The nIDNewItem parameter is ignored (not needed) if nFlags is set to MF_SEPARATOR.

lpszNewItem   Specifies the content of the new menu item. The nFlags parameter is used to interpret lpszNewItem in the following way:

nFlags	Interpretation of lpszNewItem
MF_OWNERDRAW	Contains an application-supplied 32-bit value that the application can use to maintain additional data associated with the menu item. This 32-bit value is available to the application when it processes WM_MEASUREITEM and WM_DRAWITEM messages. The value is stored in the itemData member of the structure supplied with those messages.
MF_STRING	Contains a pointer to a null-terminated string. This is the default interpretation.
MF_SEPARATOR	The lpszNewItem parameter is ignored (not needed).

pBmp   Points to a CBitmap object that will be used as the menu item.

Appends a new item to the end of a menu. The application can specify the state of the menu item by setting values in nFlags. When nIDNewItem specifies a pop-up menu, it becomes part of the menu to which it is appended. If that menu is destroyed, the appended menu will also be destroyed. An appended menu should be detached from a CMenu object to avoid conflict. Note that MF_STRING and MF_OWNERDRAW are not valid for the bitmap version of AppendMenu.

The following list describes the flags that may be set in nFlags:

• MF_CHECKED   Acts as a toggle with MF_UNCHECKED to place the default check mark next to the item. When the application supplies check-mark bitmaps (see the SetMenuItemBitmaps member function), the "check mark on" bitmap is displayed.

• MF_UNCHECKED   Acts as a toggle with MF_CHECKED to remove a check mark next to the item. When the application supplies check-mark bitmaps (see the SetMenuItemBitmaps member function), the "check mark off" bitmap is displayed.

• MF_DISABLED   Disables the menu item so that it cannot be selected but does not dim it.

• MF_ENABLED   Enables the menu item so that it can be selected and restores it from its dimmed state.

• MF_GRAYED   Disables the menu item so that it cannot be selected and dims it.

• MF_MENUBARBREAK   Places the item on a new line in static menus or in a new column in pop-up menus. The new pop-up menu column will be separated from the old column by a vertical dividing line.

• MF_MENUBREAK   Places the item on a new line in static menus or in a new column in pop-up menus. No dividing line is placed between the columns.

• MF_OWNERDRAW   Specifies that the item is an owner-draw item. When the menu is displayed for the first time, the window that owns the menu receives a WM_MEASUREITEM message, which retrieves the height and width of the menu item. The WM_DRAWITEM message is the one sent whenever the owner must update the visual appearance of the menu item. This option is not valid for a top-level menu item.

• MF_POPUP   Specifies that the menu item has a pop-up menu associated with it. The ID parameter specifies a handle to a pop-up menu that is to be associated with the item. This is used for adding either a top-level pop-up menu or a hierarchical pop-up menu to a pop-up menu item.

• MF_SEPARATOR   Draws a horizontal dividing line. Can only be used in a pop-up menu. This line cannot be dimmed, disabled, or highlighted. Other parameters are ignored.

• MF_STRING   Specifies that the menu item is a character string.

Each of the following groups lists flags that are mutually exclusive and cannot be used together:

• MF_DISABLED, MF_ENABLED, and MF_GRAYED

• MF_STRING, MF_OWNERDRAW, MF_SEPARATOR, and the bitmap version

• MF_MENUBARBREAK and MF_MENUBREAK

• MF_CHECKED and MF_UNCHECKED

Whenever a menu that resides in a window is changed (whether or not the window is displayed), the application should call CWnd::DrawMenuBar.

To delete the element from menu, there is used DeleteMenu() function. It has the following prototype:

Начало формы

Конец формы

BOOL CMenu::DeleteMenu( UINT nPosition, UINT nFlags );

Return Value : Nonzero if the function is successful; otherwise 0.

Parameters :

nPosition   Specifies the menu item that is to be deleted, as determined by nFlags.

nFlags   Is used to interpret nPosition in the following way:

nFlags	Interpretation of nPosition
MF_BYCOMMAND	Specifies that the parameter gives the command ID of the existing menu item. This is the default if neither MF_BYCOMMAND nor MF_BYPOSITION is set.
MF_BYPOSITION	Specifies that the parameter gives the position of the existing menu item. The first item is at position 0.

To find the number of elements in menu, use function:

UINT CMenu::GetMenuItemCount();

CMenu class contains a number of functions, to control menu. One of them – EnableMenuItem(), used to change the state of menu element (active / non-active). Really, the need of this function is seldom, because of standard handlers overfilling.

The constructor of CMenu class

To use the functions of CMenu class you need make by means of pointer to CMenu class object or object itself. Often of all, there is used the pointer to the main menu of application. To make that, it’s need to declare the object of CMenu class by the CMenu() constructor. This constructor creates an empty object, so before operations with object, the menu is linked to him.

As it’s known, often of all the main menu is defined in file of program resources. To control this menu dynamically (also all it’s submenus), there is need some kind of access to it. To have the pointer to main menu object, use GetMenu() function with such prototype:

CMenu* CWnd::GetMenu( ) const;

Return Value is identifier of menu. The value is NULL if CWnd has no menu. The return value is undefined if CWnd is a child window.

Having the pointer to main menu object you can easily get the pointers to the objects of submenu, containing in the main menu. That can be provided by GetSubMenu() function:

CMenu* CMenu::GetSubMenu( int nPos ) const;

Return Value: A pointer to a CMenu object whose m_hMenu member contains a handle to the pop-up menu if a pop-up menu exists at the given position; otherwise NULL. If a CMenu object does not exist, then a temporary one is created. The CMenu pointer returned should not be stored.

Parameters :

nPos   Specifies the position of the pop-up menu contained in the menu. Position values start at 0 for the first menu item. The pop-up menu's identifier cannot be used in this function.