KCoreAddons

kjob.h
1 /*
2  This file is part of the KDE project
3 
4  SPDX-FileCopyrightText: 2000 Stephan Kulow <[email protected]>
5  SPDX-FileCopyrightText: 2000 David Faure <[email protected]>
6  SPDX-FileCopyrightText: 2006 Kevin Ottens <[email protected]>
7 
8  SPDX-License-Identifier: LGPL-2.0-only
9 */
10 
11 #ifndef KJOB_H
12 #define KJOB_H
13 
14 #include <kcoreaddons_export.h>
15 #include <QObject>
16 #include <QPair>
17 
18 class KJobUiDelegate;
19 
20 class KJobPrivate;
75 class KCOREADDONS_EXPORT KJob : public QObject
76 {
77  Q_OBJECT
78  Q_PROPERTY(int error READ error NOTIFY result)
79  Q_PROPERTY(QString errorText READ errorText NOTIFY result)
80  Q_PROPERTY(QString errorString READ errorString NOTIFY result)
81  Q_PROPERTY(ulong percent READ percent NOTIFY percent) // KF6 TODO: make "int", is enough
82  Q_PROPERTY(Capabilities capabilities READ capabilities CONSTANT)
83 
84 public:
89  enum Unit {
93  Items,
94  };
96  Q_ENUM(Unit)
97 
98 
101  enum Capability {
102  NoCapabilities = 0x0000,
103  Killable = 0x0001,
104  Suspendable = 0x0002,
105  };
107 
108 
111  Q_DECLARE_FLAGS(Capabilities, Capability)
112  Q_FLAG(Capabilities)
113 
119  explicit KJob(QObject *parent = nullptr);
120 
124  ~KJob() override;
125 
135  void setUiDelegate(KJobUiDelegate *delegate);
136 
142  KJobUiDelegate *uiDelegate() const;
143 
150  Capabilities capabilities() const;
151 
158  bool isSuspended() const;
159 
181  Q_SCRIPTABLE virtual void start() = 0;
182 
183  enum KillVerbosity { Quietly, EmitResult };
184  Q_ENUM(KillVerbosity)
185 
186 public Q_SLOTS:
200  bool kill(KillVerbosity verbosity = Quietly);
201 
208  bool suspend();
209 
215  bool resume();
216 
217 protected:
225  virtual bool doKill();
226 
232  virtual bool doSuspend();
233 
239  virtual bool doResume();
240 
247  void setCapabilities(Capabilities capabilities);
248 
249 public:
268  bool exec();
269 
270  enum {
271  /*** Indicates there is no error */
272  NoError = 0,
273  /*** Indicates the job was killed */
274  KilledJobError = 1,
275  /*** Subclasses should define error codes starting at this value */
276  UserDefinedError = 100
277  };
278 
286  int error() const;
287 
299  QString errorText() const;
300 
318  virtual QString errorString() const;
319 
326  Q_SCRIPTABLE qulonglong processedAmount(Unit unit) const;
327 
334  Q_SCRIPTABLE qulonglong totalAmount(Unit unit) const;
335 
341  unsigned long percent() const;
342 
352  void setAutoDelete(bool autodelete);
353 
361  bool isAutoDelete() const;
362 
363 Q_SIGNALS:
381  void finished(KJob *job
382 #if !defined(K_DOXYGEN)
383  , QPrivateSignal
384 #endif
385  );
386 
395  void suspended(KJob *job
396 #if !defined(K_DOXYGEN)
397  , QPrivateSignal
398 #endif
399  );
400 
409  void resumed(KJob *job
410 #if !defined(K_DOXYGEN)
411  , QPrivateSignal
412 #endif
413  );
414 
429  void result(KJob *job
430 #if !defined(K_DOXYGEN)
431  , QPrivateSignal
432 #endif
433  );
434 
448  void description(KJob *job, const QString &title,
459  void infoMessage(KJob *job, const QString &plain, const QString &rich = QString());
460 
468  void warning(KJob *job, const QString &plain, const QString &rich = QString());
469 
470 Q_SIGNALS:
471  // These signals must be connected from KIO::KCoreDirLister (among others),
472  // therefore they must be public.
485  void totalAmount(KJob *job, KJob::Unit unit, qulonglong amount);
486 
499  void processedAmount(KJob *job, KJob::Unit unit, qulonglong amount);
500 
511  void totalSize(KJob *job, qulonglong size);
512 
523  void processedSize(KJob *job, qulonglong size);
524 
538  void percent(KJob *job, unsigned long percent);
539 
549  void speed(KJob *job, unsigned long speed);
550 
551 protected:
571  void setError(int errorCode);
572 
586  void setErrorText(const QString &errorText);
587 
596  void setProcessedAmount(Unit unit, qulonglong amount);
597 
606  void setTotalAmount(Unit unit, qulonglong amount);
607 
614  void setPercent(unsigned long percentage);
615 
626  void emitResult();
627 
637  void emitPercent(qulonglong processedAmount, qulonglong totalAmount);
638 
645  void emitSpeed(unsigned long speed);
646 
647 protected:
648  KJobPrivate *const d_ptr;
649  KJob(KJobPrivate &dd, QObject *parent);
650 
651 private:
652  void finishJob(bool emitResult);
653 
654  Q_PRIVATE_SLOT(d_func(), void _k_speedTimeout())
655  Q_DECLARE_PRIVATE(KJob)
656 };
657 
658 Q_DECLARE_METATYPE(KJob::Unit)
659 Q_DECLARE_OPERATORS_FOR_FLAGS(KJob::Capabilities)
660 
661 #endif
Q_ENUM(...)
Capability
Definition: kjob.h:101
The base class for all KJob UI delegate.
Unit
Describes the unit used in the methods that handle reporting the job progress info.
Definition: kjob.h:89
Q_PROPERTY(...)
Directory and file sizes in bytes.
Definition: kjob.h:90
The number of files handled by the job.
Definition: kjob.h:91
The number of directories handled by the job.
Definition: kjob.h:92
The base class for all jobs.
Definition: kjob.h:75
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Mon Aug 3 2020 23:01:25 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.