CMFCCmdUsageCount Class
Tracks the usage count of Windows messages, such as when the user selects an item from a menu.
class CMFCCmdUsageCount : public CObject
| Name | Description |
|---|---|
CMFCCmdUsageCount::CMFCCmdUsageCount |
Default constructor. |
CMFCCmdUsageCount::~CMFCCmdUsageCount |
Destructor. |
| Name | Description |
|---|---|
| CMFCCmdUsageCount::AddCmd | Increments by one the counter that is associated with the given command. |
| CMFCCmdUsageCount::GetCount | Retrieves the usage count that is associated with the given command ID. |
| CMFCCmdUsageCount::HasEnoughInformation | Determines whether this object has collected the minimum amount of tracking data. |
| CMFCCmdUsageCount::IsFreqeuntlyUsedCmd | Determines whether the given command is frequently used. |
| CMFCCmdUsageCount::Reset | Clears the usage count of all commands. |
| CMFCCmdUsageCount::Serialize | Reads this object from an archive or writes it to an archive. (Overrides CObject::Serialize.) |
| CMFCCmdUsageCount::SetOptions | Sets the values of shared CMFCCmdUsageCount class data members. |
| Name | Description |
|---|---|
m_CmdUsage |
A CMap object that maps commands to their usage counts. |
m_nMinUsagePercentage |
The minimum usage percentage for a command to be frequently used. |
m_nStartCount |
The start counter that is used to determine whether this object has collected the minimum amount of tracking data. |
m_nTotalUsage |
The count of all tracked commands. |
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.
Header: afxcmdusagecount.h
Increments by one the counter that is associated with the given command.
void AddCmd(UINT uiCmd);
uiCmd
[in] Specifies the command counter to increment.
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
IsStandardCommandfunction returns a nonzero value).
Retrieves the usage count that is associated with the given command ID.
UINT GetCount(UINT uiCmd) const;
uiCmd
[in] The ID of the command counter to retrieve.
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;
Nonzero if this object has received the minimum amount of tracking data; otherwise 0.
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;
uiCmd
[in] Specifies the command to check.
Nonzero if the command is frequently used; otherwise 0.
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();
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);
ar
[in] A CArchive object to serialize from or to.
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);
nStartCount
[in] The new initial count of all tracked commands.
nMinUsagePercentage
[in] The new minimum usage percentage.
TRUE if the method succeeds, FALSE if the nMinUsagePercentage parameter is larger than or equal to 100.
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.