1/* This file is part of the KDE libraries
2 * Copyright (c) 1997 Patrick Dowler <dowler@morgul.fsh.uvic.ca>
3 * Copyright (c) 2000 Dirk Mueller <mueller@kde.org>
4 * Copyright (c) 2002 Marc Mutz <mutz@kde.org>
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Library General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
10 *
11 * This library 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 GNU
14 * Library General Public License for more details.
15 *
16 * You should have received a copy of the GNU Library General Public License
17 * along with this library; see the file COPYING.LIB. If not, write to
18 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 * Boston, MA 02110-1301, USA.
20 */
21
22#ifndef K_NUMINPUT_H
23#define K_NUMINPUT_H
24
25#include <kdeui_export.h>
26
27#include <QtGui/QWidget>
28#include <QtGui/QSpinBox>
29
30class QSlider;
31class QSpinBox;
32class QValidator;
33
34class KIntSpinBox;
35class KNumInputPrivate;
36class KLocalizedString;
37
38/**
39 * You need to inherit from this class if you want to implement K*NumInput
40 * for a different variable type
41 *
42 */
43class KDEUI_EXPORT KNumInput : public QWidget
44{
45 Q_OBJECT
46 Q_PROPERTY( QString label READ label WRITE setLabel )
47public:
48 /**
49 * Default constructor
50 * @param parent If parent is 0, the new widget becomes a top-level
51 * window. If parent is another widget, this widget becomes a child
52 * window inside parent. The new widget is deleted when its parent is deleted.
53 */
54 explicit KNumInput(QWidget* parent=0);
55
56 /**
57 * @param below A pointer to another KNumInput.
58 * @param parent parent widget
59 * \deprecated - use the version without the below parameter instead
60 */
61#ifndef KDE_NO_DEPRECATED
62 KDE_CONSTRUCTOR_DEPRECATED KNumInput(QWidget *parent, KNumInput* below);
63#endif
64
65 /**
66 * Destructor
67 */
68 ~KNumInput();
69
70 /**
71 * Sets the text and alignment of the main description label.
72 *
73 * @param label The text of the label.
74 * Use QString() to remove an existing one.
75 *
76 * @param a The alignment of the label (Qt::Alignment).
77 * Default is @p Qt:AlignLeft | @p Qt:AlignTop.
78 *
79 * The vertical alignment flags have special meaning with this
80 * widget:
81 *
82 * @li @p Qt:AlignTop The label is placed above the edit/slider
83 * @li @p Qt:AlignVCenter The label is placed left beside the edit
84 * @li @p Qt:AlignBottom The label is placed below the edit/slider
85 *
86 */
87 virtual void setLabel(const QString & label, Qt::Alignment a = Qt::AlignLeft | Qt::AlignTop);
88
89 /**
90 * @return the text of the label.
91 */
92 QString label() const;
93
94 /**
95 * @return if the num input has a slider.
96 */
97 bool showSlider() const;
98
99 /**
100 * Sets the spacing of tickmarks for the slider.
101 *
102 * @param minor Minor tickmark separation.
103 * @param major Major tickmark separation.
104 */
105 void setSteps(int minor, int major);
106
107 /**
108 * Returns a size which fits the contents of the control.
109 *
110 * @return the preferred size necessary to show the control
111 */
112 virtual QSize sizeHint() const;
113
114protected:
115 /**
116 * @return the slider widget.
117 * @internal
118 */
119 QSlider *slider() const;
120
121 /**
122 * Call this function whenever you change something in the geometry
123 * of your KNumInput child.
124 *
125 */
126 void layout(bool deep);
127
128 /**
129 * You need to overwrite this method and implement your layout
130 * calculations there.
131 *
132 * See KIntNumInput::doLayout and KDoubleNumInput::doLayout implementation
133 * for details.
134 *
135 */
136 virtual void doLayout() = 0;
137
138private:
139 friend class KNumInputPrivate;
140 KNumInputPrivate * const d;
141
142 Q_DISABLE_COPY(KNumInput)
143};
144
145/* ------------------------------------------------------------------------ */
146
147/**
148 * @short An input widget for integer numbers, consisting of a spinbox and a slider.
149 *
150 * KIntNumInput combines a QSpinBox and optionally a QSlider
151 * with a label to make an easy to use control for setting some integer
152 * parameter. This is especially nice for configuration dialogs,
153 * which can have many such combinated controls.
154 *
155 * The slider is created only when the user specifies a range
156 * for the control using the setRange function or when the user
157 * calls setSliderEnabled.
158 *
159 * A special feature of KIntNumInput, designed specifically for
160 * the situation when there are several KIntNumInputs in a column,
161 * is that you can specify what portion of the control is taken by the
162 * QSpinBox (the remaining portion is used by the slider). This makes
163 * it very simple to have all the sliders in a column be the same size.
164 *
165 * It uses KIntValidator validator class. KIntNumInput enforces the
166 * value to be in the given range, and can display it in any base
167 * between 2 and 36.
168 *
169 * \image html kintnuminput.png "KDE Int Number Input Spinbox"
170 */
171
172class KDEUI_EXPORT KIntNumInput : public KNumInput
173{
174 Q_OBJECT
175 Q_PROPERTY( int value READ value WRITE setValue NOTIFY valueChanged USER true )
176 Q_PROPERTY( int minimum READ minimum WRITE setMinimum )
177 Q_PROPERTY( int maximum READ maximum WRITE setMaximum )
178 Q_PROPERTY( int singleStep READ singleStep WRITE setSingleStep )
179 Q_PROPERTY( int referencePoint READ referencePoint WRITE setReferencePoint )
180 Q_PROPERTY( double relativeValue READ relativeValue WRITE setRelativeValue )
181 Q_PROPERTY( QString suffix READ suffix WRITE setSuffix )
182 Q_PROPERTY( QString prefix READ prefix WRITE setPrefix )
183 Q_PROPERTY( QString specialValueText READ specialValueText WRITE setSpecialValueText )
184 Q_PROPERTY( bool sliderEnabled READ showSlider WRITE setSliderEnabled )
185
186public:
187 /**
188 * Constructs an input control for integer values
189 * with base 10 and initial value 0.
190 */
191 explicit KIntNumInput(QWidget *parent=0);
192 /**
193 * Constructor
194 * It constructs a QSpinBox that allows the input of integer numbers
195 * in the range of -INT_MAX to +INT_MAX. To set a descriptive label,
196 * use setLabel(). To enforce the value being in a range and optionally to
197 * attach a slider to it, use setRange().
198 *
199 * @param value initial value for the control
200 * @param base numeric base used for display
201 * @param parent parent QWidget
202 */
203 explicit KIntNumInput(int value, QWidget *parent=0,int base = 10);
204
205 /**
206 * Constructor
207 *
208 * the difference to the one above is the "below" parameter. It tells
209 * this instance that it is visually put below some other KNumInput widget.
210 * Note that these two KNumInput's need not to have the same parent widget
211 * or be in the same layout group.
212 * The effect is that it'll adjust its layout in correspondence
213 * with the layout of the other KNumInput's (you can build an arbitrary long
214 * chain).
215 *
216 * @param below append KIntNumInput to the KNumInput chain
217 * @param value initial value for the control
218 * @param base numeric base used for display
219 * @param parent parent QWidget
220 *
221 * \deprecated use the version without the below parameter instead.
222 */
223#ifndef KDE_NO_DEPRECATED
224 KDE_CONSTRUCTOR_DEPRECATED KIntNumInput(KNumInput* below, int value, QWidget *parent, int base = 10);
225#endif
226
227 /**
228 * Destructor
229 *
230 *
231 */
232 virtual ~KIntNumInput();
233
234 /**
235 * @return the current value.
236 */
237 int value() const;
238
239 /**
240 * @return the curent value in units of the referencePoint.
241 */
242 double relativeValue() const;
243
244 /**
245 * @return the current reference point
246 */
247 int referencePoint() const;
248
249 /**
250 * @return the suffix displayed behind the value.
251 * @see setSuffix()
252 */
253 QString suffix() const;
254 /**
255 * @return the prefix displayed in front of the value.
256 * @see setPrefix()
257 */
258 QString prefix() const;
259 /**
260 * @return the string displayed for a special value.
261 * @see setSpecialValueText()
262 */
263 QString specialValueText() const;
264
265 /**
266 * Sets the allowed input range and the step size for the slider and the
267 * spin box.
268 *
269 * @param min minimum value
270 * @param max maximum value
271 * @param step step size
272 */
273 void setRange(int min, int max, int singleStep=1);
274
275 /**
276 * @deprecated Use the other setRange function and setSliderEnabled instead
277 */
278#ifndef KDE_NO_DEPRECATED
279 KDE_DEPRECATED void setRange(int min, int max, int singleStep, bool slider);
280#endif
281
282 /**
283 * @param enabled Show the slider
284 * @default enabled
285 */
286 void setSliderEnabled(bool enabled=true);
287
288 /**
289 * Sets the minimum value.
290 */
291 void setMinimum(int min);
292 /**
293 * @return the minimum value.
294 */
295 int minimum() const;
296 /**
297 * Sets the maximum value.
298 */
299 void setMaximum(int max);
300 /**
301 * @return the maximum value.
302 */
303 int maximum() const;
304
305 /**
306 * @return the step of the spin box
307 */
308 int singleStep() const;
309
310 /**
311 * @return the step of the spin box
312 */
313 void setSingleStep(int step);
314
315 /**
316 * Sets the special value text. If set, the SpinBox will display
317 * this text instead of the numeric value whenever the current
318 * value is equal to minVal(). Typically this is used for indicating
319 * that the choice has a special (default) meaning.
320 */
321 void setSpecialValueText(const QString& text);
322
323 virtual void setLabel(const QString & label, Qt::Alignment a = Qt::AlignLeft | Qt::AlignTop);
324
325 /**
326 * This method returns the minimum size necessary to display the
327 * control. The minimum size is enough to show all the labels
328 * in the current font (font change may invalidate the return value).
329 *
330 * @return the minimum size necessary to show the control
331 */
332 virtual QSize minimumSizeHint() const;
333
334public Q_SLOTS:
335 /**
336 * Sets the value of the control.
337 */
338 void setValue(int);
339
340 /**
341 * Sets the value in units of the referencePoint
342 */
343 void setRelativeValue(double);
344
345 /**
346 * Sets the reference point for relativeValue.
347 */
348 void setReferencePoint(int);
349
350 /**
351 * Sets the suffix to @p suffix.
352 * Use QString() to disable this feature.
353 * Formatting has to be provided (e.g. a space separator between the
354 * prepended @p value and the suffix's text has to be provided
355 * as the first character in the suffix).
356 *
357 * @see QSpinBox::setSuffix(), #setPrefix()
358 */
359 void setSuffix(const QString &suffix);
360
361 /**
362 * Sets the suffix to @p suffix.
363 * Use this to add a plural-aware suffix, e.g. by using ki18np("singular", "plural").
364 *
365 * @since 4.3
366 */
367 void setSuffix(const KLocalizedString &suffix);
368
369 /**
370 * Sets the prefix to @p prefix.
371 * Use QString() to disable this feature.
372 * Formatting has to be provided (see above).
373 *
374 * @see QSpinBox::setPrefix(), #setSuffix()
375 */
376 void setPrefix(const QString &prefix);
377
378 /**
379 * sets focus to the edit widget and marks all text in if mark == true
380 *
381 */
382 void setEditFocus( bool mark = true );
383
384Q_SIGNALS:
385 /**
386 * Emitted every time the value changes (by calling setValue() or
387 * by user interaction).
388 */
389 void valueChanged(int);
390
391 /**
392 * Emitted whenever valueChanged is. Contains the change
393 * relative to the referencePoint.
394 */
395 void relativeValueChanged(double);
396
397private Q_SLOTS:
398 void spinValueChanged(int);
399 void slotEmitRelativeValueChanged(int);
400
401protected:
402 /**
403 * @return the spin box widget.
404 * @internal
405 */
406 QSpinBox *spinBox() const;
407
408 virtual void doLayout();
409 void resizeEvent ( QResizeEvent * );
410
411private:
412 void init(int value, int _base);
413
414private:
415 class KIntNumInputPrivate;
416 friend class KIntNumInputPrivate;
417 KIntNumInputPrivate * const d;
418
419 Q_DISABLE_COPY(KIntNumInput)
420};
421
422
423/* ------------------------------------------------------------------------ */
424
425class KDoubleLine;
426
427/**
428 * @short An input control for real numbers, consisting of a spinbox and a slider.
429 *
430 * KDoubleNumInput combines a QSpinBox and optionally a QSlider
431 * with a label to make an easy to use control for setting some float
432 * parameter. This is especially nice for configuration dialogs,
433 * which can have many such combinated controls.
434 *
435 * The slider is created only when the user specifies a range
436 * for the control using the setRange function with the slider
437 * parameter set to "true".
438 *
439 * A special feature of KDoubleNumInput, designed specifically for
440 * the situation when there are several instances in a column,
441 * is that you can specify what portion of the control is taken by the
442 * QSpinBox (the remaining portion is used by the slider). This makes
443 * it very simple to have all the sliders in a column be the same size.
444 *
445 * \image html kdoublenuminput.png "KDE Double Number Input Spinbox"
446 *
447 * @see KIntNumInput
448 */
449
450class KDEUI_EXPORT KDoubleNumInput : public KNumInput
451{
452 Q_OBJECT
453 Q_PROPERTY( double value READ value WRITE setValue NOTIFY valueChanged USER true )
454 Q_PROPERTY( double minimum READ minimum WRITE setMinimum )
455 Q_PROPERTY( double maximum READ maximum WRITE setMaximum )
456 Q_PROPERTY( double singleStep READ singleStep WRITE setSingleStep )
457 Q_PROPERTY( QString suffix READ suffix WRITE setSuffix )
458 Q_PROPERTY( QString prefix READ prefix WRITE setPrefix )
459 Q_PROPERTY( QString specialValueText READ specialValueText WRITE setSpecialValueText )
460 Q_PROPERTY( int decimals READ decimals WRITE setDecimals )
461 Q_PROPERTY( double referencePoint READ referencePoint WRITE setReferencePoint )
462 Q_PROPERTY( double relativeValue READ relativeValue WRITE setRelativeValue )
463 Q_PROPERTY( bool sliderEnabled READ showSlider WRITE setSliderEnabled )
464 Q_PROPERTY( double exponentRatio READ exponentRatio WRITE setExponentRatio )
465
466public:
467 /**
468 * Constructs an input control for double values
469 * with initial value 0.00.
470 */
471 explicit KDoubleNumInput(QWidget *parent = 0);
472
473 /**
474 * Constructor
475 *
476 * @param lower lower boundary value
477 * @param upper upper boundary value
478 * @param value initial value for the control
479 * @param singleStep step size to use for up/down arrow clicks
480 * @param precision number of digits after the decimal point
481 * @param parent parent QWidget
482 */
483 KDoubleNumInput(double lower, double upper, double value, QWidget *parent=0,double singleStep=0.01,
484 int precision=2);
485
486 /**
487 * destructor
488 */
489 virtual ~KDoubleNumInput();
490
491
492 /**
493 * Constructor
494 *
495 * the difference here is the "below" parameter. It tells this
496 * instance that it is visually put below some other KNumInput
497 * widget. Note that these two KNumInput's need not to have the
498 * same parent widget or be in the same layout group. The effect
499 * is that it'll adjust its layout in correspondence with the
500 * layout of the other KNumInput's (you can build an arbitrary long
501 * chain).
502 *
503 * @param below append KDoubleNumInput to the KDoubleNumInput chain
504 * @param lower lower boundary value
505 * @param upper upper boundary value
506 * @param value initial value for the control
507 * @param singleStep step size to use for up/down arrow clicks
508 * @param precision number of digits after the decimal point
509 * @param parent parent QWidget
510 *
511 * \deprecated use the version without below instead
512 */
513#ifndef KDE_NO_DEPRECATED
514 KDE_CONSTRUCTOR_DEPRECATED KDoubleNumInput(KNumInput* below,
515 double lower, double upper, double value, QWidget *parent=0,double singleStep=0.02,
516 int precision=2);
517#endif
518
519 /**
520 * @return the current value.
521 */
522 double value() const;
523
524 /**
525 * @return the suffix.
526 * @see setSuffix()
527 */
528 QString suffix() const;
529
530 /**
531 * @return the prefix.
532 * @see setPrefix()
533 */
534 QString prefix() const;
535
536 /**
537 * @return number of decimals.
538 * @see setDecimals()
539 */
540 int decimals() const;
541
542 /**
543 * @return the string displayed for a special value.
544 * @see setSpecialValueText()
545 */
546 QString specialValueText() const;
547
548 /**
549 * @param min minimum value
550 * @param max maximum value
551 * @param singleStep step size for the QSlider
552 * @param slider whether the slider is created or not
553 */
554 void setRange(double min, double max, double singleStep=1, bool slider=true);
555
556 /**
557 * @param enabled Show the slider
558 * @default enabled
559 */
560 void setSliderEnabled(bool enabled);
561
562 /**
563 * Sets the minimum value.
564 */
565 void setMinimum(double min);
566 /**
567 * @return the minimum value.
568 */
569 double minimum() const;
570 /**
571 * Sets the maximum value.
572 */
573 void setMaximum(double max);
574 /**
575 * @return the maximum value.
576 */
577 double maximum() const;
578
579 /**
580 * @return the step of the spin box
581 */
582 double singleStep() const;
583
584 /**
585 * @return the step of the spin box
586 */
587 void setSingleStep(double singleStep);
588
589 /**
590 * Specifies the number of digits to use.
591 */
592 void setDecimals(int decimals);
593
594#ifndef KDE_NO_DEPRECATED
595 KDE_DEPRECATED void setPrecision(int precision) { setDecimals(precision); }
596#endif
597
598 /**
599 * @return the reference point for relativeValue calculation
600 */
601 double referencePoint() const;
602
603 /**
604 * @return the current value in units of referencePoint.
605 */
606 double relativeValue() const;
607
608 /**
609 * Sets the special value text. If set, the spin box will display
610 * this text instead of the numeric value whenever the current
611 * value is equal to minVal(). Typically this is used for indicating
612 * that the choice has a special (default) meaning.
613 */
614 void setSpecialValueText(const QString& text);
615
616 virtual void setLabel(const QString & label, Qt::Alignment a = Qt::AlignLeft | Qt::AlignTop);
617 virtual QSize minimumSizeHint() const;
618
619 /**
620 * @return the value of the exponent use to map the slider to the
621 * spin box.
622 */
623 double exponentRatio() const;
624
625 /**
626 * @param dbl the value of the exponent use to map the slider to the
627 * spin box (dbl need to be strictly positive).
628 */
629 void setExponentRatio(double dbl);
630public Q_SLOTS:
631 /**
632 * Sets the value of the control.
633 */
634 void setValue(double);
635
636 /**
637 * Sets the value in units of referencePoint.
638 */
639 void setRelativeValue(double);
640
641 /**
642 * Sets the reference Point to @p ref. It @p ref == 0, emitting of
643 * relativeValueChanged is blocked and relativeValue
644 * just returns 0.
645 */
646 void setReferencePoint(double ref);
647
648 /**
649 * Sets the suffix to be displayed to @p suffix. Use QString() to disable
650 * this feature. Note that the suffix is attached to the value without any
651 * spacing. So if you prefer to display a space separator, set suffix
652 * to something like " cm".
653 * @see setSuffix()
654 */
655 void setSuffix(const QString &suffix);
656
657 /**
658 * Sets the prefix to be displayed to @p prefix. Use QString() to disable
659 * this feature. Note that the prefix is attached to the value without any
660 * spacing.
661 * @see setPrefix()
662 */
663 void setPrefix(const QString &prefix);
664
665Q_SIGNALS:
666 /**
667 * Emitted every time the value changes (by calling setValue() or
668 * by user interaction).
669 */
670 void valueChanged(double);
671 /**
672 * This is an overloaded member function, provided for
673 * convenience. It essentially behaves like the above function.
674 *
675 * Contains the value in units of referencePoint.
676 */
677 void relativeValueChanged(double);
678
679private Q_SLOTS:
680 void sliderMoved(int);
681 void spinBoxChanged(double);
682 void slotEmitRelativeValueChanged(double);
683
684protected:
685 virtual void doLayout();
686 void resizeEvent ( QResizeEvent * );
687
688 friend class KDoubleLine;
689private:
690 void init(double value, double lower, double upper,
691 double singleStep, int precision);
692 double mapSliderToSpin(int) const;
693 void updateLegacyMembers();
694
695private:
696 class KDoubleNumInputPrivate;
697 friend class KDoubleNumInputPrivate;
698 KDoubleNumInputPrivate * const d;
699
700 Q_DISABLE_COPY(KDoubleNumInput)
701};
702
703
704/* ------------------------------------------------------------------------ */
705
706/**
707 * @short A QSpinBox with support for arbitrary base numbers.
708 *
709 * A QSpinBox with support for arbitrary base numbers
710 * (e.g. hexadecimal).
711 *
712 * The class provides an easy interface to use other
713 * numeric systems than the decimal.
714 *
715 * \image html kintspinbox.png "KDE Integer Input Spinboxes with hexadecimal and binary input"
716 */
717class KDEUI_EXPORT KIntSpinBox : public QSpinBox
718{
719 Q_OBJECT
720 Q_PROPERTY( int base READ base WRITE setBase )
721
722public:
723
724 /**
725 * Constructor.
726 *
727 * Constructs a widget with an integer inputline with a little scrollbar
728 * and a slider, with minimal value 0, maximal value 99, step 1, base 10
729 * and initial value 0.
730 */
731 explicit KIntSpinBox( QWidget *parent = 0 );
732
733 /**
734 * Constructor.
735 *
736 * Constructs a widget with an integer inputline with a little scrollbar
737 * and a slider.
738 *
739 * @param lower The lowest valid value.
740 * @param upper The greatest valid value.
741 * @param singleStep The step size of the scrollbar.
742 * @param value The actual value.
743 * @param base The base of the used number system.
744 * @param parent The parent of the widget.
745 */
746 KIntSpinBox(int lower, int upper, int singleStep, int value, QWidget *parent,int base = 10);
747
748 /**
749 * Destructor.
750 */
751 virtual ~KIntSpinBox();
752
753 /**
754 * Sets the base in which the numbers in the spin box are represented.
755 */
756 void setBase(int base);
757 /**
758 * @return the base in which numbers in the spin box are represented.
759 */
760 int base() const;
761 /**
762 * sets focus and optionally marks all text
763 *
764 */
765 void setEditFocus(bool mark);
766
767 /**
768 * Sets the suffix to @p suffix.
769 * Use this to add a plural-aware suffix, e.g. by using ki18np("singular", "plural").
770 *
771 * @since 4.3
772 */
773 void setSuffix(const KLocalizedString &suffix);
774
775 using QSpinBox::setSuffix;
776
777protected:
778
779 /**
780 * Overloaded the method in QSpinBox
781 * to make use of the base given in the constructor.
782 */
783 virtual QString textFromValue(int) const;
784
785 /**
786 * Overloaded the method in QSpinBox
787 * to make use of the base given in the constructor.
788 */
789 virtual int valueFromText(const QString &text) const;
790
791private:
792 class KIntSpinBoxPrivate;
793 friend class KIntSpinBoxPrivate;
794 KIntSpinBoxPrivate *const d;
795
796 Q_DISABLE_COPY(KIntSpinBox)
797 Q_PRIVATE_SLOT(d, void updateSuffix(int))
798};
799
800#endif // K_NUMINPUT_H
801