qwt_picker.h 9.31 KB
Newer Older
pixhawk's avatar
pixhawk committed
1
2
3
4
/* -*- mode: C++ ; c-file-style: "stroustrup" -*- *****************************
 * Qwt Widget Library
 * Copyright (C) 1997   Josef Wilgen
 * Copyright (C) 2002   Uwe Rathmann
5
 *
pixhawk's avatar
pixhawk committed
6
7
8
9
10
11
12
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the Qwt License, Version 1.0
 *****************************************************************************/

#ifndef QWT_PICKER
#define QWT_PICKER 1

Bryant's avatar
Bryant committed
13
14
15
#include "qwt_global.h"
#include "qwt_text.h"
#include "qwt_event_pattern.h"
pixhawk's avatar
pixhawk committed
16
17
18
19
#include <qobject.h>
#include <qpen.h>
#include <qfont.h>
#include <qrect.h>
Bryant's avatar
Bryant committed
20
#include <qpainterpath.h>
pixhawk's avatar
pixhawk committed
21
22
23
24
25
26

class QWidget;
class QMouseEvent;
class QWheelEvent;
class QKeyEvent;
class QwtPickerMachine;
Bryant's avatar
Bryant committed
27
class QwtWidgetOverlay;
pixhawk's avatar
pixhawk committed
28
29
30
31

/*!
  \brief QwtPicker provides selections on a widget

Bryant's avatar
Bryant committed
32
33
34
35
36
37
  QwtPicker filters all enter, leave, mouse and keyboard events of a widget
  and translates them into an array of selected points.

  The way how the points are collected depends on type of state machine
  that is connected to the picker. Qwt offers a couple of predefined
  state machines for selecting:
pixhawk's avatar
pixhawk committed
38

Bryant's avatar
Bryant committed
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
  - Nothing\n
    QwtPickerTrackerMachine
  - Single points\n
    QwtPickerClickPointMachine, QwtPickerDragPointMachine
  - Rectangles\n
    QwtPickerClickRectMachine, QwtPickerDragRectMachine
  - Polygons\n
    QwtPickerPolygonMachine

  While these state machines cover the most common ways to collect points
  it is also possible to implement individual machines as well.

  QwtPicker translates the picked points into a selection using the
  adjustedPoints() method. adjustedPoints() is intended to be reimplemented
  to fix up the selection according to application specific requirements.
  (F.e. when an application accepts rectangles of a fixed aspect ratio only.)

  Optionally QwtPicker support the process of collecting points by a
  rubber band and tracker displaying a text for the current mouse
  position.
pixhawk's avatar
pixhawk committed
59

60
  \par Example
pixhawk's avatar
pixhawk committed
61
  \verbatim #include <qwt_picker.h>
Bryant's avatar
Bryant committed
62
#include <qwt_picker_machine.h>
pixhawk's avatar
pixhawk committed
63
64

QwtPicker *picker = new QwtPicker(widget);
Bryant's avatar
Bryant committed
65
picker->setStateMachine(new QwtPickerDragRectMachine);
pixhawk's avatar
pixhawk committed
66
67
68
picker->setTrackerMode(QwtPicker::ActiveOnly);
picker->setRubberBand(QwtPicker::RectRubberBand); \endverbatim\n

Bryant's avatar
Bryant committed
69
  The state machine triggers the following commands:
pixhawk's avatar
pixhawk committed
70

Bryant's avatar
Bryant committed
71
72
73
74
75
76
77
78
79
80
  - begin()\n
    Activate/Initialize the selection.
  - append()\n
    Add a new point
  - move() \n
    Change the position of the last point.
  - remove()\n
    Remove the last point.
  - end()\n
    Terminate the selection and call accept to validate the picked points.
pixhawk's avatar
pixhawk committed
81
82

  The picker is active (isActive()), between begin() and end().
Bryant's avatar
Bryant committed
83
  In active state the rubber band is displayed, and the tracker is visible
pixhawk's avatar
pixhawk committed
84
85
86
87
88
89
90
  in case of trackerMode is ActiveOnly or AlwaysOn.

  The cursor can be moved using the arrow keys. All selections can be aborted
  using the abort key. (QwtEventPattern::KeyPatternCode)

  \warning In case of QWidget::NoFocus the focus policy of the observed
           widget is set to QWidget::WheelFocus and mouse tracking
Bryant's avatar
Bryant committed
91
           will be manipulated while the picker is active,
pixhawk's avatar
pixhawk committed
92
93
94
95
96
97
98
           or if trackerMode() is AlwayOn.
*/

