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

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