diff options
Diffstat (limited to 'parts/documentation/interfaces/tdevdocumentationplugin.h')
-rw-r--r-- | parts/documentation/interfaces/tdevdocumentationplugin.h | 423 |
1 files changed, 423 insertions, 0 deletions
diff --git a/parts/documentation/interfaces/tdevdocumentationplugin.h b/parts/documentation/interfaces/tdevdocumentationplugin.h new file mode 100644 index 00000000..ed18a86a --- /dev/null +++ b/parts/documentation/interfaces/tdevdocumentationplugin.h @@ -0,0 +1,423 @@ +/* This file is part of the KDE project + Copyright (C) 2004 by Alexander Dymo <cloudtemple@mksat.net> + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Library General Public + License as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Library General Public License for more details. + + You should have received a copy of the GNU Library General Public License + along with this library; see the file COPYING.LIB. If not, write to + the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. +*/ +#ifndef TDEV_DOC_PLUGIN_H +#define TDEV_DOC_PLUGIN_H + +#include <tqmap.h> +#include <tqvaluelist.h> +#include <tqpair.h> + +#include <tdelistbox.h> +#include <tdelistview.h> +#include <kurl.h> +#include <tdefile.h> + +#define CACHE_VERSION "3" + +/**Documentation list item. +Stores the type of a documentation it represents and an URL.*/ +class DocumentationItem: public TDEListViewItem +{ +public: + /**Type of documentation which is represented by this item.*/ + enum Type { + Collection /**<Collection - a collection of catalogs, folder with catalogs.*/, + Catalog /**<Catalog - a term which defines a document or a group of documents.*/, + Book /**<Book - a document with nested documents.*/, + Document /**<Document.*/ + }; + + DocumentationItem(Type type, TDEListView *parent, const TQString &name); + DocumentationItem(Type type, TDEListView *parent, TDEListViewItem *after, const TQString &name); + DocumentationItem(Type type, TDEListViewItem *parent, const TQString &name); + DocumentationItem(Type type, TDEListViewItem *parent, TDEListViewItem *after, const TQString &name); + + virtual void setURL(const KURL &url) { m_url = url; } + virtual KURL url() const { return m_url; } + + Type type() const { return m_type; } + + void setType(Type t) { + if(t != m_type) { + m_type = t; + init(); + } + } +private: + void init(); + + KURL m_url; + Type m_type; +}; + +class DocumentationPlugin; + +/**Documentation catalog list item.*/ +class DocumentationCatalogItem: public DocumentationItem +{ +public: + DocumentationCatalogItem(DocumentationPlugin* plugin, TDEListView *parent, const TQString &name); + DocumentationCatalogItem(DocumentationPlugin* plugin, DocumentationItem *parent, const TQString &name); + virtual ~DocumentationCatalogItem(); + + DocumentationPlugin* plugin() const { return m_plugin; } + + virtual void setOpen(bool o); + void load(); + + virtual bool isProjectDocumentationItem() const { return m_isProjectDocumentationItem; } + virtual void setProjectDocumentationItem(bool b) { m_isProjectDocumentationItem = b; } + + virtual TQString cacheVersion() const { return ""; } /// should return a short string that identifies the version of the catalog + +protected: + virtual void activate(); + +private: + DocumentationPlugin* m_plugin; + bool isLoaded; + bool isActivated; + bool m_isProjectDocumentationItem; +}; + +class IndexBox; + +/**Prototype of index item. +Prototypes represent an index are used to build index items after index generation.*/ +class IndexItemProto +{ +public: + IndexItemProto(DocumentationPlugin *plugin, DocumentationCatalogItem *catalog, IndexBox *listbox, + const TQString &text, const TQString &description); + ~IndexItemProto(); + + void addURL(const KURL &url) { m_url = url; } + KURL url() const { return m_url; } + TQString text() const { return m_text; } + TQString description() const { return m_description; } + +private: + KURL m_url; + IndexBox *m_listbox; + TQString m_text; + TQString m_description; +}; + +/**Documentation index item.*/ +class IndexItem: public TQListBoxText { +public: + typedef TQPair<TQString, KURL> URL; + typedef TQValueList<URL> List; + + IndexItem(IndexBox *listbox, const TQString &text); + + List urls() const; + +private: + IndexBox *m_listbox; +}; + +/**Documentation index view.*/ +class IndexBox: public TDEListBox{ +public: + IndexBox(TQWidget *parent = 0, const char *name = 0); + + virtual void addIndexItem(IndexItemProto *item); + virtual void removeIndexItem(IndexItemProto *item); + virtual void fill(); + virtual void refill(); + virtual void setDirty(bool dirty); +// virtual void refill(TQValueList<IndexItemProto*> &items); + +private: + TQMap<TQString, TQValueList<IndexItemProto*> > items; + friend class IndexItem; + + bool m_dirty; +}; + +class TQPainter; +class TQColorGroup; +class TQFontMetrics; +class DocumentationPlugin; + +/**Documentation configuration item.*/ +class ConfigurationItem: public TQCheckListItem +{ +public: + ConfigurationItem(TQListView *parent, DocumentationPlugin * plugin, const TQString &title, const TQString &url, + bool indexPossible, bool fullTextSearchPossible); + + virtual TQString title() const { return m_title; } + virtual void setTitle(const TQString title) { setText(3, m_title = title); } + virtual TQString url() const { return m_url; } + virtual void setURL(const TQString url) { setText(4, m_url = url); } + + virtual bool isChanged() const { return m_title == m_origTitle; } + virtual TQString origTitle() const {return m_origTitle; } + + virtual void paintCell(TQPainter *p, const TQColorGroup &cg, int column, int width, int align); + virtual int width(const TQFontMetrics &fm, const TQListView *lv, int c) const; + + bool contents() const { return m_contents; } + void setContents(bool contents) { m_contents = contents; } + bool index() const { return m_index; } + void setIndex(bool index) { m_index = index; } + bool fullTextSearch() const { return m_fullTextSearch; } + void setFullTextSearch(bool fullTextSearch) { m_fullTextSearch = fullTextSearch; } + + bool indexPossible() const { return m_indexPossible; } + bool fullTextSearchPossible() const { return m_fullTextSearchPossible; } + + DocumentationPlugin * docPlugin() { return m_docPlugin; } + +private: + TQString m_title; + TQString m_url; + TQString m_origTitle; + + bool m_contents; + bool m_index; + bool m_fullTextSearch; + + bool m_indexPossible; + bool m_fullTextSearchPossible; + + DocumentationPlugin * m_docPlugin; +}; + + +class ProjectDocumentationPlugin; + +/** +@short 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. +*/ +class DocumentationPlugin: public TQObject +{ + Q_OBJECT + +public: + /**Capability of documentation plugin.*/ + enum Capability { Index=1 /**<index can be built for catalogs*/, + FullTextSearch=2 /**<full text search is possible in catalog locations*/, + CustomDocumentationTitles=4 /**<user can specify titles for documentation catalogs*/, + ProjectDocumentation=8 /**<plugin can handle project API documentation*/, + ProjectUserManual=16 /**<plugin can handle project user manual*/ }; + /**Possible project documentation types.*/ + enum ProjectDocType { APIDocs, UserManual }; + + /**Constructor. Should initialize capabilities of the plugin by using setCapabilities + protected method. For example, + @code + setCapabilities(Index | FullTextSearch); + @endcode + */ + DocumentationPlugin(TDEConfig *pluginConfig, TQObject *parent =0, const char *name =0); + virtual ~DocumentationPlugin(); + + /**Returns the i18n name of the plugin.*/ + virtual TQString pluginName() const = 0; + + /**Creates documentation catalog with given title and url.*/ + virtual DocumentationCatalogItem *createCatalog(TDEListView *contents, const TQString &title, const TQString &url) = 0; + + /**Initialize a list of catalogs. + @param contents the listview to fill with catalogs + */ + virtual void init(TDEListView *contents); + /**Reloads a list of catalogs. This method should add missing catalogs to the view, + update index for added catalogs and also delete restricted catalogs. + @param contents the listview to fill with catalogs + @param index the listbox with index to update + @param restrictions the list of catalogs names to remove + */ + virtual void reinit(TDEListView *contents, IndexBox *index, TQStringList restrictions); + /**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.*/ + virtual void autoSetup(); + /**Plugin specific automatic setup code. This method is called by @ref autoSetup.*/ + virtual void autoSetupPlugin() = 0; + + /**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.*/ + virtual bool catalogEnabled(const TQString &name) const; + /**Enables or disables documentation catalog.*/ + virtual void setCatalogEnabled(const TQString &name, bool e); + + /**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.*/ + virtual bool needRefreshIndex(DocumentationCatalogItem *item) = 0; + /**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.*/ + virtual bool indexEnabled(DocumentationCatalogItem *item) const; + /**Enables or disables index for documentation catalog.*/ + virtual void setIndexEnabled(DocumentationCatalogItem *item, bool e); + /**Builds index for given catalog. This method should fill index with + IndexItem objects. + @param index the listbox which contains index items + @param item the catalog item that holds an index being built + */ + virtual void createIndex(IndexBox *index, DocumentationCatalogItem *item) = 0; + + /**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.*/ + virtual void createTOC(DocumentationCatalogItem *item) = 0; + /**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 @ref createCatalog method then you can set it here.*/ + virtual void setCatalogURL(DocumentationCatalogItem *item) = 0; + virtual TQStringList fullTextSearchLocations() = 0; + + /**Loads catalog configuration and fills configurationView with ConfigurationItem objects.*/ + virtual void loadCatalogConfiguration(TDEListView *configurationView); + /**Saves catalog configuration basing on configurationView and + deletedConfigurationItems contents. If you use TDEConfig to store configuration, + it is important that you call TDEConfig::sync() method after saving.*/ + virtual void saveCatalogConfiguration(TDEListView *configurationView); + /**Adds new catalog to a configuration.*/ + virtual void addCatalogConfiguration(TDEListView *configurationView, + const TQString &title, const TQString &url); + /**Edits catalog configuration.*/ + virtual void editCatalogConfiguration(ConfigurationItem *configurationItem, + const TQString &title, const TQString &url); + /**Removes catalog from configuration. configurationItem should not be removed here.*/ + virtual void deleteCatalogConfiguration(const ConfigurationItem *const configurationItem); + + /**Returns a mode and a filter for catalog locator dialogs.*/ + virtual TQPair<KFile::Mode, TQString> catalogLocatorProps() = 0; + /**Returns a title of catalog defined by an url parameter.*/ + virtual TQString catalogTitle(const TQString &url) = 0; + + /**Reloads documentation catalogs and indices.*/ + virtual void reload(); + /**Clears documentation catalogs and indices.*/ + virtual void clear(); + + /**Checks if documentation plugin has given capability.*/ + bool hasCapability(Capability cap) const { return m_capabilities & cap; } + + /**Sets dirty flag for all indices. Index caching algorythm will update + the cache next time @ref createIndex is called.*/ + void setDirtyIndex(bool dirty) { m_indexCreated = dirty; } + + /**Caches index for documentation catalog. Reimplement this only if custom + caching algorythm is used (do not forget to reimplement also @ref loadCachedIndex + and @ref createIndex).*/ + virtual void cacheIndex(DocumentationCatalogItem *item); + /**Loads index from the cache. Reimplement this only if custom + caching algorythm is used (do not forget to reimplement also @ref cacheIndex + and @ref createIndex).*/ + virtual bool loadCachedIndex(IndexBox *index, DocumentationCatalogItem *item); + + /**Returns associated project documentation plugin. Default implementation returns zero. + Reimplement this if the documentation plugin can also handle project documentation.*/ + virtual ProjectDocumentationPlugin *projectDocumentationPlugin(ProjectDocType /* type */) { return 0; } + +public slots: + /**Creates index and fills index listbox. Reimplement this only if custom + caching algorythm is used (do not forget to reimplement also @ref cacheIndex + and @ref loadCachedIndex).*/ + virtual void createIndex(IndexBox *index); + +protected: + /**A list of loaded documentation catalogs.*/ + TQValueList<DocumentationCatalogItem*> catalogs; + /**A map of names of loaded documentation catalogs.*/ + TQMap<TQString, DocumentationCatalogItem*> namedCatalogs; + /**A map of indices of loaded documentation catalogs.*/ + TQMap<DocumentationCatalogItem*, TQValueList<IndexItemProto*> > indexes; + + /**Sets capabilities of documentation plugin.*/ + void setCapabilities(int caps) { m_capabilities = caps; } + /**Clears index of given catalog.*/ + virtual void clearCatalogIndex(DocumentationCatalogItem *item); + /**Loads index from cache or creates and caches it if does not exist.*/ + void loadIndex(IndexBox *index, DocumentationCatalogItem *item); + + /**Stores items deleted from configuration. @ref saveCatalogConfiguration + uses this to remove entries from configuration file.*/ + TQStringList deletedConfigurationItems; + + /**Configuration object used by a plugin.*/ + TDEConfig *config; + +private: + /**Adds catalog item to catalogs, namedCatalogs and indexes lists and maps.*/ + virtual void addCatalog(DocumentationCatalogItem *item); + /**Removes catalog item from catalogs, namedCatalogs and indexes lists and maps.*/ + virtual void clearCatalog(DocumentationCatalogItem *item); + + int m_capabilities; + bool m_indexCreated; + + +friend class IndexItemProto; +friend class DocumentationCatalogItem; +}; + + +/** +@short Project documentation plugin + +Represents functionality to display project documentation catalog and index in documentation browser. +*/ +class ProjectDocumentationPlugin: public TQObject { + Q_OBJECT + +public: + ProjectDocumentationPlugin(DocumentationPlugin *docPlugin, DocumentationPlugin::ProjectDocType type); + virtual ~ProjectDocumentationPlugin(); + + /**Initializes project documentation plugin - creates documentation catalog.*/ + virtual void init(TDEListView *contents, IndexBox *index, const TQString &url); + /**Deinitializes project documentation plugin - removes documentation catalog.*/ + virtual void deinit(); + + TQString pluginName() const; + TQString catalogURL() const; + +public slots: + /**Performs reinitialization if project documentation has changed (after building api documentation).*/ + virtual void reinit(); + +protected: + DocumentationPlugin *m_docPlugin; + DocumentationCatalogItem *m_catalog; + +private: + DocumentationPlugin::ProjectDocType m_type; + + class KDirWatch *m_watch; + class TDEListView *m_contents; + class IndexBox *m_index; + TQString m_url; +}; + +#endif |