kalarm/lib/spinbox.h

   1 /*
   2  *  spinbox.h  -  spin box with shift-click step value and read-only option
   3  *  Program:  kalarm
   4  *  Copyright © 2002-2008 by David Jarvie <djarvie@kde.org>
   5  *
   6  *  This program is free software; you can redistribute it and/or modify
   7  *  it under the terms of the GNU General Public License as published by
   8  *  the Free Software Foundation; either version 2 of the License, or
   9  *  (at your option) any later version.
  10  *
  11  *  This program is distributed in the hope that it will be useful,
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  14  *  GNU General Public License for more details.
  15  *
  16  *  You should have received a copy of the GNU General Public License along
  17  *  with this program; if not, write to the Free Software Foundation, Inc.,
  18  *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  19  */
  20
  21 #ifndef SPINBOX_H
  22 #define SPINBOX_H
  23
  24 #include <QSpinBox>
  25 class QEvent;
  26 class QStyleOptionSpinBox;
  27
  28
  29 /**
  30  *  @short Spin box with accelerated shift key stepping and read-only option.
  31  *
  32  *  The SpinBox class provides a QSpinBox with accelerated stepping using the shift key.
  33  *
  34  *  A separate step increment may optionally be specified for use when the shift key is
  35  *  held down. Typically this would be larger than the normal step. Then, when the user
  36  *  clicks the spin buttons, he/she can increment or decrement the value faster by holding
  37  *  the shift key down.
  38  *
  39  *  The widget may be set as read-only. This has the same effect as disabling it, except
  40  *  that its appearance is unchanged.
  41  *
  42  *  @author David Jarvie <djarvie@kde.org>
  43  */
  44 class SpinBox : public QSpinBox
  45 {
  46         Q_OBJECT
  47     public:
  48         /** Constructor.
  49          *  @param parent The parent object of this widget.
  50          */
  51         explicit SpinBox(QWidget* parent = Q_NULLPTR);
  52         /** Constructor.
  53          *  @param minValue The minimum value which the spin box can have.
  54          *  @param maxValue The maximum value which the spin box can have.
  55          *  @param parent The parent object of this widget.
  56          */
  57         SpinBox(int minValue, int maxValue, QWidget* parent = Q_NULLPTR);
  58         /** Returns true if the widget is read only. */
  59         bool         isReadOnly() const                    { return mReadOnly; }
  60         /** Sets whether the spin box can be changed by the user.
  61          *  @param readOnly True to set the widget read-only, false to set it read-write.
  62          */
  63         virtual void setReadOnly(bool readOnly);
  64         /** Returns whether the spin box value text is selected when its value is stepped. */
  65         bool         selectOnStep() const                  { return mSelectOnStep; }
  66         /** Sets whether the spin box value text should be selected when its value is stepped. */
  67         void         setSelectOnStep(bool sel)             { mSelectOnStep = sel; }
  68         /** Adds a value to the current value of the spin box. */
  69         void         addValue(int change)                  { addValue(change, false); }
  70         /** Returns the minimum value of the spin box. */
  71         int          minimum() const                       { return mMinValue; }
  72         /** Returns the maximum value of the spin box. */
  73         int          maximum() const                       { return mMaxValue; }
  74         /** Sets the minimum value of the spin box. */
  75         void         setMinimum(int val);
  76         /** Sets the maximum value of the spin box. */
  77         void         setMaximum(int val);
  78         /** Sets the minimum and maximum values of the spin box. */
  79         void         setRange(int minValue, int maxValue)  { setMinimum(minValue);  setMaximum(maxValue); }
  80         /** Returns the specified value clamped to the range of the spin box. */
  81         int          bound(int val) const;
  82         /** Called whenever the user triggers a step, to adjust the value of
  83          *  the spin box by the unshifted increment.
  84          */
  85         void         stepBy(int steps) Q_DECL_OVERRIDE;
  86         /** Returns the unshifted step increment, i.e. the amount by which the spin box value
  87          *  changes when a spin button is clicked without the shift key being pressed.
  88          */
  89         int          singleStep() const                    { return mLineStep; }
  90         /** Sets the unshifted step increment, i.e. the amount by which the spin box value
  91          *  changes when a spin button is clicked without the shift key being pressed.
  92          */
  93         void         setSingleStep(int step);
  94         /** Returns the shifted step increment, i.e. the amount by which the spin box value
  95          *  changes when a spin button is clicked while the shift key is pressed.
  96          */
  97         int          singleShiftStep() const               { return mLineShiftStep; }
  98         /** Sets the shifted step increment, i.e. the amount by which the spin box value
  99          *  changes when a spin button is clicked while the shift key is pressed.
 100          */
 101         void         setSingleShiftStep(int step);
 102         /** Returns the rectangle containing the up arrow. */
 103         QRect        upRect() const;
 104         /** Returns the rectangle containing the down arrow. */
 105         QRect        downRect() const;
 106         /** Returns the rectangle containing the up and down arrows. */
 107         QRect        upDownRect() const;
 108         /** Sets whether the edit field is displayed. */
 109         void         setUpDownOnly(bool only)              { mUpDownOnly = only; }
 110         /** Initialise a QStyleOptionSpinBox with this instance's details. */
 111         void         initStyleOption(QStyleOptionSpinBox&) const;
 112
 113     Q_SIGNALS:
 114         /** Signal emitted when the spin box's value is stepped (by the shifted or unshifted increment).
 115          *  @param step The requested step in the spin box's value. Note that the actual change in value
 116          *              may have been less than this.
 117          */
 118         void         stepped(int step);
 119
 120     protected:
 121         /** Returns the initial adjustment to the value for a shift step up or down.
 122          * The default is to step up or down to the nearest multiple of the shift
 123          * increment, so the adjustment returned is for stepping up the decrement
 124          * required to round down to a multiple of the shift increment <= current value,
 125          * or for stepping down the increment required to round up to a multiple of the
 126          * shift increment >= current value.
 127          * This method's caller then adjusts the resultant value if necessary to cater
 128          * for the widget's minimum/maximum value, and wrapping.
 129          * This should really be a static method, but it needs to be virtual...
 130          */
 131         virtual int  shiftStepAdjustment(int oldValue, int shiftStep);
 132         /** Receives events destined for the spin widget or for the edit field. */
 133         bool         eventFilter(QObject*, QEvent*) Q_DECL_OVERRIDE;
 134
 135         void         paintEvent(QPaintEvent*) Q_DECL_OVERRIDE;
 136         void         focusOutEvent(QFocusEvent*) Q_DECL_OVERRIDE;
 137         void         mousePressEvent(QMouseEvent*) Q_DECL_OVERRIDE;
 138         void         mouseDoubleClickEvent(QMouseEvent*) Q_DECL_OVERRIDE;
 139         void         mouseReleaseEvent(QMouseEvent*) Q_DECL_OVERRIDE;
 140         void         mouseMoveEvent(QMouseEvent*) Q_DECL_OVERRIDE;
 141         void         keyPressEvent(QKeyEvent*) Q_DECL_OVERRIDE;
 142         void         keyReleaseEvent(QKeyEvent*) Q_DECL_OVERRIDE;
 143         void         wheelEvent(QWheelEvent*) Q_DECL_OVERRIDE;
 144
 145     private Q_SLOTS:
 146         void         textEdited();
 147         void         valueChange();
 148     private:
 149         void         init();
 150         void         addValue(int change, bool current);
 151         int          whichButton(const QPoint&);
 152         bool         setShiftStepping(bool, int currentButton);
 153         bool         clickEvent(QMouseEvent*);
 154         bool         keyEvent(QKeyEvent*);
 155
 156         enum { NO_BUTTON, UP, DOWN };
 157
 158         int          mMinValue;
 159         int          mMaxValue;
 160         int          mLineStep;         // step when spin arrows are pressed
 161         int          mLineShiftStep;    // step when spin arrows are pressed with shift key
 162         int          mCurrentButton;    // current spin widget button
 163         bool         mShiftMouse;       // true while left button is being held down with shift key
 164         bool         mShiftMinBound;    // true if a temporary minimum bound has been set during shift stepping
 165         bool         mShiftMaxBound;    // true if a temporary maximum bound has been set during shift stepping
 166         bool         mSelectOnStep;     // select the editor text whenever spin buttons are clicked (default)
 167         bool         mUpDownOnly;       // true if edit field isn't displayed
 168         bool         mReadOnly;         // value cannot be changed
 169         bool         mSuppressSignals;
 170         bool         mEdited;           // text field has been edited
 171 };
 172
 173 #endif // SPINBOX_H
 174
 175 // vim: et sw=4: