2 Understanding the painting process
4 This file tries to describe the state of the metrics/painting
5 mechanism, and identify the improvements that could be made. The first
6 section can be read alone, although the context for them is really
7 given in the following ones.
9 Please keep this file up to date as the code evolves!!!
18 These questions are consequences of the description made in the
19 following section. Some actions are proposed.
23 The flag Update::SinglePar is set in many places but never acted on.
24 Instead, metrics update is skipped whenever the recorded height of
25 current paragraph did not change and Update::Force was not specified.
26 Is it better to keep that (which incurs extra work) or to condition it
27 on Update::SinglePar? If the first solution is kept, the flag
28 SingleParUpdate shall be removed.
30 Moreover, I fail to see (yet) where the 'single' part of the program
33 ** Buffer::change issues
35 When calling Buffer::changed outside of bv::processUpdateFlags,
36 how do we know that the update strategy is set correctly? It is
37 possible to reset the strategy at the end of bv::draw. What would be
38 a good value? NoScreenUpdate?
40 On a related note, what is the semantics of a call to
41 Buffer::changed(false)? What does the caller mean?
43 ** How to avoid redraw with FitCursor when the cursor is already OK?
45 In this case, we invoke Buffer::change(false) with drawing disabled
46 and NoScreenUpdate strategy.
48 In the draw phase, bv::checkCursorScrollOffset (the horizontal
49 scrolling machinery) will change the strategy to FullScreenUpdate if
50 the current row needs further scrolling.
52 When the update strategy it kept to NoScreenUpdate, there is currently
53 a no-draw full repaint, which should not be necessary. It would be
54 possible to avoid that if the call to checkCursorScrollOffset was done
55 in bv::processUpdateFlags instead of bv::draw.
57 The global idea would be to extend FitCursor to cover also horizontal
61 * Clean-up of drawing code
63 ** When a paragraph ends with a newline, compute correctly the height of the extra row.
64 ** Merging bv::updateMetrics and tm::metrics
66 While the full metrics computation tries hard to limit the number of
67 paragraphs that are rebroken, the version that is used for inner inset
68 does not try any such optimization. This can be very bad for very tall
69 insets. We should re-use the bv::updateMetrics logic:
70 + transfer all the logic of bv::updateMetrics to tm.
71 + Main InsetText should not be special.
73 The difficulty for a tall table cell for example, is that it may be
74 necessary to break the whole contents to know the width of the cell.
77 * Description of current drawing mechanism
79 ** Three-stage drawing
81 There are three parts to drawing the work area:
83 + the metrics phase computes the size of insets and breaks the
84 paragraphs into rows. It stores the dimension of insets (both
85 normal and math) in bv::coordCache.
87 + the nodraw drawing phase paints the screen (see below) with a null
88 painter. The only useful effect is to store the inset positions.
90 + an update() signal is sent. This in turn will trigger a paint
91 event, and the actual screen painting will happen then.
93 The machinery is controlled via bv::processUpdateFlags. This method is
94 called at the end of bv::mouseEventDispatch and in
95 GuiApplication::dispatch, via the updateCurrentView method. There are
96 also several calls in code related to dialogs. We should evaluate
97 whether this is correct.
99 Depending on the Update::flags passed to the method, it sets an update
100 strategy in (NoScreenUpdate, SingleParUpdate, FullScreenUpdate,
101 DecorationUpdate). It triggers a recomputation of the metrics when either:
103 + Update::Force has been specified
104 + Update::FitCursor has been specified and there is a need to scroll
106 + the current paragraph, after rebreak, does not have the same height as in
107 existing metrics. Note that the Update::SinglePar flag is *never*
110 If a computation of metrics has taken place, Force is removed from the
111 flags and ForceDraw is added instead.
113 It is OK to call processUptateFlags several times before an update. In
114 this case, the effects are cumulative.processUpdateFlags execute the
115 metrics-related actions, but defers the actual drawing to the next
118 The screen is drawn (with appropriate update strategy), except when
119 update flag is Update::None.
122 ** Metrics computation (and nodraw drawing phase)
124 This is triggered by bv::updateMetrics, which calls tm::redoParagraph for
125 all visible paragraphs. Some Paragraphs above or below the screen (needed
126 for page up/down) and computed as needed.
128 tm::redoParagraph will call Inset::metrics for each inset. In the case
129 of text insets, this will invoke recursively tm::metrics, which redoes
130 all the paragraphs of the inset.
132 At the end of the function, bv::updatePosCache is called. It triggers
133 a repaint of the document with a NullPainter (a painter that does
134 nothing). This has the effect of caching all insets positions.
136 ** Drawing the work area.
138 This is done in bv::draw. This method is triggered by a paint event,
139 mainly called through Buffer::changed, which draws all the work areas
140 that show the given buffer.
142 Note that, When Buffer::changed is called outside of
143 bv::processUpdateFlags, it is not clear whether the update strategy
144 has been set to a reasonable value beforehand.
146 The action depends on the update strategy:
148 + NoScreenUpdate: repaint the whole screen with drawing disabled.
149 This is only needed to update the inset positions. I am not sure
150 when this is necessary, actually. This is triggered when:
151 - Update::FitCursor is set but the cursor is already visible. It is
152 not clear why something needs to be done in this case, since this
153 should be equivalent to Update::None.
154 - this is also set when update flag is Update::None, but this value
155 is AFAICS not acted on in the code (meaning that nothing happens
156 at all in this case).
158 + FullScreenUpdate: repaint the whole screen. This is set when:
159 - updateMetrics has been invoked.
160 - scroll value of current row has changed (although this should not
163 + DecorationUpdate: actually like FullScreenUpdate, although it is
164 intended to only update inset decorations. This triggers when:
165 - Update::Decoration is set (without Update::Force) as flag.
166 - An hovered inset is detected.
168 + SingleParUpdate: only tries to repaint current paragraph in a way
169 that is not yet very clear to me.
171 BufferView::draw can also be called with a null painter from
172 BufferView::updateMetrics().