KDevelop API Documentation

DocumentationPlugin Class Reference

Documentation Plugin Interface. More...

#include <kdevdocumentationplugin.h>

Inheritance diagram for DocumentationPlugin:

Inheritance graph
[legend]
Collaboration diagram for DocumentationPlugin:

Collaboration graph
[legend]
List of all members.

Public Types

enum  Capability {
  Index = 1, FullTextSearch = 2, CustomDocumentationTitles = 4, ProjectDocumentation = 8,
  ProjectUserManual = 16
}
 Capability of documentation plugin. More...
enum  ProjectDocType { APIDocs, UserManual }
 Possible project documentation types. More...

Public Slots

virtual void createIndex (IndexBox *index)
 Creates index and fills index listbox.

Public Member Functions

 DocumentationPlugin (KConfig *pluginConfig, QObject *parent=0, const char *name=0)
 Constructor.
virtual ~DocumentationPlugin ()
virtual QString pluginName () const =0
 Returns the i18n name of the plugin.
virtual DocumentationCatalogItemcreateCatalog (KListView *contents, const QString &title, const QString &url)=0
 Creates documentation catalog with given title and url.
virtual void init (KListView *contents)
 Initialize a list of catalogs.
virtual void reinit (KListView *contents, IndexBox *index, QStringList restrictions)
 Reloads a list of catalogs.
virtual void autoSetup ()
 Initializes plugin configuration.
virtual void autoSetupPlugin ()=0
 Plugin specific automatic setup code.
virtual bool catalogEnabled (const QString &name) const
 Indicates if a catalog with specified name is enabled.
virtual void setCatalogEnabled (const QString &name, bool e)
 Enables or disables documentation catalog.
virtual bool needRefreshIndex (DocumentationCatalogItem *item)=0
 Indicates if an index of given catalog should be rebuilt.
virtual bool indexEnabled (DocumentationCatalogItem *item) const
 Indicates if an index is enabled for given catalog.
virtual void setIndexEnabled (DocumentationCatalogItem *item, bool e)
 Enables or disables index for documentation catalog.
virtual void createIndex (IndexBox *index, DocumentationCatalogItem *item)=0
 Builds index for given catalog.
virtual void createTOC (DocumentationCatalogItem *item)=0
 Creates a table of contents for given catalog.
virtual void setCatalogURL (DocumentationCatalogItem *item)=0
 Sets the URL to the catalog.
virtual QStringList fullTextSearchLocations ()=0
virtual void loadCatalogConfiguration (KListView *configurationView)
 Loads catalog configuration and fills configurationView with ConfigurationItem objects.
virtual void saveCatalogConfiguration (KListView *configurationView)
 Saves catalog configuration basing on configurationView and deletedConfigurationItems contents.
virtual void addCatalogConfiguration (KListView *configurationView, const QString &title, const QString &url)
 Adds new catalog to a configuration.
virtual void editCatalogConfiguration (ConfigurationItem *configurationItem, const QString &title, const QString &url)
 Edits catalog configuration.
virtual void deleteCatalogConfiguration (const ConfigurationItem *const configurationItem)
 Removes catalog from configuration.
virtual QPair< KFile::Mode,
QString
catalogLocatorProps ()=0
 Returns a mode and a filter for catalog locator dialogs.
virtual QString catalogTitle (const QString &url)=0
 Returns a title of catalog defined by an url parameter.
virtual void reload ()
 Reloads documentation catalogs and indices.
virtual void clear ()
 Clears documentation catalogs and indices.
bool hasCapability (Capability cap) const
 Checks if documentation plugin has given capability.
void setDirtyIndex (bool dirty)
 Sets dirty flag for all indices.
virtual void cacheIndex (DocumentationCatalogItem *item)
 Caches index for documentation catalog.
virtual bool loadCachedIndex (IndexBox *index, DocumentationCatalogItem *item)
 Loads index from the cache.
virtual ProjectDocumentationPluginprojectDocumentationPlugin (ProjectDocType type)
 Returns associated project documentation plugin.

Protected Member Functions

void setCapabilities (int caps)
 Sets capabilities of documentation plugin.
virtual void clearCatalogIndex (DocumentationCatalogItem *item)
 Clears index of given catalog.
