File indexing completed on 2024-04-14 14:25:13

0001 /*
0002     This file is part of the KDE project
0003     SPDX-FileCopyrightText: 1998, 1999 Torben Weis <weis@kde.org>
0004     SPDX-FileCopyrightText: 1999, 2000 Preston Brown <pbrown@kde.org>
0005     SPDX-FileCopyrightText: 2000 Simon Hausmann <hausmann@kde.org>
0006     SPDX-FileCopyrightText: 2000 David Faure <faure@kde.org>
0007 
0008     SPDX-License-Identifier: LGPL-2.0-or-later
0009 */
0010 
0011 #ifndef KPROPERTIESDIALOG_H
0012 #define KPROPERTIESDIALOG_H
0013 
0014 #include <QString>
0015 #include <QUrl>
0016 
0017 #include "kiowidgets_export.h"
0018 #include <kfileitem.h>
0019 
0020 #include <KPageDialog>
0021 
0022 #include <memory>
0023 
0024 class KPropertiesDialogPrivate;
0025 class KPropertiesDialogPlugin;
0026 
0027 class KJob;
0028 namespace KIO
0029 {
0030 class Job;
0031 }
0032 
0033 /**
0034  * @class KPropertiesDialog kpropertiesdialog.h <KPropertiesDialog>
0035  *
0036  * The main properties dialog class.
0037  * A Properties Dialog is a dialog which displays various information
0038  * about a particular file or URL, or several files or URLs.
0039  * This main class holds various related classes, which are instantiated in
0040  * the form of tab entries in the tabbed dialog that this class provides.
0041  * The various tabs themselves will let the user view, and sometimes change,
0042  * information about the file or URL.
0043  *
0044  * \image html kpropertiesdialog.png "Example of KPropertiesDialog"
0045  *
0046  * The best way to display the properties dialog is to use showDialog().
0047  * Otherwise, you should use (void)new KPropertiesDialog(...)
0048  * It will take care of deleting itself when closed.
0049  *
0050  * If you are looking for more flexibility, see KFileMetaInfo and
0051  * KFileMetaInfoWidget.
0052  *
0053  * This respects the "editfiletype", "run_desktop_files" and "shell_access"
0054  * Kiosk action restrictions (see KAuthorized::authorize()).
0055  */
0056 class KIOWIDGETS_EXPORT KPropertiesDialog : public KPageDialog
0057 {
0058     Q_OBJECT
0059 
0060 public:
0061     /**
0062      * Determine whether there are any property pages available for the
0063      * given file items.
0064      * @param _items the list of items to check.
0065      * @return true if there are any property pages, otherwise false.
0066      */
0067     static bool canDisplay(const KFileItemList &_items);
0068 
0069     /**
0070      * Brings up a Properties dialog, as shown above.
0071      * This is the normal constructor for
0072      * file-manager type applications, where you have a KFileItem instance
0073      * to work with.  Normally you will use this
0074      * method rather than the one below.
0075      *
0076      * @param item file item whose properties should be displayed.
0077      * @param parent is the parent of the dialog widget.
0078      */
0079     explicit KPropertiesDialog(const KFileItem &item, QWidget *parent = nullptr);
0080 
0081     /**
0082      * \overload
0083      *
0084      * You use this constructor for cases where you have a number of items,
0085      * rather than a single item. Be careful which methods you use
0086      * when passing a list of files or URLs, since some of them will only
0087      * work on the first item in a list.
0088      *
0089      * @param _items list of file items whose properties should be displayed.
0090      * @param parent is the parent of the dialog widget.
0091      */
0092     explicit KPropertiesDialog(const KFileItemList &_items, QWidget *parent = nullptr);
0093 
0094     /**
0095      * Brings up a Properties dialog. Convenience constructor for
0096      * non-file-manager applications, where you have a QUrl rather than a
0097      * KFileItem or KFileItemList.
0098      *
0099      * @param url the URL whose properties should be displayed
0100      * @param parent is the parent of the dialog widget.
0101      *
0102      * For local files with a known MIME type, simply create a KFileItem
0103      * and pass it to the other constructor.
0104      */
0105     explicit KPropertiesDialog(const QUrl &url, QWidget *parent = nullptr);
0106 
0107     /**
0108      * Brings up a Properties dialog. Convenience constructor for
0109      * non-file-manager applications, where you have a list of QUrls rather
0110      * than a KFileItemList.
0111      *
0112      * @param urls list of URLs whose properties should be displayed (must
0113      *             contain at least one non-empty URL)
0114      * @param parent is the parent of the dialog widget.
0115      *
0116      * For local files with a known MIME type, simply create a KFileItemList
0117      * and pass it to the other constructor.
0118      *
0119      * @since 5.10
0120      */
0121     explicit KPropertiesDialog(const QList<QUrl> &urls, QWidget *parent = nullptr);
0122 
0123     /**
0124      * Creates a properties dialog for a new .desktop file (whose name
0125      * is not known yet), based on a template. Special constructor for
0126      * "File / New" in file-manager type applications.
0127      *
0128      * @param _tempUrl template used for reading only
0129      * @param _currentDir directory where the file will be written to
0130      * @param _defaultName something to put in the name field,
0131      * like mimetype.desktop
0132      * @param parent is the parent of the dialog widget.
0133      */
0134     KPropertiesDialog(const QUrl &_tempUrl, const QUrl &_currentDir, const QString &_defaultName, QWidget *parent = nullptr);
0135 
0136     /**
0137      * Creates an empty properties dialog (for applications that want use
0138      * a standard dialog, but for things not doable via the plugin-mechanism).
0139      *
0140      * @param title is the string display as the "filename" in the title of the dialog.
0141      * @param parent is the parent of the dialog widget.
0142      */
0143     explicit KPropertiesDialog(const QString &title, QWidget *parent = nullptr);
0144 
0145     /**
0146      * Cleans up the properties dialog and frees any associated resources,
0147      * including the dialog itself. Note that when a properties dialog is
0148      * closed it cleans up and deletes itself.
0149      */
0150     ~KPropertiesDialog() override;
0151 
0152     /**
0153      * Immediately displays a Properties dialog using constructor with
0154      * the same parameters.
0155      * On MS Windows, if @p item points to a local file, native (non modal) property
0156      * dialog is displayed (@p parent and @p modal are ignored in this case).
0157      *
0158      * @return true on successful dialog displaying (can be false on win32).
0159      */
0160     static bool showDialog(const KFileItem &item, QWidget *parent = nullptr, bool modal = true);
0161 
0162     /**
0163      * Immediately displays a Properties dialog using constructor with
0164      * the same parameters.
0165      * On MS Windows, if @p _url points to a local file, native (non modal) property
0166      * dialog is displayed (@p parent and @p modal are ignored in this case).
0167      *
0168      * @return true on successful dialog displaying (can be false on win32).
0169      */
0170     static bool showDialog(const QUrl &_url, QWidget *parent = nullptr, bool modal = true);
0171 
0172     /**
0173      * Immediately displays a Properties dialog using constructor with
0174      * the same parameters.
0175      * On MS Windows, if @p _items has one element and this element points
0176      * to a local file, native (non modal) property dialog is displayed
0177      * (@p parent and @p modal are ignored in this case).
0178      *
0179      * @return true on successful dialog displaying (can be false on win32).
0180      */
0181     static bool showDialog(const KFileItemList &_items, QWidget *parent = nullptr, bool modal = true);
0182 
0183     /**
0184      * Immediately displays a Properties dialog using constructor with
0185      * the same parameters.
0186      *
0187      * On MS Windows, if @p _urls has one element and this element points
0188      * to a local file, native (non modal) property dialog is displayed
0189      * (@p parent and @p modal are ignored in this case).
0190      *
0191      * @param urls list of URLs whose properties should be displayed (must
0192      *             contain at least one non-empty URL)
0193      * @param parent is the parent of the dialog widget.
0194      * @param modal tells the dialog whether it should be modal.
0195      *
0196      * @return true on successful dialog displaying (can be false on win32).
0197      *
0198      * @since 5.10
0199      */
0200     static bool showDialog(const QList<QUrl> &urls, QWidget *parent = nullptr, bool modal = true);
0201 
0202     /**
0203      * Adds a "3rd party" properties plugin to the dialog.  Useful
0204      * for extending the properties mechanism.
0205      *
0206      * To create a new plugin type, inherit from the base class KPropertiesDialogPlugin
0207      * and implement all the methods. If you define a service .desktop file
0208      * for your plugin, you do not need to call insertPlugin().
0209      *
0210      * @param plugin is a pointer to the KPropertiesDialogPlugin. The Properties
0211      *        dialog will do destruction for you. The KPropertiesDialogPlugin \b must
0212      *        have been created with the KPropertiesDialog as its parent.
0213      * @see KPropertiesDialogPlugin
0214      */
0215     void insertPlugin(KPropertiesDialogPlugin *plugin);
0216 
0217 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 0)
0218     /**
0219      * @deprecated since 5.0, use url()
0220      */
0221     KIOWIDGETS_DEPRECATED_VERSION(5, 0, "Use KPropertiesDialog::url()")
0222     QUrl kurl() const
0223     {
0224         return url();
0225     }
0226 #endif
0227 
0228     /**
0229      * The URL of the file that has its properties being displayed.
0230      * This is only valid if the KPropertiesDialog was created/shown
0231      * for one file or URL.
0232      *
0233      * @return the single URL.
0234      */
0235     QUrl url() const;
0236 
0237     /**
0238      * @return the file item for which the dialog is shown
0239      *
0240      * Warning: this method returns the first item of the list.
0241      * This means that you should use this only if you are sure the dialog is used
0242      * for a single item. Otherwise, you probably want items() instead.
0243      */
0244     KFileItem &item();
0245 
0246     /**
0247      * @return the items for which the dialog is shown
0248      */
0249     KFileItemList items() const;
0250 
0251     /**
0252      * If the dialog is being built from a template, this method
0253      * returns the current directory. If no template, it returns QString().
0254      * See the template form of the constructor.
0255      *
0256      * @return the current directory or QString()
0257      */
0258     QUrl currentDir() const;
0259 
0260     /**
0261      * If the dialog is being built from a template, this method
0262      * returns the default name. If no template, it returns QString().
0263      * See the template form of the constructor.
0264      * @return the default name or QString()
0265      */
0266     QString defaultName() const;
0267 
0268     /**
0269      * Updates the item URL (either called by rename or because
0270      * a global apps/mimelnk desktop file is being saved)
0271      * Can only be called if the dialog applies to a single file or URL.
0272      * @param newUrl the new URL
0273      */
0274     void updateUrl(const QUrl &newUrl);
0275 
0276     /**
0277      * Renames the item to the specified name. This can only be called if
0278      * the dialog applies to a single file or URL.
0279      * @param _name new filename, encoded.
0280      * \see FilePropsDialogPlugin::applyChanges
0281      */
0282     void rename(const QString &_name);
0283 
0284     /**
0285      * To abort applying changes.
0286      */
0287     void abortApplying();
0288 
0289     /**
0290      * Shows the page that was previously set by
0291      * setFileSharingPage(), or does nothing if no page
0292      * was set yet.
0293      * \see setFileSharingPage
0294      */
0295     void showFileSharingPage();
0296 
0297     /**
0298      * Sets the file sharing page.
0299      * This page is shown when calling showFileSharingPage().
0300      *
0301      * @param page the page to set
0302      *
0303      * \note This should only be called by KPropertiesDialog plugins.
0304      * \see showFileSharingPage
0305      */
0306     void setFileSharingPage(QWidget *page);
0307 
0308     /**
0309      * Call this to make the filename lineedit readonly, to prevent the user
0310      * from renaming the file.
0311      * \param ro true if the lineedit should be read only
0312      */
0313     void setFileNameReadOnly(bool ro);
0314 
0315     using KPageDialog::buttonBox;
0316 
0317 public Q_SLOTS:
0318     /**
0319      * Called when the user presses 'Ok'.
0320      * @deprecated since 5.25, use accept()
0321      */
0322     KIOWIDGETS_DEPRECATED_VERSION(5, 25, "Use KPropertiesDialog::accept()")
0323     virtual void slotOk();
0324     /**
0325      * Called when the user presses 'Cancel'.
0326      * @deprecated since 5.25, use reject()
0327      */
0328     KIOWIDGETS_DEPRECATED_VERSION(5, 25, "Use KPropertiesDialog::reject()")
0329     virtual void slotCancel();
0330 
0331     /**
0332      * Called when the user presses 'Ok'.
0333      * @since 5.25
0334      */
0335     void accept() override;
0336     /**
0337      * Called when the user presses 'Cancel' or Esc.
0338      * @since 5.25
0339      */
0340     void reject() override;
0341 
0342 Q_SIGNALS:
0343     /**
0344      * This signal is emitted when the Properties Dialog is closed (for
0345      * example, with OK or Cancel buttons)
0346      */
0347     void propertiesClosed();
0348 
0349     /**
0350      * This signal is emitted when the properties changes are applied (for
0351      * example, with the OK button)
0352      */
0353     void applied();
0354 
0355     /**
0356      * This signal is emitted when the properties changes are aborted (for
0357      * example, with the Cancel button)
0358      */
0359 
0360     void canceled();
0361     /**
0362      * Emitted before changes to @p oldUrl are saved as @p newUrl.
0363      * The receiver may change @p newUrl to point to an alternative
0364      * save location.
0365      */
0366     void saveAs(const QUrl &oldUrl, QUrl &newUrl);
0367 
0368 Q_SIGNALS:
0369 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 103)
0370     /**
0371      * @deprecated Since 5.82, not used anymore.
0372      */
0373     KIOWIDGETS_DEPRECATED_VERSION_BELATED(5, 103, 5, 82, "Not used anymore")
0374     void leaveModality();
0375 #endif
0376 
0377 private:
0378     std::unique_ptr<KPropertiesDialogPrivate> d;
0379 
0380     Q_DISABLE_COPY(KPropertiesDialog)
0381 };
0382 
0383 class KPropertiesDialogPluginPrivate;
0384 /**
0385  * A Plugin in the Properties dialog
0386  * This is an abstract class. You must inherit from this class
0387  * to build a new kind of tabbed page for the KPropertiesDialog.
0388  * A plugin in itself is just a library containing code, not a dialog's page.
0389  * It's up to the plugin to insert pages into the parent dialog.
0390  *
0391  * To make a plugin available, ensure it has embedded json metadata (look for
0392  * K_PLUGIN_CLASS_WITH_JSON) and install the plugin in "\<plugins_dir>/kf5/propertiesdialog/".
0393  * (By default KDE uses the same plugins dir as Qt, you can find the @c plugins_dir path on
0394  * your system by running <tt>qtpaths --plugin-dir</tt> or <tt>qmake QT_INSTALL_PLUGINS</tt>
0395  * in terminal).
0396  *
0397  * The metadata can contain the MIME types for which the plugin should be created.
0398  * For instance:
0399  * @verbatim
0400    {
0401        "KPlugin": {
0402            "MimeTypes": ["text/html", "application/x-mymimetype"]
0403        }
0404    }
0405    @endverbatim
0406  * If the MIME types are empty or not specified, the plugin will be created for all MIME types.
0407  *
0408  * You can also include X-KDE-Protocol=file if you want that plugin
0409  * to be loaded only for local files, for instance.
0410  */
0411 class KIOWIDGETS_EXPORT KPropertiesDialogPlugin : public QObject
0412 {
0413     Q_OBJECT
0414 public:
0415     /**
0416      * Constructor
0417      * To insert tabs into the properties dialog, use the add methods provided by
0418      * KPageDialog (the properties dialog is a KPageDialog).
0419      */
0420     KPropertiesDialogPlugin(KPropertiesDialog *_props);
0421     ~KPropertiesDialogPlugin() override;
0422 
0423     /**
0424      * Applies all changes to the file.
0425      * This function is called when the user presses 'Ok'. The last plugin inserted
0426      * is called first.
0427      */
0428     virtual void applyChanges();
0429 
0430 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(4, 1)
0431     /**
0432      * Convenience method for most ::supports methods
0433      * @return true if the file is a local, regular, readable, desktop file
0434      * @deprecated Since 4.1, use KFileItem::isDesktopFile
0435      */
0436     KIOWIDGETS_DEPRECATED_VERSION(4, 1, "Use KFileItem::isDesktopFile()")
0437     static bool isDesktopFile(const KFileItem &_item);
0438 #endif
0439 
0440     void setDirty(bool b);
0441     bool isDirty() const;
0442 
0443 public Q_SLOTS:
0444     void setDirty(); // same as setDirty( true ). TODO KDE5: void setDirty(bool dirty=true);
0445 
0446 Q_SIGNALS:
0447     /**
0448      * Emit this signal when the user changed anything in the plugin's tabs.
0449      * The hosting PropertiesDialog will call applyChanges only if the
0450      * PropsPlugin has emitted this signal or if you have called setDirty() before.
0451      */
0452     void changed();
0453 
0454 protected:
0455     /**
0456      * Pointer to the dialog
0457      */
0458     KPropertiesDialog *properties;
0459 
0460     /**
0461      * Returns the font height.
0462      */
0463     int fontHeight() const;
0464 
0465 private:
0466     std::unique_ptr<KPropertiesDialogPluginPrivate> d;
0467 };
0468 
0469 #endif