KIO::NameFinderJob Class
| Header: | #include <NameFinderJob> |
| CMake: | find_package(KF6 REQUIRED COMPONENTS KIO)target_link_libraries(mytarget PRIVATE KF6::KIOCore) |
| Inherits: | KCompositeJob |
Public Functions
| NameFinderJob(const QUrl &baseUrl, const QString &name, QObject *parent) | |
| virtual | ~NameFinderJob() override |
| QUrl | baseUrl() const |
| QString | finalName() const |
| QUrl | finalUrl() const |
Reimplemented Public Functions
| virtual void | start() override |
Detailed Description
@class KIO::NameFinderJob namefinderjob.h <KIO/NameFinderJob>
@brief NameFinderJob finds a valid "New Folder" name.
This job is useful when suggesting a new folder/file name, e.g. in KNewFileMenu, the text box is pre-filled with a suggested name, typically in the form "New Folder"; to offer a valid name (i.e. one that doesn't already exist), you can use a NameFinderJob.
Internally it uses a KIO::StatJob to determine if e.g. "New Folder" already exists, and in such a case it will use KFileUtils::makeSuggestedName() to make a new name, e.g. "New Folder (1)", then if the latter exists, KFileUtils::makeSuggestedName() will be called again... etc, until it finds a name that doesn't already exist.
Since NameFinderJob uses a KIO::StatJob, the code is asynchronous, which means it should work for both local and remote filesystems without blocking I/O calls (this is important when interacting with network mounts (e.g. SMB, NFS), from the upstream QFile perspective these network mounts are "local" files even though they could actually reside on a server halfway across the world).
Note that KIO::StatJob will resolve URLs such as "desktop:/" to the most local URL, hence it's advisable to always use baseUrl() (or finalUrl()) to get the actual URL.
If the job fails for any reason targerUrl() will return an empty URL.
@note You must call start() to start the job.
@code // Create the job auto nameJob = new KIO::NameFinderJob(baseUrl, name, this); // Connect to the result() slot, and after making sure there were no errors call // finalUrl(), baseUrl() or finalName() to get the new url (base // url + suggested name), base url or suggested name, respectively connect(nameJob, &KJob::result, this, []() { if (!nameJob->error()) { const QUrl newBaseUrl = nameJob->baseUrl(); const QUrl newName = nameJob->finalName(); ..... // Create the new dir "newName" in "newBaseUrl" } });
// Start the job nameJob->start(); @endcode
@since 5.76
Member Function Documentation
[explicit] NameFinderJob::NameFinderJob(const QUrl &baseUrl, const QString &name, QObject *parent)
@brief Creates a NameFinderJob to get a "New Folder" (or "Text File.txt") name that doesn't already exist.
@param baseUrl URL of the directory where a new folder/file is going to be created @param name the initially proposed name of the new folder/file
[override virtual noexcept] NameFinderJob::~NameFinderJob()
Destructor
Note that by default jobs auto-delete themselves after emitting result.
QUrl NameFinderJob::baseUrl() const
Call this to get the base URL (i.e. the URL of the folder where a new folder/file is going to be created). Note that this could return a different URL from the one the job was initially called on, since the StatJob (which is used internally) will resolve the URL to the most local one. See KIO::StatJob::mostLocalUrl() for more details.
Typically you should call this in a slot connected to the result() signal, and after making sure no errors occurred.
QString NameFinderJob::finalName() const
Call this to get the suggested new folder/file name. Typically you should call this in a slot connected to the result() signal and after making sure no errors occurred.
QUrl NameFinderJob::finalUrl() const
Call this to get the full target URL (basically the baseUrl() + "/" + finalName()). Typically you should call this in a slot connected to the result() signal, and after making sure no errors occurred (if there were an error this method will return an empty URL).
[override virtual] void NameFinderJob::start()
Reimplements: KJob::start().
Starts the job.