← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/koffice/oneiric-updates

« back to all changes in this revision

Viewing changes to kspread/doc/Painting.dox

  • Committer: Bazaar Package Importer
  • Author(s): Alessandro Ghersi
  • Date: 2010-10-27 17:52:57 UTC
  • mfrom: (0.12.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20101027175257-s04zqqk5bs8ckm9o
Tags: 1:2.2.83-0ubuntu1
* Merge with Debian git remaining changes:
 - Add build-deps on librcps-dev, opengtl-dev, libqtgtl-dev, freetds-dev,
   create-resources, libspnav-dev
 - Remove needless build-dep on libwv2-dev
 - koffice-libs recommends create-resources
 - krita recommends pstoedit
 - Keep our patches
* New upstream release 2.3 beta 3
  - Remove debian/patches fixed by upstream
  - Update install files

Show diffs side-by-side

added added

removed removed

Lines of Context:
kspread/doc/Painting.dox
 
1
/**
 
2
\page painting Painting
 
3
\author Inge Wallin (<a href="mailto:inge@lysator.liu.se">inge@lysator.liu.se</a>)
 
4
\date 2005-08-14
 
5
 
 
6
\par Status:
 
7
    NEEDS UPDATE (CellView, SheetView)
 
8
 
 
9
\section general General
 
10
 
 
11
<p>Painting is started by Canvas::paintEvent().  This method
 
12
calls paintCell() on all visible cells, i.e. it always repaints the
 
13
entire sheet.  This is inefficient, but is OK for most circumstances.
 
14
There is a bug in bugzilla (#xxxx) which points this out.</p>
 
15
 
 
16
<p>Each cell can paint itself.  If a number of cells are explicitly
 
17
merged by the user, then the merged cell is painted by a single call
 
18
to paintCell() on its upper left corner cell, the "master" cell of the
 
19
merged group.  If paintCell() is called on any of the other cells in
 
20
the group, a recursive call to paintCell is done on the master cell.
 
21
<br>
 
22
<b>NOTE</b>: This is not yet implemented.</p>
 
23
 
 
24
<p>If the content of a cell is wider than the cell itself, then we say
 
25
that this cell <i>overflows</i> and expands into its neighbors (see
 
26
<b>Layout</b> below).  Currently this only happens for cells that are
 
27
unmerged.  Cells that are merged never expand, but instead show a
 
28
<i>more text</i> marker.  See more details about overflow below.</p>
 
29
 
 
30
<p>A border between cells is painted twice:
 
31
<ul>
 
32
  <li>When the cell on one side of the border is drawn.
 
33
  <li>When the cell on the other side is drawn.
 
34
</ul>
 
35
</p>
 
36
 
 
37
 
 
38
\section layout Layout
 
39
 
 
40
<p>Painting is a two-step process.  First, makeLayout() is called, which
 
41
analyzes the content of the cell and checks if it fits into the cell.
 
42
If it doesn't, two things can happen:</p>
 
43
 
 
44
<ol>
 
45
  <li>The cell will be painted with a <i>more text</i> marker (a red
 
46
      arrow).
 
47
 
 
48
  <li>If the cell is left aligned and the cell to the right is empty,
 
49
      the cell can <i>expand</i> into the right cell and obscure it
 
50
      with the content of this cell.  If the cell is right aligned,
 
51
      the text can overflow to the left instead.  (This is currently
 
52
      slightly buggy.)
 
53
</ol>
 
54
 
 
55
The layout code also takes into account if the cell has vertical text,
 
56
if it is angled, indented text, and so on.</p>
 
57
 
 
58
<p>The result of the layout process is the setting of the following
 
59
variables in a cell:</p>
 
60
 
 
61
<table cellspacing="0" cellpadding="3" border="1">
 
62
<tr>
 
63
  <th colspan="2">Values that are calculated during the paint process</th>
 
64
</tr>
 
65
<tr>
 
66
 <td><pre>d->textX<br>d->textY</pre></td>
 
67
 <td>Text position within the cell</td>
 
68
</tr>
 
69
<tr>
 
70
  <td><pre>d->textWidth<br>d->textHeight</pre></td>
 
71
  <td>The size of the text</td>
 
72
</tr>
 
73
<tr>
 
74
  <td><pre>d->extra()->extraXCells<br>d->extra()->extraYCells</pre></td>
 
75
  <td>Number of extra cells in X and Y direction</td>
 
76
</tr>
 
77
<tr>
 
78
  <td><pre>d->extra()->extraWidth<br>d->extra()->extraHeight</pre></td>
 
79
  <td>Extra width/height brought in by the extra cells</td>
 
80
</tr>
 
81
<tr>
 
82
  <td><pre>d->strOutText</pre></td>
 
83
  <td>The text that is shown in the cell.</td>
 
84
</tr>
 
85
</pre>
 
86
</table>
 
87
 
 
88
<p>After the layout process, paintCell() uses these
 
89
variables to position the text within the cell and also to paint "more
 
90
text" markers, etc.</p>
 
91
 
 
92
<p>The value of extra[XY]Cells and extraWidth/Height can be made non-zero
 
93
in two ways:</p>
 
94
<ol>
 
95
  <li>The cell is the master cell of a merged group.
 
96
 
 
97
  <li>The content is too wide/high, and the cell has expanded into
 
98
      neighboring cells.
 
99
</ol>
 
100
 
 
101
<p>Currently these two cases never occur simultaneously.  That might
 
102
change in the future.  So, as for now the two cases can be separated by
 
103
checking if d->extra()->merged[XY]Cells are zero (case 2) or non-zero
 
104
(case 1).</p>
 
105
 
 
106
 
 
107
\section overflow Overflow
 
108
 
 
109
<p>In this context, the word <i>overflow</i> means that the content of
 
110
a cell is wider than the cell itself.  In that case, the extra space
 
111
that is demanded can be handled in several different ways:</p>
 
112
 
 
113
<ul>
 
114
  <li>The content can be partially shown, i.e. cut.
 
115
 
 
116
  <li>The content can overflow into neighbor cell(s). Which cells that
 
117
      are affected is dependent on alignment, if the neighbors are
 
118
      empty, etc, etc.  </ul>
 
119
 
 
120
<h3>Borders and overflow</h3>
 
121
 
 
122
<p>A border that is defined for a cell should never be moved just
 
123
because it would be possible, that the content of the cell overflows.
 
124
The current version (2.0 alpha) does that, but it has to be changed.</p>
 
125
 
 
126
 
 
127
\section other Other Spreadsheets
 
128
 
 
129
<p>Here follows a survey of how a number of spreadsheet programs
 
130
handle overflow into other cells.</p>
 
131
 
 
132
<table cellspacing="0" cellpadding="3" border="1">
 
133
<tr>
 
134
  <th colspan="2">Case</th>
 
135
  <th>Excel</th>
 
136
  <th>Gnumeric</th>
 
137
  <th>Oocalc</th>
 
138
  <th>KSpread 2.0 alpha<br><i>(Check these!)</i></th>
 
139
  <th>Suggested behaviour</th>
 
140
</tr>
 
141
 
 
142
<tr>
 
143
  <td rowspan="2"><b>Text in cell<br>Left aligned</b></td>
 
144
 
 
145
  <td><i>Empty cell TtR</i></td>
 
146
  <td>Overflows into cell TtR</td>
 
147
  <td>Overflows into cell TtR</td>
 
148
  <td>Overflows into cell TtR</td>
 
149
  <td>Overflows into cell TtR</td>
 
150
  <td>Overflows into cell TtR<br><b>OK</b></td>
 
151
</tr>
 
152
<tr>
 
153
  <td><i>Non-empty cell TtR</i></td>
 
154
  <td>Text is cut<br>no mark</td>
 
155
  <td>Text is cut<br>no mark </td>
 
156
  <td>Text is cut<br>arrow TtR </td>
 
157
  <td>Text is cut<br>arrow TtR </td>
 
158
  <td>Text is cut<br>arrow TtR<br><b>OK</b></td>
 
159
</tr>
 
160
 
 
161
<tr>
 
162
  <td rowspan="3"><b>Text in Cell<br>Right aligned</b></td>
 
163
 
 
164
  <td><i>Empty cell TtL</i></td>
 
165
  <td>Overflows into cell TtL</td>
 
166
  <td>Overflows into cell TtL</td>
 
167
  <td>Overflows into cell TtL</td>
 
168
  <td>Text is cut<br>arrow TtR</td>
 
169
  <td>Overflows into cell TtL</td>
 
170
</tr>
 
171
<tr>
 
172
  <td><i>Non-empty TtL<br>empty TtR</i></td>
 
173
  <td>Text is cut<br>no mark</td>
 
174
  <td>Text is cut<br>no mark</td>
 
175
  <td>Text is left aligned(!),<br>overflows into cell TtR</td>
 
176
  <td>Text is cut<br>arrow TtR</td>
 
177
  <td>Text is cut<br>arrow TtR<br><b>OK</b></td>
 
178
</tr>
 
179
 
 
180
<tr>
 
181
<td><i>Non-empty TtL<br>non-empty TtR</i></td>
 
182
<td>Text is cut<br>no mark</td>
 
183
<td>Text is cut<br>no mark</td>
 
184
<td>Text is left aligned(!),<br>cut<br>arrow TtR</td>
 
185
<td>Text is cut<br>arrow TtR</td>
 
186
<td>Text is cut<br>arrow TtR<br><b>OK</b></td>
 
187
</tr>
 
188
 
 
189
<tr>
 
190
  <td rowspan = "2"><b>Number in cell<br>Alignment doesn't matter</b></td>
 
191
 
 
192
  <td><i>Generic format</i></td>
 
193
  <td>Precision is reduced</td>
 
194
  <td>Precision is reduced</td>
 
195
  <td>"###" is shown</td>
 
196
  <td>if no thousands separator (BUG!):<br>Precision is reduced</td>
 
197
  <td>Precision is reduced</td>
 
198
</tr>
 
199
<tr>
 
200
  <td><i>Number format</i></td>
 
201
  <td>#############<br>(cell is filled)</td>
 
202
  <td>#############<br>(cell is filled)</td>
 
203
  <td>"###" is shown</td>
 
204
  <td>if no thousands separator (BUG!):<br>variable precision:<br>precision is reduced<p>otherwise:<br>#############<br>(cell is filled)</td>
 
205
  <td>variable precision:<br>precision is reduced<p>otherwise:<br>#############<br>(cell is filled)</td>
 
206
</tr>
 
207
 
 
208
 
 
209
<tr>
 
210
  <td rowspan="2"><b>Border and overflow<br>left aligned</b></td>
 
211
 
 
212
  <td><i>Text format<br>ordinary cell</i></td>
 
213
  <td>??</td> 
 
214
  <td>Right border is not drawn<br>Text overflows TtR</td>
 
215
  <td>Border stays on cell<br>Text overflows TtR<br>Text covers right border</td>
 
216
  <td>Border moves TtR<br>Text overflows TtR</td>
 
217
  <td>Border stays on cell<br>Text is cut</td>
 
218
</tr>
 
219
 
 
220
<tr>
 
221
  <td><i>Text format<br>merged cell</i></td>
 
222
 
 
223
  <td>??</td>
 
224
  <td>Gnumeric 1.2.8 can't merge<br>Test with Gnumeric 1.4</td>
 
225
  <td>Border stays on cell<br>Text is cut</td>
 
226
  <td>Border stays on cell<br>Text is cut</td>
 
227
  <td>Border stays on cell<br>Text is cut<br><b>OK</b></td>
 
228
 </tr>
 
229
</table>
 
230
 
 
231
<p></p>
 
232
 
 
233
<table cellspacing="0" cellpadding="3" border="1">
 
234
<tr>
 
235
  <th colspan="2">Legend</th>
 
236
</tr>
 
237
 
 
238
<tr>
 
239
  <td>LA</td><td>Left Aligned</td>
 
240
</tr>
 
241
<tr>
 
242
  <td>RA</td><td>Right Aligned</td>
 
243
</tr>
 
244
<tr>
 
245
  <td>TtR</td><td>To the Right</td>
 
246
</tr>
 
247
<tr>
 
248
  <td>TtL</td><td>To the Left</td>
 
249
</tr>
 
250
 
 
251
*/