*** Introduction ***
You can find here detailed instructions how to add a custom datasource to Kst 
(version 2.x), i.e. make it read a new file format.

Kst offers a plugin-based framework for datasources, allowing you to add support 
for your own datasource (or file format) fairly easily.
You basically need to implement 3 classes derived from classes provided by Kst. 
A good starting point is to copy the sampledatasource/ directory and start 
implementing the functions. It is advisable to have some 
understanding of C++, and to have a look at other implementations, particularly 
the initial svn commit for this file which shows more or less 
all the bits required to add complete support for a new file type, in that case 
Matlab's .mat using the matio/ library.

The use of the excellent QtCreator tool can make your life much easier, with 
code-completion, code navigation and integrated documentation.
If you have plans to develop for Kst, we recommend contacting us on the 
kst@kde.org mailing list to announce your plans and discuss technical
issues as well as to get some support.


*** Outline ***
The way Kst accesses data is completely decoupled from the internal plotting and 
computation logics. Basically, you *have to* implement the following methods for 
your new datasource:
- Test if a file is supported (may be as simple as checking the file extension, 
or some magic number in the header)
- Return the list of scalars, vectors, matrices and strings available. Don't 
worry if only some of the types are supported.
- For a given data item, return the number of samples available
- For a given data item, return a range of values (i.e. samples #100 to #199)
When this is done, just add the new datasource to the build (details below) and 
start debugging (unless you're a code guru and got it right directly)!

On top of that basic functionality, you *may* also add the following optional 
features:
- Support for file or data item metadata, e.g. scalars or strings adding some 
information to the data item like units or experiment conditions.  If you want 
to support metadata, you may want to look at the netCDF datasource which 
currently has a quite extensive support for metadata.  Metadata can be browsed 
via the View->Scalars/Vectors/Strings/Matrices menus.
- Support for real-time (streaming) data, i.e. files which are being written to 
and read/plotted from simultaneously. ASCII and dirfilesource implement such a 
feature (check the internalDataSourceUpdate() method)
- Support for time-based access (warning: this feature is not really used right 
now and probably still has some rough edges)


*** Step-by-step instructions (minimal datasource), based on the matlab example 
*** replace "matlab" with your file type ***
** Step 1: Create the source directory and do the initial configuration **
- Copy the sampledatasource directory (warning: don't copy the .svn 
subfolder!!!): "mkdir matlab; cp sampledatasource/* matlab/"
- Change the names of all files to something more relevant (sampledatasource -> 
matio)
- Edit the contents of the .desktop file, especially the X-KDE-Library entry
- Edit the .pro file (if you are using qmake, which is being deprecated) or the 
[root]/src/datasources/CMakeList.txt file to activate the build.
  If needed, look at other examples to see how to detect the presence of the 
required librqries to make it conditional (check [root]/cmake/modules)
- Once the output of cmake is as wished, the data source will be compiled: start 
filling out the contents of the actual code files

** Step 2: Implement the important classes **
To get your datasource to work, you have to:
  1a) Implement the MatlabSourcePlugin::provides() (trivial)
  1b) Implement MatlabSourcePlugin::understands() 
     For that second function, the easiest is to check only the file extension. 
All plugins are queried to select the most appropriate one.  The plugin which
returns the highest number is chosen.  By convention 100 means the plugin can
certainly understand it, and 0 means it certainly cannot.  80 is a reasonable
number if you are reasonably sure this plugin is correct.
  2) Decide which kind of primitives you want to support. Primitives are scalars 
(1 value), strings, vectors (an array of values) and matrices (2-dimensional 
arrays). 
     The most usual type to support is vector, you will probably want to start 
with that. The interface between Kst core and the datasource plugins uses 
templates. 
     See the definition of DataInterfaceMatlabVector for an example, and note 
that since it uses templates the declaration and implementation have to be in 
the .cpp file.
     The classes you implement (as a minimum MatlabSourcePlugin, MatlabSource 
and DataInterfaceMatlabVector) can be all together in the same file, or one per 
file.
  3) Implement the most important functions: 
      -MatlabSource::MatlabSource 
      -MatlabSource::~MatlabSource
      -MatlabSource::init() - most of the interesting data is usually gathered 
                              and cached into member variables here
      -MatlabSource::readField() - returns a range of values for a given vector, 

  and possibly some others in MatlabSource. 

  4) Implement the interface for each primitive, which is mostly only a thin 
layer above the data source class. Start with DataInterfaceMatlabVector and add 
other types progressively.

Hints: you can use qDebug() as a stream to produce debug output, and the 
Help->Debug Dialog also provides some interesting information, in particular 
plugin loading errors.

** Step 3: Polish **
This step is important, don't neglect it! It is important to check:
- That your code is well documented/commented and easy to understand
- That you don't have crashes or memleaks. Beware the conversions to double, 
this can be tricky and Kst always expects double values!
- If you can add some metadata support. Each primitive supports meta-strings and 
meta-scalars. See netCDF for details.
- Whether you can improve your data source by adding a configuration widget. 
Currently only ASCII provides one, so look there for inspiration (warning: ASCII 
is complex!)
- If performance can be improved (performance is very important to Kst!!!)
- If some sample files can be added to the sample_data/ subdir so that others 
can perform some tests if required

