Abbreviations:
bv: BufferView
pm: ParagraphMetrics
-tm::TextMetrics
+tm: TextMetrics
* Questions / Ideas
** SinglePar update
-The flag Update::SinglePar is set in many places but never acted on.
-Instead, metrics update is skipped whenever the recorded height of
-current paragraph did not change and Update::Force was not specified.
-Is it better to keep that (which incurs extra work) or to condition it
-on Update::SinglePar? If the first solution is kept, the flag
-SingleParUpdate shall be removed.
-
-Moreover, I fail to see (yet) where the 'single' part of the program
-is acted on.
+This flag only has an effect in the current BufferView and at
+top-level, but I think it is useful in other views too. Doing this
+will require some work on the update pipeline, though.
** Buffer::change issues
When calling Buffer::changed outside of bv::processUpdateFlags,
-how do we now that the update strategy is set correctly? It is
+how do we know that the update strategy is set correctly? It is
possible to reset the strategy at the end of bv::draw. What would be
a good value? NoScreenUpdate?
On a related note, what is the semantics of a call to
Buffer::changed(false)? What does the caller mean?
-** What happens with FitCursor when the cursor is already OK?
-In this case, we invoke Buffer::change(false) with drawing disabled,
-which means that the paint machinery is invoked to update inset
-positions.
+** How to avoid redraw with FitCursor when the cursor is already OK?
+
+In this case, we invoke Buffer::change(false) with drawing disabled
+and NoScreenUpdate strategy.
+
+In the draw phase, bv::checkCursorScrollOffset (the horizontal
+scrolling machinery) will change the strategy to FullScreenUpdate if
+the current row needs further scrolling.
+
+When the update strategy it kept to NoScreenUpdate, there is currently
+a no-draw full repaint, which should not be necessary. It would be
+possible to avoid that if the call to checkCursorScrollOffset was done
+in bv::processUpdateFlags instead of bv::draw.
+
+The global idea would be to extend FitCursor to cover also horizontal
+cursor.
+
+
+* Clean-up of drawing code
-Actually, this was added as part of the horizontal scrolling GSoC
-work. We need to investigate how costly this is.
+** Set Row::changed() in a finer way
+*** singleParUpdate
-* Proposals
+When the height of the current paragraph changes, there is no need for
+a full screen update. Only the rows after the current one need to have
+their position recomputed.
-** get rid of pm::insetDimension.
+This is also true when scrolling (how to do that?)
-The information contained there is already in bv::coordCache.
+*** redoParagraph
-Effect: only code simplification.
+It should be possible to check whether the new row is the same as the
+old one and keep its changed() status in this case. This would reduce
+a lot the amount of stuff to redraw.
-** set inset position during metrics phase
+** Put labels and friends in the Row as elements
-This implies to set inset positions relative to outer isnet during
-metrics phase and then in a second loop to descend into insets and
-update positions correctly.
+It should not be necessary to access the Paragraph object to draw.
+Adding the static elements to Row is a lot of work, but worth it IMO.
-Effect: avoid going through the painter machinery when it is not necessary.
+** When a paragraph ends with a newline, compute correctly the height of the extra row.
** Merging bv::updateMetrics and tm::metrics
does not try any such optimization. This can be very bad for very tall
insets. We should re-use the bv::updateMetrics logic:
+ transfer all the logic of bv::updateMetrics to tm.
- + Main InsetText should not be special.
+ + Main InsetText should not be special.
-** Metrics outside of visible area
+The difficulty for a tall table cell for example, is that it may be
+necessary to break the whole contents to know the width of the cell.
-Currently metrics are computed for current visible paet of text, the
-page above and the page below. It should be possible to compute hidden
-rows ony on demand, although it might be a bit slow.
-There was a proposal to always compute _all_ rows, but this may become
-expensive for large files. This would though help scrolling.
+* Description of current drawing mechanism
+** Three-stage drawing
-* Two phase drawing
-
-There are two parts to drawing the work area:
+There are three parts to drawing the work area:
+ the metrics phase computes the size of insets and breaks the
paragraphs into rows. It stores the dimension of insets (both
- normal and math) in bv::coordCache, and the size of normal
- insets in pm::insetDimension.
+ normal and math) in bv::coordCache.
- + the drawing phase draws the contents and caches the inset
- positions. Since the caching of positions is useful in itself,
- there is a provision for drawing "without" drawing when the only
- thing we want is to cache inset positions
- (Painter::setDrawingEnabled).
+ + the nodraw drawing phase paints the screen (see below) with a null
+ painter. The only useful effect is to store the inset positions.
+ + an update() signal is sent. This in turn will trigger a paint
+ event, and the actual screen painting will happen then.
The machinery is controlled via bv::processUpdateFlags. This method is
called at the end of bv::mouseEventDispatch and in
+ Update::Force has been specified
+ Update::FitCursor has been specified and there is a need to scroll
the display.
- + the current paragraph, after rebreak, does not have the same height as in
- existing metrics. Note that the Update::SinglePar flag is *never*
- taken into account.
+ + Update::SinglePar has been specified and the current paragraph has
+ not changed height.
+
+If a computation of metrics has taken place, Force is removed from the
+flags and ForceDraw is added instead.
+
+It is OK to call processUpateFlags several times before an update. In
+this case, the effects are cumulative. processUpdateFlags executes the
+metrics-related actions, but defers the actual drawing to the next
+paint event.
The screen is drawn (with appropriate update strategy), except when
update flag is Update::None.
-* Metrics computation
+** Metrics computation (and nodraw drawing phase)
This is triggered by bv::updateMetrics, which calls tm::redoParagraph for
- + all visible paragraphs
- + paragraph above the screen (up to one page)
- + paragraphs below the screen (up to one page again)
-
-The paragraphs outside of the screen are required to make PageUp/Down
-work.
+all visible paragraphs. Some Paragraphs above or below the screen (needed
+for page up/down) and computed as needed.
tm::redoParagraph will call Inset::metrics for each inset. In the case
of text insets, this will invoke recursively tm::metrics, which redoes
all the paragraphs of the inset.
+Then, a single big row is created in tm::tokenizeParagraph, which is
+later broken in multiple rows by tm::breakParagraph.
+
+At the end of the function, bv::updatePosCache is called. It triggers
+a repaint of the document with a NullPainter (a painter that does
+nothing). This has the effect of caching all insets positions.
-* Drawing the work area.
+** Drawing the work area.
-This is done in bv::draw. This method is triggered mainly by
-Buffer::changed, which draws all the work areas that show the given buffer.
+This is done in bv::draw. This method is triggered by a paint event,
+mainly called through Buffer::changed, which draws all the work areas
+that show the given buffer.
Note that, When Buffer::changed is called outside of
bv::processUpdateFlags, it is not clear whether the update strategy
+ SingleParUpdate: only tries to repaint current paragraph in a way
that is not yet very clear to me.
+
+BufferView::draw can also be called with a null painter from
+BufferView::updateMetrics().