Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdelibs@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 137 insertions, 0 deletions

diff --git a/interfaces/kregexpeditor/kregexpeditorinterface.h b/interfaces/kregexpeditor/kregexpeditorinterface.h
new file mode 100644
index 000000000..f1267d711
--- /dev/null
+++ b/interfaces/kregexpeditor/kregexpeditorinterface.h
@@ -0,0 +1,137 @@
+#ifndef __kregexpeditorinterface_h__
+#define __kregexpeditorinterface_h__
+
+#include <qstring.h>
+
+/**
+ *  A graphical editor for regular expressions.
+ * 
+ * @author Jesper K. Pedersen blackie@kde.org
+ *
+ * The actual editor is located in kdeutils, with an interface in
+ * kdelibs. This means that it is a bit more complicated to create an
+ * instance of the editor, but only a little bit more complicated.
+ *
+ * To check if kregexpeditor in kdeutils is installed and available use this line:
+ * 
+ * \code
+ * bool installed=!KTrader::self()->query("KRegExpEditor/KRegExpEditor").isEmpty();
+ * \endcode
+ *
+ * The following is a template for what you need to do to create an instance of the
+ * regular expression dialog:
+ *
+ * \code
+ * QDialog *editorDialog = KParts::ComponentFactory::createInstanceFromQuery<QDialog>( "KRegExpEditor/KRegExpEditor" );
+ * if ( editorDialog ) {
+ *   // kdeutils was installed, so the dialog was found fetch the editor interface
+ *   KRegExpEditorInterface *editor = static_cast<KRegExpEditorInterface *>( editorDialog->qt_cast( "KRegExpEditorInterface" ) );
+ *   Q_ASSERT( editor ); // This should not fail!
+ *   
+ *   // now use the editor.
+ *   editor->setRegExp("^kde$");
+ *
+ *   // Finally exec the dialog
+ *   editorDialog->exec();
+ * }
+ * else {
+ *   // Don't offer the dialog.
+ * }
+ * \endcode
+ *
+ * Note: signals and slots must be connected to the editorDialog object, not to the editor object:
+ * \code
+ * connect( editorDialog, SIGNAL( canUndo( bool ) ), undoBut, SLOT( setEnabled( bool ) ) );
+ * \endcode
+ *
+ * If you want to create an instance of the editor widget, i.e. not the
+ * dialog, then you must do it in the following way:
+ *
+ * \code
+ * QWidget *editorWidget =
+ * KParts::ComponentFactory::createInstanceFromQuery<QWidget>( 
+ *     "KRegExpEditor/KRegExpEditor", QString::null, parent );
+ * if ( editorWidget ) {
+ *   // kdeutils was installed, so the widget was found fetch the editor interface
+ *   KRegExpEditorInterface *editor = static_cast<KRegExpEditorInterface *>( editorWidget->qt_cast( "KRegExpEditorInterface" ) );
+ *   Q_ASSERT( editor ); // This should not fail!
+ *   
+ *   // now use the editor.
+ *   editor->setRegExp("^kde$");
+
+ *   // Finally insert the widget into the layout of its parent
+ *   layout->addWidget( editorWidget );
+ * }
+ * else {
+ *   // Don't offer the editor widget.
+ * }
+ * \endcode
+ *
+ */
+class KRegExpEditorInterface
+{
+public:
+  /**
+   * returns the regular expression of the editor in Qt3 QRegExp
+   * syntax. Note, there is also a 'regexp' Qt property available.
+   */
+  virtual QString regExp() const = 0;
+
+protected:
+// These are signals: in classes that actually implement the interface.
+
+  /**
+   * This signal tells whether undo is available.
+   */
+  virtual void canUndo( bool ) = 0;
+
+  /**
+   * This signal tells whether redo is available.
+   */
+  virtual void canRedo( bool ) = 0;
+
+  /**
+   * This signal is emited whenever the regular expression changes.
+   * The argument is true when the regular expression is different from
+   * the loaded regular expression and false when it is equal to the
+   * loaded regular expression.
+   */
+  virtual void changes( bool ) = 0;
+
+public:
+// These are public slots: in classes that implement the interface.
+
+ /**
+  * Set the regular expression for the editor. The syntax must be Qt3
+  * QRegExp syntax.
+  */
+  virtual void setRegExp( const QString &regexp ) = 0;
+  virtual void redo() = 0;
+  virtual void undo() = 0;
+
+  /**
+   * Set text to use when showing matches. NOT IMPLEMENTED YET!
+   *   
+   * This method is not yet implemented. In later version of the widget
+   * this method will be used to give the widget a text to show matches of
+   * the regular expression on.
+   */
+  virtual void setMatchText( const QString& ) = 0;
+  
+  /**
+   * This method allows for future changes that will not break binary
+   * compatibility. DONT USE!
+   *   
+   * KDE has a policy of keeping binary compatibility for all major
+   * version of KDE. This means that new methods can not be added to this
+   * API before KDE version 4.0.
+   *
+   * This method is an escape door for that.
+   *   
+   * Conclusion: You should not use this method in this version of KDE!
+   */
+  virtual void doSomething( QString method, void* arguments ) = 0;
+};
+
+#endif
+