tool_event.h

Go to the documentation of this file.

/*
 * This program source code file is part of KiCad, a free EDA CAD application.
 *
 * Copyright (C) 2013 CERN
 * Copyright (C) 2020 KiCad Developers, see AUTHORS.txt for contributors.
 *
 * @author Tomasz Wlostowski <[email protected]>
 *
 * 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_EVENT_H
#define __TOOL_EVENT_H

#include <cstdio>
#include <deque>
#include <iterator>

#include <math/vector2d.h>
#include <core/optional.h>

#include <tool/tool_action.h>

class TOOL_ACTION;
class TOOL_MANAGER;
class TOOL_BASE;

enum TOOL_EVENT_CATEGORY
{
 TC_NONE = 0x00,
 TC_MOUSE = 0x01,
 TC_KEYBOARD = 0x02,
 TC_COMMAND = 0x04,
 TC_MESSAGE = 0x08,
 TC_VIEW = 0x10,
 TC_ANY = 0xffffffff
};

enum TOOL_ACTIONS
{
 // UI input events
 TA_NONE = 0x0000,
 TA_MOUSE_CLICK = 0x0001,
 TA_MOUSE_DBLCLICK = 0x0002,
 TA_MOUSE_UP = 0x0004,
 TA_MOUSE_DOWN = 0x0008,
 TA_MOUSE_DRAG = 0x0010,
 TA_MOUSE_MOTION = 0x0020,
 TA_MOUSE_WHEEL = 0x0040,
 TA_MOUSE = 0x007f,

 TA_KEY_PRESSED = 0x0080,
 TA_KEYBOARD = TA_KEY_PRESSED,

 // View related events
 TA_VIEW_REFRESH = 0x0100,
 TA_VIEW_ZOOM = 0x0200,
 TA_VIEW_PAN = 0x0400,
 TA_VIEW_DIRTY = 0x0800,
 TA_VIEW = 0x0f00,

 TA_CHANGE_LAYER = 0x1000,

 // Tool cancel event. Issued automagically when the user hits escape or selects End Tool from
 // the context menu.
 TA_CANCEL_TOOL = 0x2000,

 // Context menu update. Issued whenever context menu is open and the user hovers the mouse
 // over one of choices. Used in dynamic highlighting in disambiguation menu
 TA_CHOICE_MENU_UPDATE = 0x4000,

 // Context menu choice. Sent if the user picked something from the context menu or
 // closed it without selecting anything.
 TA_CHOICE_MENU_CHOICE = 0x8000,

 // Context menu is closed, no matter whether anything has been chosen or not.
 TA_CHOICE_MENU_CLOSED = 0x10000,

 TA_CHOICE_MENU = TA_CHOICE_MENU_UPDATE | TA_CHOICE_MENU_CHOICE | TA_CHOICE_MENU_CLOSED,

 // This event is sent *before* undo/redo command is performed.
 TA_UNDO_REDO_PRE = 0x20000,

 // This event is sent *after* undo/redo command is performed.
 TA_UNDO_REDO_POST = 0x40000,

 // Tool action (allows one to control tools).
 TA_ACTION = 0x80000,

 // Tool activation event.
 TA_ACTIVATE = 0x100000,

 // Tool re-activation event for tools already on the stack
 TA_REACTIVATE = 0x200000,

 // Model has changed (partial update).
 TA_MODEL_CHANGE = 0x400000,

 // Tool priming event (a special mouse click)
 TA_PRIME = 0x800001,

 TA_ANY = 0xffffffff
};

enum TOOL_MOUSE_BUTTONS
{
 BUT_NONE = 0x0,
 BUT_LEFT = 0x1,
 BUT_RIGHT = 0x2,
 BUT_MIDDLE = 0x4,
 BUT_BUTTON_MASK = BUT_LEFT | BUT_RIGHT | BUT_MIDDLE,
 BUT_ANY = 0xffffffff
};

enum TOOL_MODIFIERS
{
 MD_SHIFT = 0x1000,
 MD_CTRL = 0x2000,
 MD_ALT = 0x4000,
 MD_MODIFIER_MASK = MD_SHIFT | MD_CTRL | MD_ALT,
};

enum CONTEXT_MENU_TRIGGER
{
 CMENU_BUTTON = 0, // On the right button
 CMENU_NOW, // Right now (after TOOL_INTERACTIVE::SetContextMenu)
 CMENU_OFF // Never
};

class TOOL_EVENT
{
public:
 const std::string Format() const;

 TOOL_EVENT( TOOL_EVENT_CATEGORY aCategory = TC_NONE, TOOL_ACTIONS aAction = TA_NONE,
 TOOL_ACTION_SCOPE aScope = AS_GLOBAL, void* aParameter = nullptr ) :
 m_category( aCategory ),
 m_actions( aAction ),
 m_scope( aScope ),
 m_mouseButtons( 0 ),
 m_keyCode( 0 ),
 m_modifiers( 0 ),
 m_param( aParameter ),
 m_firstResponder( nullptr )
 {
 init();
 }

 TOOL_EVENT( TOOL_EVENT_CATEGORY aCategory, TOOL_ACTIONS aAction, int aExtraParam,
 TOOL_ACTION_SCOPE aScope = AS_GLOBAL, void* aParameter = nullptr ) :
 m_category( aCategory ),
 m_actions( aAction ),
 m_scope( aScope ),
 m_mouseButtons( 0 ),
 m_keyCode( 0 ),
 m_modifiers( 0 ),
 m_param( aParameter ),
 m_firstResponder( nullptr )
 {
 if( aCategory == TC_MOUSE )
 {
 setMouseButtons( aExtraParam & BUT_BUTTON_MASK );
 }
 else if( aCategory == TC_KEYBOARD )
 {
 m_keyCode = aExtraParam & ~MD_MODIFIER_MASK; // Filter out modifiers
 }
 else if( aCategory == TC_COMMAND )
 {
 m_commandId = aExtraParam;
 }

 if( aCategory & ( TC_MOUSE | TC_KEYBOARD ) )
 {
 m_modifiers = aExtraParam & MD_MODIFIER_MASK;
 }

 init();
 }

 TOOL_EVENT( TOOL_EVENT_CATEGORY aCategory, TOOL_ACTIONS aAction,
 const std::string& aExtraParam, TOOL_ACTION_SCOPE aScope = AS_GLOBAL,
 void* aParameter = nullptr ) :
 m_category( aCategory ),
 m_actions( aAction ),
 m_scope( aScope ),
 m_mouseButtons( 0 ),
 m_keyCode( 0 ),
 m_modifiers( 0 ),
 m_param( aParameter ),
 m_firstResponder( nullptr )
 {
 if( aCategory == TC_COMMAND || aCategory == TC_MESSAGE )
 m_commandStr = aExtraParam;

 init();
 }

 TOOL_EVENT_CATEGORY Category() const { return m_category; }

 TOOL_ACTIONS Action() const { return m_actions; }

 bool PassEvent() const { return m_passEvent; }
 void SetPassEvent( bool aPass = true ) { m_passEvent = aPass; }

 bool HasPosition() const { return m_hasPosition; }
 void SetHasPosition( bool aHasPosition ) { m_hasPosition = aHasPosition; }

 bool ForceImmediate() const { return m_forceImmediate; }
 void SetForceImmediate( bool aForceImmediate = true ) { m_forceImmediate = aForceImmediate; }

 TOOL_BASE* FirstResponder() const { return m_firstResponder; }
 void SetFirstResponder( TOOL_BASE* aTool ) { m_firstResponder = aTool; }

 bool IsReactivate() const { return m_reactivate; }
 void SetReactivate( bool aReactivate = true ) { m_reactivate = aReactivate; }

 const VECTOR2D Delta() const
 {
 return returnCheckedPosition( m_mouseDelta );
 }

 const VECTOR2D Position() const
 {
 return returnCheckedPosition( m_mousePos );
 }

 const VECTOR2D DragOrigin() const
 {
 return returnCheckedPosition( m_mouseDragOrigin );
 }

 int Buttons() const
 {
 assert( m_category == TC_MOUSE ); // this should be used only with mouse events
 return m_mouseButtons;
 }

 bool IsClick( int aButtonMask = BUT_ANY ) const;

 bool IsDblClick( int aButtonMask = BUT_ANY ) const;

 bool IsDrag( int aButtonMask = BUT_ANY ) const
 {
 return m_actions == TA_MOUSE_DRAG && ( m_mouseButtons & aButtonMask ) == m_mouseButtons;
 }

 bool IsMouseDown( int aButtonMask = BUT_ANY ) const
 {
 return m_actions == TA_MOUSE_DOWN && ( m_mouseButtons & aButtonMask ) == m_mouseButtons;
 }

 bool IsMouseUp( int aButtonMask = BUT_ANY ) const
 {
 return m_actions == TA_MOUSE_UP && ( m_mouseButtons & aButtonMask ) == m_mouseButtons;
 }

 bool IsMotion() const
 {
 return m_actions == TA_MOUSE_MOTION;
 }

 bool IsMouseAction() const
 {
 return ( m_actions & TA_MOUSE );
 }

 bool IsCancel() const
 {
 return m_actions == TA_CANCEL_TOOL;
 }

 bool IsActivate() const
 {
 return m_actions == TA_ACTIVATE;
 }

 bool IsUndoRedo() const
 {
 return m_actions & ( TA_UNDO_REDO_PRE | TA_UNDO_REDO_POST );
 }

 bool IsChoiceMenu() const
 {
 return m_actions & TA_CHOICE_MENU;
 }

 bool IsPrime() const
 {
 return m_actions == TA_PRIME;
 }

 int Modifier( int aMask = MD_MODIFIER_MASK ) const
 {
 return m_modifiers & aMask;
 }

 bool DisableGridSnapping() const
 {
 return Modifier( MD_CTRL );
 }

 int KeyCode() const
 {
 return m_keyCode;
 }

 bool IsKeyPressed() const
 {
 return m_actions == TA_KEY_PRESSED;
 }

 bool Matches( const TOOL_EVENT& aEvent ) const
 {
 if( !( m_category & aEvent.m_category ) )
 return false;

 if( m_category == TC_COMMAND || m_category == TC_MESSAGE )
 {
 if( (bool) m_commandStr && (bool) aEvent.m_commandStr )
 return *m_commandStr == *aEvent.m_commandStr;

 if( (bool) m_commandId && (bool) aEvent.m_commandId )
 return *m_commandId == *aEvent.m_commandId;
 }

 // BUGFIX: TA_ANY should match EVERYTHING, even TA_NONE (for TC_MESSAGE)
 if( m_actions == TA_ANY && aEvent.m_actions == TA_NONE && aEvent.m_category == TC_MESSAGE )
 return true;

 // BUGFIX: This check must happen after the TC_COMMAND check because otherwise events of
 // the form { TC_COMMAND, TA_NONE } will be incorrectly skipped
 if( !( m_actions & aEvent.m_actions ) )
 return false;

 return true;
 }

 bool IsAction( const TOOL_ACTION* aAction ) const;

 bool IsCancelInteractive() const;

 bool IsSelectionEvent() const;

 bool IsPointEditor() const;

 bool IsMoveTool() const;

 bool IsSimulator() const;

 template<typename T>
 inline T Parameter() const
 {
 // Exhibit #798 on why I love to hate C++
 // - reinterpret_cast needs to be used for pointers
 // - static_cast must be used for enums
 // - templates can't usefully distinguish between pointer and non-pointer types
 // Fortunately good old C's cast can be a reinterpret_cast or a static_cast, and
 // C99 gave us intptr_t which is guaranteed to be round-trippable with a pointer.
 return (T) reinterpret_cast<intptr_t>( m_param );
 }

 template<typename T>
 void SetParameter(T aParam)
 {
 m_param = reinterpret_cast<void*>( aParam );
 }

 OPT<int> GetCommandId() const
 {
 return m_commandId;
 }

 OPT<std::string> GetCommandStr() const
 {
 return m_commandStr;
 }

 void SetMousePosition( const VECTOR2D& aP )
 {
 m_mousePos = aP;
 }

private:
 friend class TOOL_DISPATCHER;

 void init();

 void setMouseDragOrigin( const VECTOR2D& aP )
 {
 m_mouseDragOrigin = aP;
 }

 void setMouseDelta( const VECTOR2D& aP )
 {
 m_mouseDelta = aP;
 }

 void setMouseButtons( int aButtons )
 {
 assert( ( aButtons & ~BUT_BUTTON_MASK ) == 0 );
 m_mouseButtons = aButtons;
 }

 void setModifiers( int aMods )
 {
 assert( ( aMods & ~MD_MODIFIER_MASK ) == 0 );
 m_modifiers = aMods;
 }

 VECTOR2D returnCheckedPosition( const VECTOR2D& aPos ) const;

 TOOL_EVENT_CATEGORY m_category;
 TOOL_ACTIONS m_actions;
 TOOL_ACTION_SCOPE m_scope;
 bool m_passEvent;
 bool m_hasPosition;
 bool m_forceImmediate;

 bool m_reactivate;

 VECTOR2D m_mouseDelta;

 VECTOR2D m_mousePos;

 VECTOR2D m_mouseDragOrigin;

 int m_mouseButtons;

 int m_keyCode;

 int m_modifiers;

 void* m_param;

 TOOL_BASE* m_firstResponder;

 OPT<int> m_commandId;
 OPT<std::string> m_commandStr;
};

typedef OPT<TOOL_EVENT> OPT_TOOL_EVENT;

class TOOL_EVENT_LIST
{
public:
 typedef TOOL_EVENT value_type;
 typedef std::deque<TOOL_EVENT>::iterator iterator;
 typedef std::deque<TOOL_EVENT>::const_iterator const_iterator;

 TOOL_EVENT_LIST()
 {}

 TOOL_EVENT_LIST( const TOOL_EVENT& aSingleEvent )
 {
 m_events.push_back( aSingleEvent );
 }

 TOOL_EVENT_LIST( const TOOL_EVENT_LIST& aEventList )
 {
 m_events.clear();

 for( const TOOL_EVENT& event : aEventList.m_events )
 m_events.push_back( event );
 }

 const std::string Format() const;

 OPT<const TOOL_EVENT&> Matches( const TOOL_EVENT& aEvent ) const
 {
 for( const TOOL_EVENT& event : m_events )
 {
 if( event.Matches( aEvent ) )
 return event;
 }

 return OPT<const TOOL_EVENT&>();
 }

 void Add( const TOOL_EVENT& aEvent )
 {
 m_events.push_back( aEvent );
 }

 iterator begin()
 {
 return m_events.begin();
 }

 iterator end()
 {
 return m_events.end();
 }

 const_iterator cbegin() const
 {
 return m_events.begin();
 }

 const_iterator cend() const
 {
 return m_events.end();
 }

 int size() const
 {
 return m_events.size();
 }

 void clear()
 {
 m_events.clear();
 }

 TOOL_EVENT_LIST& operator=( const TOOL_EVENT_LIST& aEventList )
 {
 m_events.clear();

 for( const TOOL_EVENT& event : aEventList.m_events )
 m_events.push_back( event );

 return *this;
 }

 TOOL_EVENT_LIST& operator=( const TOOL_EVENT& aEvent )
 {
 m_events.clear();
 m_events.push_back( aEvent );
 return *this;
 }

 TOOL_EVENT_LIST& operator||( const TOOL_EVENT& aEvent )
 {
 Add( aEvent );
 return *this;
 }

 TOOL_EVENT_LIST& operator||( const TOOL_EVENT_LIST& aEvent )
 {
 std::copy( aEvent.m_events.begin(), aEvent.m_events.end(), std::back_inserter( m_events ) );
 return *this;
 }

private:
 std::deque<TOOL_EVENT> m_events;
};


inline const TOOL_EVENT_LIST operator||( const TOOL_EVENT& aEventA, const TOOL_EVENT& aEventB )
{
 TOOL_EVENT_LIST l;

 l.Add( aEventA );
 l.Add( aEventB );

 return l;
}


inline const TOOL_EVENT_LIST operator||( const TOOL_EVENT& aEvent,
 const TOOL_EVENT_LIST& aEventList )
{
 TOOL_EVENT_LIST l( aEventList );

 l.Add( aEvent );
 return l;
}


#endif