void loadIndex (IndexBox *index, DocumentationCatalogItem *item)
 Loads index from cache or creates and caches it if does not exist.

Protected Attributes

QValueList< DocumentationCatalogItem * > catalogs
 A list of loaded documentation catalogs.
QMap< QString, DocumentationCatalogItem * > namedCatalogs
 A map of names of loaded documentation catalogs.
QMap< DocumentationCatalogItem *,
QValueList< IndexItemProto * > > 
indexes
 A map of indices of loaded documentation catalogs.
QStringList deletedConfigurationItems
 Stores items deleted from configuration.
KConfigconfig
 Configuration object used by a plugin.

Private Member Functions

virtual void addCatalog (DocumentationCatalogItem *item)
 Adds catalog item to catalogs, namedCatalogs and indexes lists and maps.
virtual void clearCatalog (DocumentationCatalogItem *item)
 Removes catalog item from catalogs, namedCatalogs and indexes lists and maps.

Private Attributes

int m_capabilities
bool m_indexCreated

Friends

class IndexItemProto
class DocumentationCatalogItem

Detailed Description

Documentation Plugin Interface.

All KDevelop documentation plugins must implement this interface. Documentation plugin handles certain documentation type. It provides methods to load documentation catalogs and indexes for a documentation of that type. It also has methods to configure catalogs and provides a list of URL's for the full text search tool.

Definition at line 190 of file kdevdocumentationplugin.h.


Member Enumeration Documentation

enum DocumentationPlugin::Capability
 

Capability of documentation plugin.

Enumeration values:
Index  index can be built for catalogs
FullTextSearch  full text search is possible in catalog locations
CustomDocumentationTitles  user can specify titles for documentation catalogs
ProjectDocumentation  plugin can handle project API documentation
ProjectUserManual  plugin can handle project user manual

Definition at line 195 of file kdevdocumentationplugin.h.

enum DocumentationPlugin::ProjectDocType
 

Possible project documentation types.

Enumeration values:
APIDocs 
UserManual 

Definition at line 201 of file kdevdocumentationplugin.h.


Constructor & Destructor Documentation

DocumentationPlugin::DocumentationPlugin KConfig pluginConfig,
QObject parent = 0,
const char *  name = 0
 

Constructor.

Should initialize capabilities of the plugin by using setCapabilities protected method. For example,

    setCapabilities(Index | FullTextSearch);

Definition at line 255 of file kdevdocumentationplugin.cpp.

DocumentationPlugin::~DocumentationPlugin  )  [virtual]
 

Definition at line 260 of file kdevdocumentationplugin.cpp.


Member Function Documentation

void DocumentationPlugin::addCatalog DocumentationCatalogItem item  )  [private, virtual]
 

Adds catalog item to catalogs, namedCatalogs and indexes lists and maps.

Definition at line 392 of file kdevdocumentationplugin.cpp.

References catalogs, and namedCatalogs.

Referenced by DocumentationCatalogItem::DocumentationCatalogItem().

void DocumentationPlugin::addCatalogConfiguration KListView configurationView,
const QString title,
const QString url
[virtual]
 

Adds new catalog to a configuration.

Definition at line 399 of file kdevdocumentationplugin.cpp.

References FullTextSearch, hasCapability(), and Index.

Referenced by DocGlobalConfigWidget::addCollectionButtonClicked().

void DocumentationPlugin::autoSetup  )  [virtual]
 

Initializes plugin configuration.

Documentation plugins should be able to initialize the default configuration on startup without any user interaction. Call this in the constructor of your plugin.

Definition at line 264 of file kdevdocumentationplugin.cpp.

References autoSetupPlugin(), config, KConfigBase::readBoolEntry(), KConfigBase::setGroup(), KConfigBase::sync(), and KConfigBase::writeEntry().

virtual void DocumentationPlugin::autoSetupPlugin  )  [pure virtual]
 

Plugin specific automatic setup code.

This method is called by autoSetup.

Implemented in DocCHMPlugin, DocCustomPlugin, DocDevHelpPlugin, DocDjvuPlugin, DocDoxygenPlugin, DocKDevTOCPlugin, DocPDBPlugin, DocPDFPlugin, and DocQtPlugin.

Referenced by autoSetup().

void DocumentationPlugin::cacheIndex DocumentationCatalogItem item  )  [virtual]
 

Caches index for documentation catalog.

Reimplement this only if custom caching algorythm is used (do not forget to reimplement also loadCachedIndex and createIndex).

Definition at line 329 of file kdevdocumentationplugin.cpp.

References CACHE_VERSION, indexes, kdDebug(), and locateLocal().

Referenced by loadIndex().

bool DocumentationPlugin::catalogEnabled const QString name  )  const [virtual]
 

Indicates if a catalog with specified name is enabled.

Documentation plugin should check this and do not load catalogs disabled in configuration. All catalogs are enabled by default.

Definition at line 582 of file kdevdocumentationplugin.cpp.

References config, KConfigBase::group(), KConfigBase::readBoolEntry(), and KConfigBase::setGroup().

Referenced by init(), and reinit().

virtual QPair<KFile::Mode, QString> DocumentationPlugin::catalogLocatorProps  )  [pure virtual]
 

Returns a mode and a filter for catalog locator dialogs.

Implemented in DocCHMPlugin, DocCustomPlugin, DocDevHelpPlugin, DocDjvuPlugin, DocDoxygenPlugin, DocKDevTOCPlugin, DocPDBPlugin, DocPDFPlugin, and DocQtPlugin.

Referenced by DocProjectConfigWidget::changeDocSystem(), and EditCatalogDlg::EditCatalogDlg().

virtual QString DocumentationPlugin::catalogTitle const QString url  )  [pure virtual]
 

Returns a title of catalog defined by an url parameter.

Implemented in DocCHMPlugin, DocCustomPlugin, DocDevHelpPlugin, DocDjvuPlugin, DocDoxygenPlugin, DocKDevTOCPlugin, DocPDBPlugin, DocPDFPlugin, and DocQtPlugin.

Referenced by EditCatalogDlg::locationURLChanged().

void DocumentationPlugin::clear  )  [virtual]
 

Clears documentation catalogs and indices.

Definition at line 286 of file kdevdocumentationplugin.cpp.

References catalogs, and clearCatalog().

Referenced by reload().

void DocumentationPlugin::clearCatalog DocumentationCatalogItem item  )  [private, virtual]
 

Removes catalog item from catalogs, namedCatalogs and indexes lists and maps.

Definition at line 295 of file kdevdocumentationplugin.cpp.

References catalogs, indexes, and namedCatalogs.

Referenced by clear(), and DocumentationCatalogItem::~DocumentationCatalogItem().

void DocumentationPlugin::clearCatalogIndex DocumentationCatalogItem item  )  [protected, virtual]
 

Clears index of given catalog.

Definition at line 418 of file kdevdocumentationplugin.cpp.

References indexes.

Referenced by reinit().

virtual DocumentationCatalogItem* DocumentationPlugin::createCatalog KListView contents,
const QString title,
const QString url
[pure virtual]
 

Creates documentation catalog with given title and url.

Implemented in DocCHMPlugin, DocCustomPlugin, DocDevHelpPlugin, DocDjvuPlugin, DocDoxygenPlugin, DocKDevTOCPlugin, DocPDBPlugin, DocPDFPlugin, and DocQtPlugin.

Referenced by ProjectDocumentationPlugin::init(), init(), and reinit().

void DocumentationPlugin::createIndex IndexBox index  )  [virtual, slot]
 

Creates index and fills index listbox.

Reimplement this only if custom caching algorythm is used (do not forget to reimplement also cacheIndex and loadCachedIndex).

Definition at line 316 of file kdevdocumentationplugin.cpp.

References catalogs, loadIndex(), and m_indexCreated.

virtual void DocumentationPlugin::createIndex IndexBox index,
DocumentationCatalogItem item
[pure virtual]
 

Builds index for given catalog.

This method should fill index with IndexItem objects.

Parameters:
index the listbox which contains index items

Implemented in DocCHMPlugin, DocCustomPlugin, DocDevHelpPlugin, DocDjvuPlugin, DocDoxygenPlugin, DocKDevTOCPlugin, DocPDBPlugin, DocPDFPlugin, and DocQtPlugin.

Referenced by loadIndex().

virtual void DocumentationPlugin::createTOC DocumentationCatalogItem item  )  [pure virtual]
 

