File indexing completed on 2024-04-28 07:45:40
0001 /* 0002 SPDX-FileCopyrightText: 2006 Aaron Seigo <aseigo@kde.org> 0003 SPDX-FileCopyrightText: 2007 Ryan P. Bitanga <ryan.bitanga@gmail.com> 0004 SPDX-FileCopyrightText: 2008 Jordi Polo <mumismo@gmail.com> 0005 SPDX-FileCopyrightText: 2023 Alexander Lohnau <alexander.lohnauŋmx.de> 0006 0007 SPDX-License-Identifier: LGPL-2.0-or-later 0008 */ 0009 0010 #ifndef KRUNNER_RUNNERMANAGER_H 0011 #define KRUNNER_RUNNERMANAGER_H 0012 0013 #include <QList> 0014 #include <QObject> 0015 0016 #include <KPluginMetaData> 0017 0018 #include "abstractrunner.h" 0019 #include "action.h" 0020 #include "krunner_export.h" 0021 #include <memory> 0022 0023 class KConfigGroup; 0024 namespace KRunner 0025 { 0026 class AbstractRunnerTest; 0027 } 0028 0029 namespace KRunner 0030 { 0031 class QueryMatch; 0032 class AbstractRunner; 0033 class RunnerContext; 0034 class RunnerManagerPrivate; 0035 0036 /** 0037 * @class RunnerManager runnermanager.h <KRunner/RunnerManager> 0038 * 0039 * @short The RunnerManager class decides what installed runners are runnable, 0040 * and their ratings. It is the main proxy to the runners. 0041 */ 0042 class KRUNNER_EXPORT RunnerManager : public QObject 0043 { 0044 Q_OBJECT 0045 Q_PROPERTY(QStringList history READ history) 0046 Q_PROPERTY(bool historyEnabled READ historyEnabled WRITE setHistoryEnabled NOTIFY historyEnabledChanged) 0047 0048 public: 0049 /** 0050 * Constructs a RunnerManager with the given parameters 0051 * @param configurationGroup Config group used for reading enabled plugins 0052 * @param stateGroup Config group used for storing history 0053 * @since 6.0 0054 */ 0055 explicit RunnerManager(const KConfigGroup &pluginConfigGroup, KConfigGroup stateGroup, QObject *parent); 0056 0057 /** 0058 * Constructs a RunnerManager using the default locations for state/plugin config 0059 */ 0060 explicit RunnerManager(QObject *parent = nullptr); 0061 ~RunnerManager() override; 0062 0063 /** 0064 * Finds and returns a loaded runner or a nullptr 0065 * @param pluginId the name of the runner plugin 0066 * @return Pointer to the runner 0067 */ 0068 AbstractRunner *runner(const QString &pluginId) const; 0069 0070 /** 0071 * @return the list of all currently loaded runners 0072 */ 0073 QList<AbstractRunner *> runners() const; 0074 0075 /** 0076 * Retrieves the current context 0077 * @return pointer to the current context 0078 */ 0079 RunnerContext *searchContext() const; 0080 0081 /** 0082 * Retrieves all available matches found so far for the previously launched query 0083 * @return List of matches 0084 */ 0085 QList<QueryMatch> matches() const; 0086 0087 /** 0088 * Runs a given match. This also respects the extra handling for the InformationalMatch. 0089 * This also handles the history automatically 0090 * @param match the match to be executed 0091 * @param selectedAction the action returned by @ref QueryMatch::actions that has been selected by the user, nullptr if none 0092 * @return if the RunnerWindow should close 0093 * @since 6.0 0094 */ 0095 bool run(const QueryMatch &match, const KRunner::Action &action = {}); 0096 0097 /** 0098 * @return the current query term set in @ref launchQuery 0099 */ 0100 QString query() const; 0101 0102 /** 0103 * @return History of this runner for the current activity. If the RunnerManager is not history 0104 * aware the global entries will be returned. 0105 * @since 5.78 0106 */ 0107 QStringList history() const; 0108 0109 /** 0110 * Delete the given index from the history. 0111 * @param historyEntry 0112 * @since 5.78 0113 */ 0114 Q_INVOKABLE void removeFromHistory(int index); 0115 0116 /** 0117 * Get the suggested history entry for the typed query. If no entry is found an empty string is returned. 0118 * @param typedQuery 0119 * @return completion for typedQuery 0120 * @since 5.78 0121 */ 0122 Q_INVOKABLE QString getHistorySuggestion(const QString &typedQuery) const; 0123 0124 /** 0125 * If history completion is enabled, the default value is true. 0126 * @since 5.78 0127 */ 0128 bool historyEnabled(); 0129 0130 /** 0131 * Enables/disabled the history feature for the RunnerManager instance. 0132 * The value will not be persisted and is only kept during the object's lifetime. 0133 * 0134 * @since 6.0 0135 */ 0136 void setHistoryEnabled(bool enabled); 0137 0138 /** 0139 * Causes a reload of the current configuration 0140 * This gets called automatically when the config in the KCM is saved 0141 */ 0142 void reloadConfiguration(); 0143 0144 /** 0145 * Sets a whitelist for the plugins that can be loaded by this manager. 0146 * Runners that are disabled through the config will not be loaded. 0147 * 0148 * @param plugins the plugin names of allowed runners 0149 */ 0150 void setAllowedRunners(const QStringList &runners); 0151 0152 /** 0153 * Attempts to add the AbstractRunner plugin represented 0154 * by the plugin info passed in. Usually one can simply let 0155 * the configuration of plugins handle loading Runner plugins, 0156 * but in cases where specific runners should be loaded this 0157 * allows for that to take place 0158 * @note Consider using @ref setAllowedRunners in case you want to only allow specific runners 0159 * 0160 * @param pluginMetaData the metaData to use to load the plugin 0161 * @return the loaded runner or nullptr 0162 */ 0163 AbstractRunner *loadRunner(const KPluginMetaData &pluginMetaData); 0164 0165 /** 0166 * @return mime data of the specified match 0167 */ 0168 QMimeData *mimeDataForMatch(const QueryMatch &match) const; 0169 0170 /** 0171 * @return metadata list of all known Runner plugins 0172 * @since 5.72 0173 */ 0174 static QList<KPluginMetaData> runnerMetaDataList(); 0175 0176 public Q_SLOTS: 0177 /** 0178 * Call this method when the runners should be prepared for a query session. 0179 * Call matchSessionComplete when the query session is finished for the time 0180 * being. 0181 * @see matchSessionComplete 0182 */ 0183 void setupMatchSession(); 0184 0185 /** 0186 * Call this method when the query session is finished for the time 0187 * being. 0188 * @see prepareForMatchSession 0189 */ 0190 void matchSessionComplete(); 0191 0192 /** 0193 * Launch a query, this will create threads and return immediately. 0194 * When the information will be available can be known using the 0195 * matchesChanged signal. 0196 * 0197 * @param term the term we want to find matches for 0198 * @param runnerId optional, if only one specific runner is to be used; 0199 * providing an id will put the manager into single runner mode 0200 */ 0201 void launchQuery(const QString &term, const QString &runnerId = QString()); 0202 0203 /** 0204 * Reset the current data and stops the query 0205 */ 0206 void reset(); 0207 0208 /** 0209 * Set the environment identifier for recording history and launch counts 0210 * @internal 0211 * @since 6.0 0212 */ 0213 Q_INVOKABLE void setHistoryEnvironmentIdentifier(const QString &identifier); 0214 0215 Q_SIGNALS: 0216 /** 0217 * Emitted each time a new match is added to the list 0218 */ 0219 void matchesChanged(const QList<KRunner::QueryMatch> &matches); 0220 0221 /** 0222 * Emitted when the launchQuery finish 0223 */ 0224 void queryFinished(); 0225 0226 /** 0227 * Put the given search term in the KRunner search field 0228 * @param term The term that should be displayed 0229 * @param cursorPosition Where the cursor should be positioned 0230 * @since 6.0 0231 */ 0232 void requestUpdateQueryString(const QString &term, int cursorPosition); 0233 0234 /** 0235 * @see @p historyEnabled 0236 * @since 5.78 0237 */ 0238 void historyEnabledChanged(); 0239 0240 private: 0241 // exported for dbusrunnertest 0242 KPluginMetaData convertDBusRunnerToJson(const QString &filename) const; 0243 KRUNNER_NO_EXPORT Q_INVOKABLE void onMatchesChanged(); 0244 0245 std::unique_ptr<RunnerManagerPrivate> d; 0246 0247 friend class RunnerManagerPrivate; 0248 friend AbstractRunnerTest; 0249 friend AbstractRunner; 0250 }; 0251 0252 } 0253 #endif