KSpread Painting

This file describes how the painting of a spreadsheet works and is supposed to work. At present, it is not a complete description.

General

Painting is started by KSpreadCanvas::paintUpdates(). This method calls paintCell() on all visible cells, i.e. it always repaints the entire sheet. This is inefficient, but is OK for most circumstances. There is a bug in bugzilla (#xxxx) which points this out.

Each cell can paint itself. If a number of cells are explicitly merged by the user, then the merged cell is painted by a single call to paintCell() on its upper left corner cell, the "master" cell of the merged group. If paintCell() is called on any of the other cells in the group, a recursive call to paintCell is done on the master cell.
NOTE: This is not yet implemented.

If the content of a cell is wider than the cell itself, then we say that this cell overflows and expands into its neighbors (see Layout below). Currently this only happens for cells that are unmerged. Cells that are merged never expand, but instead show a more text marker. See more details about overflow below.

A border between cells is painted twice:

When the cell on one side of the border is drawn.
When the cell on the other side is drawn.

Layout

Painting is a two-step process. First, makeLayout() is called, which analyzes the content of the cell and checks if it fits into the cell. If it doesn't, two things can happen:

The cell will be painted with a more text marker (a red arrow).
If the cell is left aligned and the cell to the right is empty, the cell can expand into the right cell and obscure it with the content of this cell. If the cell is right aligned, the text can overflow to the left instead. (This is currently slightly buggy.)

The layout code also takes into account if the cell has vertical text, if it is angled, indented text, and so on.

The result of the layout process is the setting of the following variables in a cell:

Values that are calculated during the paint process
d->textX d->textY	Text position within the cell
d->textWidth d->textHeight	The size of the text
d->fmAscent	Ascent value of the font metrics
d->extra()->extraXCells d->extra()->extraYCells	Number of extra cells in X and Y direction
d->extra()->extraWidth d->extra()->extraHeight	Extra width/height brought in by the extra cells
d->extra()->nbLines	Number of lines if multirow
d->strOutText	The text that is shown in the cell.

After the layout process, paintCell() uses these variables to position the text within the cell and also to paint "more text" markers, etc.

The value of extra[XY]Cells and extraWidth/Height can be made non-zero in two ways:

The cell is the master cell of a merged group.
The content is too wide/high, and the cell has expanded into neighboring cells.

Currently these two cases never occur simultaneously. That might change in the future. So, as for now the two cases can be separated by checking if d->extra()->merged[XY]Cells are zero (case 2) or non-zero (case 1).

Overflow

In this context, the word overflow means that the content of a cell is wider than the cell itself. In that case, the extra space that is demanded can be handled in several different ways:

The content can be partially shown, i.e. cut.
The content can overflow into neighbor cell(s). Which cells that are affected is dependent on alignment, if the neighbors are empty, etc, etc.

Borders and overflow

A border that is defined for a cell should never be moved just because the content of the cell overflows. The current version (1.4beta1) does that, but it has to be changed.

Other spreadsheets

Here follows a survey of how a number of spreadsheet programs handle overflow into other cells.

Case		Excel	Gnumeric	Oocalc	KSpread 1.4 (Check these!)	Suggested behaviour
Text in cell Left aligned	Empty cell TtR	Overflows into cell TtR	Overflows into cell TtR	Overflows into cell TtR	Overflows into cell TtR	Overflows into cell TtR OK
Text in cell Left aligned	Non-empty cell TtR	Text is cut no mark	Text is cut no mark	Text is cut arrow TtR	Text is cut arrow TtR	Text is cut arrow TtR OK
Text in Cell Right aligned	Empty cell TtL	Overflows into cell TtL	Overflows into cell TtL	Overflows into cell TtL	Text is cut arrow TtR	Overflows into cell TtL
	Non-empty TtL empty TtR	Text is cut no mark	Text is cut no mark	Text is left aligned(!), overflows into cell TtR	Text is cut arrow TtR	Text is cut arrow TtR OK
	Non-empty TtL non-empty TtR	Text is cut no mark	Text is cut no mark	Text is left aligned(!), cut arrow TtR	Text is cut arrow TtR	Text is cut arrow TtR OK
Number in cell Alignment doesn't matter	Generic format	Precision is reduced	Precision is reduced	"###" is shown	############# (cell is filled)	############# (For now) Preciesion is reduced (Long term)
Number in cell Alignment doesn't matter	Number format	############# (cell is filled)	############# (cell is filled)	"###" is shown	############# (cell is filled)	############# (cell is filled)
Border and overflow left aligned	Text format ordinary cell	??	Right border is not drawn Text overflows TtR	Border stays on cell Text overflows TtR Text covers right border	??	Border stays on cell Text overflows TtR Text covers right border
Border and overflow left aligned	Text format merged cell	??	Gnumeric 1.2.8 can't merge Test with Gnumeric 1.4	Border stays on cell Text is cut	??	Border stays on cell Text is cut(?)

Legend
LA	Left Aligned
RA	Right Aligned
TtR	To the Right
TtL	To the Left