[rkward-cvs] SF.net SVN: rkward: [1198] trunk/rkward/rkward/plugin

[tfry at users.sourceforge.net]

Revision: 1198
          http://svn.sourceforge.net/rkward/?rev=1198&view=rev
Author:   tfry
Date:     2007-01-23 03:48:34 -0800 (Tue, 23 Jan 2007)

Log Message:
-----------
API documentation and a small fix

Modified Paths:
--------------
    trunk/rkward/rkward/plugin/rkcomponentcontext.h
    trunk/rkward/rkward/plugin/rkcomponentmap.cpp
    trunk/rkward/rkward/plugin/rkcomponentmap.h

Modified: trunk/rkward/rkward/plugin/rkcomponentcontext.h
===================================================================
--- trunk/rkward/rkward/plugin/rkcomponentcontext.h	2007-01-22 23:45:03 UTC (rev 1197)
+++ trunk/rkward/rkward/plugin/rkcomponentcontext.h	2007-01-23 11:48:34 UTC (rev 1198)
@@ -26,12 +26,20 @@
 class QDomElement;
 class RKContextHandler;
 
+/** This class keeps a list of components that are useable in a certain context (e.g. x11 device). It also keeps a description of the menu structure(s) that should be used for that context. Note that in order to use the XML-GUI, you should create an RKContextHandler using makeContextHandler().
+
+ at author Thomas Friedrichsmeier
+*/
 class RKContextMap : public RKComponentGUIXML {
 public:
+/** constructor
+ at param id The id of the context */
 	RKContextMap (const QString &id);
+/** destructor */
 	~RKContextMap ();
-
+/** A menu entries to the context map from a .pluginmap file */
 	int create (const QDomElement &context_element, const QString &component_namespace);
+/** Create a context handler for this context. */
 	RKContextHandler *makeContextHandler (QObject *parent);
 protected:
 	void addedEntry (const QString &id, RKComponentHandle * /* handle */);
@@ -41,16 +49,29 @@
 };
 
 
+/** An RKContextHandler can be thought of as an instance of a context. E.g. the x11 device context by itself is just an abstract description. To actually use the context for a given device, an RKContextHandler is used. The normal way to construct an instance of this class is using RKContextMap::makeContextHandler().
 
+The context handler is responsible for
+a) providing a KXMLGUIClient to insert into the GUI
+b) provide and handle KActions to invoke the plugins in the context
+c) provide invoked plugins with context information.
+
+The last part (providing context information) is the most important one in this class. Providing context information works like this: When a plugin is invoked, we look for an RKComponentPropertyBase called "incontext" in the plugin. If it has one, it will be set to the id of this context. If not, it will be ignored. Further context properties can be added to the context handler by calling RKComponentBase::addChild(). These will be set in the invoked plugin in the same way.
+
+ at author Thomas Friedrichsmeier
+*/
 class RKContextHandler : public QObject, public RKComponentBase, public KXMLGUIClient {
 	Q_OBJECT
 friend class RKContextMap;
 protected:
+/** constructor. Protected. Use RKContextMap::makeContextHandler() instead. */
 	RKContextHandler (QObject *parent, const QDomDocument &gui_xml, const QString &id);
+/** desctructor. Should be called automatically, as this is QObject */
 	~RKContextHandler ();
-
+/** add a KAction to the context. To be called from RKContext::makeContextHandler(). */
 	void addAction (const QString &id, RKStandardComponentHandle *handle);
 private slots:
+/** slot to handle plugin activation */
 	void componentActionActivated ();
 private:
 	typedef QMap<const KAction *, RKStandardComponentHandle *> ActionMap;

Modified: trunk/rkward/rkward/plugin/rkcomponentmap.cpp
===================================================================
--- trunk/rkward/rkward/plugin/rkcomponentmap.cpp	2007-01-22 23:45:03 UTC (rev 1197)
+++ trunk/rkward/rkward/plugin/rkcomponentmap.cpp	2007-01-23 11:48:34 UTC (rev 1198)
@@ -264,9 +264,13 @@
 	list = xml->getChildElements (document_element, "context", DL_INFO);
 	for (XMLChildList::const_iterator it=list.constBegin (); it != list.constEnd (); ++it) {
 		QString id = xml->getStringAttribute (*it, "id", QString::null, DL_ERROR);
-		RKContextMap *context = new RKContextMap (id);
+
+		RKContextMap *context = getContextLocal (id);
+		if (!context) {
+			context = new RKContextMap (id);
+			contexts.insert (id, context);
+		}
 		counter += context->create (*it, cnamespace);
-		contexts.insert (id, context);
 	}
 
 	// step 4: included files

Modified: trunk/rkward/rkward/plugin/rkcomponentmap.h
===================================================================
--- trunk/rkward/rkward/plugin/rkcomponentmap.h	2007-01-22 23:45:03 UTC (rev 1197)
+++ trunk/rkward/rkward/plugin/rkcomponentmap.h	2007-01-23 11:48:34 UTC (rev 1198)
@@ -59,11 +59,18 @@
 
 class QDomElement;
 
+/** This class keeps a QDomDocument that is a represenation of the GUI using KDEs XML-GUI format (a ui.rc). Use createMenus () to have it parse the menu descriptions from a .pluginmap file. It will adjust the XML description accordingly. When done, you can use to generated gui_xml to set it as the xmlGUIBuildDocument of a KXMLGUIClient. 
+
+This class represents the common functionality between RKComponentMap and RKContextMap.
+
+ at author Thomas Friedrichsmeier
+*/
 class RKComponentGUIXML {
 protected:
 	RKComponentGUIXML ();
 	~RKComponentGUIXML ();
 
+/** reset the xml file */
 	void clearGUIDescription ();
 
 /** build XMLGUI menus
@@ -86,9 +93,10 @@
 @param index the index position where to insert the new element in the list of children (if no existing match could be found). -1 means insert at the end of the list. */
 	QDomElement findOrCreateElement (QDomElement& parent, const QString& tagname, const QString& name, const QString& label, int index);
 
-/** an entry was added to the menu(s) somewhere. Reimplement, if you want to create a KAction for this */
+/** an entry was added to the menu(s) somewhere. Reimplement, if you want to e.g. create a KAction for this */
 	virtual void addedEntry (const QString & /* id */, RKComponentHandle * /* handle */) {};
 
+/** The generated XML GUI description in KDEs ui.rc format */
 	QDomDocument gui_xml;
 };
 
@@ -116,11 +124,13 @@
 /** clears out (and deletes) all components / plugins */
 	static void clearAll ();
 
-/** returns the component identified by id */
+/** returns the component identified by id, 0 if not found */
 	static RKComponentHandle* getComponentHandle (const QString &id);
+/** look up the id of a component, empty string, if not found */
 	static QString getComponentId (RKComponentHandle* by_component);
 	static RKComponentMap *getMap () { return component_map; };
 	static void initialize ();
+/** returns the context identified by id */
 	static RKContextMap *getContext (const QString &id);
 private:
 /** typedef for easy reference to iterator */


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.