2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 2012,2014,2015,2018,2019,2021, by the GROMACS development team, led by
5 * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
6 * and including many others, as listed in the AUTHORS file in the
7 * top-level source directory and at http://www.gromacs.org.
9 * GROMACS is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU Lesser General Public License
11 * as published by the Free Software Foundation; either version 2.1
12 * of the License, or (at your option) any later version.
14 * GROMACS is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * Lesser General Public License for more details.
19 * You should have received a copy of the GNU Lesser General Public
20 * License along with GROMACS; if not, see
21 * http://www.gnu.org/licenses, or write to the Free Software Foundation,
22 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
24 * If you want to redistribute modifications to GROMACS, please
25 * consider that scientific software is very special. Version
26 * control is crucial - bugs must be traceable. We will be happy to
27 * consider code for inclusion in the official distribution, but
28 * derived work must not be called official GROMACS. Details are found
29 * in the README & COPYING files - if they are missing, get the
30 * official version at http://www.gromacs.org.
32 * To help us fund GROMACS development, we humbly ask that you cite
33 * the research papers on the package. Check out http://www.gromacs.org.
35 /*! \libinternal \file
37 * Declares helper classes for implementing gmx::IHelpTopic.
39 * \author Teemu Murtola <teemu.murtola@gmail.com>
41 * \ingroup module_onlinehelp
43 #ifndef GMX_ONLINEHELP_HELPTOPIC_H
44 #define GMX_ONLINEHELP_HELPTOPIC_H
48 #include "gromacs/onlinehelp/ihelptopic.h"
49 #include "gromacs/utility/stringutil.h"
54 /*! \libinternal \brief
55 * Abstract base class for help topics that have simple text and no subtopics.
57 * This class implements subtopic-related methods from IHelpTopic such
58 * that there are no subtopics. writeHelp() is also implemented such that it
59 * uses HelpTopicContext::writeTextBlock() to write out the text returned by a
60 * new virtual method helpText().
62 * \see SimpleHelpTopic
65 * \ingroup module_onlinehelp
67 class AbstractSimpleHelpTopic : public IHelpTopic
70 const char* name() const override = 0;
71 const char* title() const override = 0;
73 bool hasSubTopics() const override;
74 const IHelpTopic* findSubTopic(const char* name) const override;
76 void writeHelp(const HelpWriterContext& context) const override;
80 * Returns the help text for this topic.
82 * writeHelp() calls this method to obtain the actual text to format
83 * for the topic. Markup substitution etc. is done automatically by
86 virtual std::string helpText() const = 0;
89 /*! \libinternal \brief
90 * Abstract base class for help topics that have simple text and subtopics.
92 * This class implements an internal container for subtopics and provides
93 * public methods for adding subtopics (as IHelpTopic objects).
94 * Subtopic-related methods from IHelpTopic are implemented to access
95 * the internal container. writeHelp() is also implemented such that it
96 * uses HelpTopicContext::writeTextBlock() to write out the text returned by a
97 * new virtual method helpText(), and a list of subtopics is written after the
100 * \see CompositeHelpTopic
103 * \ingroup module_onlinehelp
105 class AbstractCompositeHelpTopic : public IHelpTopic
108 AbstractCompositeHelpTopic();
109 ~AbstractCompositeHelpTopic() override;
111 const char* name() const override = 0;
112 const char* title() const override = 0;
114 bool hasSubTopics() const override;
115 const IHelpTopic* findSubTopic(const char* name) const override;
117 void writeHelp(const HelpWriterContext& context) const override;
120 * Adds a given topic as a subtopic of this topic.
122 * \param topic Topis to add.
123 * \throws std::bad_alloc if out of memory.
125 * This topic takes ownership of the object.
127 * \see registerSubTopic()
129 void addSubTopic(HelpTopicPointer topic);
131 * Registers a subtopic of a certain type to this topic.
133 * \tparam Topic Type of topic to register.
134 * \throws std::bad_alloc if out of memory.
136 * \p Topic must be default-constructible and implement
139 * This method is provided as a convenient alternative to addSubTopic()
140 * for cases where each topic is implemented by a different type
141 * (which is a common case outside unit tests).
143 template<class Topic>
144 void registerSubTopic()
146 addSubTopic(HelpTopicPointer(new Topic));
150 //! \copydoc gmx::AbstractSimpleHelpTopic::helpText()
151 virtual std::string helpText() const = 0;
154 * Writes the list of subtopics.
156 * \param[in] context Context for writing the help.
157 * \param[in] title Title for the written list.
158 * \returns true if anything was printed.
159 * \throws std::bad_alloc if out of memory.
160 * \throws FileIOError on any I/O error.
162 * Subtopics with empty titles are skipped from the list.
163 * If there would be no subtopics in the list, \p title is not printed
166 * This method is provided for cases where helpText() does not provide
167 * the needed flexibility and the derived class needs to override
168 * writeHelp(). This method can then be called to print the same
169 * subtopic list that is printed by the default writeHelp()
172 bool writeSubTopicList(const HelpWriterContext& context, const std::string& title) const;
177 std::unique_ptr<Impl> impl_;
181 /*! \libinternal \brief
182 * Smart pointer type to manage a AbstractCompositeHelpTopic object.
186 typedef std::unique_ptr<AbstractCompositeHelpTopic> CompositeHelpTopicPointer;
189 /*! \libinternal \brief
190 * Template for simple implementation of AbstractSimpleHelpTopic.
192 * \tparam HelpText Struct that defines the data for the topic.
194 * \p HelpText should have public static members \c "const char name[]",
195 * \c "const char title[]" and \c "const char *const text[]".
199 struct ExampleHelpText
201 static const char name[];
202 static const char title[];
203 static const char *const text[];
206 const char ExampleHelpText::name[] = "example";
207 const char ExampleHelpText::title[] =
209 const char *const ExampleHelpText::text[] = {
210 "Text for the topic.",
211 "More text for the topic."
214 typedef SimpleHelpTopic<ExampleHelpText> ExampleHelpTopic;
218 * \ingroup module_onlinehelp
220 template<class HelpText>
221 class SimpleHelpTopic : public AbstractSimpleHelpTopic
224 const char* name() const override { return HelpText::name; }
225 const char* title() const override { return HelpText::title; }
228 std::string helpText() const override { return joinStrings(HelpText::text, "\n"); }
231 /*! \libinternal \brief
232 * Template for simple implementation of AbstractCompositeHelpTopic.
234 * \tparam HelpText Struct that defines the data for the topic.
236 * Used similarly to SimpleHelpTopic.
237 * \p HelpText should satisfy the same criteria as for SimpleHelpTopic.
239 * \see SimpleHelpTopic
242 * \ingroup module_onlinehelp
244 template<class HelpText>
245 class CompositeHelpTopic : public AbstractCompositeHelpTopic
248 // copydocs are needed with Doxygen 1.8.10, but not 1.8.5...
249 //! \copydoc gmx::AbstractCompositeHelpTopic::name()
250 const char* name() const override { return HelpText::name; }
251 //! \copydoc gmx::AbstractCompositeHelpTopic::title()
252 const char* title() const override { return HelpText::title; }
255 //! \copydoc gmx::AbstractCompositeHelpTopic::helpText()
256 std::string helpText() const override { return joinStrings(HelpText::text, "\n"); }