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 
34 #include <core/optional.h>
35 
36 #ifdef WX_COMPATIBILITY
37 #include <wx/debug.h>
38 #else
39 #include <cassert>
40 #endif
41 
42 
43 class TOOL_ACTION;
44 class TOOL_MANAGER;
45 
51 {
52  TC_NONE = 0x00,
53  TC_MOUSE = 0x01,
54  TC_KEYBOARD = 0x02,
55  TC_COMMAND = 0x04,
56  TC_MESSAGE = 0x08,
57  TC_VIEW = 0x10,
58  TC_ANY = 0xffffffff
59 };
60 
62 {
63  // UI input events
64  TA_NONE = 0x0000,
65  TA_MOUSE_CLICK = 0x0001,
67  TA_MOUSE_UP = 0x0004,
68  TA_MOUSE_DOWN = 0x0008,
69  TA_MOUSE_DRAG = 0x0010,
70  TA_MOUSE_MOTION = 0x0020,
71  TA_MOUSE_WHEEL = 0x0040,
72  TA_MOUSE = 0x007f,
73 
74  TA_KEY_PRESSED = 0x0080,
76 
77  // View related events
78  TA_VIEW_REFRESH = 0x0100,
79  TA_VIEW_ZOOM = 0x0200,
80  TA_VIEW_PAN = 0x0400,
81  TA_VIEW_DIRTY = 0x0800,
82  TA_VIEW = 0x0f00,
83 
84  TA_CHANGE_LAYER = 0x1000,
85 
86  // Tool cancel event. Issued automagically when the user hits escape or selects End Tool from
87  // the context menu.
88  TA_CANCEL_TOOL = 0x2000,
89 
90  // Context menu update. Issued whenever context menu is open and the user hovers the mouse
91  // over one of choices. Used in dynamic highligting in disambiguation menu
93 
94  // Context menu choice. Sent if the user picked something from the context menu or
95  // closed it without selecting anything.
97 
98  // Context menu is closed, no matter whether anything has been chosen or not.
100 
102 
103  // This event is sent *before* undo/redo command is performed.
104  TA_UNDO_REDO_PRE = 0x20000,
105 
106  // This event is sent *after* undo/redo command is performed.
107  TA_UNDO_REDO_POST = 0x40000,
108 
109  // Tool action (allows one to control tools).
110  TA_ACTION = 0x80000,
111 
112  // Tool activation event.
113  TA_ACTIVATE = 0x100000,
114 
115  // Model has changed (partial update).
116  TA_MODEL_CHANGE = 0x200000,
117 
118  TA_ANY = 0xffffffff
119 };
120 
122 {
123  BUT_NONE = 0x0,
124  BUT_LEFT = 0x1,
125  BUT_RIGHT = 0x2,
126  BUT_MIDDLE = 0x4,
128  BUT_ANY = 0xffffffff
129 };
130 
132 {
133  MD_SHIFT = 0x1000,
134  MD_CTRL = 0x2000,
135  MD_ALT = 0x4000,
137 };
138 
141 {
145 };
146 
149 {
150  AF_NONE = 0,
153 };
154 
157 {
158  CMENU_BUTTON = 0, // On the right button
159  CMENU_NOW, // Right now (after TOOL_INTERACTIVE::SetContextMenu)
160  CMENU_OFF // Never
161 };
162 
169 {
170 public:
177  const std::string Format() const;
178 
180  TOOL_ACTION_SCOPE aScope = AS_GLOBAL, void* aParameter = NULL ) :
181  m_category( aCategory ),
182  m_actions( aAction ),
183  m_scope( aScope ),
184  m_mouseButtons( 0 ),
185  m_keyCode( 0 ),
186  m_modifiers( 0 ),
187  m_param( aParameter ) {}
188 
189  TOOL_EVENT( TOOL_EVENT_CATEGORY aCategory, TOOL_ACTIONS aAction, int aExtraParam,
190  TOOL_ACTION_SCOPE aScope = AS_GLOBAL, void* aParameter = NULL ) :
191  m_category( aCategory ),
192  m_actions( aAction ),
193  m_scope( aScope ),
194  m_mouseButtons( 0 ),
195  m_keyCode( 0 ),
196  m_modifiers( 0 ),
197  m_param( aParameter )
198  {
199  if( aCategory == TC_MOUSE )
200  {
201  setMouseButtons( aExtraParam & BUT_BUTTON_MASK );
202  }
203  else if( aCategory == TC_KEYBOARD )
204  {
205  m_keyCode = aExtraParam & ~MD_MODIFIER_MASK; // Filter out modifiers
206  }
207  else if( aCategory == TC_COMMAND )
208  {
209  m_commandId = aExtraParam;
210  }
211 
212  if( aCategory & ( TC_MOUSE | TC_KEYBOARD ) )
213  {
214  m_modifiers = aExtraParam & MD_MODIFIER_MASK;
215  }
216  }
217 
219  const std::string& aExtraParam, TOOL_ACTION_SCOPE aScope = AS_GLOBAL,
220  void* aParameter = NULL ) :
221  m_category( aCategory ),
222  m_actions( aAction ),
223  m_scope( aScope ),
224  m_mouseButtons( 0 ),
225  m_keyCode( 0 ),
226  m_modifiers( 0 ),
227  m_param( aParameter )
228  {
229  if( aCategory == TC_COMMAND || aCategory == TC_MESSAGE )
230  m_commandStr = aExtraParam;
231  }
232 
235  {
236  return m_category;
237  }
238 
241  {
242  return m_actions;
243  }
244 
246  bool HasPosition() const
247  {
248  return m_category == TC_MOUSE;
249  }
250 
253  const VECTOR2D Delta() const
254  {
256  }
257 
259  const VECTOR2D Position() const
260  {
262  }
263 
265  const VECTOR2D DragOrigin() const
266  {
268  }
269 
271  int Buttons() const
272  {
273  assert( m_category == TC_MOUSE ); // this should be used only with mouse events
274  return m_mouseButtons;
275  }
276 
277  bool IsClick( int aButtonMask = BUT_ANY ) const
278  {
279  return ( m_actions == TA_MOUSE_CLICK )
280  && ( ( m_mouseButtons & aButtonMask ) == aButtonMask );
281  }
282 
283  bool IsDblClick( int aButtonMask = BUT_ANY ) const
284  {
285  return ( m_actions == TA_MOUSE_DBLCLICK )
286  && ( ( m_mouseButtons & aButtonMask ) == aButtonMask );
287  }
288 
289  bool IsDrag( int aButtonMask = BUT_ANY ) const
290  {
291  return ( m_actions == TA_MOUSE_DRAG ) && ( ( m_mouseButtons & aButtonMask ) == aButtonMask );
292  }
293 
294  bool IsMouseUp( int aButtonMask = BUT_ANY ) const
295  {
296  return ( m_actions == TA_MOUSE_UP ) && ( ( m_mouseButtons & aButtonMask ) == aButtonMask );
297  }
298 
299  bool IsMotion() const
300  {
301  return m_actions == TA_MOUSE_MOTION;
302  }
303 
304  bool IsCancel() const
305  {
306  return m_actions == TA_CANCEL_TOOL;
307  }
308 
309  bool IsActivate() const
310  {
311  return m_actions == TA_ACTIVATE;
312  }
313 
314  bool IsUndoRedo() const
315  {
317  }
318 
319  bool IsMenu() const
320  {
321  return m_actions & TA_CONTEXT_MENU;
322  }
323 
325  int Modifier( int aMask = MD_MODIFIER_MASK ) const
326  {
327  return m_modifiers & aMask;
328  }
329 
330  int KeyCode() const
331  {
332  return m_keyCode;
333  }
334 
335  bool IsKeyPressed() const
336  {
337  return m_actions == TA_KEY_PRESSED;
338  }
339 
347  bool Matches( const TOOL_EVENT& aEvent ) const
348  {
349  if( !( m_category & aEvent.m_category ) )
350  return false;
351 
353  {
354  if( (bool) m_commandStr && (bool) aEvent.m_commandStr )
355  return *m_commandStr == *aEvent.m_commandStr;
356 
357  if( (bool) m_commandId && (bool) aEvent.m_commandId )
358  return *m_commandId == *aEvent.m_commandId;
359  }
360 
361  // BUGFIX: TA_ANY should match EVERYTHING, even TA_NONE (for TC_MESSAGE)
362  if( m_actions == TA_ANY && aEvent.m_actions == TA_NONE && aEvent.m_category == TC_MESSAGE )
363  return true;
364 
365  // BUGFIX: This check must happen after the TC_COMMAND check because otherwise events of
366  // the form { TC_COMMAND, TA_NONE } will be incorrectly skipped
367  if( !( m_actions & aEvent.m_actions ) )
368  return false;
369 
370  return true;
371  }
372 
379  bool IsAction( const TOOL_ACTION* aAction ) const;
380 
386  template<typename T>
387  inline T Parameter() const
388  {
389  return reinterpret_cast<T>( m_param );
390  }
391 
398  template<typename T>
399  void SetParameter(T aParam)
400  {
401  m_param = (void*) aParam;
402  }
403 
405  {
406  return m_commandId;
407  }
408 
410  {
411  return m_commandStr;
412  }
413 
414  void SetMousePosition( const VECTOR2D& aP )
415  {
416  m_mousePos = aP;
417  }
418 
419 private:
420  friend class TOOL_DISPATCHER;
421 
422  void setMouseDragOrigin( const VECTOR2D& aP )
423  {
424  m_mouseDragOrigin = aP;
425  }
426 
427  void setMouseDelta( const VECTOR2D& aP )
428  {
429  m_mouseDelta = aP;
430  }
431 
432  void setMouseButtons( int aButtons )
433  {
434  assert( ( aButtons & ~BUT_BUTTON_MASK ) == 0 );
435  m_mouseButtons = aButtons;
436  }
437 
438  void setModifiers( int aMods )
439  {
440  assert( ( aMods & ~MD_MODIFIER_MASK ) == 0 );
441  m_modifiers = aMods;
442  }
443 
454  {
455  #ifdef WX_COMPATIBILITY
456  wxCHECK_MSG( HasPosition(), VECTOR2D(),
457  "Attempted to get position from non-position event" );
458  #else
459  assert( HasPosition() );
460  #endif
461 
462  return aPos;
463  }
464 
468 
472 
475 
478 
481 
484 
487 
489  void* m_param;
490 
493 };
494 
496 
504 {
505 public:
507  typedef std::deque<TOOL_EVENT>::iterator iterator;
508  typedef std::deque<TOOL_EVENT>::const_iterator const_iterator;
509 
512  {}
513 
515  TOOL_EVENT_LIST( const TOOL_EVENT& aSingleEvent )
516  {
517  m_events.push_back( aSingleEvent );
518  }
519 
526  const std::string Format() const;
527 
529  {
530  for( const_iterator i = m_events.begin(); i != m_events.end(); ++i )
531  if( i->Matches( aEvent ) )
532  return *i;
533 
534  return OPT<const TOOL_EVENT&>();
535  }
536 
542  void Add( const TOOL_EVENT& aEvent )
543  {
544  m_events.push_back( aEvent );
545  }
546 
547  iterator begin()
548  {
549  return m_events.begin();
550  }
551 
552  iterator end()
553  {
554  return m_events.end();
555  }
556 
557  const_iterator cbegin() const
558  {
559  return m_events.begin();
560  }
561 
562  const_iterator cend() const
563  {
564  return m_events.end();
565  }
566 
567  int size() const
568  {
569  return m_events.size();
570  }
571 
572  void clear()
573  {
574  m_events.clear();
575  }
576 
578  {
579  m_events.clear();
580 
581  for( std::deque<TOOL_EVENT>::const_iterator i = aEventList.m_events.begin();
582  i != aEventList.m_events.end(); ++i )
583  {
584  m_events.push_back( *i );
585  }
586 
587  return *this;
588  }
589 
591  {
592  m_events.clear();
593  m_events.push_back( aEvent );
594  return *this;
595  }
596 
598  {
599  Add( aEvent );
600  return *this;
601  }
602 
604  {
605  std::copy( aEvent.m_events.begin(), aEvent.m_events.end(), std::back_inserter( m_events ) );
606  return *this;
607  }
608 
609 private:
610  std::deque<TOOL_EVENT> m_events;
611 };
612 
613 inline const TOOL_EVENT_LIST operator||( const TOOL_EVENT& aEventA, const TOOL_EVENT& aEventB )
614 {
615  TOOL_EVENT_LIST l;
616 
617  l.Add( aEventA );
618  l.Add( aEventB );
619 
620  return l;
621 }
622 
623 inline const TOOL_EVENT_LIST operator||( const TOOL_EVENT& aEvent,
624  const TOOL_EVENT_LIST& aEventList )
625 {
626  TOOL_EVENT_LIST l( aEventList );
627 
628  l.Add( aEvent );
629  return l;
630 }
631 
632 #endif
void setMouseButtons(int aButtons)
Definition: tool_event.h:432
void setModifiers(int aMods)
Definition: tool_event.h:438
void setMouseDelta(const VECTOR2D &aP)
Definition: tool_event.h:427
TOOL_EVENT value_type
Definition: tool_event.h:506
bool IsDrag(int aButtonMask=BUT_ANY) const
Definition: tool_event.h:289
bool IsUndoRedo() const
Definition: tool_event.h:314
iterator begin()
Definition: tool_event.h:547
const std::string Format() const
Function Format() Returns information about event in form of a human-readable string.
Definition: tool_event.cpp:60
bool IsMotion() const
Definition: tool_event.h:299
const VECTOR2D Position() const
Returns mouse cursor position in world coordinates.
Definition: tool_event.h:259
int m_modifiers
State of key modifierts (Ctrl/Alt/etc.)
Definition: tool_event.h:486
TOOL_ACTIONS m_actions
Definition: tool_event.h:466
TOOL_ACTIONS
Definition: tool_event.h:61
const VECTOR2D DragOrigin() const
Returns the point where dragging has started.
Definition: tool_event.h:265
bool HasPosition() const
Returns if it this event has a valid position (true for mouse events)
Definition: tool_event.h:246
int m_mouseButtons
State of mouse buttons
Definition: tool_event.h:480
Action activates a tool
Definition: tool_event.h:152
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:179
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
OPT< std::string > m_commandStr
Definition: tool_event.h:492
VECTOR2D m_mouseDelta
Difference between mouse cursor position and the point where dragging event has started ...
Definition: tool_event.h:471
TOOL_EVENT_CATEGORY
Internal (GUI-independent) event definitions.
Definition: tool_event.h:50
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:218
int Modifier(int aMask=MD_MODIFIER_MASK) const
Returns information about key modifiers state (Ctrl, Alt, etc.)
Definition: tool_event.h:325
TOOL_ACTION_SCOPE
Scope of tool actions.
Definition: tool_event.h:140
int m_keyCode
Stores code of pressed/released key
Definition: tool_event.h:483
TOOL_EVENT_LIST & operator=(const TOOL_EVENT &aEvent)
Definition: tool_event.h:590
bool IsKeyPressed() const
Definition: tool_event.h:335
int KeyCode() const
Definition: tool_event.h:330
bool IsDblClick(int aButtonMask=BUT_ANY) const
Definition: tool_event.h:283
VECTOR2D m_mouseDragOrigin
Point where dragging has started
Definition: tool_event.h:477
TOOL_EVENT_LIST & operator||(const TOOL_EVENT_LIST &aEvent)
Definition: tool_event.h:603
OPT< int > m_commandId
Definition: tool_event.h:491
TOOL_ACTION_FLAGS
Flags for tool actions.
Definition: tool_event.h:148
void SetMousePosition(const VECTOR2D &aP)
Definition: tool_event.h:414
std::deque< TOOL_EVENT > m_events
Definition: tool_event.h:610
TOOL_EVENT(TOOL_EVENT_CATEGORY aCategory, TOOL_ACTIONS aAction, int aExtraParam, TOOL_ACTION_SCOPE aScope=AS_GLOBAL, void *aParameter=NULL)
Definition: tool_event.h:189
TOOL_EVENT_LIST()
Default constructor. Creates an empty list.
Definition: tool_event.h:511
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:399
Class TOOL_EVENT_LIST.
Definition: tool_event.h:503
Action belongs to a particular tool (i.e. a part of a pop-up menu)
Definition: tool_event.h:143
OPT< int > GetCommandId() const
Definition: tool_event.h:404
VECTOR2< double > VECTOR2D
Definition: vector2d.h:586
TOOL_ACTION_SCOPE m_scope
Definition: tool_event.h:467
const_iterator cend() const
Definition: tool_event.h:562
TOOL_EVENT_LIST & operator||(const TOOL_EVENT &aEvent)
Definition: tool_event.h:597
CONTEXT_MENU_TRIGGER
Defines when a context menu is opened.
Definition: tool_event.h:156
Class TOOL_EVENT.
Definition: tool_event.h:168
TOOL_EVENT_LIST(const TOOL_EVENT &aSingleEvent)
Constructor for a list containing only one TOOL_EVENT.
Definition: tool_event.h:515
bool IsActivate() const
Definition: tool_event.h:309
bool IsCancel() const
Definition: tool_event.h:304
OPT< std::string > GetCommandStr() const
Definition: tool_event.h:409
std::deque< TOOL_EVENT >::const_iterator const_iterator
Definition: tool_event.h:508
bool IsMouseUp(int aButtonMask=BUT_ANY) const
Definition: tool_event.h:294
All active tools
Definition: tool_event.h:144
TOOL_ACTIONS Action() const
Returns more specific information about the type of an event.
Definition: tool_event.h:240
OPT< const TOOL_EVENT & > Matches(const TOOL_EVENT &aEvent) const
Definition: tool_event.h:528
TOOL_EVENT_CATEGORY Category() const
Returns the category (eg. mouse/keyboard/action) of an event..
Definition: tool_event.h:234
Class TOOL_DISPATCHER.
int size() const
Definition: tool_event.h:567
TOOL_MOUSE_BUTTONS
Definition: tool_event.h:121
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:347
bool IsMenu() const
Definition: tool_event.h:319
const VECTOR2D Delta() const
Returns information about difference between current mouse cursor position and the place where draggi...
Definition: tool_event.h:253
T Parameter() const
Function Parameter() Returns a non-standard parameter assigned to the event.
Definition: tool_event.h:387
void Add(const TOOL_EVENT &aEvent)
Function Add() Adds a tool event to the list.
Definition: tool_event.h:542
Class TOOL_ACTION.
Definition: tool_action.h:46
size_t i
Definition: json11.cpp:597
VECTOR2D returnCheckedPosition(const VECTOR2D &aPos) const
Ensure that the event is a type that has a position before returning a position, otherwise return a m...
Definition: tool_event.h:453
TOOL_EVENT_LIST & operator=(const TOOL_EVENT_LIST &aEventList)
Definition: tool_event.h:577
void * m_param
Generic parameter used for passing non-standard data.
Definition: tool_event.h:489
boost::optional< T > OPT
Definition: optional.h:7
TOOL_MODIFIERS
Definition: tool_event.h:131
int Buttons() const
Returns information about mouse buttons state.
Definition: tool_event.h:271
std::deque< TOOL_EVENT >::iterator iterator
Definition: tool_event.h:507
void setMouseDragOrigin(const VECTOR2D &aP)
Definition: tool_event.h:422
iterator end()
Definition: tool_event.h:552
VECTOR2D m_mousePos
Current mouse cursor position
Definition: tool_event.h:474
const TOOL_EVENT_LIST operator||(const TOOL_EVENT &aEventA, const TOOL_EVENT &aEventB)
Definition: tool_event.h:613
bool IsClick(int aButtonMask=BUT_ANY) const
Definition: tool_event.h:277
const_iterator cbegin() const
Definition: tool_event.h:557
TOOL_EVENT_CATEGORY m_category
Definition: tool_event.h:465
OPT< TOOL_EVENT > OPT_TOOL_EVENT
Definition: tool_event.h:495