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 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 */
38class KWIDGETSADDONS_EXPORT KAssistantDialog : public KPageDialog
39{
40 Q_OBJECT
41public:
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
107public 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
124protected:
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
138private:
139 Q_DECLARE_PRIVATE(KAssistantDialog)
140
141 Q_DISABLE_COPY(KAssistantDialog)
142};
143
144#endif
145

source code of kwidgetsaddons/src/kassistantdialog.h