class QWT_EXPORT QwtPicker: public QObject, public QwtEventPattern
{
    Q_OBJECT

Bryant's avatar
Bryant committed
99
    Q_ENUMS( RubberBand DisplayMode ResizeMode )
pixhawk's avatar
pixhawk committed
100

Bryant's avatar
Bryant committed
101
102
    Q_PROPERTY( bool isEnabled READ isEnabled WRITE setEnabled )
    Q_PROPERTY( ResizeMode resizeMode READ resizeMode WRITE setResizeMode )
pixhawk's avatar
pixhawk committed
103

Bryant's avatar
Bryant committed
104
105
106
    Q_PROPERTY( DisplayMode trackerMode READ trackerMode WRITE setTrackerMode )
    Q_PROPERTY( QPen trackerPen READ trackerPen WRITE setTrackerPen )
    Q_PROPERTY( QFont trackerFont READ trackerFont WRITE setTrackerFont )
pixhawk's avatar
pixhawk committed
107

Bryant's avatar
Bryant committed
108
109
    Q_PROPERTY( RubberBand rubberBand READ rubberBand WRITE setRubberBand )
    Q_PROPERTY( QPen rubberBandPen READ rubberBandPen WRITE setRubberBandPen )
pixhawk's avatar
pixhawk committed
110

Bryant's avatar
Bryant committed
111
public:
112
    /*!
Bryant's avatar
Bryant committed
113
      Rubber band style
pixhawk's avatar
pixhawk committed
114

Bryant's avatar
Bryant committed
115
116
      The default value is QwtPicker::NoRubberBand.
      \sa setRubberBand(), rubberBand()
pixhawk's avatar
pixhawk committed
117
118
    */

Bryant's avatar
Bryant committed
119
120
121
    enum RubberBand
    {
        //! No rubberband.
pixhawk's avatar
pixhawk committed
122
123
        NoRubberBand = 0,

Bryant's avatar
Bryant committed
124
        //! A horizontal line ( only for QwtPickerMachine::PointSelection )
pixhawk's avatar
pixhawk committed
125
        HLineRubberBand,
Bryant's avatar
Bryant committed
126
127

        //! A vertical line ( only for QwtPickerMachine::PointSelection )
pixhawk's avatar
pixhawk committed
128
        VLineRubberBand,
Bryant's avatar
Bryant committed
129
130

        //! A crosshair ( only for QwtPickerMachine::PointSelection )
pixhawk's avatar
pixhawk committed
131
132
        CrossRubberBand,

Bryant's avatar
Bryant committed
133
        //! A rectangle ( only for QwtPickerMachine::RectSelection )
pixhawk's avatar
pixhawk committed
134
        RectRubberBand,
Bryant's avatar
Bryant committed
135
136

        //! An ellipse ( only for QwtPickerMachine::RectSelection )
pixhawk's avatar
pixhawk committed
137
138
        EllipseRubberBand,

Bryant's avatar
Bryant committed
139
        //! A polygon ( only for QwtPickerMachine::PolygonSelection )
pixhawk's avatar
pixhawk committed
140
141
        PolygonRubberBand,

Bryant's avatar
Bryant committed
142
143
144
145
        /*!
          Values >= UserRubberBand can be used to define additional
          rubber bands.
         */
pixhawk's avatar
pixhawk committed
146
147
148
        UserRubberBand = 100
    };

149
    /*!
Bryant's avatar
Bryant committed
150
151
      \brief Display mode
      \sa setTrackerMode(), trackerMode(), isActive()
pixhawk's avatar
pixhawk committed
152
    */
Bryant's avatar
Bryant committed
153
154
155
    enum DisplayMode
    {
        //! Display never
pixhawk's avatar
pixhawk committed
156
        AlwaysOff,
Bryant's avatar
Bryant committed
157
158

