ftvhelp.cpp File Reference

#include <stdio.h>
#include <stdlib.h>
#include <algorithm>
#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"
#include "portable.h"
#include "outputlist.h"
#include "threadpool.h"

Include dependency graph for ftvhelp.cpp:

Go to the source code of this file.

Classes
struct	FTVNode
struct	FTVHelp::Private
struct	NavIndexEntry
class	NavIndexEntryList
struct	JSTreeFile

Typedefs
using	FTVNodePtr = std::shared_ptr<FTVNode>
using	FTVNodeWeakPtr = std::weak_ptr<FTVNode>
using	FTVNodes = std::vector<FTVNodePtr>
using	JSTreeFiles = std::vector<JSTreeFile>

Functions
static QCString	node2URL (const FTVNodePtr &n, bool overruleFile=FALSE, bool srcLink=FALSE)
static QCString	generateIndentLabel (const FTVNodePtr &n, int level)
static void	generateIndent (TextStream &t, const FTVNodePtr &n, bool opened)
static void	generateBriefDoc (TextStream &t, const Definition *def)
static char	compoundIcon (const ClassDef *cd)
static QCString	pathToNode (const FTVNodePtr &leaf, const FTVNodePtr &n)
static bool	dupOfParent (const FTVNodePtr &n)
static void	generateJSLink (TextStream &t, const FTVNodePtr &n)
static QCString	convertFileId2Var (const QCString &fileId)
static void	collectJSTreeFiles (const FTVNodes &nl, JSTreeFiles &files)
static bool	generateJSTree (NavIndexEntryList &navIndex, TextStream &t, const FTVNodes &nl, int level, bool &first)
static void	generateJSTreeFiles (NavIndexEntryList &navIndex, TextStream &t, const FTVNodes &nodeList)
static void	generateJSNavTree (const FTVNodes &nodeList)

Variables
static int	folderId =1
static std::mutex	g_navIndexMutex

Typedef Documentation

FTVNodePtr

using FTVNodePtr = std::shared_ptr<FTVNode>

Definition at line 47 of file ftvhelp.cpp.

FTVNodes

using FTVNodes = std::vector<FTVNodePtr>

Definition at line 49 of file ftvhelp.cpp.

FTVNodeWeakPtr

using FTVNodeWeakPtr = std::weak_ptr<FTVNode>

Definition at line 48 of file ftvhelp.cpp.

JSTreeFiles

using JSTreeFiles = std::vector<JSTreeFile>

Definition at line 574 of file ftvhelp.cpp.

Function Documentation

collectJSTreeFiles()

static void collectJSTreeFiles ( const FTVNodes & nl, JSTreeFiles & files )

static

Definition at line 576 of file ftvhelp.cpp.

{
  QCString htmlOutput = Config_getString(HTML_OUTPUT);
  for (const auto &n : nl)
  {
    if (n->separateIndex) // add new file if there are children
    {
      if (!n->children.empty())
      {
        QCString fileId = n->file;
        files.emplace_back(fileId,n);
        collectJSTreeFiles(n->children,files);
      }
    }
    else // traverse without adding a new file
    {
      collectJSTreeFiles(n->children,files);
    }
  }
}

References collectJSTreeFiles(), and Config_getString.

Referenced by collectJSTreeFiles(), and generateJSTreeFiles().

compoundIcon()

static char compoundIcon ( const ClassDef * cd )

static

Definition at line 345 of file ftvhelp.cpp.

{
  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;
}

References ClassDef::compoundType(), ClassDef::Exception, Definition::getLanguage(), ClassDef::Interface, Slice, and ClassDef::Struct.

Referenced by FTVHelp::Private::generateTree().

convertFileId2Var()

static QCString convertFileId2Var ( const QCString & fileId )

static

Definition at line 558 of file ftvhelp.cpp.

{
  QCString varId = fileId;
  int i=varId.findRev('/');
  if (i>=0) varId = varId.mid(i+1);
  return substitute(varId,"-","_");
}

References QCString::findRev(), QCString::mid(), and substitute().

Referenced by generateJSTreeFiles().

dupOfParent()

static bool dupOfParent ( const FTVNodePtr & n )

static

Definition at line 533 of file ftvhelp.cpp.

{
  auto parent = n->parent.lock();
  if (!parent) return FALSE;
  if (n->file==parent->file) return TRUE;
  return FALSE;
}

References FALSE, parent(), and TRUE.

Referenced by generateJSTree(), and generateJSTreeFiles().

generateBriefDoc()

static void generateBriefDoc ( TextStream & t, const Definition * def )

static

