Merge branch 'main' into patch-1

Chapters/bloc/events.md

@@ -1,14 +1,7 @@
 ## Event handling
 
-
-
-
-
 ### Event handling
 
-
-
-
 ```smalltalk
 BlElement new 
   background: Color white; 
@@ -20,6 +13,9 @@ BlElement new
 ```
 
 `addEventHandlerOn:do:` returns the new handler so that we can store to remove it in case. 
+
+#addEventHandlerOn: do: returns the new event handler.  add a #yourself send after to return a BlElement.
+
 `when:do:` is now deprecated and rewritten as `addEventHandlerOn:do:`
 SD: we should update the following
 
@@ -38,13 +34,29 @@ We should check `example_mouseEvent_descending_bubbling`
 
 ![Windows nested in each others in Toplo.](figures/4windows.png width=80)
 
+To stop event propagation `anEvent consumed: true`
 
+There is an option to forbid mouse events for an element. 
+You just send `preventMouseEvent` to it
 
+```smalltalk
+"As a more general explanation, all UI related events can be controlled. Have a look at BlElementFlags and BlElementEventDispatcherActivatedEvents and how these classes are used. "
+
+container := BlElement new size: 500 asPoint; border: (BlBorder paint: Color red width: 2).
 
 
+"#addEventHandlerOn: do: returns the new event handler.  add a #yourself send after"
+child1 := BlElement new size: 300 asPoint; background: Color lightGreen; position: 100 asPoint; addEventHandlerOn: BlClickEvent do: [ self inform: '1' ]; yourself .
 
+"There is an option to forbid mouse events for an element. 
+You just send #preventMouseEvent to it."
+child2 := BlElement new size: 200 asPoint; position: 200 asPoint; border: (BlBorder paint: Color blue width: 2);preventMouseEvents.
 
+container addChild: child1.
+container addChild: child2.
 
+container openInSpace.
+```
 
 ### Drag&drop
 
@@ -254,4 +266,24 @@ BlShortcutWithAction new
 
 
 
+### Drag and Drop
+
+The drop event should be applied to the element that will receive the dragged content.
+`Elt1` uses the dragEnd to know when the drag has ended.
+`Elt2` uses the dropEvent to know when something try to be dropped on it.
+If you drop `elt1` on `elt2`, `elt2` opens an inspector on `elt1`.
+
+```
+| elt1 elt2 space |
+elt1 := BlElement new 
+	background: Color lightBlue;	position: 100 asPoint;	addEventHandler: BlPullHandler new disallowOutOfBounds;	id: #elt1;	yourself.
+	elt2 := BlElement new 
+	background: Color red;	size: 100 asPoint;	position: 200 asPoint;	id: #elt2;	yourself.
+	space := BlSpace new.space root addChildren: { elt1 . elt2 }. elt2 
+	addEventHandlerOn: BlDropEvent 
+	do: [ :evt | evt gestureSource inspect ].elt1 
+	addEventHandlerOn: BlDragEndEvent 
+	do: [ :evt | ]. space show.
+```
+
 

Chapters/bloc/layout.md

@@ -915,4 +915,53 @@ aContainer := BlElement new
 aContainer openInNewSpace.
 ```
 
-![Frame layout](figures/proportionalLayout.png)
+![Frame layout](figures/proportionalLayout.png)
+
+
+
+
+### Proportional layout
+
+This section should reevaluated - it is a copy and paste from an issue
+[https://github.com/pharo-graphics/Bloc/issues/562](https://github.com/pharo-graphics/Bloc/issues/562)
+
+```
+gap:= 20.
+
+BlElement new
+	constraintsDo: [ :constraints |
+		constraints horizontal exact: 400.
+		constraints vertical exact: 300.
+		constraints padding: (BlInsets all: gap) ];
+	background: Color red;
+	id: #A;
+	layout: BlProportionalLayout new;
+	addChildren: {
+		(BlElement new
+			constraintsDo: [ :constraints |
+				constraints proportional vertical bottom: 0.5.
+				constraints margin: (BlInsets all: gap) ];
+			id: #B;
+			background: Color green;
+			yourself).
+		(BlElement new
+			constraintsDo: [ :constraints |
+				constraints proportional horizontal right: 0.5.
+				constraints proportional vertical top: 0.5.
+				constraints margin: (BlInsets all: gap) ];
+			id: #C;
+			background: Color blue;
+			yourself).
+		(BlElement new
+			constraintsDo: [ :constraints |
+				constraints proportional horizontal left: 0.5.
+				constraints proportional vertical top: 0.5.
+				constraints margin: (BlInsets all: gap) ];
+			id: #D;
+			background: Color yellow;
+			yourself) };
+	yourself
+```
+
+![Proportional layout from issue 562](figures/proportionalFromIssue562.png)
+

Chapters/bloc/text.md

@@ -171,3 +171,87 @@ BlElement new
 whose result is shown in Figure *@rect@*.
 
 ![Rectangle with numbers.](figures/rectangleWithNumbers.png width=60&label=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.
+```
+
+