Creates a table of contents for given catalog.

Documentation part uses lazy loading of toc's to reduce startup time. This means that createTOC will be called on expand event of catalog item.

Implemented in DocCHMPlugin, DocCustomPlugin, DocDevHelpPlugin, DocDjvuPlugin, DocDoxygenPlugin, DocKDevTOCPlugin, DocPDBPlugin, DocPDFPlugin, and DocQtPlugin.

Referenced by DocumentationCatalogItem::load(), and reload().

void DocumentationPlugin::deleteCatalogConfiguration const ConfigurationItem *const   configurationItem  )  [virtual]
 

Removes catalog from configuration.

configurationItem should not be removed here.

Definition at line 413 of file kdevdocumentationplugin.cpp.

References deletedConfigurationItems, and ConfigurationItem::title().

Referenced by DocGlobalConfigWidget::removeCollectionButtonClicked().

void DocumentationPlugin::editCatalogConfiguration ConfigurationItem configurationItem,
const QString title,
const QString url
[virtual]
 

Edits catalog configuration.

Definition at line 406 of file kdevdocumentationplugin.cpp.

References ConfigurationItem::setTitle(), and ConfigurationItem::setURL().

Referenced by DocGlobalConfigWidget::editCollectionButtonClicked().

virtual QStringList DocumentationPlugin::fullTextSearchLocations  )  [pure virtual]
 

Implemented in DocCHMPlugin, DocCustomPlugin, DocDevHelpPlugin, DocDjvuPlugin, DocDoxygenPlugin, DocKDevTOCPlugin, DocPDBPlugin, DocPDFPlugin, and DocQtPlugin.

bool DocumentationPlugin::hasCapability Capability  cap  )  const [inline]
 

Checks if documentation plugin has given capability.

Definition at line 295 of file kdevdocumentationplugin.h.

References m_capabilities.

Referenced by addCatalogConfiguration(), EditCatalogDlg::EditCatalogDlg(), and loadCatalogConfiguration().

bool DocumentationPlugin::indexEnabled DocumentationCatalogItem item  )  const [virtual]
 

Indicates if an index is enabled for given catalog.

If documentation plugin has Index capability, indices for it's catalogs can be enabled/disabled in configuration dialog.

Definition at line 573 of file kdevdocumentationplugin.cpp.

References config, KConfigBase::group(), KConfigBase::readBoolEntry(), and KConfigBase::setGroup().

Referenced by loadIndex(), and reinit().

void DocumentationPlugin::init KListView contents  )  [virtual]
 

Initialize a list of catalogs.

Parameters:
contents the listview to fill with catalogs

Definition at line 439 of file kdevdocumentationplugin.cpp.

References catalogEnabled(), config, createCatalog(), KConfig::entryMap(), KConfigBase::readPathEntry(), and KConfigBase::setGroup().

Referenced by DocumentationPart::loadDocumentationPlugins().

bool DocumentationPlugin::loadCachedIndex IndexBox index,
DocumentationCatalogItem item
[virtual]
 

Loads index from the cache.

Reimplement this only if custom caching algorythm is used (do not forget to reimplement also cacheIndex and createIndex).

Definition at line 354 of file kdevdocumentationplugin.cpp.

References IndexItemProto::addURL(), IndexItemProto, kdDebug(), and locateLocal().

Referenced by loadIndex().

void DocumentationPlugin::loadCatalogConfiguration KListView configurationView  )  [virtual]
 

Loads catalog configuration and fills configurationView with ConfigurationItem objects.

Definition at line 503 of file kdevdocumentationplugin.cpp.

References config, KConfig::entryMap(), FullTextSearch, hasCapability(), Index, namedCatalogs, KConfigBase::readBoolEntry(), ConfigurationItem::setContents(), ConfigurationItem::setFullTextSearch(), KConfigBase::setGroup(), ConfigurationItem::setIndex(), and ConfigurationItem::title().

void DocumentationPlugin::loadIndex IndexBox index,
DocumentationCatalogItem item
[protected]
 

Loads index from cache or creates and caches it if does not exist.

Definition at line 429 of file kdevdocumentationplugin.cpp.

References cacheIndex(), createIndex(), indexEnabled(), loadCachedIndex(), and needRefreshIndex().

