tools/qdoc3/htmlgenerator.h

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2010 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