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
26 * \inheaderfile KIO/OpenFileManagerWindowJob
27 * \inmodule KIOGui
28 *
29 * \brief Open a File Manager Window.
30 *
31 * Using this job you can open a file manager window and highlight specific
32 * files within a folder. This can be useful if you downloaded a file and want
33 * to present it to the user without the user having to manually search the
34 * file in its parent folder. This can also be used for a "Show in Parent Folder"
35 * functionality.
36 *
37 * On Linux, this job will use the org.freedesktop.FileManager1 interface to highlight
38 * the files and/or folders. If this fails, the parent directory of the first URL
39 * will be opened in the default file manager instead.
40 *
41 * Note that this job is really only about highlighting certain items
42 * which means if you, for example, pass it just a URL to a folder it will
43 * not open this particular folder but instead highlight it within its parent folder.
44 *
45 * If you just want to open a folder, use OpenUrlJob instead.
46 *
47 * \since 5.24
48 */
49class KIOGUI_EXPORT OpenFileManagerWindowJob : public KJob
50{
51 Q_OBJECT
52
53public:
54 /*!
55 * Creates an OpenFileManagerWindowJob
56 */
57 explicit OpenFileManagerWindowJob(QObject *parent = nullptr);
58
59 ~OpenFileManagerWindowJob() override;
60
61 /*!
62 * Errors the job may emit
63 *
64 * \value NoValidUrlsError No valid URLs to highlight have been specified
65 * \value LaunchFailedError Failed to launch the file manager
66 */
67 enum Errors {
68 NoValidUrlsError = KJob::UserDefinedError,
69 LaunchFailedError,
70 };
71
72 /*!
73 * The files and/or folders to highlight
74 */
75 QList<QUrl> highlightUrls() const;
76
77 /*!
78 * Set the files and/or folders to highlight
79 */
80 void setHighlightUrls(const QList<QUrl> &highlightUrls);
81
82 /*!
83 * The Startup ID
84 */
85 QByteArray startupId() const;
86
87 /*!
88 * Sets the platform-specific startup id of the file manager launch.
89 *
90 * \a startupId startup id, if any (otherwise "").
91 *
92 * For X11, this would be the id for the Startup Notification protocol.
93 *
94 * For Wayland, this would be the token for the XDG Activation protocol.
95 */
96 void setStartupId(const QByteArray &startupId);
97
98 /*!
99 * Starts the job
100 */
101 void start() override;
102
103private:
104 friend class AbstractOpenFileManagerWindowStrategy;
105 friend class OpenFileManagerWindowDBusStrategy;
106 friend class OpenFileManagerWindowKRunStrategy;
107
108 std::unique_ptr<OpenFileManagerWindowJobPrivate> const d;
109};
110
111/*!
112 * \relates KIO::OpenFileManagerWindowJob
113 *
114 * Convenience method for creating a job to highlight a certain file or folder.
115 *
116 * It will create a job for a given URL(s) and automatically start it.
117 *
118 * \since 5.24
119 */
120KIOGUI_EXPORT OpenFileManagerWindowJob *highlightInFileManager(const QList<QUrl> &urls, const QByteArray &asn = QByteArray());
121
122} // namespace KIO
123
124#endif // OPENFILEMANAGERWINDOWJOB_H
125

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