1 | /* |
2 | * kregexpeditorinterface.h - KDE RegExp Editor Interface |
3 | * |
4 | * Copyright (c) 2002 Jesper K. Pedersen <blackie@kdab.net> |
5 | * Copyright (c) 2002 Simon Hausmann <hausmann@kde.org> |
6 | * |
7 | * This library is free software; you can redistribute it and/or |
8 | * modify it under the terms of the GNU Library General Public |
9 | * License as published by the Free Software Foundation; either |
10 | * version 2 of the License, or (at your option) any later version. |
11 | * |
12 | * This library is distributed in the hope that it will be useful, |
13 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
14 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
15 | * Library General Public License for more details. |
16 | * |
17 | * You should have received a copy of the GNU Library General Public License |
18 | * along with this library; see the file COPYING.LIB. If not, write to |
19 | * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
20 | * Boston, MA 02110-1301, USA. |
21 | */ |
22 | |
23 | #ifndef __kregexpeditorinterface_h__ |
24 | #define __kregexpeditorinterface_h__ |
25 | |
26 | #include <QtCore/QString> |
27 | #include <QtCore/QObject> |
28 | |
29 | /** |
30 | * A graphical editor for regular expressions. |
31 | * |
32 | * @author Jesper K. Pedersen blackie@kde.org |
33 | * |
34 | * The actual editor is located in kdeutils, with an interface in |
35 | * kdelibs. This means that it is a bit more comlicated to create an |
36 | * instance of the editor, but only a little bit more complicated. |
37 | * |
38 | * To check if kregexpeditor in kdeutils is installed and available use this line: |
39 | * |
40 | * \code |
41 | * bool installed=!KTrader::self()->query("KRegExpEditor/KRegExpEditor").isEmpty(); |
42 | * \endcode |
43 | * |
44 | * The following is a template for what you need to do to create an instance of the |
45 | * regular expression dialog: |
46 | * |
47 | * \code |
48 | * QDialog *editorDialog = KServiceTypeTrader::createInstanceFromQuery<QDialog>( "KRegExpEditor/KRegExpEditor" ); |
49 | * if ( editorDialog ) { |
50 | * // kdeutils was installed, so the dialog was found fetch the editor interface |
51 | * KRegExpEditorInterface *editor = static_cast<KRegExpEditorInterface *>( editorDialog->qt_cast( "KRegExpEditorInterface" ) ); |
52 | * Q_ASSERT( editor ); // This should not fail! |
53 | * |
54 | * // now use the editor. |
55 | * editor->setRegExp("^kde$"); |
56 | * |
57 | * // Finally exec the dialog |
58 | * editorDialog->exec(); |
59 | * } |
60 | * else { |
61 | * // Don't offer the dialog. |
62 | * } |
63 | * \endcode |
64 | * |
65 | * Note: signals and slots must be connected to the editorDialog object, not to the editor object: |
66 | * \code |
67 | * connect( editorDialog, SIGNAL( canUndo( bool ) ), undoBut, SLOT( setEnabled( bool ) ) ); |
68 | * \endcode |
69 | * |
70 | * If you want to create an instance of the editor widget, i.e. not the |
71 | * dialog, then you must do it in the following way: |
72 | * |
73 | * \code |
74 | * QWidget *editorWidget = |
75 | * KServiceTypeTrader::createInstanceFromQuery<QWidget>( |
76 | * "KRegExpEditor/KRegExpEditor", QString(), parent ); |
77 | * if ( editorWidget ) { |
78 | * // kdeutils was installed, so the widget was found fetch the editor interface |
79 | * KRegExpEditorInterface *editor = static_cast<KRegExpEditorInterface *>( editorWidget->qt_cast( "KRegExpEditorInterface" ) ); |
80 | * Q_ASSERT( editor ); // This should not fail! |
81 | * |
82 | * // now use the editor. |
83 | * editor->setRegExp("^kde$"); |
84 | |
85 | * // Finally insert the widget into the layout of its parent |
86 | * layout->addWidget( editorWidget ); |
87 | * } |
88 | * else { |
89 | * // Don't offer the editor widget. |
90 | * } |
91 | * \endcode |
92 | * |
93 | */ |
94 | class KRegExpEditorInterface |
95 | { |
96 | public: |
97 | /** |
98 | * returns the regular expression of the editor in Qt3 QRegExp |
99 | * syntax. Note, there is also a 'regexp' Qt property available. |
100 | */ |
101 | virtual QString regExp() const = 0; |
102 | |
103 | virtual ~KRegExpEditorInterface(){} |
104 | |
105 | protected: |
106 | // These are signals: in classes that actually implement the interface. |
107 | |
108 | /** |
109 | * This signal tells whether undo is available. |
110 | */ |
111 | virtual void canUndo( bool ) = 0; |
112 | |
113 | /** |
114 | * This signal tells whether redo is available. |
115 | */ |
116 | virtual void canRedo( bool ) = 0; |
117 | |
118 | /** |
119 | * This signal is emitted whenever the regular expression changes. |
120 | * The argument is true when the regular expression is different from |
121 | * the loaded regular expression and false when it is equal to the |
122 | * loaded regular expression. |
123 | */ |
124 | virtual void changes( bool ) = 0; |
125 | |
126 | public: |
127 | // These are public slots: in classes that implement the interface. |
128 | |
129 | /** |
130 | * Set the regular expression for the editor. The syntax must be Qt3 |
131 | * QRegExp syntax. |
132 | */ |
133 | virtual void setRegExp( const QString ®exp ) = 0; |
134 | virtual void redo() = 0; |
135 | virtual void undo() = 0; |
136 | |
137 | /** |
138 | * Set text to use when showing matches. NOT IMPLEMENTED YET! |
139 | * |
140 | * This method is not yet implemented. In later version of the widget |
141 | * this method will be used to give the widget a text to show matches of |
142 | * the regular expression on. |
143 | */ |
144 | virtual void setMatchText( const QString& ) = 0; |
145 | |
146 | /** |
147 | * This method allows for future changes that will not break binary |
148 | * compatibility. DO NOT USE! |
149 | * |
150 | * KDE has a policy of keeping binary compatibility for all major |
151 | * version of KDE. This means that new methods can not be added to this |
152 | * API before KDE version 4.0. |
153 | * |
154 | * This method is an escape door for that. |
155 | * |
156 | * Conclusion: You should not use this method in this version of KDE! |
157 | */ |
158 | virtual void doSomething( QString method, void* arguments ) = 0; |
159 | }; |
160 | |
161 | Q_DECLARE_INTERFACE(KRegExpEditorInterface, "org.kde.KRegExpEditorInterface/1.0" ) |
162 | |
163 | #endif |
164 | |
165 | |