diff --git a/Modules/Forms/include/mitkCheckboxesQuestion.h b/Modules/Forms/include/mitkCheckboxesQuestion.h index 713263f095..2dac18b3a1 100644 --- a/Modules/Forms/include/mitkCheckboxesQuestion.h +++ b/Modules/Forms/include/mitkCheckboxesQuestion.h @@ -1,42 +1,49 @@ /*============================================================================ The Medical Imaging Interaction Toolkit (MITK) Copyright (c) German Cancer Research Center (DKFZ) All rights reserved. Use of this source code is governed by a 3-clause BSD license that can be found in the LICENSE file. ============================================================================*/ #ifndef mitkCheckboxesQuestion_h #define mitkCheckboxesQuestion_h #include namespace mitk::Forms { + /** \brief A Question whose possible responses are represented by checkboxes. + * + * The question can have multiple responses at once, including an optional + * free text response. + * + * \sa MultipleChoiceQuestion, DropdownQuestion + */ class MITKFORMS_EXPORT CheckboxesQuestion : public QuestionWithOtherOption { public: ~CheckboxesQuestion() override; std::string GetType() const override; Question* CreateAnother() const override; void FromJSON(const nlohmann::ordered_json& j) override; void ToJSON(nlohmann::ordered_json& j) const override; using QuestionWithOptions::AddResponse; using QuestionWithOptions::RemoveResponse; using QuestionWithOtherOption::AddOtherResponse; using QuestionWithOtherOption::RemoveOtherResponse; }; MITKFORMS_EXPORT void from_json(const nlohmann::ordered_json& j, CheckboxesQuestion& q); MITKFORMS_EXPORT void to_json(nlohmann::ordered_json& j, const CheckboxesQuestion& q); } #endif diff --git a/Modules/Forms/include/mitkDropdownQuestion.h b/Modules/Forms/include/mitkDropdownQuestion.h index bcd4f61d54..ac93d62b3b 100644 --- a/Modules/Forms/include/mitkDropdownQuestion.h +++ b/Modules/Forms/include/mitkDropdownQuestion.h @@ -1,38 +1,44 @@ /*============================================================================ The Medical Imaging Interaction Toolkit (MITK) Copyright (c) German Cancer Research Center (DKFZ) All rights reserved. Use of this source code is governed by a 3-clause BSD license that can be found in the LICENSE file. ============================================================================*/ #ifndef mitkDropdownQuestion_h #define mitkDropdownQuestion_h #include namespace mitk::Forms { + /** \brief A Question whose possible responses are represented by a combo box. + * + * The question can have a single response. + * + * \sa MultipleChoiceQuestion, CheckboxesQuestion + */ class MITKFORMS_EXPORT DropdownQuestion : public QuestionWithOptions { public: ~DropdownQuestion() override; std::string GetType() const override; Question* CreateAnother() const override; void FromJSON(const nlohmann::ordered_json& j) override; void ToJSON(nlohmann::ordered_json& j) const override; using QuestionWithOptions::SetResponse; }; MITKFORMS_EXPORT void from_json(const nlohmann::ordered_json& j, DropdownQuestion& q); MITKFORMS_EXPORT void to_json(nlohmann::ordered_json& j, const DropdownQuestion& q); } #endif diff --git a/Modules/Forms/include/mitkForm.h b/Modules/Forms/include/mitkForm.h index de947ede9e..2d9712779c 100644 --- a/Modules/Forms/include/mitkForm.h +++ b/Modules/Forms/include/mitkForm.h @@ -1,87 +1,93 @@ /*============================================================================ The Medical Imaging Interaction Toolkit (MITK) Copyright (c) German Cancer Research Center (DKFZ) All rights reserved. Use of this source code is governed by a 3-clause BSD license that can be found in the LICENSE file. ============================================================================*/ #ifndef mitkForm_h #define mitkForm_h #include #include #include #include #include #include namespace mitk::Forms { class Question; + /** A form consisting of questions possibly divided into multiple sections/pages. + * + * A form always has at least a single section, which is also used to define the form's general + * title and description. Helper methods like SetTitle() or SetDescription() can be used to + * conveniently set these properties of the first section. + */ class MITKFORMS_EXPORT Form { public: class MITKFORMS_EXPORT Section { public: explicit Section(const std::string& title = "", const std::string& description = ""); ~Section(); Section(Section&& other) noexcept; Section& operator=(Section&& other) noexcept; std::string GetTitle() const; void SetTitle(const std::string& title); std::string GetDescription() const; void SetDescription(const std::string& description); std::vector GetQuestions() const; void AddQuestion(Question* question); private: std::string m_Title; std::string m_Description; std::vector> m_Questions; }; explicit Form(const std::string& title = "", const std::string& description = ""); ~Form(); Form(Form&& other) noexcept; Form& operator=(Form&& other) noexcept; Section& AddSection(const std::string& title = "", const std::string& description = ""); int GetNumberOfSections() const; Section& GetSection(int index); const Section& GetSection(int index) const; std::string GetTitle() const; void SetTitle(const std::string& title); std::string GetDescription() const; void SetDescription(const std::string& description); std::vector GetQuestions() const; void AddQuestion(Question* question); void Submit(const fs::path& csvPath) const; private: std::vector
m_Sections; }; MITKFORMS_EXPORT void from_json(const nlohmann::ordered_json& j, Form& f); MITKFORMS_EXPORT void to_json(nlohmann::ordered_json& j, const Form& f); } #endif diff --git a/Modules/Forms/include/mitkIQuestionFactory.h b/Modules/Forms/include/mitkIQuestionFactory.h index 7ba8ac78ae..6dcd8fffa6 100644 --- a/Modules/Forms/include/mitkIQuestionFactory.h +++ b/Modules/Forms/include/mitkIQuestionFactory.h @@ -1,39 +1,61 @@ /*============================================================================ The Medical Imaging Interaction Toolkit (MITK) Copyright (c) German Cancer Research Center (DKFZ) All rights reserved. Use of this source code is governed by a 3-clause BSD license that can be found in the LICENSE file. ============================================================================*/ #ifndef mitkIQuestionFactory_h #define mitkIQuestionFactory_h #include #include #include namespace mitk::Forms { class Question; + /** \brief Register subclasses of Question to create instances of them based on their type string. + * + * This is a service interface. Obtain a pointer to its single instance via GetInstance(). + * + * Each Question subclass must be registered by calling Register(), which is typically done + * in the module activator class. After Question subclasses are registered, instances of them + * can be created with Create() based on their type string. This mechanism is primarily used + * for the deserialization of questions. + */ class MITKFORMS_EXPORT IQuestionFactory { public: + /** \brief Obtain a pointer to the single instance of this service. + */ static IQuestionFactory* GetInstance(); virtual ~IQuestionFactory(); + /** \brief Register a Question subclass for the instance creation based on its type string. + * + * The service takes over ownership of the passed Question pointer. + * + * \sa Question::GetType() + */ virtual void Register(Question* question) = 0; + + /** \brief Create an instance of a Question subclass based on its type string. + * + * \sa Question::GetType(), Question::CreateAnother() + */ virtual Question* Create(const std::string& type) const = 0; }; } MITK_DECLARE_SERVICE_INTERFACE(mitk::Forms::IQuestionFactory, "org.mitk.Forms.IQuestionFactory") #endif diff --git a/Modules/Forms/include/mitkLinearScaleQuestion.h b/Modules/Forms/include/mitkLinearScaleQuestion.h index 87b8a84767..c5b01cdce3 100644 --- a/Modules/Forms/include/mitkLinearScaleQuestion.h +++ b/Modules/Forms/include/mitkLinearScaleQuestion.h @@ -1,58 +1,72 @@ /*============================================================================ The Medical Imaging Interaction Toolkit (MITK) Copyright (c) German Cancer Research Center (DKFZ) All rights reserved. Use of this source code is governed by a 3-clause BSD license that can be found in the LICENSE file. ============================================================================*/ #ifndef mitkLinearScaleQuestion_h #define mitkLinearScaleQuestion_h #include #include #include namespace mitk::Forms { + /** \brief A Question whose possible responses are represented by a discrete linear scale. + * + * The question can have a single response, which is one of the numbers within the allowed + * range. The range must start with 0 or 1 and end with any number between 2 and 10 (1 to 5 + * by default). + */ class MITKFORMS_EXPORT LinearScaleQuestion : public Question { public: LinearScaleQuestion(); ~LinearScaleQuestion() override; std::string GetType() const override; Question* CreateAnother() const override; void FromJSON(const nlohmann::ordered_json& j) override; void ToJSON(nlohmann::ordered_json& j) const override; std::vector GetResponsesAsStrings() const override; void ClearResponses() override; bool IsComplete() const override; std::optional GetResponse() const; void SetResponse(int response); std::pair GetRange() const; + + /** \brief Set the allowed range of numbers for a valid response. + * + * A valid range must start with 0 or 1 and end with any number between 2 and 10 (1 to 5 + * by default). + * + * \exception Exception Invalid range. + */ void SetRange(const std::pair& range); std::pair GetRangeLabels() const; void SetRangeLabels(const std::pair& labels); private: std::optional m_Response; std::pair m_Range; std::pair m_Labels; }; MITKFORMS_EXPORT void from_json(const nlohmann::ordered_json& j, LinearScaleQuestion& q); MITKFORMS_EXPORT void to_json(nlohmann::ordered_json& j, const LinearScaleQuestion& q); } #endif diff --git a/Modules/Forms/include/mitkMultipleChoiceQuestion.h b/Modules/Forms/include/mitkMultipleChoiceQuestion.h index 90100ef835..9ff48b749f 100644 --- a/Modules/Forms/include/mitkMultipleChoiceQuestion.h +++ b/Modules/Forms/include/mitkMultipleChoiceQuestion.h @@ -1,39 +1,45 @@ /*============================================================================ The Medical Imaging Interaction Toolkit (MITK) Copyright (c) German Cancer Research Center (DKFZ) All rights reserved. Use of this source code is governed by a 3-clause BSD license that can be found in the LICENSE file. ============================================================================*/ #ifndef mitkMultipleChoiceQuestion_h #define mitkMultipleChoiceQuestion_h #include namespace mitk::Forms { + /** \brief A Question whose possible responses are represented by radio buttons. + * + * The question can have a single response, which can optionally be free text. + * + * \sa CheckboxesQuestion, DropdownQuestion + */ class MITKFORMS_EXPORT MultipleChoiceQuestion : public QuestionWithOtherOption { public: ~MultipleChoiceQuestion() override; std::string GetType() const override; Question* CreateAnother() const override; void FromJSON(const nlohmann::ordered_json& j) override; void ToJSON(nlohmann::ordered_json& j) const override; using QuestionWithOptions::SetResponse; using QuestionWithOtherOption::SetOtherResponse; }; MITKFORMS_EXPORT void from_json(const nlohmann::ordered_json& j, MultipleChoiceQuestion& q); MITKFORMS_EXPORT void to_json(nlohmann::ordered_json& j, const MultipleChoiceQuestion& q); } #endif diff --git a/Modules/Forms/include/mitkParagraphQuestion.h b/Modules/Forms/include/mitkParagraphQuestion.h index 700b6a1e6e..68574c8a0d 100644 --- a/Modules/Forms/include/mitkParagraphQuestion.h +++ b/Modules/Forms/include/mitkParagraphQuestion.h @@ -1,36 +1,40 @@ /*============================================================================ The Medical Imaging Interaction Toolkit (MITK) Copyright (c) German Cancer Research Center (DKFZ) All rights reserved. Use of this source code is governed by a 3-clause BSD license that can be found in the LICENSE file. ============================================================================*/ #ifndef mitkParagraphQuestion_h #define mitkParagraphQuestion_h #include namespace mitk::Forms { + /** \brief A Question whose possible response is free text. + * + * \sa ShortAnswerQuestion + */ class MITKFORMS_EXPORT ParagraphQuestion : public TextQuestion { public: ~ParagraphQuestion() override; std::string GetType() const override; Question* CreateAnother() const override; void FromJSON(const nlohmann::ordered_json& j) override; void ToJSON(nlohmann::ordered_json& j) const override; }; MITKFORMS_EXPORT void from_json(const nlohmann::ordered_json& j, ParagraphQuestion& q); MITKFORMS_EXPORT void to_json(nlohmann::ordered_json& j, const ParagraphQuestion& q); } #endif diff --git a/Modules/Forms/include/mitkShortAnswerQuestion.h b/Modules/Forms/include/mitkShortAnswerQuestion.h index cd3c79a9c5..4d90af707e 100644 --- a/Modules/Forms/include/mitkShortAnswerQuestion.h +++ b/Modules/Forms/include/mitkShortAnswerQuestion.h @@ -1,36 +1,40 @@ /*============================================================================ The Medical Imaging Interaction Toolkit (MITK) Copyright (c) German Cancer Research Center (DKFZ) All rights reserved. Use of this source code is governed by a 3-clause BSD license that can be found in the LICENSE file. ============================================================================*/ #ifndef mitkShortAnswerQuestion_h #define mitkShortAnswerQuestion_h #include namespace mitk::Forms { + /** \brief A Question whose possible response is a short single-line free text. + * + * \sa ParagraphQuestion + */ class MITKFORMS_EXPORT ShortAnswerQuestion : public TextQuestion { public: ~ShortAnswerQuestion() override; std::string GetType() const override; Question* CreateAnother() const override; void FromJSON(const nlohmann::ordered_json& j) override; void ToJSON(nlohmann::ordered_json& j) const override; }; MITKFORMS_EXPORT void from_json(const nlohmann::ordered_json& j, ShortAnswerQuestion& q); MITKFORMS_EXPORT void to_json(nlohmann::ordered_json& j, const ShortAnswerQuestion& q); } #endif