LayoutDocManager Class Reference

Singleton providing access to the (user configurable) layout of the documentation. More...

#include <src/layout.h>

Classes
class	Private

Public Types
enum	LayoutPart { PART_SPECIFICATIONS }

Public Member Functions
const LayoutDocEntryList &	docEntries (LayoutPart part) const
	Returns the list of LayoutDocEntry's in representation order for a given page identified by part.
LayoutNavEntry *	rootNavEntry () const
	returns the (invisible) root of the navigation tree.
LayoutNavEntry *	createChildNavEntry (LayoutNavEntry *root, LayoutNavEntry::Kind k, bool vs, const DString &bf, const DString &tl, const DString &intro)
	append a new node as a child to root.
void	parse (const DString &fileName, const char *data=nullptr)
	Parses a user provided layout.
void	init ()
int	majorVersion () const
int	minorVersion () const

Static Public Member Functions
static LayoutDocManager &	instance ()
	Returns a reference to this singleton.
static std::string	partToString (int k)

Private Member Functions
void	addEntry (LayoutPart p, LayoutDocEntryPtr &&e)
void	mergeNavEntries (LayoutDocManager &manager)
void	mergeDocEntries (const DString &fileName, LayoutDocManager &manager)
void	removeInvisibleDocEntries ()
	LayoutDocManager ()
	~LayoutDocManager ()

Private Attributes
std::unique_ptr< Private >	d

Friends
class	LayoutParser

Detailed Description

Singleton providing access to the (user configurable) layout of the documentation.

Definition at line 259 of file layout.h.

Member Enumeration Documentation

LayoutPart

enum LayoutDocManager::LayoutPart

Enumerator
PART_SPECIFICATIONS

Definition at line 263 of file layout.h.

    {
#define PSPEC(x,y) x y,
      PART_SPECIFICATIONS
#undef PSPEC
    };

Constructor & Destructor Documentation

LayoutDocManager()

LayoutDocManager::LayoutDocManager ( )

private

Definition at line 1408 of file layout.cpp.

                                   : d(std::make_unique<Private>())
{
}

References d.

Referenced by instance(), mergeDocEntries(), mergeNavEntries(), and parse().

~LayoutDocManager()

LayoutDocManager::~LayoutDocManager ( )

private

Definition at line 1412 of file layout.cpp.

{
}

Member Function Documentation

addEntry()

void LayoutDocManager::addEntry ( LayoutDocManager::LayoutPart p, LayoutDocEntryPtr && e )

private

Definition at line 1463 of file layout.cpp.

{
  auto &docEntry = d->docEntries[static_cast<int>(p)];
  docEntry.push_back(std::move(e)); // add
}

References d.

Referenced by LayoutParser::endMemberDecl(), LayoutParser::endMemberDef(), LayoutParser::startMemberDecl(), LayoutParser::startMemberDeclEntry(), LayoutParser::startMemberDef(), LayoutParser::startMemberDefEntry(), LayoutParser::startSectionEntry(), and LayoutParser::startSimpleEntry().

createChildNavEntry()

LayoutNavEntry * LayoutDocManager::createChildNavEntry	(	LayoutNavEntry *	root,
		LayoutNavEntry::Kind	k,
		bool	vs,
		const DString &	bf,
		const DString &	tl,
		const DString &	intro )

append a new node as a child to root.

Definition at line 1452 of file layout.cpp.

{
  if (parent==nullptr) parent = &d->rootNav;
  auto ptr = std::make_unique<LayoutNavEntry>(parent,k,vs,bf,tl,intro);
  auto child = ptr.get();
  parent->appendChild(std::move(ptr));
  return child;
}

References d, and parent().

Referenced by LayoutParser::startNavEntry().

docEntries()

const LayoutDocEntryList & LayoutDocManager::docEntries

(

LayoutDocManager::LayoutPart

part

)

const

Returns the list of LayoutDocEntry's in representation order for a given page identified by part.

Definition at line 1442 of file layout.cpp.

{
  return d->docEntries[static_cast<int>(part)];
}

References d.

Referenced by LayoutParser::endMemberDecl(), and LayoutParser::endMemberDef().

init()

void LayoutDocManager::init

(

)

Definition at line 1416 of file layout.cpp.

{
  LayoutParser layoutParser(LayoutDocManager::instance());
  XMLHandlers handlers;
  handlers.startElement = [&layoutParser](const std::string &name,const XMLHandlers::Attributes &attrs) { layoutParser.startElement(name,attrs); };
  handlers.endElement   = [&layoutParser](const std::string &name) { layoutParser.endElement(name); };
  handlers.error        = [&layoutParser](const std::string &fileName,int lineNr,const std::string &msg) { layoutParser.error(fileName,lineNr,msg); };
  XMLParser parser(handlers);
  layoutParser.setDocumentLocator(&parser);
  constexpr auto layoutFile = "layout_default.xml";
  DString layout_default = ResourceMgr::instance().getAsString(layoutFile);
  parser.parse(layoutFile,layout_default.data(),Debug::isFlagSet(Debug::Lex_xml),
               [&]() { DebugLex::print(Debug::Lex_xml,"Entering","libxml/xml.l",layoutFile); },
               [&]() { DebugLex::print(Debug::Lex_xml,"Finished", "libxml/xml.l",layoutFile); }
              );
  removeInvisibleDocEntries();
  d->majorVersion = layoutParser.majorVersion();
  d->minorVersion = layoutParser.minorVersion();
}

