Audacity  2.2.0
CommandManager Class Referencefinal

CommandManager implements a system for organizing all user-callable commands. More...

#include <CommandManager.h>

Inheritance diagram for CommandManager:
XMLTagHandler

Public Member Functions

 CommandManager ()
 
virtual ~CommandManager ()
 
 CommandManager (const CommandManager &) PROHIBITED
 
CommandManageroperator= (const CommandManager &) PROHIBITED
 
void SetMaxList ()
 
void PurgeData ()
 
std::unique_ptr< wxMenuBar > AddMenuBar (const wxString &sMenu)
 
void BeginMenu (const wxString &tName)
 
void EndMenu ()
 
wxMenu * BeginSubMenu (const wxString &tName)
 
void EndSubMenu ()
 
void InsertItem (const wxString &name, const wxString &label, const CommandFunctorPointer &callback, const wxString &after, int checkmark=-1)
 
void AddItemList (const wxString &name, const wxArrayString &labels, const CommandFunctorPointer &callback)
 
void AddCheck (const wxChar *name, const wxChar *label, const CommandFunctorPointer &callback, int checkmark=0)
 
void AddCheck (const wxChar *name, const wxChar *label, const CommandFunctorPointer &callback, int checkmark, CommandFlag flags, CommandMask mask)
 
void AddItem (const wxChar *name, const wxChar *label, const CommandFunctorPointer &callback, CommandFlag flags=NoFlagsSpecifed, CommandMask mask=NoFlagsSpecifed)
 
void AddItem (const wxChar *name, const wxChar *label_in, const CommandFunctorPointer &callback, const wxChar *accel, CommandFlag flags=NoFlagsSpecifed, CommandMask mask=NoFlagsSpecifed, int checkmark=-1)
 
void AddSeparator ()
 
void AddCommand (const wxChar *name, const wxChar *label, const CommandFunctorPointer &callback, CommandFlag flags=NoFlagsSpecifed, CommandMask mask=NoFlagsSpecifed)
 
void AddCommand (const wxChar *name, const wxChar *label, const CommandFunctorPointer &callback, const wxChar *accel, CommandFlag flags=NoFlagsSpecifed, CommandMask mask=NoFlagsSpecifed)
 
void AddGlobalCommand (const wxChar *name, const wxChar *label, const CommandFunctorPointer &callback, const wxChar *accel)
 
void SetDefaultFlags (CommandFlag flags, CommandMask mask)
 
CommandFlag GetDefaultFlags () const
 
CommandMask GetDefaultMask () const
 
void SetOccultCommands (bool bOccult)
 
void SetCommandFlags (const wxString &name, CommandFlag flags, CommandMask mask)
 
void SetCommandFlags (const wxChar **names, CommandFlag flags, CommandMask mask)
 
void SetCommandFlags (CommandFlag flags, CommandMask mask,...)
 
void EnableUsingFlags (CommandFlag flags, CommandMask mask)
 
void Enable (const wxString &name, bool enabled)
 
void Check (const wxString &name, bool checked)
 
void Modify (const wxString &name, const wxString &newLabel)
 Changes the label text of a menu item. More...
 
void SetCurrentMenu (wxMenu *menu)
 
void ClearCurrentMenu ()
 
void SetKeyFromName (const wxString &name, const wxString &key)
 
void SetKeyFromIndex (int i, const wxString &key)
 
bool FilterKeyEvent (AudacityProject *project, const wxKeyEvent &evt, bool permit=false)
 
bool HandleMenuID (int id, CommandFlag flags, CommandMask mask)
 
bool HandleTextualCommand (const wxString &Str, CommandFlag flags, CommandMask mask)
 
void GetCategories (wxArrayString &cats)
 
void GetAllCommandNames (wxArrayString &names, bool includeMultis)
 
void GetAllCommandLabels (wxArrayString &labels, bool includeMultis)
 
void GetAllCommandData (wxArrayString &names, wxArrayString &keys, wxArrayString &default_keys, wxArrayString &labels, wxArrayString &categories, wxArrayString &prefixes, bool includeMultis)
 
wxString GetLabelFromName (const wxString &name)
 
wxString GetPrefixedLabelFromName (const wxString &name)
 
wxString GetCategoryFromName (const wxString &name)
 
