update text chapter with measure strategy

Author: rvillemeur

Chapters/bloc/.text.md.swp

@@ -5,14 +5,21 @@
 Bloc comes with a full API to deal with text. Not only you can deal with
 raw text, but you can apply styles as well.
 
-Before being displayed, you define your text as an instance of `BlRopedText`,
-which you can then style with **attributes** such as:
+Text is reprensented by abstract class *BlText* which serve a model for the UI 
+component. Before being displayed, you define your text as an instance of 
+`BlRopedText`, which you can then style with **attributes** such as:
 
 - font name
 - font size
 - font foreground and background color
 - font style (normal, italic, bold).
 
+Text can after be rendered as `BlTextElement`, which will take care of
+displaying properly the text with all properties defined on it.
+
+Once you have a `BlTextElement`, all properties of `BlElement` apply. 
+You can add your element to any existing `BlElement`, and integrate it easily in
+your graphical interface; it'll follow the same layout rules.
 ```smalltalk
 labelText := 'hello from bloc' asRopedText
 foreground: Color orange;
@@ -26,21 +33,17 @@ label text: labelText.
 label openInNewSpace
 ```
 
-Another way to define attributes is to pass them as
-a collection:
+Another way to define attributes is to pass them as a collection:
 
 ```smalltalk
 BlTextElement new
         position: 5 @ 5;
         text: ('Rainbow!' asRopedText attributes:
         { (BlTextForegroundAttribute paint: Color black)})
-
 ```
 
 Take a look at `BlText` method for a full list of available text attributes.
 
-Fonts are managed directly by Alexandrie. To get the list of available fonts,
-take a look at the result of `AeFontManager globalInstance familyNames`
 
 text is like a collection, and you can apply different attributes to different
 part of your text:
@@ -69,14 +72,96 @@ part of your text:
 
 ![Multiple attributes.](figures/multipleTextAttributes.png width=60)
 
