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 */
94class KRegExpEditorInterface
95{
96public:
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
105protected:
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
126public:
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 &regexp ) = 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
161Q_DECLARE_INTERFACE(KRegExpEditorInterface, "org.kde.KRegExpEditorInterface/1.0")
162
163#endif
164
165