File indexing completed on 2024-06-16 10:06:22

0001 /*
0002     This file is part of the KDE libraries
0003     SPDX-FileCopyrightText: 2016 Kai Uwe Broulik <kde@privat.broulik.de>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-or-later
0006 */
0007 
0008 #ifndef OPENFILEMANAGERWINDOWJOB_H
0009 #define OPENFILEMANAGERWINDOWJOB_H
0010 
0011 #include "kiowidgets_export.h"
0012 
0013 #include <KJob>
0014 
0015 #include <QList>
0016 #include <QUrl>
0017 
0018 #include <memory>
0019 
0020 namespace KIO
0021 {
0022 class OpenFileManagerWindowJobPrivate;
0023 
0024 /**
0025  * @class KIO::OpenFileManagerWindowJob openfilemanagerwindowjob.h <KIO/OpenFileManagerWindowJob>
0026  *
0027  * @brief Open a File Manager Window
0028  *
0029  * Using this job you can open a file manager window and highlight specific
0030  * files within a folder. This can be useful if you downloaded a file and want
0031  * to present it to the user without the user having to manually search the
0032  * file in its parent folder. This can also be used for a "Show in Parent Folder"
0033  * functionality.
0034  *
0035  * On Linux, this job will use the org.freedesktop.FileManager1 interface to highlight
0036  * the files and/or folders. If this fails, the parent directory of the first URL
0037  * will be opened in the default file manager instead.
0038  *
0039  * Note that this job is really only about highlighting certain items
0040  * which means if you, for example, pass it just a URL to a folder it will
0041  * not open this particular folder but instead highlight it within its parent folder.
0042  *
0043  * If you just want to open a folder, use OpenUrlJob instead.
0044  *
0045  * @since 5.24
0046  */
0047 class KIOWIDGETS_EXPORT OpenFileManagerWindowJob : public KJob
0048 {
0049     Q_OBJECT
0050 
0051 public:
0052     /**
0053      * Creates an OpenFileManagerWindowJob
0054      */
0055     explicit OpenFileManagerWindowJob(QObject *parent = nullptr);
0056 
0057     /**
0058      * Destroys the OpenFileManagerWindowJob
0059      */
0060     ~OpenFileManagerWindowJob() override;
0061 
0062     /**
0063      * Errors the job may emit
0064      */
0065     enum Errors {
0066         NoValidUrlsError = KJob::UserDefinedError, ///< No valid URLs to highlight have been specified
0067         LaunchFailedError, ///< Failed to launch the file manager
0068     };
0069 
0070     /**
0071      * The files and/or folders to highlight
0072      */
0073     QList<QUrl> highlightUrls() const;
0074 
0075     /**
0076      * Set the files and/or folders to highlight
0077      */
0078     void setHighlightUrls(const QList<QUrl> &highlightUrls);
0079 
0080     /**
0081      * The Startup ID
0082      */
0083     QByteArray startupId() const;
0084 
0085     /**
0086      * Sets the platform-specific startup id of the file manager launch.
0087      * @param startupId startup id, if any (otherwise "").
0088      * For X11, this would be the id for the Startup Notification protocol.
0089      * For Wayland, this would be the token for the XDG Activation protocol.
0090      */
0091     void setStartupId(const QByteArray &startupId);
0092 
0093     /**
0094      * Starts the job
0095      */
0096     void start() override;
0097 
0098 private:
0099     friend class AbstractOpenFileManagerWindowStrategy;
0100     friend class OpenFileManagerWindowDBusStrategy;
0101     friend class OpenFileManagerWindowKRunStrategy;
0102 
0103     std::unique_ptr<OpenFileManagerWindowJobPrivate> const d;
0104 };
0105 
0106 /**
0107  * Convenience method for creating a job to highlight a certain file or folder.
0108  *
0109  * It will create a job for a given URL(s) and automatically start it.
0110  *
0111  * @since 5.24
0112  */
0113 KIOWIDGETS_EXPORT OpenFileManagerWindowJob *highlightInFileManager(const QList<QUrl> &urls, const QByteArray &asn = QByteArray());
0114 
0115 } // namespace KIO
0116 
0117 #endif // OPENFILEMANAGERWINDOWJOB_H