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

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