KIO

namefinderjob.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 2020 Ahmad Samir <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.0-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
6 */
7 
8 #ifndef KIO_NAMEFINDERJOB_H
9 #define KIO_NAMEFINDERJOB_H
10 
11 #include "kiocore_export.h"
12 #include <KCompositeJob>
13 
14 #include <memory>
15 
16 namespace KIO
17 {
18 class NameFinderJobPrivate;
19 /**
20  * @class KIO::NameFinderJob namefinderjob.h <KIO/NameFinderJob>
21  *
22  *
23  * @brief NameFinderJob finds a valid "New Folder" name.
24  *
25  * This job is useful when suggesting a new folder/file name, e.g. in KNewFileMenu,
26  * the text box is pre-filled with a suggested name, typically in the form "New Folder";
27  * to offer a valid name (i.e. one that doesn't already exist), you can use a NameFinderJob.
28  *
29  * Internally it uses a KIO::StatJob to determine if e.g. "New Folder" already exists,
30  * and in such a case it will use KFileUtils::makeSuggestedName() to make a new name,
31  * e.g. "New Folder (1)", then if the latter exists, KFileUtils::makeSuggestedName() will
32  * be called again... etc, until it finds a name that doesn't already exist.
33  *
34  * Since NameFinderJob uses a KIO::StatJob, the code is asynchronous, which means it should
35  * work for both local and remote filesystems without blocking I/O calls (this is important
36  * when interacting with network mounts (e.g. SMB, NFS), from the upstream QFile perspective
37  * these network mounts are "local" files even though they could actually reside on a server
38  * halfway across the world).
39  *
40  * Note that KIO::StatJob will resolve URLs such as "desktop:/" to the most local URL, hence
41  * it's advisable to always use baseUrl() (or finalUrl()) to get the actual URL.
42  *
43  * If the job fails for any reason targerUrl() will return an empty URL.
44  *
45  * @note You must call start() to start the job.
46  *
47  * @code
48  * // Create the job
49  * auto nameJob = new KIO::NameFinderJob(baseUrl, name, this);
50  * // Connect to the result() slot, and after making sure there were no errors call
51  * // finalUrl(), baseUrl() or finalName() to get the new url (base
52  * // url + suggested name), base url or suggested name, respectively
53  * connect(nameJob, &KJob::result, this, []() {
54  * if (!nameJob->error()) {
55  * const QUrl newBaseUrl = nameJob->baseUrl();
56  * const QUrl newName = nameJob->finalName();
57  * .....
58  * // Create the new dir "newName" in "newBaseUrl"
59  * }
60  * });
61  *
62  * // Start the job
63  * nameJob->start();
64  * @endcode
65  *
66  * @since 5.76
67  */
68 
69 class KIOCORE_EXPORT NameFinderJob : public KCompositeJob
70 {
71  Q_OBJECT
72 
73 public:
74  /**
75  * @brief Creates a NameFinderJob to get a "New Folder" (or "Text File.txt") name that doesn't
76  * already exist.
77  *
78  * @param baseUrl URL of the directory where a new folder/file is going to be created
79  * @param name the initially proposed name of the new folder/file
80  */
81  explicit NameFinderJob(const QUrl &baseUrl, const QString &name, QObject *parent);
82 
83  /**
84  * Destructor
85  *
86  * Note that by default jobs auto-delete themselves after emitting result.
87  */
88  ~NameFinderJob() override;
89 
90  /**
91  * Starts the job.
92  */
93  void start() override;
94 
95  /**
96  * Call this to get the full target URL (basically the baseUrl() + "/" + finalName()).
97  * Typically you should call this in a slot connected to the result() signal, and after
98  * making sure no errors occurred (if there were an error this method will return an empty URL).
99  */
100  QUrl finalUrl() const;
101 
102  /**
103  * Call this to get the base URL (i.e.\ the URL of the folder where a new folder/file
104  * is going to be created). Note that this could return a different URL from the one
105  * the job was initially called on, since the StatJob (which is used internally) will
106  * resolve the URL to the most local one. See KIO::StatJob::mostLocalUrl() for more details.
107  *
108  * Typically you should call this in a slot connected to the result() signal, and after
109  * making sure no errors occurred.
110  */
111  QUrl baseUrl() const;
112 
113  /**
114  * Call this to get the suggested new folder/file name. Typically you should call this in a
115  * slot connected to the result() signal and after making sure no errors occurred.
116  */
117  QString finalName() const;
118 
119 private:
120  friend class NameFinderJobPrivate;
121  std::unique_ptr<NameFinderJobPrivate> d;
122 };
123 
124 } // namespace KIO
125 
126 #endif
Q_SCRIPTABLE Q_NOREPLY void start()
NameFinderJob finds a valid "New Folder" name.
Definition: namefinderjob.h:69
A namespace for KIO globals.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon Feb 6 2023 04:00:02 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.