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