1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2016 Kai Uwe Broulik <kde@privat.broulik.de>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef OPENFILEMANAGERWINDOWJOB_H
9#define OPENFILEMANAGERWINDOWJOB_H
10
11#include "kiogui_export.h"
12
13#include <KJob>
14
15#include <QList>
16#include <QUrl>
17
18#include <memory>
19
20namespace KIO
21{
22class OpenFileManagerWindowJobPrivate;
23
24/**
25 * @class KIO::OpenFileManagerWindowJob openfilemanagerwindowjob.h <KIO/OpenFileManagerWindowJob>
26 *
27 * @brief Open a File Manager Window
28 *
29 * Using this job you can open a file manager window and highlight specific
30 * files within a folder. This can be useful if you downloaded a file and want
31 * to present it to the user without the user having to manually search the
32 * file in its parent folder. This can also be used for a "Show in Parent Folder"
33 * functionality.
34 *
35 * On Linux, this job will use the org.freedesktop.FileManager1 interface to highlight
36 * the files and/or folders. If this fails, the parent directory of the first URL
37 * will be opened in the default file manager instead.
38 *
39 * Note that this job is really only about highlighting certain items
40 * which means if you, for example, pass it just a URL to a folder it will
41 * not open this particular folder but instead highlight it within its parent folder.
42 *
43 * If you just want to open a folder, use OpenUrlJob instead.
44 *
45 * @since 5.24
46 */
47class KIOGUI_EXPORT OpenFileManagerWindowJob : public KJob
48{
49 Q_OBJECT
50
51public:
52 /**
53 * Creates an OpenFileManagerWindowJob
54 */
55 explicit OpenFileManagerWindowJob(QObject *parent = nullptr);
56
57 /**
58 * Destroys the OpenFileManagerWindowJob
59 */
60 ~OpenFileManagerWindowJob() override;
61
62 /**
63 * Errors the job may emit
64 */
65 enum Errors {
66 NoValidUrlsError = KJob::UserDefinedError, ///< No valid URLs to highlight have been specified
67 LaunchFailedError, ///< Failed to launch the file manager
68 };
69
70 /**
71 * The files and/or folders to highlight
72 */
73 QList<QUrl> highlightUrls() const;
74
75 /**
76 * Set the files and/or folders to highlight
77 */
78 void setHighlightUrls(const QList<QUrl> &highlightUrls);
79
80 /**
81 * The Startup ID
82 */
83 QByteArray startupId() const;
84
85 /**
86 * Sets the platform-specific startup id of the file manager launch.
87 * @param startupId startup id, if any (otherwise "").
88 * For X11, this would be the id for the Startup Notification protocol.
89 * For Wayland, this would be the token for the XDG Activation protocol.
90 */
91 void setStartupId(const QByteArray &startupId);
92
93 /**
94 * Starts the job
95 */
96 void start() override;
97
98private:
99 friend class AbstractOpenFileManagerWindowStrategy;
100 friend class OpenFileManagerWindowDBusStrategy;
101 friend class OpenFileManagerWindowKRunStrategy;
102
103 std::unique_ptr<OpenFileManagerWindowJobPrivate> const d;
104};
105
106/**
107 * Convenience method for creating a job to highlight a certain file or folder.
108 *
109 * It will create a job for a given URL(s) and automatically start it.
110 *
111 * @since 5.24
112 */
113KIOGUI_EXPORT OpenFileManagerWindowJob *highlightInFileManager(const QList<QUrl> &urls, const QByteArray &asn = QByteArray());
114
115} // namespace KIO
116
117#endif // OPENFILEMANAGERWINDOWJOB_H
118

source code of kio/src/gui/openfilemanagerwindowjob.h