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, 269 insertions, 0 deletions

diff --git a/kutils/kreplace.h b/kutils/kreplace.h
new file mode 100644
index 000000000..2a174af23
--- /dev/null
+++ b/kutils/kreplace.h
@@ -0,0 +1,269 @@
+/*
+    Copyright (C) 2001, S.R.Haque <[email protected]>.
+    Copyright (C) 2002, David Faure <[email protected]>
+    This file is part of the KDE project
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Library General Public
+    License version 2, as published by the Free Software Foundation.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Library General Public License for more details.
+
+    You should have received a copy of the GNU Library General Public License
+    along with this library; see the file COPYING.LIB.  If not, write to
+    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+    Boston, MA 02110-1301, USA.
+*/
+
+#ifndef KREPLACE_H
+#define KREPLACE_H
+
+#include "kfind.h"
+
+class KReplaceNextDialog;
+
+/**
+ * @ingroup main
+ * @ingroup findreplace
+ * @brief A generic implementation of the "replace" function.
+ *
+ * @author S.R.Haque <[email protected]>, David Faure <[email protected]>
+ *
+ * \b Detail:
+ *
+ * This class includes prompt handling etc. Also provides some
+ * static functions which can be used to create custom behavior
+ * instead of using the class directly.
+ *
+ * \b Example:
+ *
+ * To use the class to implement a complete replace feature:
+ *
+ * In the slot connect to the replace action, after using KReplaceDialog:
+ * \code
+ *
+ *  // This creates a replace-on-prompt dialog if needed.
+ *  m_replace = new KReplace(pattern, replacement, options, this);
+ *
+ *  // Connect signals to code which handles highlighting
+ *  // of found text, and on-the-fly replacement.
+ *  connect( m_replace, SIGNAL( highlight( const QString &, int, int ) ),
+ *          this, SLOT( slotHighlight( const QString &, int, int ) ) );
+ *  // Connect findNext signal - called when pressing the button in the dialog
+ *  connect( m_replace, SIGNAL( findNext() ),
+ *          this, SLOT( slotReplaceNext() ) );
+ *  // Connect replace signal - called when doing a replacement
+ *  connect( m_replace, SIGNAL( replace(const QString &, int, int, int) ),
+ *          this, SLOT( slotReplace(const QString &, int, int, int) ) );
+ * \endcode
+ *  Then initialize the variables determining the "current position"
+ *  (to the cursor, if the option FromCursor is set,
+ *   to the beginning of the selection if the option SelectedText is set,
+ *   and to the beginning of the document otherwise).
+ *  Initialize the "end of search" variables as well (end of doc or end of selection).
+ *  Swap begin and end if FindBackwards.
+ *  Finally, call slotReplaceNext();
+ *
+ * \code
+ *  void slotReplaceNext()
+ *  {
+ *      KFind::Result res = KFind::NoMatch;
+ *      while ( res == KFind::NoMatch && <position not at end> ) {
+ *          if ( m_replace->needData() )
+ *              m_replace->setData( <current text fragment> );
+ *
+ *          // Let KReplace inspect the text fragment, and display a dialog if a match is found
+ *          res = m_replace->replace();
+ *
+ *          if ( res == KFind::NoMatch ) {
+ *              <Move to the next text fragment, honoring the FindBackwards setting for the direction>
+ *          }
+ *      }
+ *
+ *      if ( res == KFind::NoMatch ) // i.e. at end
+ *          <Call either  m_replace->displayFinalDialog(); delete m_replace; m_replace = 0L;
+ *           or           if ( m_replace->shouldRestart() ) { reinit (w/o FromCursor) and call slotReplaceNext(); }
+ *                        else { m_replace->closeReplaceNextDialog(); }>
+ *  }
+ * \endcode
+ *
+ *  Don't forget delete m_find in the destructor of your class,
+ *  unless you gave it a parent widget on construction.
+ *
+ */
+class KUTILS_EXPORT KReplace :
+    public KFind
+{
+    Q_OBJECT
+
+public:
+
+    /**
+     * Only use this constructor if you don't use KFindDialog, or if
+     * you use it as a modal dialog.
+     * @param pattern The pattern to look for.
+     * @param replacement The replacement string.
+     * @param options Options for the find dialog. @see KFindDialog and KReplaceDialog.
+     * @param parent The parent widget.
+     */
+    KReplace(const QString &pattern, const QString &replacement, long options, QWidget *parent = 0);
+    /**
+     * This is the recommended constructor if you also use KReplaceDialog (non-modal).
+     * You should pass the pointer to it here, so that when a message box
+     * appears it has the right parent. Don't worry about deletion, KReplace
+     * will notice if the find dialog is closed.
+     * @param pattern The pattern to look for.
+     * @param replacement The replacement string.
+     * @param options Options for the find dialog. @see KFindDialog and KReplaceDialog.
+     * @param parent The parent widget.
+     * @param replaceDialog A pointer to the KReplaceDialog object.
+     */
+    KReplace(const QString &pattern, const QString &replacement, long options, QWidget *parent, QWidget* replaceDialog);
+
+    /**
+     * Destructor.
+     */
+    virtual ~KReplace();
+
+    /**
+     * Return the number of replacements made (i.e. the number of times
+     * the replace signal was emitted).
+     * Can be used in a dialog box to tell the user how many replacements were made.
+     * The final dialog does so already, unless you used setDisplayFinalDialog(false).
+     * @return The number of replacements.
+     */
+    int numReplacements() const { return m_replacements; }
+
+    /**
+     * Call this to reset the numMatches & numReplacements counts.
+     * Can be useful if reusing the same KReplace for different operations,
+     * or when restarting from the beginning of the document.
+     */
+    virtual void resetCounts();
+
+    /**
+     * Walk the text fragment (e.g. kwrite line, kspread cell) looking for matches.
+     * For each match, if prompt-on-replace is specified, emits the highlight() signal
+     * and displays the prompt-for-replace dialog before doing the replace.
+     * @return Whether or not there has been a match.
+     */
+    Result replace();
+
+    /**
+     * Return (or create) the dialog that shows the "find next?" prompt.
+     * Usually you don't need to call this.
+     * One case where it can be useful, is when the user selects the "Find"
+     * menu item while a find operation is under way. In that case, the
+     * program may want to call setActiveWindow() on that dialog.
+     * @return The replace next dialog.
+     */
+    KDialogBase* replaceNextDialog( bool create = false );
+
+    /**
+     * Close the "replace next?" dialog. The application should do this when
+     * the last match was hit. If the application deletes the KReplace, then
+     * "find previous" won't be possible anymore.
+     */
+    void closeReplaceNextDialog();
+
+    /**
+     * Searches the given string, replaces with the given replacement string,
+     * and returns whether a match was found. If one is,
+     * the replacement string length is also returned.
+     *
+     * A performance optimised version of the function is provided for use
+     * with regular expressions.
+     *
+     * @param text The string to search.
+     * @param pattern The pattern to look for.
+     * @param replacement The replacement string to insert into the text.
+     * @param index The starting index into the string.
+     * @param options The options to use.
+     * @param replacedLength Output parameter, contains the length of the replaced string.
+     * Not always the same as replacement.length(), when backreferences are used.
+     * @return The index at which a match was found, or -1 if no match was found.
+     */
+    static int replace( QString &text, const QString &pattern, const QString &replacement, int index, long options, int *replacedLength );
+
+    /**
+     * Searches the given regular expression, replaces with the given replacement string,
+     * and returns whether a match was found. If one is,
+     * the replacement string length is also returned.
+     *
+     * Another version of the function is provided for use with strings.
+     *
+     * @param text The string to search.
+     * @param pattern The regular expression pattern to look for.
+     * @param replacement The replacement string to insert into the text.
+     * @param index The starting index into the string.
+     * @param options The options to use.
+     * @param replacedLength Output parameter, contains the length of the replaced string.
+     * Not always the same as replacement.length(), when backreferences are used.
+     * @return The index at which a match was found, or -1 if no match was found.
+     */
+    static int replace( QString &text, const QRegExp &pattern, const QString &replacement, int index, long options, int *replacedLength );
+
+    /**
+     * Returns @c true if we should restart the search from scratch.
+     * Can ask the user, or return @c false (if we already searched/replaced the
+     * whole document without the PromptOnReplace option).
+     *
+     * @param forceAsking set to @c true if the user modified the document during the
+     * search. In that case it makes sense to restart the search again.
+     *
+     * @param showNumMatches set to @c true if the dialog should show the number of
+     * matches. Set to @c false if the application provides a "find previous" action,
+     * in which case the match count will be erroneous when hitting the end,
+     * and we could even be hitting the beginning of the document (so not all
+     * matches have even been seen).
+     *
+     * @return @c true, if the search should be restarted.
+     */
+    virtual bool shouldRestart( bool forceAsking = false, bool showNumMatches = true ) const;
+
+    /**
+     * Displays the final dialog telling the user how many replacements were made.
+     * Call either this or shouldRestart().
+     */
+    virtual void displayFinalDialog() const;
+
+signals:
+
+    /**
+     * Connect to this slot to implement updating of replaced text during the replace
+     * operation.
+     *
+     * Extra care must be taken to properly implement the "no prompt-on-replace" case.
+     * For instance highlight isn't emitted in that case (some code might rely on it),
+     * and for performance reasons one should repaint after replace() ONLY if
+     * prompt-on-replace was selected.
+     *
+     * @param text The text, in which the replacement has already been done.
+     * @param replacementIndex Starting index of the matched substring
+     * @param replacedLength Length of the replacement string
+     * @param matchedLength Length of the matched string
+     */
+    void replace(const QString &text, int replacementIndex, int replacedLength, int matchedLength);
+
+protected slots:
+
+    void slotSkip();
+    void slotReplace();
+    void slotReplaceAll();
+
+private:
+    KReplaceNextDialog* dialog();
+    void doReplace();
+    static int replace( QString &text, const QString &replacement, int index, long options, int length );
+
+    QString m_replacement;
+    unsigned m_replacements;
+
+    // Binary compatible extensibility.
+    class KReplacePrivate;
+    KReplacePrivate *d;
+};
+#endif