1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2006 Olivier Goffart <ogoffart at kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-only
6*/
7
8#ifndef KASSISTANTDIALOG_H
9#define KASSISTANTDIALOG_H
10
11#include <kpagedialog.h>
12
13#include <kwidgetsaddons_export.h>
14
15class KAssistantDialogPrivate;
16
17/*!
18 * \class KAssistantDialog
19 * \inmodule KWidgetsAddons
20 *
21 * \brief This class provides a framework for assistant dialogs.
22 *
23 * An assistant dialog consists of a sequence of pages.
24 * Its purpose is to guide the user (assist) through a process step by step.
25 * Assistant dialogs are useful for complex or infrequently occurring tasks
26 * that people may find difficult to learn or do.
27 * Sometimes a task requires too many input fields to fit them on a single dialog.
28 *
29 * Create and populate dialog pages that inherit from QWidget and add them
30 * to the assistant dialog using addPage().
31 *
32 * The functions next() and back() are virtual and may be reimplemented to
33 * override the default actions of the next and back buttons.
34 *
35 * \image kassistantdialog.png "KAssistantDialog"
36 */
37class KWIDGETSADDONS_EXPORT KAssistantDialog : public KPageDialog
38{
39 Q_OBJECT
40public:
41 /*!
42 * Construct a new assistant dialog with \a parent as parent.
43 *
44 * \a parent is the parent of the widget.
45 *
46 * \a flags the window flags to give to the assistant dialog. The
47 * default of zero is usually what you want.
48 */
49 explicit KAssistantDialog(QWidget *parent = nullptr, Qt::WindowFlags flags = Qt::WindowFlags());
50 ~KAssistantDialog() override;
51
52 /*!
53 * Specify if the content of the page is valid, and if the next button may be enabled on this page.
54 * By default all pages are valid.
55 *
56 * This will disable or enable the next button on the specified page
57 *
58 * \a page the page on which the next button will be enabled/disable
59 *
60 * \a enable if true the next button will be enabled, if false it will be disabled
61 */
62 void setValid(KPageWidgetItem *page, bool enable);
63
64 /*!
65 * return if a page is valid
66 *
67 * \a page the page to check the validity of
68 * \sa setValid()
69 */
70 bool isValid(KPageWidgetItem *page) const;
71
72 /*!
73 * Specify whether a page is appropriate.
74 *
75 * A page is considered inappropriate if it should not be shown due to
76 * the contents of other pages making it inappropriate.
77 *
78 * A page which is inappropriate will not be shown.
79 *
80 * The last page in an assistant dialog should always be appropriate
81 *
82 * \a page the page to set as appropriate
83 *
84 * \a appropriate flag indicating the appropriateness of the page.
85 *
86 * If \a appropriate is true, then \a page is appropriate and will be
87 * shown in the assistant dialog. If false, \a page will not be shown.
88 */
89 void setAppropriate(KPageWidgetItem *page, bool appropriate);
90
91 /*!
92 * Check if a page is appropriate for use in the assistant dialog.
93 *
94 * \a page is the page to check the appropriateness of.
95 *
96 * Returns \c true if \a page is appropriate, false if it is not
97 */
98 bool isAppropriate(KPageWidgetItem *page) const;
99
100 /*!
101 * Returns the next button
102 */
103 QPushButton *nextButton() const;
104
105 /*!
106 * Returns the finish button
107 */
108 QPushButton *backButton() const;
109
110 /*!
111 * Returns the finish button
112 */
113 QPushButton *finishButton() const;
114
115public Q_SLOTS:
116 /*!
117 * Called when the user clicks the Back button.
118 *
119 * This function will show the preceding relevant page in the sequence.
120 * Do nothing if the current page is the first page in the sequence.
121 */
122 virtual void back();
123
124 /*!
125 * Called when the user clicks the Next/Finish button.
126 *
127 * This function will show the next relevant page in the sequence.
128 * If the current page is the last page, it will call accept()
129 */
130 virtual void next();
131
132protected:
133 /*!
134 * Construct an assistant dialog from a single widget.
135 *
136 * \a widget the widget to construct the dialog with
137 *
138 * \a parent the parent of the assistant dialog
139 *
140 * \a flags the window flags to use when creating the widget. The default
141 * of zero is usually fine.
142 *
143 * Calls the KPageDialog(KPageWidget *widget, QWidget *parent, Qt::WindowFlags flags) constructor
144 */
145 explicit KAssistantDialog(KPageWidget *widget, QWidget *parent = nullptr, Qt::WindowFlags flags = Qt::WindowFlags());
146
147 void showEvent(QShowEvent *event) override;
148
149private:
150 Q_DECLARE_PRIVATE(KAssistantDialog)
151
152 Q_DISABLE_COPY(KAssistantDialog)
153};
154
155#endif
156

source code of kwidgetsaddons/src/kassistantdialog.h