CCmdUI class in MFC

MFC ccmdui class

1. CCmdUI Class

Is used only within an ON_UPDATE_COMMAND_UI handler in a CCmdTarget-derived class..

Remarks CCmdUI does not have a base class.

When a user of your application pulls down a menu, each menu item needs to know whether it should be displayed as enabled or disabled. The target of a menu command provides this information by implementing an ON_UPDATE_COMMAND_UI handler. For each of the command user-interface objects in your application, use the Class Wizard or Properties window (in Class View) to create a message-map entry and function prototype for each handler.

When the menu is pulled down, the framework searches for and calls each ON_UPDATE_COMMAND_UI handler, each handler calls CCmdUI member functions such as Enable and Check, and the framework then appropriately displays each menu item.

A menu item can be replaced with a control-bar button or other command user-interface object without changing the code within the ON_UPDATE_COMMAND_UI handler.

The following table summarizes the effect CCmdUI's member functions have on various command user-interface items.

2. The CCmdUI Class

When it routes an update command to its handler, the framework passes the handler a pointer to a CCmdUI object (or to an object of a CCmdUI-derived class). This object represents the menu item or toolbar button or other user-interface object that generated the command. The update handler calls member functions of the CCmdUI structure through the pointer to update the user-interface object. For example, here is an update handler for the Clear All menu item:

void CMyWinApp::OnUpdateEditClearAll(CCmdUI *pCmdUI) { pCmdUI->Enable(m_bClearAllAvailable); }

This handler calls the Enable member function of an object with access to the menu item. Enable makes the item available for use.

3. How to: Update User-Interface Objects

Typically, menu items and toolbar buttons have more than one state. For example, a menu item is grayed (dimmed) if it is unavailable in the present context. Menu items can also be checked or unchecked. A toolbar button can also be disabled if unavailable, or it can be checked.

Who updates the state of these items as program conditions change Logically, if a menu item generates a command that is handled by, say, a document, it makes sense to have the document update the menu item. The document probably contains the information on which the update is based.

If a command has multiple user-interface objects (perhaps a menu item and a toolbar button), both are routed to the same handler function. This encapsulates your user-interface update code for all of the equivalent user-interface objects in a single place.

The framework provides a convenient interface for automatically updating user-interface objects. You can choose to do the updating in some other way, but the interface provided is efficient and easy to use.

4. When Update Handlers Are Called

Suppose the user clicks the mouse in the File menu, which generates a WM_INITMENUPOPUP message. The framework's update mechanism collectively updates all items on the File menu before the menu drops down so the user can see it.

To do this, the framework routes update commands for all menu items in the pop-up menu along the standard command routing. Command targets on the routing have an opportunity to update any menu items by matching the update command with an appropriate message-map entry (of the form ON_UPDATE_COMMAND_UI) and calling an "update handler" function. Thus, for a menu with six menu items, six update commands are sent out. If an update handler exists for the command ID of the menu item, it is called to do the updating. If not, the framework checks for the existence of a handler for that command ID and enables or disables the menu item as appropriate.

If the framework does not find an ON_UPDATE_COMMAND_UI entry during command routing, it automatically enables the user-interface object if there is an ON_COMMAND entry somewhere with the same command ID. Otherwise, it disables the user-interface object. Therefore, to ensure that a user-interface object is enabled, supply a handler for the command the object generates or supply an update handler for it. See the figure in the topic User-Interface Objects and Command IDs..

5. ON_UPDATE_COMMAND_UI Macro

To connect a user-interface object to a command-update handler in a command-target object, open Class View, then right-click on the class to which the handler will be added, and choose Class Wizard. Find the user-interface object's ID in the list on the left, then choose UPDATE_COMMAND_UI in the right pane and click Add Handler. This creates a handler function in the class and adds the appropriate entry in the message map. See Mapping Messages to Functions for more information. You can specify additional messages to handle in the Messages pane.

For example, to update a Clear All command in your program's Edit menu, use the Class Wizard to add a message-map entry in the selected class, a function declaration for a command-update handler called OnUpdateEditClearAll in the class declaration, and an empty function template in the class's implementation file. The function prototype looks like this:.

6. User-Interface Objects and Command IDs

Menu items, toolbar buttons, and accelerator keys are "user-interface objects" capable of generating commands. Each such user-interface object has an ID. You associate a user-interface object with a command by assigning the same ID to the object and the command. As explained in Messages, commands are implemented as special messages. The figure "Commands in the Framework" below shows how the framework manages commands. When a user-interface object generates a command, such as ID_EDIT_CLEAR_ALL, one of the objects in your application handles the command — in the figure below, the document object's OnEditClearAll function is called via the document's message map..

Message

7. Messages

The message loop in the Run member function of class CWinApp retrieves queued messages generated by various events. For example, when the user clicks the mouse, Windows sends several mouse-related messages, such as WM_LBUTTONDOWN when the left mouse button is pressed and WM_LBUTTONUP when the left mouse button is released. The framework's implementation of the application message loop dispatches the message to the appropriate window.

The important categories of messages are described in Message Categories...

8. Message Categories

What kinds of messages do you write handlers for There are three main categories:

1. Windows messages
This includes primarily those messages beginning with the WM_ prefix, except for WM_COMMAND. Windows messages are handled by windows and views. These messages often have parameters that are used in determining how to handle the message.
2. Control notifications
This includes WM_COMMAND notification messages from controls and other child windows to their parent windows. For example, an edit control sends its parent a WM_COMMAND message containing the EN_CHANGE control-notification code when the user has taken an action that may have altered text in the edit control. The window's handler for the message responds to the notification message in some appropriate way, such as retrieving the text in the control.
The framework routes control-notification messages like other WM_ messages. One exception, however, is the BN_CLICKED control-notification message sent by buttons when the user clicks them. This message is treated specially as a command message and routed like other commands.
3. Command messages
This includes WM_COMMAND notification messages from user-interface objects: menus, toolbar buttons, and accelerator keys. The framework processes commands differently from other messages, and they can be handled by more kinds of objects, as explained in Command Targets....