/* This file is part of the KDE project Copyright (C) 2004 by Alexander Dymo 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 KDEV_DOC_PLUGIN_H #define KDEV_DOC_PLUGIN_H #include #include #include #include #include #include #include #define CACHE_VERSION "3" /**Documentation list item. Stores the type of a documentation it represents and an URL.*/ class DocumentationItem: public KListViewItem { public: /**Type of documentation which is represented by this item.*/ enum Type { Collection /** URL; typedef QValueList List; IndexItem(IndexBox *listbox, const QString &text); List urls() const; private: IndexBox *m_listbox; }; /**Documentation index view.*/ class IndexBox: public KListBox{ public: IndexBox(QWidget *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(QValueList &items); private: QMap > items; friend class IndexItem; bool m_dirty; }; class QPainter; class QColorGroup; class QFontMetrics; class DocumentationPlugin; /**Documentation configuration item.*/ class ConfigurationItem: public QCheckListItem { public: ConfigurationItem(QListView *parent, DocumentationPlugin * plugin, const QString &title, const QString &url, bool indexPossible, bool fullTextSearchPossible); virtual QString title() const { return m_title; } virtual void setTitle(const QString title) { setText(3, m_title = title); } virtual QString url() const { return m_url; } virtual void setURL(const QString url) { setText(4, m_url = url); } virtual bool isChanged() const { return m_title == m_origTitle; } virtual QString origTitle() const {return m_origTitle; } virtual void paintCell(QPainter *p, const QColorGroup &cg, int column, int width, int align); virtual int width(const QFontMetrics &fm, const QListView *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: QString m_title; QString m_url; QString 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 QObject { Q_OBJECT public: /**Capability of documentation plugin.*/ enum Capability { Index=1 /** catalogLocatorProps() = 0; /**Returns a title of catalog defined by an url parameter.*/ virtual QString catalogTitle(const QString &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.*/ QValueList catalogs; /**A map of names of loaded documentation catalogs.*/ QMap namedCatalogs; /**A map of indices of loaded documentation catalogs.*/ QMap > 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.*/ QStringList deletedConfigurationItems; /**Configuration object used by a plugin.*/ KConfig *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 QObject { Q_OBJECT public: ProjectDocumentationPlugin(DocumentationPlugin *docPlugin, DocumentationPlugin::ProjectDocType type); virtual ~ProjectDocumentationPlugin(); /**Initializes project documentation plugin - creates documentation catalog.*/ virtual void init(KListView *contents, IndexBox *index, const QString &url); /**Deinitializes project documentation plugin - removes documentation catalog.*/ virtual void deinit(); QString pluginName() const; QString 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 KListView *m_contents; class IndexBox *m_index; QString m_url; }; #endif