The K Desktop Environment

6.2. DCOP Interface

The DCOP interface allows to control Kpl by other KDE applications and scripts.

For a KDE application which should make use of the DCOP interface of Kpl you should include the header file kpl_stub.h, which is installed in the directory $KDEDIR/include. You also need to compile the file kpl_stub.cpp in $KDEDIR/share/apps/kpl and link it to your application. These two files provide the DCOP interface functions of Kpl as methods of the class KplApp_stub. A C++ example demo1.cpp which makes use of them is installed in $KDEDIR/share/apps/kpl.

The KDE XmlRpc Daemon (kxmlrpcd) provides a way to use the DCOP interface of Kpl from scripts written in several languages by remote procedure calls (RPC) with XML and HTTP, even running on another platform. An example demo1.py written in Python is installed in $KDEDIR/share/apps/kpl. It essentially does the same as the C++ example. To run it, you need to unzip the Python XML-RPC library http://www.pythonware.com/downloads/xmlrpc-0.9.8-990621.zip into your Python directory (/usr/lib/python1.5, for instance). Note that the authentification mechanism of kxmlrpcd needs the authentification string as the very first parameter of each interface function call.

To test the DCOP interface of Kpl you also can use the KDE DCOP utilities dcop (command line) and kdcop (GUI).

