KIO

openfilemanagerwindowjob.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 2016 Kai Uwe Broulik <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.0-or-later
6 */
7 
8 #ifndef OPENFILEMANAGERWINDOWJOB_H
9 #define OPENFILEMANAGERWINDOWJOB_H
10 
11 #include "kiowidgets_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 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  */
47 class KIOWIDGETS_EXPORT OpenFileManagerWindowJob : public KJob
48 {
49  Q_OBJECT
50 
51 public:
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 
98 private:
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  */
113 KIOWIDGETS_EXPORT OpenFileManagerWindowJob *highlightInFileManager(const QList<QUrl> &urls, const QByteArray &asn = QByteArray());
114 
115 } // namespace KIO
116 
117 #endif // OPENFILEMANAGERWINDOWJOB_H
OpenFileManagerWindowJob * highlightInFileManager(const QList< QUrl > &urls, const QByteArray &asn)
Convenience method for creating a job to highlight a certain file or folder.
Q_SCRIPTABLE Q_NOREPLY void start()
@ LaunchFailedError
Failed to launch the file manager.
Open a File Manager Window.
A namespace for KIO globals.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Feb 5 2023 04:00:52 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.