References d, DString::data(), LayoutParser::endElement(), XMLHandlers::endElement, LayoutParser::error(), XMLHandlers::error, ResourceMgr::getAsString(), instance(), ResourceMgr::instance(), Debug::isFlagSet(), LayoutParser, Debug::Lex_xml, LayoutParser::majorVersion(), LayoutParser::minorVersion(), msg, XMLParser::parse(), removeInvisibleDocEntries(), LayoutParser::setDocumentLocator(), LayoutParser::startElement(), and XMLHandlers::startElement.

Referenced by parseInput().

instance()

LayoutDocManager & LayoutDocManager::instance ( )

static

Returns a reference to this singleton.

Definition at line 1436 of file layout.cpp.

{
  static LayoutDocManager theInstance;
  return theInstance;
}

References LayoutDocManager().

Referenced by addMembersToIndex(), ClassDefImpl::countAdditionalInheritedMembers(), ModuleDefImpl::countVisibleMembers(), NamespaceDefImpl::countVisibleMembers(), generateJSNavTree(), ClassDefImpl::getTitleForMemberListType(), init(), parseInput(), printLayout(), renderQuickLinksAsTabs(), ClassDefImpl::setAnonymousEnumType(), ClassDefImpl::writeAdditionalInheritedMembers(), writeAlphabeticalExceptionIndex(), writeAlphabeticalIndex(), writeAlphabeticalInterfaceIndex(), writeAlphabeticalStructIndex(), writeAnnotatedIndexGeneric(), writeDefaultQuickLinks(), ClassDefImpl::writeDocumentation(), ConceptDefImpl::writeDocumentation(), DirDefImpl::writeDocumentation(), FileDefImpl::writeDocumentation(), GroupDefImpl::writeDocumentation(), ModuleDefImpl::writeDocumentation(), NamespaceDefImpl::writeDocumentation(), ClassDefImpl::writeDocumentationContents(), writeExampleIndex(), writeFileIndex(), writeGraphicalClassHierarchy(), writeGraphicalExceptionHierarchy(), writeGraphicalInterfaceHierarchy(), writeHierarchicalExceptionIndex(), writeHierarchicalIndex(), writeHierarchicalInterfaceIndex(), ClassDefImpl::writeInlineDocumentation(), writeModuleMembers(), writeNamespaceIndex(), writeNamespaceMembers(), ClassDefImpl::writeSummaryLinks(), FileDefImpl::writeSummaryLinks(), GroupDefImpl::writeSummaryLinks(), ModuleDefImpl::writeSummaryLinks(), NamespaceDefImpl::writeSummaryLinks(), ClassDefImpl::writeTagFile(), DirDefImpl::writeTagFile(), FileDefImpl::writeTagFile(), GroupDefImpl::writeTagFile(), ModuleDefImpl::writeTagFile(), and NamespaceDefImpl::writeTagFile().

majorVersion()

int LayoutDocManager::majorVersion

(

)

const

Definition at line 1530 of file layout.cpp.

{
  return d->majorVersion;
}

References d.

mergeDocEntries()

void LayoutDocManager::mergeDocEntries ( const DString & fileName, LayoutDocManager & manager )

private

Definition at line 1722 of file layout.cpp.

{
   for (size_t i=0; i<d->docEntries.size(); i++)
   {
     //printf("========= part %zu\n",i);
     mergeDocEntryLists(fileName,other.d->docEntries[i],d->docEntries[i]);
   }
}

References d, LayoutDocManager(), and mergeDocEntryLists().

Referenced by parse().

mergeNavEntries()

void LayoutDocManager::mergeNavEntries ( LayoutDocManager & manager )

private

Definition at line 1634 of file layout.cpp.

{
  mergeNavTreeNodesRec(other.rootNavEntry(),rootNavEntry());
}

References LayoutDocManager(), mergeNavTreeNodesRec(), and rootNavEntry().

minorVersion()

int LayoutDocManager::minorVersion

(

)

const

Definition at line 1535 of file layout.cpp.

{
  return d->minorVersion;
}

References d.

parse()

void LayoutDocManager::parse	(	const DString &	fileName,
		const char *	data = nullptr )

Parses a user provided layout.

Definition at line 1469 of file layout.cpp.