+### BlText vs. BlTextElement
+
+You have 2 different levels to manage text in Bloc.
+- `BlText` and its subclass `BlRopedText` create a text model where you can specify its attributes and style.
+- `BlTextElement` and its subclasses will properly display the text inside a Bloc element.
+
+A small example. You can notice that `BlText` background is different from `BlTextElement` background. 
+
+```smalltalk
+| labelText label |
+labelText := 'hello from bloc' asRopedText
+             background: Color orange ;
+             fontSize: 75;
+             fontName: 'Source Code Pro';
+             italic;
+             underline;
+             underlineColor: Color red;
+             vertical.
+
+(labelText from: 1 to: 5) foreground: Color blue.
+(labelText from: 7 to: 11) foreground: Color white.
+(labelText from: 12 to: 15) foreground: Color red.
+
+label := (BlTextElement text: labelText) position: 50 @ 10; background: Color yellow.
+```
+
+you can define the style of your text through BlTextAttributesStyler
+
+````smalltalk
+text := 'Hi John' asRopedText.
+
+styler := BlTextAttributesStyler on: (text from: 3 to: 7).
+styler
+bold;
+italic;
+fontSize: 30;
+fontName: 'Roboto';
+monospace;
+foreground: Color green.
+styler style.
+```
+
+or using a fluent API
+
+````smalltalk
+text := 'Hi John' asRopedText.
+(text from: 3 to: 7) stylerDo: [ :aStyler | aStyler bold italic foreground: Color red ].
+````
+
+As you may have noticed, this gives you a very fine-grained control over the style of your text.
+You also need to re-specify attributes when your text changes.
+If you want all your text to use the same attribute, you can then use `BlAttributedTextElement`. 
+You can then change your text, `BlAttributedTextElement` will reuse its attributes.
+
+
+```smalltalk
+text := 'Hi John' asRopedText.
+
+element := BlAttributedTextElement new.
+attributes := element attributesBuilder
+              foreground: Color green;
+              monospace;
+              bold;
+              italic;
+              fontSize: 30;
+              fontName: 'Roboto';
+              monospace.
+
+label := (element text: text)
+         position: 50 @ 10;
+         background: Color yellow;
+         margin: (BlInsets all: 2);
+         padding: (BlInsets all: 2);
+         outskirts: BlOutskirts centered;
+         border: (BlBorder paint: Color red width: 2).
+
+element text: 'hello world' asRopedText.
+label.
+```
+
+
 
 ### Text size
 
+Fonts are managed directly by Alexandrie. To get the list of available fonts,
+take a look at the result of `AeFontManager globalInstance familyNames`
+
 The size of your text will depend on the font you have selected. This font will
 constrain aspect of the size of letters, words, and text. 
 Let's familiarize ourselves with those basic measures. 
-Bloc will get the measures (in `BATextParagraphSpan >> measure`)
-to get the size of your text, and position it into your element.
 
 Figure *@MulAttri@* describes the information listed below: 
 
@@ -117,14 +202,16 @@ Internally, your text will be split into a collection of *spans*.
 A span is a homogeneous styled piece of text where every character has the same set of
 attributes.
 
-### Text bounds
+### Advanced used of BlTextElement - Text bounds
 
-Text can after be rendered as `BlTextElement`, which will take care of
-displaying properly the text with all properties defined on it.
 
-Once you have a `BlTextElement`, all properties of `BlElement` apply. 
-You can add your element to any existing `BlElement`, and integrate it easily in
-your graphical interface; it'll follow the same layout rules.
+You can define very precicely how your text is place in your BlTextElement.
+During Bloc rendering phase, element return their measure to be layedout 
+properly. This happen in the `onMeasure:` message. you can customize the rule 
+used for text measurement to make it fit to your Bloc scene. By default, 
+BlTextElement use the *tightMeasurement* strategy. You can change it with the 
+right message. For example, to use the editor measurement, simply state:
+`yourElement editorMeasurement`
 
 `BlTextElement` has 3 available measures by default that determine its bounds.
 
@@ -134,7 +221,19 @@ your graphical interface; it'll follow the same layout rules.
 
 ![Text measures.](figures/textMeasure.png width=80)
 
-By default, *BlTextElement* will follow the *tightMeasurement* measure.
+You can develop your own strategy and customize text measure at two levels:
+1. Text is first converted to `BlTextParagraph`, which will receive a subclass 
+   of `BlTextParagraphBaselineMeasurer` as a baseline measure strategy
+1. Paragraph measure is then used by a subclass of 
+   `BlTextElementMeasurementStrategy` to specify the *BlBounds* of 
+   BlTextElement.
+
+you can then add a new method do *BlTextElement* with your new strategy, like
+```
+BlTextElement >> tightMeasurement
+	self measurement: BlTextElementTightMeasurementStrategy uniqueInstance.
+	self baselineMeasurer: BlBoundsBaselineMeasurer uniqueInstance
+```
 
 ### Examples
 
@@ -174,85 +273,7 @@ whose result is shown in Figure *@rect@*.
 
 
 
-### BlText vs. BlTextElement
 
-You have 2 different levels to manage text in Bloc.
-- `BlText` and its subclass `BlRopedText` create a text model where you can specify its attributes and style.
-- `BlTextElement` and its subclasses will properly display the text inside a Bloc element.
-
-A small example. You can notice that `BlText` background is different from `BlTextElement` background. 
-
-```smalltalk
-| labelText label |
-labelText := 'hello from bloc' asRopedText
-             background: Color orange ;
-             fontSize: 75;
-             fontName: 'Source Code Pro';
-             italic;
-             underline;
-             underlineColor: Color red;
-             vertical.
-
-(labelText from: 1 to: 5) foreground: Color blue.
-(labelText from: 7 to: 11) foreground: Color white.
-(labelText from: 12 to: 15) foreground: Color red.
-
-label := (BlTextElement text: labelText) position: 50 @ 10; background: Color yellow.
-```
-
-you can define the style of your text through BlTextAttributesStyler
-
-````smalltalk
-text := 'Hi John' asRopedText.
-
-styler := BlTextAttributesStyler on: (text from: 3 to: 7).
-styler
-bold;
-italic;
-fontSize: 30;
-fontName: 'Roboto';
-monospace;
-foreground: Color green.
-styler style.
-```
-
-or using a fluent API
-
-````smalltalk
-text := 'Hi John' asRopedText.
-(text from: 3 to: 7) stylerDo: [ :aStyler | aStyler bold italic foreground: Color red ].
-````
-
-As you may have noticed, this gives you a very fine-grained control over the style of your text.
-You also need to re-specify attributes when your text changes.
-If you want all your text to use the same attribute, you can then use `BlAttributedTextElement`. 
-You can then change your text, `BlAttributedTextElement` will reuse its attributes.
-
-
-```smalltalk
-text := 'Hi John' asRopedText.
-
-element := BlAttributedTextElement new.
-attributes := element attributesBuilder
-              foreground: Color green;
-              monospace;
-              bold;
-              italic;
-              fontSize: 30;
-              fontName: 'Roboto';
-              monospace.
-
-label := (element text: text)
-         position: 50 @ 10;
-         background: Color yellow;
-         margin: (BlInsets all: 2);
-         padding: (BlInsets all: 2);
-         outskirts: BlOutskirts centered;
-         border: (BlBorder paint: Color red width: 2).
-
-element text: 'hello world' asRopedText.
-label.
-```
 
 ### upload a font to bloc
 
@@ -391,4 +412,4 @@ label transformDo: [ :t |
 label size: label transformedBounds extent.
 ```
 
-In this snippet we rotate the element containing the text (but not the textElement) using `TBlTransformable>>tranformDo:` but for that we need to force its layout and just like in the earlier example, the transformation didn't change the position nor the bounds hence the last line.
+In this snippet we rotate the element containing the text (but not the textElement) using `TBlTransformable>>tranformDo:` but for that we need to force its layout and just like in the earlier example, the transformation didn't change the position nor the bounds hence the last line.