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 namespace KNSCore
16 {
17 /**
18  * @short A way to ask a user a question from inside a GUI-less library (like KNewStuffCore)
19  *
20  * Rather than using a message box (which is a UI thing), when you want to ask your user
21  * a question, create an instance of this class and use that instead. The consuming library
22  * (in most cases KNewStuff or KNewStuffQuick) will listen to any question being asked,
23  * and act appropriately (that is, KNewStuff will show a dialog with an appropriate dialog
24  * box, and KNewStuffQuick will either request a question be asked if the developer is using
25  * the plugin directly, or ask the question using an appropriate method for Qt Quick based
26  * applications)
27  *
28  * The following is an example of a question asking the user to select an item from a list.
29  *
30  * @code
31 QStringList choices() << "foo" << "bar";
32 Question question(Question::SelectFromListQuestion);
33 question.setTitle("Pick your option");
34 question.setQuestion("Please select which option you would like");
35 question.setList(choices);
36 if(question.ask() == Question::OKResponse) {
37     QString theChoice = question.response();
38 }
39 @endcode
40  */
41 class KNEWSTUFFCORE_EXPORT Question : public QObject
42 {
43     Q_OBJECT
44 public:
45     enum Response {
46         InvalidResponse = 0,
47         YesResponse = 1,
48         NoResponse = 2,
49         ContinueResponse = 3,
50         CancelResponse = 4,
51         OKResponse = YesResponse,
52     };
53     Q_ENUM(Response)
54 
55     enum QuestionType {
56         YesNoQuestion = 0,
57         ContinueCancelQuestion = 1,
58         InputTextQuestion = 2,
59         SelectFromListQuestion = 3,
60         PasswordQuestion = 4,
61     };
62     Q_ENUM(QuestionType)
63 
64     explicit Question(QuestionType = YesNoQuestion, QObject *parent = nullptr);
65     ~Question() override;
66 
67     Response ask();
68 
69     void setQuestionType(QuestionType newType = YesNoQuestion);
70     QuestionType questionType() const;
71 
72     void setQuestion(const QString &newQuestion);
73     QString question() const;
74     void setTitle(const QString &newTitle);
75     QString title() const;
76     void setList(const QStringList &newList);
77     QStringList list() const;
78 
79     /**
80      * When the user makes a choice on a question, that is a response. This is the return value in ask().
81      * @param response This will set the response, and mark the question as answered
82      */
83     void setResponse(Response response);
84     /**
85      * If the user has any way of inputting data to go along with the response above, consider this a part
86      * of the response. As such, you can set, and later get, that response as well. This does NOT mark the
87      * question as answered ( @see setResponse(Response) ).
88      * @param response This sets the string response for the question
89      */
90     void setResponse(const QString &response);
91     QString response() const;
92 
93 private:
94     class Private;
95     Private *d;
96 };
97 }
98 
99 #endif // KNS3_QUESTION_H
100