wxString GetKeyFromName (const wxString &name) const
 
wxString GetDefaultKeyFromName (const wxString &name)
 
bool GetEnabled (const wxString &name)
 
void WriteXML (XMLWriter &xmlFile) const
 
void TellUserWhyDisallowed (const wxString &Name, CommandFlag flagsGot, CommandFlag flagsRequired)
 
wxString DescribeCommandsAndShortcuts (const std::vector< wxString > &commands, const wxString &separator=wxT(" / ")) const
 
- Public Member Functions inherited from XMLTagHandler
 XMLTagHandler ()
 
virtual ~XMLTagHandler ()
 
virtual void HandleXMLEndTag (const wxChar *WXUNUSED(tag))
 
virtual void HandleXMLContent (const wxString &WXUNUSED(content))
 
bool ReadXMLTag (const char *tag, const char **attrs)
 
void ReadXMLEndTag (const char *tag)
 
void ReadXMLContent (const char *s, int len)
 
XMLTagHandlerReadXMLChild (const char *tag)
 

Protected Member Functions

int NextIdentifier (int ID)
 
CommandListEntryNewIdentifier (const wxString &name, const wxString &label, wxMenu *menu, const CommandFunctorPointer &callback, bool multi, int index, int count)
 
CommandListEntryNewIdentifier (const wxString &name, const wxString &label, const wxString &accel, wxMenu *menu, const CommandFunctorPointer &callback, bool multi, int index, int count)
 
bool HandleCommandEntry (const CommandListEntry *entry, CommandFlag flags, CommandMask mask, const wxEvent *evt=NULL)
 
void Enable (CommandListEntry *entry, bool enabled)
 
wxMenuBar * CurrentMenuBar () const
 
wxMenuBar * GetMenuBar (const wxString &sMenu) const
 
wxMenu * CurrentSubMenu () const
 
wxMenu * CurrentMenu () const
 
wxString GetLabel (const CommandListEntry *entry) const
 
wxString GetLabelWithDisabledAccel (const CommandListEntry *entry) const
 
bool HandleXMLTag (const wxChar *tag, const wxChar **attrs) override
 
void HandleXMLEndTag (const wxChar *tag) override
 
XMLTagHandlerHandleXMLChild (const wxChar *tag) override
 

Private Attributes

wxSortedArrayString mMaxListOnly
 
MenuBarList mMenuBarList
 
SubMenuList mSubMenuList
 
CommandList mCommandList
 
CommandNameHash mCommandNameHash
 
CommandNameHash mCommandKeyHash
 
CommandIDHash mCommandIDHash
 
int mCurrentID
 
int mXMLKeysRead
 
bool mbSeparatorAllowed
 
wxString mCurrentMenuName
 
std::unique_ptr< wxMenu > uCurrentMenu
 
wxMenu * mCurrentMenu {}
 
CommandFlag mDefaultFlags
 
CommandMask mDefaultMask
 
bool bMakingOccultCommands
 

Detailed Description

CommandManager implements a system for organizing all user-callable commands.

It creates and manages a menu bar with a command associated with each item, and managing other commands callable by keyboard shortcuts.

Commands are implemented by overriding an abstract functor class. See Menus.cpp for an example use.

Menus or submenus containing lists of items can be added at once, with a single function (functor) to be called when any of the items is selected, with the index number of the selection as the parameter. This is useful for dynamic menus (effects) and submenus containing a list of choices (selection formats).

Menu items can be enabled or disabled individually, groups of "multi-items" can be enabled or disabled all at once, or entire sets of commands can be enabled or disabled all at once using flags. The flags should be a bitfield stored in a 32-bit integer but can be whatever you want. You specify both the desired values of the flags, and the set of flags relevant to a particular command, by using a combination of a flags parameter and a mask parameter. Any flag set to 0 in the mask parameter is the same as "don't care". Any command whose mask is set to zero will not be affected by enabling/disabling by flags.

Constructor & Destructor Documentation

CommandManager::CommandManager ( )

Standard Constructor

References mbSeparatorAllowed, and SetMaxList().

CommandManager::~CommandManager ( )
virtual

Class Destructor. Includes PurgeData, which removes menubars

References PurgeData().

CommandManager::CommandManager ( const CommandManager )

Member Function Documentation

