This file describes how the painting of a spreadsheet 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 cells visible, 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).  This currently 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, and then 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:

1) The cell will be painted with a "more text" marker (a red arrow).

2) 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:
 d->textX			Text position within the cell
 d->textY
 d->textWidth			The size of the text
 d->textHeight
 d->fmAscent
 d->extra()->extraXCells	Number of extra cells
 d->extra()->extraYCells
 d->extra()->extraWidth		Extra width/height brought in by the
 d->extra()->extraHeight        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:

1) The cell is the master cell of a merged group.

2) 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 ones are
   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.  Currently (1,4beta1) does that,
but it has to be changed.


Other spreadsheets
------------------

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

Note: the table is almost 190 characters wide.

Case				Excel				Gnumeric			Oocalc				KSpread				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
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

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(!),	Text is cut, arrow TtR		Text is cut, arrow TtR
												overflows into cell TtR
Non-empty TtL, non-empty TtR	Text is cut, no mark		Text is cut, no mark		Text is left aligned(!),	Text is cut, arrow TtR		Text is cut, arrow TtR
												cut, arrow is drawn TtR

Number in cell, Alignment turned out not to matter
--------------------------------------------------
Generic format	 		Precision is reduced		Precision is reduced		### is shown			############# (cell is filled)	############# (For now)
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	Border stays on cell						Border stays on cell
								Text overflows TtR		Text overflows TtR						Text overflows TtR
												Text covers right border					Text covers right border
Text format, merged cell					Gnumeric 1.2.8 can't merge	Border stays on cell						Border stays on cell
								Test with Gnumeric 1.4		Text is cut							Text is cut(?)


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