File indexing completed on 2024-12-01 03:41:43

0001 /*
0002     This file is part of the KDE project
0003     SPDX-FileCopyrightText: 2000 Matej Koss <koss@miesto.sk>
0004     SPDX-FileCopyrightText: 2007 Kevin Ottens <ervin@kde.org>
0005     SPDX-FileCopyrightText: 2008 Rafael Fernández López <ereslibre@kde.org>
0006 
0007     SPDX-License-Identifier: LGPL-2.0-only
0008 */
0009 
0010 #ifndef KABSTRACTWIDGETJOBTRACKER_H
0011 #define KABSTRACTWIDGETJOBTRACKER_H
0012 
0013 #include <KJobTrackerInterface>
0014 #include <kjobwidgets_export.h>
0015 
0016 #include <memory>
0017 
0018 class KJob;
0019 class QWidget;
0020 class KAbstractWidgetJobTrackerPrivate;
0021 
0022 /**
0023  * @class KAbstractWidgetJobTracker kabstractwidgetjobtracker.h KAbstractWidgetJobTracker
0024  *
0025  * The base class for widget based job trackers.
0026  */
0027 class KJOBWIDGETS_EXPORT KAbstractWidgetJobTracker : public KJobTrackerInterface
0028 {
0029     Q_OBJECT
0030 
0031 public:
0032     /**
0033      * Creates a new KAbstractWidgetJobTracker
0034      *
0035      * @param parent the parent of this object and of the widget displaying the job progresses
0036      */
0037     explicit KAbstractWidgetJobTracker(QWidget *parent = nullptr);
0038 
0039     /**
0040      * Destroys a KAbstractWidgetJobTracker
0041      */
0042     ~KAbstractWidgetJobTracker() override;
0043 
0044     // KDE5: move this two virtual methods to be placed correctly (ereslibre)
0045 public Q_SLOTS:
0046     /**
0047      * Register a new job in this tracker.
0048      * Note that job trackers inheriting from this class can have only one job
0049      * registered at a time.
0050      *
0051      * @param job the job to register
0052      */
0053     void registerJob(KJob *job) override;
0054 
0055     /**
0056      * Unregister a job from this tracker.
0057      *
0058      * @param job the job to unregister
0059      */
0060     void unregisterJob(KJob *job) override;
0061 
0062 public:
0063     /**
0064      * The widget associated to this tracker.
0065      *
0066      * @param job the job that is assigned the widget we want to return
0067      * @return the widget displaying the job progresses
0068      */
0069     virtual QWidget *widget(KJob *job) = 0;
0070 
0071     /**
0072      * This controls whether the job should be canceled if the dialog is closed.
0073      *
0074      * @param job the job's widget that will be stopped when closing
0075      * @param stopOnClose If true the job will be stopped if the dialog is closed,
0076      * otherwise the job will continue even on close.
0077      * @see stopOnClose()
0078      */
0079     void setStopOnClose(KJob *job, bool stopOnClose);
0080 
0081     /**
0082      * Checks whether the job will be killed when the dialog is closed.
0083      *
0084      * @param job the job's widget that will be stopped when closing
0085      * @return true if the job is killed on close event, false otherwise.
0086      * @see setStopOnClose()
0087      */
0088     bool stopOnClose(KJob *job) const;
0089 
0090     /**
0091      * This controls whether the dialog should be deleted or only cleaned when
0092      * the KJob is finished (or canceled).
0093      *
0094      * If your dialog is an embedded widget and not a separate window, you should
0095      * setAutoDelete(false) in the constructor of your custom dialog.
0096      *
0097      * @param job the job's widget that is going to be auto-deleted
0098      * @param autoDelete If false the dialog will only call method slotClean.
0099      * If true the dialog will be deleted.
0100      * @see autoDelete()
0101      */
0102     void setAutoDelete(KJob *job, bool autoDelete);
0103 
0104     /**
0105      * Checks whether the dialog should be deleted or cleaned.
0106      *
0107      * @param job the job's widget that will be auto-deleted
0108      * @return false if the dialog only calls slotClean, true if it will be
0109      *         deleted
0110      * @see setAutoDelete()
0111      */
0112     bool autoDelete(KJob *job) const;
0113 
0114 protected Q_SLOTS:
0115     /**
0116      * Called when a job is finished, in any case. It is used to notify
0117      * that the job is terminated and that progress UI (if any) can be hidden.
0118      *
0119      * @param job the job that emitted this signal
0120      */
0121     void finished(KJob *job) override;
0122 
0123     /**
0124      * This method should be called for correct cancellation of IO operation
0125      * Connect this to the progress widgets buttons etc.
0126      *
0127      * @param job The job that is being stopped
0128      */
0129     virtual void slotStop(KJob *job);
0130 
0131     /**
0132      * This method should be called for pause/resume
0133      * Connect this to the progress widgets buttons etc.
0134      *
0135      * @param job The job that is being suspended
0136      */
0137     virtual void slotSuspend(KJob *job);
0138 
0139     /**
0140      * This method should be called for pause/resume
0141      * Connect this to the progress widgets buttons etc.
0142      *
0143      * @param job The job that is being resumed
0144      */
0145     virtual void slotResume(KJob *job);
0146 
0147     /**
0148      * This method is called when the widget should be cleaned (after job is finished).
0149      * redefine this for custom behavior.
0150      *
0151      * @param job The job that is being cleaned
0152      */
0153     virtual void slotClean(KJob *job);
0154 
0155 Q_SIGNALS:
0156     /**
0157      * Emitted when the user aborted the operation
0158      *
0159      * @param job The job that has been stopped
0160      */
0161     void stopped(KJob *job);
0162 
0163     /**
0164      * Emitted when the user suspended the operation
0165      *
0166      * @param job The job that has been suspended
0167      */
0168     void suspend(KJob *job);
0169 
0170     /**
0171      * Emitted when the user resumed the operation
0172      *
0173      * @param job The job that has been resumed
0174      */
0175     void resume(KJob *job);
0176 
0177 protected:
0178     KJOBWIDGETS_NO_EXPORT explicit KAbstractWidgetJobTracker(KAbstractWidgetJobTrackerPrivate &dd, QWidget *parent = nullptr);
0179 
0180 protected:
0181     std::unique_ptr<KAbstractWidgetJobTrackerPrivate> const d_ptr;
0182 
0183 private:
0184     Q_DECLARE_PRIVATE(KAbstractWidgetJobTracker)
0185 };
0186 
0187 #endif