21 Aug 2020 - The wiki is undergoing a major cleanup. If you arrived here from a search engine and cannot find the page, please use the wiki search instead (top right corner of page)
More info can be found on the forum

Difference between revisions of "Animating your skin"

From Official Kodi Wiki
Jump to: navigation, search
m (after testing this was right before.)
(Attributes)
 
(29 intermediate revisions by 13 users not shown)
Line 1: Line 1:
==About Skin Animations==
+
{{mininav|[[Development]]|[[Add-on development]]|[[Skinning]]}}
The XBMC skin engine has support for animations between control and window states. The animations are defined through use of the <animation> tag, which has a defined type and various attributes that specify the animation to be performed. All animations are additive – if two of them are in effect at the same time, their effects are added together. Note that you may only have one animation of each type however.
+
<section begin="main content" />
===Window Animations===
+
The Kodi skin engine has support for animations between control and window states. The animations are defined through use of the <animation> tag, which has a defined type and various attributes that specify the animation to be performed. All animations are additive – if two of them are in effect at the same time, their effects are added together. You may also have more than one animation of each type.
There are two valid window animation – the animation to perform when the window is opened, and the animation to perform when the window is closed. They take the same format as the control animations.
 
  
===Control Animations===
+
== Window Animations ==
 +
There are two valid window animations – the animation to perform when the window is opened, and the animation to perform when the window is closed. They take the same format as the control animations. You can, however, have more than one animation performed for the WindowOpen or WindowClose animation.
 +
 
 +
== Control Animations ==
 
There are 6 valid control animations: WindowOpen, WindowClose, Visible, Hidden, Focus, and Unfocus. There is also a combination animation VisibleChange that constructs the Visible animation, then reverses it for the Hidden animation.
 
There are 6 valid control animations: WindowOpen, WindowClose, Visible, Hidden, Focus, and Unfocus. There is also a combination animation VisibleChange that constructs the Visible animation, then reverses it for the Hidden animation.
  
===Format of Animation Tags===
+
== Format of Animation Tags ==
The animation tag is formatted as follows:
+
The animation tag is formatted as follows for a single animation:
<xml>
+
<syntaxhighlight lang="xml" enclose="div">
<animation attributes>type</animation>
+
<animation effect="EFFECT" attributes>TYPE</animation>
</xml>
+
</syntaxhighlight>
====Types====
+
and as follows for multiple animations:
 +
<syntaxhighlight lang="xml" enclose="div">
 +
<animation type="TYPE" condition="Window.IsActive(Home)" reversible="false">
 +
  <effect type="EFFECT" other_attributes />
 +
  ...
 +
  <effect type="EFFECT" other_attributes />
 +
</animation>
 +
</syntaxhighlight>
 +
 
 +
=== Types ===
 
The type can be one of the following:
 
The type can be one of the following:
 
; WindowOpen  
 
; WindowOpen  
Line 25: Line 36:
 
: Performed when the control gains focus.  
 
: Performed when the control gains focus.  
 
; Unfocus  
 
; Unfocus  
: Performed when the control loses focus.  
+
: Performed when the control loses focus.
 +
; Conditional
 +
: Performed when the control's condition attribute is filled.  
 
; VisibleChange  
 
; VisibleChange  
 
: The same as the Visible type, except the reverse animation is auto-created for the Hidden type. Just saves having to have both animations if the animation is the same in both directions (ie just reversed)
 
: The same as the Visible type, except the reverse animation is auto-created for the Hidden type. Just saves having to have both animations if the animation is the same in both directions (ie just reversed)
  
====Attributes====
+
=== Attributes ===
 
The attributes available are as follows. Note that all attributes, like tags, are case sensitive
 
The attributes available are as follows. Note that all attributes, like tags, are case sensitive
 
; effect  
 
; effect  
: Specifies the effect to use. Currently “fade”, “slide”, “rotate”, and “zoom” are supported.  
+
: Specifies the effect to use. Currently “fade”, “slide”, “rotate”, "rotatex", "rotatey", and “zoom” are supported.
 +
: rotatex - rotates a control around the X-Axis (horizontal)
 +
