Merge remote-tracking branch 'refs/remotes/origin/main'

Chapters/bloc/animation.md

@@ -215,7 +215,7 @@ sequencially to an element:
 
 A custom animation for element rotation.
 
-```
+```smalltalk
 BlAnimation << #BlRotateAnimation 
 	slots: { #angle }; 
 	tag: 'Animation'; 
@@ -231,22 +231,13 @@ BlRotateAnimation >> valueForStep: aNumber
 	^ (angle * aNumber)
 ```
 
-You then update your example with:
+you can then use it like:
 
-```
+```smalltalk
 | elt frame container anim |
-elt := BlElement new 
-	background: (Color red alpha: 0.5); 
-	position: 100 asPoint; 
-	size: 100 asPoint.
-frame := BlElement new 
-	background: Color yellow; 
-	position: 100 asPoint; 
-	size: 100 asPoint.
-container := BlElement new 
-	background: Color lightGreen; 
-	size: 500 asPoint; 
-	addChildren: {frame. elt}.
+elt := BlElement new background: (Color red alpha: 0.5); position: 100 asPoint; size: 100 asPoint.
+frame := BlElement new background: Color yellow; position: 100 asPoint; size: 100 asPoint.
+container := BlElement new background: Color lightGreen; size: 500 asPoint; addChildren: {frame. elt}.
 
 anim := BlRotateAnimation new angle: 90; duration: 1 second.
 

Chapters/bloc/element.md

@@ -253,6 +253,33 @@ You can apply transformations to a `BlElement`:
 - reflection
 - etc...
 
+Transformation are affine transformation. For more detail, you can search on the internet, there are countless references to it. To simplify it, I'll say we apply  a transformation matrix (*BlMatrix2D*) to all point of our figure path, each point represented as *BlVector*. 
+
+You have 3 type of tranformation available in Bloc:
+- **BlElementLocalTransformation**: This transformation combine an affine transformation (*BlAffineTransformation* subclasses), with a point of origin (*BlAffineTransformationOrigin* subclasses). By default, origin is the center of your element, BlAffineTransformationCenterOrigin.
+- **BlElementAbsoluteTransformation**: This transformation apply a transformation matrix to your shape, without point of origin. Its  result is similar to *BlElementLocalTransformation*, with origin set to *BlAffineTransformationTopLeftOrigin*
+- **BlElementCompositeTransformation** which are combination of *BlElementLocalTransformation* and/or *BlElementAbsoluteTransformation*
+
+Most of the time, you won't have to deal with matrix definition. You'll use the 
+helper method `transformDo`, and define your transformation using *BlTransformationBuilder*.
+
+When you're defining a transformation using `transformDo:` , you'll, by default, 
+use *BlAffineCompositeTransformation*. All transformation move added subsequently will be composed together.
+The origin will be set to *BlAffineTransformationCenterOrigin*.
+
+Those two transformation below are strictly equivalent, and rotate your element by 45 degree. 
+One use the underlying object, while the other use the helper methods:
+
+```smalltalk
+elt transformation: (BlElementLocalTransformation 
+	newWith: ((BlRotationTransformation new angle: 45) 
+	origin: (BlAffineTransformationCenterOrigin defaultInstance ) )).
+```
+
+```smalltalk
+elt transformDo: [ :t | t rotateBy: 45 ].
+```
+
 A transformation is applied in the scope of the message `transformDo:` as shown below.
 ```
 element transformDo: [ :b | b scaleBy: 0.2; translateBy: -25 @ -15 ];

Chapters/bloc/layout.md

@@ -62,8 +62,28 @@ To ease this kind of script one can use `whenLayoutedDoOnce:` which arms a one
 shot event handler that reacts to the `BlElementLayoutComputedEvent` event.
 
 
+### element order
+Your element will be displayed in the order you added them to your parent. You
+can, however, specify their *zIndex*. They will then follow this index order, 
+from low to high.
 
+In the example below, with zIndex, element shoud appears from black to red. 
+With zIndex, you can reorder the order of display of the elements. Note that
+zIndex can be negative.
 
+```smalltalk
+container:= BlElement new geometry: BlRectangleGeometry new; size: 150@150; background: Color lightGray .
+        
+elt1 := BlElement new geometry: BlCircleGeometry new;  size: 100 asPoint; zIndex: 1;  background:Color  black.
+elt2 := BlElement new geometry: BlCircleGeometry new;  size: 100 asPoint; zIndex: 2; position:10@10; background: Color blue.
+elt3 := BlElement new geometry: BlCircleGeometry new; size: 100 asPoint; zIndex: -1; position:20@20; background: Color red.
+        
+container addChildren: {elt1 . elt2 . elt3}.
+
+container.
+```
+
+![zIndex example](figures/zIndexExample.png)
 
 ### Space around elements