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 | |
30 | class 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 | */ |
39 | namespace 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 | |