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 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
69class KIOCORE_EXPORT NameFinderJob : public KCompositeJob
70{
71 Q_OBJECT
72
73public:
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
119private:
120 friend class NameFinderJobPrivate;
121 std::unique_ptr<NameFinderJobPrivate> d;
122};
123
124} // namespace KIO
125
126#endif
127

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