Definition at line 322 of file ftvhelp.cpp.

{
  QCString brief = def->briefDescription(TRUE);
  //printf("*** %p: generateBriefDoc(%s)='%s'\n",def,qPrint(def->name()),qPrint(brief));
  if (!brief.isEmpty())
  {
    auto parser { createDocParser() };
    auto ast    { validatingParseDoc(*parser.get(),
                                     def->briefFile(),def->briefLine(),
                                     def,nullptr,brief,FALSE,FALSE,
                                     QCString(),TRUE,TRUE,Config_getBool(MARKDOWN_SUPPORT)) };
    const DocNodeAST *astImpl = dynamic_cast<const DocNodeAST*>(ast.get());
    if (astImpl)
    {
      QCString relPath = relativePathToRoot(def->getOutputFileBase());
      OutputCodeList htmlList;
      htmlList.add<HtmlCodeGenerator>(&t,relPath);
      HtmlDocVisitor visitor(t,htmlList,def);
      std::visit(visitor,astImpl->root);
    }
  }
}

References OutputCodeList::add(), Definition::briefDescription(), Definition::briefFile(), Definition::briefLine(), Config_getBool, createDocParser(), FALSE, Definition::getOutputFileBase(), QCString::isEmpty(), relativePathToRoot(), DocNodeAST::root, TRUE, and validatingParseDoc().

Referenced by FTVHelp::Private::generateTree().

generateIndent()

static void generateIndent ( TextStream & t, const FTVNodePtr & n, bool opened )

static

Definition at line 257 of file ftvhelp.cpp.

{
  int indent=0;
  auto parent = n->parent.lock();
  while (parent) { indent++; parent=parent->parent.lock(); }
  if (n->isDir)
  {
    QCString dir = opened ? "▼" : "►";
    t << "<span style=\"width:" << (indent*16) << "px;display:inline-block;\">&#160;</span>"
      << "<span id=\"arr_" << generateIndentLabel(n,0) << "\" class=\"arrow\" ";
    t << "onclick=\"dynsection.toggleFolder('" << generateIndentLabel(n,0) << "')\"";
    t << ">" << dir
      << "</span>";
  }
  else
  {
    t << "<span style=\"width:" << ((indent+1)*16) << "px;display:inline-block;\">&#160;</span>";
  }
}

References generateIndentLabel(), and parent().

Referenced by FTVHelp::Private::generateTree().

generateIndentLabel()

static QCString generateIndentLabel ( const FTVNodePtr & n, int level )

static

Definition at line 245 of file ftvhelp.cpp.

{
  QCString result;
  auto parent = n->parent.lock();
  if (parent)
  {
    result=generateIndentLabel(parent,level+1);
  }
  result+=QCString().setNum(n->index)+"_";
  return result;
}

References generateIndentLabel(), parent(), and QCString::setNum().

Referenced by generateIndent(), generateIndentLabel(), and FTVHelp::Private::generateTree().

generateJSLink()

static void generateJSLink ( TextStream & t, const FTVNodePtr & n )

static

Definition at line 541 of file ftvhelp.cpp.

{
  if (n->file.isEmpty()) // no link
  {
    t << "\"" << convertToJSString(n->name) << "\", null, ";
  }
  else // link into other page
  {
    QCString result = n->name;
    if (Config_getBool(HIDE_SCOPE_NAMES)) result=stripScope(result);
    t << "\"" << convertToJSString(result) << "\", \"";
    t << externalRef("",n->ref,TRUE);
    t << node2URL(n);
    t << "\", ";
  }
}

References Config_getBool, convertToJSString(), externalRef(), node2URL(), stripScope(), and TRUE.

Referenced by generateJSTree().

generateJSNavTree()

static void generateJSNavTree ( const FTVNodes & nodeList )

static

Definition at line 731 of file ftvhelp.cpp.

