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 | |
20 | namespace KIO |
21 | { |
22 | class 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 | */ |
49 | class KIOGUI_EXPORT OpenFileManagerWindowJob : public KJob |
50 | { |
51 | Q_OBJECT |
52 | |
53 | public: |
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 | |
103 | private: |
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 | */ |
120 | KIOGUI_EXPORT OpenFileManagerWindowJob *highlightInFileManager(const QList<QUrl> &urls, const QByteArray &asn = QByteArray()); |
121 | |
122 | } // namespace KIO |
123 | |
124 | #endif // OPENFILEMANAGERWINDOWJOB_H |
125 | |