File indexing completed on 2024-07-21 12:11:47

0001 /*
0002     This file is part of the KDE libraries
0003     SPDX-FileCopyrightText: 1999 Waldo Bastian <bastian@kde.org>
0004     SPDX-FileCopyrightText: 2000, 2007 David Faure <faure@kde.org>
0005 
0006     SPDX-License-Identifier: LGPL-2.0-only
0007 */
0008 
0009 #ifndef KDESKTOPFILEACTIONS_H
0010 #define KDESKTOPFILEACTIONS_H
0011 
0012 #include "kiowidgets_export.h"
0013 #include <KServiceAction>
0014 #include <QDebug>
0015 #include <QList>
0016 #include <QUrl>
0017 class KDesktopFile;
0018 class KService;
0019 
0020 /**
0021  * KDesktopFileActions provides a number of methods related to actions in desktop files.
0022  */
0023 namespace KDesktopFileActions
0024 {
0025 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 82)
0026 /**
0027  * Returns a list of services for the given .desktop file that are handled
0028  * by KIO itself. Namely mount/unmount for FSDevice files.
0029  * @return the list of services
0030  *
0031  * @deprecated since 5.82, FSDevice .desktop file template hasn't been installed
0032  * for a long time. And users don't seem to mount devices using that method any more.
0033  */
0034 KIOWIDGETS_EXPORT
0035 KIOWIDGETS_DEPRECATED_VERSION(5, 82, "For lack of usage.")
0036 QList<KServiceAction> builtinServices(const QUrl &url);
0037 #endif
0038 
0039 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 86)
0040 /**
0041  * Returns a list of services defined by the user as possible actions
0042  * on the given .desktop file. May include separators (see KServiceAction::isSeparator)
0043  * which should appear in user-visible representations of those actions,
0044  * such as separators in a menu.
0045  * @param path the path to the desktop file describing the services
0046  * @param bLocalFiles true if those services are to be applied to local files only
0047  * (if false, services that don't have %u or %U in the Exec line won't be taken into account).
0048  * @return the list of user defined actions
0049  * @deprecated Since 5.86, use userDefinedServices(KService, bool, QList<QUrl>) instead
0050  */
0051 KIOWIDGETS_DEPRECATED_VERSION(5, 86, "Use userDefinedServices(KService, bool, QList<QUrl>) instead")
0052 KIOWIDGETS_EXPORT QList<KServiceAction> userDefinedServices(const QString &path, bool bLocalFiles);
0053 #endif
0054 
0055 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 86)
0056 /**
0057  * Overload of userDefinedServices but also allows you to pass a list of urls for this file.
0058  * This allows for the menu to be changed depending on the exact files via
0059  * the X-KDE-GetActionMenu extension.
0060  * @deprecated Since 5.86, use userDefinedServices(KService, bool, QList<QUrl>) instead
0061  */
0062 KIOWIDGETS_DEPRECATED_VERSION(5, 86, "Use userDefinedServices(KService, bool, QList<QUrl>) instead")
0063 KIOWIDGETS_EXPORT QList<KServiceAction>
0064 userDefinedServices(const QString &path, const KDesktopFile &desktopFile, bool bLocalFiles, const QList<QUrl> &file_list = QList<QUrl>());
0065 #endif
0066 
0067 /**
0068  * Returns a list of services defined by the user as possible actions
0069  * on the given .desktop file represented by the KService instance.
0070  * May include separators (see KServiceAction::isSeparator) which should
0071  * appear in user-visible representations of those actions,
0072  * such as separators in a menu.
0073  * @param path the path to the desktop file describing the services
0074  * @param bLocalFiles true if those services are to be applied to local files only
0075  * (if false, services that don't have %u or %U in the Exec line won't be taken into account).
0076  * @param file_list list of urls; this allows for the menu to be changed depending on the exact files via
0077  * the X-KDE-GetActionMenu extension.
0078  *
0079  * @return the list of user defined actions
0080  */
0081 KIOWIDGETS_EXPORT QList<KServiceAction> userDefinedServices(const KService &service, bool bLocalFiles, const QList<QUrl> &file_list = QList<QUrl>());
0082 
0083 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 84)
0084 /**
0085  * Execute @p service on the list of @p urls.
0086  *
0087  * @param urls the list of urls
0088  * @param service the service to execute
0089  *
0090  * @deprecated Since 5.84, use KIO::ApplicationLauncherJob instead; for example:
0091  *
0092  * @code
0093  * KIO::ApplicationLauncherJob *job = new KIO::ApplicationLauncherJob(action);
0094  * job->setUrls(urls);
0095  * job->setUiDelegate(new KDialogJobUiDelegate(KJobUiDelegate::AutoHandlingEnabled, parent));
0096  * job->start();
0097  * @endcode
0098  */
0099 KIOWIDGETS_EXPORT
0100 KIOWIDGETS_DEPRECATED_VERSION(5, 84, "Use KIO::ApplicationLauncherJob instead, see the API docs for a code example.")
0101 void executeService(const QList<QUrl> &urls, const KServiceAction &service);
0102 #endif
0103 
0104 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 71)
0105 /**
0106  * Invokes the default action for the desktop entry. If the desktop
0107  * entry is not local, then only false is returned. Otherwise we
0108  * would create a security problem. Only types Link and Mimetype
0109  * could be followed.
0110  *
0111  * @param _url the url to run
0112  * @param _is_local true if the URL is local, false otherwise
0113  * @return true on success and false on failure.
0114  * @see KRun::runUrl
0115  * @deprecated since 5.71, use OpenUrlJob instead
0116  */
0117 KIOWIDGETS_EXPORT
0118 KIOWIDGETS_DEPRECATED_VERSION(5, 71, "Use KIO::OpenUrlJob instead")
0119 bool run(const QUrl &_url, bool _is_local);
0120 #endif
0121 
0122 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 71)
0123 /**
0124  * Invokes the default action for the desktop entry. If the desktop
0125  * entry is not local, then only false is returned. Otherwise we
0126  * would create a security problem. Only types Link and Mimetype
0127  * could be followed.
0128  *
0129  * Use this function if a startup notification id has already been created.
0130  *
0131  * @param _url the url to run
0132  * @param _is_local true if the URL is local, false otherwise
0133  * @param asn Application startup notification id, if available
0134  * @return true on success and false on failure.
0135  * @see KRun::runUrl
0136  * @since 5.5
0137  * @deprecated since 5.71, use OpenUrlJob instead
0138  */
0139 KIOWIDGETS_EXPORT
0140 KIOWIDGETS_DEPRECATED_VERSION(5, 71, "Use KIO::OpenUrlJob instead")
0141 bool runWithStartup(const QUrl &_url, bool _is_local, const QByteArray &asn);
0142 #endif
0143 }
0144 
0145 #endif