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 */
47class 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