1 /******************************************************************************

     2  *

     3  * 

     4  *

     5  *

     6  * Copyright (C) 1997-2008 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,

    42               ClassInheritanceGraph, ClassNestedClasses,

    43               ClassCollaborationGraph, ClassAllMembersLink,

    44               ClassUsedFiles,

    45 

    46               // Namespace specific items

    47               NamespaceNestedNamespaces, NamespaceClasses,

    48 

    49               // File specific items

    50               FileClasses, FileNamespaces, 

    51               FileIncludes, FileIncludeGraph, 

    52               FileIncludedByGraph, FileSourceLink,

    53 

    54               // Group specific items

    55               GroupClasses, GroupNamespaces,

    56               GroupDirs, GroupNestedGroups, GroupFiles,

    57               GroupGraph, GroupPageDocs,

    58 

    59               // Directory specific items

    60               DirSubDirs, DirFiles, DirGraph

    61 

    62             };

    63   virtual Kind kind() const = 0;

    64 };

    65 

    66 /** @brief Represents of a piece of a documentation page without configurable parts */

    67 struct LayoutDocEntrySimple : LayoutDocEntry

    68 {

    69   public:

    70     LayoutDocEntrySimple(Kind k) : m_kind(k) {}

    71     Kind kind() const { return m_kind; }

    72   private:

    73     Kind m_kind;

    74 };

    75 

    76 struct LayoutDocEntrySection: public LayoutDocEntrySimple

    77 {

    78   LayoutDocEntrySection(Kind k,const QCString &tl) :

    79     LayoutDocEntrySimple(k), title(tl) {}

    80   QCString title;

    81 };

    82 

    83 /** @brief Represents of a member declaration list with configurable title and subtitle. */

    84 struct LayoutDocEntryMemberDecl: public LayoutDocEntry

    85 {

    86   LayoutDocEntryMemberDecl(MemberList::ListType tp,

    87                            const QCString &tl,const QCString &ss) 

    88     : type(tp), title(tl),subscript(ss) {}

    89 

    90   Kind kind() const { return MemberDecl; }

    91   MemberList::ListType type;

    92   QCString title;

    93   QCString subscript;

    94 };

    95 

    96 /** @brief Represents of a member definition list with configurable title. */

    97 struct LayoutDocEntryMemberDef: public LayoutDocEntry

    98 {

    99   LayoutDocEntryMemberDef(MemberList::ListType tp,const QCString &tl) 

   100     : type(tp), title(tl) {}

   101 

   102   Kind kind() const { return MemberDef; }

   103   MemberList::ListType type;

   104   QCString title;

   105 };

   106 

   107 /** @brief Base class for the layout of a navigation item at the top of the HTML pages. */

   108 struct LayoutNavEntry 

   109 {

   110   public:

   111     enum Kind { 

   112       MainPage, 

   113       Pages,

   114       Modules, 

   115       Namespaces, 

   116       NamespaceMembers,

   117       Classes, 

   118       ClassAnnotated, 

   119       ClassHierarchy, 

   120       ClassMembers,

   121       Files, 

   122       FileGlobals,

   123       Dirs, 

   124       Examples

   125     };

   126     LayoutNavEntry(LayoutNavEntry *parent,Kind k,bool vs,const QString &bf, const QString &tl,bool prepend=FALSE) 

   127       : m_parent(parent), m_kind(k), m_visible(vs), m_baseFile(bf), m_title(tl) 

   128     { m_children.setAutoDelete(TRUE); 

   129       if (parent) { if (prepend) parent->prependChild(this); else parent->addChild(this); }

   130     }

   131     LayoutNavEntry *parent() const   { return m_parent; }

   132     Kind kind() const                { return m_kind; }

   133     QCString baseFile() const        { return m_baseFile; }

   134     QCString title() const           { return m_title; }

   135     bool visible()                   { return m_visible; }

   136     void clear()                     { m_children.clear(); }

   137     void addChild(LayoutNavEntry *e) { m_children.append(e); }

   138     void prependChild(LayoutNavEntry *e) { m_children.prepend(e); }

   139     const QList<LayoutNavEntry> &children() const { return m_children; }

   140     LayoutNavEntry *find(LayoutNavEntry::Kind k) const;

   141 

   142   private:

   143     LayoutNavEntry() : m_parent(0) {}

   144     LayoutNavEntry *m_parent;

   145     Kind m_kind;

   146     bool m_visible;

   147     QCString m_baseFile;

   148     QCString m_title;

   149     QList<LayoutNavEntry> m_children;

   150     friend class LayoutDocManager;

   151 };

   152 

   153 /** @brief Singleton providing access to the (user configurable) layout of the documentation */

   154 class LayoutDocManager

   155 {

   156     class Private;

   157   public:

   158     enum LayoutPart

   159     {

   160       Class, Namespace, File, Group, Directory,

   161       NrParts

   162     };

   163     /** Returns a reference to this singleton. */

   164     static LayoutDocManager &instance();

   165 

   166     /** Returns the list of LayoutDocEntry's in representation order for a given page identified by @a part. */

   167     const QList<LayoutDocEntry> &docEntries(LayoutPart part) const;

   168 

   169     /** returns the (invisible) root of the navigation tree. */

   170     LayoutNavEntry *rootNavEntry() const;

   171 

   172     /** Parses a user provided layout */

   173     void parse(QTextStream &t);

   174     void init();

   175   private:

   176     void addEntry(LayoutPart p,LayoutDocEntry*e);

   177     void clear(LayoutPart p);

   178     LayoutDocManager();

   179     ~LayoutDocManager();

   180     Private *d;

   181     friend class LayoutParser;

   182 };

   183 

   184 void writeDefaultLayoutFile(const char *fileName);

   185 

   186 #endif

   187