Referenced by createIndex(), and reinit().

virtual bool DocumentationPlugin::needRefreshIndex DocumentationCatalogItem item  )  [pure virtual]
 

Indicates if an index of given catalog should be rebuilt.

This method is used by index caching algorythm to make a descision to rebuild index or to load it from cache.

Implemented in DocCHMPlugin, DocCustomPlugin, DocDevHelpPlugin, DocDjvuPlugin, DocDoxygenPlugin, DocKDevTOCPlugin, DocPDBPlugin, DocPDFPlugin, and DocQtPlugin.

Referenced by loadIndex().

virtual QString DocumentationPlugin::pluginName  )  const [pure virtual]
 

Returns the i18n name of the plugin.

Implemented in DocCHMPlugin, DocCustomPlugin, DocDevHelpPlugin, DocDjvuPlugin, DocDoxygenPlugin, DocKDevTOCPlugin, DocPDBPlugin, DocPDFPlugin, and DocQtPlugin.

Referenced by ProjectDocumentationPlugin::pluginName().

virtual ProjectDocumentationPlugin* DocumentationPlugin::projectDocumentationPlugin ProjectDocType  type  )  [inline, virtual]
 

Returns associated project documentation plugin.

Default implementation returns zero. Reimplement this if the documentation plugin can also handle project documentation.

Reimplemented in DocCustomPlugin, DocDevHelpPlugin, DocDjvuPlugin, DocDoxygenPlugin, DocPDBPlugin, and DocPDFPlugin.

Definition at line 312 of file kdevdocumentationplugin.h.

Referenced by DocProjectConfigWidget::accept(), DocPDFPlugin::projectDocumentationPlugin(), DocPDBPlugin::projectDocumentationPlugin(), DocDoxygenPlugin::projectDocumentationPlugin(), DocDjvuPlugin::projectDocumentationPlugin(), DocDevHelpPlugin::projectDocumentationPlugin(), and DocCustomPlugin::projectDocumentationPlugin().

void DocumentationPlugin::reinit KListView contents,
IndexBox index,
QStringList  restrictions
[virtual]
 

Reloads a list of catalogs.

This method should add missing catalogs to the view, update index for added catalogs and also delete restricted catalogs.

Parameters:
contents the listview to fill with catalogs
index the listbox with index to update
restrictions the list of catalogs names to remove

Definition at line 452 of file kdevdocumentationplugin.cpp.

References catalogEnabled(), clearCatalogIndex(), config, createCatalog(), deletedConfigurationItems, KConfig::entryMap(), indexEnabled(), indexes, kdDebug(), loadIndex(), m_indexCreated, namedCatalogs, KConfigBase::readPathEntry(), IndexBox::setDirty(), and KConfigBase::setGroup().

void DocumentationPlugin::reload  )  [virtual]
 

Reloads documentation catalogs and indices.

Definition at line 276 of file kdevdocumentationplugin.cpp.

References catalogs, clear(), and createTOC().

void DocumentationPlugin::saveCatalogConfiguration KListView configurationView  )  [virtual]
 

Saves catalog configuration basing on configurationView and deletedConfigurationItems contents.

If you use KConfig to store configuration, it is important that you call KConfig::sync() method after saving.

Definition at line 526 of file kdevdocumentationplugin.cpp.

References config, ConfigurationItem::contents(), deletedConfigurationItems, KConfigBase::deleteEntry(), ConfigurationItem::fullTextSearch(), ConfigurationItem::index(), ConfigurationItem::isChanged(), ConfigurationItem::origTitle(), KConfigBase::setGroup(), KConfigBase::sync(), ConfigurationItem::title(), ConfigurationItem::url(), KConfigBase::writeEntry(), and KConfigBase::writePathEntry().

void DocumentationPlugin::setCapabilities int  caps  )  [inline, protected]
 

Sets capabilities of documentation plugin.

Definition at line 329 of file kdevdocumentationplugin.h.

References m_capabilities.

void DocumentationPlugin::setCatalogEnabled const QString name,
bool  e
[virtual]
 

Enables or disables documentation catalog.

Definition at line 591 of file kdevdocumentationplugin.cpp.

