CMFCCmdUsageCount Class

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CMFCCmdUsageCount Class.

Tracks the usage count of Windows messages, such as when the user selects an item from a menu.

class CMFCCmdUsageCount : public CObject  

Public Constructors

NameDescription
CMFCCmdUsageCount::CMFCCmdUsageCountDefault constructor.
CMFCCmdUsageCount::~CMFCCmdUsageCountDestructor.

Public Methods

NameDescription
CMFCCmdUsageCount::AddCmdIncrements by one the counter that is associated with the given command.
CMFCCmdUsageCount::GetCountRetrieves the usage count that is associated with the given command ID.
CMFCCmdUsageCount::HasEnoughInformationDetermines whether this object has collected the minimum amount of tracking data.
CMFCCmdUsageCount::IsFreqeuntlyUsedCmdDetermines whether the given command is frequently used.
CMFCCmdUsageCount::ResetClears the usage count of all commands.
CMFCCmdUsageCount::SerializeReads this object from an archive or writes it to an archive. (Overrides CObject::Serialize.)
CMFCCmdUsageCount::SetOptionsSets the values of shared CMFCCmdUsageCount class data members.

Data Members

NameDescription
m_CmdUsageA CMap object that maps commands to their usage counts.
m_nMinUsagePercentageThe minimum usage percentage for a command to be frequently used.
m_nStartCountThe start counter that is used to determine whether this object has collected the minimum amount of tracking data.
m_nTotalUsageThe count of all tracked commands.

Remarks

The CMFCCmdUsageCount class maps each numeric Windows message identifier to a 32-bit unsigned integer counter. CMFCToolBar uses this class to display frequently-used toolbar items. For more information about CMFCToolBar, see CMFCToolBar Class.

You can persist CMFCCmdUsageCount class data between runs of your program. Use the CMFCCmdUsageCount::Serialize method to serialize class member data and the CMFCCmdUsageCount::SetOptions method to set shared member data.

CObject

CMFCCmdUsageCount

Header: afxcmdusagecount.h

Increments by one the counter that is associated with the given command.

void AddCmd(UINT uiCmd);

Parameters

ParameterDescription
[in] uiCmdSpecifies the command counter to increment.

Remarks

This method adds a new entry to the map structure of command counts, m_CmdUsage, if the entry does not already exist.

This method does nothing in the following cases:

  • The toolbar framework is in customization mode (the CMFCToolBar::IsCustomizeMode method returns a nonzero value).

  • The command refers to a submenu or menu separator ( uiCmd equals 0 or -1).

  • uiCmd refers to a standard command (the global IsStandardCommand function returns a nonzero value).

Retrieves the usage count that is associated with the given command ID.

UINT GetCount(UINT uiCmd) const;  

Parameters

ParameterDescription
[in] uiCmdThe ID of the command counter to retrieve.

Return Value

The usage count that is associated with the given command ID.

Determines whether this object has received the minimum amount of tracking data.

BOOL HasEnoughInformation() const;  

Return Value

Nonzero if this object has received the minimum amount of tracking data; otherwise 0.

Remarks

This method returns a nonzero value if the total count, m_nTotalUsage, of all tracked commands is equal to or larger than the initial count, m_nStartCount. By default, the framework sets the initial count 0. You can override this value by using the CMFCCmdUsageCount::SetOptions method.

This method is used by CMFCMenuBar::IsShowAllCommands to determine whether to show all available menu commands.

Determines whether the given command is frequently used.

BOOL IsFreqeuntlyUsedCmd(UINT uiCmd) const;  

Parameters

ParameterDescription
[in] uiCmdSpecifies the command to check.

Return Value

Nonzero if the command is frequently used; otherwise 0.

Remarks

This method returns 0 if the total command usage, m_nTotalUsage, is 0. Otherwise, this method returns nonzero if the percentage of which the specified command is used is larger than the minimum percentage, m_nMinUsagePercentage. By default, the framework sets the minimum percentage to 5. You can override this value by using the CMFCCmdUsageCount::SetOptions method. If the minimum percentage is 0, this method returns nonzero if the specified command count is larger than 0.

CMFCToolBar::IsCommandRarelyUsed uses this method to determine whether a command is rarely used.

Clears the usage count of all commands.

void Reset();

Remarks

Call this method to clear all entries from the map structure of command counts, m_CmdUsage, and to reset the total command usage, m_nTotalUsage, counter to 0.

Reads this object from an archive, or writes it to an archive.

virtual void Serialize(CArchive& ar);

Parameters

ParameterDescription
[in] arA CArchive object to serialize from or to.

Remarks

This method serializes the map structure of command counts, m_CmdUsage, and the total command usage, m_nTotalUsage, counter from or to the specified archive.

For serialization examples, see Serialization: Serializing an Object.

Sets the values of shared CMFCCmdUsageCount class data members.

static BOOL __stdcall SetOptions(
    UINT nStartCount,  
    UINT nMinUsagePercentage);

Parameters

ParameterDescription
[in] nStartCountThe new initial count of all tracked commands.
[in] nMinUsagePercentageThe new minimum usage percentage.

Return Value

TRUE if the method succeeds, FALSE if the nMinUsagePercentage parameter is larger than or equal to 100.

Remarks

This method sets the shared CMFCCmdUsageCount class data members m_nStartCount and m_nMinUsagePercentage to nStartCount and nMinUsagePercentage, respectively. m_nStartCount is used by the CMFCCmdUsageCount::HasEnoughInformation method to determine whether this object has collected the minimum amount of tracking data. m_nMinUsagePercentage is used by the CMFCCmdUsageCount::IsFreqeuntlyUsedCmd method to determine whether a given command is frequently used.

In Debug builds this method generates an assertion failure if the nMinUsagePercentage parameter is larger than or equal to 100.

Hierarchy Chart
Classes
CMFCToolBar Class

Show: