Audacity  2.2.2
CommandManager.h
Go to the documentation of this file.
1 /**********************************************************************
2 
3  Audacity: A Digital Audio Editor
4 
5  CommandManager.h
6 
7  Brian Gunlogson
8  Dominic Mazzoni
9 
10 **********************************************************************/
11 
12 #ifndef __AUDACITY_COMMAND_MANAGER__
13 #define __AUDACITY_COMMAND_MANAGER__
14 
15 #include "../Experimental.h"
16 
17 #include "CommandFunctors.h"
18 #include "CommandFlag.h"
19 
20 #include "../MemoryX.h"
21 #include <vector>
22 #include <wx/string.h>
23 #include <wx/dynarray.h>
24 #include <wx/menu.h>
25 #include <wx/hashmap.h>
26 
27 #include "../xml/XMLTagHandler.h"
28 
29 #include "audacity/Types.h"
30 
31 #ifndef __AUDACITY_OLD_STD__
32 #include <unordered_map>
33 #endif
34 
36 {
37  MenuBarListEntry(const wxString &name_, wxMenuBar *menubar_)
38  : name(name_), menubar(menubar_)
39  {}
40 
41  wxString name;
42  wxMenuBar *menubar; // This structure does not assume memory ownership!
43 };
44 
46 {
47  SubMenuListEntry(const wxString &name_, std::unique_ptr<wxMenu> &&menu_)
48  : name(name_), menu( std::move(menu_) )
49  {}
50 
52  : name(std::move(that.name))
53  , menu(std::move(that.menu))
54  {
55  }
56 
57  wxString name;
58  std::unique_ptr<wxMenu> menu;
59 };
60 
62 {
63  int id;
64  wxString name;
65  wxString key;
66  wxString defaultKey;
67  wxString label;
68  wxString labelPrefix;
69  wxString labelTop;
70  wxMenu *menu;
74  bool multi;
75  int index;
76  int count;
77  bool enabled;
79  bool wantKeyup;
80  bool isGlobal;
81  bool isOccult;
84 };
85 
86 using MenuBarList = std::vector < MenuBarListEntry >;
87 
88 // to do: remove the extra indirection when Mac compiler moves to newer version
89 using SubMenuList = std::vector < movable_ptr<SubMenuListEntry> >;
90 
91 // This is an array of pointers, not structures, because the hash maps also point to them,
92 // so we don't want the structures to relocate with vector operations.
93 using CommandList = std::vector<movable_ptr<CommandListEntry>>;
94 
95 using CommandNameHash = std::unordered_map<wxString, CommandListEntry*>;
96 using CommandIDHash = std::unordered_map<int, CommandListEntry*>;
97 
98 class AudacityProject;
99 
100 class AUDACITY_DLL_API CommandManager final : public XMLTagHandler
101 {
102  public:
103 
104  //
105  // Constructor / Destructor
106  //
107 
108  CommandManager();
109  virtual ~CommandManager();
110 
112  CommandManager &operator= (const CommandManager&) PROHIBITED;
113 
114  void SetMaxList();
115  void PurgeData();
116 
117  //
118  // Creating menus and adding commands
119  //
120 
121  std::unique_ptr<wxMenuBar> AddMenuBar(const wxString & sMenu);
122 
123  // You may either called SetCurrentMenu later followed by ClearCurrentMenu,
124  // or else BeginMenu followed by EndMenu. Don't mix them.
125  void BeginMenu(const wxString & tName);
126  void EndMenu();
127 
128  wxMenu* BeginSubMenu(const wxString & tName);
129  void EndSubMenu();
130 
131  void InsertItem(const wxString & name,
132  const wxString & label,
133  CommandHandlerFinder finder,
134  CommandFunctorPointer callback,
135  const wxString & after,
136  int checkmark = -1);
137 
138  void AddItemList(const wxString & name,
139  const wxArrayString & labels,
140  CommandHandlerFinder finder,
141  CommandFunctorPointer callback);
142 
143  void AddCheck(const wxChar *name,
144  const wxChar *label,
145  CommandHandlerFinder finder,
146  CommandFunctorPointer callback,
147  int checkmark = 0);
148 
149  void AddCheck(const wxChar *name,
150  const wxChar *label,
151  CommandHandlerFinder finder,
152  CommandFunctorPointer callback,
153  int checkmark,
154  CommandFlag flags,
155  CommandMask mask);
156 
157  void AddItem(const wxChar *name,
158  const wxChar *label,
159  CommandHandlerFinder finder,
160  CommandFunctorPointer callback,
163  const CommandParameter &parameter = CommandParameter{});
164 
165  void AddItem(const wxChar *name,
166  const wxChar *label_in,
167  CommandHandlerFinder finder,
168  CommandFunctorPointer callback,
169  const wxChar *accel,
172  int checkmark = -1,
173  const CommandParameter &parameter = CommandParameter{});
174 
175  void AddSeparator();
176 
177  // A command doesn't actually appear in a menu but might have a
178  // keyboard shortcut.
179  void AddCommand(const wxChar *name,
180  const wxChar *label,
181  CommandHandlerFinder finder,
182  CommandFunctorPointer callback,
185 
186  void AddCommand(const wxChar *name,
187  const wxChar *label,
188  CommandHandlerFinder finder,
189  CommandFunctorPointer callback,
190  const wxChar *accel,
193 
194  void AddGlobalCommand(const wxChar *name,
195  const wxChar *label,
196  CommandHandlerFinder finder,
197  CommandFunctorPointer callback,
198  const wxChar *accel);
199  //
200  // Command masks
201  //
202 
203  // For NEW items/commands
204  void SetDefaultFlags(CommandFlag flags, CommandMask mask);
205  CommandFlag GetDefaultFlags() const { return mDefaultFlags; }
206  CommandMask GetDefaultMask() const { return mDefaultMask; }
207 
208  void SetOccultCommands( bool bOccult);
209 
210 
211  void SetCommandFlags(const wxString &name, CommandFlag flags, CommandMask mask);
212  void SetCommandFlags(const wxChar **names,
213  CommandFlag flags, CommandMask mask);
214  // Pass multiple command names as const wxChar *, terminated by NULL
215  void SetCommandFlags(CommandFlag flags, CommandMask mask, ...);
216 
217  //
218  // Modifying menus
219  //
220 
221  void EnableUsingFlags(CommandFlag flags, CommandMask mask);
222  void Enable(const wxString &name, bool enabled);
223  void Check(const wxString &name, bool checked);
224  void Modify(const wxString &name, const wxString &newLabel);
225 
226  // You may either called SetCurrentMenu later followed by ClearCurrentMenu,
227  // or else BeginMenu followed by EndMenu. Don't mix them.
228  void SetCurrentMenu(wxMenu * menu);
229  void ClearCurrentMenu();
230 
231  //
232  // Modifying accelerators
233  //
234 
235  void SetKeyFromName(const wxString &name, const wxString &key);
236  void SetKeyFromIndex(int i, const wxString &key);
237 
238  //
239  // Executing commands
240  //
241 
242  // "permit" allows filtering even if the active window isn't a child of the project.
243  // Lyrics and MixerTrackCluster classes use it.
244  bool FilterKeyEvent(AudacityProject *project, const wxKeyEvent & evt, bool permit = false);
245  bool HandleMenuID(int id, CommandFlag flags, CommandMask mask);
246  bool HandleTextualCommand(const wxString & Str, CommandFlag flags, CommandMask mask);
247 
248  //
249  // Accessing
250  //
251 
252  void GetCategories(wxArrayString &cats);
253  void GetAllCommandNames(wxArrayString &names, bool includeMultis);
254  void GetAllCommandLabels(wxArrayString &labels, bool includeMultis);
255  void GetAllCommandData(
256  wxArrayString &names, wxArrayString &keys, wxArrayString &default_keys,
257  wxArrayString &labels, wxArrayString &categories,
258 #if defined(EXPERIMENTAL_KEY_VIEW)
259  wxArrayString &prefixes,
260 #endif
261  bool includeMultis);
262 
263  wxString GetLabelFromName(const wxString &name);
264  wxString GetPrefixedLabelFromName(const wxString &name);
265  wxString GetCategoryFromName(const wxString &name);
266  wxString GetKeyFromName(const wxString &name) const;
267  wxString GetDefaultKeyFromName(const wxString &name);
268 
269  bool GetEnabled(const wxString &name);
270 
271 #if defined(__WXDEBUG__)
272  void CheckDups();
273 #endif
274 
275  //
276  // Loading/Saving
277  //
278 
279  void WriteXML(XMLWriter &xmlFile) const /* not override */;
280  void TellUserWhyDisallowed(const wxString & Name, CommandFlag flagsGot, CommandFlag flagsRequired);
281 
285  using LocalizedCommandName = std::pair<wxString, const wxChar*>;
286  using LocalizedCommandNameVector = std::vector<LocalizedCommandName>;
287  wxString DescribeCommandsAndShortcuts
288  (// An array of paired user-visible strings, and
289  // non-user-visible command names. If a shortcut key is defined
290  // for the command, then it is appended, parenthesized, after the
291  // user-visible string.
292  const LocalizedCommandNameVector &commands) const;
293 
294 protected:
295 
296  //
297  // Creating menus and adding commands
298  //
299 
300  int NextIdentifier(int ID);
301  CommandListEntry *NewIdentifier(const wxString & name,
302  const wxString & label,
303  wxMenu *menu,
304  CommandHandlerFinder finder,
305  CommandFunctorPointer callback,
306  bool multi,
307  int index,
308  int count);
309  CommandListEntry *NewIdentifier(const wxString & name,
310  const wxString & label,
311  const wxString & accel,
312  wxMenu *menu,
313  CommandHandlerFinder finder,
314  CommandFunctorPointer callback,
315  bool multi,
316  int index,
317  int count,
318  const CommandParameter &parameter);
319 
320  //
321  // Executing commands
322  //
323 
324  bool HandleCommandEntry(const CommandListEntry * entry, CommandFlag flags, CommandMask mask, const wxEvent * evt = NULL);
325 
326  //
327  // Modifying
328  //
329 
330  void Enable(CommandListEntry *entry, bool enabled);
331 
332  //
333  // Accessing
334  //
335 
336  wxMenuBar * CurrentMenuBar() const;
337  wxMenuBar * GetMenuBar(const wxString & sMenu) const;
338  wxMenu * CurrentSubMenu() const;
339  wxMenu * CurrentMenu() const;
340  wxString GetLabel(const CommandListEntry *entry) const;
341  wxString GetLabelWithDisabledAccel(const CommandListEntry *entry) const;
342 
343  //
344  // Loading/Saving
345  //
346 
347  bool HandleXMLTag(const wxChar *tag, const wxChar **attrs) override;
348  void HandleXMLEndTag(const wxChar *tag) override;
349  XMLTagHandler *HandleXMLChild(const wxChar *tag) override;
350 
351 private:
352  // mMaxList only holds shortcuts that should not be added (by default).
353  wxSortedArrayString mMaxListOnly;
354 
363 
364  bool mbSeparatorAllowed; // false at the start of a menu and immediately after a separator.
365 
367  std::unique_ptr<wxMenu> uCurrentMenu;
368  wxMenu *mCurrentMenu {};
369 
373 };
374 
375 #endif
std::pair< wxString, const wxChar * > LocalizedCommandName
wxString labelPrefix
static wxArrayString names()
Definition: Tags.cpp:697
List of SubMenuListEntry.
bool bMakingOccultCommands
int id
#define PROHIBITED
Definition: Audacity.h:217
List of CommandListEntry.
CommandMask mask
wxString defaultKey
wxString label
CommandList mCommandList
virtual XMLTagHandler * HandleXMLChild(const wxChar *tag)=0
CommandNameHash mCommandKeyHash
int count
wxString label
Definition: Tags.cpp:727
std::unique_ptr< wxMenu > uCurrentMenu
bool enabled
List of MenuBarListEntry.
SubMenuList mSubMenuList
wxMenuBar * menubar
wxString name
wxString mCurrentMenuName
int index
wxString key
wxMenu * menu
AudacityProject provides the main window, with tools and tracks contained within it.
Definition: Project.h:161
CommandParameter parameter
SubMenuListEntry(SubMenuListEntry &&that)
CommandNameHash mCommandNameHash
std::vector< LocalizedCommandName > LocalizedCommandNameVector
CommandFunctorPointer callback
CommandListEntry is a structure used by CommandManager.
bool skipKeydown
virtual bool HandleXMLTag(const wxChar *tag, const wxChar **attrs)=0
CommandManager implements a system for organizing all user-callable commands.
CommandHandlerFinder finder
This class is an interface which should be implemented by classes which wish to be able to load and s...
Definition: XMLTagHandler.h:70
bool isGlobal
wxSortedArrayString mMaxListOnly
bool multi
bool wantKeyup
#define EXPERIMENTAL_KEY_VIEW
Definition: Project.h:47
wxString name
CommandMask mDefaultMask
CommandFlag GetDefaultFlags() const
MenuBarList mMenuBarList
CommandMask GetDefaultMask() const
CommandFlag
Definition: CommandFlag.h:16
SubMenuListEntry(const wxString &name_, std::unique_ptr< wxMenu > &&menu_)
std::unique_ptr< wxMenu > menu
const wxChar * name
Definition: Distortion.cpp:94
CommandFlag mDefaultFlags
std::unordered_map< wxString, CommandListEntry * > CommandNameHash
MenuBarListEntry(const wxString &name_, wxMenuBar *menubar_)
void(CommandHandlerObject::*)(const CommandContext &) CommandFunctorPointer
wxString labelTop
virtual void HandleXMLEndTag(const wxChar *WXUNUSED(tag))
Definition: XMLTagHandler.h:87
CommandHandlerObject &(*)(AudacityProject &) CommandHandlerFinder
Base class for XMLFileWriter and XMLStringWriter that provides the general functionality for creating...
Definition: XMLWriter.h:22
CommandIDHash mCommandIDHash
CommandFlag flags
wxString CommandParameter
SubMenuListEntry is a structure used by CommandManager.
MenuBarListEntry is a structure used by CommandManager.
std::unordered_map< int, CommandListEntry * > CommandIDHash
bool isOccult
wxString name