1/*
2 Copyright (C) 2003 Nadeem Hasan <nhasan@kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License as published by the Free Software Foundation; either
7 version 2 of the License, or (at your option) any later version.
8
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Library General Public License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to
16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 Boston, MA 02110-1301, USA.
18*/
19
20#ifndef KINPUTDIALOG_H
21#define KINPUTDIALOG_H
22
23#include <QtCore/QStringList>
24
25#include <kdeui_export.h>
26
27#include <limits.h>
28#include <float.h>
29
30class QValidator;
31
32/**
33 * The KInputDialog namespace provides simple dialogs to get a single value
34 * from the user. The value can be a string, a number (either an integer or
35 * a float) or an item from a list.
36 *
37 * @author Nadeem Hasan <nhasan@kde.org>
38 */
39namespace KInputDialog
40{
41 /**
42 * Static convenience function to get a string from the user.
43 *
44 * caption is the text that is displayed in the title bar. label is the
45 * text that appears as a label for the line edit. value is the initial
46 * value of the line edit. ok will be set to true if user pressed Ok
47 * and false if user pressed Cancel.
48 *
49 * If you provide a validator, the Ok button is disabled as long as
50 * the validator doesn't return Acceptable. If there is no validator,
51 * the Ok button is enabled whenever the line edit isn't empty. If you
52 * want to accept empty input, create a trivial QValidator that
53 * always returns acceptable, e.g. QRegExpValidator with a regexp
54 * of ".*".
55 *
56 * @param caption Caption of the dialog
57 * @param label Text of the label for the line edit
58 * @param value Initial value of the line edit
59 * @param ok This bool would be set to true if user pressed Ok
60 * @param parent Parent of the dialog widget
61 * @param validator A @ref QValidator to be associated with the line edit
62 * @param mask Mask associated with the line edit. See the
63 * documentation for @ref QLineEdit about masks
64 * @param whatsThis a QWhatsThis text for the input widget.
65 * @param completionList a list of items which should be used for input completion
66 * @return String user entered if Ok was pressed, else a null string
67 */
68 KDEUI_EXPORT QString getText( const QString &caption, const QString &label,
69 const QString &value=QString(), bool *ok=0, QWidget *parent=0,
70 QValidator *validator=0,
71 const QString &mask=QString(),
72 const QString& whatsThis=QString(),
73 const QStringList &completionList=QStringList() );
74
75 /**
76 * Static convenience function to get a multiline string from the user.
77 *
78 * caption is the text that is displayed in the title bar. label is the
79 * text that appears as a label for the line edit. value is the initial
80 * value of the line edit. ok will be set to true if user pressed Ok
81 * and false if user pressed Cancel.
82 *
83 * @param caption Caption of the dialog
84 * @param label Text of the label for the line edit
85 * @param value Initial value of the line edit
86 * @param ok This bool would be set to true if user pressed Ok
87 * @param parent Parent of the dialog widget
88 *
89 * @return String user entered if Ok was pressed, else a null string
90 */
91 KDEUI_EXPORT QString getMultiLineText( const QString &caption,
92 const QString &label, const QString &value=QString(),
93 bool *ok=0, QWidget *parent=0 );
94
95 /**
96 * Static convenience function to get an integer from the user.
97 *
98 * caption is the text that is displayed in the title bar. label is the
99 * text that appears as the label for the spin box. value is the initial
100 * value for the spin box. minValue and maxValue are the minimum and
101 * maximum allowable values the user may choose. step is the amount by
102 * which the value will change as the user presses the increment and
103 * decrement buttons of the spin box. Base is the base of the number.
104 *
105 * @param caption Caption of the dialog
106 * @param label Text of the label for the spin box
107 * @param value Initial value of the spin box
108 * @param minValue Minimum value user can input
109 * @param maxValue Maximum value user can input
110 * @param step Amount by which value is incremented or decremented
111 * @param base Base of the number
112 * @param ok This bool would be set to true if user pressed Ok
113 * @param parent Parent of the dialog widget
114 *
115 * @return Number user entered if Ok was pressed, else 0
116 */
117
118 KDEUI_EXPORT int getInteger( const QString &caption, const QString &label,
119 int value=0, int minValue=INT_MIN, int maxValue=INT_MAX,
120 int step=1, int base=10, bool *ok=0, QWidget *parent=0 );
121
122 /**
123 * This is an overloaded convenience function. It behaves exactly same as
124 * above except it assumes base to be 10, i.e. accepts decimal numbers.
125 */
126 KDEUI_EXPORT int getInteger( const QString &caption, const QString &label,
127 int value=0, int minValue=INT_MIN, int maxValue=INT_MAX,
128 int step=1, bool *ok=0, QWidget *parent=0 );
129
130 /**
131 * Static convenience function to get a floating point number from the user.
132 *
133 * caption is the text that is displayed in the title bar. label is the
134 * text that appears as the label for the spin box. value is the initial
135 * value for the spin box. minValue and maxValue are the minimum and
136 * maximum allowable values the user may choose. step is the amount by
137 * which the value will change as the user presses the increment and
138 * decrement buttons of the spin box.
139 *
140 * @param caption Caption of the dialog
141 * @param label Text of the label for the spin box
142 * @param value Initial value of the spin box
143 * @param minValue Minimum value user can input
144 * @param maxValue Maximum value user can input
145 * @param step Amount by which value is incremented or decremented
146 * @param decimals Number of digits after the decimal point
147 * @param ok This bool would be set to true if user pressed Ok
148 * @param parent Parent of the dialog widget
149 *
150 * @return Number user entered if Ok was pressed, else 0
151 */
152 KDEUI_EXPORT double getDouble( const QString &caption, const QString &label,
153 double value=0, double minValue=-DBL_MAX,
154 double maxValue=DBL_MAX, double step=0.1, int decimals=1,
155 bool *ok=0, QWidget *parent=0 );
156
157 /**
158 * This is an overloaded convenience function. It behaves exctly like
159 * the above function.
160 */
161 KDEUI_EXPORT double getDouble( const QString &caption, const QString &label,
162 double value=0, double minValue=-DBL_MAX,
163 double maxValue=DBL_MAX, int decimals=1, bool *ok=0,
164 QWidget *parent=0 );
165
166 /**
167 * Static convenience function to let the user select an item from a
168 * list. caption is the text that is displayed in the title bar.
169 * label is the text that appears as the label for the list. list
170 * is the string list which is inserted into the list, and current
171 * is the number of the item which should be the selected item. If
172 * editable is true, the user can enter his own text.
173 *
174 * @param caption Caption of the dialog
175 * @param label Text of the label for the list
176 * @param list List of item for user to choose from
177 * @param current Index of the selected item
178 * @param editable If true, user can enter own text
179 * @param ok This bool would be set to true if user pressed Ok
180 * @param parent Parent of the dialog widget
181 *
182 * @return Text of the selected item. If @p editable is true this can be
183 * a text entered by the user.
184 */
185 KDEUI_EXPORT QString getItem( const QString &caption, const QString &label,
186 const QStringList &list, int current=0, bool editable=false,
187 bool *ok=0, QWidget *parent=0 );
188
189 /**
190 * Static convenience function to let the user select one or more
191 * items from a listbox. caption is the text that is displayed in the
192 * title bar. label is the text that appears as the label for the listbox.
193 * list is the string list which is inserted into the listbox, select
194 * is the list of item(s) that should be the selected. If multiple is
195 * true, the user can select multiple items.
196 *
197 * @param caption Caption of the dialog
198 * @param label Text of the label for the list
199 * @param list List of item for user to choose from
200 * @param select List of item(s) that should be selected
201 * @param multiple If true, user can select multiple items
202 * @param ok This bool would be set to true if user pressed Ok
203 * @param parent Parent of the dialog widget
204 *
205 * @return List of selected items if multiple is true, else currently
206 * selected item as a QStringList
207 */
208 KDEUI_EXPORT QStringList getItemList( const QString &caption,
209 const QString &label, const QStringList &list=QStringList(),
210 const QStringList &select=QStringList(), bool multiple=false,
211 bool *ok=0, QWidget *parent=0 );
212}
213
214#endif // KINPUTDIALOG_H
215
216/* vim: set ai et sw=2 ts=2
217*/
218