Warning, /office/calligra/sheets/doc/Dependencies.dox is written in an unsupported language. File is not indexed.

 /**
 \page dependencies Dependency Handling
 \author Ariya Hidayat (<a href="mailto:ariya@kde.org">ariya@kde.org</a>)
 \date 2004
 
 \par Status:
     FINISHED; NEEDS UPDATE (RecalcManager)
 
 <p>When a cell holds a formula, then it is likely that it depends on other
 cell(s) for calculating the result. For example, if cell A11 has the formula
 &quot;=SUM(A1:A10)&quot;, this means that values in cells A1, A2, A3, until
 A10 must be correctly calculated first before the sum can be obtained for
 cell A11. This is called <i>dependency</i>.</p>
 
 <p>As for now, Calligra Sheets tries to manage dependency by storing the dependent
 cells or ranges in the cell itself. This is not too efficient. If a cell
 is very simple, i.e. stored only value, not formula, such scheme will just
 waste a couple of bytes of pointers for the dependency data structure.
 It is much more wiser to simply create one <i>dependency manager</i> for each
 worksheet; it should be responsible for maintaining and handling cell
 dependencies for that sheet. Also Calligra Sheets always stores ranges which depend
 on one particular cell and ranges whose one of its dependent is that cell
 (and these are all in the cell structure itself). This is not necessary as
 that information is redundant. The dependency manager should be able to handle
 both cases.</p>
 
 <p>Let us have a look at this simple example:</p>
 
 <table cellspacing="0" cellpadding="3" border="1">
 <tr>
   <td align="center">&nbsp;</td>
   <td align="center">A</td>
   <td align="center">B</td>
   <td align="center">C</td>
   <td align="center">D</td>
 </tr>
 <tr>
   <td align="center">1</td>
   <td align="right">14</td>
   <td align="right">36</td>
   <td align="right">&nbsp;</td>
   <td align="right">&nbsp;</td>
 </tr>
 <tr>
   <td align="center">2</td>
   <td align="right">3</td>
   <td align="right">&nbsp;</td>
   <td align="right">&nbsp;</td>
   <td align="right">&nbsp;</td>
 </tr>
 <tr>
   <td align="center">3</td>
   <td align="right">77</td>
   <td align="right">&nbsp;</td>
   <td align="right">&nbsp;</td>
   <td align="right">&nbsp;</td>
 </tr>
 <tr>
   <td align="center">4</td>
   <td align="right">=SUM(<b>A1:A3</b>)</td>
   <td align="right">=A4+SUM(<b>B1:B3</b>)</td>
   <td align="right">=100*<b>B4</b></td>
   <td align="right">&nbsp;</td>
 </tr>
 </table>
 
 <p>Such sheet should produce dependencies like:</p>
 
 <table cellspacing="0" cellpadding="3" border="1">
 <tr>
   <td><b>Reference</b></td>
   <td><b>Dependent(s)</b></td>
 </tr>
 <tr>
   <td>A4</td>
   <td>A1:A3</td>
 </tr>
 <tr>
   <td>B4</td>
   <td>A4 and B1:B3</td>
 </tr>
 <tr>
   <td>C4</td>
   <td>B4</td>
 </tr>
 </table>
 
 <p>When we want to recalculate cell B4, from the dependencies shown above we
 may know that first we need to know values of cell A4 and range B1:B3. Further on,
 cell A4 needs to know values of cells in range A1:A3. Therefore, <i>given one reference
 cell</i> (e.g. B4), the dependency manager must be able to <i>return all
 dependents, cells and/or ranges</i> (e.g. A4, B1:B3). Do we need to go
 recursively when searching for dependencies? That really depends on the
 implementation, but it is not a big problem, though.</p>
 
 <p>In another case, say the user has changed cell A3 so we need to update the
 calculation. We should not recalculate the whole sheet because it wastes time.
 We just need to recalculate cells that depend on A3, in this case A4, B4 and C4.
 So the dependency manager has another responsibility: <i>given a cell</i>
 it should <i>find all cells and/or ranges which depend on that particular
 cell</i>. It is a matter of iterating over all dependencies and checking
 whether the cell is within the dependent(s) and returning the reference cell.
 In this example, cell A3 is in the range A1:A3, a dependent range of cell A4.
 Hence, we just return A4. Recursive or not, we can either continue finding
 dependents of A4 or just stop here.</p>
 
 <p>Note also that dependency manager should not store cell pointers, but rather
 only the location of the cell (i.e. the sheet that owns the cell, row number and
 column number). This is because on some cases the dependent cell may not exist
 yet. As illustrated in the example, dependents of cell B4 are A4, B1, B2 and B3
 but here cells B2 and B3 are still empty. Of course, when we just want to
 know which cells we need to recalculate for one reference cell, the dependency
 manager is allowed to return only non-empty cells (e.g. A4 and B1 in our case)
 as empty cells have no effect and will not be recalculated anyway.</p>
 
 <p>By the same manner, dependency manager can also held responsible when
 chart comes into play. Any charts placed in the sheet (that are actually KChart
 parts) depend on some values of the cells. An action by the user to changing
 those cells, directly or indirectly, should trigger the update of the respective
 charts.</p>
 
 <p>Inter-sheet dependencies can be well handled if we store the owner of
 each dependent. This is not shown yet in the explanation above to avoid
 unnecessary complication. But let have one example now: if Sheet2!A1 is
 &quot;=SUM(Sheet1!A1:A10)&quot; then changing Sheet1!A1 (the dependent)
 means updating Sheet2!A1 (the reference). Of course during recalculation we
 must take care that all sheets in the document must be processed, even though
 only one single cell in one sheet has been changed.</p>
 
 */