Edit

CCmdUI Class

  • Article

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

Syntax

class CCmdUI

Members

Public Methods

Name Description
CCmdUI::ContinueRouting Tells the command-routing mechanism to continue routing the current message down the chain of handlers.
CCmdUI::Enable Enables or disables the user-interface item for this command.
CCmdUI::SetCheck Sets the check state of the user-interface item for this command.
CCmdUI::SetRadio Like the SetCheck member function, but operates on radio groups.
CCmdUI::SetText Sets the text for the user-interface item for this command.

Public Data Members

Name Description
CCmdUI::m_nID The ID of the user-interface object.
CCmdUI::m_nIndex The index of the user-interface object.
CCmdUI::m_pMenu Points to the menu represented by the CCmdUI object.
CCmdUI::m_pOther Points to the window object that sent the notification.
CCmdUI::m_pSubMenu Points to the contained sub-menu represented by the CCmdUI object.

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.

User-Interface Item Enable SetCheck SetRadio SetText
Menu item Enables or disables Checks or unchecks Checks using a dot Sets item text
Toolbar button Enables or disables Selects, unselects, or indeterminate Same as SetCheck (Not applicable)
Status-bar pane Makes text visible or invisible Sets pop-out or normal border Same as SetCheck Sets pane text
Normal button in CDialogBar Enables or disables Checks or unchecks check box Same as SetCheck Sets button text
Normal control in CDialogBar Enables or disables (Not applicable) (Not applicable) Sets window text

For more on the use of this class, see How to Update User-Interface Objects.

Inheritance Hierarchy

CCmdUI

Requirements

Header: afxwin.h

CCmdUI::ContinueRouting

Call this member function to tell the command-routing mechanism to continue routing the current message down the chain of handlers.

void ContinueRouting();

Remarks

This is an advanced member function that should be used in conjunction with an ON_COMMAND_EX handler that returns FALSE. For more information, see Technical Note 6.

CCmdUI::Enable

Call this member function to enable or disable the user-interface item for this command.

virtual void Enable(BOOL bOn = TRUE);

Parameters

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

Example

ON_UPDATE_COMMAND_UI(ID_FILE_SAVE, &CMyDoc::OnUpdateFileSave)

 

void CMyDoc::OnUpdateFileSave(CCmdUI *pCmdUI)
{
   // Enable the menu item if the file has been modified.
   pCmdUI->Enable(m_bModified);
}

CCmdUI::m_nID

The ID of the menu item, toolbar button, or other user-interface object represented by the CCmdUI object.

UINT m_nID;

CCmdUI::m_nIndex

The index of the menu item, toolbar button, or other user-interface object represented by the CCmdUI object.

UINT m_nIndex;

CCmdUI::m_pMenu

Pointer (of CMenu type) to the menu represented by the CCmdUI object.

CMenu* m_pMenu;

Remarks

NULL if the item is not a menu.

CCmdUI::m_pSubMenu

Pointer (of CMenu type) to the contained sub-menu represented by the CCmdUI object.

CMenu* m_pSubMenu;

Remarks

NULL if the item is not a menu. If the sub menu is a pop-up, m_nID contains the ID of the first item in the pop-up menu. For more information, see Technical Note 21.

CCmdUI::m_pOther

Pointer (of type CWnd) to the window object, such as a tool or status bar, that sent the notification.

CWnd* m_pOther;

Remarks

NULL if the item is a menu or a non- CWnd object.

CCmdUI::SetCheck

Call this member function to set the user-interface item for this command to the appropriate check state.

virtual void SetCheck(int nCheck = 1);

Parameters

nCheck
Specifies the check state to set. If 0, unchecks; if 1, checks; and if 2, sets indeterminate.

Remarks

This member function works for menu items and toolbar buttons. The indeterminate state applies only to toolbar buttons.

CCmdUI::SetRadio

Call this member function to set the user-interface item for this command to the appropriate check state.

virtual void SetRadio(BOOL bOn = TRUE);

Parameters

bOn
TRUE to enable the item; otherwise FALSE.

Remarks

This member function operates like SetCheck, except that it operates on user-interface items acting as part of a radio group. Unchecking the other items in the group is not automatic unless the items themselves maintain the radio-group behavior.

CCmdUI::SetText

Call this member function to set the text of the user-interface item for this command.

virtual void SetText(LPCTSTR lpszText);

Parameters

lpszText
A pointer to a text string.

Example

void CMyRichEditView::OnUpdateLineNumber(CCmdUI *pCmdUI)
{
   int nLine = GetRichEditCtrl().LineFromChar(-1) + 1;

   CString string;
   string.Format(_T("Line %d"), nLine);
   pCmdUI->Enable(TRUE);
   pCmdUI->SetText(string);
}

See also

MFC Sample MDI
Hierarchy Chart
CCmdTarget Class