diff options
Diffstat (limited to 'kdeui/kprogress.h')
| -rw-r--r-- | kdeui/kprogress.h | 401 |
1 files changed, 401 insertions, 0 deletions
diff --git a/kdeui/kprogress.h b/kdeui/kprogress.h new file mode 100644 index 000000000..28ed989c7 --- /dev/null +++ b/kdeui/kprogress.h @@ -0,0 +1,401 @@ +/* This file is part of the KDE libraries + Copyright (C) 1996 Martynas Kunigelis + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Library General Public + License version 2 as published by the Free Software Foundation. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Library General Public License for more details. + + You should have received a copy of the GNU Library General Public License + along with this library; see the file COPYING.LIB. If not, write to + the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. +*/ +/***************************************************************************** +* * +* KProgress -- progress indicator widget for KDE * +* Original QRangeControl-based version written by Martynas Kunigelis * +* Current QProgressBar based version by Aaron Seigo * +* * +*****************************************************************************/ + +#ifndef _KPROGRESS_H +#define _KPROGRESS_H "$Id$" + +#include <qprogressbar.h> +#include <kdialogbase.h> + +/** + * @short A progress indicator widget. + * + * KProgress is derived from QProgressBar, so + * you can use all the methods from that class. The only real difference + * is that a signal is emitted on changes to the value and you do not need + * to subclass KProgress just to change the format of the indicator text. + * + * \b Details \n + * + * \image html kprogress.png "KDE Progress Widget" + * + * @author Aaron Seigo + */ +class KDEUI_EXPORT KProgress : public QProgressBar +{ + Q_OBJECT + +public: + /** + * Construct a progress bar. + */ + KProgress(QWidget *parent=0, const char *name=0, WFlags f = 0); + + /** + * Construct a progress bar with a total number of steps. + * The totalSteps is the total number of steps that need to be completed for the operation which this progress + * bar represents. For example, if the operation is to examine 50 files, this value would be 50. Before examining + * the first file, call setProgress(0); call setProgress(50) after examining the last file. + */ + KProgress(int totalSteps, QWidget *parent=0, const char *name=0, WFlags f = 0); + + /** + * Destruct the progress bar. + */ + ~KProgress(); + + /** + * If this is set to @p true, the progress text will be displayed. + * + */ + void setTextEnabled(bool); + + /** + * @deprecated Retrieves the current status, use progress() instead + * + * @see setValue() + */ + // ### Remove this KDE 4.0 + int value() const KDE_DEPRECATED; + + /** + * Returns @p true if progress text will be displayed, + * @p false otherwise. + * + * @see setFormat() + */ + bool textEnabled() const; + + /** + * Retrieve the current format for printing status text. + * @see setFormat() + */ + QString format() const; + + /** + * @deprecated but kept for source compatibility with KDE2's KProgress. + * Use setTotalSteps() instead + */ + // ### Remove this KDE 4.0 + void setRange(int min, int max) KDE_DEPRECATED; + + /** + * @deprecated Use totalSteps() instead + */ + // ### Remove this KDE 4.0 + int maxValue() KDE_DEPRECATED; + +public slots: + + /** + * Set the format of the text to use to display status. + * + * The default format is "%p%" (which looks like "42%".) + * + * Note: Setting the format to anything other then "%p%" will force centerIndicator to true, + * since it's often impossible to layout a progressbar with a more general format with the + * indicator string anywhere else. + * + * @param format "%p" is replaced by percentage done, "%v" is replaced by actual + * value, "%m" is replaced by the maximum value. + */ + void setFormat(const QString & format); + + /** + * Set the current total number of steps in the action that the progress bar + * is representing. + */ + void setTotalSteps(int totalSteps); + + /** + * Set the current value of the progress bar to @p progress. + */ + virtual void setProgress(int progress); + + /** + * @deprecated Use setProgress(int) instead + */ + // ### Remove this KDE 4.0 + void setValue(int progress); + + /** + * Advance the progress bar by @p offset. + * + * This method is + * provided for convenience and is equivalent with + * setProgress(progress()+offset). + */ + virtual void advance(int offset); + +signals: + /** + * Emitted when the state of the progress bar changes. + */ + void percentageChanged(int); + +protected: + virtual bool setIndicator(QString & indicator, int progress, int totalSteps); + +private: + QString mFormat; + +protected: + virtual void virtual_hook( int id, void* data ); +private: + class KProgressPrivate; + KProgressPrivate *d; +}; + +/** + * KProgressDialog provides a dialog with a text label, a progress bar + * and an optional cancel button with a KDE look 'n feel. + * + * Since knowing how long it can take to complete an action and it is + * undesirable to show a dialog for a split second before hiding it, + * there are a few ways to control the timing behavior of KProgressDialog. + * There is a time out that can be set before showing the dialog as well + * as an option to autohide or keep displaying the dialog once complete. + * + * All the functionality of KProgress is available through direct access + * to the progress bar widget via progressBar(); + * + * @short A dialog with a progress bar + * @author Aaron J. Seigo + */ +class KDEUI_EXPORT KProgressDialog : public KDialogBase +{ + Q_OBJECT + + public: + /** + * Constructs a KProgressDialog + * + * @param parent Parent of the widget + * @param name Widget name + * @param caption Text to display in window title bar + * @param text Text to display in the dialog + * @param modal Set to true to make the dialog modal + */ + KProgressDialog(QWidget* parent = 0, const char* name = 0, + const QString& caption = QString::null, + const QString& text = QString::null, + bool modal = false); + + /** + * Destructor + */ + ~KProgressDialog(); + + /** + * Returns the KProgress used in this dialog. + * To set the number of steps or other progress bar related + * settings, access the KProgress object directly via this method. + */ + KProgress* progressBar(); + + /** + * Returns the KProgress used in this dialog. + * To set the number of steps or other progress bar related + * settings, access the KProgress object directly via this method. + */ + const KProgress* progressBar() const; + + /** + * Sets the text in the dialog + * + * @param text the text to display + */ + void setLabel(const QString & text); + + /** + * Returns the current dialog text + * @deprecated + */ + // ### Remove this KDE 4.0 + QString labelText() KDE_DEPRECATED; + + /** + * Returns the current dialog text + */ + QString labelText() const; + + /** + * Sets whether or not the user can cancel the process. + * If the dialog is cancellable, the Cancel button will be shown + * and the user can close the window using the window decorations. + * If the process is not (or should not be) interuptable, + * set the dialog to be modal and not cancellable. + * + * @param allowCancel Set to true to make the dialog non-closable + */ + void setAllowCancel(bool allowCancel); + + /** + * Returns true if the dialog can be canceled, false otherwise + * @deprecated + */ + // ### Remove this KDE 4.0 + bool allowCancel() KDE_DEPRECATED; + + /** + * Returns true if the dialog can be canceled, false otherwise + */ + bool allowCancel() const; + + /** + * Sets whether the cancel button is visible. setAllowCancel(false) + * implies showCancelButton(false) + * + * @param show Whether or not the cancel button should be shown + */ + void showCancelButton(bool show); + + /** + * Sets whether the dialog should close automagically when + * all the steps in the KProgress have been completed. + */ + void setAutoClose(bool close); + + /** + * Returns true if the dialog will close upon completion, + * or false otherwise + */ + // ### Remove this KDE 4.0 + bool autoClose(); + + /** + * Returns true if the dialog will close upon completion, + * or false otherwise + */ + bool autoClose() const; + + /** + * Sets whether the dialog should reset the KProgress dialog + * back to 0 steps compelete when all steps have been completed. + * This is useful for KProgressDialogs that will be reused. + */ + void setAutoReset(bool autoReset); + + /** + * Returns true if the KProgress widget will be reset + * upon completion, or false otherwise + */ + // ### Remove this KDE 4.0 + bool autoReset(); + + /** + * Returns true if the KProgress widget will be reset + * upon completion, or false otherwise + */ + bool autoReset() const; + + /** + * Returns true if the dialog was closed or canceled + * before completion. If the dialog is not cancellable + * it will always return false. + */ + // ### Remove this KDE 4.0 + bool wasCancelled(); + + /** + * Returns true if the dialog was closed or canceled + * before completion. If the dialog is not cancellable + * it will always return false. + */ + bool wasCancelled() const; + + /** + * Ignores the last cancel action if the cancel button was + * pressed. Useful for kdialog when combined with a KMessageBox + * to display a message like "Are you sure you want to cancel?" + * @since 3.5.5 + */ + void ignoreCancel(); + + /** + * Sets the text to appear on the cancel button. + */ + void setButtonText(const QString&); + + /** + * Returns the text on the cancel button + * @deprecated + */ + // ### Remove this KDE 4.0 + QString buttonText() KDE_DEPRECATED; + + /** + * Returns the text on the cancel button + */ + QString buttonText() const; + + /** + * Set the minimum number of milliseconds to wait before + * actually showing the dialog + */ + void setMinimumDuration(int ms); + + /** + * Returns the wait duration in milliseconds + * @deprecated + */ + // ### Remove this KDE 4.0 + int minimumDuration() KDE_DEPRECATED; + + /** + * Returns the wait duration in milliseconds + */ + int minimumDuration() const; + + /** + * Reimplemented for internal reasons, the API is not affected. + */ + virtual void show(); + + protected slots: + void slotAutoShow(); + void slotAutoActions(int percentage); + void slotCancel(); + + private: + // ### Move these member variables to d in KDE 4.0 + bool mAutoClose; + bool mAutoReset; + bool mCancelled; + bool mAllowCancel; + bool mShown; + QString mCancelText; + QLabel* mLabel; + KProgress* mProgressBar; + QTimer* mShowTimer; + int mMinDuration; + protected: + virtual void virtual_hook( int id, void* data ); + private: + struct KProgressDialogPrivate; + KProgressDialogPrivate *d; +}; + +#endif |