1 /******************************************************************************
2  *
3  *
4  *
5  *
6  * Copyright (C) 1997-2015 by Dimitri van Heesch.
7  *
8  * Permission to use, copy, modify, and distribute this software and its
9  * documentation under the terms of the GNU General Public License is hereby
10  * granted. No representations are made about the suitability of this software
11  * for any purpose. It is provided "as is" without express or implied warranty.
12  * See the GNU General Public License for more details.
13  *
14  * Documents produced by Doxygen are derivative works derived from the
15  * input used in their production; they are not affected by this license.
16  *
17  */
18 
19 #ifndef LAYOUT_H
20 #define LAYOUT_H
21 
22 #include <memory>
23 #include <vector>
24 #include "types.h"
25 
26 class LayoutParser;
27 struct LayoutNavEntry;
28 class MemberList;
29 
30 /** @brief Base class representing a piece of a documentation page */
31 struct LayoutDocEntry
32 {
~LayoutDocEntryLayoutDocEntry33   virtual ~LayoutDocEntry() {}
34   enum Kind {
35               // Generic items for all pages
36               MemberGroups,
37               MemberDeclStart, MemberDeclEnd, MemberDecl,
38               MemberDefStart, MemberDefEnd, MemberDef,
39               BriefDesc, DetailedDesc,
40               AuthorSection,
41 
42               // Class specific items
43               ClassIncludes, ClassInlineClasses,
44               ClassInheritanceGraph, ClassNestedClasses,
45               ClassCollaborationGraph, ClassAllMembersLink,
46               ClassUsedFiles,
47 
48               // Concept specific items
49               ConceptDefinition,
50 
51               // Namespace specific items
52               NamespaceNestedNamespaces, NamespaceNestedConstantGroups,
53               NamespaceClasses, NamespaceConcepts, NamespaceInterfaces, NamespaceStructs, NamespaceExceptions,
54               NamespaceInlineClasses,
55 
56               // File specific items
57               FileClasses, FileConcepts, FileInterfaces, FileStructs, FileExceptions, FileConstantGroups, FileNamespaces,
58               FileIncludes, FileIncludeGraph,
59               FileIncludedByGraph, FileSourceLink,
60               FileInlineClasses,
61 
62               // Group specific items
63               GroupClasses, GroupConcepts, GroupInlineClasses, GroupNamespaces,
64               GroupDirs, GroupNestedGroups, GroupFiles,
65               GroupGraph, GroupPageDocs,
66 
67               // Directory specific items
68               DirSubDirs, DirFiles, DirGraph
69 
70             };
71   virtual Kind kind() const = 0;
72 };
73 
74 /** @brief Represents of a piece of a documentation page without configurable parts */
75 struct LayoutDocEntrySimple : LayoutDocEntry
76 {
77   public:
LayoutDocEntrySimpleLayoutDocEntrySimple78     LayoutDocEntrySimple(Kind k) : m_kind(k) {}
kindLayoutDocEntrySimple79     Kind kind() const { return m_kind; }
80   private:
81     Kind m_kind;
82 };
83 
84 struct LayoutDocEntrySection: public LayoutDocEntrySimple
85 {
LayoutDocEntrySectionLayoutDocEntrySection86   LayoutDocEntrySection(Kind k,const QCString &tl) :
87     LayoutDocEntrySimple(k), m_title(tl) {}
88   QCString title(SrcLangExt lang) const;
89 private:
90   QCString m_title;
91 };
92 
93 /** @brief Represents of a member declaration list with configurable title and subtitle. */
94 struct LayoutDocEntryMemberDecl: public LayoutDocEntry
95 {
LayoutDocEntryMemberDeclLayoutDocEntryMemberDecl96   LayoutDocEntryMemberDecl(MemberListType tp,
97                            const QCString &tl,const QCString &ss)
98     : type(tp), m_title(tl), m_subscript(ss) {}
99 
kindLayoutDocEntryMemberDecl100   Kind kind() const { return MemberDecl; }
101   MemberListType type;
102   QCString title(SrcLangExt lang) const;
103   QCString subtitle(SrcLangExt lang) const;
104 private:
105   QCString m_title;
106   QCString m_subscript;
107 };
108 
109 /** @brief Represents of a member definition list with configurable title. */
110 struct LayoutDocEntryMemberDef: public LayoutDocEntry
111 {
LayoutDocEntryMemberDefLayoutDocEntryMemberDef112   LayoutDocEntryMemberDef(MemberListType tp,const QCString &tl)
113     : type(tp), m_title(tl) {}
114 
kindLayoutDocEntryMemberDef115   Kind kind() const { return MemberDef; }
116   MemberListType type;
117   QCString title(SrcLangExt lang) const;
118 private:
119   QCString m_title;
120 };
121 
122 using LayoutNavEntryList = std::vector< std::unique_ptr<LayoutNavEntry> >;
123 
124 /** @brief Base class for the layout of a navigation item at the top of the HTML pages. */
125 struct LayoutNavEntry
126 {
127   public:
128     enum Kind {
129       None = -1,
130       MainPage,
131       Pages,
132       Modules,
133       Namespaces,
134       NamespaceList,
135       NamespaceMembers,
136       Concepts,
137       Classes,
138       ClassList,
139       ClassIndex,
140       ClassHierarchy,
141       ClassMembers,
142       Interfaces,
143       InterfaceList,
144       InterfaceIndex,
145       InterfaceHierarchy,
146       Structs,
147       StructList,
148       StructIndex,
149       Exceptions,
150       ExceptionList,
151       ExceptionIndex,
152       ExceptionHierarchy,
153       Files,
154       FileList,
155       FileGlobals,
156       Examples,
157       User,
158       UserGroup
159     };
160     LayoutNavEntry(LayoutNavEntry *parent,Kind k,bool vs,const QCString &bf,
161                    const QCString &tl,const QCString &intro,bool prepend=false)
m_parentLayoutNavEntry162       : m_parent(parent), m_kind(k), m_visible(vs), m_baseFile(bf), m_title(tl), m_intro(intro)
163     {
164       if (parent)
165       {
166         if (prepend) parent->prependChild(this); else parent->addChild(this);
167       }
168     }
parentLayoutNavEntry169     LayoutNavEntry *parent() const   { return m_parent; }
kindLayoutNavEntry170     Kind kind() const                { return m_kind; }
baseFileLayoutNavEntry171     QCString baseFile() const        { return m_baseFile; }
titleLayoutNavEntry172     QCString title() const           { return m_title; }
introLayoutNavEntry173     QCString intro() const           { return m_intro; }
174     QCString url() const;
visibleLayoutNavEntry175     bool visible()                   { return m_visible; }
clearLayoutNavEntry176     void clear()                     { m_children.clear(); }
addChildLayoutNavEntry177     void addChild(LayoutNavEntry *e) { m_children.push_back(std::unique_ptr<LayoutNavEntry>(e)); }
prependChildLayoutNavEntry178     void prependChild(LayoutNavEntry *e) { m_children.insert(m_children.begin(),std::unique_ptr<LayoutNavEntry>(e)); }
childrenLayoutNavEntry179     const LayoutNavEntryList &children() const { return m_children; }
180     LayoutNavEntry *find(LayoutNavEntry::Kind k,const QCString &file=QCString()) const;
181 
182   private:
LayoutNavEntryLayoutNavEntry183     LayoutNavEntry() : m_parent(0), m_kind(None), m_visible(true) {}
184     LayoutNavEntry *m_parent;
185     Kind m_kind;
186     bool m_visible;
187     QCString m_baseFile;
188     QCString m_title;
189     QCString m_intro;
190     LayoutNavEntryList m_children;
191     friend class LayoutDocManager;
192 };
193 
194 using LayoutDocEntryList = std::vector< std::unique_ptr<LayoutDocEntry> >;
195 
196 /** @brief Singleton providing access to the (user configurable) layout of the documentation */
197 class LayoutDocManager
198 {
199     class Private;
200   public:
201     enum LayoutPart
202     {
203       Class, Concept, Namespace, File, Group, Directory,
204       NrParts
205     };
206     /** Returns a reference to this singleton. */
207     static LayoutDocManager &instance();
208 
209     /** Returns the list of LayoutDocEntry's in representation order for a given page identified by @a part. */
210     const LayoutDocEntryList &docEntries(LayoutPart part) const;
211 
212     /** returns the (invisible) root of the navigation tree. */
213     LayoutNavEntry *rootNavEntry() const;
214 
215     /** Parses a user provided layout */
216     void parse(const QCString &fileName);
217     void init();
218   private:
219     void addEntry(LayoutPart p,LayoutDocEntry*e);
220     void clear(LayoutPart p);
221     LayoutDocManager();
222     ~LayoutDocManager();
223     std::unique_ptr<Private> d;
224     friend class LayoutParser;
225 };
226 
227 void writeDefaultLayoutFile(const QCString &fileName);
228 
229 #endif
230 
231