File indexing completed on 2022-11-29 15:04:28

0001 /*
0002     SPDX-FileCopyrightText: 2016 Eike Hein <hein.org>
0003     SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
0004 */
0005 
0006 #ifndef TASKTOOLS_H
0007 #define TASKTOOLS_H
0008 
0009 #include <QIcon>
0010 #include <QModelIndex>
0011 #include <QUrl>
0012 
0013 #include <KService>
0014 #include <KSharedConfig>
0015 
0016 namespace Latte
0017 {
0018 namespace WindowSystem
0019 {
0020 
0021 struct AppData
0022 {
0023     QString id; // Application id (*.desktop sans extension).
0024     QString name; // Application name.
0025     QString genericName; // Generic application name.
0026     QIcon icon;
0027     QUrl url;
0028     bool skipTaskbar = false;
0029 };
0030 
0031 enum UrlComparisonMode {
0032      Strict = 0,
0033      IgnoreQueryItems
0034 };
0035 
0036 /**
0037  * Fills in and returns an AppData struct based on the given URL.
0038  *
0039  * If the URL contains iconData in its query string, it is decoded and
0040  * set as AppData.icon, taking precedence over normal icon discovery.
0041  *
0042  * If the URL is using the preferred:// scheme, the URL it resolves to
0043  * is set as AppData.url.
0044  *
0045  * The supplied fallback icon is set as AppData.icon if no other icon
0046  * could be found.
0047  *
0048  * @see defaultApplication
0049  * @param url A URL to a .desktop file or executable, or a preferred:// URL.
0050  * @param fallbackIcon An icon to use when none could be read from the URL or
0051  * otherwise found.
0052  * @returns @c AppData filled in based on the given URL.
0053  */
0054 AppData appDataFromUrl(const QUrl &url, const QIcon &fallbackIcon = QIcon());
0055 
0056 /**
0057  * Takes several bits of window metadata as input and tries to find
0058  * the .desktop file for the application owning this window, or,
0059  * failing that, the path to its executable.
0060  *
0061  * The source for the metadata is generally the window's appId on
0062  * Wayland, or the window class part of the WM_CLASS window property
0063  * on X Windows.
0064  *
0065  * TODO: The supplied config object can contain various mapping and
0066  * mangling rules that affect the behavior of this function, allowing
0067  * to map bits of metadata to different values and other things. This
0068  * config file format still needs to be documented fully; in the
0069  * meantime the bundled default rules in taskmanagerrulesrc (the
0070  * config file opened by various models in this library) can be used
0071  * for reference.
0072  *
0073  * @param appId A string uniquely identifying the application owning
0074  * the window, ideally matching a .desktop file name.
0075  * @param pid The process id for the process owning the window.
0076  * @param config A KConfig object parameterizing the matching
0077  * behavior.
0078  * @param xWindowsWMClassName The instance name part of X Windows'
0079  * WM_CLASS window property.
0080  * @returns A .desktop file or executable path for the application
0081  * owning the window.
0082  */
0083 QUrl windowUrlFromMetadata(const QString &appId, quint32 pid = 0,
0084     KSharedConfig::Ptr config = KSharedConfig::Ptr(), const QString &xWindowsWMClassName = QString());
0085 
0086 /**
0087  * Returns a list of (usually application) KService instances for the
0088  * given process id, by examining the process and querying the service
0089  * database for process metadata.
0090  *
0091  * @param pid A process id.
0092  * @param rulesConfig A KConfig object parameterizing the matching
0093  * behavior.
0094  * @returns A list of KService instances.
0095  */
0096 KService::List servicesFromPid(quint32 pid,
0097     KSharedConfig::Ptr rulesConfig = KSharedConfig::Ptr());
0098 
0099 /**
0100  * Returns a list of (usually application) KService instances for the
0101  * given process command line and process name, by mangling the command
0102  * line in various ways and checking the data against the Exec keys in
0103  * the service database. Mangling is done e.g. to check for executable
0104  * names with and without paths leading to them and to ignore arguments.
0105  * if needed.
0106  *
0107  * The [Settings]TryIgnoreRuntimes key in the supplied config object can
0108  * hold a comma-separated list of runtime executables that this code will
0109  * try to ignore in the process command line. This is useful in cases where
0110  * the command line has the contents of a .desktop Exec key prefixed with
0111  * a runtime executable. The code tries to strip the path to the runtime
0112  * executable if needed.
0113  *
0114  * @param cmdLine A process command line.
0115  * @param processName The process name.
0116  * @param rulesConfig A KConfig object parameterizing the matching
0117  * behavior.
0118  * @returns A list of KService instances.
0119  */
0120 KService::List servicesFromCmdLine(const QString &cmdLine, const QString &processName,
0121     KSharedConfig::Ptr rulesConfig = KSharedConfig::Ptr());
0122 
0123 /**
0124  * Returns an application id for an URL using the preferred:// scheme.
0125  *
0126  * Recognized values for the host component of the URL are:
0127  * - "browser"
0128  * - "mailer"
0129  * - "terminal"
0130  * - "windowmanager"
0131  *
0132  * If the host component matches none of the above, an attempt is made
0133  * to match to application links stored in kcm_componentchooser/.
0134  *
0135  * @param url A URL using the preferred:// scheme.
0136  * @returns an application id for the given URL.
0137  **/
0138 QString defaultApplication(const QUrl &url);
0139 
0140 /**
0141  * Convenience function to compare two launcher URLs either strictly
0142  * or ignoring their query strings.
0143  *
0144  * @see LauncherTasksModel
0145  * @param a The first launcher URL.
0146  * @param b The second launcher URL.
0147  * @param mode The comparison mode. Either Strict or IgnoreQueryItems.
0148  * @returns @c true if the URLs match.
0149  **/
0150 //bool launcherUrlsMatch(const QUrl &a, const QUrl &b, UrlComparisonMode mode = Strict);
0151 
0152 /**
0153  * Determines whether tasks model entries belong to the same app.
0154  *
0155  * @param a The first model index.
0156  * @param b The second model index.
0157  * @returns @c true if the model entries belong to the same app.
0158  **/
0159 //bool appsMatch(const QModelIndex &a, const QModelIndex &b);
0160 
0161 /**
0162  * Given global coordinates, returns the geometry of the screen they are
0163  * on, or the geometry of the screen they are closest to.
0164  *
0165  * @param pos Coordinates in global space.
0166  * @return The geometry of the screen containing pos or closest to pos.
0167  */
0168 //QRect screenGeometry(const QPoint &pos);
0169 
0170 /**
0171  * Attempts to run the application described by the AppData struct that
0172  * is passed in, optionally also handing the application a list of URLs
0173  * to open.
0174  *
0175  * @param appData An application data struct.
0176  * @param urls A list of URLs for the application to open.
0177  */
0178 //void runApp(const AppData &appData,
0179 //    const QList<QUrl> &urls = QList<QUrl>());
0180 }
0181 }
0182 #endif
0183