src/layout.h

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