<doc>
	<legacy_id>2397</legacy_id>
	<name>visual effect</name>
	<type>command</type>

	<syntax>
		<example>visual [effect] <i>effectName</i> [<i>speed</i>] [to <i>finalImage</i>] [with sound <i>audioClip</i>] [and param_1 <i>value_1</i> and ...]</example>
	</syntax>

	<synonyms>
	</synonyms>

	<summary>Adds a visual effect trasition.</summary>

	<examples>
<example><p>visual effect dissolve</p><p>go next card</p></example>
<example><p>hide me</p><p>show me with visual effect iris close slowly</p><p></p></example>
<example><p>lock screen</p><p>   # Do something</p><p>unlock screen with visual effect wipe up to black with sound "doom.wav"</p></example>
	</examples>

	<history>
		<introduced version="1.0">Added.</introduced>
		<deprecated version=""></deprecated>
		<removed version=""></removed>
		<changed version="4.5.3">iOS support added</changed>
<changed version="2.7">2.7</changed>
<changed version=""></changed>
		<experimental version=""></experimental>
		<nonexperimental version=""></nonexperimental>
	</history>

	<objects>
	</objects>

	<platforms>
		<mac/>
		<windows/>
		<linux/>
		<ios/>
		<android/>
	</platforms>

	<classes>
		<desktop/>
		<web/>
		<mobile/>
	</classes>

	<security>
	</security>


	<classification>
		<category>Images &amp; Multimedia</category>
	</classification>

	<references>
		<command tag="answer effect">answer effect Command</command>
		<property tag="multiEffect">multiEffect Property</property>
		<keyword tag="black">black Keyword</keyword>
	</references>

	<description>
	<overview>Use the <b>visual effect</b> <glossary tag="command">command</glossary> to add a special effect the next time there is a move to another <keyword tag="card">card</keyword>.</overview>

		<parameters>
  <parameter>
    <name>effectName</name>
    <description>Is either an encoded QuickTime special effect description generated by the answer effect command, the name of a Core Image Transition Effect, or one of the following:</description>
    <options title="">
      <option>
        <item>plain</item>
        <description/>
      </option>
      <option>
        <item>checkerboard</item>
        <description>Desktop / Web</description>
      </option>
      <option>
        <item>venetian blinds</item>
        <description>Desktop / Web</description>
      </option>
      <option>
        <item>iris close | iris open</item>
        <description>Desktop / Web</description>
      </option>
      <option>
        <item>zoom close | zoom in | zoom open | zoom out</item>
        <description>Desktop / Web</description>
      </option>
      <option>
        <item>wipe up | wipe down | wipe right | wipe left</item>
        <description>Desktop / Web</description>
      </option>
      <option>
        <item>dissolve</item>
        <description/>
      </option>
      <option>
        <item>push up | push down | push right | push left</item>
        <description/>
      </option>
      <option>
        <item>reveal up | reveal down | reveal right | reveal left</item>
        <description>Desktop / Web / iOS / Android</description>
      </option>
      <option>
        <item>shrink to bottom | shrink to center | shrink to top</item>
        <description>Desktop / Web</description>
      </option>
      <option>
        <item>stretch from bottom | stretch from center | stretch from top</item>
        <description>Desktop / Web</description>
      </option>
      <option>
        <item>scroll up | scroll left | scroll down | scroll right</item>
        <description>iOS / Android</description>
      </option>
      <option>
        <item>curl up | curl down</item>
        <description>iOS</description>
      </option>
      <option>
        <item>flip left | flip right</item>
        <description>iOS. The background behind the flip is taken from the background color of
