KWidgetsAddons

kassistantdialog.h
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 
146 };
147 
148 #endif
A dialog base class which can handle multiple pages.
Definition: kpagedialog.h:77
This class provides a framework for assistant dialogs.
Page widget with many layouts (faces).
Definition: kpagewidget.h:24
Q_DISABLE_COPY(Class)
KPageWidgetItem is used by KPageWidget and represents a page.
virtual void showEvent(QShowEvent *event) override
typedef WindowFlags
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sat Dec 4 2021 22:48:05 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.