{{tag>dragonscript appbehavior}}
<WRAP youarehere>
[[:start|Start Page]] >> [[main|DragonScript Scripting Language]] >> [[dragengine:modules:dragonscript:abstractions|Abstraction Layers: How you want to build your Game]] >> [[dragengine:modules:dragonscript:behavior_elements|Behavior Elements]] >> **GABehaviorFadeOverCanvas**
</WRAP>

====== GABehaviorFadeOverCanvas ======

Game application behavior adding a fade-over-canvas overlay to the desktop. The overlay fades a canvas in, keeps it shown and fades it out again. The canvas is created using a [[canvascreators|Canvas Creators]]. Typically this is a single color, like black or white, but it can be also an image, video or a complex canvas. Canvas creates can be loaded from file but it is easier to define a [[.:xmlguitheme:widgetdesigner|Widget Designer]] through [[guitheme#xml_gui_themeing|XML Gui Theming]] to fetch the canvas creator from. The overlay can be controlled through actions and conditions of the [[gabehavior_statemachine|GABehaviorStateMachine]].

To access this behavior from other application behaviors use ''GABehaviorFadeOverCanvas.getBehaviorInApp()''.

====== State Machine Actions ======

This behavior adds these state machine actions.

===== fadeOverCanvas.set =====

Set overlay parameters.

^Parameter^Value^Description^
|time.fadeIn|float|Duration in seconds of fading in. Default value is ''1''.|
|time.stay|float|Duration in seconds the canvas stays shown before fading out. Default value is ''1''. To manually fade out set this value high, for example ''9999''.|
|time.fadeOut|float|Duration in seconds of fading out. Default value is ''1''.|
|smoothStep|''true'', ''false''|Use smooth stepping for fading instead of linear stepping. Default is ''true''.|
|canvasCreator|string|Path to [[.:xmlguitheme:canvascreator|canvas creator file (.decc)]] to load and use.|
|designerSelector|string|[[guitheme|Gui theme designer selector]] to use. Uses the ''normal.canvas'' property as canvas creator.|
|designerSelector.preset|''black'', ''white''|<WRAP>Use designer selector with predefined name:
  * ''black'': ''FadeOverCanvas.Black''
  * ''white'': ''FadeOverCanvas.White''
</WRAP>|

This is an example of using this action to fade over a white canvas:
<code xml>
<action name='fadeOverCanvas.set'>
  <parameter name='designerSelector.preset'>white</parameter>
  <parameter name='time.fadeIn'>0.5</parameter>
  <parameter name='time.stay'>2</parameter>
  <parameter name='time.fadeOut'>0.5</parameter>
</action>
</code>

===== fadeOverCanvas.update =====

Update overlay parameters and run overlay actions.

^Parameter^Value^Description^
|set|''hidden'', ''shown''|Set overlay state directly.|
|fade|''in'', ''out''|Start fading in/out. Has no effect if overlay is not in the ''hidden'' state (fade in) or ''shown'' state (fade out).|

This is an example of using this action to start fading in:
<code xml>
<action name='fadeOverCanvas.update'>
  <parameter name='fade'>in</parameter>
</action>
</code>

This is an example of using this action to set overlay shown then start fading out:
<code xml>
<action name='fadeOverCanvas.update'>
  <parameter name='set'>shown</parameter>
  <parameter name='fade'>out</parameter>
</action>
</code>

====== State Machine Conditions ======

This behavior adds these state machine conditions.

===== fadeOverCanvas.check =====

Evaluate overlay parameters.

^Parameter^Value^Description^
|running|''true'', ''false''|Overlay is running. Equals to ''state'' is not ''hidden''.|
|state|''hidden'', ''fadeIn'', ''shown'', ''fadeOut''|Overlay state equals value.|
|state.not|''hidden'', ''fadeIn'', ''shown'', ''fadeOut''|Overlay state does not equal value.|

This is an example of using this condition to check that the overlay is not hidden:
<code xml>
<action name='myAction'>
  <condition>fadeOverCanvas.check</condition>
  <parameter name='state.not'>hidden</parameter>
</action>
</code>

====== State Machine Events ======

This behavior sends these state machine events.

===== fadeOverCanvas.hidden =====

Overlay is now hidden. Happens if fading out finished or the overlay has been set to hidden.

===== fadeOverCanvas.fadeIn =====

Overlay begins fading in.

===== fadeOverCanvas.shown =====

Overlay is now shown. Happens if fading in finished or the overlay has been set to shown.

===== fadeOverCanvas.fadeOut =====

Overlay begins fading out.

====== Required Behaviors ======

This behavior requires no other behaviors.

====== Optional Behaviors ======

  * [[gabehavior_statemachine|GABehaviorStateMachine]]: Add actions and conditions for state machine to use.

====== API Documentation ======

#@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1GABehaviorFadeOverCanvas.html,GABehaviorFadeOverCanvas~@#.

Since DragonScript Module Version ''1.35''

====== Use Cases ======

  * Fade over black from one scene to another.
  * Create effects like flash-bang temporarily whiteout the screen.

====== Live Examples ======

  * [[https://github.com/LordOfDragons/deexamples|DEExamples Repository]]: Element class changing color using a state machine receiving trigger events.