kreplacedialog.h

/*
    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 KREPLACEDIALOG_H
#define KREPLACEDIALOG_H
 
#include "ktextwidgets_export.h"
 
#include "kfinddialog.h"
 
class KReplaceDialogPrivate;
 
/**
 * @class KReplaceDialog kreplace.h <KReplaceDialog>
 *
 * @short A generic "replace" dialog.
 *
 * @author S.R.Haque <srhaque@iee.org>
 *
 * \b Detail:
 *
 * This widget inherits from KFindDialog and implements
 * the following additional functionalities:  a replacement string
 * object and an area for a user-defined widget to extend the dialog.
 *
 * \b Example:
 *
 * To use the basic replace dialog:
 *
 * \code
 * \endcode
 *
 * To use your own extensions:
 *
 * \code
 * \endcode
 *
 * \image html kreplacedialog.png "KReplaceDialog Widget"
 */
class KTEXTWIDGETS_EXPORT KReplaceDialog : public KFindDialog
{
    Q_OBJECT
 
public:
    /// Options.
 
    enum Options {
        /// Should the user be prompted before the replace operation?
        PromptOnReplace = 256,
        BackReference = 512,
    };
 
    /**
     * Construct a replace dialog.read-only or rather select-only combo box with a
     * parent object and a name.
     *
     * @param parent The parent object of this widget
     * @param options A bitfield of the Options to be enabled.
     * @param findStrings A QStringList to insert in the combo box of text to find
     * @param replaceStrings A QStringList to insert in the combo box of text to
     *        replace with
     * @param hasSelection Whether a selection exists
     */
    explicit KReplaceDialog(QWidget *parent = nullptr,
                            long options = 0,
                            const QStringList &findStrings = QStringList(),
                            const QStringList &replaceStrings = QStringList(),
                            bool hasSelection = true);
 
    /**
     * Destructor.
     */
    ~KReplaceDialog() override;
 
    /**
     * Provide the list of @p strings to be displayed as the history
     * of replacement strings. @p strings might get truncated if it is
     * too long.
     *
     * @param history The replacement history.
     * @see replacementHistory
     */
    void setReplacementHistory(const QStringList &history);
 
    /**
     * Returns the list of history items.
     *
     * @see setReplacementHistory
     */
    QStringList replacementHistory() const;
 
    /**
     * Set the options which are enabled.
     *
     * @param options The setting of the Options.
     */
    void setOptions(long options);
 
    /**
     * Returns the state of the options. Disabled options may be returned in
     * an indeterminate state.
     *
     * @see setOptions
     */
    long options() const;
 
    /**
     * Returns the replacement string.
     */
    QString replacement() const;
 
    /**
     * 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 the regular expression support widgets
     * for the replacement string.
     */
    QWidget *replaceExtension() const;
 
protected:
    void showEvent(QShowEvent *) override;
 
private:
    Q_DECLARE_PRIVATE(KReplaceDialog)
};
 
#endif // KREPLACEDIALOG_H