File indexing completed on 2024-06-02 05:19:16

 /*
  *  spinbox.h  -  spin box with shift-click step value and read-only option
  *  Program:  kalarm
  *  SPDX-FileCopyrightText: 2002-2023 David Jarvie <djarvie@kde.org>
  *
  *  SPDX-License-Identifier: GPL-2.0-or-later
  */
 
 #pragma once
 
 #include <QSpinBox>
 class QEvent;
 class QStyle;
 class QStyleOptionSpinBox;
 
 
 /**
  *  @short Spin box with accelerated shift or control key stepping, and read-only option.
  *
  *  The SpinBox class provides a QSpinBox with accelerated stepping using the shift or
  *  control key.
  *
  *  A separate step increment may optionally be specified for use when the shift or
  *  control key is held down. Typically this would be larger than the normal step. Then,
  *  when the user clicks the spin buttons, he/she can increment or decrement the value
  *  faster by holding the shift key down.
  *
  *  The widget may be set as read-only. This has the same effect as disabling it, except
  *  that its appearance is unchanged.
  *
  *  @author David Jarvie <djarvie@kde.org>
  */
 class SpinBox : public QSpinBox
 {
     Q_OBJECT
 public:
     /** Constructor.
      *  @param parent The parent object of this widget.
      */
     explicit SpinBox(QWidget* parent = nullptr);
 
     /** Constructor.
      *  @param minValue The minimum value which the spin box can have.
      *  @param maxValue The maximum value which the spin box can have.
      *  @param parent The parent object of this widget.
      */
     SpinBox(int minValue, int maxValue, QWidget* parent = nullptr);
 
     ~SpinBox() override;
 
     /** Returns true if the widget is read only. */
     bool         isReadOnly() const                    { return mReadOnly; }
 
     /** Sets whether the spin box can be changed by the user.
      *  @param readOnly True to set the widget read-only, false to set it read-write.
      */
     virtual void setReadOnly(bool readOnly);
 
     /** Returns whether the spin box value text is selected when its value is stepped. */
     bool         selectOnStep() const                  { return mSelectOnStep; }
 
     /** Sets whether the spin box value text should be selected when its value is stepped. */
     void         setSelectOnStep(bool sel)             { mSelectOnStep = sel; }
 
     /** Adds a value to the current value of the spin box. */
     void         addValue(int change)                  { addValue(change, false); }
 
     /** Returns the minimum value of the spin box. */
     int          minimum() const                       { return mMinValue; }
 
     /** Returns the maximum value of the spin box. */
     int          maximum() const                       { return mMaxValue; }
 
     /** Sets the minimum value of the spin box. */
     void         setMinimum(int val);
 
     /** Sets the maximum value of the spin box. */
     void         setMaximum(int val);
 
     /** Sets the minimum and maximum values of the spin box. */
     void         setRange(int minValue, int maxValue)  { setMinimum(minValue);  setMaximum(maxValue); }
 
     /** Returns the specified value clamped to the range of the spin box. */
     int          bound(int val) const;
 
     /** Called whenever the user triggers a step, to adjust the value of
      *  the spin box by the unshifted increment.
      */
     void         stepBy(int steps) override;
 
     /** Returns the unshifted step increment, i.e. the amount by which the spin box value
      *  changes when a spin button is clicked without the shift or control key being pressed.
      */
     int          singleStep() const                    { return mLineStep; }
 
     /** Sets the unshifted step increment, i.e. the amount by which the spin box value
      *  changes when a spin button is clicked without the shift or control key being pressed.
      */
     void         setSingleStep(int step);
 
     /** Returns the shifted step increment, i.e. the amount by which the spin box value
      *  changes when a spin button is clicked while the shift key is pressed.
      */
     int          singleShiftStep() const               { return mLineShiftStep; }
 
     /** Sets the shifted step increment, i.e. the amount by which the spin box value
      *  changes when a spin button is clicked while the shift key is pressed.
      */
     void         setSingleShiftStep(int step);
 
     /** Returns the control step increment, i.e. the amount by which the spin box value
      *  changes when a spin button is clicked while the control key is pressed.
      *  @return  control key step increment, or 0 if none has been set.
      */
     int          singleControlStep() const             { return mLineControlStep; }
 
     /** Returns whether control steps should always set the value to a multiple of
      *  the control step increment.
      */
     bool         modControlStep() const                { return mModControlStep; }
 
     /** Sets the control step increment, i.e. the amount by which the spin box value
      *  changes when a spin button is clicked while the control key is pressed.
      *  By default, Qt uses the single step increment multiplied by 10.
      *  @param step Increment when control key is pressed, or 0 to use default Qt
      *              handling which multiplies the default step by 10.
      *  @param mod  Control steps should always set value to multiple of @p step.
      */
     void         setSingleControlStep(int step, bool mod = true);
 
     /** Returns the rectangle containing the up arrow. */
     QRect        upRect() const;
 
     /** Returns the rectangle containing the down arrow. */
     QRect        downRect() const;
 
     /** Returns the rectangle containing the up and down arrows. */
     QRect        upDownRect() const;
 
     /** Sets whether the edit field is displayed. */
     void         setUpDownOnly(bool only)              { mUpDownOnly = only; }
 
     /** Initialise a QStyleOptionSpinBox with this instance's details. */
     void         initStyleOption(QStyleOptionSpinBox*) const override;
 
 Q_SIGNALS:
     /** Signal emitted when the spin box's value is stepped (by the shifted or unshifted increment).
      *  @param step The requested step in the spin box's value. Note that the actual change in value
      *              may have been less than this.
      *  @param modified Qt has automatically modified the step due to the control key.
      */
     void         stepped(int step, bool control);
 
 protected:
     /** Returns the initial adjustment to the value for a shift step up or down.
      * The default is to step up or down to the nearest multiple of the shift
      * increment, so the adjustment returned is for stepping up the decrement
      * required to round down to a multiple of the shift increment <= current value,
      * or for stepping down the increment required to round up to a multiple of the
      * shift increment >= current value.
      * This method's caller then adjusts the resultant value if necessary to cater
      * for the widget's minimum/maximum value, and wrapping.
      * This should really be a static method, but it needs to be virtual...
      */
     virtual int  shiftStepAdjustment(int oldValue, int shiftStep);
 
     /** Receives events destined for the spin widget or for the edit field. */
     bool         eventFilter(QObject*, QEvent*) override;
 
     void         paintEvent(QPaintEvent*) override;
     void         focusOutEvent(QFocusEvent*) override;
     void         mousePressEvent(QMouseEvent*) override;
     void         mouseDoubleClickEvent(QMouseEvent*) override;
     void         mouseReleaseEvent(QMouseEvent*) override;
     void         mouseMoveEvent(QMouseEvent*) override;
     void         keyPressEvent(QKeyEvent*) override;
     void         keyReleaseEvent(QKeyEvent*) override;
     void         wheelEvent(QWheelEvent*) override;
 
 private Q_SLOTS:
     void         textEdited();
     void         valueChange();
 private:
     enum class Modifier { None, Shift, Control };
 
     void         init();
     void         addValue(int change, bool current);
     int          whichButton(const QPoint&);
     bool         setShiftStepping(Modifier, int currentButton);
     bool         clickEvent(QMouseEvent*);
     bool         keyEvent(QKeyEvent*);
     static Modifier getModifier(Qt::KeyboardModifiers);
 
     enum { NO_BUTTON, UP, DOWN };
 
     int          mMinValue;
     int          mMaxValue;
     int          mLineStep;                  // step when spin arrows are pressed
     int          mLineShiftStep;             // step when spin arrows are pressed with shift key
     int          mLineControlStep {0};       // step when spin arrows are pressed with control key
     int          mCurrentButton {NO_BUTTON}; // current spin widget button
     Modifier     mMouseKey {Modifier::None}; // which modifier key applies while left button is being held down
     QStyle*      mControlStyle {nullptr};    // style to prevent Qt multiplying control step by 10
     bool         mShiftMinBound {false};     // true if a temporary minimum bound has been set during shift stepping
     bool         mShiftMaxBound {false};     // true if a temporary maximum bound has been set during shift stepping
     bool         mSelectOnStep {true};       // select the editor text whenever spin buttons are clicked (default)
     bool         mModControlStep {true};     // control steps set value to multiple of step
     bool         mUpDownOnly {false};        // true if edit field isn't displayed
     bool         mReadOnly {false};          // value cannot be changed
     bool         mSuppressSignals {false};
     bool         mEdited {false};            // text field has been edited
 };
 
 // vim: et sw=4: