Changeset View
Changeset View
Standalone View
Standalone View
src/include/ktexteditor/editor.h
Show All 35 Lines | |||||
36 | * are internal and subject to change. We mean it! | 36 | * are internal and subject to change. We mean it! | ||
37 | */ | 37 | */ | ||
38 | namespace KTextEditor | 38 | namespace KTextEditor | ||
39 | { | 39 | { | ||
40 | 40 | | |||
41 | class Application; | 41 | class Application; | ||
42 | class Command; | 42 | class Command; | ||
43 | class Document; | 43 | class Document; | ||
44 | class View; | ||||
44 | class EditorPrivate; | 45 | class EditorPrivate; | ||
45 | class ConfigPage; | 46 | class ConfigPage; | ||
46 | 47 | | |||
48 | | ||||
49 | /** | ||||
50 | * Enum that defines whether replaced variables in expandVariable() and | ||||
51 | * Editor::expandText() are quoted in case the replacement text contains | ||||
52 | * spaces. | ||||
53 | * | ||||
54 | * QuotationMode::ShellQuoting is typically used when passing the replaced | ||||
55 | * text as arguments to a child process. | ||||
56 | * | ||||
57 | * @since 5.57 | ||||
58 | */ | ||||
59 | enum class QuotationMode | ||||
60 | { | ||||
61 | /** | ||||
62 | * Never quote. | ||||
63 | */ | ||||
64 | NoQuoting, | ||||
65 | /** | ||||
66 | * Quote when the replacement text contains spaces. Shell quoting | ||||
67 | * is typically used when the expanded text is passed to the shell. | ||||
68 | */ | ||||
69 | ShellQuoting | ||||
70 | }; | ||||
71 | | ||||
47 | /** | 72 | /** | ||
48 | * \brief Accessor interface for the KTextEditor framework. | 73 | * \brief Accessor interface for the KTextEditor framework. | ||
49 | * | 74 | * | ||
50 | * Topics: | 75 | * Topics: | ||
51 | * - \ref editor_intro | 76 | * - \ref editor_intro | ||
52 | * - \ref editor_config | 77 | * - \ref editor_config | ||
53 | * - \ref editor_commands | 78 | * - \ref editor_commands | ||
54 | * | 79 | * | ||
▲ Show 20 Lines • Show All 186 Lines • ▼ Show 20 Line(s) | 250 | public: | |||
241 | 266 | | |||
242 | /** | 267 | /** | ||
243 | * Get a list of available command line strings. | 268 | * Get a list of available command line strings. | ||
244 | * \return command line strings | 269 | * \return command line strings | ||
245 | * \see commands() | 270 | * \see commands() | ||
246 | */ | 271 | */ | ||
247 | virtual QStringList commandList() const = 0; | 272 | virtual QStringList commandList() const = 0; | ||
248 | 273 | | |||
274 | public: | ||||
275 | /** | ||||
276 | * Function that is called to expand a variable in @p text. | ||||
277 | */ | ||||
278 | using ExpandFunction = QString (*)(const QStringView& text, KTextEditor::View* view); | ||||
279 | | ||||
280 | /** | ||||
281 | * Registers a variable called @p name for exact matches. | ||||
282 | * For instance, a variable called "CurrentDocument:Path" could be | ||||
283 | * registered which then expands to the path the current document. | ||||
284 | * | ||||
285 | * @return true on success, false if the variable could not be registered, | ||||
286 | * e.g. because it already was registered previously. | ||||
287 | * | ||||
288 | * @since 5.57 | ||||
289 | */ | ||||
290 | bool registerVariableMatch(const QString& name, const QString& description, ExpandFunction expansionFunc); | ||||
291 | | ||||
292 | /** | ||||
293 | * Registers a variable for arbitrary text that matches the specified | ||||
294 | * prefix. For instance, a variable called "ENV:" could be registered | ||||
295 | * which then expands arbitrary environment variables, e.g. ENV:HOME | ||||
296 | * would expand to the user's home directory. | ||||
297 | * | ||||
298 | * @note A colon ':' is used as separator for the prefix and the text | ||||
299 | * after the colon that should be evaluated. | ||||
300 | * | ||||
301 | * @return true on success, false if a prefix could not be registered, | ||||
302 | * e.g. because it already was registered previously. | ||||
303 | * | ||||
304 | * @since 5.57 | ||||
305 | */ | ||||
306 | bool registerVariablePrefix(const QString& prefix, const QString& description, ExpandFunction expansionFunc); | ||||
307 | | ||||
308 | /** | ||||
309 | * Unregisters a variable that was previously registered with | ||||
310 | * registerVariableMatch(). | ||||
311 | * | ||||
312 | * @return true if the variable was successfully unregistered, and | ||||
313 | * false if the variable did not exist. | ||||
314 | * | ||||
315 | * @since 5.57 | ||||
316 | */ | ||||
317 | bool unregisterVariableMatch(const QString& variable); | ||||
318 | | ||||
319 | /** | ||||
320 | * Unregisters a prefix of variable that was previously registered with | ||||
321 | * registerVariableMatch(). | ||||
322 | * | ||||
323 | * @return true if the variable was successfully unregistered, and | ||||
324 | * false if the variable did not exist. | ||||
325 | * | ||||
326 | * @since 5.57 | ||||
327 | */ | ||||
328 | bool unregisterVariablePrefix(const QString& variable); | ||||
329 | | ||||
330 | /** | ||||
331 | * Expands a single @p variable, writing the expanded value to @p output. | ||||
332 | * The expanded text in @p output is never quoted. | ||||
333 | * | ||||
334 | * @return true on success, otherwise false. | ||||
335 | * | ||||
336 | * @since 5.57 | ||||
337 | */ | ||||
338 | bool expandVariable(const QString& variable, KTextEditor::View* view, QString& output) const; | ||||
339 | | ||||
340 | /** | ||||
341 | * Expands arbitrary @p text that may contain arbitrary many variables. | ||||
342 | * On success, the expanded text is written to @p output. Depending on | ||||
343 | * the @p quotationMode, the @p output is either not quoted at all | ||||
344 | * (QuotationMode::NoQuoting), or quoted with shell quoting (QuotationMode::ShellQuoting) | ||||
345 | * | ||||
346 | * @return true on success, otherwise false. | ||||
347 | * | ||||
348 | * @since 5.57 | ||||
349 | */ | ||||
350 | bool expandText(const QString& text, KTextEditor::View* view, QString& output, QuotationMode quotationMode = QuotationMode::NoQuoting) const; | ||||
351 | | ||||
249 | private: | 352 | private: | ||
250 | /** | 353 | /** | ||
251 | * private d-pointer, pointing to the internal implementation | 354 | * private d-pointer, pointing to the internal implementation | ||
252 | */ | 355 | */ | ||
253 | EditorPrivate *const d; | 356 | EditorPrivate *const d; | ||
254 | }; | 357 | }; | ||
255 | 358 | | |||
256 | } | 359 | } | ||
257 | 360 | | |||
258 | #endif | 361 | #endif |