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-or-later
9 */
10 
11 #ifndef KJOB_H
12 #define KJOB_H
13 
14 #include <QObject>
15 #include <QPair>
16 #include <kcoreaddons_export.h>
17 #include <memory>
18 
19 class KJobUiDelegate;
20 
21 class KJobPrivate;
22 /**
23  * @class KJob kjob.h KJob
24  *
25  * The base class for all jobs.
26  * For all jobs created in an application, the code looks like
27  *
28  * \code
29  * void SomeClass::methodWithAsynchronousJobCall()
30  * {
31  * KJob *job = someoperation(some parameters);
32  * connect(job, &KJob::result, this, &SomeClass::handleResult);
33  * job->start();
34  * }
35  * \endcode
36  * (other connects, specific to the job)
37  *
38  * And handleResult is usually at least:
39  *
40  * \code
41  * void SomeClass::handleResult(KJob *job)
42  * {
43  * if (job->error()) {
44  * doSomething();
45  * }
46  * }
47  * \endcode
48  *
49  * With the synchronous interface the code looks like
50  *
51  * \code
52  * void SomeClass::methodWithSynchronousJobCall()
53  * {
54  * KJob *job = someoperation( some parameters );
55  * if (!job->exec()) {
56  * // An error occurred
57  * } else {
58  * // Do something
59  * }
60  * }
61  * \endcode
62  *
63  * Subclasses must implement start(), which should trigger the execution of
64  * the job (although the work should be done asynchronously). errorString()
65  * should also be reimplemented by any subclasses that introduce new error
66  * codes.
67  *
68  * @note KJob and its subclasses are meant to be used in a fire-and-forget way.
69  * Jobs will delete themselves when they finish using deleteLater() (although
70  * this behaviour can be changed), so a job instance will disappear after the
71  * next event loop run.
72  */
73 class KCOREADDONS_EXPORT KJob : public QObject
74 {
75  Q_OBJECT
76  Q_PROPERTY(int error READ error NOTIFY result)
77  Q_PROPERTY(QString errorText READ errorText NOTIFY result)
78  Q_PROPERTY(QString errorString READ errorString NOTIFY result)
79  Q_PROPERTY(ulong percent READ percent NOTIFY percentChanged) // KF6 TODO: make "int", is enough
80  Q_PROPERTY(Capabilities capabilities READ capabilities CONSTANT)
81 
82 public:
83  /**
84  * Describes the unit used in the methods that handle reporting the job progress info.
85  * @see totalAmount
86  */
87  enum Unit {
88  Bytes = 0, ///< Directory and file sizes in bytes
89  Files, ///< The number of files handled by the job
90  Directories, ///< The number of directories handled by the job
91  Items, ///< The number of items (e.g. both directories and files) handled by the job
92  ///< @since 5.72
93 
94  UnitsCount, ///< @internal since 5.87, used internally only, do not use.
95  };
96  Q_ENUM(Unit)
97 
98  /**
99  * @see Capabilities
100  */
101  enum Capability {
102  NoCapabilities = 0x0000, ///< None of the capabilities exist
103  Killable = 0x0001, ///< The job can be killed
104  Suspendable = 0x0002, ///< The job can be suspended
105  };
106  Q_ENUM(Capability)
107 
108  /**
109  * Stores a combination of #Capability values.
110  */
111  Q_DECLARE_FLAGS(Capabilities, Capability)
112  Q_FLAG(Capabilities)
113 
114  /**
115  * Creates a new KJob object.
116  *
117  * @param parent the parent QObject
118  */
119  explicit KJob(QObject *parent = nullptr);
120 
121  /**
122  * Destroys a KJob object.
123  */
124  ~KJob() override;
125 
126  /**
127  * Attach a UI delegate to this job.
128  *
129  * If the job had another UI delegate, it's automatically deleted. Once
130  * attached to the job, the UI delegate will be deleted with the job.
131  *
132  * @param delegate the new UI delegate to use
133  * @see KJobUiDelegate
134  */
135  void setUiDelegate(KJobUiDelegate *delegate);
136 
137  /**
138  * Retrieves the delegate attached to this job.
139  *
140  * @return the delegate attached to this job, or @c nullptr if there's no such delegate
141  */
142  KJobUiDelegate *uiDelegate() const;
143 
144  /**
145  * Returns the capabilities of this job.
146  *
147  * @return the capabilities that this job supports
148  * @see setCapabilities()
149  */
150  Capabilities capabilities() const;
151 
152  /**
153  * Returns if the job was suspended with the suspend() call.
154  *
155  * @return if the job was suspended
156  * @see suspend() resume()
157  */
158  bool isSuspended() const;
159 
160  /**
161  * Starts the job asynchronously.
162  *
163  * When the job is finished, result() is emitted.
164  *
165  * Warning: Never implement any synchronous workload in this method. This method
166  * should just trigger the job startup, not do any work itself. It is expected to
167  * be non-blocking.
168  *
169  * This is the method all subclasses need to implement.
170  * It should setup and trigger the workload of the job. It should not do any
171  * work itself. This includes all signals and terminating the job, e.g. by
172  * emitResult(). The workload, which could be another method of the
173  * subclass, is to be triggered using the event loop, e.g. by code like:
174  * \code
175  * void ExampleJob::start()
176  * {
177  * QTimer::singleShot(0, this, &ExampleJob::doWork);
178  * }
179  * \endcode
180  */
181  Q_SCRIPTABLE virtual void start() = 0;
182 
183  enum KillVerbosity {
184  Quietly,
185  EmitResult,
186  };
187  Q_ENUM(KillVerbosity)
188 
189 public Q_SLOTS:
190  /**
191  * Aborts this job.
192  *
193  * This kills and deletes the job.
194  *
195  * @param verbosity if equals to EmitResult, Job will emit signal result
196  * and ask uiserver to close the progress window.
197  * @p verbosity is set to EmitResult for subjobs. Whether applications
198  * should call with Quietly or EmitResult depends on whether they rely
199  * on result being emitted or not. Please notice that if @p verbosity is
200  * set to Quietly, signal result will NOT be emitted.
201  * @return true if the operation is supported and succeeded, false otherwise
202  */
203  // TODO KF6 slot arguments need to be fully-qualified, KJob::KillVerbosity
204  bool kill(KillVerbosity verbosity = Quietly);
205 
206  /**
207  * Suspends this job.
208  * The job should be kept in a state in which it is possible to resume it.
209  *
210  * @return true if the operation is supported and succeeded, false otherwise
211  */
212  bool suspend();
213 
214  /**
215  * Resumes this job.
216  *
217  * @return true if the operation is supported and succeeded, false otherwise
218  */
219  bool resume();
220 
221 protected:
222  /**
223  * Aborts this job quietly.
224  *
225  * This simply kills the job, no error reporting or job deletion should be involved.
226  *
227  * @return true if the operation is supported and succeeded, false otherwise
228  */
229  virtual bool doKill();
230 
231  /**
232  * Suspends this job.
233  *
234  * @return true if the operation is supported and succeeded, false otherwise
235  */
236  virtual bool doSuspend();
237 
238  /**
239  * Resumes this job.
240  *
241  * @return true if the operation is supported and succeeded, false otherwise
242  */
243  virtual bool doResume();
244 
245  /**
246  * Sets the capabilities for this job.
247  *
248  * @param capabilities are the capabilities supported by this job
249  * @see capabilities()
250  */
251  void setCapabilities(Capabilities capabilities);
252 
253 public:
254  /**
255  * Executes the job synchronously.
256  *
257  * This will start a nested QEventLoop internally. Nested event loop can be dangerous and
258  * can have unintended side effects, you should avoid calling exec() whenever you can and use the
259  * asynchronous interface of KJob instead.
260  *
261  * Should you indeed call this method, you need to make sure that all callers are reentrant,
262  * so that events delivered by the inner event loop don't cause non-reentrant functions to be
263  * called, which usually wreaks havoc.
264  *
265  * Note that the event loop started by this method does not process user input events, which means
266  * your user interface will effectively be blocked. Other events like paint or network events are
267  * still being processed. The advantage of not processing user input events is that the chance of
268  * accidental reentrance is greatly reduced. Still you should avoid calling this function.
269  *
270  * @return true if the job has been executed without error, false otherwise
271  */
272  bool exec();
273 
274  enum {
275  /*** Indicates there is no error */
276  NoError = 0,
277  /*** Indicates the job was killed */
278  KilledJobError = 1,
279  /*** Subclasses should define error codes starting at this value */
280  UserDefinedError = 100,
281  };
282 
283  /**
284  * Returns the error code, if there has been an error.
285  *
286  * Only call this method from the slot connected to result().
287  *
288  * @return the error code for this job, 0 if no error.
289  */
290  int error() const;
291 
292  /**
293  * Returns the error text if there has been an error.
294  *
295  * Only call if error is not 0.
296  *
297  * This is usually some extra data associated with the error,
298  * such as a URL. Use errorString() to get a human-readable,
299  * translated message.
300  *
301  * @return a string to help understand the error
302  */
303  QString errorText() const;
304 
305  /**
306  * A human-readable error message.
307  *
308  * This provides a translated, human-readable description of the
309  * error. Only call if error is not 0.
310  *
311  * Subclasses should implement this to create a translated
312  * error message from the error code and error text.
313  * For example:
314  * \code
315  * if (error() == ReadFailed) {
316  * i18n("Could not read \"%1\"", errorText());
317  * }
318  * \endcode
319  *
320  * @return a translated error message, providing error() is 0
321  */
322  virtual QString errorString() const;
323 
324  /**
325  * Returns the processed amount of a given unit for this job.
326  *
327  * @param unit the unit of the requested amount
328  * @return the processed size
329  */
330  Q_SCRIPTABLE qulonglong processedAmount(Unit unit) const;
331 
332  /**
333  * Returns the total amount of a given unit for this job.
334  *
335  * @param unit the unit of the requested amount
336  * @return the total size
337  */
338  Q_SCRIPTABLE qulonglong totalAmount(Unit unit) const;
339 
340  /**
341  * Returns the overall progress of this job.
342  *
343  * @return the overall progress of this job
344  */
345  unsigned long percent() const;
346 
347  /**
348  * Sets the auto-delete property of the job. If @p autodelete is
349  * set to @c false the job will not delete itself once it is finished.
350  *
351  * The default for any KJob is to automatically delete itself, which
352  * implies that the job was created on the heap (using <tt>new</tt>).
353  * If the job is created on the stack (which isn't the typical use-case
354  * for a job) then you must set auto-delete to @c false, otherwise you
355  * could get a crash when the job finishes and tries to delete itself.
356  *
357  * @note If you set auto-delete to @c false then you need to kill the
358  * job manually, ideally by calling kill().
359  *
360  * @param autodelete set to @c false to disable automatic deletion
361  * of the job.
362  */
363  void setAutoDelete(bool autodelete);
364 
365  /**
366  * Returns whether this job automatically deletes itself once
367  * the job is finished.
368  *
369  * @return whether the job is deleted automatically after
370  * finishing.
371  */
372  bool isAutoDelete() const;
373 
374  /**
375  * This method can be used to indicate to classes listening to signals from a job
376  * that they should ideally show a progress bar, but not a finished notification.
377  *
378  * For example when opening a remote URL, a job will emit the progress of the
379  * download, which can be used to show a progress dialog or a Plasma notification,
380  * then when the job is done it'll emit e.g. the finished signal. Showing the user the
381  * progress dialog is useful, however the dialog/notification about the download being
382  * finished isn't of much interest, because the user can see the application that invoked
383  * the job opening the actual file that was downloaded.
384  *
385  * @since 5.92
386  */
387  void setFinishedNotificationHidden(bool hide = true);
388 
389  /**
390  * Whether to <em>not</em> show a finished notification when a job's finished
391  * signal is emitted.
392  *
393  * @see setFinishedNotificationHidden()
394  *
395  * @since 5.92
396  */
397  bool isFinishedNotificationHidden() const;
398 
399  /**
400  * Returns @c true if this job was started with exec(), which starts a nested event-loop
401  * (with QEventLoop::ExcludeUserInputEvents, which blocks the GUI), otherwise returns
402  * @c false which indicates this job was started asynchronously with start().
403  *
404  * This is useful for code that for example shows a dialog to ask the user a question,
405  * and that would be no-op since the user cannot interact with the dialog.
406  *
407  * @since 5.95
408  */
409  bool isStartedWithExec() const;
410 
411 Q_SIGNALS:
412  /**
413  * Emitted when the job is finished, in any case. It is used to notify
414  * observers that the job is terminated and that progress can be hidden.
415  *
416  * Since 5.75 this signal is guaranteed to be emitted exactly once.
417  *
418  * This is a private signal, it can't be emitted directly by subclasses of
419  * KJob, use emitResult() instead.
420  *
421  * In general, to be notified of a job's completion, client code should connect to result()
422  * rather than finished(), so that kill(Quietly) is indeed quiet.
423  * However if you store a list of jobs and they might get killed silently,
424  * then you must connect to this instead of result(), to avoid dangling pointers in your list.
425  *
426  * @param job the job that emitted this signal
427  * @internal
428  *
429  * @see result
430  */
431  void finished(KJob *job
432 #if !defined(K_DOXYGEN)
433  ,
434  QPrivateSignal
435 #endif
436  );
437 
438  /**
439  * Emitted when the job is suspended.
440  *
441  * This is a private signal, it can't be emitted directly by subclasses of
442  * KJob.
443  *
444  * @param job the job that emitted this signal
445  */
446  void suspended(KJob *job
447 #if !defined(K_DOXYGEN)
448  ,
449  QPrivateSignal
450 #endif
451  );
452 
453  /**
454  * Emitted when the job is resumed.
455  *
456  * This is a private signal, it can't be emitted directly by subclasses of
457  * KJob.
458  *
459  * @param job the job that emitted this signal
460  */
461  void resumed(KJob *job
462 #if !defined(K_DOXYGEN)
463  ,
464  QPrivateSignal
465 #endif
466  );
467 
468  /**
469  * Emitted when the job is finished (except when killed with KJob::Quietly).
470  *
471  * Since 5.75 this signal is guaranteed to be emitted at most once.
472  *
473  * Use error to know if the job was finished with error.
474  *
475  * This is a private signal, it can't be emitted directly by subclasses of
476  * KJob, use emitResult() instead.
477  *
478  * Please connect to this signal instead of finished.
479  *
480  * @param job the job that emitted this signal
481  *
482  * @see kill
483  */
484  void result(KJob *job
485 #if !defined(K_DOXYGEN)
486  ,
487  QPrivateSignal
488 #endif
489  );
490 
491  /**
492  * Emitted to display general description of this job. A description has
493  * a title and two optional fields which can be used to complete the
494  * description.
495  *
496  * Examples of titles are "Copying", "Creating resource", etc.
497  * The fields of the description can be "Source" with an URL, and,
498  * "Destination" with an URL for a "Copying" description.
499  * @param job the job that emitted this signal
500  * @param title the general description of the job
501  * @param field1 first field (localized name and value)
502  * @param field2 second field (localized name and value)
503  */
504  void description(KJob *job,
505  const QString &title,
508  /**
509  * Emitted to display state information about this job.
510  * Examples of message are "Resolving host", "Connecting to host...", etc.
511  *
512  * @param job the job that emitted this signal
513  * @param plain the info message
514  * @param rich the rich text version of the message, or QString() is none is available -- do not use, it's ignored
515  */
516  void infoMessage(KJob *job, const QString &plain, const QString &rich = QString()); // KF6 TODO remove the 'rich' argument
517 
518  /**
519  * Emitted to display a warning about this job.
520  *
521  * @param job the job that emitted this signal
522  * @param plain the warning message
523  * @param rich the rich text version of the message, or QString() is none is available
524  */
525  void warning(KJob *job, const QString &plain, const QString &rich = QString());
526 
527 Q_SIGNALS:
528  // These signals must be connected from KIO::KCoreDirLister (among others),
529  // therefore they must be public.
530 
531 #if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 80)
532  /**
533  * Emitted when we know the amount the job will have to process. The unit of this
534  * amount is sent too. It can be emitted several times if the job manages several
535  * different units.
536  *
537  * @note This is a private signal, it shouldn't be emitted directly by subclasses of
538  * KJob, use setTotalAmount() instead.
539  *
540  * @param job the job that emitted this signal
541  * @param unit the unit of the total amount
542  * @param amount the total amount
543  *
544  * @deprecated since 5.80, use the KJob::totalAmountChanged(KJob *, KJob::Unit, qulonglong) signal instead
545  */
546  KCOREADDONS_DEPRECATED_VERSION(5, 80, "Use KJob::totalAmountChanged(KJob *, KJob::Unit, qulonglong) signal")
547  void totalAmount(KJob *job, KJob::Unit unit, qulonglong amount); // clazy:exclude=overloaded-signal
548 #endif
549 
550  /**
551  * Emitted when we know the amount the job will have to process. The unit of this
552  * amount is sent too. It can be emitted several times if the job manages several
553  * different units.
554  *
555  * @note This is a private signal, it shouldn't be emitted directly by subclasses of
556  * KJob, use setTotalAmount() instead.
557  *
558  * @param job the job that emitted this signal
559  * @param unit the unit of the total amount
560  * @param amount the total amount
561  *
562  * @since 5.80
563  */
564  void totalAmountChanged(KJob *job,
565  KJob::Unit unit,
566  qulonglong amount
567 #if !defined(K_DOXYGEN)
568  ,
569  QPrivateSignal
570 #endif
571  );
572 
573 #if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 80)
574  /**
575  * Regularly emitted to show the progress of this job by giving the current amount.
576  * The unit of this amount is sent too. It can be emitted several times if the job
577  * manages several different units.
578  *
579  * @note This is a private signal, it shouldn't be emitted directly by subclasses of
580  * KJob, use setProcessedAmount() instead.
581  *
582  * @param job the job that emitted this signal
583  * @param unit the unit of the processed amount
584  * @param amount the processed amount
585  *
586  * @deprecated since 5.80, use the KJob::processedAmountChanged(KJob *, KJob::Unit, qulonglong)
587  * signal instead
588  */
589  KCOREADDONS_DEPRECATED_VERSION(5, 80, "Use KJob::processedAmountChanged(KJob *, KJob::Unit, qulonglong) signal")
590  void processedAmount(KJob *job, KJob::Unit unit, qulonglong amount); // clazy:exclude=overloaded-signal
591 #endif
592 
593  /**
594  * Regularly emitted to show the progress of this job by giving the current amount.
595  * The unit of this amount is sent too. It can be emitted several times if the job
596  * manages several different units.
597  *
598  * @note This is a private signal, it shouldn't be emitted directly by subclasses of
599  * KJob, use setProcessedAmount() instead.
600  *
601  * @param job the job that emitted this signal
602  * @param unit the unit of the processed amount
603  * @param amount the processed amount
604  *
605  * @since 5.80
606  */
607  void processedAmountChanged(KJob *job,
608  KJob::Unit unit,
609  qulonglong amount
610 #if !defined(K_DOXYGEN)
611  ,
612  QPrivateSignal
613 #endif
614  );
615 
616  /**
617  * Emitted when we know the size of this job (data size in bytes for transfers,
618  * number of entries for listings, etc).
619  *
620  * @note This is a private signal, it shouldn't be emitted directly by subclasses of
621  * KJob, use setTotalAmount() instead.
622  *
623  * @param job the job that emitted this signal
624  * @param size the total size
625  */
626  void totalSize(KJob *job, qulonglong size);
627 
628  /**
629  * Regularly emitted to show the progress of this job
630  * (current data size in bytes for transfers, entries listed, etc.).
631  *
632  * @note This is a private signal, it shouldn't be emitted directly by subclasses of
633  * KJob, use setProcessedAmount() instead.
634  *
635  * @param job the job that emitted this signal
636  * @param size the processed size
637  */
638  void processedSize(KJob *job, qulonglong size);
639 
640 #if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 80)
641  /**
642  * Progress signal showing the overall progress of the job
643  * This is valid for any kind of job, and allows using a
644  * a progress bar very easily. (see KProgressBar).
645  * Note that this signal is not emitted for finished jobs.
646  *
647  * @note This is a private signal, it shouldn't be emitted directly by subclasses of
648  * KJob, use emitPercent(), setPercent() setTotalAmount() or
649  * setProcessedAmount() instead.
650  *
651  * @param job the job that emitted this signal
652  * @param percent the percentage
653  *
654  * @deprecated since 5.80, use the KJob::percentChanged(KJob *, unsigned long)
655  * signal instead.
656  */
657  KCOREADDONS_DEPRECATED_VERSION(5, 80, "Use KJob::percentChanged(KJob *, unsigned long) signal")
658  void percent(KJob *job, unsigned long percent); // clazy:exclude=overloaded-signal
659 #endif
660 
661  /**
662  * Progress signal showing the overall progress of the job. This is
663  * valid for any kind of job, and allows using a progress bar very
664  * easily. (see KProgressBar).
665  *
666  * Note that this signal is not emitted for finished jobs.
667  *
668  * @note This is a private signal, it shouldn't be emitted directly
669  * by subclasses of KJob, use emitPercent(), setPercent() setTotalAmount()
670  * or setProcessedAmount() instead.
671  *
672  * @param job the job that emitted this signal
673  * @param percent the percentage
674  *
675  * @since 5.80
676  */
677  void percentChanged(KJob *job,
678  unsigned long percent
679 #if !defined(K_DOXYGEN)
680  ,
681  QPrivateSignal
682 #endif
683  );
684 
685  /**
686  * Emitted to display information about the speed of this job.
687  *
688  * @note This is a private signal, it shouldn't be emitted directly by subclasses of
689  * KJob, use emitSpeed() instead.
690  *
691  * @param job the job that emitted this signal
692  * @param speed the speed in bytes/s
693  */
694  void speed(KJob *job, unsigned long speed);
695 
696 protected:
697  /**
698  * Returns if the job has been finished and has emitted the finished() signal.
699  *
700  * @return if the job has been finished
701  * @see finished()
702  * @since 5.75
703  */
704  // KF6 TODO: make public. Useful at least for unittests that run multiple jobs in parallel.
705  bool isFinished() const;
706 
707  /**
708  * Sets the error code.
709  *
710  * It should be called when an error
711  * is encountered in the job, just before calling emitResult().
712  *
713  * You should define an (anonymous) enum of error codes,
714  * with values starting at KJob::UserDefinedError, and use
715  * those. For example,
716  * @code
717  * enum {
718  * InvalidFoo = UserDefinedError,
719  * BarNotFound,
720  * };
721  * @endcode
722  *
723  * @param errorCode the error code
724  * @see emitResult()
725  */
726  void setError(int errorCode);
727 
728  /**
729  * Sets the error text.
730  *
731  * It should be called when an error
732  * is encountered in the job, just before calling emitResult().
733  *
734  * Provides extra information about the error that cannot be
735  * determined directly from the error code. For example, a
736  * URL or filename. This string is not normally translatable.
737  *
738  * @param errorText the error text
739  * @see emitResult(), errorString(), setError()
740  */
741  void setErrorText(const QString &errorText);
742 
743  /**
744  * Sets the processed size. The processedAmount() and percent() signals
745  * are emitted if the values changed. The percent() signal is emitted
746  * only for the progress unit.
747  *
748  * @param unit the unit of the new processed amount
749  * @param amount the new processed amount
750  */
751  void setProcessedAmount(Unit unit, qulonglong amount);
752 
753  /**
754  * Sets the total size. The totalSize() and percent() signals
755  * are emitted if the values changed. The percent() signal is emitted
756  * only for the progress unit.
757  *
758  * @param unit the unit of the new total amount
759  * @param amount the new total amount
760  */
761  void setTotalAmount(Unit unit, qulonglong amount);
762 
763  /**
764  * Sets the unit that will be used internally to calculate
765  * the progress percentage.
766  * The default progress unit is Bytes.
767  * @since 5.76
768  */
769  void setProgressUnit(Unit unit);
770 
771  /**
772  * Sets the overall progress of the job. The percent() signal
773  * is emitted if the value changed.
774  *
775  * The job takes care of this if you call setProcessedAmount
776  * in Bytes (or the unit set by setProgressUnit).
777  * This method allows you to set your own progress, as an alternative.
778  *
779  * @param percentage the new overall progress
780  */
781  void setPercent(unsigned long percentage);
782 
783  /**
784  * Utility function to emit the result signal, and suicide this job.
785  * It first notifies the observers to hide the progress for this job using
786  * the finished() signal.
787  *
788  * @note Deletes this job using deleteLater().
789  *
790  * @see result()
791  * @see finished()
792  */
793  void emitResult();
794 
795  /**
796  * Utility function for inherited jobs.
797  * Emits the percent signal if bigger than previous value,
798  * after calculating it from the parameters.
799  *
800  * @param processedAmount the processed amount
801  * @param totalAmount the total amount
802  * @see percent()
803  */
804  void emitPercent(qulonglong processedAmount, qulonglong totalAmount);
805 
806  /**
807  * Utility function for inherited jobs.
808  * Emits the speed signal and starts the timer for removing that info
809  *
810  * @param speed the speed in bytes/s
811  */
812  void emitSpeed(unsigned long speed);
813 
814 protected:
815  std::unique_ptr<KJobPrivate> const d_ptr;
816 
817  KCOREADDONS_NO_EXPORT KJob(KJobPrivate &dd, QObject *parent);
818 
819 private:
820  KCOREADDONS_NO_EXPORT void finishJob(bool emitResult);
821 
822  Q_DECLARE_PRIVATE(KJob)
823 };
824 
825 Q_DECLARE_METATYPE(KJob::Unit)
826 Q_DECLARE_OPERATORS_FOR_FLAGS(KJob::Capabilities)
827 
828 #endif
Q_PROPERTY(...)
Q_ENUM(...)
Q_SLOTSQ_SLOTS
@ Files
The number of files handled by the job.
Definition: kjob.h:89
Q_SCRIPTABLE Q_NOREPLY void start()
@ Directories
The number of directories handled by the job.
Definition: kjob.h:90
Definition: kjob.h:73
void suspend()
void error(QWidget *parent, const QString &text, const QString &title, const KGuiItem &buttonOk, Options options=Notify)
Q_SIGNALSQ_SIGNALS
Unit
Describes the unit used in the methods that handle reporting the job progress info.
Definition: kjob.h:87
Capability
Definition: kjob.h:101
@ UnitsCount
Definition: kjob.h:94
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Dec 5 2023 04:05:49 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.