1 | /* This file is part of the KDE libraries |
2 | Copyright (C) 1996 Martynas Kunigelis // krazy:exclude=copyright (email unknown) |
3 | Copyright (C) 2006-2007 Urs Wolfer <uwolfer at kde.org> |
4 | |
5 | This library is free software; you can redistribute it and/or |
6 | modify it under the terms of the GNU Library General Public |
7 | License version 2 as published by the Free Software Foundation. |
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 KPROGRESSDIALOG_H |
21 | #define KPROGRESSDIALOG_H |
22 | |
23 | #include <QtGui/QProgressBar> |
24 | |
25 | #include <kdialog.h> |
26 | |
27 | /** |
28 | * @short A dialog with a progress bar |
29 | * |
30 | * KProgressDialog provides a dialog with a text label, a progress bar |
31 | * and an optional cancel button with a KDE look 'n feel. |
32 | * |
33 | * Since knowing how long it can take to complete an action and it is |
34 | * undesirable to show a dialog for a split second before hiding it, |
35 | * there are a few ways to control the timing behavior of KProgressDialog. |
36 | * There is a time out that can be set before showing the dialog as well |
37 | * as an option to autohide or keep displaying the dialog once complete. |
38 | * |
39 | * All the functionality of QProgressBar is available through direct access |
40 | * to the progress bar widget via progressBar(); |
41 | * |
42 | * \image html kprogressdialog.png "KDE Progress Dialog" |
43 | * |
44 | * @author Aaron J. Seigo |
45 | * @author Urs Wolfer uwolfer @ kde.org |
46 | */ |
47 | class KDEUI_EXPORT KProgressDialog : public KDialog |
48 | { |
49 | Q_OBJECT |
50 | |
51 | public: |
52 | /** |
53 | * Constructs a KProgressDialog |
54 | * |
55 | * @param parent Parent of the widget |
56 | * @param caption Text to display in window title bar |
57 | * @param text Text to display in the dialog |
58 | * @param flags The widget flags |
59 | */ |
60 | explicit KProgressDialog(QWidget* parent = 0, const QString& caption = QString(), |
61 | const QString& text = QString(), Qt::WindowFlags flags = 0); |
62 | |
63 | /** |
64 | * Destructor |
65 | */ |
66 | ~KProgressDialog(); |
67 | |
68 | /** |
69 | * Returns the QProgressBar used in this dialog. |
70 | * To set the number of steps or other progress bar related |
71 | * settings, access the QProgressBar object directly via this method. |
72 | */ |
73 | QProgressBar *progressBar(); |
74 | |
75 | /** |
76 | * Returns the QProgressBar used in this dialog. |
77 | * To set the number of steps or other progress bar related |
78 | * settings, access the QProgressBar object directly via this method. |
79 | */ |
80 | const QProgressBar *progressBar() const; |
81 | |
82 | /** |
83 | * Sets the text in the dialog |
84 | * |
85 | * @param text the text to display |
86 | */ |
87 | void setLabelText(const QString &text); |
88 | |
89 | /** |
90 | * Returns the current dialog text |
91 | */ |
92 | QString labelText() const; |
93 | |
94 | /** |
95 | * Sets whether or not the user can cancel the process. |
96 | * If the dialog is cancellable, the Cancel button will be shown |
97 | * and the user can close the window using the window decorations. |
98 | * If the process is not (or should not be) interuptable, |
99 | * set the dialog to be modal and not cancellable. |
100 | * |
101 | * The default is true. |
102 | * |
103 | * @param allowCancel Set to true to make the dialog non-closable |
104 | */ |
105 | void setAllowCancel(bool allowCancel); |
106 | |
107 | /** |
108 | * Returns true if the dialog can be canceled, false otherwise |
109 | */ |
110 | bool allowCancel() const; |
111 | |
112 | /** |
113 | * Sets whether the cancel button is visible. setAllowCancel(false) |
114 | * implies showCancelButton(false) |
115 | * |
116 | * The default is true. |
117 | * |
118 | * @param show Whether or not the cancel button should be shown |
119 | */ |
120 | void showCancelButton(bool show); |
121 | |
122 | /** |
123 | * Sets whether the dialog should close automagically when |
124 | * all the steps in the QProgressBar have been completed. |
125 | * |
126 | * The default is true. |
127 | */ |
128 | void setAutoClose(bool close); |
129 | |
130 | /** |
131 | * Returns true if the dialog will close upon completion, |
132 | * or false otherwise |
133 | */ |
134 | bool autoClose() const; |
135 | |
136 | /** |
137 | * Sets whether the dialog should reset the QProgressBar dialog |
138 | * back to 0 steps compelete when all steps have been completed. |
139 | * This is useful for KProgressDialogs that will be reused. |
140 | * |
141 | * The default is false. |
142 | */ |
143 | void setAutoReset(bool autoReset); |
144 | |
145 | /** |
146 | * Returns true if the QProgressBar widget will be reset |
147 | * upon completion, or false otherwise |
148 | */ |
149 | bool autoReset() const; |
150 | |
151 | /** |
152 | * Returns true if the dialog was closed or canceled |
153 | * before completion. If the dialog is not cancellable |
154 | * it will always return false. |
155 | */ |
156 | bool wasCancelled() const; |
157 | |
158 | /** |
159 | * Ignores the last cancel action if the cancel button was |
160 | * pressed. Useful for kdialog when combined with a KMessageBox |
161 | * to display a message like "Are you sure you want to cancel?" |
162 | */ |
163 | void ignoreCancel(); |
164 | |
165 | /** |
166 | * Sets the text to appear on the cancel button. |
167 | */ |
168 | void setButtonText(const QString &text); |
169 | |
170 | /** |
171 | * Returns the text on the cancel button |
172 | */ |
173 | QString buttonText() const; |
174 | |
175 | /** |
176 | * Set the minimum number of milliseconds to wait before |
177 | * actually showing the dialog. |
178 | * |
179 | * If the expected duration of the task is less than the minimumDuration, the dialog will |
180 | * not appear at all. This prevents the dialog popping up for tasks that are quickly over. |
181 | * For tasks that are expected to exceed the minimumDuration, the dialog will pop up after |
182 | * the minimumDuration time. |
183 | * If set to 0, the dialog is always shown immediately. The default is |
184 | * 2000 milliseconds. |
185 | */ |
186 | void setMinimumDuration(int ms); |
187 | |
188 | /** |
189 | * Returns the time that must pass before the dialog appears. |
190 | * @see setMinimumDuration |
191 | */ |
192 | int minimumDuration() const; |
193 | |
194 | virtual void reject(); |
195 | |
196 | protected: |
197 | virtual void showEvent(QShowEvent *event); |
198 | |
199 | private: |
200 | Q_PRIVATE_SLOT(d, void slotAutoShow()) |
201 | Q_PRIVATE_SLOT(d, void slotAutoActions(int percentage)) |
202 | |
203 | private: |
204 | class KProgressDialogPrivate; |
205 | friend class KProgressDialogPrivate; |
206 | KProgressDialogPrivate *const d; |
207 | |
208 | Q_DISABLE_COPY(KProgressDialog) |
209 | }; |
210 | |
211 | #endif |
212 | |