KDE API Reference

Contents

KIO::NameFinderJob Class

class KIO::NameFinderJob

NameFinderJob finds a valid "New Folder" name. More...

Header: #include <KIO/NameFinderJob>
CMake: find_package(KF6 REQUIRED COMPONENTS KIO)
target_link_libraries(mytarget PRIVATE KF6::KIOCore)
Since: 5.76
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

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.

// 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();

Member Function Documentation

[explicit] NameFinderJob::NameFinderJob(const QUrl &baseUrl, const QString &name, QObject *parent)

Creates a NameFinderJob to get a "New Folder" (or "Text File.txt") name that doesn't already exist.

baseUrl URL of the directory where a new folder/file is going to be created

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.