{
  //printf("============ LayoutDocManager::parse(%s)\n",qPrint(fileName));
  LayoutDocManager layoutDocManager;
  LayoutParser layoutParser(layoutDocManager);
  XMLHandlers handlers;
  handlers.startElement = [&layoutParser](const std::string &name,const XMLHandlers::Attributes &attrs) { layoutParser.startElement(name,attrs); };
  handlers.endElement   = [&layoutParser](const std::string &name) { layoutParser.endElement(name); };
  handlers.error        = [&layoutParser](const std::string &fn,int lineNr,const std::string &msg) { layoutParser.error(fn,lineNr,msg); };
  XMLParser parser(handlers);
  layoutParser.setDocumentLocator(&parser);
  parser.parse(fileName.data(),
               data ? data : fileToString(fileName).data(),
               Debug::isFlagSet(Debug::Lex_xml),
               [&]() { DebugLex::print(Debug::Lex_xml,"Entering","libxml/xml.l",qPrint(fileName)); },
               [&]() { DebugLex::print(Debug::Lex_xml,"Finished", "libxml/xml.l",qPrint(fileName)); },
               transcodeCharacterStringToUTF8
              );
 
  // version in the user defined layout overrides default one
  d->majorVersion = layoutParser.majorVersion();
  d->minorVersion = layoutParser.minorVersion();
 
  // merge missing parts of the default layout into the user defined layout
  // For now merging in defaults has been disabled for navigation entries
  // to avoid "extra entries" for projects that work with partial layout files.
  //mergeNavEntries(layoutDocManager);
 
  // for compatibility reasons we only merge defaults when the user defined layout has at least version 2.0 or higher
  if (d->majorVersion>=2)
  {
    mergeDocEntries(fileName,layoutDocManager);
  }
 
  layoutDocManager.removeInvisibleDocEntries();
 
  // replace default layout with merged layout
  d->docEntries.swap(layoutDocManager.d->docEntries);
  d->rootNav.swap(layoutDocManager.d->rootNav);
}

References d, DString::data(), LayoutParser::endElement(), XMLHandlers::endElement, LayoutParser::error(), XMLHandlers::error, fileToString(), Debug::isFlagSet(), LayoutDocManager(), LayoutParser, Debug::Lex_xml, LayoutParser::majorVersion(), mergeDocEntries(), LayoutParser::minorVersion(), msg, XMLParser::parse(), DebugLex::print(), qPrint(), removeInvisibleDocEntries(), LayoutParser::setDocumentLocator(), LayoutParser::startElement(), XMLHandlers::startElement, and transcodeCharacterStringToUTF8().

Referenced by parseInput().

partToString()

std::string LayoutDocManager::partToString ( int k )

inlinestatic

Definition at line 271 of file layout.h.

    {
      switch (k)
      {
#define PSPEC(x,y) case x: return #x; break;
        PART_SPECIFICATIONS
#undef PSPEC
        default: return "unknown"; // to satisfy compiler
      }
    }

References PART_SPECIFICATIONS.

Referenced by printLayout().

removeInvisibleDocEntries()

void LayoutDocManager::removeInvisibleDocEntries ( )

private

Definition at line 1510 of file layout.cpp.

{
  // remove invisible entries
  for (auto &list : d->docEntries)
  {
    auto it = list.begin();
    while (it!=list.end())
    {
      if (*it==nullptr || !(*it)->visible())
      {
        it = list.erase(it);
      }
      else
      {
        ++it;
      }
    }
  }
}

References d.

Referenced by init(), and parse().

rootNavEntry()

LayoutNavEntry * LayoutDocManager::rootNavEntry

(

)

const

returns the (invisible) root of the navigation tree.

Definition at line 1447 of file layout.cpp.

{
  return &d->rootNav;
}

References d.

Referenced by generateJSNavTree(), mergeNavEntries(), renderQuickLinksAsTabs(), LayoutParser::startNavEntry(), LayoutParser::startNavIndex(), writeAlphabeticalExceptionIndex(), writeAlphabeticalIndex(), writeAlphabeticalInterfaceIndex(), writeAlphabeticalStructIndex(), writeAnnotatedIndexGeneric(), writeDefaultQuickLinks(), writeExampleIndex(), writeFileIndex(), writeGraphicalClassHierarchy(), writeGraphicalExceptionHierarchy(), writeGraphicalInterfaceHierarchy(), writeHierarchicalExceptionIndex(), writeHierarchicalIndex(), writeHierarchicalInterfaceIndex(), and writeNamespaceIndex().

Friends And Related Symbol Documentation

LayoutParser

friend class LayoutParser

friend

Definition at line 304 of file layout.h.

References LayoutParser, printLayout(), and writeDefaultLayoutFile().

Referenced by init(), LayoutParser, and parse().

Member Data Documentation

d

std::unique_ptr<Private> LayoutDocManager::d

private

Definition at line 303 of file layout.h.

Referenced by addEntry(), createChildNavEntry(), docEntries(), init(), LayoutDocManager(), majorVersion(), mergeDocEntries(), minorVersion(), parse(), removeInvisibleDocEntries(), and rootNavEntry().

---

The documentation for this class was generated from the following files:

• src/layout.h
• src/layout.cpp