sheets/doc/Interfaces.dox

0001 /**
0002  * \page interfaces Interfaces
0003  * \author Stefan Nikolaus
0004  * \date 2008-08-21
0005  *
0006  *
0007  * \section intro Introduction
0008  * This page describes how external applications can interact with Calligra Sheets.
0009  *
0010  * \subsection resources Development Resources
0011  * The interfaces are located in KoTableInterface.h.
0012  * Pointers to them are stored as canvas resources (KoResourceManager).
0013  *
0014  * \subsection ranges About Cell Ranges
0015  * Calligra Sheets is able to export data from and import data to cell ranges. Those cell
0016  * ranges will be modified by column/row/cell range insertions/removals, as every
0017  * other cell range does. I.e. their location is variable and external applications
0018  * need to get informed about their movements.
0019  * For this case, Calligra Sheets' interfaces provide methods, that return an <b>extended
0020  * model</b> - extended by a method returning the current cell range address.
0021  *
0022  *
0023  *
0024  *
0025  * \section export Data Export
0026  * \par Status
0027  *      design not fixed yet; not implemented yet
0028  * \par Example usage
0029  *      Charts
0030  *
0031  * The interface for exporting data to external applications is called KoTable::SourceRangeManager.
0032  *
0033  * To export data there's a method that takes a cell range address and returns an extended model.
0034  * The model gets informed of value changes and it informs its views (or its users in general).
0035  *
0036  * In order to remove a cell range, that acts as data source, a method taking the extended model
0037  * as parameter is provided.
0038  *
0039  *
0040  *
0041  *
0042  * \section import Data Import
0043  * \par Status
0044  *      design not fixed yet; not implemented yet
0045  * \par Example usage
0046  *      Database queries
0047  *
0048  * The interface for importing data from external applications is called KoTable::TargetRangeManager.
0049  *
0050  * It provides a method, that takes a cell range address and an arbitrary data model. The method
0051  * returns an extended model, a proxy model for the provided data model, in order to deliver the
0052  * variable cell range address.
0053  * If the external application does not want to provide a model itself, but just wants to write
0054  * to the cell range, the data model parameter can also be null. Then, a writable table model is
0055  * created by Calligra Sheets and returned as extended model.
0056  *
0057  * In order to remove a cell range, that retrieves external data, a method taking the extended model
0058  * as parameter is provided.
0059  *
0060  * The TargetRangeManager implementation needs to track the model signals indicating data changes
0061  * and column/row insertions/removals. It has the task to write the data into the value storage.
0062  *
0063  * Most of the database range settings (OpenDocument v1.1, 8.6.1 Database range) should be passed to
0064  * the creation method, collected in one parameter.
0065  * Optionally, a dialog should be shown asking for exactly the same settings on creation. The passed
0066  * ones should then be taken as defaults, because the defaults may vary for different external data.
0067  * Additionally, a list of config widgets is passed, that will be shown in the same dialog. There,
0068  * the data provider's parameters can be changed, e.g. altering a SQL query, even later after
0069  * creation.
0070  */