NCBI C++ ToolKit
ui_command.hpp
Go to the documentation of this file.

Go to the SVN repository for this file.

1 #ifndef GUI_WIDGETS_WX___COMMAND_REGISTRY__HPP
2 #define GUI_WIDGETS_WX___COMMAND_REGISTRY__HPP
3 
4 /* $Id: ui_command.hpp 46055 2021-01-21 18:38:04Z grichenk $
5  * ===========================================================================
6  *
7  * PUBLIC DOMAIN NOTICE
8  * National Center for Biotechnology Information
9  *
10  * This software/database is a "United States Government Work" under the
11  * terms of the United States Copyright Act. It was written as part of
12  * the author's official duties as a United States Government employee and
13  * thus cannot be copyrighted. This software/database is freely available
14  * to the public for use. The National Library of Medicine and the U.S.
15  * Government have not placed any restriction on its use or reproduction.
16  *
17  * Although all reasonable efforts have been taken to ensure the accuracy
18  * and reliability of the software and data, the NLM and the U.S.
19  * Government do not and cannot warrant the performance or results that
20  * may be obtained by using this software or data. The NLM and the U.S.
21  * Government disclaim all warranties, express or implied, including
22  * warranties of performance, merchantability or fitness for any particular
23  * purpose.
24  *
25  * Please cite the author in any work or product based on this material.
26  *
27  * ===========================================================================
28  *
29  * Authors: Andrey Yazhuk
30  *
31  * File Description:
32  * CUICommand and CUICommandRegistry class declarations.
33  */
34 
35 #include <corelib/ncbistd.hpp>
36 #include <unordered_map>
37 
38 #include <gui/gui_export.h>
39 
40 #include <gui/utils/ui_object.hpp>
41 #include <gui/utils/command.hpp>
42 
43 // This header must (at least indirectly) precede any wxWidgets headers.
45 
46 #include <wx/menuitem.h>
47 #include <wx/event.h>
48 #include <wx/menu.h>
49 
50 class wxMenu;
51 class wxMenuItem;
52 class wxMenuBar;
53 class wxToolBar;
54 class wxAuiToolBar;
55 class wxWindow;
56 class wxAcceleratorEntry;
57 class wxAcceleratorTable;
58 
59 
61 
62 struct SwxMenuItemRec;
63 struct SwxCommandRec;
64 
65 ///////////////////////////////////////////////////////////////////////////////
66 /// CUICommand
67 ///
68 /// CUICommand represents a UI command that can be used in menus, toolbars,
69 /// menu bar and other similar UI controls.
70 ///
71 /// - Command ID - an integer identifier that is used in GUI Tookit event
72 /// handling.
73 /// - Menu Label - a label for menu with access keys and shortcut.
74 /// Example: “Save as &Web Page\tCtrl+W”
75 /// For other fields see CUIObject.
76 
78  : public CUIObject
79 {
80 public:
81  /// a collection of wxWidget-style accelerator definitions
82  typedef vector<wxAcceleratorEntry> TAccelerators;
83 
84  CUICommand(
85  TCmdID cmd_id,
86  string menu_label,
87  string name,
88  string icon_alias,
89  string hint = kEmptyStr,
90  string description = kEmptyStr,
91  string help_id = kEmptyStr,
92  wxItemKind kind = wxITEM_NORMAL
93  );
94  CUICommand( const SwxCommandRec* rec );
95  CUICommand( const CUICommand& cmd );
96 
97  ~CUICommand();
98 
99  /// the class inherits set/get methods from CUIObject
100 
101  void SetCmdID(TCmdID cmd_id);
102 
103  void AddAccelerator(int flags, int key_code); // see wxAcceleratorEntry constructor
104 
105  int GetCmdID() const;
106  const string& GetMenuLabel() const;
107  const string& GetName() const { return CUIObject::GetLabel(); }
108 
109  const TAccelerators* GetAccelerators() const;
110 
111  wxMenuItem* AppendMenuItem( wxMenu& menu ) const;
112  wxMenuItem* AppendMenuItem( wxMenu& menu, wxItemKind kind ) const;
113 
114 protected:
115  TCmdID m_CmdID; // menu command ID
116  string m_MenuLabel;
117  wxItemKind m_Kind;
118 
119  // one or more keyboard accelerators for the command
120  unique_ptr<TAccelerators> m_Accelerators;
121 };
122 
124 {
126  string m_MenuLabel;
127  string m_Name;
128  string m_IconAlias;
129  string m_Hint;
131  string m_HelpId;
132  wxItemKind m_Kind;
133 };
134 
135 ///////////////////////////////////////////////////////////////////////////////
136 ///
137 /// CUICommandRegistry is a centralized registry where all application commands
138 /// should be registered. The purpose of the registry is to provide completed,
139 /// consistent and non-redundant information on application commands, their
140 /// labels, tooltips, icons and other attributes. Application components shall
141 /// use CUICommandRegistry for constructing menus, toolbars and other
142 /// command-based UI components. Components adding new commands to the
143 /// application shall register them in CUICommandRegistry.
144 
146 {
147 public:
148  /// the main instance associated with the application
149  static CUICommandRegistry& GetInstance();
150 
151  CUICommandRegistry(TCmdID start_id);
152  virtual ~CUICommandRegistry();
153 
154  /// assumes ownership of the given object
155  /// returns a command id (useful when registry is used for auto id assignment)
156  int RegisterCommand(CUICommand* cmd);
157 
158  /// create a CUICommand and registers it
159  int RegisterCommand(TCmdID cmd_id,
160  string menu_label,
161  string label,
162  string icon_alias,
163  string hint = kEmptyStr,
164  string description = kEmptyStr,
165  string help_id = kEmptyStr,
166  wxItemKind kind = wxITEM_NORMAL);
167 
168  /// returns CUICommand object or NULL
169  const CUICommand* FindCommandByID( TCmdID cmd_id ) const;
170  /// It is expensive function so use it wisely
171  const CUICommand* FindCommandByName( string name ) const;
172 
173  /// @name Accelerators support
174  /// @{
175  /// add a new accelerators to the local table
176  void AddAccelerator(const wxAcceleratorEntry& entry);
177 
178  /// apply accumulated accelerators to the specifed frame
179  void ApplyAccelerators(wxWindow* frame);
180  /// @}
181 
182  /// @name Menu and ToolBar support
183  /// @{
184  wxMenuItem* AppendMenuItem( wxMenu& menu, TCmdID cmd_id ) const;
185  wxMenuItem* AppendMenuItem( wxMenu& menu, TCmdID cmd_id, wxItemKind kind ) const;
186  void AppendMenuItems(wxMenu& menu, const TCmdID* cmd_ids, int count) const;
187  void AppendMenuItems(wxMenu& menu, const vector<TCmdID> cmd_ids) const;
188 
189  /// create a menu from a static definition (see WX_*_MENU macros)
190  wxMenu* CreateMenu( const SwxMenuItemRec* items );
191 
192  void AppendTool(wxToolBar& tool_bar, TCmdID cmd_id);
193  void AppendTool(wxAuiToolBar& tool_bar, TCmdID cmd_id);
194  /// @}
195 private:
198 
199 protected:
200  typedef std::unordered_map<int, CUICommand*> TIDToCommand;
201 
203 
204  TCmdID m_NextID; // the id of the next generated cmd id
206 
207  // support for Accelerators
208  vector<wxAcceleratorEntry> m_AccelEntries;
209 };
210 
212 {
214  eDefaultItem = 0,
219  eSeparator
220  };
221 
225  eExternal
226  };
227 
228  int m_Type;
229  const char* m_Label;
231  int m_Kind;
233 
234  bool IsSubMenu() const
235  {
236  return m_Type == eSubmenu && m_CommandID == eCmdNone;
237  }
238  bool IsSubMenuEnd() const
239  {
240  return m_Type == eSubmenu && m_CommandID == eCmdInvalid;
241  }
242  bool IsMenuEnd() const
243  {
244  return m_Type == eSubmenu && m_CommandID == eCmdMenuEnd;
245  }
246 
247  bool IsInternal() const
248  {
249  return m_InternalOrExternal == eInternal;
250  }
251 
252  bool IsExternal() const
253  {
254  return m_InternalOrExternal == eExternal;
255  }
256 
257  bool IsBoth() const
258  {
259  return m_InternalOrExternal == eBoth;
260  }
261 };
262 
263 
264 ////////////////////////////////////////////////////////////////////////////////
265 /// New macros for defining menus for use with CUICommandRegistry
266 #define WX_DEFINE_MENU(name) \
267  const SwxMenuItemRec name[] = { \
268  WX_SUBMENU("Root")
269 
270 #define WX_MENU_ITEM(cmd) \
271  { SwxMenuItemRec::eDefaultItem, "", cmd, SwxMenuItemRec::eDefaultItem, SwxMenuItemRec::eBoth },
272 
273 #define WX_MENU_NORMAL_ITEM(cmd) \
274  { SwxMenuItemRec::eNormalItem, "", cmd, SwxMenuItemRec::eDefaultItem, SwxMenuItemRec::eBoth },
275 
276 #define WX_MENU_CHECK_ITEM(cmd) \
277  { SwxMenuItemRec::eCheckItem, "", cmd, SwxMenuItemRec::eDefaultItem, SwxMenuItemRec::eBoth },
278 
279 #define WX_MENU_RADIO_ITEM(cmd) \
280  { SwxMenuItemRec::eRadioItem, "", cmd, SwxMenuItemRec::eDefaultItem, SwxMenuItemRec::eBoth },
281 
282 #define WX_MENU_SEPARATOR() \
283  { SwxMenuItemRec::eSeparator, "", eCmdNone, SwxMenuItemRec::eDefaultItem, SwxMenuItemRec::eBoth },
284 
285 #define WX_MENU_SEPARATOR_L(label) \
286  { SwxMenuItemRec::eSeparator, label, eCmdNone, SwxMenuItemRec::eDefaultItem, SwxMenuItemRec::eBoth },
287 
288 #define WX_SUBMENU(label) \
289  { SwxMenuItemRec::eSubmenu, label, eCmdNone, SwxMenuItemRec::eDefaultItem, SwxMenuItemRec::eBoth },
290 
291 #define WX_END_SUBMENU() \
292  { SwxMenuItemRec::eSubmenu, "", eCmdInvalid, SwxMenuItemRec::eDefaultItem, SwxMenuItemRec::eBoth },
293 
294 #define WX_END_MENU() \
295  { SwxMenuItemRec::eSubmenu, "", eCmdMenuEnd, SwxMenuItemRec::eDefaultItem, SwxMenuItemRec::eBoth }, \
296  };
297 
298 
299 #define WX_SUBMENU_INT(label) \
300  { SwxMenuItemRec::eSubmenu, label, eCmdNone, SwxMenuItemRec::eDefaultItem, SwxMenuItemRec::eInternal },
301 
302 #define WX_MENU_ITEM_INT(cmd) \
303  { SwxMenuItemRec::eDefaultItem, "", cmd, SwxMenuItemRec::eDefaultItem, SwxMenuItemRec::eInternal },
304 
305 #define WX_MENU_NORMAL_ITEM_INT(cmd) \
306  { SwxMenuItemRec::eNormalItem, "", cmd, SwxMenuItemRec::eDefaultItem. SwxMenuItemRec::eInternal },
307 
308 #define WX_MENU_CHECK_ITEM_INT(cmd) \
309  { SwxMenuItemRec::eCheckItem, "", cmd, SwxMenuItemRec::eDefaultItem, SwxMenuItemRec::eInternal },
310 
311 #define WX_MENU_RADIO_ITEM_INT(cmd) \
312  { SwxMenuItemRec::eRadioItem, "", cmd, SwxMenuItemRec::eDefaultItem, SwxMenuItemRec::eInternal },
313 
314 #define WX_MENU_SEPARATOR_INT() \
315  { SwxMenuItemRec::eSeparator, "", eCmdNone, SwxMenuItemRec::eDefaultItem, SwxMenuItemRec::eInternal },
316 
317 #define WX_MENU_SEPARATOR_L_INT(label) \
318  { SwxMenuItemRec::eSeparator, label, eCmdNone, SwxMenuItemRec::eDefaultItem, SwxMenuItemRec::eInternal },
319 
320 
321 #define WX_SUBMENU_EXT(label) \
322  { SwxMenuItemRec::eSubmenu, label, eCmdNone, SwxMenuItemRec::eDefaultItem, SwxMenuItemRec::eExternal },
323 
324 #define WX_MENU_ITEM_EXT(cmd) \
325  { SwxMenuItemRec::eDefaultItem, "", cmd, SwxMenuItemRec::eDefaultItem, SwxMenuItemRec::eExternal },
326 
327 #define WX_MENU_NORMAL_ITEM_EXT(cmd) \
328  { SwxMenuItemRec::eNormalItem, "", cmd, SwxMenuItemRec::eDefaultItem. SwxMenuItemRec::eExternal },
329 
330 #define WX_MENU_CHECK_ITEM_EXT(cmd) \
331  { SwxMenuItemRec::eCheckItem, "", cmd, SwxMenuItemRec::eDefaultItem, SwxMenuItemRec::eExternal },
332 
333 #define WX_MENU_RADIO_ITEM_EXT(cmd) \
334  { SwxMenuItemRec::eRadioItem, "", cmd, SwxMenuItemRec::eDefaultItem, SwxMenuItemRec::eExternal },
335 
336 #define WX_MENU_SEPARATOR_EXT() \
337  { SwxMenuItemRec::eSeparator, "", eCmdNone, SwxMenuItemRec::eDefaultItem, SwxMenuItemRec::eExternal },
338 
339 #define WX_MENU_SEPARATOR_L_EXT(label) \
340  { SwxMenuItemRec::eSeparator, label, eCmdNone, SwxMenuItemRec::eDefaultItem, SwxMenuItemRec::eExternal },
341 
342 
343 ///////////////////////////////////////////////////////////////////////////////
344 /// IUICommandContributor - contributes commands to the common command space.
345 ///
346 /// Packages can declare their own set of commands to use inside package-related views.
347 /// Views (factories, actually) can declare their command sets also.
348 ///
349 /// This interface is to be implemented by packages and view factories.
351 {
352 public:
353  /// returns a vector of commands (takes ownership over CUICommand pointers)
354  virtual vector<CUICommand*> GetCommands() = 0;
355 
356  /// returns a handler which processes commands from the set above
357  /// not needed for views
358  virtual wxEvtHandler* GetEventHandler() { return NULL; };
359 
361 };
362 
363 ///////////////////////////////////////////////////////////////////////////////
364 /// IMenuContributor - contributes menu to Menu Service.
365 ///
366 /// Objects such as Views can declare extension points that will be be extended
367 /// by classes implementing IMenuContributor.
368 ///
369 /// This interface is to be implemented by packages and views.
371 {
372 public:
373  /// returns a menu (must be deleted by the caller)
374  /// menu injections should follow a separator named "Contribs"
375  virtual const wxMenu* GetMenu() {
377  };
378 
379  virtual ~IMenuContributor() {};
380 
381 protected:
382  /// simpler way to provide a static menu using macros defined
383  /// earlier in this file
384  virtual const SwxMenuItemRec* GetMenuDef() const { return NULL; };
385 };
386 
387 ///////////////////////////////////////////////////////////////////////////////
388 /// IToolBarContributor - a factory that produces toolbars.
389 /// Toolbars can be shared across views, so vie showld implement
390 /// a method GetCompatibleToolBars( vector<string>& names )
391 /// to designate toolbars it handles.
392 ///
393 /// This interface is to be implemented by packages and view factories.
395 {
396 public:
397  /// returns the names of toolbars produced
398  virtual void GetToolBarNames( vector<string>& names ) = 0;
399 
400  /// creates a toolbar with the given name (must be deleted by the caller)
401  virtual wxAuiToolBar* CreateToolBar( const string& name, wxWindow* parent ) = 0;
402 
403  virtual ~IToolBarContributor() {};
404 };
405 
406 
408 
409 
410 #endif // GUI_WIDGETS_WX___COMMAND_REGISTRY__HPP
411 
@ eBoth
Both preliminary and traceback stages.
Definition: blast_def.h:332
CUICommandRegistry is a centralized registry where all application commands should be registered.
Definition: ui_command.hpp:146
static CUICommandRegistry & GetInstance()
the main instance associated with the application
Definition: ui_command.cpp:176
wxMenu * CreateMenu(const SwxMenuItemRec *items)
create a menu from a static definition (see WX_*_MENU macros)
Definition: ui_command.cpp:349
std::unordered_map< int, CUICommand * > TIDToCommand
Definition: ui_command.hpp:200
CUICommandRegistry & operator=(const CUICommandRegistry &)
TIDToCommand m_IDToCommand
Definition: ui_command.hpp:205
static CUICommandRegistry sm_TheRegistry
CUICommandRegistry.
Definition: ui_command.hpp:202
vector< wxAcceleratorEntry > m_AccelEntries
Definition: ui_command.hpp:208
CUICommandRegistry(const CUICommandRegistry &)
CUICommand.
Definition: ui_command.hpp:79
TCmdID m_CmdID
Definition: ui_command.hpp:115
string m_MenuLabel
Definition: ui_command.hpp:116
unique_ptr< TAccelerators > m_Accelerators
Definition: ui_command.hpp:120
const string & GetName() const
Definition: ui_command.hpp:107
vector< wxAcceleratorEntry > TAccelerators
a collection of wxWidget-style accelerator definitions
Definition: ui_command.hpp:82
CUICommand(const SwxCommandRec *rec)
wxItemKind m_Kind
Definition: ui_command.hpp:117
CUIObject - default mix-in implementation of IUIObject.
Definition: ui_object.hpp:81
IMenuContributor - contributes menu to Menu Service.
Definition: ui_command.hpp:371
virtual const wxMenu * GetMenu()
returns a menu (must be deleted by the caller) menu injections should follow a separator named "Contr...
Definition: ui_command.hpp:375
virtual ~IMenuContributor()
Definition: ui_command.hpp:379
virtual const SwxMenuItemRec * GetMenuDef() const
simpler way to provide a static menu using macros defined earlier in this file
Definition: ui_command.hpp:384
IToolBarContributor - a factory that produces toolbars.
Definition: ui_command.hpp:395
virtual void GetToolBarNames(vector< string > &names)=0
returns the names of toolbars produced
virtual ~IToolBarContributor()
Definition: ui_command.hpp:403
virtual wxAuiToolBar * CreateToolBar(const string &name, wxWindow *parent)=0
creates a toolbar with the given name (must be deleted by the caller)
IUICommandContributor - contributes commands to the common command space.
Definition: ui_command.hpp:351
virtual wxEvtHandler * GetEventHandler()
returns a handler which processes commands from the set above not needed for views
Definition: ui_command.hpp:358
virtual ~IUICommandContributor()
Definition: ui_command.hpp:360
virtual vector< CUICommand * > GetCommands()=0
returns a vector of commands (takes ownership over CUICommand pointers)
GUI command routing and handling framework.
Include a standard set of the NCBI C++ Toolkit most basic headers.
static uch flags
Workaround for wxWidgets header errors in certain configurations; MUST be included (at least indirect...
static CS_COMMAND * cmd
Definition: ct_dynamic.c:26
static const struct name_t names[]
#define NULL
Definition: ncbistd.hpp:225
virtual const string & GetLabel() const
Definition: ui_object.cpp:124
int TCmdID
@ eCmdMenuEnd
Definition: command.hpp:63
@ eCmdInvalid
marks menu end in array initializers
Definition: command.hpp:64
@ eCmdNone
not a valid command
Definition: command.hpp:65
#define END_NCBI_SCOPE
End previously defined NCBI scope.
Definition: ncbistl.hpp:103
#define BEGIN_NCBI_SCOPE
Define ncbi namespace.
Definition: ncbistl.hpp:100
#define kEmptyStr
Definition: ncbistr.hpp:123
#define NCBI_GUIWIDGETS_WX_EXPORT
Definition: gui_export.h:543
static const char label[]
Defines to provide correct exporting from DLLs in Windows.
#define count
string m_Description
Definition: ui_command.hpp:130
string m_IconAlias
Definition: ui_command.hpp:128
wxItemKind m_Kind
Definition: ui_command.hpp:132
string m_MenuLabel
Definition: ui_command.hpp:126
TCmdID m_CommandID
Definition: ui_command.hpp:230
bool IsMenuEnd() const
Definition: ui_command.hpp:242
const char * m_Label
Definition: ui_command.hpp:229
bool IsExternal() const
Definition: ui_command.hpp:252
bool IsBoth() const
Definition: ui_command.hpp:257
bool IsSubMenu() const
Definition: ui_command.hpp:234
bool IsSubMenuEnd() const
Definition: ui_command.hpp:238
EMenuInternalOrExternal m_InternalOrExternal
Definition: ui_command.hpp:232
bool IsInternal() const
Definition: ui_command.hpp:247
wxMenu * CreateMenu(const CMenuItem *item)
Creates a wxMenu object replicating the structure of CMenuItem.
Definition: wx_utils.cpp:365
Modified on Fri Sep 20 14:57:06 2024 by modify_doxy.py rev. 669887