Unfortunately the XmlRpc Daemon of KDE 2.0.1 still contains a bug resulting in errors due to uncomplete remote procedure calls, when more than 1 Kbytes have to be transferred. This will happen when using functions with very long parameter lists like newFrameItem() (see below). As a workaround, until the problem is fixed in a more profound way, you can apply a patch to the source code of kxmlrpcd. The patch file named kxmlrpcserver-patch is installed in $KDEDIR/share/apps/kpl. It simply increases the size of a buffer from 1 K to 4 K. You will have to unpack the source package of kdebase-2.0.1 (available on ftp://ftp.kde.org/pub/kde/) and to apply the patch in the directory kdebase-2.0.1/kxmlrpc by running
 % patch -p0 < kxmlrpcserver-patch

After that you should run
 % ./configure

in the directory kdebase-2.0.1 and (at least in the directory kdebase-2.0.1/kxmlrpc)
 % make

and (as root)
 % make install

The patched version of kxmlrpc then will be active when you login next time.

The DCOP interface of Kpl provides the following functions:

6.2.1. newPlot

void newPlot();

Erases the current plot.

6.2.2. openPlot

bool openPlot(const QString& url);

Opens a plot file.

Parameters:

url

URL of the file.

Returns: true when succeeded.

6.2.3. openData

bool openData(const QString& url);

Opens a data file.

Parameters:

url

URL of the file.

Returns: true when succeeded.

6.2.4. doPlot

void doPlot();

Performs plot.

6.2.5. savePlot

bool savePlot(const QString& url);

Saves a plot file.

Parameters:

url

URL of the file.

Returns: true when succeeded.

6.2.6. savePS

bool savePS(const QString& url,
            int landscape);

Generates a PostScript file.

Parameters:

url

URL of the file.

landscape

true for landscape orientation.

Returns: true when succeeded.

6.2.7. printPlot

bool printPlot(const QString& printerName,
               const QString& fileName,
               int landscape,
               int numCopies);

Prints current plot.

Parameters:

printerName

name of the printer.

fileName

name of the output file (empty for output to printer).

landscape

true for landscape orientation.

numCopies

number of copies.

Returns: true when succeeded.

6.2.8. setAutoplotOption

void setAutoplotOption(int setting);

Sets autoplot option.

Parameters:

setting

true to plot automatically after changes.

6.2.9. setPathOption

void setPathOption(int setting);

Sets path saving option.

Parameters:

setting

true to save absolute paths.

6.2.10. setBoundingBoxOption

void setBoundingBoxOption(int setting);

Sets calculate PS bounding box option.

Parameters:

setting

true to calculate automatically the box.

6.2.11. setPageFormat

void setPageFormat(double w, double h);

Sets page size.

Parameters:

w

width in cm.

h

height in cm.

6.2.12. setColors

void setColors(const QString& colFrame,
               const QString& colGrid,
               const QString& colData);

Sets default colors (hex-encoded RGB strings, example: "ff" for red).

Parameters:

colFrame

color for frame and labels.

colGrid

color for ticks and grid lines.

colData

color for lines and markers.

6.2.13. setOutputFormat

void setOutputFormat(const QString& pres,
                     int prec);

Sets format for numeric output.

Parameters:

pres

printf() presentation character.

prec

precision.

6.2.14. setAutoplot

void setAutoplot(double x0,
                 double w,
                 double y0,
                 double h,
                 int gridmode,
                 const QString& sx,
                 const QString& sy,
                 const QString& sh,
                 int pathHeading,
                 int ix,
                 int iy,
                 int ie,
                 int logx,
                 int logy,
                 int errbars,
                 int symb,
                 int autoNorm,
                 int autoFit);

Sets Autoplot options.

Parameters:

x0

left page margin in centimeters.

w

width of the data window in centimeters.

y0

bottom page margin in centimeters.

h

height of the data window in centimeters.

gridmode

0 for frame only, 1 for axes with tics, 2 for axes with tics and labels, 3 for grid, 4 for grid with labels.

sx

x axis text.

sy

y axis text.

sh

heading text.

pathHeading

true for heading = path.

ix

x column index.

iy

y column index.

ie

y error column index.

logx

true for logarithmic scaling of x axis.

logy

true for logarithmic scaling of y axis.

errbars

true to plot error bars.

symb

0 for circles, < 0 for different markers, >0 for different line types.

autoNorm

true for automatic normalization.

autoFit

true for automatic parameter fit.

6.2.15. setAutofit

void setAutofit(const QString& path,
                const QString& name,
                int nonLin,
                int errCol,
                const QString& errModPath,
                const QString& errModName,
                int itMax,
                double tol,
                int symb,
                const QString& color,
                int showDlg,
                int savePar,
                int follow);

Sets Autofit parameters.

Parameters:

path

absolute path of the library for the fit function.

name

fit function name.

nonLin

true for nonlinear parameter fits.

errCol

true for data weighing by error column, false for weighing by error model function.

errModPath

absolute path of the library for the error model function.

errModName

error model function name.

itMax

maximum number of iterations (nonlinear fits only).

tol

tolerance level (nonlinear fits only).

symb

function plot: 0 for circles, < 0 for different markers, >0 for different line types.

color

color for function plot.

showDlg

true to display parameter fit dialog.

savePar

true to save resulting parameter files.

follow

true to follow parameter sets in fit series.

6.2.16. loadAutofitPar

bool loadAutofitPar(const QString& url);

Loads Autofit function parameters from file.

Parameters:

url

URL of the file.

Returns: true when succeeded.

6.2.17. setAutofitPar

bool setAutofitPar(int iPar,
                   double value);

Sets Autofit function parameter value.

Parameters:

iPar

parameter index.

value

parameter value.

Returns: true when succeeded.

6.2.18. enableFitPar

bool enableFitPar(int iPar,
                  int fit);

Enables/disables (Auto)fit function parameter.

Parameters:

iPar

parameter index.

fit

true enables parameter fitting.

Returns: true when succeeded.

6.2.19. loadErrModPar

bool loadErrModPar(const QString& url,
                   int iArr);

Loads error model function parameters from file.

Parameters:

url

URL of the file.

iArr

array list index.

Returns: true when succeeded.

6.2.20. setErrModPar

bool setErrModPar(int iPar,
                  double value,
                  int iArr);

Sets error model function parameter value.

Parameters:

iPar

parameter index.

value

parameter value.

iArr

array list index.

Returns: true when succeeded.

6.2.21. deleteItem

bool deleteItem(int iItem);

Deletes plot item.

Parameters:

iItem

item index.

Returns: true when succeeded.

6.2.22. moveItem

bool moveItem(int is,
              int id);

Moves plot item.

Parameters:

is

source item index.

id

destination item index.

Returns: true when succeeded.

6.2.23. newFrameItem

void newFrameItem(double x0,
                  double w,
                  double y0,
                  double h,
                  double xmin,
                  double xmax,
                  double ymin,
                  double ymax,
                  int logx,
                  int logy,
                  int ndigx,
                  int ndigy,
                  const QString& colFrame,
                  const QString& colGrid,
                  double xtic,
                  double ytic,
                  int mticx,
                  int mticy,
                  int gridmode,
                  int iex,
                  int iey,
                  const QString& sx,
                  const QString& sy,
                  const QString& sh,
                  double relSize,
                  int active);

Appends new frame item.

Parameters:

x0

left page margin in centimeters.

w

width in centimeters.

y0

bottom page margin in centimeters.

h

height in centimeters.

xmin

x value of left data window margin in user units.

xmax

x value of right data window margin in user units.

ymin

y value of bottom data window margin in user units.

ymax

y value of top window data margin in user units.

logx

true for logarithmic scaling of x axis.

logy

true for logarithmic scaling of y axis.

ndigx

number of digits for x axis.

ndigy

number of digits for y axis.

colFrame

color for frame and labels.

colGrid

color for grids and tics.

xtic

distance between major tics of x axis.

ytic

distance between major tics of y axis.

mticx

number of intervals between major tics of x axis.

mticy

number of intervals between major tics of y axis.

gridmode

0 for frame only, 1 for axes with tics, 2 for axes with tics and labels, 3 for grid, 4 for grid with labels.

iex

logarithm of normalization factor for x axis.

iey

logarithm of normalization factor for y axis.

sx

x axis text.

sy

y axis text.

sh

heading text.

relSize

relative size of text, markers and lines.

active

true for visible item.

6.2.24. newArrayItem

bool newArrayItem(const QString& path,
                  int ix,
                  int iy,
                  int ie,
                  int istart,
                  int n,
                  int errbars,
                  int symb,
                  const QString& color,
                  double fx,
                  double fy,
                  int active);

Appends new array item.

Parameters:

path

absolute path of the data file.

ix

x column index.

iy

y column index.

ie

y error column index.

istart

start row index.

n

number of data points.

errbars

true to plot error bars.

symb

0 for circles, < 0 for different markers, >0 for different line types.

color

color for data plot.

fx

normalization factor for x values.

fy

normalization factor for y values.

active

true for visible item.

Returns: true when succeeded.

6.2.25. newFunItem

bool newFunItem(const QString& path,
                const QString& name,
                double xmin,
                double xmax,
                double dx,
                int symb,
                const QString& color,
                double fx,
                double fy,
                int active);

Appends new function item.

Parameters:

path

absolute path of the function library.

name

function name.

xmin

minimum argument value.

xmax

maximum argument value.

dx

argument stepsize.

symb

0 for circles, < 0 for different markers, >0 for different line types.

color

color for function plot.

fx

normalization factor for x values.

fy

normalization factor for y values.

active

true for visible item.

Returns: true when succeeded.

6.2.26. newParFunItem

bool newParFunItem(const QString& pathx,
                   const QString& namex,
                   const QString& pathy,
                   const QString& namey,
                   double tmin,
                   double tmax,
                   double dt,
                   int symb,
                   const QString& color,
                   double fx,
                   double fy,
                   int active);

Appends new parametric function item.

Parameters:

pathx

absolute path of the x function library.

namex

x function name.

pathy

absolute path of the y function library.

namey

y function name.

tmin

minimum argument value.

tmax

maximum argument value.

dt

argument stepsize.

symb

0 for circles, < 0 for different markers, >0 for different line types.

color

color for function plot.

fx

normalization factor for x values.

fy

normalization factor for y values.

active

true for visible item.

Returns: true when succeeded.

6.2.27. newLegendItem

void newLegendItem(int symb,
                   const QString& colSymb,
                   double x,
                   double y,
                   const QString& text,
                   const QString& colText,
                   double xoff,
                   double yoff,
                   double relSize,
                   int active);

Appends new legend item.

Parameters:

symb

0 for circles, < 0 for different markers, >0 for different line types.

colSymb

color for marker or line.

x

x position in cm.

y

y position in cm.

text

legend text.

colText

color for text.

xoff

x offset for text in cm.

yoff

y offset for text in cm.

relSize

relative size of text.

active

true for visible item.

6.2.28. autoScaleFrame

bool autoScaleFrame(int iItem,
                    int autoNorm);

Scales frame automatically corresponding to all child items.

Parameters:

iItem

item index.

autoNorm

true for automatic normalization.

Returns: true when succeeded.

6.2.29. loadPar

bool loadPar(const QString& url,
             int iItem,
             int yFun);

Loads function parameters from file.

Parameters:

url

URL of the file.

iItem

item index.

yFun

true for y function parameter, false for x function parameter (only for parametric functions).

Returns: true when succeeded.

6.2.30. setPar

bool setPar(int iItem,
            int iPar,
            double value,
            int yFun);

Sets function parameter value.

Parameters:

iItem

item index.

iPar

parameter index.

value

parameter value.

yFun

true for y function parameter, false for x function parameter (only for parametric functions).

Returns: true when succeeded.

6.2.31. setArrayRange

bool setArrayRange(int iItem,
                   int iStart,
                   int n);

Sets array row range.

Parameters:

iItem

item index.

iStart

start row index.

n

number of data points.

Returns: true when succeeded.

6.2.32. addFitItems

bool addFitItems(int erase,
                 int iArr,
                 int iFun,
                 int errCol,
                 const QString& errModPath,
                 const QString& errModName);

Adds array and function items to item lists for (multidimensional) parameter fitting.

Parameters:

erase

erases lists first when true.

iArr

array item index.

iFun

function item index.

errCol

true for data weighing by error column, false for weighing by error model function.

errModPath

absolute path of the library for the error model function.

errModName

error model function name.

Returns: true when succeeded.

6.2.33. fit

bool fit(int nonLin,
         int savePar,
         int follow);

Performs parameter fit.

Parameters:

nonLin

true for nonlinear parameter fits.

savePar

true to save resulting parameter files.

follow

true to follow parameter sets in fit series.

Returns: true when succeeded.

6.2.34. chiSquare

double chiSquare();

Returns chi-square of last fit.

Returns: chi-square.

6.2.35. saveFitPar

bool saveFitPar(const QString& url);

Saves parameters and their errors resulting from a fit to a file.

Parameters:

url

URL of the file.

Returns: true when succeeded.

6.2.36. exportValues

bool exportValues(const QString& url,
                  int iItem);

Exports function value table to file.

Parameters:

url

URL of the file.

iItem

item index.

Returns: true when succeeded.