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

source code of kio/src/core/namefinderjob.h