File indexing completed on 2024-12-01 12:39:35

0001 /*
0002     This file is part of the KDE project
0003     SPDX-FileCopyrightText: 2001 S.R. Haque <srhaque@iee.org>.
0004     SPDX-FileCopyrightText: 2002 David Faure <david@mandrakesoft.com>
0005 
0006     SPDX-License-Identifier: LGPL-2.0-only
0007 */
0008 
0009 #ifndef KFINDDIALOG_H
0010 #define KFINDDIALOG_H
0011 
0012 #include "ktextwidgets_export.h"
0013 
0014 #include <QDialog>
0015 #include <memory>
0016 
0017 class KFindDialogPrivate;
0018 
0019 /**
0020  * @class KFindDialog kfinddialog.h <KFindDialog>
0021  *
0022  * @brief A generic "find" dialog.
0023  *
0024  * @author S.R.Haque <srhaque@iee.org>
0025  *
0026  * \b Detail:
0027  *
0028  * This widget inherits from KDialog and implements
0029  * the following additional functionalities:  a find string
0030  * object and an area for a user-defined widget to extend the dialog.
0031  *
0032  * \b Example:
0033  *
0034  * To use the basic modal find dialog, and then run the search:
0035  *
0036  * \code
0037  *  KFindDialog dlg(....)
0038  *  if (dlg.exec() != QDialog::Accepted)
0039  *      return;
0040  *
0041  *  // proceed with KFind from here
0042  * \endcode
0043  *
0044  * To create a non-modal find dialog:
0045  * \code
0046  *   if (m_findDialog) {
0047  *     m_findDialog->activateWindow();
0048  *   } else {
0049  *     m_findDialog = new KFindDialog(...);
0050  *     connect(m_findDialog, &KFindDialog::okClicked, this, [this] {
0051  *         m_findDialog->close();
0052  *         delete m_find;
0053  *         m_find = new KFind(m_findDialog->pattern(), m_findDialog->options(), this);
0054  *         // ... see KFind documentation for what else should be done here
0055  *     });
0056  *   }
0057  * \endcode
0058  * Don't forget to delete and reset m_findDialog when closed.
0059  * (But do NOT delete your KFind object at that point, it's needed for "Find Next".)
0060  *
0061  * To use your own extensions: see findExtension().
0062  *
0063  * \image html kfinddialog.png "KFindDialog Widget"
0064  */
0065 class KTEXTWIDGETS_EXPORT KFindDialog : public QDialog
0066 {
0067     Q_OBJECT
0068 
0069 public:
0070     /**
0071      * Construct a modal find dialog
0072      *
0073      * @param parent The parent object of this widget.
0074      * @param options A bitfield of the Options to be checked.
0075      * @param findStrings The find history, see findHistory()
0076      * @param hasSelection Whether a selection exists
0077      */
0078     explicit KFindDialog(QWidget *parent = nullptr,
0079                          long options = 0,
0080                          const QStringList &findStrings = QStringList(),
0081                          bool hasSelection = false,
0082                          bool replaceDialog = false);
0083 
0084     /**
0085      * Destructor.
0086      */
0087     ~KFindDialog() override;
0088 
0089     /**
0090      * Provide the list of @p strings to be displayed as the history
0091      * of find strings. @p strings might get truncated if it is
0092      * too long.
0093      *
0094      * @param history The find history.
0095      * @see findHistory
0096      */
0097     void setFindHistory(const QStringList &history);
0098 
0099     /**
0100      * Returns the list of history items.
0101      *
0102      * @see setFindHistory
0103      */
0104     QStringList findHistory() const;
0105 
0106     /**
0107      * Enable/disable the 'search in selection' option, depending
0108      * on whether there actually is a selection.
0109      *
0110      * @param hasSelection true if a selection exists
0111      */
0112     void setHasSelection(bool hasSelection);
0113 
0114     /**
0115      * Hide/show the 'from cursor' option, depending
0116      * on whether the application implements a cursor.
0117      *
0118      * @param hasCursor true if the application features a cursor
0119      * This is assumed to be the case by default.
0120      */
0121     void setHasCursor(bool hasCursor);
0122 
0123     /**
0124      * Enable/disable the 'Find backwards' option, depending
0125      * on whether the application supports it.
0126      *
0127      * @param supports true if the application supports backwards find
0128      * This is assumed to be the case by default.
0129      */
0130     void setSupportsBackwardsFind(bool supports);
0131 
0132     /**
0133      * Enable/disable the 'Case sensitive' option, depending
0134      * on whether the application supports it.
0135      *
0136      * @param supports true if the application supports case sensitive find
0137      * This is assumed to be the case by default.
0138      */
0139     void setSupportsCaseSensitiveFind(bool supports);
0140 
0141     /**
0142      * Enable/disable the 'Whole words only' option, depending
0143      * on whether the application supports it.
0144      *
0145      * @param supports true if the application supports whole words only find
0146      * This is assumed to be the case by default.
0147      */
0148     void setSupportsWholeWordsFind(bool supports);
0149 
0150     /**
0151      * Enable/disable the 'Regular expression' option, depending
0152      * on whether the application supports it.
0153      *
0154      * @param supports true if the application supports regular expression find
0155      * This is assumed to be the case by default.
0156      */
0157     void setSupportsRegularExpressionFind(bool supports);
0158 
0159     /**
0160      * Set the options which are checked.
0161      *
0162      * @param options The setting of the Options.
0163      *
0164      * @see options()
0165      * @see KFind::Options
0166      */
0167     void setOptions(long options);
0168 
0169     /**
0170      * Returns the state of the options. Disabled options may be returned in
0171      * an indeterminate state.
0172      *
0173      * @see setOptions()
0174      * @see KFind::Options
0175      */
0176     long options() const;
0177 
0178     /**
0179      * Returns the pattern to find.
0180      */
0181     QString pattern() const;
0182 
0183     /**
0184      * Sets the pattern to find
0185      */
0186     void setPattern(const QString &pattern);
0187 
0188     /**
0189      * Returns an empty widget which the user may fill with additional UI
0190      * elements as required. The widget occupies the width of the dialog,
0191      * and is positioned immediately below the regular expression support
0192      * widgets for the pattern string.
0193      */
0194     QWidget *findExtension() const;
0195 
0196 Q_SIGNALS:
0197     /**
0198      * This signal is sent whenever one of the option checkboxes is toggled.
0199      * Call options() to get the new state of the checkboxes.
0200      */
0201     void optionsChanged();
0202 
0203     /**
0204      * This signal is sent when the user clicks on Ok button.
0205      */
0206     void okClicked();
0207 
0208     /**
0209      * This signal is sent when the user clicks on Cancel button.
0210      */
0211     void cancelClicked();
0212 
0213 protected:
0214     void showEvent(QShowEvent *) override;
0215 
0216 protected:
0217     KTEXTWIDGETS_NO_EXPORT explicit KFindDialog(KFindDialogPrivate &dd,
0218                                                 QWidget *parent = nullptr,
0219                                                 long options = 0,
0220                                                 const QStringList &findStrings = QStringList(),
0221                                                 bool hasSelection = false,
0222                                                 bool replaceDialog = false);
0223 
0224 private:
0225     friend class KReplaceDialog;
0226     Q_DECLARE_PRIVATE_D(d, KFindDialog)
0227     std::unique_ptr<class KFindDialogPrivate> const d;
0228     // KF6 TODO: change private d to protected d_ptr, use normal Q_DECLARE_PRIVATE, remove friend
0229 };
0230 
0231 #endif // KFINDDIALOG_H