3 * This source code is part of
7 * GROningen MAchine for Chemical Simulations
9 * Written by David van der Spoel, Erik Lindahl, Berk Hess, and others.
10 * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
11 * Copyright (c) 2001-2009, The GROMACS development team,
12 * check out http://www.gromacs.org for more information.
14 * This program is free software; you can redistribute it and/or
15 * modify it under the terms of the GNU General Public License
16 * as published by the Free Software Foundation; either version 2
17 * of the License, or (at your option) any later version.
19 * If you want to redistribute modifications, please consider that
20 * scientific software is very special. Version control is crucial -
21 * bugs must be traceable. We will be happy to consider code for
22 * inclusion in the official distribution, but derived work must not
23 * be called official GROMACS. Details are found in the README & COPYING
24 * files - if they are missing, get the official version at www.gromacs.org.
26 * To help us fund GROMACS development, we humbly ask that you cite
27 * the papers on the package - you can find them in the top README file.
29 * For more info, check our website at http://www.gromacs.org
31 /*! \libinternal \file
33 * Declares helper classes and functions for implementing
34 * gmx::HelpTopicInterface.
36 * \author Teemu Murtola <teemu.murtola@cbr.su.se>
38 * \ingroup module_onlinehelp
40 #ifndef GMX_ONLINEHELP_HELPTOPIC_H
41 #define GMX_ONLINEHELP_HELPTOPIC_H
43 #include "../utility/format.h"
44 #include "../utility/uniqueptr.h"
46 #include "helptopicinterface.h"
52 /*! \libinternal \brief
53 * Helper for writing simple help text.
55 * \param file File to write the help to.
56 * \param[in] topic Topic to write the help for (used for title).
57 * \param[in] text Text to write for the topic.
59 * Formats basic help by writing a title (obtained from \p topic), followed by
60 * \p text with markup substituted and lines properly wrapped.
64 void writeBasicHelpTopic(File *file, const HelpTopicInterface &topic,
65 const std::string &text);
68 /*! \libinternal \brief
69 * Abstract base class for help topics that have simple text and no subtopics.
71 * This class implements subtopic-related methods from HelpTopicInterface such
72 * that there are no subtopics. writeHelp() is also implemented such that it
73 * uses writeBasicHelpTopic() to write out the text returned by a new virtual
76 * \see SimpleHelpTopic
79 * \ingroup module_onlinehelp
81 class AbstractSimpleHelpTopic : public HelpTopicInterface
84 virtual const char *name() const = 0;
85 virtual const char *title() const = 0;
87 virtual bool hasSubTopics() const;
88 virtual const HelpTopicInterface *findSubTopic(const char *name) const;
90 virtual void writeHelp(File *file) const;
94 * Returns the help text for this topic.
96 * writeHelp() calls this method to obtain the actual text to format
97 * for the topic. Markup substitution etc. is done automatically by
100 virtual std::string helpText() const = 0;
103 /*! \libinternal \brief
104 * Abstract base class for help topics that have simple text and subtopics.
106 * This class implements an internal container for subtopics and provides
107 * public methods for adding subtopics (as HelpTopicInterface objects).
108 * Subtopic-related methods from HelpTopicInterface are implemented to access
109 * the internal container. writeHelp() is also implemented such that it
110 * uses writeBasicHelpTopic() to write out the text returned by a new virtual
111 * method helpText(), and a list of subtopics is written after the actual text.
113 * \see CompositeHelpTopic
116 * \ingroup module_onlinehelp
118 class AbstractCompositeHelpTopic : public HelpTopicInterface
121 AbstractCompositeHelpTopic();
122 virtual ~AbstractCompositeHelpTopic();
124 virtual const char *name() const = 0;
125 virtual const char *title() const = 0;
127 virtual bool hasSubTopics() const;
128 virtual const HelpTopicInterface *findSubTopic(const char *name) const;
130 virtual void writeHelp(File *file) const;
133 * Adds a given topic as a subtopic of this topic.
135 * \param topic Topis to add.
136 * \throws std::bad_alloc if out of memory.
138 * This topic takes ownership of the object.
140 * \see registerSubTopic()
142 void addSubTopic(HelpTopicPointer topic);
144 * Registers a subtopic of a certain type to this topic.
146 * \tparam Topic Type of topic to register.
147 * \throws std::bad_alloc if out of memory.
149 * \p Topic must be default-constructible and implement
150 * HelpTopicInterface.
152 * This method is provided as a convenient alternative to addSubTopic()
153 * for cases where each topic is implemented by a different type
154 * (which is a common case outside unit tests).
156 template <class Topic>
157 void registerSubTopic()
159 addSubTopic(HelpTopicPointer(new Topic));
163 //! \copydoc AbstractSimpleHelpTopic::helpText()
164 virtual std::string helpText() const = 0;
167 * Writes the list of subtopics.
169 * \param file File to write the list to.
170 * \param[in] title Title for the written list.
171 * \returns true if anything was printed.
173 * Subtopics with empty titles are skipped from the list.
174 * If there would be no subtopics in the list, \p title is not printed
177 * This method is provided for cases where helpText() does not provide
178 * the needed flexibility and the derived class needs to override
179 * writeHelp(). This method can then be called to print the same
180 * subtopic list that is printed by the default writeHelp()
183 bool writeSubTopicList(File *file, const std::string &title) const;
188 PrivateImplPointer<Impl> impl_;
192 /*! \libinternal \brief
193 * Smart pointer type to manage a AbstractCompositeHelpTopic object.
197 typedef gmx_unique_ptr<AbstractCompositeHelpTopic>::type
198 CompositeHelpTopicPointer;
201 /*! \libinternal \brief
202 * Template for simple implementation of AbstractSimpleHelpTopic.
204 * \tparam HelpText Struct that defines the data for the topic.
206 * \p HelpText should have public static members \c "const char name[]",
207 * \c "const char title[]" and \c "const char *const text[]".
211 struct ExampleHelpText
213 static const char name[];
214 static const char title[];
215 static const char *const text[];
218 const char ExampleHelpText::name[] = "example";
219 const char ExampleHelpText::title[] =
221 const char *const ExampleHelpText::text[] = {
222 "Text for the topic.",
223 "More text for the topic."
226 typedef SimpleHelpTopic<ExampleHelpText> ExampleHelpTopic;
230 * \ingroup module_onlinehelp
232 template <class HelpText>
233 class SimpleHelpTopic : public AbstractSimpleHelpTopic
236 virtual const char *name() const
238 return HelpText::name;
240 virtual const char *title() const
242 return HelpText::title;
246 virtual std::string helpText() const
248 return concatenateStrings(HelpText::text);
252 /*! \libinternal \brief
253 * Template for simple implementation of AbstractCompositeHelpTopic.
255 * \tparam HelpText Struct that defines the data for the topic.
257 * Used similarly to SimpleHelpTopic.
258 * \p HelpText should satisfy the same criteria as for SimpleHelpTopic.
260 * \see SimpleHelpTopic
263 * \ingroup module_onlinehelp
265 template <class HelpText>
266 class CompositeHelpTopic : public AbstractCompositeHelpTopic
269 virtual const char *name() const
271 return HelpText::name;
273 virtual const char *title() const
275 return HelpText::title;
279 virtual std::string helpText() const
281 return concatenateStrings(HelpText::text);