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