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

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the tools applications of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*

    43   htmlgenerator.h

    44 */

    45 

    46 #ifndef HTMLGENERATOR_H

    47 #define HTMLGENERATOR_H

    48 

    49 #define QDOC_NAME_ALIGNMENT

    50 

    51 #include <qmap.h>

    52 #include <qregexp.h>

    53 

    54 #include "codemarker.h"

    55 #include "config.h"

    56 #include "dcfsection.h"

    57 #include "pagegenerator.h"

    58 

    59 QT_BEGIN_NAMESPACE

    60 

    61 #if 0

    62 struct NavigationBar

    63 {

    64     SectionIterator prev;

    65     SectionIterator current;

    66     SectionIterator next;

    67 };

    68 #endif

    69 

    70 typedef QMultiMap<QString, Node*> NodeMultiMap;

    71 typedef QMap<QString, NodeMultiMap> NewSinceMaps;

    72 typedef QMap<Node*, NodeMultiMap> ParentMaps;

    73 typedef QMap<QString, const Node*> NodeMap;

    74 typedef QMap<QString, NodeMap> NewClassMaps;

    75 

    76 class HelpProjectWriter;

    77 

    78 class HtmlGenerator : public PageGenerator

    79 {

    80  public:

    81     enum SinceType { 

    82         Namespace, 

    83         Class, 

    84         MemberFunction,

    85         NamespaceFunction,

    86         GlobalFunction,

    87         Macro,

    88         Enum, 

    89         Typedef, 

    90         Property,

    91         Variable, 

    92         QmlProperty,

    93         QmlSignal,

    94         QmlMethod,

    95         LastSinceType

    96     };

    97 

    98  public:

    99     HtmlGenerator();

   100     ~HtmlGenerator();

   101 

   102     virtual void initializeGenerator(const Config& config);

   103     virtual void terminateGenerator();

   104     virtual QString format();

   105     virtual void generateTree(const Tree *tree, CodeMarker *marker);

   106 

   107     static QString protect(const QString& string);

   108     static QString cleanRef(const QString& ref);

   109     static QString sinceTitle(int i) { return sinceTitles[i]; }

   110 

   111  protected:

   112     virtual void startText(const Node *relative, CodeMarker *marker);

   113     virtual int generateAtom(const Atom *atom, 

   114                              const Node *relative,

   115                              CodeMarker *marker);

   116     virtual void generateClassLikeNode(const InnerNode *inner, CodeMarker *marker);

   117     virtual void generateFakeNode(const FakeNode *fake, CodeMarker *marker);

   118     virtual QString fileExtension(const Node *node);

   119     virtual QString refForNode(const Node *node);

   120     virtual QString linkForNode(const Node *node, const Node *relative);

   121     virtual QString refForAtom(Atom *atom, const Node *node);

   122 

   123  private:

   124     enum SubTitleSize { SmallSubTitle, LargeSubTitle };

   125 

   126     const QPair<QString,QString> anchorForNode(const Node *node);

   127     const Node *findNodeForTarget(const QString &target, 

   128                                   const Node *relative,

   129                                   CodeMarker *marker, 

   130                                   const Atom *atom = 0);

   131     void generateHeader(const QString& title, const Node *node = 0,

   132                         CodeMarker *marker = 0, bool mainPage = true);

   133     void generateTitle(const QString& title, 

   134                        const Text &subTitle, 

   135                        SubTitleSize subTitleSize,

   136                        const Node *relative, 

   137                        CodeMarker *marker);

   138     void generateFooter(const Node *node = 0);

   139     void generateBrief(const Node *node, 

   140                        CodeMarker *marker,

   141                        const Node *relative = 0);

   142     void generateIncludes(const InnerNode *inner, CodeMarker *marker);

   143 #if 0

   144     void generateNavigationBar(const NavigationBar& bar, 

   145                                const Node *node,

   146                                CodeMarker *marker);

   147 #endif

   148     void generateTableOfContents(const Node *node, 

   149                                  CodeMarker *marker,

   150                                  Doc::SectioningUnit sectioningUnit,

   151                                  int numColumns, 

   152                                  const Node *relative = 0);

   153     QString generateListOfAllMemberFile(const InnerNode *inner, CodeMarker *marker);

   154     QString generateLowStatusMemberFile(const InnerNode *inner, 

   155                                         CodeMarker *marker,

   156                                         CodeMarker::Status status);

   157     void generateClassHierarchy(const Node *relative, 

   158                                 CodeMarker *marker,

   159 				const NodeMap &classMap);

   160     void generateAnnotatedList(const Node *relative, 

   161                                CodeMarker *marker,

   162 			       const NodeMap &nodeMap);

   163     void generateCompactList(const Node *relative, 

   164                              CodeMarker *marker,

   165 			     const NodeMap &classMap,

   166                              QString commonPrefix = QString());

   167     void generateFunctionIndex(const Node *relative, CodeMarker *marker);

   168     void generateLegaleseList(const Node *relative, CodeMarker *marker);

   169     void generateOverviewList(const Node *relative, CodeMarker *marker);

   170     void generateSectionList(const Section& section, 

   171                              const Node *relative,

   172 			     CodeMarker *marker, 

   173                              CodeMarker::SynopsisStyle style);

   174 #ifdef QDOC_QML

   175     void generateQmlSummary(const Section& section,

   176                             const Node *relative,

   177                             CodeMarker *marker);

   178     void generateQmlItem(const Node *node,

   179                          const Node *relative,

   180                          CodeMarker *marker,

   181                          bool summary);

   182     void generateDetailedQmlMember(const Node *node,

   183                                    const InnerNode *relative,

   184                                    CodeMarker *marker);

   185     void generateQmlInherits(const QmlClassNode* cn, CodeMarker* marker);

   186     void generateQmlInstantiates(const QmlClassNode* qcn, CodeMarker* marker);

   187     void generateInstantiatedBy(const ClassNode* cn, CodeMarker* marker);

   188 #endif

   189 #ifdef QDOC_NAME_ALIGNMENT

   190     void generateSection(const NodeList& nl,

   191                          const Node *relative,

   192                          CodeMarker *marker,

   193                          CodeMarker::SynopsisStyle style);

   194     void generateSynopsis(const Node *node, 

   195                           const Node *relative, 

   196                           CodeMarker *marker,

   197 			  CodeMarker::SynopsisStyle style,

   198                           bool nameAlignment = false);

   199     void generateSectionInheritedList(const Section& section, 

   200                                       const Node *relative,

   201                                       CodeMarker *marker,

   202                                       bool nameAlignment = false);

   203     QString highlightedCode(const QString& markedCode, 

   204                             CodeMarker *marker, 

   205                             const Node *relative,

   206                             CodeMarker::SynopsisStyle style = CodeMarker::Accessors,

   207                             bool nameAlignment = false);

   208 #else

   209     void generateSynopsis(const Node *node, 

   210                           const Node *relative, 

   211                           CodeMarker *marker,

   212 			  CodeMarker::SynopsisStyle style);

   213     void generateSectionInheritedList(const Section& section, 

   214                                       const Node *relative,

   215                                       CodeMarker *marker);

   216     QString highlightedCode(const QString& markedCode, 

   217                             CodeMarker *marker, 

   218                             const Node *relative);

   219 #endif

   220     void generateFullName(const Node *apparentNode, 

   221                           const Node *relative, 

   222                           CodeMarker *marker,

   223 			  const Node *actualNode = 0);

   224     void generateDetailedMember(const Node *node, 

   225                                 const InnerNode *relative, 

   226                                 CodeMarker *marker);

   227     void generateLink(const Atom *atom, 

   228                       const Node *relative, 

   229                       CodeMarker *marker);

   230     void generateStatus(const Node *node, CodeMarker *marker);

   231     

   232     QString registerRef(const QString& ref);

   233     QString fileBase(const Node *node);

   234 #if 0

   235     QString fileBase(const Node *node, const SectionIterator& section);

   236 #endif

   237     QString fileName(const Node *node);

   238     void findAllClasses(const InnerNode *node);

   239     void findAllFunctions(const InnerNode *node);

   240     void findAllLegaleseTexts(const InnerNode *node);

   241     void findAllNamespaces(const InnerNode *node);

   242 #ifdef ZZZ_QDOC_QML    

   243     void findAllQmlClasses(const InnerNode *node);

   244 #endif

   245     void findAllSince(const InnerNode *node);

   246     static int hOffset(const Node *node);

   247     static bool isThreeColumnEnumValueTable(const Atom *atom);

   248     virtual QString getLink(const Atom *atom, 

   249                             const Node *relative, 

   250                             CodeMarker *marker, 

   251                             const Node** node);

   252     virtual void generateDcf(const QString &fileBase, 

   253                              const QString &startPage,

   254                              const QString &title, DcfSection &dcfRoot);

   255     virtual void generateIndex(const QString &fileBase, 

   256                                const QString &url,

   257                                const QString &title);

   258     void generateMacRef(const Node *node, CodeMarker *marker);

   259     void beginLink(const QString &link, 

   260                    const Node *node, 

   261                    const Node *relative, 

   262                    CodeMarker *marker);

   263     void endLink();

   264 

   265 #if 0

   266     NavigationBar currentNavigationBar;

   267 #endif

   268     QMap<QString, QString> refMap;

   269     int codeIndent;

   270     DcfSection dcfClassesRoot;

   271     DcfSection dcfOverviewsRoot;

   272     DcfSection dcfExamplesRoot;

   273     DcfSection dcfDesignerRoot;

   274     DcfSection dcfLinguistRoot;

   275     DcfSection dcfAssistantRoot;

   276     DcfSection dcfQmakeRoot;

   277     HelpProjectWriter *helpProjectWriter;

   278     bool inLink;

   279     bool inObsoleteLink;

   280     bool inContents;

   281     bool inSectionHeading;

   282     bool inTableHeader;

   283     int numTableRows;

   284     bool threeColumnEnumValueTable;

   285     QString link;

   286     QStringList sectionNumber;

   287     QRegExp funcLeftParen;

   288     QString style;

   289     QString postHeader;

   290     QString footer;

   291     QString address;

   292     bool pleaseGenerateMacRef;

   293     QString project;

   294     QString projectDescription;

   295     QString projectUrl;

   296     QString navigationLinks;

   297     QStringList stylesheets;

   298     QStringList customHeadElements;

   299     const Tree *myTree;

   300     bool slow;

   301     bool obsoleteLinks;

   302     QMap<QString, NodeMap > moduleClassMap;

   303     QMap<QString, NodeMap > moduleNamespaceMap;

   304     NodeMap nonCompatClasses;

   305     NodeMap mainClasses;

   306     NodeMap compatClasses;

   307     NodeMap obsoleteClasses;

   308     NodeMap namespaceIndex;

   309     NodeMap serviceClasses;

   310 #ifdef QDOC_QML    

   311     NodeMap qmlClasses;

   312 #endif

   313     QMap<QString, NodeMap > funcIndex;

   314     QMap<Text, const Node *> legaleseTexts;

   315     NewSinceMaps newSinceMaps;

   316     static QString sinceTitles[];

   317     NewClassMaps newClassMaps;

   318 };

   319 

   320 #define HTMLGENERATOR_ADDRESS           "address"

   321 #define HTMLGENERATOR_FOOTER            "footer"

   322 #define HTMLGENERATOR_GENERATEMACREFS    "generatemacrefs" // ### document me

   323 #define HTMLGENERATOR_POSTHEADER        "postheader"

   324 #define HTMLGENERATOR_STYLE             "style"

   325 #define HTMLGENERATOR_STYLESHEETS       "stylesheets"

   326 #define HTMLGENERATOR_CUSTOMHEADELEMENTS "customheadelements"

   327 

   328 QT_END_NAMESPACE

   329 

   330 #endif

   331