1/*
2 This file is part of the KDE project
3 SPDX-FileCopyrightText: 1998-2009 David Faure <faure@kde.org>
4 SPDX-FileCopyrightText: 2003 Sven Leiber <s.leiber@web.de>
5
6 SPDX-License-Identifier: LGPL-2.0-only OR LGPL-3.0-only
7*/
8
9#ifndef KNEWFILEMENU_H
10#define KNEWFILEMENU_H
11
12#include "kiofilewidgets_export.h"
13
14#include <KActionMenu>
15#include <QUrl>
16
17#include <memory>
18
19class KJob;
20
21class KActionCollection;
22class KNewFileMenuPrivate;
23
24/**
25 * @class KNewFileMenu knewfilemenu.h <KNewFileMenu>
26 *
27 * The 'Create New' submenu, for creating files using templates
28 * (e.g.\ "new HTML file") and directories.
29 *
30 * The same instance can be used by both for the File menu and the RMB popup menu,
31 * in a file manager. This is also used in the file dialog's RMB menu.
32 *
33 * To use this class, you need to connect aboutToShow() of the File menu
34 * with slotCheckUpToDate() and to call slotCheckUpToDate() before showing
35 * the RMB popupmenu.
36 *
37 * KNewFileMenu automatically updates the list of templates shown if installed templates
38 * are added/updated/deleted.
39 *
40 * @author Björn Ruberg <bjoern@ruberg-wegener.de>
41 * Made dialogs working asynchronously
42 * @author David Faure <faure@kde.org>
43 * Ideas and code for the new template handling mechanism ('link' desktop files)
44 * from Christoph Pickart <pickart@iam.uni-bonn.de>
45 */
46class KIOFILEWIDGETS_EXPORT KNewFileMenu : public KActionMenu
47{
48 Q_OBJECT
49public:
50 /**
51 * Constructor.
52 *
53 * @param parent the parent object, for ownership.
54 * If the parent object is a widget, it will also be used as the parent widget
55 * for any dialogs that this class might show. Otherwise, call setParentWidget.
56 *
57 * @since 5.100
58 */
59 KNewFileMenu(QObject *parent);
60
61 /**
62 * Destructor.
63 * KNewMenu uses internally a globally shared cache, so that multiple instances
64 * of it don't need to parse the installed templates multiple times. Therefore
65 * you can safely create and delete KNewMenu instances without a performance issue.
66 */
67 ~KNewFileMenu() override;
68
69 /**
70 * Returns the modality of dialogs
71 */
72 bool isModal() const;
73
74 /**
75 * Sets the modality of dialogs created by KNewFile. Set to false if you do not want to block
76 * your application window when entering a new directory name i.e.
77 */
78 void setModal(bool modality);
79
80 /**
81 * Sets a parent widget for the dialogs shown by KNewFileMenu.
82 * This is strongly recommended, for apps with a main window.
83 */
84 void setParentWidget(QWidget *parentWidget);
85
86 /**
87 * Set the working directory.
88 * Files will be created relative to this directory.
89 * @since 5.97.
90 */
91 void setWorkingDirectory(const QUrl &directory);
92
93 /**
94 * Returns the working directory.
95 * Files will be created relative to this directory.
96 * @since 5.97.
97 */
98 QUrl workingDirectory() const;
99
100 /**
101 * Only show the files in a given set of MIME types.
102 * This is useful in specialized applications (while file managers, on
103 * the other hand, want to show all MIME types).
104 */
105 void setSupportedMimeTypes(const QStringList &mime);
106
107 /**
108 * Returns the MIME types set in supportedMimeTypes()
109 */
110 QStringList supportedMimeTypes() const;
111
112 /**
113 * Whether on not the dialog should emit `selectExistingDir` when trying to create an exist directory
114 *
115 * default: false
116 *
117 * @since 5.76
118 */
119 void setSelectDirWhenAlreadyExist(bool b);
120
121 /**
122 * Use this to set a shortcut for the "New Folder" action.
123 *
124 * The shortcut is copied from @param action.
125 *
126 * @since 5.100
127 */
128 void setNewFolderShortcutAction(QAction *action);
129
130 /**
131 * Use this to set a shortcut for the new file action.
132 *
133 * The shortcut is copied from @param action.
134 *
135 * @since 5.100
136 */
137 void setNewFileShortcutAction(QAction *action);
138
139 /**
140 * Use this to check if namejob for new directory creation still running.
141 * Namejob is what spawns the new directory dialog, which can be slow in,
142 * for example, network folders.
143 *
144 * @since 6.2
145 */
146 bool isCreateDirectoryRunning();
147
148 /**
149 * Use this to check if the file creation process is still running.
150 * @since 6.2
151 */
152 bool isCreateFileRunning();
153
154public Q_SLOTS:
155 /**
156 * Checks if updating the list is necessary
157 * IMPORTANT : Call this in the slot for aboutToShow.
158 */
159 void checkUpToDate();
160
161 /**
162 * Call this to create a new directory as if the user had done it using
163 * a popupmenu. This is useful to make sure that creating a directory with
164 * a key shortcut (e.g. F10) triggers the exact same code as when using
165 * the New menu.
166 * Requirements: since 5.97 call setWorkingDirectory first (for older releases call setPopupFiles first), and keep this KNewFileMenu instance
167 * alive (the mkdir is async).
168 */
169 void createDirectory();
170
171 /**
172 * Call this to create a new file as if the user had done it using
173 * a popupmenu. This is useful to make sure that creating a directory with
174 * a key shortcut (e.g. Shift-F10) triggers the exact same code as when using
175 * the New menu.
176 * Requirements: since 5.97 call setWorkingDirectory first (for older releases call setPopupFiles first), and keep this KNewFileMenu instance
177 * alive (the copy is async).
178 * @since 5.53
179 */
180 void createFile();
181
182Q_SIGNALS:
183
184 /**
185 * Emitted once the creation job for file @p url has been started
186 * @since 6.2
187 */
188 void fileCreationStarted(const QUrl &url);
189
190 /**
191 * Emitted once the file (or symlink) @p url has been successfully created
192 */
193 void fileCreated(const QUrl &url);
194
195 /**
196 * Emitted once the creation for file @p url has been rejected
197 * @since 6.2
198 */
199 void fileCreationRejected(const QUrl &url);
200
201 /**
202 * Emitted once the creation job for directory @p url has been started
203 * @since 6.2
204 */
205 void directoryCreationStarted(const QUrl &url);
206
207 /**
208 * Emitted once the directory @p url has been successfully created
209 */
210 void directoryCreated(const QUrl &url);
211
212 /**
213 * Emitted once the creation for directory @p url has been rejected
214 * @since 6.2
215 */
216 void directoryCreationRejected(const QUrl &url);
217
218 /**
219 * Emitted when trying to create a new directory that has the same name as
220 * an existing one, so that KDirOperator can select the existing item in
221 * the view (in case the user wants to use that directory instead of creating
222 * a new one).
223 *
224 * @since 5.76
225 */
226 void selectExistingDir(const QUrl &url);
227
228protected Q_SLOTS:
229
230 /**
231 * Called when the job that copied the template has finished.
232 * This method is virtual so that error handling can be reimplemented.
233 * Make sure to call the base class slotResult when !job->error() though.
234 */
235 virtual void slotResult(KJob *job);
236
237private:
238 friend class KNewFileMenuPrivate;
239 std::unique_ptr<KNewFileMenuPrivate> const d;
240};
241
242#endif
243

source code of kio/src/filewidgets/knewfilemenu.h