1/*
2 This file is part of KNewStuffCore.
3 SPDX-FileCopyrightText: 2016 Dan Leinir Turthra Jensen <admin@leinir.dk>
4
5 SPDX-License-Identifier: LGPL-2.1-or-later
6*/
7
8#ifndef KNS3_QUESTION_H
9#define KNS3_QUESTION_H
10
11#include <QObject>
12
13#include "knewstuffcore_export.h"
14
15#include <memory>
16
17namespace KNSCore
18{
19class Entry;
20class QuestionPrivate;
21/*!
22 \class KNSCore::Question
23 \inmodule KNewStuffCore
24
25 \brief A way to ask a user a question from inside a GUI-less library (like KNewStuffCore).
26
27 Rather than using a message box (which is a UI thing), when you want to ask your user
28 a question, create an instance of this class and use that instead. The consuming library
29 (in most cases KNewStuff or KNewStuffQuick) will listen to any question being asked,
30 and act appropriately (that is, KNewStuff will show a dialog with an appropriate dialog
31 box, and KNewStuffQuick will either request a question be asked if the developer is using
32 the plugin directly, or ask the question using an appropriate method for Qt Quick based
33 applications)
34
35 The following is an example of a question asking the user to select an item from a list.
36
37 \code
38QStringList choices() << "foo" << "bar";
39Question question(Question::SelectFromListQuestion);
40question.setTitle("Pick your option");
41question.setQuestion("Please select which option you would like");
42question.setList(choices);
43question.setEntry(entry);
44if (question.ask() == Question::OKResponse) {
45 QString theChoice = question.response();
46}
47\endcode
48 */
49class KNEWSTUFFCORE_EXPORT Question : public QObject
50{
51 Q_OBJECT
52public:
53 /*!
54 * \enum KNSCore::Question::Response
55 *
56 * \brief Defines how the user responded to the question.
57 *
58 * \sa QuestionType
59 *
60 * \value InvalidResponse
61 * The user did not provide a valid response.
62 *
63 * \value YesResponse
64 * The user selected yes.
65 *
66 * \value NoResponse
67 * The user selected no.
68 *
69 * \value ContinueResponse
70 * The user selected continue.
71 *
72 * \value CancelResponse
73 * The user selected cancel.
74 *
75 * \value OKResponse
76 * The user selected OK.
77 */
78 enum Response {
79 InvalidResponse = 0,
80 YesResponse = 1,
81 NoResponse = 2,
82 ContinueResponse = 3,
83 CancelResponse = 4,
84 OKResponse = YesResponse,
85 };
86 Q_ENUM(Response)
87
88 /*!
89 * \enum KNSCore::Question::QuestionType
90 *
91 * \brief Defines the type of question to be presented to the user.
92 *
93 * \sa Response
94 *
95 * \value YesNoQuestion
96 * The question can be answered with either yes or no.
97 *
98 * \value ContinueCancelQuestion
99 * The question can be answered with either continue or cancel.
100 *
101 * \value InputTextQuestion
102 * Answering the question requires text input from the user.
103 *
104 * \value SelectFromListQuestion
105 * Answering the question requires selecting from a list of choices.
106 *
107 * \value PasswordQuestion
108 * Answering the question requires the user to input a password.
109 */
110 enum QuestionType {
111 YesNoQuestion = 0,
112 ContinueCancelQuestion = 1,
113 InputTextQuestion = 2,
114 SelectFromListQuestion = 3,
115 PasswordQuestion = 4,
116 };
117 Q_ENUM(QuestionType)
118
119 explicit Question(QuestionType = YesNoQuestion, QObject *parent = nullptr);
120 ~Question() override;
121
122 /*!
123 * Returns the user's reponse to the question.
124 *
125 * \sa setResponse
126 */
127 Response ask();
128
129 /*!
130 * Sets the type of question presented to the user.
131 *
132 * \a newType is the question type
133 */
134 void setQuestionType(QuestionType newType = YesNoQuestion);
135
136 /*!
137 * Returns the configured question type.
138 */
139 QuestionType questionType() const;
140
141 /*!
142 * Sets the question to be presented to the user.
143 *
144 * \a newQuestion is the question message
145 *
146 */
147 void setQuestion(const QString &newQuestion);
148
149 /*!
150 * Returns the question message to be presented to the user.
151 */
152 QString question() const;
153
154 /*!
155 * Sets the title of the UX element presented to the user.
156 *
157 * \a newTitle is the title text
158 */
159 void setTitle(const QString &newTitle);
160
161 /*!
162 * Returns the title of the UX element.
163 */
164 QString title() const;
165
166 /*!
167 * Sets the list of optional choices to present to the user to \a newList
168 * for a SelectFromListQuestion.
169 */
170 void setList(const QStringList &newList);
171
172 /*!
173 * Returns the list of choices to present to the user, if any.
174 */
175 QStringList list() const;
176
177 /*!
178 * Sets the data \a entry container this question refers to.
179 */
180 void setEntry(const Entry &entry);
181
182 /*!
183 * Returns the configured entry.
184 */
185 Entry entry() const;
186
187 /*!
188 * When the user makes a choice on a question, that is a response. This is the return value in ask().
189 *
190 * \a response This will set the response, and mark the question as answered
191 *
192 */
193 void setResponse(Response response);
194
195 /*!
196 * If the user has any way of inputting data to go along with the response above, consider this a part
197 * of the response. As such, you can set, and later get, that response as well. This does NOT mark the
198 * question as answered.
199 *
200 * \a response This sets the string response for the question
201 *
202 * \sa setResponse
203 */
204 void setResponse(const QString &response);
205
206 /*!
207 * Returns the response data provided by the user, if any.
208 */
209 QString response() const;
210
211private:
212 const std::unique_ptr<QuestionPrivate> d;
213};
214}
215
216#endif // KNS3_QUESTION_H
217

source code of knewstuff/src/core/question.h