Merge pull request #375 from juliangrigera/documentation

Readme extension

README.md

@@ -31,6 +31,80 @@ You can replace `dev-1.0` by `v2.0.0-alpha` to load such released version.
 Alternatively, you can do it by terminal (MacOS, linux... and should work as well in Windows with MINGW64). 
 Create a directory and execute `<this_repo>/scripts/build.sh`, which first downloads the Pharo image and VM and then loads the project.
 
+## Getting Started
+Open a new window (a Bloc _space_) 
+```smalltalk
+aSpace := BlSpace new.
+aSpace show.
+
+"Edit the space's properties, like title and size"
+aSpace title: 'Bloc basics'.
+aSpace extent: 800 @ 600.
+```
+
+Draw an element (a `BlElement`)
+```smalltalk
+"Create a red rectangle"
+rectangle := BlElement new 
+	background: Color red; 
+	size: 150 @ 150;
+	yourself.
+	
+"Add it to the space"
+aSpace root addChild: rectangle.
+
+"Update its properties"
+rectangle 
+	background: Color lightBlue;
+	position: 100 @ 100;
+	border: (BlBorder paint: Color blue width: 10).
+```
+
+Nesting elements
+```smalltalk
+"Create a circle using a geometry (a BlElementGeometry subclass)"
+circle := BlElement new
+	background: Color blue;
+	geometry: BlCircleGeometry new;
+	size: 80 @ 80;
+	yourself.
+rectangle addChild: circle.
+
+"Use a transformation to resize and show child element's overflow"
+circle transformDo: [ :builder | builder scaleBy: 1.2 ].
+rectangle clipChildren: false
+```
+
+Animating
+```smalltalk
+"Animate opacity"
+rectangle addAnimation: (BlOpacityAnimation new opacity: 0.5).
+
+"Animate transformations"
+fallAnimation := (BlTransformAnimation translate: 0 @ 200) absolute.
+rectangle addAnimation: fallAnimation.
+climbAnimation := (BlTransformAnimation translate: 0 @ 0) absolute.
+rectangle addAnimation: climbAnimation.
+
+"Create sequence of animations"
+animationSequence := (BlSequentialAnimation withAll: {fallAnimation . climbAnimation})
+	beInfinite;
+	yourself.
+rectangle addAnimation: animationSequence
+```
+
+Handling Events
+```smalltalk
+"Change color on click"
+rectangle addEventHandlerOn: BlClickEvent do: [ :event | event target background: Color lightGray ].
+
+"Animate on hover/blur"
+rectangle 
+	addEventHandlerOn: BlMouseEnterEvent
+	do: [ :event | event target addAnimation: (BlOpacityAnimation new opacity: 0.2)];
+	addEventHandlerOn: BlMouseLeaveEvent 
+	do: [ :event | event target addAnimation: (BlOpacityAnimation new opacity: 0.8)] 
+```
 
 ## License and Contributing