Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdesdk@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 108 insertions, 0 deletions

diff --git a/cervisia/cvsservice/DESIGN b/cervisia/cvsservice/DESIGN
new file mode 100644
index 00000000..cbd414da
--- /dev/null
+++ b/cervisia/cvsservice/DESIGN
@@ -0,0 +1,108 @@
+OVERVIEW
+--------
+
+The cvs DCOP service consists of the following three parts:
+
+1. CvsService - The main interface to the functionality of the cvs command line
+                client. There is one method for each cvs command, e.g. add,
+                checkout, commit, etc... The methods assemble the command line
+                arguments, create a CvsJob and return a DCOPRef object for it
+                to the caller. There is one instance of this service for each
+                application instance.
+
+2. Repository - This DCOPObject manages the configuration data of the current
+                cvs repository. The data is automatically updated when other
+                service instances change it.
+
+3. CvsJob     - This class represents a cvs job. You can execute and cancel it,
+                and you can retrieve the output of the cvs client by either
+                connecting to the proper DCOP signals or by using the output()
+                method. There are two types of jobs. First the non-concurrent
+                job which has to run alone, like cvs update or import. Second
+                the jobs which can run concurrently like cvs log or annotate.
+
+USAGE
+-----
+
+How-to use this service in C++ applications:
+
+    // start DCOP service
+    QString error;
+    QCString appId;
+
+    KApplication::startServiceByDesktopName("cvsservice", QStringList(), &error,
+                                            &appId);
+
+    // create stub for repository
+    Repository_stub repository(appId, "CvsRepository");
+
+    // set directory of working copy
+    repository.setWorkingCopy("/home/user/kde/kdesdk/cervisia");
+
+    // create stub for service
+    CvsService_stub cvsService(appId, "CvsService");
+
+    // call "cvs log" for cervisiapart.h
+    DCOPRef job = cvsService.log("cervisiapart.h");
+
+    // connect to signals to get output
+    connectDCOPSignal(job.app(), job.obj(), "jobExited(bool, int)", [MY SLOT]);
+    connectDCOPSignal(job.app(), job.obj(), "receivedStdout(QString)",
+                      [MY SLOT]);
+
+    // execute the cvs command
+    job.execute();
+
+
+How-to use this service in a shell script:
+
+    #!/bin/sh
+
+    # start DCOP service
+    APP=`dcopstart cvsservice`
+
+    # set directory of working copy
+    dcop $APP CvsRepository setWorkingCopy /home/user/kde/kdesdk/cervisia
+
+    # call "cvs log" for cervisiapart.h
+    JOB=`dcop $APP CvsService log cervisiapart.h`
+
+    # execute the cvs command
+    dcop $JOB execute
+
+    # print the output on stdout
+    dcop $JOB output
+
+    # stop DCOP service
+    dcop $APP CvsService quit
+
+
+How-to use this service in a javascript:
+
+    #!/usr/bin/env kjscmd
+
+    var client = new DCOPClient(this);
+    if ( client.attach() )
+    {
+        // start DCOP service
+        var appID = client.dcopStart("cvsservice");
+
+        // set directory of working copy
+        client.send(appID, "CvsRepository", "setWorkingCopy(QString)", "/home/user/kde/kdesdk/cervisia");
+
+        // call "cvs log" for cervisiapart.h
+        var job = client.call(appID, "CvsService", "log(QString)", "cervisiapart.h");
+
+        // execute the cvs command
+        job.call("execute()");
+
+        // wait for job to finish
+        while( job.call("isRunning()") );
+
+        // print the output on stdout
+        var output = job.call("output()");
+        println(output);
+
+        // stop DCOP service
+        client.send(appID, "CvsService", "quit()");
+    }