the current stack - i.e. the card is cut out and flipped over the stack.</description>
      </option>
    </options>
  </parameter>
  <parameter>
    <name>speed</name>
    <description>One of the following. If no speed is specified, the visual effect takes place at normal speed.</description>
    <options title="">
      <option>
        <item>very slow</item>
        <description/>
      </option>
      <option>
        <item>slow</item>
        <description/>
      </option>
      <option>
        <item>normal</item>
        <description/>
      </option>
      <option>
        <item>fast</item>
        <description/>
      </option>
      <option>
        <item>very fast</item>
        <description/>
      </option>
    </options>
  </parameter>
  <parameter>
    <name>finalImage</name>
    <description>One of the folllwing:</description>
    <options title="">
      <option>
        <item>black</item>
        <description/>
      </option>
      <option>
        <item>white</item>
        <description/>
      </option>
      <option>
        <item>gray</item>
        <description/>
      </option>
      <option>
        <item>inverse</item>
        <description/>
      </option>
      <option>
        <item>card</item>
        <description/>
      </option>
    </options>
  </parameter>
  <parameter>
    <name>audioClip</name>
    <description>A reference to an audio clip in an open stack, or the file path of a sound file. The sound is played during the transition.</description>
  </parameter>
  <parameter>
    <name>style</name>
    <description>The style of the iOS status bar.</description>
    <options title="">
      <option>
        <item>default</item>
        <description>The default mode for the device.</description>
      </option>
      <option>
        <item>translucent</item>
        <description>Semi-transparent status bar (in this case the stack appears underneath it).</description>
      </option>
      <option>
        <item>opaque</item>
        <description>A black status bar (in this case the stack appears below it).</description>
      </option>
    </options>
  </parameter>		</parameters>

	<value></value>
	<comments>When you issue a <b>visual effect</b> <glossary tag="command">command</glossary>, it is stored to be used the next time you navigate to another <keyword tag="card">card</keyword> in the same window with the <command tag="go">go</command>, <command tag="find">find</command>, or <command tag="pop">pop</command> <glossary tag="command">command</glossary>. Usually, you place the <b>visual effect</b> <glossary tag="command">command</glossary> immediately before these <glossary tag="command">commands</glossary> in a <glossary tag="handler">handler</glossary>, like this:<p></p><p>  visual effect dissolve <i>-- sets up the effect</i></p><p>  go to card Index     <i>-- effect is seen during the go</i></p><p></p><p>However, it is not necessary to execute the navigation command immediately; the visual effect is stored and used the next time you navigate. You can even issue a <b>visual effect</b> <glossary tag="command">command</glossary> in one <glossary tag="handler">handler</glossary> and the navigation <glossary tag="command">command</glossary> in another <glossary tag="handler">handler</glossary>. All visual effects are cleared when all pending <glossary tag="handler">handlers</glossary> <control_st tag="exit">exit</control_st>.</p><p></p><p>The <b>visual effect</b> <glossary tag="command">command</glossary> affects only navigation within a window. If you want to create a transition effect when moving between <function tag="stacks">stacks</function>, use the go...in window form of the <b>go</b> <glossary tag="command">command</glossary>:</p><p></p><p>  visual effect wipe down</p><p>  go stack Index in window Part 2 <i>-- replaces stack on screen</i></p><p></p><p>You can issue more than one visual effect in order to stack up several effects. All the pending visual effects are executed in the order they were issued during the card transition. This example makes the card appear to shrink and then re-expand:</p><p></p><p>  visual effect shrink to center to black</p><p>  visual effect stretch from center to card</p><p>  go card Showoff</p><p></p><p>The speed of visual effects is controlled by the setting of the <b>effectRate</b> <glossary tag="property">property</glossary>.</p><p></p><p>To execute a visual effect without moving to another card, lock the screen, make any changes you want to the card's appearance, and use the unlock screen with visual effect form of the <b>lock screen</b> <glossary tag="command">command</glossary>.</p><p></p><p>Visual effects do not affect the rectangle of a player whose <b>alwaysBuffer</b> <glossary tag="property">property</glossary> is set to false. For visual effects to be seen in a <glossary tag="player">player's</glossary> rectangle, the <glossary tag="player">player's</glossary> <property tag="alwaysBuffer">alwaysBuffer</property> must be true.</p><p></p><p>All visual effects function correctly on stacks with a deep mask. In this case, the alpha channel is taken into account and moves with the colour of the pixel. For example, a Core Image ripple effect appears to ripple the actual window itself, not just its contents.</p><p></p><p>If either the <b>dontUseQT</b> or <property tag="dontUseQTEffects">dontUseQTEffects</property> <glossary tag="property">property</glossary> is set to true, only the built-in visual effects can be used, and the additional effects generated by the <command tag="answer effect">answer effect</command> <glossary tag="command">command</glossary> are not available.</p><p></p><p>For technical information about QuickTime special effects, see Apple Computer's QuickTime developer documentation at <u>http://developer.apple.com/techpubs/quicktime/qtdevdocs/REF/refEffects.3d.htm</u>.</p><p></p><p>The Core Image visual effects are only available on MacOS 10.4 and later. For technical information about these effects, see Apple Computer' Core Image developer documentation <u>http://developer.apple.com/macosx/coreimage.html</u>.</p><p></p><p></p><p></p><change><p>The ability to use QuickTime special effects was introduced in version 1.1. In previous versions, only the built-in visual effects listed in the Parameters section were available.</change><p>The ability to use Core Image transition effects together with the enhanced syntax for parameter passing was introduced in version 2.6.</p><p>&#9;</p></comments>
	</description>
</doc>