        //! Display always
pixhawk's avatar
pixhawk committed
159
        AlwaysOn,
Bryant's avatar
Bryant committed
160
161

        //! Display only when the selection is active
pixhawk's avatar
pixhawk committed
162
163
164
        ActiveOnly
    };

165
    /*!
pixhawk's avatar
pixhawk committed
166
167
168
      Controls what to do with the selected points of an active
         selection when the observed widget is resized.

Bryant's avatar
Bryant committed
169
170
      The default value is QwtPicker::Stretch.
      \sa setResizeMode()
pixhawk's avatar
pixhawk committed
171
172
    */

Bryant's avatar
Bryant committed
173
174
175
    enum ResizeMode
    {
        //! All points are scaled according to the new size,
pixhawk's avatar
pixhawk committed
176
        Stretch,
Bryant's avatar
Bryant committed
177
178

        //! All points remain unchanged.
pixhawk's avatar
pixhawk committed
179
180
181
        KeepSize
    };

Bryant's avatar
Bryant committed
182
183
184
    explicit QwtPicker( QWidget *parent );
    explicit QwtPicker( RubberBand rubberBand,
                        DisplayMode trackerMode, QWidget * );
pixhawk's avatar
pixhawk committed
185
186
187

    virtual ~QwtPicker();

Bryant's avatar
Bryant committed
188
189
190
    void setStateMachine( QwtPickerMachine * );
    const QwtPickerMachine *stateMachine() const;
    QwtPickerMachine *stateMachine();
pixhawk's avatar
pixhawk committed
191

Bryant's avatar
Bryant committed
192
    void setRubberBand( RubberBand );
pixhawk's avatar
pixhawk committed
193
194
    RubberBand rubberBand() const;

Bryant's avatar
Bryant committed
195
    void setTrackerMode( DisplayMode );
pixhawk's avatar
pixhawk committed
196
197
    DisplayMode trackerMode() const;

Bryant's avatar
Bryant committed
198
    void setResizeMode( ResizeMode );
pixhawk's avatar
pixhawk committed
199
200
    ResizeMode resizeMode() const;

Bryant's avatar
Bryant committed
201
    void setRubberBandPen( const QPen & );
pixhawk's avatar
pixhawk committed
202
203
    QPen rubberBandPen() const;

Bryant's avatar
Bryant committed
204
    void setTrackerPen( const QPen & );
pixhawk's avatar
pixhawk committed
205
206
    QPen trackerPen() const;

Bryant's avatar
Bryant committed
207
    void setTrackerFont( const QFont & );
pixhawk's avatar
pixhawk committed
208
209
210
211
212
    QFont trackerFont() const;

    bool isEnabled() const;
    bool isActive() const;

Bryant's avatar
Bryant committed
213
    virtual bool eventFilter( QObject *, QEvent * );
pixhawk's avatar
pixhawk committed
214
215
216
217

    QWidget *parentWidget();
    const QWidget *parentWidget() const;

Bryant's avatar
Bryant committed
218
219
220
221
    virtual QPainterPath pickArea() const;

    virtual void drawRubberBand( QPainter * ) const;
    virtual void drawTracker( QPainter * ) const;
pixhawk's avatar
pixhawk committed
222

Bryant's avatar
Bryant committed
223
    virtual QRegion rubberBandMask() const;
pixhawk's avatar
pixhawk committed
224

Bryant's avatar
Bryant committed
225
    virtual QwtText trackerText( const QPoint &pos ) const;
pixhawk's avatar
pixhawk committed
226
    QPoint trackerPosition() const;
Bryant's avatar
Bryant committed
227
    virtual QRect trackerRect( const QFont & ) const;
pixhawk's avatar
pixhawk committed
228

Bryant's avatar
Bryant committed
229
230
231
232
233
234
235
236
237
238
239
240
241
242
    QPolygon selection() const;

public Q_SLOTS:
    void setEnabled( bool );

Q_SIGNALS:
    /*!
      A signal indicating, when the picker has been activated.
      Together with setEnabled() it can be used to implement
      selections with more than one picker.

      \param on True, when the picker has been activated
    */
    void activated( bool on );
pixhawk's avatar
pixhawk committed
243
244

