#include "ftvhelp.h"
#include <memory>
#include <variant>
#include <vector>
#include "classdef.h"
#include "config.h"
#include "docparser.h"
#include "doxygen.h"
#include "filedef.h"
#include "htmldocvisitor.h"
#include "language.h"
#include "layout.h"
#include "message.h"
#include "outputlist.h"
#include "pagedef.h"
#include "portable.h"
#include "resourcemgr.h"
#include "threadpool.h"
#include "util.h"

Include dependency graph for ftvhelp.cpp:

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 DString	node2URL (const FTVNodePtr &n, bool overruleFile=false, bool srcLink=false)
static DString	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 DString	pathToNode (const FTVNodePtr &leaf, const FTVNodePtr &n)
static bool	dupOfParent (const FTVNodePtr &n)
static void	generateJSLink (TextStream &t, const FTVNodePtr &n)
static DString	convertFileId2Var (const DString &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 50 of file ftvhelp.cpp.

◆ FTVNodes

using FTVNodes = std::vector<FTVNodePtr>

Definition at line 52 of file ftvhelp.cpp.

◆ FTVNodeWeakPtr

using FTVNodeWeakPtr = std::weak_ptr<FTVNode>

Definition at line 51 of file ftvhelp.cpp.

◆ JSTreeFiles

using JSTreeFiles = std::vector<JSTreeFile>

Definition at line 595 of file ftvhelp.cpp.

Function Documentation

◆ collectJSTreeFiles()

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

static

Definition at line 597 of file ftvhelp.cpp.

{
  DString htmlOutput = Config_getString(HTML_OUTPUT);
  for (const auto &n : nl)
  {
    if (n->separateIndex) // add new file if there are children
    {
      if (!n->children.empty())
      {
        DString 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()

char compoundIcon ( const ClassDef * cd )

static

Definition at line 360 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, and ClassDef::Struct.

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

◆ convertFileId2Var()

DString convertFileId2Var ( const DString & fileId )

static

Definition at line 577 of file ftvhelp.cpp.

{
  DString varId = fileId;
  size_t i=varId.rfind('/');
  if (i!=DString::npos) varId = varId.mid(i+1);
  if (isdigit(varId[0])) varId.prepend("_");
 
  return substitute(varId,"-","_");
}

References DString::mid(), DString::npos, DString::prepend(), DString::rfind(), and substitute().

Referenced by generateJSTreeFiles().

◆ dupOfParent()

bool dupOfParent ( const FTVNodePtr & n )

static

Definition at line 550 of file ftvhelp.cpp.

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

References parent().

Referenced by generateJSTree(), and generateJSTreeFiles().

◆ generateBriefDoc()

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

static

Definition at line 331 of file ftvhelp.cpp.

{
  DString brief = def->briefDescription(true);
  //printf("*** %p: generateBriefDoc(%s)='%s'\n",def,qPrint(def->name()),qPrint(brief));
  if (!brief.empty())
  {
    auto parser { createDocParser() };
    auto ast    { validatingParseDoc(*parser.get(),
                                     def->briefFile(),
                                     def->briefLine(),
                                     def,
                                     nullptr,
                                     brief,
                                     DocOptions()
                                     .setSingleLine(true)
                                     .setLinkFromIndex(true))
                 };
    const DocNodeAST *astImpl = dynamic_cast<const DocNodeAST*>(ast.get());
    if (astImpl)
    {
      DString 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(), createDocParser(), DString::empty(), Definition::getOutputFileBase(), relativePathToRoot(), DocNodeAST::root, and validatingParseDoc().

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

◆ generateIndent()

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

static

Definition at line 263 of file ftvhelp.cpp.

{
  bool dynamicSections = Config_getBool(HTML_DYNAMIC_SECTIONS);
  int indent=0;
  auto parent = n->parent.lock();
  while (parent) { indent++; parent=parent->parent.lock(); }
  if (n->isDir && dynamicSections)
  {
    const char *ARROW_DOWN = "<span class=\"arrowhead opened\"></span>";
    const char *ARROW_RIGHT = "<span class=\"arrowhead closed\"></span>";
    DString dir = opened ? ARROW_DOWN : ARROW_RIGHT;
    for(int i=0;i<indent;i++) t << "<span class=\"spacer\">&#160;</span>";
    t << "<span id=\"arr_" << generateIndentLabel(n,0) << "\" class=\"arrow\">" << dir
      << "</span>";
  }
  else
  {
    for(int i=0;i<=indent;i++) t << "<span class=\"spacer\">&#160;</span>";
  }
}

References Config_getBool, generateIndentLabel(), and parent().

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

◆ generateIndentLabel()

DString generateIndentLabel	(	const FTVNodePtr &	n,
		int	level )

static

Definition at line 251 of file ftvhelp.cpp.

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

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

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

◆ generateJSLink()

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

static

Definition at line 558 of file ftvhelp.cpp.

{
  bool nameAsHtml = !n->nameAsHtml.empty();
  DString link = nameAsHtml ? convertToJSString(n->nameAsHtml,true) : convertToJSString(n->name);
  if (Config_getBool(HIDE_SCOPE_NAMES)) link=stripScope(link);
  link = substitute(link,"\n","");
  if (n->file.empty()) // no link
  {
    t << "\"" << link << "\", null, ";
  }
  else // link into other page
  {
    t << "\"" << link << "\", \"";
    t << externalRef("",n->ref);
    t << node2URL(n);
    t << "\", ";
  }
}

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

Referenced by generateJSTree().

◆ generateJSNavTree()

void generateJSNavTree ( const FTVNodes & nodeList )

static

Definition at line 752 of file ftvhelp.cpp.

{
  DString 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 << "  [ ";
    DString projName = Config_getString(PROJECT_NAME);
    if (projName.empty())
    {
      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.empty() && (n2.url.empty() || (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++;
          DString fileName = htmlOutput+"/navtreeindex"+DString().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 << "\nconst SYNCONMSG = '"  << theTranslator->trPanelSynchronisationTooltip(false) << "';";
    t << "\nconst SYNCOFFMSG = '" << theTranslator->trPanelSynchronisationTooltip(true)  << "';";
    t << "\nconst LISTOFALLMEMBERS = '" << theTranslator->trListOfAllMembers() << "';";
  }
 
  auto &mgr = ResourceMgr::instance();
  {
    std::ofstream fn = Portable::openOutputStream(htmlOutput+"/navtree.js");
    if (fn.is_open())
    {
      TextStream t(&fn);
      t << substitute(
             substitute(mgr.getAsString("navtree.js"),
                "$TREEVIEW_WIDTH", DString().setNum(Config_getInt(TREEVIEW_WIDTH))),
                "$PROJECTID",getProjectId());
    }
  }
}

References Config_getInt, Config_getString, convertToJSString(), DString::empty(), LayoutNavEntry::find(), generateJSTree(), generateJSTreeFiles(), getProjectId(), Doxygen::htmlFileExtension, LayoutDocManager::instance(), ResourceMgr::instance(), JAVASCRIPT_LICENSE_TEXT, Doxygen::mainPage, mainPageHasTitle(), Portable::openOutputStream(), NavIndexEntry::path, LayoutDocManager::rootNavEntry(), DString::setNum(), substitute(), theTranslator, LayoutNavEntry::title(), Translator::trListOfAllMembers(), Translator::trPanelSynchronisationTooltip(), and NavIndexEntry::url.

Referenced by FTVHelp::generateTreeViewScripts().

◆ generateJSTree()

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

static

Definition at line 620 of file ftvhelp.cpp.

{
  DString htmlOutput = Config_getString(HTML_OUTPUT);
  DString 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 = fd->visibleInIndex(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
      {
        DString fileId = n->file;
        if (!n->anchor.empty())
        {
          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(), DString::fill(), g_navIndexMutex, generateJSLink(), generateJSTree(), node2URL(), pathToNode(), toFileDef(), Definition::TypeFile, and FileDef::visibleInIndex().

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

◆ generateJSTreeFiles()

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

static

Definition at line 701 of file ftvhelp.cpp.

{
  DString htmlOutput = Config_getString(HTML_OUTPUT);
 
  auto getVarName = [](const FTVNodePtr n)
  {
    DString                  fileId = n->file;
    if (!n->anchor.empty()) fileId+="_"+n->anchor;
    if (dupOfParent(n))       fileId+="_dup";
    return fileId;
  };
 
  auto generateJSFile = [&](const JSTreeFile &tf)
  {
    DString fileId = getVarName(tf.node);
    DString 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()

DString node2URL	(	const FTVNodePtr &	n,
		bool	overruleFile = false,
		bool	srcLink = false )

static

Definition at line 219 of file ftvhelp.cpp.

{
  DString url = n->file;
  if (!url.empty() && url.at(0)=='!')  // relative URL
  {
    // remove leading !
    url = url.mid(1);
  }
  else if (!url.empty() && 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.empty()) url+="#"+n->anchor;
  }
  return url;
}

References addHtmlExtensionIfMissing(), DString::at(), DString::empty(), Definition::getOutputFileBase(), Definition::getSourceFileBase(), DString::mid(), toFileDef(), and Definition::TypeFile.

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

◆ pathToNode()

DString pathToNode	(	const FTVNodePtr &	leaf,
		const FTVNodePtr &	n )

static

Definition at line 537 of file ftvhelp.cpp.

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

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

Referenced by generateJSTree(), and pathToNode().

Variable Documentation

◆ folderId

int folderId =1

static

Definition at line 46 of file ftvhelp.cpp.

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

◆ g_navIndexMutex

std::mutex g_navIndexMutex

static

Definition at line 618 of file ftvhelp.cpp.

Referenced by generateJSTree().

Classes

Typedefs

Functions

Variables

Typedef Documentation

◆ FTVNodePtr

◆ FTVNodes

◆ FTVNodeWeakPtr

◆ JSTreeFiles

Function Documentation

◆ collectJSTreeFiles()

◆ compoundIcon()

◆ convertFileId2Var()

◆ dupOfParent()

◆ generateBriefDoc()

◆ generateIndent()

◆ generateIndentLabel()

◆ generateJSLink()

◆ generateJSNavTree()

◆ generateJSTree()

◆ generateJSTreeFiles()

◆ node2URL()

◆ pathToNode()

Variable Documentation

◆ folderId

◆ g_navIndexMutex