Warning, /office/calligra/sheets/doc/Painting.dox is written in an unsupported language. File is not indexed.
0001 /** 0002 \page painting Painting 0003 \author Inge Wallin (<a href="mailto:inge@lysator.liu.se">inge@lysator.liu.se</a>) 0004 \date 2005-08-14 0005 0006 \par Status: 0007 NEEDS UPDATE (CellView, SheetView) 0008 0009 \section general General 0010 0011 <p>Painting is started by Canvas::paintEvent(). This method 0012 calls paintCell() on all visible cells, i.e. it always repaints the 0013 entire sheet. This is inefficient, but is OK for most circumstances. 0014 There is a <a href="https://bugs.kde.org/show_bug.cgi?id=298497">bug</a> in bugzilla which points this out.</p> 0015 0016 <p>Each cell can paint itself. If a number of cells are explicitly 0017 merged by the user, then the merged cell is painted by a single call 0018 to paintCell() on its upper left corner cell, the "master" cell of the 0019 merged group. If paintCell() is called on any of the other cells in 0020 the group, a recursive call to paintCell is done on the master cell. 0021 </p> 0022 <p><b>NOTE</b>: This is not yet implemented.</p> 0023 0024 <p>If the content of a cell is wider than the cell itself, then we say 0025 that this cell <i>overflows</i> and expands into its neighbors (see 0026 <b>Layout</b> below). Currently this only happens for cells that are 0027 unmerged. Cells that are merged never expand, but instead show a 0028 <i>more text</i> marker. See more details about overflow below.</p> 0029 0030 <p>A border between cells is painted twice: 0031 <ul> 0032 <li>When the cell on one side of the border is drawn. 0033 <li>When the cell on the other side is drawn. 0034 </ul> 0035 </p> 0036 0037 0038 \section layout Layout 0039 0040 <p>Painting is a two-step process. First, makeLayout() is called, which 0041 analyzes the content of the cell and checks if it fits into the cell. 0042 If it doesn't, two things can happen:</p> 0043 0044 <ol> 0045 <li>The cell will be painted with a <i>more text</i> marker (a red 0046 arrow). 0047 0048 <li>If the cell is left aligned and the cell to the right is empty, 0049 the cell can <i>expand</i> into the right cell and obscure it 0050 with the content of this cell. If the cell is right aligned, 0051 the text can overflow to the left instead. (This is currently 0052 slightly buggy.) 0053 </ol> 0054 0055 The layout code also takes into account if the cell has vertical text, 0056 if it is angled, indented text, and so on.</p> 0057 0058 <p>The result of the layout process is the setting of the following 0059 variables in a cell:</p> 0060 0061 <table cellspacing="0" cellpadding="3" border="1"> 0062 <tr> 0063 <th colspan="2">Values that are calculated during the paint process</th> 0064 </tr> 0065 <tr> 0066 <td><pre>d->textX<br>d->textY</pre></td> 0067 <td>Text position within the cell</td> 0068 </tr> 0069 <tr> 0070 <td><pre>d->textWidth<br>d->textHeight</pre></td> 0071 <td>The size of the text</td> 0072 </tr> 0073 <tr> 0074 <td><pre>d->extra()->extraXCells<br>d->extra()->extraYCells</pre></td> 0075 <td>Number of extra cells in X and Y direction</td> 0076 </tr> 0077 <tr> 0078 <td><pre>d->extra()->extraWidth<br>d->extra()->extraHeight</pre></td> 0079 <td>Extra width/height brought in by the extra cells</td> 0080 </tr> 0081 <tr> 0082 <td><pre>d->strOutText</pre></td> 0083 <td>The text that is shown in the cell.</td> 0084 </tr> 0085 </table> 0086 0087 <p>After the layout process, paintCell() uses these 0088 variables to position the text within the cell and also to paint "more 0089 text" markers, etc.</p> 0090 0091 <p>The value of extra[XY]Cells and extraWidth/Height can be made non-zero 0092 in two ways:</p> 0093 <ol> 0094 <li>The cell is the master cell of a merged group. 0095 0096 <li>The content is too wide/high, and the cell has expanded into 0097 neighboring cells. 0098 </ol> 0099 0100 <p>Currently these two cases never occur simultaneously. That might 0101 change in the future. So, as for now the two cases can be separated by 0102 checking if d->extra()->merged[XY]Cells are zero (case 2) or non-zero 0103 (case 1).</p> 0104 0105 0106 \section overflow Overflow 0107 0108 <p>In this context, the word <i>overflow</i> means that the content of 0109 a cell is wider than the cell itself. In that case, the extra space 0110 that is demanded can be handled in several different ways:</p> 0111 0112 <ul> 0113 <li>The content can be partially shown, i.e. cut. 0114 0115 <li>The content can overflow into neighbor cell(s). Which cells that 0116 are affected is dependent on alignment, if the neighbors are 0117 empty, etc, etc. </ul> 0118 0119 <h3>Borders and overflow</h3> 0120 0121 <p>A border that is defined for a cell should never be moved just 0122 because it would be possible, that the content of the cell overflows. 0123 The current version (2.0 alpha) does that, but it has to be changed.</p> 0124 0125 0126 \section other Other Spreadsheets 0127 0128 <p>Here follows a survey of how a number of spreadsheet programs 0129 handle overflow into other cells.</p> 0130 0131 <table cellspacing="0" cellpadding="3" border="1"> 0132 <tr> 0133 <th colspan="2">Case</th> 0134 <th>Excel</th> 0135 <th>Gnumeric</th> 0136 <th>Oocalc</th> 0137 <th>KSpread 2.0 alpha<br><i>(Check these!)</i></th> 0138 <th>Suggested behaviour</th> 0139 </tr> 0140 0141 <tr> 0142 <td rowspan="2"><b>Text in cell<br>Left aligned</b></td> 0143 0144 <td><i>Empty cell TtR</i></td> 0145 <td>Overflows into cell TtR</td> 0146 <td>Overflows into cell TtR</td> 0147 <td>Overflows into cell TtR</td> 0148 <td>Overflows into cell TtR</td> 0149 <td>Overflows into cell TtR<br><b>OK</b></td> 0150 </tr> 0151 <tr> 0152 <td><i>Non-empty cell TtR</i></td> 0153 <td>Text is cut<br>no mark</td> 0154 <td>Text is cut<br>no mark </td> 0155 <td>Text is cut<br>arrow TtR </td> 0156 <td>Text is cut<br>arrow TtR </td> 0157 <td>Text is cut<br>arrow TtR<br><b>OK</b></td> 0158 </tr> 0159 0160 <tr> 0161 <td rowspan="3"><b>Text in Cell<br>Right aligned</b></td> 0162 0163 <td><i>Empty cell TtL</i></td> 0164 <td>Overflows into cell TtL</td> 0165 <td>Overflows into cell TtL</td> 0166 <td>Overflows into cell TtL</td> 0167 <td>Text is cut<br>arrow TtR</td> 0168 <td>Overflows into cell TtL</td> 0169 </tr> 0170 <tr> 0171 <td><i>Non-empty TtL<br>empty TtR</i></td> 0172 <td>Text is cut<br>no mark</td> 0173 <td>Text is cut<br>no mark</td> 0174 <td>Text is left aligned(!),<br>overflows into cell TtR</td> 0175 <td>Text is cut<br>arrow TtR</td> 0176 <td>Text is cut<br>arrow TtR<br><b>OK</b></td> 0177 </tr> 0178 0179 <tr> 0180 <td><i>Non-empty TtL<br>non-empty TtR</i></td> 0181 <td>Text is cut<br>no mark</td> 0182 <td>Text is cut<br>no mark</td> 0183 <td>Text is left aligned(!),<br>cut<br>arrow TtR</td> 0184 <td>Text is cut<br>arrow TtR</td> 0185 <td>Text is cut<br>arrow TtR<br><b>OK</b></td> 0186 </tr> 0187 0188 <tr> 0189 <td rowspan = "2"><b>Number in cell<br>Alignment doesn't matter</b></td> 0190 0191 <td><i>Generic format</i></td> 0192 <td>Precision is reduced</td> 0193 <td>Precision is reduced</td> 0194 <td>"###" is shown</td> 0195 <td>if no thousands separator (BUG!):<br>Precision is reduced</td> 0196 <td>Precision is reduced</td> 0197 </tr> 0198 <tr> 0199 <td><i>Number format</i></td> 0200 <td>#############<br>(cell is filled)</td> 0201 <td>#############<br>(cell is filled)</td> 0202 <td>"###" is shown</td> 0203 <td>if no thousands separator (BUG!):<br>variable precision:<br>precision is reduced<p>otherwise:<br>#############<br>(cell is filled)</td> 0204 <td>variable precision:<br>precision is reduced<p>otherwise:<br>#############<br>(cell is filled)</td> 0205 </tr> 0206 0207 0208 <tr> 0209 <td rowspan="2"><b>Border and overflow<br>left aligned</b></td> 0210 0211 <td><i>Text format<br>ordinary cell</i></td> 0212 <td>??</td> 0213 <td>Right border is not drawn<br>Text overflows TtR</td> 0214 <td>Border stays on cell<br>Text overflows TtR<br>Text covers right border</td> 0215 <td>Border moves TtR<br>Text overflows TtR</td> 0216 <td>Border stays on cell<br>Text is cut</td> 0217 </tr> 0218 0219 <tr> 0220 <td><i>Text format<br>merged cell</i></td> 0221 0222 <td>??</td> 0223 <td>Gnumeric 1.2.8 can't merge<br>Test with Gnumeric 1.4</td> 0224 <td>Border stays on cell<br>Text is cut</td> 0225 <td>Border stays on cell<br>Text is cut</td> 0226 <td>Border stays on cell<br>Text is cut<br><b>OK</b></td> 0227 </tr> 0228 </table> 0229 0230 <p></p> 0231 0232 <table cellspacing="0" cellpadding="3" border="1"> 0233 <tr> 0234 <th colspan="2">Legend</th> 0235 </tr> 0236 0237 <tr> 0238 <td>LA</td><td>Left Aligned</td> 0239 </tr> 0240 <tr> 0241 <td>RA</td><td>Right Aligned</td> 0242 </tr> 0243 <tr> 0244 <td>TtR</td><td>To the Right</td> 0245 </tr> 0246 <tr> 0247 <td>TtL</td><td>To the Left</td> 0248 </tr> 0249 0250 */