Documentation for animation and transition

Samples/basic/animation/src/main.cpp

@@ -62,13 +62,10 @@ public:
 			// Button fun
 			{
 				auto el = document->GetElementById("start_game");
-				PropertyDictionary pd;
-				StyleSheetSpecification::ParsePropertyDeclaration(pd, "transform", "rotate(10) translateX(100px)");
-				auto p = pd.GetProperty("transform");
-				el->Animate("transform", *p, 1.8f, Tween{ Tween::Elastic, Tween::InOut }, -1, true);
-
-				auto pp = Transform::MakeProperty({ Transforms::Scale2D{3.f} });
-				el->AddAnimationKey("transform", pp, 1.3f, Tween{ Tween::Elastic, Tween::InOut });
+				auto p1 = Transform::MakeProperty({ Transforms::Rotate2D{10.f}, Transforms::TranslateX{100.f} });
+				auto p2 = Transform::MakeProperty({ Transforms::Scale2D{3.f} });
+				el->Animate("transform", p1, 1.8f, Tween{ Tween::Elastic, Tween::InOut }, -1, true);
+				el->AddAnimationKey("transform", p2, 1.3f, Tween{ Tween::Elastic, Tween::InOut });
 			}
 			{
 				auto el = document->GetElementById("high_scores");

readme.md

@@ -7,31 +7,10 @@ Original website at http://librocket.com
 
 ## Fork features
 
-This fork contains some additional features over the [original libRocket branch](https://github.com/libRocket/libRocket), briefly documented here.
+This fork contains some additional features over the [original libRocket branch](https://github.com/libRocket/libRocket), briefly documented here. Some of the new features utilize features from C++17, thus, a C++17-compliant compiler should be used.
 
 
-
-## Density-independent pixel (dp)
-
-The `dp` unit behaves like `px` except that its size can be set globally to scale relative to pixels. This makes it easy to achieve a scalable user interface. Set the ratio globally on the context by calling:
-
-```C++
-float dp_ratio = 1.5f;
-context->SetDensityIndependentPixelRatio(dp_ratio);
-```
-
-Usage example in RCSS:
-```CSS
-div#header 
-{
-	width: 800dp;
-	height: 50dp;
-	font-size: 20dp;
-}
-```
-
-
-### Transform property
+## Transform property
 
 Based on the work of @shoemark, with additional fixes.
 
@@ -40,7 +19,7 @@ Use `perspective`, `perspective-origin`, `transform` and `transform-origin` in R
 ```CSS
 perspective: 1000px;
 perspective-origin: 20px 50%;
-transform: rotateX(10) skew(-10, 15) translateZ(100dp);
+transform: rotateX(10) skew(-10, 15) translateZ(100px);
 transform-origin: left top 0;
 ```
 
@@ -73,7 +52,133 @@ skew,         angle2
 Angles are in degrees by default.
 
 
-### Pointer events
+
+
+
+## Animations
+
+
+Most RCSS properties can be animated, this includes properties representing lengths, colors, or transforms. From C++, an animation can be started on an Element by calling
+
+```C++
+bool Element::Animate(const String& property_name, const Property& target_value, float duration, Tween tween = Tween{}, int num_iterations = 1, bool alternate_direction = true, float delay = 0.0f, const Property* start_value = nullptr);
+```
+
+Additional animation keys can be added, extending the duration of the animation, by calling
+
+```C++
+bool Element::AddAnimationKey(const String& property_name, const Property& target_value, float duration, Tween tween = Tween{});
+```
+
+C++ example usage:
+
+```C++
+auto p1 = Transform::MakeProperty({ Transforms::Rotate2D{10.f}, Transforms::TranslateX{100.f} });
+auto p2 = Transform::MakeProperty({ Transforms::Scale2D{3.f} });
+el->Animate("transform", p1, 1.8f, Tween{ Tween::Elastic, Tween::InOut }, -1, true);
+el->AddAnimationKey("transform", p2, 1.3f, Tween{ Tween::Elastic, Tween::InOut });
+```
+
+
+Animations can also be specified entirely in RCSS, with keyframes.
+```CSS
+animation: <duration> <delay> <tweening-function> <num_iterations|infinite> <alternate> <paused> <keyframes-name>;
+```
+All values, except `<duration>` and `<kyframes-name>`, are optional. Delay must be specified after duration, otherwise values can be given in any order. Keyframes are specified as in CSS, see example below. Multiple animations can be specified on the same element by using a comma-separated list.
+
+Tweening functions (or in CSS lingo, `animation-timing-function`s) specify how the animated value progresses during the animation cycle. A tweening function in RCSS is specified as `<name>-in`, `<name>-out`, or `<name>-in-out`, with one of the following names,
+```
+back
+bounce
+circular
+cubic
+elastic
+exponential
+linear
+quadratic
+quartic
+quintic
+sine
+```
+
+RCSS example usage:
+
+```CSS
+@keyframes my-progress-bar
+{
+	0%, 30% {
+		background-color: #d99;
+	}
+	50% {
+		background-color: #9d9;
+	}
+	to { 
+		background-color: #f9f;
+		width: 100%;
+	}
+}
+#my_element
+{
+	width: 25px;
+	animation: 2s cubic-in-out infinite alternate my-progress-bar;
+}
+```
+
+Internally, animations apply their properties on the local style of the element. Thus, mixing RML style attributes and animations should be avoided on the same element.
+
+Animations are very powerful coupled with transforms. See the animation sample project for more examples and details.
+
+
+
+## Transitions
+
+Transitions apply an animation between two property values on an element when its property changes. Transitions are implemented in RCSS similar to how they operate in CSS. However, in RCSS, they only apply when a class or pseudo-class is added to or removed from an element.
+
+```CSS
+transition: <space-separated-list-of-properties|all|none> <duration> <delay> <tweening-function>;
+```
+The property list specifies the properties to be animated. Delay and tweening-function are optional. Delay must be specified after duration, otherwise values can be given in any order. Multiple transitions can be specified on the same element by using a comma-separated list. The tweening function is specified as in the `animation` RCSS property.
+
+
+Example usage:
+
+```CSS
+#transition_test {
+	transition: padding-left background-color transform 1.6s elastic-out;
+	transform: scale(1.0);
+	background-color: #c66;
+}
+#transition_test:hover {
+	padding-left: 60px;
+	transform: scale(1.5);
+	background-color: #ddb700;
+} 
+```
+
+See the animation sample project for more examples and details.
+
+
+## Density-independent pixel (dp)
+
+The `dp` unit behaves like `px` except that its size can be set globally to scale relative to pixels. This makes it easy to achieve a scalable user interface. Set the ratio globally on the context by calling:
+
+```C++
+float dp_ratio = 1.5f;
+context->SetDensityIndependentPixelRatio(dp_ratio);
+```
+
+Usage example in RCSS:
+```CSS
+div#header 
+{
+	width: 800dp;
+	height: 50dp;
+	font-size: 20dp;
+}
+```
+
+
+## Pointer events
 
 Set the element property to disregard mouse input events on this and descending elements.
 ```CSS
@@ -82,7 +187,7 @@ pointer-events: none;
 Default is `auto`.
 
 
-### Image-color property
+## Image-color property
 
 Non-standard RCSS property which multiplies a color with images in `<img>` tags and image decorators. Useful for `:hover`-events and for applying transparency.
 ```CSS
@@ -92,7 +197,7 @@ icon-image: background.png 34px 0px 66px 28px;
 ```
 
 
-### Inline-block
+## Inline-block
 
 Unlike the original branch, elements with
 ```CSS
@@ -102,7 +207,7 @@ will shrink to the width of their content, like in CSS.
 
 
 
-### Border shorthand
+## Border shorthand
 
 Enables the `border` property shorthand.
 ```CSS
@@ -110,7 +215,7 @@ border: 4px #e99;
 ```
 
 
-### Various changes
+## Various changes
 
 The slider on the `input.range` element can be dragged from anywhere in the element. Additionally, the `:checked` pseudo class can be used to style the selected item in drop-down lists.