[Libreoffice-commits] core.git: vcl/inc

[Tor Lillqvist]

 vcl/inc/sallayout.hxx |   27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

New commits:
commit 2cff5631297adc89dfcfdceee7d33d0a27233b9b
Author: Tor Lillqvist <tml at iki.fi>
Date:   Mon Apr 8 08:29:58 2013 +0300

    Add a commment with guesses about the layout engine "API"
    
    If anybody knnows more, or can point to actual useful documentation,
    please amend.
    
    Change-Id: I59910d9e5da71d67f6e5917f933c5a03f8d55a50

diff --git a/vcl/inc/sallayout.hxx b/vcl/inc/sallayout.hxx
index c46c272..ad6cd94 100644
--- a/vcl/inc/sallayout.hxx
+++ b/vcl/inc/sallayout.hxx
@@ -158,6 +158,33 @@ typedef sal_uInt32 sal_GlyphId;
 // all positions/widths are in font units
 // one exception: drawposition is in pixel units
 
+// Unfortunately there is little documentation to help implementors of
+// new classes derived from SalLayout ("layout engines"), and the code
+// and data structures are far from obvious.
+
+// For instance, I *think* the important virtual functions in the
+// layout engines are called in this order:
+
+// * InitFont()
+// * LayoutText()
+// * AdjustLayout(), any number of times (but presumably
+// usually not at all or just once)
+// * Optionally, DrawText()
+
+// Functions that just return information like GetTexWidth() and
+// FillDXArray() are called after LayoutText() and before DrawText().
+
+// Another important questions is which parts of an ImplLayoutArgs can
+// be changed by callers between LayoutText() and AdjustLayout()
+// calls. It probably makes sense only if one assumes that the "string
+// related inputs" part are not changed after LayoutText().
+
+// But why use the same ImplLayoutArgs structure as parameter for both
+// LayoutText() and AdjustLayout() in the first place? And why
+// duplicate some of the fields in both SalLayout and ImplLayoutArgs
+// (mnMinCharPos, mnEndCharPos, mnLayoutFlags==mnFlags,
+// mnOrientation)? Lost in history...
+
 class VCL_PLUGIN_PUBLIC SalLayout
 {
 public: