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