File indexing completed on 2024-09-29 09:29:01
0001 /* 0002 This file is part of the KDE project 0003 SPDX-FileCopyrightText: 1998-2009 David Faure <faure@kde.org> 0004 SPDX-FileCopyrightText: 2003 Sven Leiber <s.leiber@web.de> 0005 0006 SPDX-License-Identifier: LGPL-2.0-only OR LGPL-3.0-only 0007 */ 0008 0009 #ifndef KNEWFILEMENU_H 0010 #define KNEWFILEMENU_H 0011 0012 #include "kiofilewidgets_export.h" 0013 0014 #include <KActionMenu> 0015 #include <QUrl> 0016 0017 #include <memory> 0018 0019 class KJob; 0020 0021 class KActionCollection; 0022 class KNewFileMenuPrivate; 0023 0024 /** 0025 * @class KNewFileMenu knewfilemenu.h <KNewFileMenu> 0026 * 0027 * The 'Create New' submenu, for creating files using templates 0028 * (e.g.\ "new HTML file") and directories. 0029 * 0030 * The same instance can be used by both for the File menu and the RMB popup menu, 0031 * in a file manager. This is also used in the file dialog's RMB menu. 0032 * 0033 * To use this class, you need to connect aboutToShow() of the File menu 0034 * with slotCheckUpToDate() and to call slotCheckUpToDate() before showing 0035 * the RMB popupmenu. 0036 * 0037 * KNewFileMenu automatically updates the list of templates shown if installed templates 0038 * are added/updated/deleted. 0039 * 0040 * @author Björn Ruberg <bjoern@ruberg-wegener.de> 0041 * Made dialogs working asynchronously 0042 * @author David Faure <faure@kde.org> 0043 * Ideas and code for the new template handling mechanism ('link' desktop files) 0044 * from Christoph Pickart <pickart@iam.uni-bonn.de> 0045 * @since 4.5 0046 */ 0047 class KIOFILEWIDGETS_EXPORT KNewFileMenu : public KActionMenu 0048 { 0049 Q_OBJECT 0050 public: 0051 #if KIOFILEWIDGETS_ENABLE_DEPRECATED_SINCE(5, 100) 0052 /** 0053 * Constructor. 0054 * @param collection the KActionCollection the QAction with name @p name should be added to. 0055 * @param name action name, when adding the action to @p collection 0056 * @param parent the parent object, for ownership. 0057 * If the parent object is a widget, it will also used as parent widget 0058 * for any dialogs that this class might show. Otherwise, call setParentWidget. 0059 * @note If you want the "Create directory..." action shortcut to show up next to its text, 0060 * make sure to have an action with name "create_dir" (and shortcut set) in @p collection. 0061 * This will only work with KIO >= 5.27. 0062 * From KIO >= 5.53, an action named "create_file" (and shortcut set) in @p collection 0063 * will be linked to the creation of the first file template (either from XDG_TEMPLATES_DIR 0064 * or from :/kio5/newfile-templates) 0065 * @deprecated since 5.100, use KNewFileMenu(QObject *) instead. To associate the action shortcuts use 0066 * setNewFileShortcutAction() and setNewFolderShortcutAction() 0067 */ 0068 KIOFILEWIDGETS_DEPRECATED_VERSION(5, 100, "Use KNewFileMenu(QObject *)") 0069 KNewFileMenu(KActionCollection *collection, const QString &name, QObject *parent); 0070 #endif 0071 0072 /** 0073 * Constructor. 0074 * 0075 * @param parent the parent object, for ownership. 0076 * If the parent object is a widget, it will also be used as the parent widget 0077 * for any dialogs that this class might show. Otherwise, call setParentWidget. 0078 * 0079 * @since 5.100 0080 */ 0081 KNewFileMenu(QObject *parent); 0082 0083 /** 0084 * Destructor. 0085 * KNewMenu uses internally a globally shared cache, so that multiple instances 0086 * of it don't need to parse the installed templates multiple times. Therefore 0087 * you can safely create and delete KNewMenu instances without a performance issue. 0088 */ 0089 ~KNewFileMenu() override; 0090 0091 /** 0092 * Returns the modality of dialogs 0093 */ 0094 bool isModal() const; 0095 0096 #if KIOFILEWIDGETS_ENABLE_DEPRECATED_SINCE(5, 97) 0097 /** 0098 * Returns the files that the popup is shown for 0099 * @deprecated since 5.97, use KNewFileMenu::workingDirectory(). 0100 */ 0101 KIOFILEWIDGETS_DEPRECATED_VERSION(5, 97, "Use KNewFileMenu::workingDirectory()") 0102 QList<QUrl> popupFiles() const; 0103 #endif 0104 0105 /** 0106 * Sets the modality of dialogs created by KNewFile. Set to false if you do not want to block 0107 * your application window when entering a new directory name i.e. 0108 */ 0109 void setModal(bool modality); 0110 0111 /** 0112 * Sets a parent widget for the dialogs shown by KNewFileMenu. 0113 * This is strongly recommended, for apps with a main window. 0114 */ 0115 void setParentWidget(QWidget *parentWidget); 0116 0117 #if KIOFILEWIDGETS_ENABLE_DEPRECATED_SINCE(5, 97) 0118 /** 0119 * Set the files the popup is shown for 0120 * Call this before showing up the menu 0121 * @deprecated since 5.97, use KNewFileMenu::setWorkingDirectory(const QUrl &). 0122 */ 0123 KIOFILEWIDGETS_DEPRECATED_VERSION(5, 97, "Use KNewFileMenu::setWorkingDirectory(const QUrl &)") 0124 void setPopupFiles(const QList<QUrl> &files); 0125 #endif 0126 0127 /** 0128 * Set the working directory. 0129 * Files will be created relative to this directory. 0130 * @since 5.97. 0131 */ 0132 void setWorkingDirectory(const QUrl &directory); 0133 0134 /** 0135 * Returns the working directory. 0136 * Files will be created relative to this directory. 0137 * @since 5.97. 0138 */ 0139 QUrl workingDirectory() const; 0140 0141 #if KIOFILEWIDGETS_ENABLE_DEPRECATED_SINCE(5, 0) 0142 KIOFILEWIDGETS_DEPRECATED_VERSION(5, 0, "Use KNewFileMenu::setWorkingDirectory(const QUrl &)") 0143 void setPopupFiles(const QUrl &file) 0144 { 0145 setWorkingDirectory(file); 0146 } 0147 #endif 0148 0149 /** 0150 * Only show the files in a given set of MIME types. 0151 * This is useful in specialized applications (while file managers, on 0152 * the other hand, want to show all MIME types). 0153 */ 0154 void setSupportedMimeTypes(const QStringList &mime); 0155 0156 #if KIOFILEWIDGETS_ENABLE_DEPRECATED_SINCE(5, 97) 0157 KIOFILEWIDGETS_DEPRECATED_VERSION(5, 97, "Calling this has no effect") 0158 /** 0159 * Set if the directory view currently shows dot files. 0160 * @deprecated since 5.97. Calling this has no effect. 0161 */ 0162 void setViewShowsHiddenFiles(bool b); 0163 #endif 0164 0165 /** 0166 * Returns the MIME types set in supportedMimeTypes() 0167 */ 0168 QStringList supportedMimeTypes() const; 0169 0170 /** 0171 * Whether on not the dialog should emit `selectExistingDir` when trying to create an exist directory 0172 * 0173 * default: false 0174 * 0175 * @since 5.76 0176 */ 0177 void setSelectDirWhenAlreadyExist(bool b); 0178 0179 /** 0180 * Use this to set a shortcut for the "New Folder" action. 0181 * 0182 * The shortcut is copied from @param action. 0183 * 0184 * @since 5.100 0185 */ 0186 void setNewFolderShortcutAction(QAction *action); 0187 0188 /** 0189 * Use this to set a shortcut for the new file action. 0190 * 0191 * The shortcut is copied from @param action. 0192 * 0193 * @since 5.100 0194 */ 0195 void setNewFileShortcutAction(QAction *action); 0196 0197 public Q_SLOTS: 0198 /** 0199 * Checks if updating the list is necessary 0200 * IMPORTANT : Call this in the slot for aboutToShow. 0201 */ 0202 void checkUpToDate(); 0203 0204 /** 0205 * Call this to create a new directory as if the user had done it using 0206 * a popupmenu. This is useful to make sure that creating a directory with 0207 * a key shortcut (e.g. F10) triggers the exact same code as when using 0208 * the New menu. 0209 * Requirements: since 5.97 call setWorkingDirectory first (for older releases call setPopupFiles first), and keep this KNewFileMenu instance 0210 * alive (the mkdir is async). 0211 */ 0212 void createDirectory(); 0213 0214 /** 0215 * Call this to create a new file as if the user had done it using 0216 * a popupmenu. This is useful to make sure that creating a directory with 0217 * a key shortcut (e.g. Shift-F10) triggers the exact same code as when using 0218 * the New menu. 0219 * Requirements: since 5.97 call setWorkingDirectory first (for older releases call setPopupFiles first), and keep this KNewFileMenu instance 0220 * alive (the copy is async). 0221 * @since 5.53 0222 */ 0223 void createFile(); 0224 0225 Q_SIGNALS: 0226 /** 0227 * Emitted once the file (or symlink) @p url has been successfully created 0228 */ 0229 void fileCreated(const QUrl &url); 0230 0231 /** 0232 * Emitted once the directory @p url has been successfully created 0233 */ 0234 void directoryCreated(const QUrl &url); 0235 0236 /** 0237 * Emitted when trying to create a new directory that has the same name as 0238 * an existing one, so that KDirOperator can select the existing item in 0239 * the view (in case the user wants to use that directory instead of creating 0240 * a new one). 0241 * 0242 * @since 5.76 0243 */ 0244 void selectExistingDir(const QUrl &url); 0245 0246 protected Q_SLOTS: 0247 0248 /** 0249 * Called when the job that copied the template has finished. 0250 * This method is virtual so that error handling can be reimplemented. 0251 * Make sure to call the base class slotResult when !job->error() though. 0252 */ 0253 virtual void slotResult(KJob *job); 0254 0255 private: 0256 friend class KNewFileMenuPrivate; 0257 std::unique_ptr<KNewFileMenuPrivate> const d; 0258 }; 0259 0260 #endif