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