{
  QCString htmlOutput = Config_getString(HTML_OUTPUT);
  std::ofstream f = Portable::openOutputStream(htmlOutput+"/navtreedata.js");
  NavIndexEntryList navIndex;
  if (f.is_open())
  {
    TextStream t(&f);
    //TextStream tidx(&fidx);
    //tidx << "var NAVTREEINDEX =\n";
    //tidx << "{\n";
    t << JAVASCRIPT_LICENSE_TEXT;
    t << "var NAVTREE =\n";
    t << "[\n";
    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.emplace_back("index"+Doxygen::htmlFileExtension,"");
    // related page index is written as a child of index.html, so add this as well
    navIndex.emplace_back("pages"+Doxygen::htmlFileExtension,"");
 
    bool first=TRUE;
    generateJSTree(navIndex,t,nodeList,1,first);
    generateJSTreeFiles(navIndex,t,nodeList);
 
    if (first)
      t << "]\n";
    else
      t << "\n  ] ]\n";
    t << "];\n\n";
 
    // write the navigation index (and sub-indices)
    std::stable_sort(navIndex.begin(),navIndex.end(),[](const auto &n1,const auto &n2)
        { return !n1.url.isEmpty() && (n2.url.isEmpty() || (n1.url<n2.url)); });
 
    int subIndex=0;
    int elemCount=0;
    const int maxElemCount=250;
    std::ofstream tsidx = Portable::openOutputStream(htmlOutput+"/navtreeindex0.js");
    if (tsidx.is_open())
    {
      t << "var NAVTREEINDEX =\n";
      t << "[\n";
      tsidx << "var NAVTREEINDEX" << subIndex << " =\n";
      tsidx << "{\n";
      first=TRUE;
      auto it = navIndex.begin();
      while (it!=navIndex.end())
      {
        const NavIndexEntry &e = *it;
        if (elemCount==0)
        {
          if (!first)
          {
            t << ",\n";
          }
          else
          {
            first=FALSE;
          }
          t << "\"" << e.url << "\"";
        }
        tsidx << "\"" << e.url << "\":[" << e.path << "]";
        ++it;
        if (it!=navIndex.end() && elemCount<maxElemCount-1) tsidx << ","; // not last entry
        tsidx << "\n";
 
        elemCount++;
        if (it!=navIndex.end() && elemCount>=maxElemCount) // switch to new sub-index
        {
          tsidx << "};\n";
          elemCount=0;
          tsidx.close();
          subIndex++;
          QCString fileName = htmlOutput+"/navtreeindex"+QCString().setNum(subIndex)+".js";
          tsidx = Portable::openOutputStream(fileName);
          if (!tsidx.is_open()) break;
          tsidx << "var NAVTREEINDEX" << subIndex << " =\n";
          tsidx << "{\n";
        }
      }
      tsidx << "};\n";
      t << "\n];\n";
    }
    t << "\nvar SYNCONMSG = '"  << theTranslator->trPanelSynchronisationTooltip(FALSE) << "';";
    t << "\nvar SYNCOFFMSG = '" << theTranslator->trPanelSynchronisationTooltip(TRUE)  << "';";
  }
 
  auto &mgr = ResourceMgr::instance();
  {
    std::ofstream fn = Portable::openOutputStream(htmlOutput+"/navtree.js");
    if (fn.is_open())
    {
      TextStream t(&fn);
      t << substitute(mgr.getAsString("navtree.js"),"$PROJECTID",getProjectId());
    }
  }
}

References Config_getString, convertToJSString(), FALSE, LayoutNavEntry::find(), generateJSTree(), generateJSTreeFiles(), getProjectId(), Doxygen::htmlFileExtension, LayoutDocManager::instance(), ResourceMgr::instance(), QCString::isEmpty(), JAVASCRIPT_LICENSE_TEXT, Doxygen::mainPage, mainPageHasTitle(), Portable::openOutputStream(), NavIndexEntry::path, LayoutDocManager::rootNavEntry(), QCString::setNum(), substitute(), theTranslator, LayoutNavEntry::title(), TRUE, and NavIndexEntry::url.

Referenced by FTVHelp::generateTreeViewScripts().

generateJSTree()

static bool generateJSTree ( NavIndexEntryList & navIndex, TextStream & t, const FTVNodes & nl, int level, bool & first )

static

Definition at line 599 of file ftvhelp.cpp.

