TN022: Standard Commands Implementation

This note describes the standard command implementations provided by MFC 2.0. Please be sure to read Technical Note 21 first since that describes the mechanisms used to implement many of the standard commands.

This description assumes knowledge of the MFC architectures, APIs, and common programming practice. Documented as well as undocumented "implementation only" APIs are described. This is not a place to start to learn about the features of or how to program in MFC. Please refer to the Visual C++ Programmer's Guide for more general information and for details of documented APIs.

The Problem

MFC defines many standard command IDs in the header file AFXRES.H. Framework support for these commands varies. Understanding where and how the framework classes handle these commands will not only show you how the framework works internally but will provide useful information on how to customize the standard implementations and hopefully teach you a few techniques for implementing your own command handlers.

Contents of This Technical Note

Each command ID is described in two sections:

Most default command implementations are prewired in the framework's base class message map. There are some command implementations which require explicit wiring in your derived class. These are described under "Note". If you chose the right options in AppWizard, these default handlers will be connected for you in the generated skeleton application.

Naming Convention

Standard commands follow a simple naming convention that we recommend you use if possible. Most standard commands are located in standard places in an application's menu bar. The symbolic name of the command starts with "ID_" followed by the standard popup menu name, followed by the menu item name. The symbolic name is in upper case with underscore word-breaks. For commands that do not have standard menu item names, a logical command name is defined starting with "ID_" (for example, ID_NEXT_PANE).

We use the prefix "ID_" to indicate commands that are designed to be bound to menu items, toolbar buttons, or other command user-interface objects. Command handlers handling "ID_" commands should use the ON_COMMAND and ON_UPDATE_COMMAND_UI mechanisms of the MFC command architecture.

We recommend you use the standard "IDM_" prefix for menu items which do not follow the command architecture and need menu-specific code to enable and disable them. Of course the number of menu specific commands should be small since following the MFC command architecture not only makes command handlers more powerful (since they will work with toolbars) but makes the command handler code reusable.

ID Ranges

Please refer to Technical Note 20 for more details on the use of ID ranges in MFC.

MFC standard commands fall in the range 0xE000 to 0xEFFF. Please do not rely on the specific values of these IDs since they are subject to change in future versions of the library.

Your application should define its commands in the range 0x8000 to 0xDFFF.

Standard Command IDs

For each command ID, there is a standard message line prompt string that can be found in the file PROMPTS.RC. The string ID for that menu prompt must be the same as for the command ID.

Update-Only Command Handlers

There are several standard command IDs that are used as indicators in status bars. These use the same update-command UI handling mechanism to display their current visual state during application idle time. Since they can't be selected by the user (that is, you can't push a status bar pane), then it makes no sense to have an ON_COMMAND handler for these command IDs.

All three of these are implemented in CFrameWnd::OnUpdateKeyIndicator, an implementation helper that uses the command ID to map to the appropriate Virtual Key. A common implementation enables or disables (for status panes disabled = no text) the CCmdUI object depending on whether the appropriate Virtual Key is currently locked.

Customization of this command handler is not recommended.

Currently there is no standard implementation for these indicators.

If you choose to implement these indicators, we recommend you use these indicator IDs and maintaining the ordering of the indicators in your status bar (that is, in this order: EXT, CAP, NUM, SCRL, OVR, REC).

Technical Notes by NumberTechnical Notes by Category