    /*!
245
      A signal emitting the selected points,
pixhawk's avatar
pixhawk committed
246
247
      at the end of a selection.

Bryant's avatar
Bryant committed
248
      \param polygon Selected points
pixhawk's avatar
pixhawk committed
249
    */
Bryant's avatar
Bryant committed
250
    void selected( const QPolygon &polygon );
pixhawk's avatar
pixhawk committed
251
252
253
254
255
256
257

    /*!
      A signal emitted when a point has been appended to the selection

      \param pos Position of the appended point.
      \sa append(). moved()
    */
Bryant's avatar
Bryant committed
258
    void appended( const QPoint &pos );
pixhawk's avatar
pixhawk committed
259
260

    /*!
261
      A signal emitted whenever the last appended point of the
pixhawk's avatar
pixhawk committed
262
263
264
265
266
      selection has been moved.

      \param pos Position of the moved last point of the selection.
      \sa move(), appended()
    */
Bryant's avatar
Bryant committed
267
268
269
270
271
    void moved( const QPoint &pos );

    /*!
      A signal emitted whenever the last appended point of the
      selection has been removed.
pixhawk's avatar
pixhawk committed
272

Bryant's avatar
Bryant committed
273
274
275
276
      \param pos Position of the point, that has been removed
      \sa remove(), appended()
    */
    void removed( const QPoint &pos );
pixhawk's avatar
pixhawk committed
277
278
279
280
    /*!
      A signal emitted when the active selection has been changed.
      This might happen when the observed widget is resized.

Bryant's avatar
Bryant committed
281
      \param selection Changed selection
pixhawk's avatar
pixhawk committed
282
283
      \sa stretchSelection()
    */
Bryant's avatar
Bryant committed
284
    void changed( const QPolygon &selection );
pixhawk's avatar
pixhawk committed
285
286

protected:
Bryant's avatar
Bryant committed
287
    virtual QPolygon adjustedPoints( const QPolygon & ) const;
pixhawk's avatar
pixhawk committed
288

Bryant's avatar
Bryant committed
289
    virtual void transition( const QEvent * );
pixhawk's avatar
pixhawk committed
290
291

    virtual void begin();
Bryant's avatar
Bryant committed
292
293
294
295
    virtual void append( const QPoint & );
    virtual void move( const QPoint & );
    virtual void remove();
    virtual bool end( bool ok = true );
pixhawk's avatar
pixhawk committed
296

Bryant's avatar
Bryant committed
297
    virtual bool accept( QPolygon & ) const;
pixhawk's avatar
pixhawk committed
298
299
    virtual void reset();

Bryant's avatar
Bryant committed
300
301
302
303
304
305
306
307
308
    virtual void widgetMousePressEvent( QMouseEvent * );
    virtual void widgetMouseReleaseEvent( QMouseEvent * );
    virtual void widgetMouseDoubleClickEvent( QMouseEvent * );
    virtual void widgetMouseMoveEvent( QMouseEvent * );
    virtual void widgetWheelEvent( QWheelEvent * );
    virtual void widgetKeyPressEvent( QKeyEvent * );
    virtual void widgetKeyReleaseEvent( QKeyEvent * );
    virtual void widgetEnterEvent( QEvent * );
    virtual void widgetLeaveEvent( QEvent * );
pixhawk's avatar
pixhawk committed
309

Bryant's avatar
Bryant committed
310
311
    virtual void stretchSelection( const QSize &oldSize,
                                   const QSize &newSize );
pixhawk's avatar
pixhawk committed
312
313
314

    virtual void updateDisplay();

Bryant's avatar
Bryant committed
315
316
317
318
    const QwtWidgetOverlay *rubberBandOverlay() const;
    const QwtWidgetOverlay *trackerOverlay() const;

    const QPolygon &pickedPoints() const;
pixhawk's avatar
pixhawk committed
319
320

private:
Bryant's avatar
Bryant committed
321
    void init( QWidget *, RubberBand rubberBand, DisplayMode trackerMode );
pixhawk's avatar
pixhawk committed
322

Bryant's avatar
Bryant committed
323
    void setMouseTracking( bool );
pixhawk's avatar
pixhawk committed
324
325
326
327

    class PrivateData;
    PrivateData *d_data;
};
328

pixhawk's avatar
pixhawk committed
329
#endif