void CommandManager::AddCheck ( const wxChar *  name,
const wxChar *  label,
const CommandFunctorPointer callback,
int  checkmark = 0 
)
void CommandManager::AddCheck ( const wxChar *  name,
const wxChar *  label,
const CommandFunctorPointer callback,
int  checkmark,
CommandFlag  flags,
CommandMask  mask 
)

References AddItem().

void CommandManager::AddCommand ( const wxChar *  name,
const wxChar *  label,
const CommandFunctorPointer callback,
CommandFlag  flags = NoFlagsSpecifed,
CommandMask  mask = NoFlagsSpecifed 
)

Add a command that doesn't appear in a menu. When the key is pressed, the given function pointer will be called (via the CommandManagerListener)

void CommandManager::AddCommand ( const wxChar *  name,
const wxChar *  label,
const CommandFunctorPointer callback,
const wxChar *  accel,
CommandFlag  flags = NoFlagsSpecifed,
CommandMask  mask = NoFlagsSpecifed 
)
void CommandManager::AddGlobalCommand ( const wxChar *  name,
const wxChar *  label,
const CommandFunctorPointer callback,
const wxChar *  accel 
)
void CommandManager::AddItem ( const wxChar *  name,
const wxChar *  label,
const CommandFunctorPointer callback,
CommandFlag  flags = NoFlagsSpecifed,
CommandMask  mask = NoFlagsSpecifed 
)
void CommandManager::AddItem ( const wxChar *  name,
const wxChar *  label_in,
const CommandFunctorPointer callback,
const wxChar *  accel,
CommandFlag  flags = NoFlagsSpecifed,
CommandMask  mask = NoFlagsSpecifed,
int  checkmark = -1 
)
void CommandManager::AddItemList ( const wxString &  name,
const wxArrayString &  labels,
const CommandFunctorPointer callback 
)

Add a list of menu items to the current menu. When the user selects any one of these, the given functor will be called with its position in the list as the index number. When you call Enable on this command name, it will enable or disable all of the items at once.

References CurrentMenu(), GetLabel(), CommandListEntry::id, mbSeparatorAllowed, and NewIdentifier().

Referenced by AudacityProject::CreateMenusAndCommands().

std::unique_ptr< wxMenuBar > CommandManager::AddMenuBar ( const wxString &  sMenu)

Makes a NEW menubar for placement on the top of a project Names it according to the passed-in string argument.

If the menubar already exists, that's unexpected.

References GetMenuBar(), and mMenuBarList.

Referenced by AudacityProject::CreateMenusAndCommands().

void CommandManager::AddSeparator ( )
void CommandManager::BeginMenu ( const wxString &  tName)

This starts a NEW menu

References mCurrentMenu, mCurrentMenuName, and uCurrentMenu.

Referenced by AudacityProject::CreateMenusAndCommands().

wxMenu * CommandManager::BeginSubMenu ( const wxString &  tName)
void CommandManager::ClearCurrentMenu ( )

References mCurrentMenu, and uCurrentMenu.

wxMenu * CommandManager::CurrentMenu ( ) const
protected

This returns the current menu that we're appending to - note that it could be a submenu if BeginSubMenu was called and we haven't reached EndSubMenu yet.

References CurrentSubMenu(), and mCurrentMenu.

Referenced by AddItem(), AddItemList(), AddSeparator(), and EndSubMenu().

wxMenuBar * CommandManager::CurrentMenuBar ( ) const
protected

Retrieve the 'current' menubar; either NULL or the last on in the mMenuBarList.

References mMenuBarList.

Referenced by EndMenu().

wxMenu * CommandManager::CurrentSubMenu ( ) const
protected

