src/layout.h

   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 <qlist.h>
  23 #include "types.h"
  24
  25 class LayoutParser;
  26 class MemberList;
  27 class QTextStream;
  28
  29 /** @brief Base class representing a piece of a documentation page */
  30 struct LayoutDocEntry
  31 {
  32   virtual ~LayoutDocEntry() {}
  33   enum Kind {
  34               // Generic items for all pages
  35               MemberGroups,
  36               MemberDeclStart, MemberDeclEnd, MemberDecl,
  37               MemberDefStart, MemberDefEnd, MemberDef,
  38               BriefDesc, DetailedDesc,
  39               AuthorSection,
  40
  41               // Class specific items
  42               ClassIncludes, ClassInlineClasses,
  43               ClassInheritanceGraph, ClassNestedClasses,
  44               ClassCollaborationGraph, ClassAllMembersLink,
  45               ClassUsedFiles,
  46
  47               // Namespace specific items
  48               NamespaceNestedNamespaces, NamespaceNestedConstantGroups,
  49               NamespaceClasses, NamespaceInterfaces, NamespaceStructs, NamespaceExceptions,
  50               NamespaceInlineClasses,
  51
  52               // File specific items
  53               FileClasses, FileInterfaces, FileStructs, FileExceptions, FileConstantGroups, FileNamespaces,
  54               FileIncludes, FileIncludeGraph,
  55               FileIncludedByGraph, FileSourceLink,
  56               FileInlineClasses,
  57
  58               // Group specific items
  59               GroupClasses, GroupInlineClasses, GroupNamespaces,
  60               GroupDirs, GroupNestedGroups, GroupFiles,
  61               GroupGraph, GroupPageDocs,
  62
  63               // Directory specific items
  64               DirSubDirs, DirFiles, DirGraph
  65
  66             };
  67   virtual Kind kind() const = 0;
  68 };
  69
  70 /** @brief Represents of a piece of a documentation page without configurable parts */
  71 struct LayoutDocEntrySimple : LayoutDocEntry
  72 {
  73   public:
  74     LayoutDocEntrySimple(Kind k) : m_kind(k) {}
  75     Kind kind() const { return m_kind; }
  76   private:
  77     Kind m_kind;
  78 };
  79
  80 struct LayoutDocEntrySection: public LayoutDocEntrySimple
  81 {
  82   LayoutDocEntrySection(Kind k,const QCString &tl) :
  83     LayoutDocEntrySimple(k), m_title(tl) {}
  84   QCString title(SrcLangExt lang) const;
  85 private:
  86   QCString m_title;
  87 };
  88
  89 /** @brief Represents of a member declaration list with configurable title and subtitle. */
  90 struct LayoutDocEntryMemberDecl: public LayoutDocEntry
  91 {
  92   LayoutDocEntryMemberDecl(MemberListType tp,
  93                            const QCString &tl,const QCString &ss)
  94     : type(tp), m_title(tl), m_subscript(ss) {}
  95
  96   Kind kind() const { return MemberDecl; }
  97   MemberListType type;
  98   QCString title(SrcLangExt lang) const;
  99   QCString subtitle(SrcLangExt lang) const;
 100 private:
 101   QCString m_title;
 102   QCString m_subscript;
 103 };
 104
 105 /** @brief Represents of a member definition list with configurable title. */
 106 struct LayoutDocEntryMemberDef: public LayoutDocEntry
 107 {
 108   LayoutDocEntryMemberDef(MemberListType tp,const QCString &tl)
 109     : type(tp), m_title(tl) {}
 110
 111   Kind kind() const { return MemberDef; }
 112   MemberListType type;
 113   QCString title(SrcLangExt lang) const;
 114 private:
 115   QCString m_title;
 116 };
 117
 118 /** @brief Base class for the layout of a navigation item at the top of the HTML pages. */
 119 struct LayoutNavEntry
 120 {
 121   public:
 122     enum Kind {
 123       None = -1,
 124       MainPage,
 125       Pages,
 126       Modules,
 127       Namespaces,
 128       NamespaceList,
 129       NamespaceMembers,
 130       Classes,
 131       ClassList,
 132       ClassIndex,
 133       ClassHierarchy,
 134       ClassMembers,
 135       Interfaces,
 136       InterfaceList,
 137       InterfaceIndex,
 138       InterfaceHierarchy,
 139       Structs,
 140       StructList,
 141       StructIndex,
 142       Exceptions,
 143       ExceptionList,
 144       ExceptionIndex,
 145       ExceptionHierarchy,
 146       Files,
 147       FileList,
 148       FileGlobals,
 149       Examples,
 150       User,
 151       UserGroup
 152     };
 153     LayoutNavEntry(LayoutNavEntry *parent,Kind k,bool vs,const QCString &bf,
 154                    const QCString &tl,const QCString &intro,bool prepend=FALSE)
 155       : m_parent(parent), m_kind(k), m_visible(vs), m_baseFile(bf), m_title(tl), m_intro(intro)
 156     { m_children.setAutoDelete(TRUE);
 157       if (parent) { if (prepend) parent->prependChild(this); else parent->addChild(this); }
 158     }
 159     LayoutNavEntry *parent() const   { return m_parent; }
 160     Kind kind() const                { return m_kind; }
 161     QCString baseFile() const        { return m_baseFile; }
 162     QCString title() const           { return m_title; }
 163     QCString intro() const           { return m_intro; }
 164     QCString url() const;
 165     bool visible()                   { return m_visible; }
 166     void clear()                     { m_children.clear(); }
 167     void addChild(LayoutNavEntry *e) { m_children.append(e); }
 168     void prependChild(LayoutNavEntry *e) { m_children.prepend(e); }
 169     const QList<LayoutNavEntry> &children() const { return m_children; }
 170     LayoutNavEntry *find(LayoutNavEntry::Kind k,const char *file=0) const;
 171
 172   private:
 173     LayoutNavEntry() : m_parent(0), m_kind(None), m_visible(FALSE) {}
 174     LayoutNavEntry *m_parent;
 175     Kind m_kind;
 176     bool m_visible;
 177     QCString m_baseFile;
 178     QCString m_title;
 179     QCString m_intro;
 180     QList<LayoutNavEntry> m_children;
 181     friend class LayoutDocManager;
 182 };
 183
 184 /** @brief Singleton providing access to the (user configurable) layout of the documentation */
 185 class LayoutDocManager
 186 {
 187     class Private;
 188   public:
 189     enum LayoutPart
 190     {
 191       Class, Namespace, File, Group, Directory,
 192       NrParts
 193     };
 194     /** Returns a reference to this singleton. */
 195     static LayoutDocManager &instance();
 196
 197     /** Returns the list of LayoutDocEntry's in representation order for a given page identified by @a part. */
 198     const QList<LayoutDocEntry> &docEntries(LayoutPart part) const;
 199
 200     /** returns the (invisible) root of the navigation tree. */
 201     LayoutNavEntry *rootNavEntry() const;
 202
 203     /** Parses a user provided layout */
 204     void parse(QTextStream &t,const char *fileName);
 205     void init();
 206   private:
 207     void addEntry(LayoutPart p,LayoutDocEntry*e);
 208     void clear(LayoutPart p);
 209     LayoutDocManager();
 210     ~LayoutDocManager();
 211     Private *d;
 212     friend class LayoutParser;
 213 };
 214
 215 void writeDefaultLayoutFile(const char *fileName);
 216
 217 #endif
 218