KParts

textextension.h
1 /*
2  This file is part of the KDE project
3  SPDX-FileCopyrightText: 2010 David Faure <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.0-or-later
6 */
7 
8 #ifndef KPARTS_TEXTEXTENSION_H
9 #define KPARTS_TEXTEXTENSION_H
10 
11 #include <kparts/kparts_export.h>
12 
13 #include <KFind>
14 #include <QObject>
15 #include <memory>
16 
17 namespace KParts
18 {
19 class ReadOnlyPart;
20 class TextExtensionPrivate;
21 
22 /**
23  * @class TextExtension textextension.h <KParts/TextExtension>
24  *
25  * @short An extension for KParts that allows to retrieve text from the part.
26  *
27  * For instance, the text-to-speech plugin uses this to speak the whole text
28  * from the part or the selected text. The translation plugin uses it for
29  * translating the selected text, and so on.
30  *
31  * @since 4.6
32  */
33 class KPARTS_EXPORT TextExtension : public QObject
34 {
35  Q_OBJECT
36 public:
37  explicit TextExtension(KParts::ReadOnlyPart *parent);
38  ~TextExtension() override;
39 
40  /**
41  * Queries @p obj for a child object which inherits from this
42  * TextExtension class.
43  */
44  static TextExtension *childObject(QObject *obj);
45 
46  enum Format { PlainText, HTML };
47 
48  /**
49  * Returns true if the user selected text in the part.
50  */
51  virtual bool hasSelection() const;
52  /**
53  * Returns the selected text, in the requested format.
54  * If the format is not supported, the part must return an empty string.
55  */
56  virtual QString selectedText(Format format) const;
57  /**
58  * Returns the complete text shown in the part, in the requested format.
59  * If the format is not supported, the part must return an empty string.
60  */
61  virtual QString completeText(Format format) const;
62 
63  /**
64  * Returns the number of pages, for parts who support the concept of pages.
65  * Otherwise returns 0.
66  */
67  virtual int pageCount() const;
68  /**
69  * Returns the current page (between 0 and pageCount()-1),
70  * for parts who support the concept of pages.
71  * Otherwise returns 0.
72  */
73  virtual int currentPage() const;
74  /**
75  * Returns the text in a given page, in the requested format.
76  */
77  virtual QString pageText(Format format) const;
78 
79  /**
80  * Returns true if @p string is found using the given @p options.
81  *
82  * If any text matches @p string, then it will be selected/highlighted.
83  * To find the next matching text, simply call this function again with the
84  * same search text until it returns false.
85  *
86  * To clear a selection, just pass an empty string.
87  *
88  * Note that parts that implement this extension might not support all the
89  * options available in @ref KFind::SearchOptions.
90  */
91  virtual bool findText(const QString &string, KFind::SearchOptions options) const;
92 
93  // for future extensions can be made via slots
94 
95 Q_SIGNALS:
96  /**
97  * This signal is emitted when the selection changes.
98  */
99  void selectionChanged();
100 
101 private:
102  // for future extensions
103  std::unique_ptr<TextExtensionPrivate> const d;
104 };
105 
106 }
107 
108 #endif /* KPARTS_TEXTEXTENSION_H */
An extension for KParts that allows to retrieve text from the part.
Definition: textextension.h:33
Base class for any "viewer" part.
Definition: readonlypart.h:51
The KParts namespace,.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Tue Aug 9 2022 03:51:33 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.