KiCad PCB EDA Suite
tool_manager.h
Go to the documentation of this file.
1 /*
2  * This program source code file is part of KiCad, a free EDA CAD application.
3  *
4  * Copyright (C) 2013 CERN
5  * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors.
6  *
7  * @author Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
8  * @author Maciej Suminski <maciej.suminski@cern.ch>
9  *
10  * This program is free software; you can redistribute it and/or
11  * modify it under the terms of the GNU General Public License
12  * as published by the Free Software Foundation; either version 2
13  * of the License, or (at your option) any later version.
14  *
15  * This program is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18  * GNU General Public License for more details.
19  *
20  * You should have received a copy of the GNU General Public License
21  * along with this program; if not, you may find one here:
22  * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
23  * or you may search the http://www.gnu.org website for the version 2 license,
24  * or you may write to the Free Software Foundation, Inc.,
25  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
26  */
27 
28 #ifndef __TOOL_MANAGER_H
29 #define __TOOL_MANAGER_H
30 
31 #include <typeinfo>
32 #include <map>
33 #include <list>
34 #include <stack>
35 
36 #include <tool/tool_base.h>
37 #include <view/view_controls.h>
38 
39 class TOOLS_HOLDER;
40 class TOOL_BASE;
41 class ACTION_MANAGER;
42 class ACTION_MENU;
43 class APP_SETTINGS_BASE;
44 
45 
53 {
54 private:
55  struct TOOL_STATE;
56 
57 public:
58  TOOL_MANAGER();
59 
60  ~TOOL_MANAGER();
61 
62  // Helper typedefs
63  typedef std::map<TOOL_BASE*, TOOL_STATE*> TOOL_STATE_MAP;
64  typedef std::map<std::string, TOOL_STATE*> NAME_STATE_MAP;
65  typedef std::map<TOOL_ID, TOOL_STATE*> ID_STATE_MAP;
66  typedef std::list<TOOL_ID> ID_LIST;
67  typedef std::vector<TOOL_BASE*> TOOL_VEC;
68 
72  static TOOL_ID MakeToolId( const std::string& aToolName );
73 
80  void RegisterTool( TOOL_BASE* aTool );
81 
88  bool InvokeTool( TOOL_ID aToolId );
89 
96  bool InvokeTool( const std::string& aToolName );
97 
102  void ShutdownAllTools();
103 
110  void ShutdownTool( TOOL_BASE* aTool );
111 
118  void ShutdownTool( TOOL_ID aToolId );
119 
126  void ShutdownTool( const std::string& aToolName );
127 
140  template<typename T>
141  bool RunAction( const std::string& aActionName, bool aNow = false, T aParam = NULL )
142  {
143  return RunAction( aActionName, aNow, reinterpret_cast<void*>( aParam ) );
144  }
145 
146  bool RunAction( const std::string& aActionName, bool aNow, void* aParam );
147 
148  bool RunAction( const std::string& aActionName, bool aNow = false )
149  {
150  return RunAction( aActionName, aNow, (void*) NULL );
151  }
152 
166  template <typename T>
167  bool RunAction( const TOOL_ACTION& aAction, bool aNow = false, T aParam = NULL )
168  {
169  return RunAction( aAction, aNow, reinterpret_cast<void*>( aParam ) );
170  }
171 
172  bool RunAction( const TOOL_ACTION& aAction, bool aNow, void* aParam );
173 
174  bool RunAction( const TOOL_ACTION& aAction, bool aNow = false )
175  {
176  return RunAction( aAction, aNow, (void*) NULL );
177  }
178 
179  const std::map<std::string, TOOL_ACTION*>& GetActions();
180 
184  void CancelTool();
185 
192  void PrimeTool( const VECTOR2D& aPosition );
193 
195  int GetHotKey( const TOOL_ACTION& aAction );
196 
198 
205  TOOL_BASE* FindTool( int aId ) const;
206 
213  TOOL_BASE* FindTool( const std::string& aName ) const;
214 
215  /*
216  * Return the tool of given type or NULL if there is no such tool registered.
217  */
218  template<typename T>
219  T* GetTool()
220  {
221  std::map<const char*, TOOL_BASE*>::iterator tool = m_toolTypes.find( typeid( T ).name() );
222 
223  if( tool != m_toolTypes.end() )
224  return static_cast<T*>( tool->second );
225 
226  return NULL;
227  }
228 
232  void DeactivateTool();
233 
234 
238  bool IsToolActive( TOOL_ID aId ) const;
239 
240 
244  void ResetTools( TOOL_BASE::RESET_REASON aReason );
245 
252  void InitTools();
253 
260  bool ProcessEvent( const TOOL_EVENT& aEvent );
261 
267  inline void PostEvent( const TOOL_EVENT& aEvent )
268  {
269  // Horrific hack, but it's a crash bug. Don't let inter-frame commands stack up
270  // waiting to be processed.
271  if( aEvent.IsSimulator() && m_eventQueue.size() > 0 && m_eventQueue.back().IsSimulator() )
272  m_eventQueue.pop_back();
273 
274  m_eventQueue.push_back( aEvent );
275  }
276 
282  void SetEnvironment( EDA_ITEM* aModel, KIGFX::VIEW* aView,
283  KIGFX::VIEW_CONTROLS* aViewControls, APP_SETTINGS_BASE* aSettings,
284  TOOLS_HOLDER* aFrame );
285 
286  /*
287  * Accessors for the environment objects (view, model, etc.)
288  */
289  KIGFX::VIEW* GetView() const { return m_view; }
290 
292 
295 
296  EDA_ITEM* GetModel() const { return m_model; }
297 
299 
300  TOOLS_HOLDER* GetToolHolder() const { return m_frame; }
301 
308  inline int GetCurrentToolId() const
309  {
310  return m_activeTools.empty() ? -1 : m_activeTools.front();
311  }
312 
319  inline TOOL_BASE* GetCurrentTool() const
320  {
321  return FindTool( GetCurrentToolId() );
322  }
323 
329  {
330  auto it = m_toolIdIndex.find( GetCurrentToolId() );
331  return ( it != m_toolIdIndex.end() ) ? it->second : nullptr;
332  }
333 
344  int GetPriority( int aToolId ) const;
345 
352  void ScheduleNextState( TOOL_BASE* aTool, TOOL_STATE_FUNC& aHandler,
353  const TOOL_EVENT_LIST& aConditions );
354 
360  void ClearTransitions( TOOL_BASE* aTool );
361 
362  void RunMainStack( TOOL_BASE* aTool, std::function<void()> aFunc );
363 
367  void UpdateUI( const TOOL_EVENT& aEvent );
368 
374  TOOL_EVENT* ScheduleWait( TOOL_BASE* aTool, const TOOL_EVENT_LIST& aConditions );
375 
387  void ScheduleContextMenu( TOOL_BASE* aTool, ACTION_MENU* aMenu, CONTEXT_MENU_TRIGGER aTrigger );
388 
396  bool SaveClipboard( const std::string& aTextUTF8 );
397 
406  std::string GetClipboardUTF8() const;
407 
412  const KIGFX::VC_SETTINGS& GetCurrentToolVC() const;
413 
418  {
419  return m_menuActive;
420  }
421 
429  {
431  }
432 
436  void DispatchContextMenu( const TOOL_EVENT& aEvent );
437 
444  bool DispatchHotKey( const TOOL_EVENT& aEvent );
445 
447  {
448  return m_menuCursor;
449  }
450 
451 private:
452  typedef std::pair<TOOL_EVENT_LIST, TOOL_STATE_FUNC> TRANSITION;
453 
457  bool dispatchInternal( const TOOL_EVENT& aEvent );
458 
465  bool dispatchActivation( const TOOL_EVENT& aEvent );
466 
473  bool invokeTool( TOOL_BASE* aTool );
474 
483  bool runTool( TOOL_BASE* aTool );
484 
493  ID_LIST::iterator finishTool( TOOL_STATE* aState );
494 
501  bool isRegistered( TOOL_BASE* aTool ) const
502  {
503  return m_toolState.count( aTool ) > 0;
504  }
505 
512  bool isActive( TOOL_BASE* aTool );
513 
519  void saveViewControls( TOOL_STATE* aState );
520 
524  void applyViewControls( TOOL_STATE* aState );
525 
531  bool processEvent( const TOOL_EVENT& aEvent );
532 
539  void setActiveState( TOOL_STATE* aState );
540 
543 
546 
549 
552 
554  std::map<const char*, TOOL_BASE*> m_toolTypes;
555 
558 
561 
563  std::map<TOOL_ID, OPT<VECTOR2D>> m_cursorSettings;
564 
570 
572  std::list<TOOL_EVENT> m_eventQueue;
573 
576 
578 
581 
584 
587 };
588 
589 #endif
void ShutdownAllTools()
Shutdown all tools with a currently registered event loop in this tool manager by waking them up with...
bool m_menuActive
Tool currently displaying a popup menu. It is negative when there is no menu displayed.
Definition: tool_manager.h:580
void DispatchContextMenu(const TOOL_EVENT &aEvent)
Handle context menu related events.
VECTOR2D GetCursorPosition()
VECTOR2D m_menuCursor
Definition: tool_manager.h:575
KIGFX::VIEW * GetView() const
Definition: tool_manager.h:289
void UpdateUI(const TOOL_EVENT &aEvent)
Update the status bar and synchronizes toolbars.
int GetHotKey(const TOOL_ACTION &aAction)
ACTION_MANAGER * m_actionMgr
Original cursor position, if overridden by the context menu handler.
Definition: tool_manager.h:560
bool processEvent(const TOOL_EVENT &aEvent)
Main function for event processing.
static TOOL_ID MakeToolId(const std::string &aToolName)
Generates a unique ID from for a tool with given name.
int GetPriority(int aToolId) const
Return priority of a given tool.
TOOL_VEC m_toolOrder
Index of registered tools current states, associated by tools' objects.
Definition: tool_manager.h:542
Defines the structure of a menu based on ACTIONs.
Definition: action_menu.h:45
ID_STATE_MAP m_toolIdIndex
Index of the registered tools to easily lookup by their type.
Definition: tool_manager.h:551
void ScheduleNextState(TOOL_BASE *aTool, TOOL_STATE_FUNC &aHandler, const TOOL_EVENT_LIST &aConditions)
Define a state transition.
bool RunAction(const TOOL_ACTION &aAction, bool aNow=false)
Definition: tool_manager.h:174
std::map< TOOL_ID, TOOL_STATE * > ID_STATE_MAP
Definition: tool_manager.h:65
std::map< TOOL_ID, OPT< VECTOR2D > > m_cursorSettings
Definition: tool_manager.h:563
ID_LIST::iterator finishTool(TOOL_STATE *aState)
Deactivate a tool and does the necessary clean up.
bool dispatchActivation(const TOOL_EVENT &aEvent)
Check if it is a valid activation event and invokes a proper tool.
std::map< std::string, TOOL_STATE * > NAME_STATE_MAP
Definition: tool_manager.h:64
bool RunAction(const std::string &aActionName, bool aNow=false, T aParam=NULL)
Run the specified action.
Definition: tool_manager.h:141
void PrimeTool(const VECTOR2D &aPosition)
"Prime" a tool by sending a cursor left-click event with the mouse position set to the passed in posi...
Manage TOOL_ACTION objects.
TOOL_BASE * FindTool(int aId) const
Search for a tool with given ID.
TOOL_EVENT * ScheduleWait(TOOL_BASE *aTool, const TOOL_EVENT_LIST &aConditions)
Pause execution of a given tool until one or more events matching aConditions arrives.
bool DispatchHotKey(const TOOL_EVENT &aEvent)
Handle specific events, that are intended for TOOL_MANAGER rather than tools.
void applyViewControls(TOOL_STATE *aState)
Apply #VIEW_CONTROLS settings stored in a #TOOL_STATE object.
bool IsContextMenuActive()
True while processing a context menu.
Definition: tool_manager.h:417
TOOLS_HOLDER * m_frame
Definition: tool_manager.h:568
EDA_ITEM * GetModel() const
Definition: tool_manager.h:296
void DeactivateTool()
Deactivate the currently active tool.
bool InvokeTool(TOOL_ID aToolId)
Call a tool by sending a tool activation event to tool of given ID.
void ShutdownTool(TOOL_BASE *aTool)
Shutdown the specified tool by waking it up with a null event to terminate the processing loop.
std::map< TOOL_BASE *, TOOL_STATE * > TOOL_STATE_MAP
Definition: tool_manager.h:63
EDA_ITEM * m_model
Definition: tool_manager.h:565
Master controller class:
Definition: tool_manager.h:52
NAME_STATE_MAP m_toolNameIndex
Index of the registered tools current states, associated by tools' ID numbers.
Definition: tool_manager.h:548
int TOOL_ID
Unique identifier for tools.
Definition: tool_base.h:57
bool IsSimulator() const
Indicate if the event is from the simulator.
Definition: tool_event.cpp:227
A list of TOOL_EVENTs, with overloaded || operators allowing for concatenating TOOL_EVENTs with littl...
Definition: tool_event.h:575
APP_SETTINGS_BASE is a settings class that should be derived for each standalone KiCad application.
Definition: app_settings.h:99
TOOL_ID m_menuOwner
Pointer to the state object corresponding to the currently executed tool.
Definition: tool_manager.h:583
#define NULL
const std::map< std::string, TOOL_ACTION * > & GetActions()
void setActiveState(TOOL_STATE *aState)
Save the previous active state and sets a new one.
bool ProcessEvent(const TOOL_EVENT &aEvent)
Propagate an event to tools that requested events of matching type(s).
std::string GetClipboardUTF8() const
Return the information currently stored in the system clipboard.
CONTEXT_MENU_TRIGGER
Defines when a context menu is opened.
Definition: tool_event.h:163
Generic, UI-independent tool event.
Definition: tool_event.h:173
const KIGFX::VC_SETTINGS & GetCurrentToolVC() const
Return the view controls settings for the current tool or the general settings if there is no active ...
bool runTool(TOOL_BASE *aTool)
Make a tool active, so it can receive events and react to them.
Structure to keep VIEW_CONTROLS settings for easy store/restore operations.
Definition: view_controls.h:41
void ResetTools(TOOL_BASE::RESET_REASON aReason)
Reset all tools (i.e.
An interface for classes handling user events controlling the view behavior such as zooming,...
Struct describing the current execution state of a TOOL.
KIGFX::VIEW_CONTROLS * m_viewControls
Definition: tool_manager.h:567
TOOL_BASE * GetCurrentTool() const
Return the tool that is on the top of the active tools stack (was invoked the most recently).
Definition: tool_manager.h:319
std::function< int(const TOOL_EVENT &)> TOOL_STATE_FUNC
Definition: tool_base.h:59
TOOL_STATE * GetCurrentToolState() const
Return the #TOOL_STATE object representing the state of the active tool.
Definition: tool_manager.h:328
bool isActive(TOOL_BASE *aTool)
Return information about a tool activation status.
KIGFX::VIEW * m_view
Definition: tool_manager.h:566
int GetCurrentToolId() const
Return id of the tool that is on the top of the active tools stack (was invoked the most recently).
Definition: tool_manager.h:308
void RunMainStack(TOOL_BASE *aTool, std::function< void()> aFunc)
bool m_warpMouseAfterContextMenu
Flag indicating whether a context menu is currently displayed.
Definition: tool_manager.h:577
bool isRegistered(TOOL_BASE *aTool) const
Return information about a tool registration status.
Definition: tool_manager.h:501
TOOLS_HOLDER * GetToolHolder() const
Definition: tool_manager.h:300
KIGFX::VIEW_CONTROLS * GetViewControls() const
Definition: tool_manager.h:291
bool SaveClipboard(const std::string &aTextUTF8)
Store information to the system clipboard.
std::list< TOOL_EVENT > m_eventQueue
Right click context menu position.
Definition: tool_manager.h:572
const char * name
Definition: DXF_plotter.cpp:59
ACTION_MANAGER * GetActionManager()
Definition: tool_manager.h:197
void SetEnvironment(EDA_ITEM *aModel, KIGFX::VIEW *aView, KIGFX::VIEW_CONTROLS *aViewControls, APP_SETTINGS_BASE *aSettings, TOOLS_HOLDER *aFrame)
Set the work environment (model, view, view controls and the parent window).
TOOL_STATE * m_activeState
Definition: tool_manager.h:586
std::vector< TOOL_BASE * > TOOL_VEC
Definition: tool_manager.h:67
Base abstract interface for all kinds of tools.
Definition: tool_base.h:66
Represent a single user action.
Definition: tool_action.h:49
void VetoContextMenuMouseWarp()
Disable mouse warping after the current context menu is closed.
Definition: tool_manager.h:428
A base class for most all the KiCad significant classes used in schematics and boards.
Definition: eda_item.h:149
RESET_REASON
Determine the reason of reset for a tool.
Definition: tool_base.h:78
void InitTools()
Initializes all registered tools.
VECTOR2D GetMousePosition()
bool IsToolActive(TOOL_ID aId) const
Return true if a tool with given id is active (executing)
Hold a (potentially large) number of VIEW_ITEMs and renders them on a graphics device provided by the...
Definition: view.h:67
void ClearTransitions(TOOL_BASE *aTool)
Clear the state transition map for a tool.
ID_LIST m_activeTools
Instance of ACTION_MANAGER that handles TOOL_ACTIONs.
Definition: tool_manager.h:557
bool RunAction(const std::string &aActionName, bool aNow=false)
Definition: tool_manager.h:148
VECTOR2D GetMenuCursorPos()
Definition: tool_manager.h:446
std::list< TOOL_ID > ID_LIST
Definition: tool_manager.h:66
void PostEvent(const TOOL_EVENT &aEvent)
Put an event to the event queue to be processed at the end of event processing cycle.
Definition: tool_manager.h:267
TOOL_STATE_MAP m_toolState
Index of the registered tools current states, associated by tools' names.
Definition: tool_manager.h:545
void ScheduleContextMenu(TOOL_BASE *aTool, ACTION_MENU *aMenu, CONTEXT_MENU_TRIGGER aTrigger)
Set behavior of the tool's context popup menu.
void saveViewControls(TOOL_STATE *aState)
Save the #VIEW_CONTROLS settings to the tool state object.
bool RunAction(const TOOL_ACTION &aAction, bool aNow=false, T aParam=NULL)
Run the specified action.
Definition: tool_manager.h:167
APP_SETTINGS_BASE * m_settings
Queue that stores events to be processed at the end of the event processing cycle.
Definition: tool_manager.h:569
bool invokeTool(TOOL_BASE *aTool)
Invoke a tool by sending a proper event (in contrary to runTool, which makes the tool run for real).
APP_SETTINGS_BASE * GetSettings() const
Definition: tool_manager.h:298
void CancelTool()
Send a cancel event to the tool currently at the top of the tool stack.
void RegisterTool(TOOL_BASE *aTool)
Add a tool to the manager set and sets it up.
bool dispatchInternal(const TOOL_EVENT &aEvent)
Passe an event at first to the active tools, then to all others.
std::pair< TOOL_EVENT_LIST, TOOL_STATE_FUNC > TRANSITION
Definition: tool_manager.h:452
std::map< const char *, TOOL_BASE * > m_toolTypes
Stack of the active tools.
Definition: tool_manager.h:554