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