References config, KConfigBase::group(), KConfigBase::setGroup(), and KConfigBase::writeEntry().

virtual void DocumentationPlugin::setCatalogURL DocumentationCatalogItem item  )  [pure virtual]
 

Sets the URL to the catalog.

This method will be called each time user clicks the documentation item. If it is too much overhead to determine the documentation catalog url in createCatalog method then you can set it here.

Implemented in DocCHMPlugin, DocCustomPlugin, DocDevHelpPlugin, DocDjvuPlugin, DocDoxygenPlugin, DocKDevTOCPlugin, DocPDBPlugin, DocPDFPlugin, and DocQtPlugin.

Referenced by DocumentationCatalogItem::activate(), and FindDocumentation::searchInContents().

void DocumentationPlugin::setDirtyIndex bool  dirty  )  [inline]
 

Sets dirty flag for all indices.

Index caching algorythm will update the cache next time createIndex is called.

Definition at line 299 of file kdevdocumentationplugin.h.

References m_indexCreated.

void DocumentationPlugin::setIndexEnabled DocumentationCatalogItem item,
bool  e
[virtual]
 

Enables or disables index for documentation catalog.

Definition at line 565 of file kdevdocumentationplugin.cpp.

References config, KConfigBase::group(), KConfigBase::setGroup(), and KConfigBase::writeEntry().


Friends And Related Function Documentation

friend class DocumentationCatalogItem [friend]
 

Definition at line 353 of file kdevdocumentationplugin.h.

Referenced by DocPDFPlugin::createCatalog(), DocPDBPlugin::createCatalog(), DocDjvuPlugin::createCatalog(), DocCustomPlugin::createCatalog(), and DocCHMPlugin::createCatalog().

friend class IndexItemProto [friend]
 

Definition at line 352 of file kdevdocumentationplugin.h.

Referenced by DocQtPlugin::createIndex(), DocKDevTOCPlugin::createIndex(), DocDevHelpPlugin::createIndex(), DocDoxygenPlugin::createIndexFromTag(), and loadCachedIndex().


Member Data Documentation

QValueList<DocumentationCatalogItem*> DocumentationPlugin::catalogs [protected]
 

A list of loaded documentation catalogs.

Definition at line 322 of file kdevdocumentationplugin.h.

Referenced by addCatalog(), clear(), clearCatalog(), createIndex(), and reload().

KConfig* DocumentationPlugin::config [protected]
 

Configuration object used by a plugin.

Definition at line 340 of file kdevdocumentationplugin.h.

Referenced by autoSetup(), catalogEnabled(), indexEnabled(), init(), loadCatalogConfiguration(), reinit(), saveCatalogConfiguration(), setCatalogEnabled(), and setIndexEnabled().

QStringList DocumentationPlugin::deletedConfigurationItems [protected]
 

Stores items deleted from configuration.

saveCatalogConfiguration uses this to remove entries from configuration file.

Definition at line 337 of file kdevdocumentationplugin.h.

Referenced by deleteCatalogConfiguration(), reinit(), and saveCatalogConfiguration().

QMap<DocumentationCatalogItem*, QValueList<IndexItemProto*> > DocumentationPlugin::indexes [protected]
 

A map of indices of loaded documentation catalogs.

Definition at line 326 of file kdevdocumentationplugin.h.

Referenced by cacheIndex(), clearCatalog(), clearCatalogIndex(), IndexItemProto::IndexItemProto(), and reinit().

int DocumentationPlugin::m_capabilities [private]
 

Definition at line 348 of file kdevdocumentationplugin.h.

Referenced by hasCapability(), and setCapabilities().

bool DocumentationPlugin::m_indexCreated [private]
 

Definition at line 349 of file kdevdocumentationplugin.h.

Referenced by createIndex(), reinit(), and setDirtyIndex().

QMap<QString, DocumentationCatalogItem*> DocumentationPlugin::namedCatalogs [protected]
 

A map of names of loaded documentation catalogs.

Definition at line 324 of file kdevdocumentationplugin.h.

Referenced by addCatalog(), clearCatalog(), loadCatalogConfiguration(), and reinit().


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for KDevelop Version 3.1.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Tue Feb 22 09:41:28 2005 by doxygen 1.3.9.1 written by Dimitri van Heesch, © 1997-2003