{
  QCString htmlOutput = Config_getString(HTML_OUTPUT);
  QCString indentStr;
  indentStr.fill(' ',level*2);
 
  bool found=FALSE;
  for (const auto &n : nl)
  {
    // terminate previous entry
    if (!first) t << ",\n";
    first=FALSE;
 
    // start entry
    if (!found)
    {
      t << "[\n";
    }
    found=TRUE;
 
    if (n->addToNavIndex) // add entry to the navigation index
    {
      std::lock_guard lock(g_navIndexMutex);
      if (n->def && n->def->definitionType()==Definition::TypeFile)
      {
        const FileDef *fd = toFileDef(n->def);
        bool src = false;
        bool doc = fileVisibleInIndex(fd,src);
        if (doc)
        {
          navIndex.emplace_back(node2URL(n,TRUE,FALSE),pathToNode(n,n));
        }
        if (src)
        {
          navIndex.emplace_back(node2URL(n,TRUE,TRUE),pathToNode(n,n));
        }
      }
      else
      {
        navIndex.emplace_back(node2URL(n),pathToNode(n,n));
      }
    }
 
    if (n->separateIndex) // store items in a separate file for dynamic loading
    {
      t << indentStr << "  [ ";
      generateJSLink(t,n);
      if (!n->children.empty()) // write children to separate file for dynamic loading
      {
        QCString fileId = n->file;
        if (!n->anchor.isEmpty())
        {
          fileId+="_"+n->anchor;
        }
        if (dupOfParent(n))
        {
          fileId+="_dup";
        }
        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 << "\n" << indentStr << "  ] ]";
    }
  }
  return found;
}

References Config_getString, dupOfParent(), FALSE, fileVisibleInIndex(), QCString::fill(), found, g_navIndexMutex, generateJSLink(), generateJSTree(), node2URL(), pathToNode(), toFileDef(), TRUE, and Definition::TypeFile.

Referenced by generateJSNavTree(), generateJSTree(), and generateJSTreeFiles().

generateJSTreeFiles()

static void generateJSTreeFiles ( NavIndexEntryList & navIndex, TextStream & t, const FTVNodes & nodeList )

static

Definition at line 680 of file ftvhelp.cpp.

{
  QCString htmlOutput = Config_getString(HTML_OUTPUT);
 
  auto getVarName = [](const FTVNodePtr n)
  {
    QCString                  fileId = n->file;
    if (!n->anchor.isEmpty()) fileId+="_"+n->anchor;
    if (dupOfParent(n))       fileId+="_dup";
    return fileId;
  };
 
  auto generateJSFile = [&](const JSTreeFile &tf)
  {
    QCString fileId = getVarName(tf.node);
    QCString fileName = htmlOutput+"/"+fileId+".js";
    std::ofstream ff = Portable::openOutputStream(fileName);
    if (ff.is_open())
    {
      bool firstChild = true;
      TextStream tt(&ff);
      tt << "var " << convertFileId2Var(fileId) << " =\n";
      generateJSTree(navIndex,tt,tf.node->children,1,firstChild);
      tt << "\n];";
    }
  };
 
  JSTreeFiles jsTreeFiles;
  collectJSTreeFiles(nodeList,jsTreeFiles);
 
  std::size_t numThreads = static_cast<std::size_t>(Config_getInt(NUM_PROC_THREADS));
  if (numThreads>1) // multi threaded version
  {
    ThreadPool threadPool(numThreads);
    std::vector< std::future<void> > results;
    for (const auto &tf : jsTreeFiles)
    {
      results.emplace_back(threadPool.queue([&](){ generateJSFile(tf); }));
    }
    // wait for the results
    for (auto &f : results) f.get();
  }
  else // single threaded version
  {
    for (const auto &tf : jsTreeFiles)
    {
      generateJSFile(tf);
    }
  }
}

References collectJSTreeFiles(), Config_getInt, Config_getString, convertFileId2Var(), dupOfParent(), generateJSTree(), Portable::openOutputStream(), and ThreadPool::queue().

Referenced by generateJSNavTree().

node2URL()

static QCString node2URL ( const FTVNodePtr & n, bool overruleFile = FALSE, bool srcLink = FALSE )

static

Definition at line 213 of file ftvhelp.cpp.

{
  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();
      }
    }
    addHtmlExtensionIfMissing(url);
    if (!n->anchor.isEmpty()) url+="#"+n->anchor;
  }
  return url;
}

References addHtmlExtensionIfMissing(), QCString::at(), FALSE, Definition::getOutputFileBase(), Definition::getSourceFileBase(), QCString::isEmpty(), QCString::mid(), toFileDef(), and Definition::TypeFile.

Referenced by generateJSLink(), generateJSTree(), and FTVHelp::Private::generateLink().

pathToNode()

static QCString pathToNode ( const FTVNodePtr & leaf, const FTVNodePtr & n )

static

Definition at line 520 of file ftvhelp.cpp.

{
  QCString result;
  auto parent = n->parent.lock();
  if (parent)
  {
    result+=pathToNode(leaf,parent);
  }
  result+=QCString().setNum(n->index);
  if (leaf!=n) result+=",";
  return result;
}

References parent(), pathToNode(), and QCString::setNum().

Referenced by generateJSTree(), and pathToNode().

Variable Documentation

folderId

int folderId =1

static

Definition at line 43 of file ftvhelp.cpp.

Referenced by FTVHelp::Private::generateTree().

g_navIndexMutex

std::mutex g_navIndexMutex

static

Definition at line 597 of file ftvhelp.cpp.

Referenced by generateJSTree().