: rotatey - rotates a control around the Y-Axis (vertical)
 +
: rotate - rotates a control around the Z-Axis
 
; time :  
 
; time :  
 
Specifies the length of time that the animation will run, in milliseconds.  
 
Specifies the length of time that the animation will run, in milliseconds.  
Line 39: Line 55:
 
; start  
 
; start  
 
: The start state of the control for this transistion.  
 
: The start state of the control for this transistion.  
:*For fades, this is the opaqueness as a percentage (ie start="100" is fully opaque, start="0" is fully transparent.  
+
:* For fades, this is the opaqueness as a percentage (ie start="100" is fully opaque, start="0" is fully transparent.  
:*For slides, this is the relative coordinate offset to start the control at (ie start="50,60" will start the control off at 50 pixels to the right, and 60 pixels below it's normal viewing position.  
+
:* For slides, this is the relative coordinate offset to start the control at (ie start="50,60" will start the control off at 50 pixels to the right, and 60 pixels below it's normal viewing position.  
:*For rotates, this is the starting degree offset from the horizontal. (ie start="30" will start the control off on an angle of 30 degrees from the horizontal).  
+
:* For rotates, this is the starting degree offset from the horizontal. (ie start="30" will start the control off on an angle of 30 degrees from the horizontal).  
:*For zooms, this is the starting size as a percentage. (ie start="50,60" will start the control at 50% of it's horizontal size and 60% of it's vertical size).  
+
:* For zooms, this is the starting size as a percentage. (ie start="50,60" will start the control at 50% of it's horizontal size and 60% of it's vertical size).
; end
+
:Note: With zooms you can also specify the coordinates and dimensions of the texture. (ie start="left,top,width,height").
 +
; end  
 
: The end state of the control for this transistion. Similar to the start state, except that the end state is always kept after the animation is finished, and until the control changes its state.  
 
: The end state of the control for this transistion. Similar to the start state, except that the end state is always kept after the animation is finished, and until the control changes its state.  
 
; acceleration  
 
; acceleration  
: Amount to accelerate or decelerate during a “slide”, “zoom” or “rotate” transistion. For deceleration, use a negative value. A value of -1 will cause the control to come to rest at its end coordinates. Defaults to 0.  
+
: Amount to accelerate or decelerate during a “slide”, “zoom” or “rotate” transistion. For deceleration, use a negative value. A value of -1 will cause the control to come to rest at its end coordinates. Defaults to 0. (Also see the tween attribute)
 
; center  
 
; center  
: Center of the rotation or zoom to perform with a “rotate” or “zoom” transistion. This is the coordinates about which the rotation or zoom will take place. eg center="30,50” will mean that all points will revolve around (or zoom from) the (30,50) pixel location.
+
: Center of the rotation or zoom to perform with a “rotate” or “zoom” transistion. This is the coordinates about which the rotation or zoom will take place. eg center="30,50” will mean that all points will revolve around (or zoom from) the (30,50) pixel location. You can set center="auto" to have Kodi automatically zoom from the center of the control.
 +
: Center shifts the rotational axis at the level, rotatex - center="y,z" coordinates, rotatey - center="x,z" coordinates, rotate - center="x,y" coordinates
 
; condition
 
; condition
 
: The conditions under which this animation should be performed. Defaults to being always performed. [[Conditional Visibility|See here for a list of valid conditionals.]]
 
: The conditions under which this animation should be performed. Defaults to being always performed. [[Conditional Visibility|See here for a list of valid conditionals.]]
 
; reversible  
 
; reversible  
 
: If “false” the animation is not reversed if it is interrupted when it is finished. For instance a Visible animation will normally be reversed (instead of running the Hidden animation) if the control becomes hidden before the visible animation has finished. Setting reversible="false” prevents this behaviour (the Hidden animation will take its place). Defaults to true.
 
: If “false” the animation is not reversed if it is interrupted when it is finished. For instance a Visible animation will normally be reversed (instead of running the Hidden animation) if the control becomes hidden before the visible animation has finished. Setting reversible="false” prevents this behaviour (the Hidden animation will take its place). Defaults to true.
 +
; loop
 +
: If “true” will make your animation loop. (jump back to the start after it reaches the end)
 +
; pulse
 +
: If “true” will make your animation pulse. (Bounce back from start to end to start to end .........)
 +
; tween
 +
: Tween is like an advanced acceleration attribute that can be applied to all animations. Instead of a steady acceleration or deceleration, you can specify curves that the animation should follow. Currently, the engine supports “elastic“, “bounce“, “circle“, “back“, “sine“, “cubic“, “quadratic“ and, the default, “linear“. [[Tweeners|More information about Tweeners]]
 +
; easing
 +
: Easing basically defines the direction of the tween and can be one of “out“, “inout“ and “in“. The default value is “out“. [[Tweeners|More information about Easing]]
  
===Examples===
+
== Examples ==
<xml>
+
<syntaxhighlight lang="xml" enclose="div">
 
<visible>Player.HasAudio</visible>
 
<visible>Player.HasAudio</visible>
 
<animation effect="fade" time="400">VisibleChange</animation>
 
<animation effect="fade" time="400">VisibleChange</animation>
</xml>
+
</syntaxhighlight>
  
This causes XBMC to fade the control in 400 milliseconds between the visible and hidden states. The control will start off hidden, and will fade in over 400ms when you play audio, and when it's finished, it will fade out again over 400ms.
+
This causes Kodi to fade the control in 400 milliseconds between the visible and hidden states. The control will start off hidden, and will fade in over 400ms when you play audio, and when it's finished, it will fade out again over 400ms.
 
----
 
----
 
You can also specify different transistion times for transistioning in and out as follows:
 
You can also specify different transistion times for transistioning in and out as follows:
  
<xml>
+
<syntaxhighlight lang="xml" enclose="div">
 
<animation effect="fade" time="100">WindowOpen</animation>
 
<animation effect="fade" time="100">WindowOpen</animation>
<animation effect="fade" time="100">WindowClose</animation>
+
<animation effect="fade" time="1000">WindowClose</animation>
</xml>
+
</syntaxhighlight>
 +
 
  
 
This, when used as the animation tag for the ~MusicOSD dialog, will cause it to fade in quickly (in 100ms) when activated and the fade out again slowly (in 1 second (1000ms)) when it's cancelled.
 
This, when used as the animation tag for the ~MusicOSD dialog, will cause it to fade in quickly (in 100ms) when activated and the fade out again slowly (in 1 second (1000ms)) when it's cancelled.
Line 73: Line 100:
 
You can also specify that a control should always fade in when the window is opened by using
 
You can also specify that a control should always fade in when the window is opened by using
  
<xml>
+
<syntaxhighlight lang="xml" enclose="div">
 
<animation effect="fade" time="200">WindowOpen</animation>
 
<animation effect="fade" time="200">WindowOpen</animation>
</xml>
+
</syntaxhighlight>
  
 
This specifies that it will always start hidden, but will fade in immediately (over a time of 200ms) when the window is opened.
 
This specifies that it will always start hidden, but will fade in immediately (over a time of 200ms) when the window is opened.
 +
 
----
 
----
There is also ability to add delays preceding the transistions. For instance
+
There is also ability to add delays preceding the transistions. For instance
  
<xml>
+
<syntaxhighlight lang="xml" enclose="div">
 
<animation effect="fade" time="200" delay="200">Hidden</animation>
 
<animation effect="fade" time="200" delay="200">Hidden</animation>
</xml>
+
</syntaxhighlight>
  
would mean that the control will fade out after a delay of 200ms. This is useful for "crossfade" effects, where you want the new control to fade in while the old control is still on screen (and then fade the old one out once the new one is completely opaque).
+
would mean that the control will fade out after a delay of 200ms. This is useful for "crossfade" effects, where you want the new control to fade in while the old control is still on screen (and then fade the old one out once the new one is completely opaque).
 
----
 
----
 
There are also slide effects available.
 
There are also slide effects available.
  
<xml>
+
<syntaxhighlight lang="xml" enclose="div">
 
<animation effect="slide" end="30,0" time="200">Focus</animation>
 
<animation effect="slide" end="30,0" time="200">Focus</animation>
</xml>
+
</syntaxhighlight>
  
will slide the control 30 pixels to the right of its normal position when it becomes focused. Note that when it becomes unfocused it will jump back to it's normal position. A Unfocus animation will make it slide back gracefully.
+
will slide the control 30 pixels to the right of its normal position when it becomes focused. Note that when it becomes unfocused it will jump back to it's normal position. A Unfocus animation will make it slide back gracefully.
 
----
 
----
 
There are also rotate effects available.
 
There are also rotate effects available.
  
<xml>
+
<syntaxhighlight lang="xml" enclose="div">
 
<animation effect="rotate" end="30" center="360,288" time="200">Focus</animation>
 
<animation effect="rotate" end="30" center="360,288" time="200">Focus</animation>
</xml>
+
</syntaxhighlight>
  
 
will rotate the control 30 degrees counter clockwise about the center of a PAL screen (360,288) when the control becomes focused.
 
will rotate the control 30 degrees counter clockwise about the center of a PAL screen (360,288) when the control becomes focused.
Line 105: Line 133:
 
And we also have zoom effects.
 
And we also have zoom effects.
  
<xml>
+
<syntaxhighlight lang="xml" enclose="div">
 
<animation effect="zoom" end="120" center="360,288" time="200">Focus</animation>
 
<animation effect="zoom" end="120" center="360,288" time="200">Focus</animation>
</xml>
+
</syntaxhighlight>
  
will zoom the control to 120% of its normal size when the control becomes focused, with the zoom centered at the center of a PAL screen (360,288). You can zoom each dimension by different amounts (effectively a stretch operation) as well. To stretch a control an extra 50% horizontally when focused, we can use
+
will zoom the control to 120% of its normal size when the control becomes focused, with the zoom centered at the center of a PAL screen (360,288). You can zoom each dimension by different amounts (effectively a stretch operation) as well. To stretch a control an extra 50% horizontally when focused, we can use
  
<xml>
+
<syntaxhighlight lang="xml" enclose="div">
 
<animation effect="zoom" end="150,100" center="360,288" time="200">Focus</animation>
 
<animation effect="zoom" end="150,100" center="360,288" time="200">Focus</animation>
</xml>
+
</syntaxhighlight>
 
----
 
----
An example of a conditional animation is:
+
An example of a condition attribute is:
  
<xml>
+
<syntaxhighlight lang="xml" enclose="div">
 
<animation effect="slide" start="-120,0" time="200" condition="Window.Previous(Home)">WindowOpen</animation>
 
<animation effect="slide" start="-120,0" time="200" condition="Window.Previous(Home)">WindowOpen</animation>
</xml>
+
</syntaxhighlight>
  
 
This will cause the slide animation to only be performed if you are coming to this window from the Home window.
 
This will cause the slide animation to only be performed if you are coming to this window from the Home window.
[[category:Skin Development]]
+
----
 +
An example of a Conditional animation type is:
 +
 
 +
<syntaxhighlight lang="xml" enclose="div">
 +
<animation effect="slide" start="-120,0" time="200" condition="Control.HasFocus(2)">Conditional</animation>
 +
</syntaxhighlight>
 +
 
 +
This will cause the slide animation to only be performed when the control with the id of 2 gains focus.
 +
----
 +
An example of a fade animation with a pulse:
 +
 
 +
<syntaxhighlight lang="xml" enclose="div">
 +
<animation effect="fade" start="20" time="200" condition="Control.HasFocus(2)" pulse="true">Conditional</animation>
 +
</syntaxhighlight>
 +
 
 +
This will cause the control to start at 20% opacity and fade to full in 200 milliseconds and fade back to 20% opacity and keeping looping in that fashion
 +
----
 +
An example of two animations at once:
 +
 
 +
<syntaxhighlight lang="xml" enclose="div">
 +
<animation type="WindowOpen">
 +
<effect type="fade" start="0" end="100" time="200"/>
 +
<effect type="zoom" end="150,100" center="auto" time="200" delay="200"/>
 +
</animation>
 +
</syntaxhighlight>
 +
 
 +
This will cause the control to fade in over 200 ms, then zoom to 150% it's width from the center of the control.
 +
 
 +
<section end="main content" />
 +
== See also ==
 +
'''Development:'''
 +
* [[Add-on development]]
 +
* [[Skinning]]
 +
 
 +
[[Category:Skin development]]

Latest revision as of 12:14, 9 April 2016

Home icon grey.png   ▶ Development ▶ Add-on development ▶ Skinning ▶ Animating your skin

The Kodi skin engine has support for animations between control and window states. The animations are defined through use of the <animation> tag, which has a defined type and various attributes that specify the animation to be performed. All animations are additive – if two of them are in effect at the same time, their effects are added together. You may also have more than one animation of each type.

1 Window Animations

There are two valid window animations – the animation to perform when the window is opened, and the animation to perform when the window is closed. They take the same format as the control animations. You can, however, have more than one animation performed for the WindowOpen or WindowClose animation.

2 Control Animations

There are 6 valid control animations: WindowOpen, WindowClose, Visible, Hidden, Focus, and Unfocus. There is also a combination animation VisibleChange that constructs the Visible animation, then reverses it for the Hidden animation.

3 Format of Animation Tags

The animation tag is formatted as follows for a single animation:

<animation effect="EFFECT" attributes>TYPE</animation>

and as follows for multiple animations:

<animation type="TYPE" condition="Window.IsActive(Home)" reversible="false">
  <effect type="EFFECT" other_attributes />
   ...
  <effect type="EFFECT" other_attributes />
</animation>

3.1 Types

The type can be one of the following:

WindowOpen
Performed once only when the window is opened.
WindowClose
Performed once only when the window is closed. No animation is performed when switching to fullscreen video, however.
Visible
Performed when the control becomes visible via its <visible> tag.
Hidden
Performed when the control becomes hidden via its <visible> tag.
Focus
Performed when the control gains focus.
Unfocus
Performed when the control loses focus.
Conditional
Performed when the control's condition attribute is filled.
VisibleChange
The same as the Visible type, except the reverse animation is auto-created for the Hidden type. Just saves having to have both animations if the animation is the same in both directions (ie just reversed)

3.2 Attributes

The attributes available are as follows. Note that all attributes, like tags, are case sensitive

effect
Specifies the effect to use. Currently “fade”, “slide”, “rotate”, "rotatex", "rotatey", and “zoom” are supported.
rotatex - rotates a control around the X-Axis (horizontal)
rotatey - rotates a control around the Y-Axis (vertical)
rotate - rotates a control around the Z-Axis
time 

Specifies the length of time that the animation will run, in milliseconds.

delay
The time to delay the transistion before starting it, in milliseconds.
start
The start state of the control for this transistion.
  • For fades, this is the opaqueness as a percentage (ie start="100" is fully opaque, start="0" is fully transparent.
  • For slides, this is the relative coordinate offset to start the control at (ie start="50,60" will start the control off at 50 pixels to the right, and 60 pixels below it's normal viewing position.
  • For rotates, this is the starting degree offset from the horizontal. (ie start="30" will start the control off on an angle of 30 degrees from the horizontal).
  • For zooms, this is the starting size as a percentage. (ie start="50,60" will start the control at 50% of it's horizontal size and 60% of it's vertical size).
Note: With zooms you can also specify the coordinates and dimensions of the texture. (ie start="left,top,width,height").
end
The end state of the control for this transistion. Similar to the start state, except that the end state is always kept after the animation is finished, and until the control changes its state.
acceleration
Amount to accelerate or decelerate during a “slide”, “zoom” or “rotate” transistion. For deceleration, use a negative value. A value of -1 will cause the control to come to rest at its end coordinates. Defaults to 0. (Also see the tween attribute)
center
Center of the rotation or zoom to perform with a “rotate” or “zoom” transistion. This is the coordinates about which the rotation or zoom will take place. eg center="30,50” will mean that all points will revolve around (or zoom from) the (30,50) pixel location. You can set center="auto" to have Kodi automatically zoom from the center of the control.
Center shifts the rotational axis at the level, rotatex - center="y,z" coordinates, rotatey - center="x,z" coordinates, rotate - center="x,y" coordinates
condition
The conditions under which this animation should be performed. Defaults to being always performed. See here for a list of valid conditionals.
reversible
If “false” the animation is not reversed if it is interrupted when it is finished. For instance a Visible animation will normally be reversed (instead of running the Hidden animation) if the control becomes hidden before the visible animation has finished. Setting reversible="false” prevents this behaviour (the Hidden animation will take its place). Defaults to true.
loop
If “true” will make your animation loop. (jump back to the start after it reaches the end)
pulse
If “true” will make your animation pulse. (Bounce back from start to end to start to end .........)
tween
Tween is like an advanced acceleration attribute that can be applied to all animations. Instead of a steady acceleration or deceleration, you can specify curves that the animation should follow. Currently, the engine supports “elastic“, “bounce“, “circle“, “back“, “sine“, “cubic“, “quadratic“ and, the default, “linear“. More information about Tweeners
easing
Easing basically defines the direction of the tween and can be one of “out“, “inout“ and “in“. The default value is “out“. More information about Easing

4 Examples

<visible>Player.HasAudio</visible>
<animation effect="fade" time="400">VisibleChange</animation>

This causes Kodi to fade the control in 400 milliseconds between the visible and hidden states. The control will start off hidden, and will fade in over 400ms when you play audio, and when it's finished, it will fade out again over 400ms.


You can also specify different transistion times for transistioning in and out as follows:

<animation effect="fade" time="100">WindowOpen</animation>
<animation effect="fade" time="1000">WindowClose</animation>


This, when used as the animation tag for the ~MusicOSD dialog, will cause it to fade in quickly (in 100ms) when activated and the fade out again slowly (in 1 second (1000ms)) when it's cancelled.


You can also specify that a control should always fade in when the window is opened by using

<animation effect="fade" time="200">WindowOpen</animation>

This specifies that it will always start hidden, but will fade in immediately (over a time of 200ms) when the window is opened.


There is also ability to add delays preceding the transistions. For instance

<animation effect="fade" time="200" delay="200">Hidden</animation>

would mean that the control will fade out after a delay of 200ms. This is useful for "crossfade" effects, where you want the new control to fade in while the old control is still on screen (and then fade the old one out once the new one is completely opaque).


There are also slide effects available.

<animation effect="slide" end="30,0" time="200">Focus</animation>

will slide the control 30 pixels to the right of its normal position when it becomes focused. Note that when it becomes unfocused it will jump back to it's normal position. A Unfocus animation will make it slide back gracefully.


There are also rotate effects available.

<animation effect="rotate" end="30" center="360,288" time="200">Focus</animation>

will rotate the control 30 degrees counter clockwise about the center of a PAL screen (360,288) when the control becomes focused.


And we also have zoom effects.

<animation effect="zoom" end="120" center="360,288" time="200">Focus</animation>

will zoom the control to 120% of its normal size when the control becomes focused, with the zoom centered at the center of a PAL screen (360,288). You can zoom each dimension by different amounts (effectively a stretch operation) as well. To stretch a control an extra 50% horizontally when focused, we can use

<animation effect="zoom" end="150,100" center="360,288" time="200">Focus</animation>

An example of a condition attribute is:

<animation effect="slide" start="-120,0" time="200" condition="Window.Previous(Home)">WindowOpen</animation>

This will cause the slide animation to only be performed if you are coming to this window from the Home window.


An example of a Conditional animation type is:

<animation effect="slide" start="-120,0" time="200" condition="Control.HasFocus(2)">Conditional</animation>

This will cause the slide animation to only be performed when the control with the id of 2 gains focus.


An example of a fade animation with a pulse:

<animation effect="fade" start="20" time="200" condition="Control.HasFocus(2)" pulse="true">Conditional</animation>

This will cause the control to start at 20% opacity and fade to full in 200 milliseconds and fade back to 20% opacity and keeping looping in that fashion


An example of two animations at once:

<animation type="WindowOpen">
 <effect type="fade" start="0" end="100" time="200"/>
 <effect type="zoom" end="150,100" center="auto" time="200" delay="200"/>
</animation>

This will cause the control to fade in over 200 ms, then zoom to 150% it's width from the center of the control.


5 See also

Development: