diff options
Diffstat (limited to 'examples/customproxy/doc/src/customproxy.qdoc')
| -rw-r--r-- | examples/customproxy/doc/src/customproxy.qdoc | 85 |
1 files changed, 84 insertions, 1 deletions
diff --git a/examples/customproxy/doc/src/customproxy.qdoc b/examples/customproxy/doc/src/customproxy.qdoc index 8bb02105..288a7149 100644 --- a/examples/customproxy/doc/src/customproxy.qdoc +++ b/examples/customproxy/doc/src/customproxy.qdoc @@ -26,5 +26,88 @@ \image customproxy-example.png - TODO + The interesting thing about custom proxy example is the custom dataset and the corresponding + proxy usage, so we concentrate on that and skip explaining the basic Q3DBars functionality + - for that see \l{Bars Example}. + + This example defines a simple flexible data set \c VariantDataSet where each data item is a + a variant list. Each item can have multiple different values, identified by their index in + the list. In this example, the data set is storing monthly rainfall data, where value in + index one is the year, index two contains the month, and the third value has the amount + of rainfall in that month. + + The custom proxy we provide here is similar to item model based proxies provided by Qt + Data Visualization in that it requires a mapping object to interpret the data. + + Let's take a closer look at the custom classes: + + \section1 VariantDataSet + + \c VariantDataSet class provides a simple API: + + \snippet ../examples/customproxy/variantdataset.h 1 + \dots 0 + \codeline + \snippet ../examples/customproxy/variantdataset.h 0 + + As you can see, the data items are simply QVariantList objects, and the data can be added either + singly or in lists. The only additional functionality provided is clearing the data set and querying + for a reference to the data contained in the set. Signals are emitted when data is added or the set + is cleared. + + \section1 VariantBarDataProxy + + \c VariantBarDataProxy is a subclass of QBarDataProxy and provides a simple API of just getters + and setters for the data set and the mapping: + + \snippet ../examples/customproxy/variantbardataproxy.h 0 + \dots 0 + \codeline + \snippet ../examples/customproxy/variantbardataproxy.h 1 + + On the implementation side, the proxy listens for the changes in the data set and the mapping, + and resolves the data set if any changes are detected. It is not particularly efficient + implementation in that any change will cause re-resolving of the entire data set, but that is not + an issue for this example. The interesting part is the \c resolveDataSet() method: + + \snippet ../examples/customproxy/variantbardataproxy.cpp 0 + + In \c resolveDataSet() method we sort the variant data values into rows and columns based on the + mapping. This is very similar to how QItemModelBarDataProxy handles mapping, except we use + list indexes instead of item model roles here. Once the values are sorted, we generate \c QBarDataArray + out of them, and call \c resetArray() method on the parent class. + + \section1 VariantBarDataMapping + + \c VariantBarDataMapping stores the mapping information between \c VariantDataSet data item indexes + and rows, columns, and values of \c QBarDataArray. It also contains the lists of rows and columns to + be included in the resolved data: + + \snippet ../examples/customproxy/variantbardatamapping.h 0 + \dots 0 + \codeline + \snippet ../examples/customproxy/variantbardatamapping.h 1 + \dots 0 + \codeline + \snippet ../examples/customproxy/variantbardatamapping.h 2 + \dots 0 + \codeline + \snippet ../examples/customproxy/variantbardatamapping.h 3 + + The primary way to use a \c VariantBarDataMapping object is to give the mappings already at the + constructor, though they can be set later individually or all together with \c remap() method. + A signal is emitted if mapping changes. It is basically a simplified version of + QItemModelBarDataMapping adapted to work with variant lists instead of item models. + + \section1 RainfallGraph + + \c RainfallGraph class handles the setup of the graph. The interesting part is the \c addDataSet() + method: + + \snippet ../examples/customproxy/rainfallgraph.cpp 0 + + Bulk of that method is used for populating the variant data set. Once the set is populated, + visualizing the data is trivial with the help of our custom proxy: + + \snippet ../examples/customproxy/rainfallgraph.cpp 1 */ |