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:
383  void finished(KJob *job
384 #if !defined(K_DOXYGEN)
385  , QPrivateSignal
386 #endif
387  );
388 
397  void suspended(KJob *job
398 #if !defined(K_DOXYGEN)
399  , QPrivateSignal
400 #endif
401  );
402 
411  void resumed(KJob *job
412 #if !defined(K_DOXYGEN)
413  , QPrivateSignal
414 #endif
415  );
416 
433  void result(KJob *job
434 #if !defined(K_DOXYGEN)
435  , QPrivateSignal
436 #endif
437  );
438 
452  void description(KJob *job, const QString &title,
463  void infoMessage(KJob *job, const QString &plain, const QString &rich = QString());
464 
472  void warning(KJob *job, const QString &plain, const QString &rich = QString());
473 
474 Q_SIGNALS:
475  // These signals must be connected from KIO::KCoreDirLister (among others),
476  // therefore they must be public.
489  void totalAmount(KJob *job, KJob::Unit unit, qulonglong amount);
490 
503  void processedAmount(KJob *job, KJob::Unit unit, qulonglong amount);
504 
515  void totalSize(KJob *job, qulonglong size);
516 
527  void processedSize(KJob *job, qulonglong size);
528 
542  void percent(KJob *job, unsigned long percent);
543 
553  void speed(KJob *job, unsigned long speed);
554 
555 protected:
563  bool isFinished() const;
564 
584  void setError(int errorCode);
585 
599  void setErrorText(const QString &errorText);
600 
609  void setProcessedAmount(Unit unit, qulonglong amount);
610 
619  void setTotalAmount(Unit unit, qulonglong amount);
620 
627  void setProgressUnit(Unit unit);
628 
639  void setPercent(unsigned long percentage);
640 
651  void emitResult();
652 
662  void emitPercent(qulonglong processedAmount, qulonglong totalAmount);
663 
670  void emitSpeed(unsigned long speed);
671 
672 protected:
673  KJobPrivate *const d_ptr;
674  KJob(KJobPrivate &dd, QObject *parent);
675 
676 private:
677  void finishJob(bool emitResult);
678 
679  Q_PRIVATE_SLOT(d_func(), void _k_speedTimeout())
680  Q_DECLARE_PRIVATE(KJob)
681 };
682 
683 Q_DECLARE_METATYPE(KJob::Unit)
684 Q_DECLARE_OPERATORS_FOR_FLAGS(KJob::Capabilities)
685 
686 #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 Sat Nov 28 2020 23:02:20 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.