Warning, /office/calligra/plugins/chartshape/ARCHITECTURE is written in an unsupported language. File is not indexed.
0001 This text provides a very short introduction to the architecture of 0002 the chart shape. At this time it's work in progress. 0003 0004 0005 Part I: Components 0006 0007 Part I describes the organization of the code and what can be found 0008 where. 0009 0010 0011 Subdirectories 0012 ============== 0013 0014 dialogs/ various dialogs for the chart tool 0015 commands/ undo/redo commands 0016 tests/ test code -- run it by 'make tests' in the build dir 0017 0018 0019 Classes in the top directory 0020 ============================ 0021 0022 Shape classes 0023 ------------- 0024 ChartShapeFactory All these classes are standard KoShape classes 0025 ChartShape 0026 ChartToolFactory 0027 ChartTool 0028 ChartConfigWidget 0029 0030 chartshape.desktop The desktop file describing this plugin 0031 0032 ChartDocument This class inherits KoDocument. The chart and 0033 the formula are special shapes because they 0034 are their own document types, defined in 0035 ODF. This also means that they can be saved in 0036 a subdirectory or inline inside the XML tree. 0037 0038 0039 Chart classes 0040 ------------- 0041 0042 The following classes are central in the loading, rendering and 0043 editing of charts. Most (all?) of the classes directly represent a 0044 chart entity defined in the ODF standard. 0045 0046 Axis data about an axis in the chart 0047 DataSet data _about_ a dataset. The actual data 0048 is stored in a table. 0049 Legend stores information about the legend 0050 PlotArea the main area where the chart itself is shown 0051 Surface wall or floor in a 3D chart 0052 CellRegion a region in e.g. a spreadsheet where a dataset 0053 can fetch its values. 0054 0055 0056 Data classes 0057 ------------ 0058 0059 KChartModel Takes a list of DataSet's and compiles them 0060 into a QAbstractItemModel for use with KChart. 0061 KChartConversions Conversions between odf concepts and KChart 0062 concepts 0063 0064 ChartProxyModel Factory for DataSets and decoration of a 0065 ChartTableModel . 0066 TableSource FIXME: Something to do with connection to Sheets. 0067 OdfLoadingHelper Helper for loading data when connected to a 0068 spreadsheet. FIXME: find out more. 0069 0070 ChartTableModel Stores the numeric data if this isn't provided 0071 from the outside, e.g. from a spreadsheet. 0072 ChartTableView A view of a table. Used in the data editor. 0073 0074 0075 Helper classes 0076 -------------- 0077 0078 kochart_global Common definitions of enums and some 0079 category functions 0080 CellRegionStringValidator Validates a cell region descriptor string 0081 ChartLayout Manages the layout of the parts (plot area, 0082 legend, titles, etc) 0083 ScreenConversions Conversions between pt (distance) and px (pixels) 0084 SingleModelHelper FIXME: No idea what this is 0085 TextLabelDummy Place holder for text labels (title, etc) 0086 0087 0088 0089 Part II: Functional description 0090 0091 Part II contains high-level descriptions on key structures and 0092 processes. 0093 0094 0095 General Architecture 0096 ==================== 0097 0098 The chart shape is a rather complex shape that inherits KoShape. It is 0099 also at the same time a KoShapeContainer, i.e. it can contain other 0100 KoShapes. The parts of a chart -- plot area, legend, axes titles, 0101 chart title, subtitle and footer -- are all KoShapes themselves, owned 0102 by the ChartShape class. The geometric relationship between them is 0103 managed by the ChartLayout class. This is especially visible when 0104 resizing the chart, something which sometimes rearranges the chart 0105 drastically if the available area becomes very small. 0106 0107 The chart shape is also special because it publishes a small part of 0108 its internal API to the world. Normally the only external API for a 0109 shape is the generic one defined in KoShape.h. The more detailed API 0110 that is used by the tool(s) is seldom published. However, the chart 0111 shape is designed to be used by applications and controlled 0112 programmatically, e.g. from the spreadsheet. When a user updates the 0113 cell values then the chart also has to be updated. This API is 0114 published in interfaces/KoChartInterface.h. (As a side note, I think 0115 this could be done for more shapes.) 0116 0117 The second thing that makes the chart shape special is that Charts 0118 (and Formulas) are defined as their own document types in the ODF 0119 standard. This means that a chart can actually be its own standalone 0120 document with the file extension .odc. Everything that has to do with 0121 the chart document is collected into the class ChartDocument. 0122 0123 The actual rendering of the chart parts is done with the KChart 0124 engine from KDE. KChart can render most chart types in ODF with 0125 the exception of 3D type charts. Surface charts are not handled at 0126 all, and 3D variants of 2D charts (bar, line, etc) are shown with 0127 simple extrusions and not real perspective 3D. 3D only types, like 0128 cylinder, cone, etc are not handled at all. Nevertheless, KChart is 0129 quite capable and works well in general. 0130 0131 0132 ODF and KChart 0133 --------------- 0134 0135 As described above, there are a number of classes which directly 0136 represent entities in the ODF chart standard. These are Axis, Legend, 0137 PlotArea, Surface, DataSet, and CellRegion. All these classes load and 0138 save their internal data to the ODF xml tree and also manage their 0139 respective counterparts from KChart, so for instance the Axis class 0140 handles all settings and data of the KChartAxis classes (different 0141 ones for Cartesian and Circular axes). 0142 0143 Unfortunately there is not a perfect 1-to-1 relationship between the 0144 concepts in ODF charts and KChart so there is some complexity in the 0145 mapping between them. See below for more details. 0146 0147 0148 KChart concepts 0149 ================ 0150 0151 Objects 0152 ------- 0153 0154 KChart is a library of classes that are used to show a chart and also 0155 offers some interaction with them. All the classes are in the KChart 0156 namespace but in the description below we shall forego the namespace 0157 prefix in the interest of clarity. 0158 0159 The main class in KChart is _Chart_. This class manages the rest of 0160 the classes and represents the canvas on which the chart parts are 0161 painted. On this Chart there can be zero or more _Diagrams_, each of 0162 which is what we in daily talk call a 'chart'. There is one type of 0163 subclass to Diagram for each chart type, e.g. PieDiagram or 0164 BarDiagram. If we want to create new types we can subclass 0165 AbstractDiagram. 0166 0167 Each diagram is associated with a CoordinatePlane which defines the 0168 scale and transformation between data coordinates and pixel 0169 coordinates. There are 3 types of coordinate planes: Cartesian, Polar 0170 and Radar. One coordinate plane can be shared by several diagrams, 0171 making it possible to e.g. create a combined bar and line chart. 0172 0173 A Chart can hold several CoordinatePlanes and/or Diagrams, making it 0174 possible to create advanced layouts with separate diagrams or diagrams 0175 that overlap. 0176 0177 An _Axis_ is what connects the coordinate plane with a diagram. The 0178 axis is owned by a diagram but can also be associated with other 0179 diagrams, thereby creating a shared axis. 0180 0181 In addition to diagrams there are other types of visible objects on 0182 the Chart: Legends, Headers, Footers, or custom elements that inherit 0183 KChart::Area. 0184 0185 A KChart::Chart is a QWidget, as are many other KChart objects. The 0186 Legend is the only object that can be placed outside this widget 0187 according to the documentation. 0188 0189 0190 Styling 0191 ------- 0192 0193 Each type of object (Diagram, Axis, etc) in KChart has a set of 0194 attributes associated with it, much like ODF styles. These are all 0195 named after the object they describe, e.g. BarAttributes, 0196 RulerAttributes, etc. 0197 0198 The normal way to configure an object is to fetch out the attributes, 0199 change some of them, and put them back into the object. 0200 0201 0202 Data 0203 ---- 0204 0205 KChart uses the Qt4 model/view paradigm. A class that inherits 0206 AbstractDiagram is at the same time a QAbstractItemView and takes a 0207 QAbstractItemModel as its data input. 0208 0209 The item models that are given to the diagrams combine the numeric 0210 data in that is presented in the chart with some styling coming from 0211 the datasets, e.g. color, marker, etc. 0212 0213 0214 Mapping ODF concepts to KChart classes 0215 ======================================= 0216 0217 The main KChart::Chart instance is owned by PlotArea. PlotArea also 0218 holds 2 cartesian coordinate plane, one polar and one radar 0219 plane. Third, it holds a list of Diagrams, one per diagram type that 0220 was ever used(?). 0221 0222 The KChart::Chart can show headers, footers, axis labels and other 0223 text items. The chart shape does not use this but instead uses 0224 standard text shapes for them. There are several reasons for this: 0225 - The KChart items are not interactively editable and styleable 0226 - They cannot be easily moved around 0227 - The loading and saving of them would be much more difficult, 0228 especially if rich text is used. 0229 This means that the Chart inside the plotarea will only contain the 0230 diagrams and axes; all other areas are shown outside the Chart, but 0231 inside the ChartShape. 0232 0233 Each class that represents an ODF type (Axis, Legend, etc) also has 0234 ownership of the corresponding KChart type. Some exceptions exist 0235 (FIXME: Check this in more detail). 0236 0237 The class ChartProxyModel connects the ODF Datasets and numeric data 0238 with KChart. It takes the numeric input and rearranges it in the 0239 order that is necessary for each chart type. 0240 0241 0242 Editing 0243 ======= 0244 0245 Editing of the chart settings can be done only by the ChartTool. The 0246 chart tool uses the API calls in the different storage classes to 0247 change the values. All manipulations are direct and there is currently 0248 no undo/redo with the exception of setting the chart type. [This needs 0249 to be fixed.] 0250 0251 Changing of the data values can be done through the sheet connection 0252 model that are used by e.g. Calligra Sheets (FIXME: Find out more 0253 details). 0254 0255 0256 Using External Data Sources 0257 =========================== 0258 0259 E.g. spreadsheets FIXME: find out more and write this. 0260