/****************************************************************************** * ftvhelp.cpp,v 1.0 2000/09/06 16:09:00 * * Copyright (C) 1997-2015 by Dimitri van Heesch. * * Permission to use, copy, modify, and distribute this software and its * documentation under the terms of the GNU General Public License is hereby * granted. No representations are made about the suitability of this software * for any purpose. It is provided "as is" without express or implied warranty. * See the GNU General Public License for more details. * * Documents produced by Doxygen are derivative works derived from the * input used in their production; they are not affected by this license. * * Original version contributed by Kenney Wong * Modified by Dimitri van Heesch * * Folder Tree View for offline help on browsers that do not support HTML Help. */ #include #include #include #include #include #include "ftvhelp.h" #include "config.h" #include "message.h" #include "doxygen.h" #include "language.h" #include "htmlgen.h" #include "layout.h" #include "pagedef.h" #include "docparser.h" #include "htmldocvisitor.h" #include "filedef.h" #include "classdef.h" #include "util.h" #include "resourcemgr.h" #define MAX_INDENT 1024 static int folderId=1; const char *JAVASCRIPT_LICENSE_TEXT = R"LIC(/* @licstart The following is the entire license notice for the JavaScript code in this file. The MIT License (MIT) Copyright (C) 1997-2020 by Dimitri van Heesch Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. @licend The above is the entire license notice for the JavaScript code in this file */ )LIC"; struct FTVNode { FTVNode(bool dir,const char *r,const char *f,const char *a, const char *n,bool sepIndex,bool navIndex,const Definition *df) : isLast(TRUE), isDir(dir),ref(r),file(f),anchor(a),name(n), index(0), parent(0), separateIndex(sepIndex), addToNavIndex(navIndex), def(df) { children.setAutoDelete(TRUE); } int computeTreeDepth(int level) const; int numNodesAtLevel(int level,int maxLevel) const; bool isLast; bool isDir; QCString ref; QCString file; QCString anchor; QCString name; int index; QList children; FTVNode *parent; bool separateIndex; bool addToNavIndex; const Definition *def; }; int FTVNode::computeTreeDepth(int level) const { int maxDepth=level; QListIterator li(children); FTVNode *n; for (;(n=li.current());++li) { if (n->children.count()>0) { int d = n->computeTreeDepth(level+1); if (d>maxDepth) maxDepth=d; } } return maxDepth; } int FTVNode::numNodesAtLevel(int level,int maxLevel) const { int num=0; if (level li(children); FTVNode *n; for (;(n=li.current());++li) { num+=n->numNodesAtLevel(level+1,maxLevel); } } return num; } //---------------------------------------------------------------------------- /*! Constructs an ftv help object. * The object has to be \link initialize() initialized\endlink before it can * be used. */ FTVHelp::FTVHelp(bool TLI) { /* initial depth */ m_indentNodes = new QList[MAX_INDENT]; m_indentNodes[0].setAutoDelete(TRUE); m_indent=0; m_topLevelIndex = TLI; } /*! Destroys the ftv help object. */ FTVHelp::~FTVHelp() { delete[] m_indentNodes; } /*! This will create a folder tree view table of contents file (tree.js). * \sa finalize() */ void FTVHelp::initialize() { } /*! Finalizes the FTV help. This will finish and close the * contents file (index.js). * \sa initialize() */ void FTVHelp::finalize() { generateTreeView(); } /*! Increase the level of the contents hierarchy. * This will start a new sublist in contents file. * \sa decContentsDepth() */ void FTVHelp::incContentsDepth() { //printf("%p: incContentsDepth() indent=%d\n",this,m_indent); m_indent++; ASSERT(m_indent0); if (m_indent>0) { m_indent--; QList *nl = &m_indentNodes[m_indent]; FTVNode *parent = nl->getLast(); if (parent) { QList *children = &m_indentNodes[m_indent+1]; while (!children->isEmpty()) { parent->children.append(children->take(0)); } } } } /*! Add a list item to the contents file. * \param isDir TRUE if the item is a directory, FALSE if it is a text * \param name the name of the item. * \param ref the URL of to the item. * \param file the file containing the definition of the item * \param anchor the anchor within the file. * \param separateIndex put the entries in a separate index file * \param addToNavIndex add this entry to the quick navigation index * \param def Definition corresponding to this entry */ void FTVHelp::addContentsItem(bool isDir, const char *name, const char *ref, const char *file, const char *anchor, bool separateIndex, bool addToNavIndex, const Definition *def ) { //printf("%p: m_indent=%d addContentsItem(%s,%s,%s,%s)\n",this,m_indent,name,ref,file,anchor); QList *nl = &m_indentNodes[m_indent]; FTVNode *newNode = new FTVNode(isDir,ref,file,anchor,name,separateIndex,addToNavIndex,def); if (!nl->isEmpty()) { nl->getLast()->isLast=FALSE; } nl->append(newNode); newNode->index = nl->count()-1; if (m_indent>0) { QList *pnl = &m_indentNodes[m_indent-1]; newNode->parent = pnl->getLast(); } } static QCString node2URL(const FTVNode *n,bool overruleFile=FALSE,bool srcLink=FALSE) { QCString url = n->file; if (!url.isEmpty() && url.at(0)=='!') // relative URL { // remove leading ! url = url.mid(1); } else if (!url.isEmpty() && url.at(0)=='^') // absolute URL { // skip, keep ^ in the output } else // local file (with optional anchor) { if (overruleFile && n->def && n->def->definitionType()==Definition::TypeFile) { const FileDef *fd = toFileDef(n->def); if (srcLink) { url = fd->getSourceFileBase(); } else { url = fd->getOutputFileBase(); } } url = addHtmlExtensionIfMissing(url); if (!n->anchor.isEmpty()) url+="#"+n->anchor; } return url; } QCString FTVHelp::generateIndentLabel(FTVNode *n,int level) { QCString result; if (n->parent) { result=generateIndentLabel(n->parent,level+1); } result+=QCString().setNum(n->index)+"_"; return result; } void FTVHelp::generateIndent(FTextStream &t, FTVNode *n,bool opened) { int indent=0; FTVNode *p = n->parent; while (p) { indent++; p=p->parent; } if (n->isDir) { QCString dir = opened ? "▼" : "►"; t << " " << "" << dir << ""; } else { t << " "; } } void FTVHelp::generateLink(FTextStream &t,FTVNode *n) { //printf("FTVHelp::generateLink(ref=%s,file=%s,anchor=%s\n", // n->ref.data(),n->file.data(),n->anchor.data()); bool setTarget = FALSE; if (n->file.isEmpty()) // no link { t << "" << convertToHtml(n->name) << ""; } else // link into other frame { if (!n->ref.isEmpty()) // link to entity imported via tag file { t << "ref,TRUE); t << node2URL(n); if (!setTarget) { if (m_topLevelIndex) t << "\" target=\"basefrm\">"; else t << "\" target=\"_self\">"; } else { t << "\">"; } t << convertToHtml(n->name); t << ""; if (!n->ref.isEmpty()) { t << " [external]"; } } } static void generateBriefDoc(FTextStream &t,const Definition *def) { QCString brief = def->briefDescription(TRUE); //printf("*** %p: generateBriefDoc(%s)='%s'\n",def,def->name().data(),brief.data()); if (!brief.isEmpty()) { DocNode *root = validatingParseDoc(def->briefFile(),def->briefLine(), def,0,brief,FALSE,FALSE, 0,TRUE,TRUE,Config_getBool(MARKDOWN_SUPPORT)); QCString relPath = relativePathToRoot(def->getOutputFileBase()); HtmlCodeGenerator htmlGen(t,relPath); HtmlDocVisitor *visitor = new HtmlDocVisitor(t,htmlGen,def); root->accept(visitor); delete visitor; delete root; } } static char compoundIcon(const ClassDef *cd) { char icon='C'; if (cd->getLanguage() == SrcLangExt_Slice) { if (cd->compoundType()==ClassDef::Interface) { icon='I'; } else if (cd->compoundType()==ClassDef::Struct) { icon='S'; } else if (cd->compoundType()==ClassDef::Exception) { icon='E'; } } return icon; } void FTVHelp::generateTree(FTextStream &t, const QList &nl,int level,int maxLevel,int &index) { QListIterator nli(nl); FTVNode *n; for (nli.toFirst();(n=nli.current());++nli) { t << "=maxLevel) // item invisible by default t << " style=\"display:none;\""; else // item visible by default index++; t << ">"; bool nodeOpened = level+1isDir) { if (n->def && n->def->definitionType()==Definition::TypeGroup) { // no icon } else if (n->def && n->def->definitionType()==Definition::TypePage) { // no icon } else if (n->def && n->def->definitionType()==Definition::TypeNamespace) { if (n->def->getLanguage() == SrcLangExt_Slice) { t << "M"; } else { t << "N"; } } else if (n->def && n->def->definitionType()==Definition::TypeClass) { char icon=compoundIcon(toClassDef(n->def)); t << "" << icon << ""; } else { t << " "; } generateLink(t,n); t << ""; if (n->def) { generateBriefDoc(t,n->def); } t << "" << endl; folderId++; generateTree(t,n->children,level+1,maxLevel,index); } else // leaf node { const FileDef *srcRef=0; if (n->def && n->def->definitionType()==Definition::TypeFile && (toFileDef(n->def))->generateSourceFile()) { srcRef = toFileDef(n->def); } if (srcRef) { t << "getSourceFileBase() << Doxygen::htmlFileExtension << "\">"; } if (n->def && n->def->definitionType()==Definition::TypeGroup) { // no icon } else if (n->def && n->def->definitionType()==Definition::TypePage) { // no icon } else if (n->def && n->def->definitionType()==Definition::TypeNamespace) { if (n->def->getLanguage() == SrcLangExt_Slice) { t << "M"; } else { t << "N"; } } else if (n->def && n->def->definitionType()==Definition::TypeClass) { char icon=compoundIcon(toClassDef(n->def)); t << "" << icon << ""; } else if (n->def && n->def->definitionType()==Definition::TypeDir) { t << ""; } else { t << ""; } if (srcRef) { t << ""; } generateLink(t,n); t << ""; if (n->def) { generateBriefDoc(t,n->def); } t << "" << endl; } } } //----------------------------------------------------------- struct NavIndexEntry { NavIndexEntry(const QCString &u,const QCString &p) : url(u), path(p) {} QCString url; QCString path; }; class NavIndexEntryList : public QList { public: NavIndexEntryList() : QList() { setAutoDelete(TRUE); } ~NavIndexEntryList() {} private: int compareValues(const NavIndexEntry *item1,const NavIndexEntry *item2) const { // sort list based on url return qstrcmp(item1->url,item2->url); } }; static QCString pathToNode(const FTVNode *leaf,const FTVNode *n) { QCString result; if (n->parent) { result+=pathToNode(leaf,n->parent); } result+=QCString().setNum(n->index); if (leaf!=n) result+=","; return result; } static bool dupOfParent(const FTVNode *n) { if (n->parent==0) return FALSE; if (n->file==n->parent->file) return TRUE; return FALSE; } static void generateJSLink(FTextStream &t,const FTVNode *n) { if (n->file.isEmpty()) // no link { t << "\"" << convertToJSString(n->name) << "\", null, "; } else // link into other page { t << "\"" << convertToJSString(n->name) << "\", \""; t << externalRef("",n->ref,TRUE); t << node2URL(n); t << "\", "; } } static QCString convertFileId2Var(const QCString &fileId) { QCString varId = fileId; int i=varId.findRev('/'); if (i>=0) varId = varId.mid(i+1); return substitute(varId,"-","_"); } static bool generateJSTree(NavIndexEntryList &navIndex,FTextStream &t, const QList &nl,int level,bool &first) { static QCString htmlOutput = Config_getString(HTML_OUTPUT); QCString indentStr; indentStr.fill(' ',level*2); bool found=FALSE; QListIterator nli(nl); const FTVNode *n; for (nli.toFirst();(n=nli.current());++nli) { // terminate previous entry if (!first) t << "," << endl; first=FALSE; // start entry if (!found) { t << "[" << endl; } found=TRUE; if (n->addToNavIndex) // add entry to the navigation index { if (n->def && n->def->definitionType()==Definition::TypeFile) { const FileDef *fd = toFileDef(n->def); bool doc,src; doc = fileVisibleInIndex(fd,src); if (doc) { navIndex.append(new NavIndexEntry(node2URL(n,TRUE,FALSE),pathToNode(n,n))); } if (src) { navIndex.append(new NavIndexEntry(node2URL(n,TRUE,TRUE),pathToNode(n,n))); } } else { navIndex.append(new NavIndexEntry(node2URL(n),pathToNode(n,n))); } } if (n->separateIndex) // store items in a separate file for dynamic loading { bool firstChild=TRUE; t << indentStr << " [ "; generateJSLink(t,n); if (n->children.count()>0) // write children to separate file for dynamic loading { QCString fileId = n->file; if (n->anchor) { fileId+="_"+n->anchor; } if (dupOfParent(n)) { fileId+="_dup"; } QFile f(htmlOutput+"/"+fileId+".js"); if (f.open(IO_WriteOnly)) { FTextStream tt(&f); tt << "var " << convertFileId2Var(fileId) << " =" << endl; generateJSTree(navIndex,tt,n->children,1,firstChild); tt << endl << "];"; } t << "\"" << fileId << "\" ]"; } else // no children { t << "null ]"; } } else // show items in this file { bool firstChild=TRUE; t << indentStr << " [ "; generateJSLink(t,n); bool emptySection = !generateJSTree(navIndex,t,n->children,level+1,firstChild); if (emptySection) t << "null ]"; else t << endl << indentStr << " ] ]"; } } return found; } static void generateJSNavTree(const QList &nodeList) { QCString htmlOutput = Config_getString(HTML_OUTPUT); QFile f(htmlOutput+"/navtreedata.js"); NavIndexEntryList navIndex; if (f.open(IO_WriteOnly) /*&& fidx.open(IO_WriteOnly)*/) { //FTextStream tidx(&fidx); //tidx << "var NAVTREEINDEX =" << endl; //tidx << "{" << endl; FTextStream t(&f); t << JAVASCRIPT_LICENSE_TEXT; t << "var NAVTREE =" << endl; t << "[" << endl; t << " [ "; QCString projName = Config_getString(PROJECT_NAME); if (projName.isEmpty()) { if (mainPageHasTitle()) // Use title of main page as root { t << "\"" << convertToJSString(Doxygen::mainPage->title()) << "\", "; } else // Use default section title as root { LayoutNavEntry *lne = LayoutDocManager::instance().rootNavEntry()->find(LayoutNavEntry::MainPage); t << "\"" << convertToJSString(lne->title()) << "\", "; } } else // use PROJECT_NAME as root tree element { t << "\"" << convertToJSString(projName) << "\", "; } t << "\"index" << Doxygen::htmlFileExtension << "\", "; // add special entry for index page navIndex.append(new NavIndexEntry("index"+Doxygen::htmlFileExtension,"")); // related page index is written as a child of index.html, so add this as well navIndex.append(new NavIndexEntry("pages"+Doxygen::htmlFileExtension,"")); bool first=TRUE; generateJSTree(navIndex,t,nodeList,1,first); if (first) t << "]" << endl; else t << endl << " ] ]" << endl; t << "];" << endl << endl; // write the navigation index (and sub-indices) navIndex.sort(); int subIndex=0; int elemCount=0; const int maxElemCount=250; //QFile fidx(htmlOutput+"/navtreeindex.js"); QFile fsidx(htmlOutput+"/navtreeindex0.js"); if (/*fidx.open(IO_WriteOnly) &&*/ fsidx.open(IO_WriteOnly)) { //FTextStream tidx(&fidx); FTextStream tsidx(&fsidx); t << "var NAVTREEINDEX =" << endl; t << "[" << endl; tsidx << "var NAVTREEINDEX" << subIndex << " =" << endl; tsidx << "{" << endl; QListIterator li(navIndex); NavIndexEntry *e; first=TRUE; for (li.toFirst();(e=li.current());) // for each entry { if (elemCount==0) { if (!first) { t << "," << endl; } else { first=FALSE; } t << "\"" << e->url << "\""; } tsidx << "\"" << e->url << "\":[" << e->path << "]"; ++li; if (li.current() && elemCount=maxElemCount) // switch to new sub-index { tsidx << "};" << endl; elemCount=0; fsidx.close(); subIndex++; fsidx.setName(htmlOutput+"/navtreeindex"+QCString().setNum(subIndex)+".js"); if (!fsidx.open(IO_WriteOnly)) break; tsidx.setDevice(&fsidx); tsidx << "var NAVTREEINDEX" << subIndex << " =" << endl; tsidx << "{" << endl; } } tsidx << "};" << endl; t << endl << "];" << endl; } t << endl << "var SYNCONMSG = '" << theTranslator->trPanelSynchronisationTooltip(FALSE) << "';"; t << endl << "var SYNCOFFMSG = '" << theTranslator->trPanelSynchronisationTooltip(TRUE) << "';"; } ResourceMgr::instance().copyResource("navtree.js",htmlOutput); } //----------------------------------------------------------- // new style images void FTVHelp::generateTreeViewImages() { QCString dname=Config_getString(HTML_OUTPUT); const ResourceMgr &rm = ResourceMgr::instance(); rm.copyResource("doc.luma",dname); rm.copyResource("folderopen.luma",dname); rm.copyResource("folderclosed.luma",dname); rm.copyResource("splitbar.lum",dname); } // new style scripts void FTVHelp::generateTreeViewScripts() { QCString htmlOutput = Config_getString(HTML_OUTPUT); // generate navtree.js & navtreeindex.js generateJSNavTree(m_indentNodes[0]); // copy resize.js & navtree.css ResourceMgr::instance().copyResource("resize.js",htmlOutput); ResourceMgr::instance().copyResource("navtree.css",htmlOutput); } // write tree inside page void FTVHelp::generateTreeViewInline(FTextStream &t) { int preferredNumEntries = Config_getInt(HTML_INDEX_NUM_ENTRIES); t << "
\n"; QListIterator li(m_indentNodes[0]); FTVNode *n; int d=1, depth=1; for (;(n=li.current());++li) { if (n->children.count()>0) { d = n->computeTreeDepth(2); if (d>depth) depth=d; } } int preferredDepth = depth; // write level selector if (depth>1) { t << "
["; t << theTranslator->trDetailLevel(); t << " "; for (int i=1;i<=depth;i++) { t << "" << i << ""; } t << "]
"; if (preferredNumEntries>0) { preferredDepth=1; for (int i=1;i<=depth;i++) { int num=0; for (li.toFirst();(n=li.current());++li) { num+=n->numNodesAtLevel(0,i); } if (num<=preferredNumEntries) { preferredDepth=i; } else { break; } } } } //printf("preferred depth=%d\n",preferredDepth); if (m_indentNodes[0].count()) { t << "\n"; int index=0; generateTree(t,m_indentNodes[0],0,preferredDepth,index); t << "
\n"; } t << "
\n"; } // write old style index.html and tree.html void FTVHelp::generateTreeView() { generateTreeViewImages(); generateTreeViewScripts(); }