2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 2012,2014,2015, 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
46 #include "gromacs/onlinehelp/ihelptopic.h"
47 #include "gromacs/utility/classhelpers.h"
48 #include "gromacs/utility/stringutil.h"
49 #include "gromacs/utility/uniqueptr.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 virtual const char *name() const = 0;
71 virtual const char *title() const = 0;
73 virtual bool hasSubTopics() const;
74 virtual const IHelpTopic *findSubTopic(const char *name) const;
76 virtual void writeHelp(const HelpWriterContext &context) const;
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 virtual ~AbstractCompositeHelpTopic();
111 virtual const char *name() const = 0;
112 virtual const char *title() const = 0;
114 virtual bool hasSubTopics() const;
115 virtual const IHelpTopic *findSubTopic(const char *name) const;
117 virtual void writeHelp(const HelpWriterContext &context) const;
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,
173 const std::string &title) const;
178 PrivateImplPointer<Impl> impl_;
182 /*! \libinternal \brief
183 * Smart pointer type to manage a AbstractCompositeHelpTopic object.
187 typedef gmx_unique_ptr<AbstractCompositeHelpTopic>::type
188 CompositeHelpTopicPointer;
191 /*! \libinternal \brief
192 * Template for simple implementation of AbstractSimpleHelpTopic.
194 * \tparam HelpText Struct that defines the data for the topic.
196 * \p HelpText should have public static members \c "const char name[]",
197 * \c "const char title[]" and \c "const char *const text[]".
201 struct ExampleHelpText
203 static const char name[];
204 static const char title[];
205 static const char *const text[];
208 const char ExampleHelpText::name[] = "example";
209 const char ExampleHelpText::title[] =
211 const char *const ExampleHelpText::text[] = {
212 "Text for the topic.",
213 "More text for the topic."
216 typedef SimpleHelpTopic<ExampleHelpText> ExampleHelpTopic;
220 * \ingroup module_onlinehelp
222 template <class HelpText>
223 class SimpleHelpTopic : public AbstractSimpleHelpTopic
226 virtual const char *name() const
228 return HelpText::name;
230 virtual const char *title() const
232 return HelpText::title;
236 virtual std::string helpText() const
238 return joinStrings(HelpText::text, "\n");
242 /*! \libinternal \brief
243 * Template for simple implementation of AbstractCompositeHelpTopic.
245 * \tparam HelpText Struct that defines the data for the topic.
247 * Used similarly to SimpleHelpTopic.
248 * \p HelpText should satisfy the same criteria as for SimpleHelpTopic.
250 * \see SimpleHelpTopic
253 * \ingroup module_onlinehelp
255 template <class HelpText>
256 class CompositeHelpTopic : public AbstractCompositeHelpTopic
259 virtual const char *name() const
261 return HelpText::name;
263 virtual const char *title() const
265 return HelpText::title;
269 virtual std::string helpText() const
271 return joinStrings(HelpText::text, "\n");