AbstractTool.h
Go to the documentation of this file.
1 /* Copyright (C) 2008 National Institute For Space Research (INPE) - Brazil.
2 
3  This file is part of the TerraLib - a Framework for building GIS enabled applications.
4 
5  TerraLib is free software: you can redistribute it and/or modify
6  it under the terms of the GNU Lesser General Public License as published by
7  the Free Software Foundation, either version 3 of the License,
8  or (at your option) any later version.
9 
10  TerraLib is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY; without even the implied warranty of
12  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13  GNU Lesser General Public License for more details.
14 
15  You should have received a copy of the GNU Lesser General Public License
16  along with TerraLib. See COPYING. If not, write to
17  TerraLib Team at <terralib-team@terralib.org>.
18  */
19 
20 /*!
21  \file terralib/qt/widgets/tools/AbstractTool.h
22 
23  \brief Abstract tool concept.
24 */
25 
26 #ifndef __TERRALIB_QT_WIDGETS_INTERNAL_ABSTRACTTOOL_H
27 #define __TERRALIB_QT_WIDGETS_INTERNAL_ABSTRACTTOOL_H
28 
29 // TerraLib
30 #include "../Config.h"
31 
32 // Boost
33 #include <boost/noncopyable.hpp>
34 
35 // Qt
36 #include <QtCore/QObject>
37 #include <QCursor>
38 
39 // Forward declarations
40 class QMouseEvent;
41 
42 namespace te
43 {
44  namespace qt
45  {
46  namespace widgets
47  {
48 // Forward declarations
49  class MapDisplay;
50 
51  /*!
52  \class AbstractTool
53 
54  \brief This class defines an interface for objects that can receive application events and respond to
55  them, according to specific tool behavior. Tools, in general, receives map display interaction events, like
56  MouseClick, MouseMove, etc. Tools are created to do some GIS operation using the user interactions.
57 
58  \ingroup widgets
59 
60  \sa CoordTracking, Info, Measure, Pan, RubberBand, Selection, Zoom, ZoomArea, ZoomClick, ZoomKeyboard, ZoomWheel
61  */
62  class TEQTWIDGETSEXPORT AbstractTool : public QObject, public boost::noncopyable
63  {
64  public:
65 
66  /** @name Initializer Methods
67  * Methods related to instantiation and destruction.
68  */
69  //@{
70 
71  /*!
72  \brief It constructs a tool associated with the given map display and with the specified cursor.
73 
74  \param display The map display associated with the tool.
75  \param parent The tool's parent.
76 
77  \note The tool will NOT take the ownership of the given pointers.
78  \note If the given cursor is different of Qt::BlankCursor, it will be setted on map display.
79  */
80  AbstractTool(MapDisplay* display, QObject* parent = 0);
81 
82  /*! \brief Destructor. */
83  virtual ~AbstractTool();
84 
85  //@}
86 
87  /** @name AbstractTool Methods
88  * Methods related with tool behavior.
89  */
90  //@{
91 
92  /*!
93  \brief Filters events if this object has been installed as an event filter for the watched object.
94 
95  \param watched The watched object.
96  \param event The last event sent to watched object.
97 
98  \note In your reimplementation of this function, if you want to filter the event out,
99  i.e. stop it being handled further, return true; otherwise return false.
100 
101  \note Here, the default implementation looks for QMouseEvents and call the pure virutal methods
102  defined on AbstractTool class, e.g. mousePressEvent().
103  */
104  virtual bool eventFilter(QObject* watched, QEvent* e);
105 
106  /*!
107  \brief This event handler can be reimplemented in a concrete tool class
108  to receive mouse press events for the watched object.
109 
110  \param e The mouse event.
111 
112  \return If you want to filter the event out, i.e. stop it being handled further, return true; otherwise return false.
113  */
114  virtual bool mousePressEvent(QMouseEvent* e);
115 
116  /*!
117  \brief This event handler can be reimplemented in a concrete tool class
118  to receive mouse move events for the watched object.
119 
120  \param e The mouse event.
121 
122  \return If you want to filter the event out, i.e. stop it being handled further, return true; otherwise return false.
123  */
124  virtual bool mouseMoveEvent(QMouseEvent* e);
125 
126  /*!
127  \brief This event handler can be reimplemented in a concrete tool class
128  to receive mouse release events for the watched object.
129 
130  \param e The mouse event.
131 
132  \return If you want to filter the event out, i.e. stop it being handled further, return true; otherwise return false.
133  */
134  virtual bool mouseReleaseEvent(QMouseEvent* e);
135 
136  /*!
137  \brief This event handler can be reimplemented in a concrete tool class
138  to receive mouse double click events for the watched object.
139 
140  \param e The mouse event.
141 
142  \return If you want to filter the event out, i.e. stop it being handled further, return true; otherwise return false.
143 
144  \note The AbstractTool will also receive mouse press and mouse release events in addition to the double click event.
145  It is up to the developer to ensure that the application interprets these events correctly.
146  */
147  virtual bool mouseDoubleClickEvent(QMouseEvent* e);
148 
149  //@}
150 
151  /*!
152  \brief It sets the tool cursor.
153 
154  \param cursor The cursor that will be used during the tool operation.
155  */
156  virtual void setCursor(const QCursor& cursor);
157 
158  protected:
159 
160  MapDisplay* m_display; //!< The map display associated with the tool.
161  QCursor m_cursor; //!< The default tool cursor.
162  };
163 
164  } // end namespace widgets
165  } // end namespace qt
166 } // end namespace te
167 
168 #endif // __TERRALIB_QT_WIDGETS_INTERNAL_ABSTRACTTOOL_H
A widget to control the display of a set of layers.
Definition: MapDisplay.h:66
QCursor m_cursor
The default tool cursor.
Definition: AbstractTool.h:161
This class defines an interface for objects that can receive application events and respond to them...
Definition: AbstractTool.h:62
URI C++ Library.
#define TEQTWIDGETSEXPORT
You can use this macro in order to export/import classes and functions from this module.
Definition: Config.h:63
MapDisplay * m_display
The map display associated with the tool.
Definition: AbstractTool.h:160