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 <tool/tool_event.h>
38 #include <view/view_controls.h>
39 
40 class TOOLS_HOLDER;
41 class TOOL_ACTION;
42 class TOOL_BASE;
43 class ACTION_MANAGER;
44 class ACTION_MENU;
45 class APP_SETTINGS_BASE;
46 
47 
55 {
56 private:
57  struct TOOL_STATE;
58 
59 public:
60  TOOL_MANAGER();
61 
62  ~TOOL_MANAGER();
63 
64  // Helper typedefs
65  typedef std::map<TOOL_BASE*, TOOL_STATE*> TOOL_STATE_MAP;
66  typedef std::map<std::string, TOOL_STATE*> NAME_STATE_MAP;
67  typedef std::map<TOOL_ID, TOOL_STATE*> ID_STATE_MAP;
68  typedef std::list<TOOL_ID> ID_LIST;
69  typedef std::vector<TOOL_BASE*> TOOL_VEC;
70 
74  static TOOL_ID MakeToolId( const std::string& aToolName );
75 
82  void RegisterTool( TOOL_BASE* aTool );
83 
90  bool InvokeTool( TOOL_ID aToolId );
91 
98  bool InvokeTool( const std::string& aToolName );
99 
104  void ShutdownAllTools();
105 
112  void ShutdownTool( TOOL_BASE* aTool );
113 
120  void ShutdownTool( TOOL_ID aToolId );
121 
128  void ShutdownTool( const std::string& aToolName );
129 
142  template<typename T>
143  bool RunAction( const std::string& aActionName, bool aNow = false, T aParam = NULL )
144  {
145  return RunAction( aActionName, aNow, reinterpret_cast<void*>( aParam ) );
146  }
147 
148  bool RunAction( const std::string& aActionName, bool aNow, void* aParam );
149 
150  bool RunAction( const std::string& aActionName, bool aNow = false )
151  {
152  return RunAction( aActionName, aNow, (void*) NULL );
153  }
154 
168  template <typename T>
169  bool RunAction( const TOOL_ACTION& aAction, bool aNow = false, T aParam = NULL )
170  {
171  return RunAction( aAction, aNow, reinterpret_cast<void*>( aParam ) );
172  }
173 
174  bool RunAction( const TOOL_ACTION& aAction, bool aNow, void* aParam );
175 
176  bool RunAction( const TOOL_ACTION& aAction, bool aNow = false )
177  {
178  return RunAction( aAction, aNow, (void*) NULL );
179  }
180 
181  const std::map<std::string, TOOL_ACTION*>& GetActions() const;
182 
186  void CancelTool();
187 
194  void PrimeTool( const VECTOR2D& aPosition );
195 
197  int GetHotKey( const TOOL_ACTION& aAction ) const;
198 
200 
207  TOOL_BASE* FindTool( int aId ) const;
208 
215  TOOL_BASE* FindTool( const std::string& aName ) const;
216 
217  /*
218  * Return the tool of given type or nullptr if there is no such tool registered.
219  */
220  template<typename T>
221  T* GetTool()
222  {
223  std::map<const char*, TOOL_BASE*>::iterator tool = m_toolTypes.find( typeid( T ).name() );
224 
225  if( tool != m_toolTypes.end() )
226  return static_cast<T*>( tool->second );
227 
228  return nullptr;
229  }
230 
234  void DeactivateTool();
235 
236 
240  bool IsToolActive( TOOL_ID aId ) const;
241 
242 
246  void ResetTools( TOOL_BASE::RESET_REASON aReason );
247 
254  void InitTools();
255 
262  bool ProcessEvent( const TOOL_EVENT& aEvent );
263 
269  void PostEvent( const TOOL_EVENT& aEvent );
270 
276  void SetEnvironment( EDA_ITEM* aModel, KIGFX::VIEW* aView,
277  KIGFX::VIEW_CONTROLS* aViewControls, APP_SETTINGS_BASE* aSettings,
278  TOOLS_HOLDER* aFrame );
279 
280  /*
281  * Accessors for the environment objects (view, model, etc.)
282  */
283  KIGFX::VIEW* GetView() const { return m_view; }
284 
286 
287  VECTOR2D GetMousePosition() const;
288  VECTOR2D GetCursorPosition() const;
289 
290  EDA_ITEM* GetModel() const { return m_model; }
291 
293 
294  TOOLS_HOLDER* GetToolHolder() const { return m_frame; }
295 
302  inline int GetCurrentToolId() const
303  {
304  return m_activeTools.empty() ? -1 : m_activeTools.front();
305  }
306 
313  inline TOOL_BASE* GetCurrentTool() const
314  {
315  return FindTool( GetCurrentToolId() );
316  }
317 
323  {
324  auto it = m_toolIdIndex.find( GetCurrentToolId() );
325  return ( it != m_toolIdIndex.end() ) ? it->second : nullptr;
326  }
327 
338  int GetPriority( int aToolId ) const;
339 
346  void ScheduleNextState( TOOL_BASE* aTool, TOOL_STATE_FUNC& aHandler,
347  const TOOL_EVENT_LIST& aConditions );
348 
354  void ClearTransitions( TOOL_BASE* aTool );
355 
356  void RunMainStack( TOOL_BASE* aTool, std::function<void()> aFunc );
357 
361  void UpdateUI( const TOOL_EVENT& aEvent );
362 
368  TOOL_EVENT* ScheduleWait( TOOL_BASE* aTool, const TOOL_EVENT_LIST& aConditions );
369 
381  void ScheduleContextMenu( TOOL_BASE* aTool, ACTION_MENU* aMenu, CONTEXT_MENU_TRIGGER aTrigger );
382 
390  bool SaveClipboard( const std::string& aTextUTF8 );
391 
400  std::string GetClipboardUTF8() const;
401 
406  const KIGFX::VC_SETTINGS& GetCurrentToolVC() const;
407 
411  bool IsContextMenuActive() const
412  {
413  return m_menuActive;
414  }
415 
423  {
425  }
426 
430  void DispatchContextMenu( const TOOL_EVENT& aEvent );
431 
438  bool DispatchHotKey( const TOOL_EVENT& aEvent );
439 
441  {
442  return m_menuCursor;
443  }
444 
445 private:
446  typedef std::pair<TOOL_EVENT_LIST, TOOL_STATE_FUNC> TRANSITION;
447 
451  bool dispatchInternal( TOOL_EVENT& aEvent );
452 
459  bool dispatchActivation( const TOOL_EVENT& aEvent );
460 
467  bool invokeTool( TOOL_BASE* aTool );
468 
477  bool runTool( TOOL_BASE* aTool );
478 
487  ID_LIST::iterator finishTool( TOOL_STATE* aState );
488 
495  bool isRegistered( TOOL_BASE* aTool ) const
496  {
497  return m_toolState.count( aTool ) > 0;
498  }
499 
506  bool isActive( TOOL_BASE* aTool ) const;
507 
513  void saveViewControls( TOOL_STATE* aState );
514 
518  void applyViewControls( const TOOL_STATE* aState );
519 
525  bool processEvent( const TOOL_EVENT& aEvent );
526 
533  void setActiveState( TOOL_STATE* aState );
534 
537 
540 
543 
546 
548  std::map<const char*, TOOL_BASE*> m_toolTypes;
549 
552 
555 
557  std::map<TOOL_ID, OPT<VECTOR2D>> m_cursorSettings;
558 
564 
566  std::list<TOOL_EVENT> m_eventQueue;
567 
570 
572 
575 
578 
581 };
582 
583 #endif // __TOOL_MANAGER_H
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:574
void DispatchContextMenu(const TOOL_EVENT &aEvent)
Handle context menu related events.
VECTOR2D m_menuCursor
Definition: tool_manager.h:569
KIGFX::VIEW * GetView() const
Definition: tool_manager.h:283
void UpdateUI(const TOOL_EVENT &aEvent)
Update the status bar and synchronizes toolbars.
ACTION_MANAGER * m_actionMgr
Original cursor position, if overridden by the context menu handler.
Definition: tool_manager.h:554
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:536
Defines the structure of a menu based on ACTIONs.
Definition: action_menu.h:48
ID_STATE_MAP m_toolIdIndex
Index of the registered tools to easily lookup by their type.
Definition: tool_manager.h:545
void ScheduleNextState(TOOL_BASE *aTool, TOOL_STATE_FUNC &aHandler, const TOOL_EVENT_LIST &aConditions)
Define a state transition.
bool dispatchInternal(TOOL_EVENT &aEvent)
Pass an event at first to the active tools, then to all others.
bool RunAction(const TOOL_ACTION &aAction, bool aNow=false)
Definition: tool_manager.h:176
std::map< TOOL_ID, TOOL_STATE * > ID_STATE_MAP
Definition: tool_manager.h:67
VECTOR2D GetMousePosition() const
std::map< TOOL_ID, OPT< VECTOR2D > > m_cursorSettings
Definition: tool_manager.h:557
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:66
bool RunAction(const std::string &aActionName, bool aNow=false, T aParam=NULL)
Run the specified action.
Definition: tool_manager.h:143
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.
TOOLS_HOLDER * m_frame
Definition: tool_manager.h:562
EDA_ITEM * GetModel() const
Definition: tool_manager.h:290
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:65
EDA_ITEM * m_model
Definition: tool_manager.h:559
Master controller class:
Definition: tool_manager.h:54
NAME_STATE_MAP m_toolNameIndex
Index of the registered tools current states, associated by tools' ID numbers.
Definition: tool_manager.h:542
const std::map< std::string, TOOL_ACTION * > & GetActions() const
int TOOL_ID
Unique identifier for tools.
Definition: tool_base.h:56
A list of TOOL_EVENTs, with overloaded || operators allowing for concatenating TOOL_EVENTs with littl...
Definition: tool_event.h:549
VECTOR2D GetCursorPosition() const
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:577
#define NULL
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:142
Generic, UI-independent tool event.
Definition: tool_event.h:152
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 IsContextMenuActive() const
True while processing a context menu.
Definition: tool_manager.h:411
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:561
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:313
std::function< int(const TOOL_EVENT &)> TOOL_STATE_FUNC
Definition: tool_base.h:58
TOOL_STATE * GetCurrentToolState() const
Return the #TOOL_STATE object representing the state of the active tool.
Definition: tool_manager.h:322
KIGFX::VIEW * m_view
Definition: tool_manager.h:560
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:302
void RunMainStack(TOOL_BASE *aTool, std::function< void()> aFunc)
bool isActive(TOOL_BASE *aTool) const
Return information about a tool activation status.
bool m_warpMouseAfterContextMenu
Flag indicating whether a context menu is currently displayed.
Definition: tool_manager.h:571
bool isRegistered(TOOL_BASE *aTool) const
Return information about a tool registration status.
Definition: tool_manager.h:495
TOOLS_HOLDER * GetToolHolder() const
Definition: tool_manager.h:294
KIGFX::VIEW_CONTROLS * GetViewControls() const
Definition: tool_manager.h:285
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:566
const char * name
Definition: DXF_plotter.cpp:59
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:580
std::vector< TOOL_BASE * > TOOL_VEC
Definition: tool_manager.h:69
Base abstract interface for all kinds of tools.
Definition: tool_base.h:65
Represent a single user action.
Definition: tool_action.h:67
void VetoContextMenuMouseWarp()
Disable mouse warping after the current context menu is closed.
Definition: tool_manager.h:422
A base class for most all the KiCad significant classes used in schematics and boards.
Definition: eda_item.h:100
RESET_REASON
Determine the reason of reset for a tool.
Definition: tool_base.h:77
ACTION_MANAGER * GetActionManager() const
Definition: tool_manager.h:199
void applyViewControls(const TOOL_STATE *aState)
Apply #VIEW_CONTROLS settings stored in a #TOOL_STATE object.
void InitTools()
Initializes all registered tools.
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:551
bool RunAction(const std::string &aActionName, bool aNow=false)
Definition: tool_manager.h:150
VECTOR2D GetMenuCursorPos() const
Definition: tool_manager.h:440
std::list< TOOL_ID > ID_LIST
Definition: tool_manager.h:68
void PostEvent(const TOOL_EVENT &aEvent)
Put an event to the event queue to be processed at the end of event processing cycle.
TOOL_STATE_MAP m_toolState
Index of the registered tools current states, associated by tools' names.
Definition: tool_manager.h:539
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:169
APP_SETTINGS_BASE * m_settings
Queue that stores events to be processed at the end of the event processing cycle.
Definition: tool_manager.h:563
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:292
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.
std::pair< TOOL_EVENT_LIST, TOOL_STATE_FUNC > TRANSITION
Definition: tool_manager.h:446
int GetHotKey(const TOOL_ACTION &aAction) const
std::map< const char *, TOOL_BASE * > m_toolTypes
Stack of the active tools.
Definition: tool_manager.h:548