File indexing completed on 2024-12-01 03:43:35

 /*
     This file is part of the KDE project
     SPDX-FileCopyrightText: 2001 S.R. Haque <srhaque@iee.org>.
     SPDX-FileCopyrightText: 2002 David Faure <david@mandrakesoft.com>
 
     SPDX-License-Identifier: LGPL-2.0-only
 */
 
 #ifndef KFINDDIALOG_H
 #define KFINDDIALOG_H
 
 #include "ktextwidgets_export.h"
 
 #include <QDialog>
 #include <memory>
 
 class KFindDialogPrivate;
 
 /**
  * @class KFindDialog kfinddialog.h <KFindDialog>
  *
  * @brief A generic "find" dialog.
  *
  * @author S.R.Haque <srhaque@iee.org>
  *
  * \b Detail:
  *
  * This widget inherits from KDialog and implements
  * the following additional functionalities:  a find string
  * object and an area for a user-defined widget to extend the dialog.
  *
  * \b Example:
  *
  * To use the basic modal find dialog, and then run the search:
  *
  * \code
  *  KFindDialog dlg(....)
  *  if (dlg.exec() != QDialog::Accepted)
  *      return;
  *
  *  // proceed with KFind from here
  * \endcode
  *
  * To create a non-modal find dialog:
  * \code
  *   if (m_findDialog) {
  *     m_findDialog->activateWindow();
  *   } else {
  *     m_findDialog = new KFindDialog(...);
  *     connect(m_findDialog, &KFindDialog::okClicked, this, [this] {
  *         m_findDialog->close();
  *         delete m_find;
  *         m_find = new KFind(m_findDialog->pattern(), m_findDialog->options(), this);
  *         // ... see KFind documentation for what else should be done here
  *     });
  *   }
  * \endcode
  * Don't forget to delete and reset m_findDialog when closed.
  * (But do NOT delete your KFind object at that point, it's needed for "Find Next".)
  *
  * To use your own extensions: see findExtension().
  *
  * \image html kfinddialog.png "KFindDialog Widget"
  */
 class KTEXTWIDGETS_EXPORT KFindDialog : public QDialog
 {
     Q_OBJECT
 
 public:
     /**
      * Construct a modal find dialog
      *
      * @param parent The parent object of this widget.
      * @param options A bitfield of the Options to be checked.
      * @param findStrings The find history, see findHistory()
      * @param hasSelection Whether a selection exists
      */
     explicit KFindDialog(QWidget *parent = nullptr,
                          long options = 0,
                          const QStringList &findStrings = QStringList(),
                          bool hasSelection = false,
                          bool replaceDialog = false);
 
     /**
      * Destructor.
      */
     ~KFindDialog() override;
 
     /**
      * Provide the list of @p strings to be displayed as the history
      * of find strings. @p strings might get truncated if it is
      * too long.
      *
      * @param history The find history.
      * @see findHistory
      */
     void setFindHistory(const QStringList &history);
 
     /**
      * Returns the list of history items.
      *
      * @see setFindHistory
      */
     QStringList findHistory() const;
 
     /**
      * Enable/disable the 'search in selection' option, depending
      * on whether there actually is a selection.
      *
      * @param hasSelection true if a selection exists
      */
     void setHasSelection(bool hasSelection);
 
     /**
      * Hide/show the 'from cursor' option, depending
      * on whether the application implements a cursor.
      *
      * @param hasCursor true if the application features a cursor
      * This is assumed to be the case by default.
      */
     void setHasCursor(bool hasCursor);
 
     /**
      * Enable/disable the 'Find backwards' option, depending
      * on whether the application supports it.
      *
      * @param supports true if the application supports backwards find
      * This is assumed to be the case by default.
      */
     void setSupportsBackwardsFind(bool supports);
 
     /**
      * Enable/disable the 'Case sensitive' option, depending
      * on whether the application supports it.
      *
      * @param supports true if the application supports case sensitive find
      * This is assumed to be the case by default.
      */
     void setSupportsCaseSensitiveFind(bool supports);
 
     /**
      * Enable/disable the 'Whole words only' option, depending
      * on whether the application supports it.
      *
      * @param supports true if the application supports whole words only find
      * This is assumed to be the case by default.
      */
     void setSupportsWholeWordsFind(bool supports);
 
     /**
      * Enable/disable the 'Regular expression' option, depending
      * on whether the application supports it.
      *
      * @param supports true if the application supports regular expression find
      * This is assumed to be the case by default.
      */
     void setSupportsRegularExpressionFind(bool supports);
 
     /**
      * Set the options which are checked.
      *
      * @param options The setting of the Options.
      *
      * @see options()
      * @see KFind::Options
      */
     void setOptions(long options);
 
     /**
      * Returns the state of the options. Disabled options may be returned in
      * an indeterminate state.
      *
      * @see setOptions()
      * @see KFind::Options
      */
     long options() const;
 
     /**
      * Returns the pattern to find.
      */
     QString pattern() const;
 
     /**
      * Sets the pattern to find
      */
     void setPattern(const QString &pattern);
 
     /**
      * Returns an empty widget which the user may fill with additional UI
      * elements as required. The widget occupies the width of the dialog,
      * and is positioned immediately below the regular expression support
      * widgets for the pattern string.
      */
     QWidget *findExtension() const;
 
 Q_SIGNALS:
     /**
      * This signal is sent whenever one of the option checkboxes is toggled.
      * Call options() to get the new state of the checkboxes.
      */
     void optionsChanged();
 
     /**
      * This signal is sent when the user clicks on Ok button.
      */
     void okClicked();
 
     /**
      * This signal is sent when the user clicks on Cancel button.
      */
     void cancelClicked();
 
 protected:
     void showEvent(QShowEvent *) override;
 
 protected:
     KTEXTWIDGETS_NO_EXPORT explicit KFindDialog(KFindDialogPrivate &dd,
                                                 QWidget *parent = nullptr,
                                                 long options = 0,
                                                 const QStringList &findStrings = QStringList(),
                                                 bool hasSelection = false,
                                                 bool replaceDialog = false);
 
 protected:
     std::unique_ptr<class KFindDialogPrivate> const d_ptr;
 
 private:
     Q_DECLARE_PRIVATE(KFindDialog)
 };
 
 #endif // KFINDDIALOG_H