ground/gcs/src/libs/qwt/src/qwt_picker.h

   1 /* -*- mode: C++ ; c-file-style: "stroustrup" -*- *****************************
   2  * Qwt Widget Library
   3  * Copyright (C) 1997   Josef Wilgen
   4  * Copyright (C) 2002   Uwe Rathmann
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the Qwt License, Version 1.0
   8  *****************************************************************************/
   9
  10 #ifndef QWT_PICKER
  11 #define QWT_PICKER 1
  12
  13 #include "qwt_global.h"
  14 #include "qwt_text.h"
  15 #include "qwt_event_pattern.h"
  16 #include <qobject.h>
  17 #include <qpen.h>
  18 #include <qfont.h>
  19 #include <qrect.h>
  20 #include <qpainterpath.h>
  21
  22 class QWidget;
  23 class QMouseEvent;
  24 class QWheelEvent;
  25 class QKeyEvent;
  26 class QwtPickerMachine;
  27 class QwtWidgetOverlay;
  28
  29 /*!
  30   \brief QwtPicker provides selections on a widget
  31
  32   QwtPicker filters all enter, leave, mouse and keyboard events of a widget
  33   and translates them into an array of selected points.
  34
  35   The way how the points are collected depends on type of state machine
  36   that is connected to the picker. Qwt offers a couple of predefined
  37   state machines for selecting:
  38
  39   - Nothing\n
  40     QwtPickerTrackerMachine
  41   - Single points\n
  42     QwtPickerClickPointMachine, QwtPickerDragPointMachine
  43   - Rectangles\n
  44     QwtPickerClickRectMachine, QwtPickerDragRectMachine
  45   - Polygons\n
  46     QwtPickerPolygonMachine
  47
  48   While these state machines cover the most common ways to collect points
  49   it is also possible to implement individual machines as well.
  50
  51   QwtPicker translates the picked points into a selection using the
  52   adjustedPoints() method. adjustedPoints() is intended to be reimplemented
  53   to fix up the selection according to application specific requirements.
  54   (F.e. when an application accepts rectangles of a fixed aspect ratio only.)
  55
  56   Optionally QwtPicker support the process of collecting points by a
  57   rubber band and tracker displaying a text for the current mouse
  58   position.
  59
  60   \par Example
  61   \verbatim #include <qwt_picker.h>
  62 #include <qwt_picker_machine.h>
  63
  64 QwtPicker *picker = new QwtPicker(widget);
  65 picker->setStateMachine(new QwtPickerDragRectMachine);
  66 picker->setTrackerMode(QwtPicker::ActiveOnly);
  67 picker->setRubberBand(QwtPicker::RectRubberBand); \endverbatim\n
  68
  69   The state machine triggers the following commands:
  70
  71   - begin()\n
  72     Activate/Initialize the selection.
  73   - append()\n
  74     Add a new point
  75   - move() \n
  76     Change the position of the last point.
  77   - remove()\n
  78     Remove the last point.
  79   - end()\n
  80     Terminate the selection and call accept to validate the picked points.
  81
  82   The picker is active (isActive()), between begin() and end().
  83   In active state the rubber band is displayed, and the tracker is visible
  84   in case of trackerMode is ActiveOnly or AlwaysOn.
  85
  86   The cursor can be moved using the arrow keys. All selections can be aborted
  87   using the abort key. (QwtEventPattern::KeyPatternCode)
  88
  89   \warning In case of QWidget::NoFocus the focus policy of the observed
  90            widget is set to QWidget::WheelFocus and mouse tracking
  91            will be manipulated while the picker is active,
  92            or if trackerMode() is AlwayOn.
  93 */
  94
  95 class QWT_EXPORT QwtPicker: public QObject, public QwtEventPattern
  96 {
  97     Q_OBJECT
  98
  99     Q_ENUMS( RubberBand DisplayMode ResizeMode )
 100
 101     Q_PROPERTY( bool isEnabled READ isEnabled WRITE setEnabled )
 102     Q_PROPERTY( ResizeMode resizeMode READ resizeMode WRITE setResizeMode )
 103
 104     Q_PROPERTY( DisplayMode trackerMode READ trackerMode WRITE setTrackerMode )
 105     Q_PROPERTY( QPen trackerPen READ trackerPen WRITE setTrackerPen )
 106     Q_PROPERTY( QFont trackerFont READ trackerFont WRITE setTrackerFont )
 107
 108     Q_PROPERTY( RubberBand rubberBand READ rubberBand WRITE setRubberBand )
 109     Q_PROPERTY( QPen rubberBandPen READ rubberBandPen WRITE setRubberBandPen )
 110
 111 public:
 112     /*!
 113       Rubber band style
 114
 115       The default value is QwtPicker::NoRubberBand.
 116       \sa setRubberBand(), rubberBand()
 117     */
 118
 119     enum RubberBand
 120     {
 121         //! No rubberband.
 122         NoRubberBand = 0,
 123
 124         //! A horizontal line ( only for QwtPickerMachine::PointSelection )
 125         HLineRubberBand,
 126
 127         //! A vertical line ( only for QwtPickerMachine::PointSelection )
 128         VLineRubberBand,
 129
 130         //! A crosshair ( only for QwtPickerMachine::PointSelection )
 131         CrossRubberBand,
 132
 133         //! A rectangle ( only for QwtPickerMachine::RectSelection )
 134         RectRubberBand,
 135
 136         //! An ellipse ( only for QwtPickerMachine::RectSelection )
 137         EllipseRubberBand,
 138
 139         //! A polygon ( only for QwtPickerMachine::PolygonSelection )
 140         PolygonRubberBand,
 141
 142         /*!
 143           Values >= UserRubberBand can be used to define additional
 144           rubber bands.
 145          */
 146         UserRubberBand = 100
 147     };
 148
 149     /*!
 150       \brief Display mode
 151       \sa setTrackerMode(), trackerMode(), isActive()
 152     */
 153     enum DisplayMode
 154     {
 155         //! Display never
 156         AlwaysOff,
 157
 158         //! Display always
 159         AlwaysOn,
 160
 161         //! Display only when the selection is active
 162         ActiveOnly
 163     };
 164
 165     /*!
 166       Controls what to do with the selected points of an active
 167          selection when the observed widget is resized.
 168
 169       The default value is QwtPicker::Stretch.
 170       \sa setResizeMode()
 171     */
 172
 173     enum ResizeMode
 174     {
 175         //! All points are scaled according to the new size,
 176         Stretch,
 177
 178         //! All points remain unchanged.
 179         KeepSize
 180     };
 181
 182     explicit QwtPicker( QWidget *parent );
 183     explicit QwtPicker( RubberBand rubberBand,
 184                         DisplayMode trackerMode, QWidget * );
 185
 186     virtual ~QwtPicker();
 187
 188     void setStateMachine( QwtPickerMachine * );
 189     const QwtPickerMachine *stateMachine() const;
 190     QwtPickerMachine *stateMachine();
 191
 192     void setRubberBand( RubberBand );
 193     RubberBand rubberBand() const;
 194
 195     void setTrackerMode( DisplayMode );
 196     DisplayMode trackerMode() const;
 197
 198     void setResizeMode( ResizeMode );
 199     ResizeMode resizeMode() const;
 200
 201     void setRubberBandPen( const QPen & );
 202     QPen rubberBandPen() const;
 203
 204     void setTrackerPen( const QPen & );
 205     QPen trackerPen() const;
 206
 207     void setTrackerFont( const QFont & );
 208     QFont trackerFont() const;
 209
 210     bool isEnabled() const;
 211     bool isActive() const;
 212
 213     virtual bool eventFilter( QObject *, QEvent * );
 214
 215     QWidget *parentWidget();
 216     const QWidget *parentWidget() const;
 217
 218     virtual QPainterPath pickArea() const;
 219
 220     virtual void drawRubberBand( QPainter * ) const;
 221     virtual void drawTracker( QPainter * ) const;
 222
 223     virtual QRegion rubberBandMask() const;
 224
 225     virtual QwtText trackerText( const QPoint &pos ) const;
 226     QPoint trackerPosition() const;
 227     virtual QRect trackerRect( const QFont & ) const;
 228
 229     QPolygon selection() const;
 230
 231 public Q_SLOTS:
 232     void setEnabled( bool );
 233
 234 Q_SIGNALS:
 235     /*!
 236       A signal indicating, when the picker has been activated.
 237       Together with setEnabled() it can be used to implement
 238       selections with more than one picker.
 239
 240       \param on True, when the picker has been activated
 241     */
 242     void activated( bool on );
 243
 244     /*!
 245       A signal emitting the selected points,
 246       at the end of a selection.
 247
 248       \param polygon Selected points
 249     */
 250     void selected( const QPolygon &polygon );
 251
 252     /*!
 253       A signal emitted when a point has been appended to the selection
 254
 255       \param pos Position of the appended point.
 256       \sa append(). moved()
 257     */
 258     void appended( const QPoint &pos );
 259
 260     /*!
 261       A signal emitted whenever the last appended point of the
 262       selection has been moved.
 263
 264       \param pos Position of the moved last point of the selection.
 265       \sa move(), appended()
 266     */
 267     void moved( const QPoint &pos );
 268
 269     /*!
 270       A signal emitted whenever the last appended point of the
 271       selection has been removed.
 272
 273       \param pos Position of the point, that has been removed
 274       \sa remove(), appended()
 275     */
 276     void removed( const QPoint &pos );
 277     /*!
 278       A signal emitted when the active selection has been changed.
 279       This might happen when the observed widget is resized.
 280
 281       \param selection Changed selection
 282       \sa stretchSelection()
 283     */
 284     void changed( const QPolygon &selection );
 285
 286 protected:
 287     virtual QPolygon adjustedPoints( const QPolygon & ) const;
 288
 289     virtual void transition( const QEvent * );
 290
 291     virtual void begin();
 292     virtual void append( const QPoint & );
 293     virtual void move( const QPoint & );
 294     virtual void remove();
 295     virtual bool end( bool ok = true );
 296
 297     virtual bool accept( QPolygon & ) const;
 298     virtual void reset();
 299
 300     virtual void widgetMousePressEvent( QMouseEvent * );
 301     virtual void widgetMouseReleaseEvent( QMouseEvent * );
 302     virtual void widgetMouseDoubleClickEvent( QMouseEvent * );
 303     virtual void widgetMouseMoveEvent( QMouseEvent * );
 304     virtual void widgetWheelEvent( QWheelEvent * );
 305     virtual void widgetKeyPressEvent( QKeyEvent * );
 306     virtual void widgetKeyReleaseEvent( QKeyEvent * );
 307     virtual void widgetEnterEvent( QEvent * );
 308     virtual void widgetLeaveEvent( QEvent * );
 309
 310     virtual void stretchSelection( const QSize &oldSize,
 311                                    const QSize &newSize );
 312
 313     virtual void updateDisplay();
 314
 315     const QwtWidgetOverlay *rubberBandOverlay() const;
 316     const QwtWidgetOverlay *trackerOverlay() const;
 317
 318     const QPolygon &pickedPoints() const;
 319
 320 private:
 321     void init( QWidget *, RubberBand rubberBand, DisplayMode trackerMode );
 322
 323     void setMouseTracking( bool );
 324
 325     class PrivateData;
 326     PrivateData *d_data;
 327 };
 328
 329 #endif