kicad/include/tool/tool_manager.h

/*
 * This program source code file is part of KiCad, a free EDA CAD application.
 *
 * Copyright (C) 2013 CERN
 * @author Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, you may find one here:
 * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
 * or you may search the http://www.gnu.org website for the version 2 license,
 * or you may write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
 */

#ifndef __TOOL_MANAGER_H
#define __TOOL_MANAGER_H

#include <cstdio>
#include <map>
#include <vector>
#include <deque>

#include <boost/unordered_map.hpp>

#include <math/vector2d.h>

#include <tool/tool_event.h>
#include <tool/tool_base.h>

class TOOL_BASE;
class CONTEXT_MENU;
class wxWindow;

/**
 * Class TOOL_MANAGER.
 * Master controller class:
 * - registers editing tools
 * - pumps UI events to tools requesting them
 * - manages tool state machines (transitions and wait requests)
 */
class TOOL_MANAGER
{
	public:
		
		TOOL_MANAGER();
		~TOOL_MANAGER();

		/**
		 * Generates an unique ID from for a tool with given name.
		 */
		static TOOL_ID MakeToolId( const std::string& aToolName );

		/**
    	 * Function RegisterTool()
	     * Adds a tool to the manager set and sets it up. Called once for
	     * each tool during application initialization.
     	 * @param aTool: tool to be added. Ownership is transferred.
     	 */
		void RegisterTool( TOOL_BASE* aTool );

		/**
		 * Function InvokeTool()
		 * Calls a tool by sending a tool activation event to tool of given ID or name.
		 * An user-defined parameter object can be also passed 
		 */	
		void InvokeTool( TOOL_ID aToolId );
		void InvokeTool( const std::string& name );

		template <class Parameters>
			void InvokeTool( const std::string& name, const Parameters& aToolParams );


		/**
		 * Function FindTool()
		 * Searches for a tool with given name or ID 
		 */
		TOOL_BASE *FindTool( int aId );
		TOOL_BASE *FindTool( const std::string& aName );

		/**
		 * Resets the state of a given tool by clearing its wait and
		 * transition lists and calling tool's internal Reset() method.
		 */
		void ResetTool( TOOL_BASE *aTool );

		/**
		 * Takes an event from the TOOL_DISPATCHER and propagates it to 
		 * tools that requested events of matching type(s)
		 */
		bool ProcessEvent( TOOL_EVENT& aEvent );
		
		/**
		 * Sets the work environment (model, view, view controls and the parent window).
		 * These are made available to the tool. Called by the parent frame (PCB_EDIT_FRAME)
		 * when the board is set up
		 */
		void SetEnvironment( EDA_ITEM* aModel, KiGfx::VIEW* aView,
		                     KiGfx::VIEW_CONTROLS* aViewControls, wxWindow* aFrame );

		/* Accessors for the environment objects (view, model, etc.) */
		KiGfx::VIEW* GetView()
		{
			return m_view;
		}

		KiGfx::VIEW_CONTROLS* GetViewControls()
		{
			return m_viewControls;
		}

		EDA_ITEM* GetModel()
		{
			return m_model;
		}

		wxWindow* GetEditFrame()
		{
			return m_editFrame;
		}

		/**
		 * Defines a state transition - the events that cause a given handler method in the tool 
		 * to be called. Called by TOOL_INTERACTIVE::Go(). May be called from a coroutine context.
		 */
		void ScheduleNextState( TOOL_BASE* aTool, TOOL_STATE_FUNC& aHandler,
		                        const TOOL_EVENT_LIST& aConditions );
		
		/**
		 * Pauses execution of a given tool until one or more events matching aConditions arrives.
		 * The pause/resume operation is done through COROUTINE object.
		 * Called only from coroutines.
		 */
		boost::optional<TOOL_EVENT> ScheduleWait( TOOL_BASE* aTool,
		                                          const TOOL_EVENT_LIST& aConditions );
		
		/**
		 * Sets behaviour of the tool's context popup menu. 
		 * @param aMenu - the menu structure, defined by the tool
		 * @param aTrigger - when the menu is activated: 
		 * CMENU_NOW: opens the menu right now
		 * CMENU_BUTTON: opens the menu when RMB is pressed
		 * CMENU_OFF: menu is disabled.
		 * May be called from a coroutine context.
		 */
		void ScheduleContextMenu( TOOL_BASE* aTool, CONTEXT_MENU* aMenu,
		                          TOOL_ContextMenuTrigger aTrigger );

	private:
		void dispatchInternal ( TOOL_EVENT& aEvent );

		struct ToolState;
		typedef std::pair<TOOL_EVENT_LIST, TOOL_STATE_FUNC> Transition;

		std::map<TOOL_BASE*, ToolState*> m_toolState;
		std::map<std::string, ToolState*> m_toolNameIndex;
		std::map<TOOL_ID, ToolState*> m_toolIdIndex;

		EDA_ITEM* m_model;
		KiGfx::VIEW* m_view;
		KiGfx::VIEW_CONTROLS* m_viewControls;
		wxWindow* m_editFrame;

		ToolState* m_currentTool;
};

#endif