File indexing completed on 2024-04-28 04:58:12
0001 /* 0002 This file is part of the KDE project 0003 SPDX-FileCopyrightText: 2010 David Faure <faure@kde.org> 0004 0005 SPDX-License-Identifier: LGPL-2.0-or-later 0006 */ 0007 0008 #ifndef TEXTEXTENSION_H 0009 #define TEXTEXTENSION_H 0010 0011 #include "libkonq_export.h" 0012 0013 #include <KFind> 0014 #include <QObject> 0015 #include <memory> 0016 0017 namespace KParts { 0018 class ReadOnlyPart; 0019 } 0020 class TextExtensionPrivate; 0021 0022 /** 0023 * @class TextExtension textextension.h 0024 * 0025 * @short An extension for KParts that allows to retrieve text from the part. 0026 * 0027 * For instance, the text-to-speech plugin uses this to speak the whole text 0028 * from the part or the selected text. The translation plugin uses it for 0029 * translating the selected text, and so on. 0030 * 0031 * @since 4.6 0032 */ 0033 class LIBKONQ_EXPORT TextExtension : public QObject 0034 { 0035 Q_OBJECT 0036 public: 0037 explicit TextExtension(KParts::ReadOnlyPart *parent); 0038 ~TextExtension() override; 0039 0040 /** 0041 * Queries @p obj for a child object which inherits from this 0042 * TextExtension class. 0043 */ 0044 static TextExtension *childObject(QObject *obj); 0045 0046 enum Format { PlainText, HTML }; 0047 0048 /** 0049 * Returns true if the user selected text in the part. 0050 */ 0051 virtual bool hasSelection() const; 0052 /** 0053 * Returns the selected text, in the requested format. 0054 * If the format is not supported, the part must return an empty string. 0055 */ 0056 virtual QString selectedText(Format format) const; 0057 /** 0058 * Returns the complete text shown in the part, in the requested format. 0059 * If the format is not supported, the part must return an empty string. 0060 */ 0061 virtual QString completeText(Format format) const; 0062 0063 /** 0064 * Returns the number of pages, for parts who support the concept of pages. 0065 * Otherwise returns 0. 0066 */ 0067 virtual int pageCount() const; 0068 /** 0069 * Returns the current page (between 0 and pageCount()-1), 0070 * for parts who support the concept of pages. 0071 * Otherwise returns 0. 0072 */ 0073 virtual int currentPage() const; 0074 /** 0075 * Returns the text in a given page, in the requested format. 0076 */ 0077 virtual QString pageText(Format format) const; 0078 0079 /** 0080 * Returns true if @p string is found using the given @p options. 0081 * 0082 * If any text matches @p string, then it will be selected/highlighted. 0083 * To find the next matching text, simply call this function again with the 0084 * same search text until it returns false. 0085 * 0086 * To clear a selection, just pass an empty string. 0087 * 0088 * Note that parts that implement this extension might not support all the 0089 * options available in @ref KFind::SearchOptions. 0090 */ 0091 virtual bool findText(const QString &string, KFind::SearchOptions options) const; 0092 0093 // for future extensions can be made via slots 0094 0095 Q_SIGNALS: 0096 /** 0097 * This signal is emitted when the selection changes. 0098 */ 0099 void selectionChanged(); 0100 0101 private: 0102 // for future extensions 0103 std::unique_ptr<TextExtensionPrivate> const d; 0104 }; 0105 0106 #endif /* TEXTEXTENSION_H */