1 | /* This file is part of the KDE project |
2 | Copyright (C) 2010 David Faure <faure@kde.org> |
3 | |
4 | This library is free software; you can redistribute it and/or |
5 | modify it under the terms of the GNU Library General Public |
6 | License as published by the Free Software Foundation; either |
7 | version 2 of the License, or (at your option) any later version. |
8 | |
9 | This library is distributed in the hope that it will be useful, |
10 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
12 | Library General Public License for more details. |
13 | |
14 | You should have received a copy of the GNU Library General Public License |
15 | along with this library; see the file COPYING.LIB. If not, write to |
16 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
17 | Boston, MA 02110-1301, USA. |
18 | */ |
19 | |
20 | #ifndef KPARTS_TEXTEXTENSION_H |
21 | #define KPARTS_TEXTEXTENSION_H |
22 | |
23 | #include <QtCore/QObject> |
24 | #include <kparts/kparts_export.h> |
25 | #include <kfind.h> |
26 | |
27 | namespace KParts |
28 | { |
29 | |
30 | class ReadOnlyPart; |
31 | class TextExtensionPrivate; |
32 | |
33 | /** |
34 | * @short an extension for KParts that allows to retrieve text from the part. |
35 | * |
36 | * For instance, the text-to-speech plugin uses this to speak the whole text |
37 | * from the part or the selected text. The translation plugin uses it for |
38 | * translating the selected text, and so on. |
39 | * |
40 | * @since 4.6 |
41 | */ |
42 | class KPARTS_EXPORT TextExtension : public QObject |
43 | { |
44 | Q_OBJECT |
45 | public: |
46 | TextExtension(KParts::ReadOnlyPart* parent); |
47 | ~TextExtension(); |
48 | |
49 | /** |
50 | * Queries @p obj for a child object which inherits from this |
51 | * TextExtension class. |
52 | */ |
53 | static TextExtension *childObject( QObject *obj ); |
54 | |
55 | enum Format { PlainText, HTML }; |
56 | |
57 | /** |
58 | * Returns true if the user selected text in the part. |
59 | */ |
60 | virtual bool hasSelection() const; |
61 | /** |
62 | * Returns the selected text, in the requested format. |
63 | * If the format is not supported, the part must return an empty string. |
64 | */ |
65 | virtual QString selectedText(Format format) const; |
66 | /** |
67 | * Returns the complete text shown in the part, in the requested format. |
68 | * If the format is not supported, the part must return an empty string. |
69 | */ |
70 | virtual QString completeText(Format format) const; |
71 | |
72 | |
73 | /** |
74 | * Returns the number of pages, for parts who support the concept of pages. |
75 | * Otherwise returns 0. |
76 | */ |
77 | virtual int pageCount() const; |
78 | /** |
79 | * Returns the current page (between 0 and pageCount()-1), |
80 | * for parts who support the concept of pages. |
81 | * Otherwise returns 0. |
82 | */ |
83 | virtual int currentPage() const; |
84 | /** |
85 | * Returns the text in a given page, in the requested format. |
86 | */ |
87 | virtual QString pageText(Format format) const; |
88 | |
89 | /** |
90 | * Returns true if @p string is found using the given @p options. |
91 | * |
92 | * If any text matches @p string, then it will be selected/highlighted. |
93 | * To find the next matching text, simply call this function again with the |
94 | * same search text until it returns false. |
95 | * |
96 | * To clear a selection, just pass an empty string. |
97 | * |
98 | * Note that parts that implement this extension might not support all the |
99 | * options available in @ref KFind::SearchOptions. |
100 | */ |
101 | virtual bool findText(const QString& string, KFind::SearchOptions options) const; |
102 | |
103 | // for future extensions can be made via slots |
104 | |
105 | Q_SIGNALS: |
106 | /** |
107 | * This signal is emitted when the selection changes. |
108 | */ |
109 | void selectionChanged(); |
110 | |
111 | private: |
112 | // for future extensions |
113 | TextExtensionPrivate* const d; |
114 | }; |
115 | |
116 | } |
117 | |
118 | #endif /* KPARTS_TEXTEXTENSION_H */ |
119 | |