GUI animation types

From HEWIKI
(Difference between revisions)
Jump to: navigation, search
(moved to category GUIXML)
(removed Hero's Journey specific GUI Animations and added a tutorial for creating a new GUI Animation)
 
Line 1: Line 1:
{{HJ-todo}}
+
{{tocright}} There are several different pre-existing '''GUI animation types''' which can be applied to a GUIControl, each of which has its own specific use and arguments.  This page gives details on the different types and a simple tutorial for creating a new GUI Animation.
  
There are several different pre-existing '''GUI animation types''' which can be applied to a GUIControl, each of which has its own specific use and arguments.  This page gives details on the different types.
+
== Existing Types ==
  
== Commonly Used Types ==
+
To see a complete list of all available animation types, open the script editor and look for scripts that start with the prefix "GUIA_".  To create a new type, see the section on [[Technical:GUIAnimations#Creating_a_custom_animation_effect_-_How_Animations_Work|GUIAnimations]] or the [[#Create a New Animation|Create a New Animation]] tutorial on this page.  Following is a list of the [[Clean Engine]] GUI Animations.  For detailed arguments please see the appropriate section further down on the page, or open the appropriate script and look at its comments.  For example, to learn the details of the Interpolate animation, you could examine the client-side script GUIA_Interpolate.
 
+
To see a complete list of all available animation types, open the script editor and look for scripts that start with the prefix "GUIA_".  To create a new type, see the section on [[Technical:GUIAnimations|GUIAnimations]].  Following is a list of the more commonly-used ones.  For detailed arguments of each type, please see the appropriate section further down on the page, or open the appropriate script and look at its comments.  For example, to learn the details of the Interpolate animation, you could examine the client-side script GUIA_Interpolate.hsl.
+
  
 
* <code>Interpolate</code> - Will change fields of a Control based on upper and lower boundary arguments.  For example, it could be used to change a control's color, size, position, or any combination of other numeric (float-value) fields.
 
* <code>Interpolate</code> - Will change fields of a Control based on upper and lower boundary arguments.  For example, it could be used to change a control's color, size, position, or any combination of other numeric (float-value) fields.
 
* <code>Frames</code> - This animation takes a given texture file, and steps through different sections of it, making each part of the texture file a different "frame" of the animation.  The arguments of this animation specify things like the size of the frame, how many rows of frames exist in the file, how long each frame needs to be displayed, and so forth.
 
 
* <code>Revealer</code> - Used by the character manager, this displays a graphic in a left to right "revealing" style, with some sparkles tossed in for good measure.
 
 
* <code>CategoryTopicExpansion</code> - Used in the character manager to get category and topic headers to expand and collapse.
 
 
* <code>ButtonClicks</code> - Animates the depression of a button when it is clicked.  This animation is specific to buttons, and cannot be used on any other type of GUIControl.
 
  
 
Each of the above animations can be set on a control either by directly adding a reference to the "animation" field of the control's properties, or via a script.
 
Each of the above animations can be set on a control either by directly adding a reference to the "animation" field of the control's properties, or via a script.
  
== ButtonClicks() ==
+
<br>
 
+
This animation causes the movement of a button Control that makes it look like the button is depressed when the mouse clicks on it.  Note that this animation type is unique to button Controls, and cannot be used on other types of Controls (since they won't have the pieces that this animation looks for).
+
 
+
==== [[GUIXML]] Syntax ====
+
 
+
Most buttons already have this animation type built in to their <code>animation</code> field.  However, if one doesn't, here is how to add it:
+
 
+
* Examine the Button control via the [[Technical:GUI|GUI]] Editor
+
* Look at the button's properties
+
* In the button's Animation field, add the following:
+
 
+
<hsl>
+
      onMouseDown=ButtonClicks(press); onMouseUp=ButtonClicks(depress);
+
</hsl>
+
 
+
== Revealer() ==
+
 
+
This animation causes a Control to draw (or redraw) itself from left to right, with some attached sparkles.  For an example, look at the Character Manager, for the way that the header text appears at the top left of the screen.
+
 
+
==== [[GUIXML]] Syntax ====
+
 
+
In the animation field of the Window control, add the following:
+
<hsl>
+
OnMouseClick=Revealer();
+
</hsl>
+
 
+
==== [[Technical:HSL|HSL]] Syntax ====
+
To do the same thing via a script, for example, to set it such that right-clicking on a button will make its entire window sparkle, add the following:
+
<hsl>
+
function WonderfulButton_OnMouseClick(args references Class GUIMouseEvent)
+
  if (args.rightButton = true)
+
    var ButtonsWindow = GUIutils:rootParent(me)
+
    GUIAnimation:addAnimation(ButtonsWindow, "Revealer", "")
+
  .
+
</hsl>
+
  
 
== Interpolate() ==
 
== Interpolate() ==
Line 74: Line 29:
 
</hsl>
 
</hsl>
  
 +
<br>
  
 
==== [[GUIXML]] Syntax ====
 
==== [[GUIXML]] Syntax ====
Line 82: Line 38:
 
onMouseEnter=Interpolate(defaultStatePresentation.color.a,0.5,1.0,0.6,1,false,SMOOTH,false,0,fadein);
 
onMouseEnter=Interpolate(defaultStatePresentation.color.a,0.5,1.0,0.6,1,false,SMOOTH,false,0,fadein);
 
onMouseLeave=Interpolate(defaultStatePresentation.color.a,1,0.5,0.6,1,false,SMOOTH,false,0,fadeout);
 
onMouseLeave=Interpolate(defaultStatePresentation.color.a,1,0.5,0.6,1,false,SMOOTH,false,0,fadeout);
</hsl>
+
</hsl>
 +
 
 +
<br>
  
 
==== [[Technical:HSL|HSL]] Syntax ====
 
==== [[Technical:HSL|HSL]] Syntax ====
Line 91: Line 49:
 
Though the above would be acceptable, it would be difficult to read.  A better way to send the arguments would be as follows:
 
Though the above would be acceptable, it would be difficult to read.  A better way to send the arguments would be as follows:
 
<hsl>
 
<hsl>
  aa as String
+
aa as String
  aa = aa + "size.y"                              // field to change
+
aa = aa + "size.y"                              // field to change
  aa = aa + "," + getReady.size.y                  // Minimum value
+
aa = aa + "," + getReady.size.y                  // Minimum value
  aa = aa + "," + "0"                              // Maximum value
+
aa = aa + "," + "0"                              // Maximum value
  aa = aa + "," + "0.5"                            // duration of effect
+
aa = aa + "," + "0.5"                            // duration of effect
  aa = aa + "," + "1"                              // repeat count
+
aa = aa + "," + "1"                              // repeat count
  aa = aa + "," + "false"                          // reverse direction when max achieved
+
aa = aa + "," + "false"                          // reverse direction when max achieved
  aa = aa + "," + "SMOOTH"                        // interpolation curve
+
aa = aa + "," + "SMOOTH"                        // interpolation curve
  aa = aa + "," + "false"                          // restore value when done
+
aa = aa + "," + "false"                          // restore value when done
  aa = aa + "," + "0"                              // delay start by seconds
+
aa = aa + "," + "0"                              // delay start by seconds
  aa = aa + "," + "readyshrink"                    // name for this animation
+
aa = aa + "," + "readyshrink"                    // name for this animation
  
  animationNode as NodeRef of Class GUIAnimation = GUIAnimation:addAnimation(getReady, "Interpolate", aa)
+
animationNode as NodeRef of Class GUIAnimation = GUIAnimation:addAnimation(getReady, "Interpolate", aa)
 
</hsl>
 
</hsl>
  
== Frames() ==
+
<br>
  
This animation works with the Control's texture file, which is assumed to have several frames of animation within it.  The animation's arguments specify the size and placement of the frames, and then how quickly to play through them.  Note that this animation type does not bring its own animation with it!  It can only work with the texture that is already on the Control, which must already have been created by an artist to supply the necessary animation frames.
+
== Create a New Animation ==
  
Examples of this animation can be found in the Ability Bar icons, to supply the moving clock shadow that appears on them when they are clicked.  In that case, there is a "shadow" control with the texture file that has the animation frames, and this control is overlaid on top of whichever ability icon needs to have the animation. The texture file has a set of frames for each of the three icon shapes, and all three sets are in the same texture file.  Its size is hardcoded -- it doesn't "stretch" to other controls, so this animation can only be used on something that's the exact size and shape of an Ability Bar icon.
+
This tutorial will provide step by step instructions for creating a simple Fade [[GUI Animations|GUI Animation]]. The result of the animation (given the animation parameters below) will cause a GUI Control to fade from 1.0 alpha to 0.5 alpha over 0.5 seconds when the mouse hovers over the control, then fade from 0.5 alpha to 1.0 alpha over 0.5 seconds when the mouse leaves the control.
  
Frames are numbered sequentially, with the first frame being #0 (not 1). All frames must be the same size, and arranged in the texture file in such a way that their borders are right up against each other without any space in between.
+
* Create a new class in the client [[DOM]] named "GUIA_Fade" using the <code>data</code> archetype.
 +
* Add the field <code>timeIndex</code> to the class "GUIA_Fade".
 +
* Create a new client script name "GUIA_Fade".
 +
** Note: This is not the class methods script for the "GUIA_Fade" class.
 +
* Add the functions <code>GUIAnimation_init()</code>, <code>GUIAnimation_stop()</code> and <code>GUIAnimation_tick()</code> to the "GUIA_Fade" script. See below for the full script contents.
 +
* Compile and Submit the script.
 +
* Use the following string for the animation of a GUI Control: <code>"onMouseEnter=Fade(1.0,0.5,0.5); onMouseLeave=Fade(0.5,1.0,0.5);"</code>.
 +
** The animation can be [[GUI_Animations#Triggering_an_Animation_via_HeroBlade|Triggered via HeroBlade]] or [[GUI_Animations#Setting_an_event_trigger_on_an_animation_via_HSL|Triggered via HSL]].
 +
** Note: if the animation is [[GUI_Animations#Setting_an_event_trigger_on_an_animation_via_HSL|Triggered via HSL]], the <code>animation</code> field of the GUI Control must be set before the control is se to build (<code>build=TRUE</code>).
  
{| border="1" align="left" width="100%" cellpadding="5" cellspacing="2"
+
<br>
| '''Argument'''||'''Datatype'''||'''Description'''
+
|-
+
| statePresentation||String||Potential values are: (default, disabled, hover, selected, selectedDisabled)
+
|-
+
| startFrame||Integer||The frame of animation to start with, counting the first frame as #0.
+
|-
+
| endFrame||Integer||The last frame to display
+
|-
+
| duration||Float|| &nbsp;
+
|-
+
| framesPerRow ||Integer|| &nbsp;
+
|-
+
| startingX ||Float||The x,y coordinates specify the location of the first frame of animation in the texture file
+
|-
+
| startingY ||Float|| &nbsp;
+
|-
+
| repeatCnt ||Integer|| &nbsp;
+
|-
+
| reverse ||Boolean|| &nbsp;
+
|-
+
| restore ||Boolean|| &nbsp;
+
|-
+
| delay ||Float|| &nbsp;
+
|-
+
| animID||String = args[12]|| &nbsp;
+
|}
+
  
<br clear="all">
+
=== Fade Animation Script ===
  
==== [[GUIXML]] Syntax ====
+
Below is the full contents of the "GUIA_Fade" GUI Animation script:
 +
<hsl>
 +
//==Args==
 +
// The following args are enclosed in one string
 +
//1 startAlpha(float) - what value of alpha to start the animation at
 +
//2 endAlpha(float) - what value of alpha to end the animation at
 +
//3 duration(float) - over how much time (in seconds) to fade from startAlpha to endAlpha
 +
shared function GUIAnimation_init(animation as NodeRef of Class GUIAnimation) as Boolean
 +
  where animation is kindof GUIA_Fade
 +
    //this will split the single argument string into a list of the arguments
 +
    SplitBy(animation.GUIanimationArgs, ",", animation.argsList)
 +
   
 +
    if animation.argsList.length != 3
 +
      println("Invalid number of arguments for the fade animation, arguments=" + animation.GUIanimationArgs)
 +
      return false
 +
    .
 +
   
 +
    //record when this animation started
 +
    animation.timeIndex = SYSTEM.TIME.NOW
 +
  .
 +
  return true
 +
.
  
<hsl>onMouseClick=frames(default,0,59,15,15,0,0,0,false,false,0,clockShadow);</hsl>
+
shared function GUIAnimation_stop(animation as NodeRef of Class GUIAnimation)
 +
  if(animation != None)
 +
    destroyNode(animation)
 +
  .
 +
.
  
==== HSL Syntax ====
+
shared function GUIAnimation_tick(animation as NodeRef of Class GUIAnimation)
 +
  where animation is kindof GUIA_Fade
 +
    //copy the animation arguments into readable variables
 +
    start_alpha as Float = animation.argsList[1]
 +
    end_alpha as Float = animation.argsList[2]
 +
    duration as Float = animation.argsList[3]
 +
   
 +
    //this is how much time has elapsed since the animation started
 +
    elapsed as TimeInterval = SYSTEM.TIME.NOW - animation.timeIndex
 +
   
 +
    //if the animation has been running the desired amount of time stop it
 +
    if elapsed.secondsTotal > duration
 +
      GUIAnimation_stop(animation)
 +
      return
 +
    .
 +
   
 +
    //calculate what the alpha should be based on how far along in the animtion it is
 +
    alpha as Float = (end_alpha - start_alpha) * (elapsed.secondsTotal / duration) + start_alpha
 +
    animation.controlToAnimate.hoverStatePresentation.color.a = FABS(alpha)
 +
    animation.controlToAnimate.defaultStatePresentation.color.a = FABS(alpha)
 +
  .
 +
.
 +
</hsl>
  
For sample code, please check the <code>mainBar.hsl</code> client-side script, in the <code>applyClockShadow()</code> function.
+
<br>
  
 
== See also ==
 
== See also ==

Latest revision as of 21:38, 14 November 2011

Contents

There are several different pre-existing GUI animation types which can be applied to a GUIControl, each of which has its own specific use and arguments. This page gives details on the different types and a simple tutorial for creating a new GUI Animation.

Existing Types

To see a complete list of all available animation types, open the script editor and look for scripts that start with the prefix "GUIA_". To create a new type, see the section on GUIAnimations or the Create a New Animation tutorial on this page. Following is a list of the Clean Engine GUI Animations. For detailed arguments please see the appropriate section further down on the page, or open the appropriate script and look at its comments. For example, to learn the details of the Interpolate animation, you could examine the client-side script GUIA_Interpolate.

Each of the above animations can be set on a control either by directly adding a reference to the "animation" field of the control's properties, or via a script.


Interpolate()

This animation takes two different values for some field on the target GUIControl, and then animates the Control by moving from one value to the other. For example, if a minimum and maximum values were indicated for the Control's size field, this animation would cause the Control to appear to grow from one size to another.

//==Args==
//1 field(string), the field on the GUIControl to modify, such as size.x or defaultStatePresentation.color.a
//2 min(float)
//3 max(float)
//4 duration in seconds(float)
//5 repeat count(integer)
//6 reverse(boolean), forward and backward(true), or just forward(false)
//7 curve(Enum of type interpolation curve), LINEAR, HOLD, EASE_IN, EASE_OUT, SMOOTH
//8 restore(boolean), restores the orignal value after the animation is finished
//9 delay in seconds(float), the amount of time to wait before actually starting the animation
//10 id(string), the ID of the animation


GUIXML Syntax

This is the value of the animation field on an "Action Mark" icon (such as when a character approaches an object that they can sit down on) which causes the icon to solidify as the mouse cursor passes over it:

onMouseEnter=Interpolate(defaultStatePresentation.color.a,0.5,1.0,0.6,1,false,SMOOTH,false,0,fadein);
onMouseLeave=Interpolate(defaultStatePresentation.color.a,1,0.5,0.6,1,false,SMOOTH,false,0,fadeout);


HSL Syntax

GUIAnimation:addAnimation(getReady, "Interpolate", "size.y, getReady.size.y, 0, 0.5, 1, false, smooth, false, 0, readyshrink")

Though the above would be acceptable, it would be difficult to read. A better way to send the arguments would be as follows:

aa as String
aa = aa + "size.y"                               // field to change
aa = aa + "," + getReady.size.y                  // Minimum value
aa = aa + "," + "0"                              // Maximum value
aa = aa + "," + "0.5"                            // duration of effect
aa = aa + "," + "1"                              // repeat count
aa = aa + "," + "false"                          // reverse direction when max achieved
aa = aa + "," + "SMOOTH"                         // interpolation curve
aa = aa + "," + "false"                          // restore value when done
aa = aa + "," + "0"                              // delay start by seconds
aa = aa + "," + "readyshrink"                    // name for this animation
 
animationNode as NodeRef of Class GUIAnimation = GUIAnimation:addAnimation(getReady, "Interpolate", aa)


Create a New Animation

This tutorial will provide step by step instructions for creating a simple Fade GUI Animation. The result of the animation (given the animation parameters below) will cause a GUI Control to fade from 1.0 alpha to 0.5 alpha over 0.5 seconds when the mouse hovers over the control, then fade from 0.5 alpha to 1.0 alpha over 0.5 seconds when the mouse leaves the control.


Fade Animation Script

Below is the full contents of the "GUIA_Fade" GUI Animation script:

//==Args==
// The following args are enclosed in one string
//1 startAlpha(float) - what value of alpha to start the animation at
//2 endAlpha(float) - what value of alpha to end the animation at
//3 duration(float) - over how much time (in seconds) to fade from startAlpha to endAlpha
shared function GUIAnimation_init(animation as NodeRef of Class GUIAnimation) as Boolean
  where animation is kindof GUIA_Fade
    //this will split the single argument string into a list of the arguments
    SplitBy(animation.GUIanimationArgs, ",", animation.argsList)
 
    if animation.argsList.length != 3
      println("Invalid number of arguments for the fade animation, arguments=" + animation.GUIanimationArgs)
      return false
    .
 
    //record when this animation started
    animation.timeIndex = SYSTEM.TIME.NOW
  .
  return true
.
 
shared function GUIAnimation_stop(animation as NodeRef of Class GUIAnimation)
  if(animation != None)
    destroyNode(animation)
  .
.
 
shared function GUIAnimation_tick(animation as NodeRef of Class GUIAnimation)
  where animation is kindof GUIA_Fade
    //copy the animation arguments into readable variables
    start_alpha as Float = animation.argsList[1]
    end_alpha as Float = animation.argsList[2]
    duration as Float = animation.argsList[3]
 
    //this is how much time has elapsed since the animation started
    elapsed as TimeInterval = SYSTEM.TIME.NOW - animation.timeIndex
 
    //if the animation has been running the desired amount of time stop it
    if elapsed.secondsTotal > duration
      GUIAnimation_stop(animation)
      return
    .
 
    //calculate what the alpha should be based on how far along in the animtion it is
    alpha as Float = (end_alpha - start_alpha) * (elapsed.secondsTotal / duration) + start_alpha
    animation.controlToAnimate.hoverStatePresentation.color.a = FABS(alpha)
    animation.controlToAnimate.defaultStatePresentation.color.a = FABS(alpha)
  .
.


See also

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox