* clarify several points in the api documentation. time to do a techbase tutorial!

* pass the exact match action into exec(). this allows runners the opportunity to store otherwise expensive information in the action and get it back easily

svn path=/trunk/KDE/kdebase/workspace/libs/plasma/; revision=689642

abstractrunner.cpp

@@ -32,6 +32,8 @@ class AbstractRunner::Private
             exactMatch( 0 ),
             actions( new KActionCollection( runner ) )
         {
+            delete exactMatch;
+            actions->clear();
         }
 
         QAction* exactMatch;
@@ -100,7 +102,11 @@ void AbstractRunner::fillMatches( KActionCollection* matches,
 
 void AbstractRunner::runExactMatch()
 {
-    exec( d->term );
+    if (!d->exactMatch) {
+        return;
+    }
+
+    exec(d->exactMatch, d->term);
 }
 
 AbstractRunner::List AbstractRunner::loadRunners( QWidget* parent )

abstractrunner.h

@@ -56,13 +56,19 @@ class PLASMA_EXPORT AbstractRunner : public QObject
          * The action will be activated if the user selects it.
          * If the action is informational only and should not be executed,
          * disable the action with setEnabled( false ).
+         *
+         * If this runner's exact match is selected, the action will not
+         * be triggered, but it will be passed into the exec method.
+         * @see exec
+         *
+         * Ownership of the action passes to the AbstractRunner class.
          */
-        QAction* exactMatch( const QString& command );
+        QAction* exactMatch(const QString& command);
 
         /**
          * @return the last action generated by exactMatch( const QString& )
          */
-        QAction* exactMatch( );
+        QAction* exactMatch();
 
         /**
          * Requests the runner to find possible matches for the search term.
@@ -87,7 +93,7 @@ class PLASMA_EXPORT AbstractRunner : public QObject
          * If the hasOptions() returns true, this method will be called to get
          * the widget displaying the options the user can interact with.
          */
-        virtual QWidget* options( );
+        virtual QWidget* options();
 
         /**
          * Static method is called to load and get a list available of Runners.
@@ -110,6 +116,12 @@ class PLASMA_EXPORT AbstractRunner : public QObject
          * to a maximium of max matches starting at offset in the data set
          * If the action is informational only and should not be executed,
          * disable the action with setEnabled( false ).
+         *
+         * @param matches the action collection to add matches to
+         * @param term the current search term
+         * @param max the maximum number of results to return
+         * @param offset the number of initial results to skip,
+         *               used in conjunction with max
          */
         virtual void fillMatches( KActionCollection* matches,
                                   const QString& term,
@@ -121,18 +133,24 @@ class PLASMA_EXPORT AbstractRunner : public QObject
          * default runner. Other runner's actions will be suggested in the
          * interface. Non-exact matches should be offered via findMatches.
          * The action will be activated if the user selects it.
+         *
+         * @param term the current search term
          */
-        virtual QAction* accepts( const QString& term ) = 0;
+        virtual QAction* accepts(const QString& term) = 0;
 
         /**
          * Take action on the command. What this means is dependant on the
          * particular runner implementation, e.g. some runners may treat
          * command as a shell command, while others may treat it as an
          * equation or a user name or ...
-         * This will be called automatically when the exact match
+         *
-         * QAction is triggered
+         * This will be called automatically when the exact match is
+         * selected.
+         *
+         * @param action the QAction provided via exactMatch
+         * @param command the full command string
          */
-        virtual bool exec( const QString& command ) = 0;
+        virtual bool exec(QAction* action, const QString& command) = 0;
 
     private:
         class Private;