This returns the 'Current' Submenu, which is the one at the end of the mSubMenuList (or NULL, if it doesn't exist).

References mSubMenuList.

Referenced by CurrentMenu().

wxString CommandManager::DescribeCommandsAndShortcuts ( const std::vector< wxString > &  commands,
const wxString &  separator = wxT(" / ") 
) const

Formatting summaries that include shortcut keys

References GetKeyFromName(), KeyStringDisplay(), and Internat::Parenthesize().

void CommandManager::Enable ( const wxString &  name,
bool  enabled 
)
void CommandManager::Enable ( CommandListEntry entry,
bool  enabled 
)
protected

Enables or disables a menu item based on its name (not the label in the menu bar, but the name of the command.) If you give it the name of a multi-item (one that was added using AddItemList(), it will enable or disable all of them at once

References CommandListEntry::count, CommandListEntry::enabled, CommandListEntry::id, mCommandIDHash, CommandListEntry::menu, CommandListEntry::multi, CommandListEntry::name, and NextIdentifier().

void CommandManager::EnableUsingFlags ( CommandFlag  flags,
CommandMask  mask 
)

References Enable(), and mCommandList.

Referenced by AudacityProject::UpdateMenus().

void CommandManager::EndMenu ( )

This attaches a menu to the menubar and ends the menu

References COMMAND, CurrentMenuBar(), mCurrentMenu, mCurrentMenuName, and uCurrentMenu.

Referenced by AudacityProject::CreateMenusAndCommands().

void CommandManager::EndSubMenu ( )

This function is called after the final item of a SUBmenu is added. Submenu items are added just like regular menu items; they just happen after BeginSubMenu() is called but before EndSubMenu() is called.

References CurrentMenu(), mbSeparatorAllowed, and mSubMenuList.

Referenced by AudacityProject::AddEffectMenuItemGroup(), AudacityProject::AddEffectMenuItems(), AudacityProject::CreateMenusAndCommands(), and AudacityProject::CreateRecentFilesMenu().

void CommandManager::GetAllCommandData ( wxArrayString &  names,
wxArrayString &  keys,
wxArrayString &  default_keys,
wxArrayString &  labels,
wxArrayString &  categories,
wxArrayString &  prefixes,
bool  includeMultis 
)

References mCommandList.

Referenced by KeyConfigPrefs::RefreshBindings().

void CommandManager::GetAllCommandLabels ( wxArrayString &  labels,
bool  includeMultis 
)

References mCommandList.

void CommandManager::GetAllCommandNames ( wxArrayString &  names,
bool  includeMultis 
)

References mCommandList.

Referenced by GetAllMenuCommands::Apply().

void CommandManager::GetCategories ( wxArrayString &  cats)
wxString CommandManager::GetCategoryFromName ( const wxString &  name)
CommandFlag CommandManager::GetDefaultFlags ( ) const
inline
wxString CommandManager::GetDefaultKeyFromName ( const wxString &  name)
CommandMask CommandManager::GetDefaultMask ( ) const
inline
bool CommandManager::GetEnabled ( const wxString &  name)
wxString CommandManager::GetKeyFromName ( const wxString &  name) const
wxString CommandManager::GetLabel ( const CommandListEntry entry) const
protected
wxString CommandManager::GetLabelFromName ( const wxString &  name)
wxString CommandManager::GetLabelWithDisabledAccel ( const CommandListEntry entry) const
protected
wxMenuBar * CommandManager::GetMenuBar ( const wxString &  sMenu) const
protected

Retrieves the menubar based on the name given in AddMenuBar(name)

References mMenuBarList.

Referenced by AddMenuBar().

wxString CommandManager::GetPrefixedLabelFromName ( const wxString &  name)
bool CommandManager::HandleCommandEntry ( const CommandListEntry entry,
CommandFlag  flags,
CommandMask  mask,
const wxEvent *  evt = NULL 
)
protected

HandleCommandEntry() takes a CommandListEntry and executes it returning true iff successful. If you pass any flags, the command won't be executed unless the flags are compatible with the command's flags.

References CommandListEntry::callback, CommandListEntry::enabled, CommandListEntry::flags, GetActiveProject(), CommandListEntry::index, CommandListEntry::label, CommandListEntry::mask, and AudacityProject::ReportIfActionNotAllowed().

Referenced by FilterKeyEvent(), HandleMenuID(), and HandleTextualCommand().

bool CommandManager::HandleMenuID ( int  id,
CommandFlag  flags,
CommandMask  mask 
)

Call this when a menu event is received. If it matches a command, it will call the appropriate CommandManagerListener function. If you pass any flags, the command won't be executed unless the flags are compatible with the command's flags.

References HandleCommandEntry(), and mCommandIDHash.

Referenced by AudacityProject::OnMenu().

XMLTagHandler * CommandManager::HandleXMLChild ( const wxChar *  tag)
overrideprotectedvirtual

Implements XMLTagHandler.

void CommandManager::HandleXMLEndTag ( const wxChar *  tag)
overrideprotected

References _(), and mXMLKeysRead.

bool CommandManager::HandleXMLTag ( const wxChar *  tag,
const wxChar **  attrs 
)
overrideprotectedvirtual
void CommandManager::InsertItem ( const wxString &  name,
const wxString &  label_in,
const CommandFunctorPointer callback,
const wxString &  after,
int  checkmark = -1 
)

Add a menu item to the current menu. When the user selects it, the given functor will be called

References GetActiveProject(), GetLabel(), CommandListEntry::id, label, mbSeparatorAllowed, names, and NewIdentifier().

void CommandManager::Modify ( const wxString &  name,
const wxString &  newLabel 
)
CommandListEntry * CommandManager::NewIdentifier ( const wxString &  name,
const wxString &  label,
wxMenu *  menu,
const CommandFunctorPointer callback,
bool  multi,
int  index,
int  count 
)
protected

Given all of the information for a command, comes up with a NEW unique ID, adds it to a list, and returns the ID. WARNING: Does this conflict with the identifiers set for controls/windows? If it does, a workaround may be to keep controls below wxID_LOWEST and keep menus above wxID_HIGHEST

Referenced by AddCommand(), AddGlobalCommand(), AddItem(), AddItemList(), and InsertItem().

CommandListEntry * CommandManager::NewIdentifier ( const wxString &  name,
const wxString &  label,
const wxString &  accel,
wxMenu *  menu,
const CommandFunctorPointer callback,
bool  multi,
int  index,
int  count 
)
protected
int CommandManager::NextIdentifier ( int  ID)
protected

Referenced by Enable(), and NewIdentifier().

CommandManager& CommandManager::operator= ( const CommandManager )
void CommandManager::SetCommandFlags ( const wxString &  name,
CommandFlag  flags,
CommandMask  mask 
)
void CommandManager::SetCommandFlags ( const wxChar **  names,
CommandFlag  flags,
CommandMask  mask 
)

References names, and SetCommandFlags().

void CommandManager::SetCommandFlags ( CommandFlag  flags,
CommandMask  mask,
  ... 
)

References name, and SetCommandFlags().

void CommandManager::SetCurrentMenu ( wxMenu *  menu)

References mCurrentMenu, and uCurrentMenu.

void CommandManager::SetDefaultFlags ( CommandFlag  flags,
CommandMask  mask 
)
void CommandManager::SetKeyFromIndex ( int  i,
const wxString &  key 
)
void CommandManager::SetKeyFromName ( const wxString &  name,
const wxString &  key 
)
void CommandManager::SetMaxList ( )
void CommandManager::SetOccultCommands ( bool  bOccult)
void CommandManager::TellUserWhyDisallowed ( const wxString &  Name,
CommandFlag  flagsGot,
CommandFlag  flagsRequired 
)
void CommandManager::WriteXML ( XMLWriter xmlFile) const

Member Data Documentation

bool CommandManager::bMakingOccultCommands
private

Referenced by NewIdentifier(), and SetOccultCommands().

bool CommandManager::mbSeparatorAllowed
private
CommandIDHash CommandManager::mCommandIDHash
private
CommandNameHash CommandManager::mCommandKeyHash
private
int CommandManager::mCurrentID
private

Referenced by NewIdentifier(), and PurgeData().

wxMenu* CommandManager::mCurrentMenu {}
private
wxString CommandManager::mCurrentMenuName
private
CommandFlag CommandManager::mDefaultFlags
private

Referenced by NewIdentifier(), and SetDefaultFlags().

CommandMask CommandManager::mDefaultMask
private

Referenced by NewIdentifier(), and SetDefaultFlags().

wxSortedArrayString CommandManager::mMaxListOnly
private

Referenced by NewIdentifier(), and SetMaxList().

MenuBarList CommandManager::mMenuBarList
private
SubMenuList CommandManager::mSubMenuList
private
int CommandManager::mXMLKeysRead
private

Referenced by HandleXMLEndTag(), and HandleXMLTag().

std::unique_ptr<wxMenu> CommandManager::uCurrentMenu
private

The documentation for this class was generated from the following files: