openfilemanagerwindowjob.h

/*
    This file is part of the KDE libraries
    SPDX-FileCopyrightText: 2016 Kai Uwe Broulik <kde@privat.broulik.de>
 
    SPDX-License-Identifier: LGPL-2.0-or-later
*/
 
#ifndef OPENFILEMANAGERWINDOWJOB_H
#define OPENFILEMANAGERWINDOWJOB_H
 
#include "kiogui_export.h"
 
#include <KJob>
 
#include <QList>
#include <QUrl>
 
#include <memory>
 
namespace KIO
{
class OpenFileManagerWindowJobPrivate;
 
/**
 * @class KIO::OpenFileManagerWindowJob openfilemanagerwindowjob.h <KIO/OpenFileManagerWindowJob>
 *
 * @brief Open a File Manager Window
 *
 * Using this job you can open a file manager window and highlight specific
 * files within a folder. This can be useful if you downloaded a file and want
 * to present it to the user without the user having to manually search the
 * file in its parent folder. This can also be used for a "Show in Parent Folder"
 * functionality.
 *
 * On Linux, this job will use the org.freedesktop.FileManager1 interface to highlight
 * the files and/or folders. If this fails, the parent directory of the first URL
 * will be opened in the default file manager instead.
 *
 * Note that this job is really only about highlighting certain items
 * which means if you, for example, pass it just a URL to a folder it will
 * not open this particular folder but instead highlight it within its parent folder.
 *
 * If you just want to open a folder, use OpenUrlJob instead.
 *
 * @since 5.24
 */
class KIOGUI_EXPORT OpenFileManagerWindowJob : public KJob
{
    Q_OBJECT
 
public:
    /**
     * Creates an OpenFileManagerWindowJob
     */
    explicit OpenFileManagerWindowJob(QObject *parent = nullptr);
 
    /**
     * Destroys the OpenFileManagerWindowJob
     */
    ~OpenFileManagerWindowJob() override;
 
    /**
     * Errors the job may emit
     */
    enum Errors {
        NoValidUrlsError = KJob::UserDefinedError, ///< No valid URLs to highlight have been specified
        LaunchFailedError, ///< Failed to launch the file manager
    };
 
    /**
     * The files and/or folders to highlight
     */
    QList<QUrl> highlightUrls() const;
 
    /**
     * Set the files and/or folders to highlight
     */
    void setHighlightUrls(const QList<QUrl> &highlightUrls);
 
    /**
     * The Startup ID
     */
    QByteArray startupId() const;
 
    /**
     * Sets the platform-specific startup id of the file manager launch.
     * @param startupId startup id, if any (otherwise "").
     * For X11, this would be the id for the Startup Notification protocol.
     * For Wayland, this would be the token for the XDG Activation protocol.
     */
    void setStartupId(const QByteArray &startupId);
 
    /**
     * Starts the job
     */
    void start() override;
 
private:
    friend class AbstractOpenFileManagerWindowStrategy;
    friend class OpenFileManagerWindowDBusStrategy;
    friend class OpenFileManagerWindowKRunStrategy;
 
    std::unique_ptr<OpenFileManagerWindowJobPrivate> const d;
};
 
/**
 * Convenience method for creating a job to highlight a certain file or folder.
 *
 * It will create a job for a given URL(s) and automatically start it.
 *
 * @since 5.24
 */
KIOGUI_EXPORT OpenFileManagerWindowJob *highlightInFileManager(const QList<QUrl> &urls, const QByteArray &asn = QByteArray());
 
} // namespace KIO
 
#endif // OPENFILEMANAGERWINDOWJOB_H