File indexing completed on 2024-07-14 03:54:28

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 
0026 /**
0027  * @class KPropertiesDialog kpropertiesdialog.h <KPropertiesDialog>
0028  *
0029  * The main properties dialog class.
0030  * A Properties Dialog is a dialog which displays various information
0031  * about a particular file or URL, or several files or URLs.
0032  * This main class holds various related classes, which are instantiated in
0033  * the form of tab entries in the tabbed dialog that this class provides.
0034  * The various tabs themselves will let the user view, and sometimes change,
0035  * information about the file or URL.
0036  *
0037  * \image html kpropertiesdialog.png "Example of KPropertiesDialog"
0038  *
0039  * The best way to display the properties dialog is to use showDialog().
0040  * Otherwise, you should use (void)new KPropertiesDialog(...)
0041  * It will take care of deleting itself when closed.
0042  *
0043  * If you are looking for more flexibility, see KFileMetaInfo and
0044  * KFileMetaInfoWidget.
0045  *
0046  * This respects the "editfiletype", "run_desktop_files" and "shell_access"
0047  * Kiosk action restrictions (see KAuthorized::authorize()).
0048  */
0049 class KIOWIDGETS_EXPORT KPropertiesDialog : public KPageDialog
0050 {
0051     Q_OBJECT
0052 
0053 public:
0054     /**
0055      * Determine whether there are any property pages available for the
0056      * given file items.
0057      * @param _items the list of items to check.
0058      * @return true if there are any property pages, otherwise false.
0059      */
0060     static bool canDisplay(const KFileItemList &_items);
0061 
0062     /**
0063      * Brings up a Properties dialog, as shown above.
0064      * This is the normal constructor for
0065      * file-manager type applications, where you have a KFileItem instance
0066      * to work with.  Normally you will use this
0067      * method rather than the one below.
0068      *
0069      * @param item file item whose properties should be displayed.
0070      * @param parent is the parent of the dialog widget.
0071      */
0072     explicit KPropertiesDialog(const KFileItem &item, QWidget *parent = nullptr);
0073 
0074     /**
0075      * \overload
0076      *
0077      * You use this constructor for cases where you have a number of items,
0078      * rather than a single item. Be careful which methods you use
0079      * when passing a list of files or URLs, since some of them will only
0080      * work on the first item in a list.
0081      *
0082      * @param _items list of file items whose properties should be displayed.
0083      * @param parent is the parent of the dialog widget.
0084      */
0085     explicit KPropertiesDialog(const KFileItemList &_items, QWidget *parent = nullptr);
0086 
0087     /**
0088      * Brings up a Properties dialog. Convenience constructor for
0089      * non-file-manager applications, where you have a QUrl rather than a
0090      * KFileItem or KFileItemList.
0091      *
0092      * @param url the URL whose properties should be displayed
0093      * @param parent is the parent of the dialog widget.
0094      *
0095      * For local files with a known MIME type, simply create a KFileItem
0096      * and pass it to the other constructor.
0097      */
0098     explicit KPropertiesDialog(const QUrl &url, QWidget *parent = nullptr);
0099 
0100     /**
0101      * Brings up a Properties dialog. Convenience constructor for
0102      * non-file-manager applications, where you have a list of QUrls rather
0103      * than a KFileItemList.
0104      *
0105      * @param urls list of URLs whose properties should be displayed (must
0106      *             contain at least one non-empty URL)
0107      * @param parent is the parent of the dialog widget.
0108      *
0109      * For local files with a known MIME type, simply create a KFileItemList
0110      * and pass it to the other constructor.
0111      *
0112      * @since 5.10
0113      */
0114     explicit KPropertiesDialog(const QList<QUrl> &urls, QWidget *parent = nullptr);
0115 
0116     /**
0117      * Creates a properties dialog for a new .desktop file (whose name
0118      * is not known yet), based on a template. Special constructor for
0119      * "File / New" in file-manager type applications.
0120      *
0121      * @param _tempUrl template used for reading only
0122      * @param _currentDir directory where the file will be written to
0123      * @param _defaultName something to put in the name field,
0124      * like mimetype.desktop
0125      * @param parent is the parent of the dialog widget.
0126      */
0127     KPropertiesDialog(const QUrl &_tempUrl, const QUrl &_currentDir, const QString &_defaultName, QWidget *parent = nullptr);
0128 
0129     /**
0130      * Creates an empty properties dialog (for applications that want use
0131      * a standard dialog, but for things not doable via the plugin-mechanism).
0132      *
0133      * @param title is the string display as the "filename" in the title of the dialog.
0134      * @param parent is the parent of the dialog widget.
0135      */
0136     explicit KPropertiesDialog(const QString &title, QWidget *parent = nullptr);
0137 
0138     /**
0139      * Cleans up the properties dialog and frees any associated resources,
0140      * including the dialog itself. Note that when a properties dialog is
0141      * closed it cleans up and deletes itself.
0142      */
0143     ~KPropertiesDialog() override;
0144 
0145     /**
0146      * Immediately displays a Properties dialog using constructor with
0147      * the same parameters.
0148      * On MS Windows, if @p item points to a local file, native (non modal) property
0149      * dialog is displayed (@p parent and @p modal are ignored in this case).
0150      *
0151      * @return true on successful dialog displaying (can be false on win32).
0152      */
0153     static bool showDialog(const KFileItem &item, QWidget *parent = nullptr, bool modal = true);
0154 
0155     /**
0156      * Immediately displays a Properties dialog using constructor with
0157      * the same parameters.
0158      * On MS Windows, if @p _url points to a local file, native (non modal) property
0159      * dialog is displayed (@p parent and @p modal are ignored in this case).
0160      *
0161      * @return true on successful dialog displaying (can be false on win32).
0162      */
0163     static bool showDialog(const QUrl &_url, QWidget *parent = nullptr, bool modal = true);
0164 
0165     /**
0166      * Immediately displays a Properties dialog using constructor with
0167      * the same parameters.
0168      * On MS Windows, if @p _items has one element and this element points
0169      * to a local file, native (non modal) property dialog is displayed
0170      * (@p parent and @p modal are ignored in this case).
0171      *
0172      * @return true on successful dialog displaying (can be false on win32).
0173      */
0174     static bool showDialog(const KFileItemList &_items, QWidget *parent = nullptr, bool modal = true);
0175 
0176     /**
0177      * Immediately displays a Properties dialog using constructor with
0178      * the same parameters.
0179      *
0180      * On MS Windows, if @p _urls has one element and this element points
0181      * to a local file, native (non modal) property dialog is displayed
0182      * (@p parent and @p modal are ignored in this case).
0183      *
0184      * @param urls list of URLs whose properties should be displayed (must
0185      *             contain at least one non-empty URL)
0186      * @param parent is the parent of the dialog widget.
0187      * @param modal tells the dialog whether it should be modal.
0188      *
0189      * @return true on successful dialog displaying (can be false on win32).
0190      *
0191      * @since 5.10
0192      */
0193     static bool showDialog(const QList<QUrl> &urls, QWidget *parent = nullptr, bool modal = true);
0194 
0195     /**
0196      * The URL of the file that has its properties being displayed.
0197      * This is only valid if the KPropertiesDialog was created/shown
0198      * for one file or URL.
0199      *
0200      * @return the single URL.
0201      */
0202     QUrl url() const;
0203 
0204     /**
0205      * @return the file item for which the dialog is shown
0206      *
0207      * Warning: this method returns the first item of the list.
0208      * This means that you should use this only if you are sure the dialog is used
0209      * for a single item. Otherwise, you probably want items() instead.
0210      */
0211     KFileItem &item();
0212 
0213     /**
0214      * @return the items for which the dialog is shown
0215      */
0216     KFileItemList items() const;
0217 
0218     /**
0219      * If the dialog is being built from a template, this method
0220      * returns the current directory. If no template, it returns QString().
0221      * See the template form of the constructor.
0222      *
0223      * @return the current directory or QString()
0224      */
0225     QUrl currentDir() const;
0226 
0227     /**
0228      * If the dialog is being built from a template, this method
0229      * returns the default name. If no template, it returns QString().
0230      * See the template form of the constructor.
0231      * @return the default name or QString()
0232      */
0233     QString defaultName() const;
0234 
0235     /**
0236      * Updates the item URL (either called by rename or because
0237      * a global apps/mimelnk desktop file is being saved)
0238      * Can only be called if the dialog applies to a single file or URL.
0239      * @param newUrl the new URL
0240      */
0241     void updateUrl(const QUrl &newUrl);
0242 
0243     /**
0244      * Renames the item to the specified name. This can only be called if
0245      * the dialog applies to a single file or URL.
0246      * @param _name new filename, encoded.
0247      * \see FilePropsDialogPlugin::applyChanges
0248      */
0249     void rename(const QString &_name);
0250 
0251     /**
0252      * To abort applying changes.
0253      */
0254     void abortApplying();
0255 
0256     /**
0257      * Shows the page that was previously set by
0258      * setFileSharingPage(), or does nothing if no page
0259      * was set yet.
0260      * \see setFileSharingPage
0261      */
0262     void showFileSharingPage();
0263 
0264     /**
0265      * Sets the file sharing page.
0266      * This page is shown when calling showFileSharingPage().
0267      *
0268      * @param page the page to set
0269      *
0270      * \note This should only be called by KPropertiesDialog plugins.
0271      * \see showFileSharingPage
0272      */
0273     void setFileSharingPage(QWidget *page);
0274 
0275     /**
0276      * Call this to make the filename lineedit readonly, to prevent the user
0277      * from renaming the file.
0278      * \param ro true if the lineedit should be read only
0279      */
0280     void setFileNameReadOnly(bool ro);
0281 
0282     using KPageDialog::buttonBox;
0283 
0284 public Q_SLOTS:
0285     /**
0286      * Called when the user presses 'Ok'.
0287      * @since 5.25
0288      */
0289     void accept() override;
0290     /**
0291      * Called when the user presses 'Cancel' or Esc.
0292      * @since 5.25
0293      */
0294     void reject() override;
0295 
0296 Q_SIGNALS:
0297     /**
0298      * This signal is emitted when the Properties Dialog is closed (for
0299      * example, with OK or Cancel buttons)
0300      */
0301     void propertiesClosed();
0302 
0303     /**
0304      * This signal is emitted when the properties changes are applied (for
0305      * example, with the OK button)
0306      */
0307     void applied();
0308 
0309     /**
0310      * This signal is emitted when the properties changes are aborted (for
0311      * example, with the Cancel button)
0312      */
0313     void canceled();
0314 
0315     /**
0316      * Emitted before changes to @p oldUrl are saved as @p newUrl.
0317      * The receiver may change @p newUrl to point to an alternative
0318      * save location.
0319      */
0320     void saveAs(const QUrl &oldUrl, QUrl &newUrl);
0321 
0322 private:
0323     std::unique_ptr<KPropertiesDialogPrivate> d;
0324 
0325     Q_DISABLE_COPY(KPropertiesDialog)
0326 };
0327 
0328 #endif