KiCad PCB EDA Suite
tool_event.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  * @author Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
6  *
7  * This program is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU General Public License
9  * as published by the Free Software Foundation; either version 2
10  * of the License, or (at your option) any later version.
11  *
12  * This program is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15  * GNU General Public License for more details.
16  *
17  * You should have received a copy of the GNU General Public License
18  * along with this program; if not, you may find one here:
19  * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
20  * or you may search the http://www.gnu.org website for the version 2 license,
21  * or you may write to the Free Software Foundation, Inc.,
22  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
23  */
24 
25 #ifndef __TOOL_EVENT_H
26 #define __TOOL_EVENT_H
27 
28 #include <cstdio>
29 #include <deque>
30 #include <iterator>
31 
32 #include <math/vector2d.h>
33 #include <core/optional.h>
34 
35 #ifdef WX_COMPATIBILITY
36 #include <wx/debug.h>
37 #else
38 #include <cassert>
39 #endif
40 
41 
42 class TOOL_ACTION;
43 class TOOL_MANAGER;
44 
50 {
51  TC_NONE = 0x00,
52  TC_MOUSE = 0x01,
53  TC_KEYBOARD = 0x02,
54  TC_COMMAND = 0x04,
55  TC_MESSAGE = 0x08,
56  TC_VIEW = 0x10,
57  TC_ANY = 0xffffffff
58 };
59 
61 {
62  // UI input events
63  TA_NONE = 0x0000,
64  TA_MOUSE_CLICK = 0x0001,
66  TA_MOUSE_UP = 0x0004,
67  TA_MOUSE_DOWN = 0x0008,
68  TA_MOUSE_DRAG = 0x0010,
69  TA_MOUSE_MOTION = 0x0020,
70  TA_MOUSE_WHEEL = 0x0040,
71  TA_MOUSE = 0x007f,
72 
73  TA_KEY_PRESSED = 0x0080,
75 
76  // View related events
77  TA_VIEW_REFRESH = 0x0100,
78  TA_VIEW_ZOOM = 0x0200,
79  TA_VIEW_PAN = 0x0400,
80  TA_VIEW_DIRTY = 0x0800,
81  TA_VIEW = 0x0f00,
82 
83  TA_CHANGE_LAYER = 0x1000,
84 
85  // Tool cancel event. Issued automagically when the user hits escape or selects End Tool from
86  // the context menu.
87  TA_CANCEL_TOOL = 0x2000,
88 
89  // Context menu update. Issued whenever context menu is open and the user hovers the mouse
90  // over one of choices. Used in dynamic highligting in disambiguation menu
92 
93  // Context menu choice. Sent if the user picked something from the context menu or
94  // closed it without selecting anything.
96 
97  // Context menu is closed, no matter whether anything has been chosen or not.
99 
101 
102  // This event is sent *before* undo/redo command is performed.
103  TA_UNDO_REDO_PRE = 0x20000,
104 
105  // This event is sent *after* undo/redo command is performed.
106  TA_UNDO_REDO_POST = 0x40000,
107 
108  // Tool action (allows one to control tools).
109  TA_ACTION = 0x80000,
110 
111  // Tool activation event.
112  TA_ACTIVATE = 0x100000,
113 
114  // Model has changed (partial update).
115  TA_MODEL_CHANGE = 0x200000,
116 
117  TA_ANY = 0xffffffff
118 };
119 
121 {
122  BUT_NONE = 0x0,
123  BUT_LEFT = 0x1,
124  BUT_RIGHT = 0x2,
125  BUT_MIDDLE = 0x4,
127  BUT_ANY = 0xffffffff
128 };
129 
131 {
132  MD_SHIFT = 0x1000,
133  MD_CTRL = 0x2000,
134  MD_ALT = 0x4000,
136 };
137 
140 {
144 };
145 
148 {
149  AF_NONE = 0,
152 };
153 
156 {
157  CMENU_BUTTON = 0, // On the right button
158  CMENU_NOW, // Right now (after TOOL_INTERACTIVE::SetContextMenu)
159  CMENU_OFF // Never
160 };
161 
168 {
169 public:
176  const std::string Format() const;
177 
179  TOOL_ACTION_SCOPE aScope = AS_GLOBAL, void* aParameter = NULL ) :
180  m_category( aCategory ),
181  m_actions( aAction ),
182  m_scope( aScope ),
183  m_mouseButtons( 0 ),
184  m_keyCode( 0 ),
185  m_modifiers( 0 ),
186  m_param( aParameter ) {}
187 
188  TOOL_EVENT( TOOL_EVENT_CATEGORY aCategory, TOOL_ACTIONS aAction, int aExtraParam,
189  TOOL_ACTION_SCOPE aScope = AS_GLOBAL, void* aParameter = NULL ) :
190  m_category( aCategory ),
191  m_actions( aAction ),
192  m_scope( aScope ),
193  m_mouseButtons( 0 ),
194  m_keyCode( 0 ),
195  m_modifiers( 0 ),
196  m_param( aParameter )
197  {
198  if( aCategory == TC_MOUSE )
199  {
200  setMouseButtons( aExtraParam & BUT_BUTTON_MASK );
201  }
202  else if( aCategory == TC_KEYBOARD )
203  {
204  m_keyCode = aExtraParam & ~MD_MODIFIER_MASK; // Filter out modifiers
205  }
206  else if( aCategory == TC_COMMAND )
207  {
208  m_commandId = aExtraParam;
209  }
210 
211  if( aCategory & ( TC_MOUSE | TC_KEYBOARD ) )
212  {
213  m_modifiers = aExtraParam & MD_MODIFIER_MASK;
214  }
215  }
216 
218  const std::string& aExtraParam, TOOL_ACTION_SCOPE aScope = AS_GLOBAL,
219  void* aParameter = NULL ) :
220  m_category( aCategory ),
221  m_actions( aAction ),
222  m_scope( aScope ),
223  m_mouseButtons( 0 ),
224  m_keyCode( 0 ),
225  m_modifiers( 0 ),
226  m_param( aParameter )
227  {
228  if( aCategory == TC_COMMAND || aCategory == TC_MESSAGE )
229  m_commandStr = aExtraParam;
230  }
231 
234  {
235  return m_category;
236  }
237 
240  {
241  return m_actions;
242  }
243 
245  bool HasPosition() const
246  {
247  return m_category == TC_MOUSE || m_category == TC_COMMAND;
248  }
249 
252  const VECTOR2D Delta() const
253  {
255  }
256 
258  const VECTOR2D Position() const
259  {
261  }
262 
264  const VECTOR2D DragOrigin() const
265  {
267  }
268 
270  int Buttons() const
271  {
272  assert( m_category == TC_MOUSE ); // this should be used only with mouse events
273  return m_mouseButtons;
274  }
275 
276  bool IsClick( int aButtonMask = BUT_ANY ) const;
277 
278  bool IsDblClick( int aButtonMask = BUT_ANY ) const;
279 
280  bool IsDrag( int aButtonMask = BUT_ANY ) const
281  {
282  return m_actions == TA_MOUSE_DRAG && ( m_mouseButtons & aButtonMask ) == aButtonMask;
283  }
284 
285  bool IsMouseUp( int aButtonMask = BUT_ANY ) const
286  {
287  return m_actions == TA_MOUSE_UP && ( m_mouseButtons & aButtonMask ) == aButtonMask;
288  }
289 
290  bool IsMotion() const
291  {
292  return m_actions == TA_MOUSE_MOTION;
293  }
294 
295  bool IsCancel() const
296  {
297  return m_actions == TA_CANCEL_TOOL;
298  }
299 
300  bool IsActivate() const
301  {
302  return m_actions == TA_ACTIVATE;
303  }
304 
305  bool IsUndoRedo() const
306  {
308  }
309 
310  bool IsMenu() const
311  {
312  return m_actions & TA_CONTEXT_MENU;
313  }
314 
316  int Modifier( int aMask = MD_MODIFIER_MASK ) const
317  {
318  return m_modifiers & aMask;
319  }
320 
321  int KeyCode() const
322  {
323  return m_keyCode;
324  }
325 
326  bool IsKeyPressed() const
327  {
328  return m_actions == TA_KEY_PRESSED;
329  }
330 
338  bool Matches( const TOOL_EVENT& aEvent ) const
339  {
340  if( !( m_category & aEvent.m_category ) )
341  return false;
342 
344  {
345  if( (bool) m_commandStr && (bool) aEvent.m_commandStr )
346  return *m_commandStr == *aEvent.m_commandStr;
347 
348  if( (bool) m_commandId && (bool) aEvent.m_commandId )
349  return *m_commandId == *aEvent.m_commandId;
350  }
351 
352  // BUGFIX: TA_ANY should match EVERYTHING, even TA_NONE (for TC_MESSAGE)
353  if( m_actions == TA_ANY && aEvent.m_actions == TA_NONE && aEvent.m_category == TC_MESSAGE )
354  return true;
355 
356  // BUGFIX: This check must happen after the TC_COMMAND check because otherwise events of
357  // the form { TC_COMMAND, TA_NONE } will be incorrectly skipped
358  if( !( m_actions & aEvent.m_actions ) )
359  return false;
360 
361  return true;
362  }
363 
370  bool IsAction( const TOOL_ACTION* aAction ) const;
371 
377  template<typename T>
378  inline T Parameter() const
379  {
380  return reinterpret_cast<T>( m_param );
381  }
382 
389  template<typename T>
390  void SetParameter(T aParam)
391  {
392  m_param = (void*) aParam;
393  }
394 
396  {
397  return m_commandId;
398  }
399 
401  {
402  return m_commandStr;
403  }
404 
405  void SetMousePosition( const VECTOR2D& aP )
406  {
407  m_mousePos = aP;
408  }
409 
410 private:
411  friend class TOOL_DISPATCHER;
412 
413  void setMouseDragOrigin( const VECTOR2D& aP )
414  {
415  m_mouseDragOrigin = aP;
416  }
417 
418  void setMouseDelta( const VECTOR2D& aP )
419  {
420  m_mouseDelta = aP;
421  }
422 
423  void setMouseButtons( int aButtons )
424  {
425  assert( ( aButtons & ~BUT_BUTTON_MASK ) == 0 );
426  m_mouseButtons = aButtons;
427  }
428 
429  void setModifiers( int aMods )
430  {
431  assert( ( aMods & ~MD_MODIFIER_MASK ) == 0 );
432  m_modifiers = aMods;
433  }
434 
445  {
446  #ifdef WX_COMPATIBILITY
447  wxCHECK_MSG( HasPosition(), VECTOR2D(),
448  "Attempted to get position from non-position event" );
449  #else
450  assert( HasPosition() );
451  #endif
452 
453  return aPos;
454  }
455 
459 
463 
466 
469 
472 
475 
478 
480  void* m_param;
481 
484 };
485 
487 
495 {
496 public:
498  typedef std::deque<TOOL_EVENT>::iterator iterator;
499  typedef std::deque<TOOL_EVENT>::const_iterator const_iterator;
500 
503  {}
504 
506  TOOL_EVENT_LIST( const TOOL_EVENT& aSingleEvent )
507  {
508  m_events.push_back( aSingleEvent );
509  }
510 
517  const std::string Format() const;
518 
520  {
521  for( const_iterator i = m_events.begin(); i != m_events.end(); ++i )
522  if( i->Matches( aEvent ) )
523  return *i;
524 
525  return OPT<const TOOL_EVENT&>();
526  }
527 
533  void Add( const TOOL_EVENT& aEvent )
534  {
535  m_events.push_back( aEvent );
536  }
537 
539  {
540  return m_events.begin();
541  }
542 
544  {
545  return m_events.end();
546  }
547 
549  {
550  return m_events.begin();
551  }
552 
554  {
555  return m_events.end();
556  }
557 
558  int size() const
559  {
560  return m_events.size();
561  }
562 
563  void clear()
564  {
565  m_events.clear();
566  }
567 
569  {
570  m_events.clear();
571 
572  for( std::deque<TOOL_EVENT>::const_iterator i = aEventList.m_events.begin();
573  i != aEventList.m_events.end(); ++i )
574  {
575  m_events.push_back( *i );
576  }
577 
578  return *this;
579  }
580 
582  {
583  m_events.clear();
584  m_events.push_back( aEvent );
585  return *this;
586  }
587 
589  {
590  Add( aEvent );
591  return *this;
592  }
593 
595  {
596  std::copy( aEvent.m_events.begin(), aEvent.m_events.end(), std::back_inserter( m_events ) );
597  return *this;
598  }
599 
600 private:
601  std::deque<TOOL_EVENT> m_events;
602 };
603 
604 
605 inline const TOOL_EVENT_LIST operator||( const TOOL_EVENT& aEventA, const TOOL_EVENT& aEventB )
606 {
607  TOOL_EVENT_LIST l;
608 
609  l.Add( aEventA );
610  l.Add( aEventB );
611 
612  return l;
613 }
614 
615 
616 inline const TOOL_EVENT_LIST operator||( const TOOL_EVENT& aEvent,
617  const TOOL_EVENT_LIST& aEventList )
618 {
619  TOOL_EVENT_LIST l( aEventList );
620 
621  l.Add( aEvent );
622  return l;
623 }
624 
625 
634 namespace TOOL_EVT_UTILS
635 {
643  bool IsCancelInteractive( const TOOL_EVENT& aEvt );
644 
650  bool IsSelectionEvent( const TOOL_EVENT& aEvt );
651 
652 }
653 
654 
655 #endif
int Buttons() const
Returns information about mouse buttons state.
Definition: tool_event.h:270
bool IsCancel() const
Definition: tool_event.h:295
void setMouseButtons(int aButtons)
Definition: tool_event.h:423
OPT< int > GetCommandId() const
Definition: tool_event.h:395
void setModifiers(int aMods)
Definition: tool_event.h:429
void setMouseDelta(const VECTOR2D &aP)
Definition: tool_event.h:418
TOOL_EVENT value_type
Definition: tool_event.h:497
const std::string Format() const
Function Format() Returns information about event in form of a human-readable string.
Definition: tool_event.cpp:60
iterator begin()
Definition: tool_event.h:538
OPT< const TOOL_EVENT & > Matches(const TOOL_EVENT &aEvent) const
Definition: tool_event.h:519
TOOL_ACTIONS Action() const
Returns more specific information about the type of an event.
Definition: tool_event.h:239
int m_modifiers
State of key modifierts (Ctrl/Alt/etc.)
Definition: tool_event.h:477
bool IsClick(int aButtonMask=BUT_ANY) const
Definition: tool_event.cpp:165
TOOL_ACTIONS m_actions
Definition: tool_event.h:457
TOOL_ACTIONS
Definition: tool_event.h:60
int m_mouseButtons
State of mouse buttons
Definition: tool_event.h:471
Action activates a tool
Definition: tool_event.h:151
bool IsMotion() const
Definition: tool_event.h:290
bool IsKeyPressed() const
Definition: tool_event.h:326
TOOL_EVENT(TOOL_EVENT_CATEGORY aCategory=TC_NONE, TOOL_ACTIONS aAction=TA_NONE, TOOL_ACTION_SCOPE aScope=AS_GLOBAL, void *aParameter=NULL)
Definition: tool_event.h:178
bool IsSelectionEvent(const TOOL_EVENT &aEvt)
Function IsSelectionEvent()
Definition: tool_event.cpp:185
TOOL_EVENT_CATEGORY Category() const
Returns the category (eg. mouse/keyboard/action) of an event..
Definition: tool_event.h:233
VECTOR2D returnCheckedPosition(const VECTOR2D &aPos) const
Ensure that the event is a type that has a position before returning a position, otherwise return a n...
Definition: tool_event.h:444
OPT< std::string > m_commandStr
Definition: tool_event.h:483
VECTOR2D m_mouseDelta
Difference between mouse cursor position and the point where dragging event has started
Definition: tool_event.h:462
TOOL_EVENT_CATEGORY
Internal (GUI-independent) event definitions.
Definition: tool_event.h:49
TOOL_EVENT(TOOL_EVENT_CATEGORY aCategory, TOOL_ACTIONS aAction, const std::string &aExtraParam, TOOL_ACTION_SCOPE aScope=AS_GLOBAL, void *aParameter=NULL)
Definition: tool_event.h:217
TOOL_ACTION_SCOPE
Scope of tool actions.
Definition: tool_event.h:139
int m_keyCode
Stores code of pressed/released key
Definition: tool_event.h:474
TOOL_EVENT_LIST & operator=(const TOOL_EVENT &aEvent)
Definition: tool_event.h:581
VECTOR2D m_mouseDragOrigin
Point where dragging has started
Definition: tool_event.h:468
TOOL_EVENT_LIST & operator||(const TOOL_EVENT_LIST &aEvent)
Definition: tool_event.h:594
OPT< int > m_commandId
Definition: tool_event.h:482
TOOL_ACTION_FLAGS
Flags for tool actions.
Definition: tool_event.h:147
void SetMousePosition(const VECTOR2D &aP)
Definition: tool_event.h:405
bool IsAction(const TOOL_ACTION *aAction) const
Function IsAction() Tests if the event contains an action issued upon activation of the given TOOL_AC...
Definition: tool_event.cpp:54
std::deque< TOOL_EVENT > m_events
Definition: tool_event.h:601
TOOL_EVENT(TOOL_EVENT_CATEGORY aCategory, TOOL_ACTIONS aAction, int aExtraParam, TOOL_ACTION_SCOPE aScope=AS_GLOBAL, void *aParameter=NULL)
Definition: tool_event.h:188
TOOL_EVENT_LIST()
Default constructor. Creates an empty list.
Definition: tool_event.h:502
Class TOOL_MANAGER.
Definition: tool_manager.h:49
void SetParameter(T aParam)
Function SetParameter() Sets a non-standard parameter assigned to the event.
Definition: tool_event.h:390
Class TOOL_EVENT_LIST.
Definition: tool_event.h:494
bool IsDrag(int aButtonMask=BUT_ANY) const
Definition: tool_event.h:280
Action belongs to a particular tool (i.e. a part of a pop-up menu)
Definition: tool_event.h:142
const VECTOR2D Delta() const
Returns information about difference between current mouse cursor position and the place where draggi...
Definition: tool_event.h:252
VECTOR2< double > VECTOR2D
Definition: vector2d.h:586
TOOL_ACTION_SCOPE m_scope
Definition: tool_event.h:458
bool IsDblClick(int aButtonMask=BUT_ANY) const
Definition: tool_event.cpp:171
TOOL_EVENT_LIST & operator||(const TOOL_EVENT &aEvent)
Definition: tool_event.h:588
CONTEXT_MENU_TRIGGER
Defines when a context menu is opened.
Definition: tool_event.h:155
T Parameter() const
Function Parameter() Returns a non-standard parameter assigned to the event.
Definition: tool_event.h:378
Class TOOL_EVENT.
Definition: tool_event.h:167
TOOL_EVENT_LIST(const TOOL_EVENT &aSingleEvent)
Constructor for a list containing only one TOOL_EVENT.
Definition: tool_event.h:506
const VECTOR2D DragOrigin() const
Returns the point where dragging has started.
Definition: tool_event.h:264
bool Matches(const TOOL_EVENT &aEvent) const
Function Matches() Tests whether two events match in terms of category & action or command.
Definition: tool_event.h:338
std::deque< TOOL_EVENT >::const_iterator const_iterator
Definition: tool_event.h:499
bool IsCancelInteractive(const TOOL_EVENT &aEvt)
Function IsCancelInteractive()
Definition: tool_event.cpp:177
All active tools
Definition: tool_event.h:143
bool IsMouseUp(int aButtonMask=BUT_ANY) const
Definition: tool_event.h:285
const std::string Format() const
Function Format() Returns information about event in form of a human-readable string.
Definition: tool_event.cpp:154
Namespace TOOL_EVT_UTILS.
Class TOOL_DISPATCHER.
int Modifier(int aMask=MD_MODIFIER_MASK) const
Returns information about key modifiers state (Ctrl, Alt, etc.)
Definition: tool_event.h:316
TOOL_MOUSE_BUTTONS
Definition: tool_event.h:120
OPT< std::string > GetCommandStr() const
Definition: tool_event.h:400
const_iterator cend() const
Definition: tool_event.h:553
bool IsActivate() const
Definition: tool_event.h:300
bool IsUndoRedo() const
Definition: tool_event.h:305
void Add(const TOOL_EVENT &aEvent)
Function Add() Adds a tool event to the list.
Definition: tool_event.h:533
const_iterator cbegin() const
Definition: tool_event.h:548
int size() const
Definition: tool_event.h:558
Class TOOL_ACTION.
Definition: tool_action.h:46
size_t i
Definition: json11.cpp:597
TOOL_EVENT_LIST & operator=(const TOOL_EVENT_LIST &aEventList)
Definition: tool_event.h:568
void * m_param
Generic parameter used for passing non-standard data.
Definition: tool_event.h:480
boost::optional< T > OPT
Definition: optional.h:7
TOOL_MODIFIERS
Definition: tool_event.h:130
bool IsMenu() const
Definition: tool_event.h:310
bool HasPosition() const
Returns if it this event has a valid position (true for mouse events)
Definition: tool_event.h:245
std::deque< TOOL_EVENT >::iterator iterator
Definition: tool_event.h:498
void setMouseDragOrigin(const VECTOR2D &aP)
Definition: tool_event.h:413
int KeyCode() const
Definition: tool_event.h:321
iterator end()
Definition: tool_event.h:543
VECTOR2D m_mousePos
Current mouse cursor position
Definition: tool_event.h:465
const TOOL_EVENT_LIST operator||(const TOOL_EVENT &aEventA, const TOOL_EVENT &aEventB)
Definition: tool_event.h:605
TOOL_EVENT_CATEGORY m_category
Definition: tool_event.h:456
const VECTOR2D Position() const
Returns mouse cursor position in world coordinates.
Definition: tool_event.h:258
OPT< TOOL_EVENT > OPT_TOOL_EVENT
Definition: tool_event.h:486