Name: visual effect

Type: command

Syntax: visual [effect] <effectName> [<speed>] [to <finalImage>] [with sound <audioClip>] [and param_1 <value_1> and ...]

Summary: Adds a visual effect trasition.

Introduced: 1.0

OS: mac,windows,linux,ios,android

Platforms: desktop,web,mobile

Example:
visual effect dissolve
go next card

Example:
hide me
show me with visual effect iris close slowly

Example:
lock screen
   # Do something
unlock screen with visual effect wipe up to black with sound "doom.wav"

Parameters:
effectName (enum): 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:
- "plain"
- "checkerboard": Desktop / Web
- "venetian blinds": Desktop / Web
- "iris close | iris open": Desktop / Web
- "zoom close | zoom in | zoom open | zoom out": Desktop / Web
- "wipe up | wipe down | wipe right | wipe left": Desktop / Web
- "dissolve"
- "push up | push down | push right | push left"
- "reveal up | reveal down | reveal right | reveal left": Desktop / Web / iOS / Android
- "shrink to bottom | shrink to center | shrink to top": Desktop / Web
- "stretch from bottom | stretch from center | stretch from top": Desktop / Web
- "scroll up | scroll left | scroll down | scroll right": iOS / Android
- "curl up | curl down": iOS
- "flip left | flip right": 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.
speed (enum): One of the following. If no speed is specified, the visual effect takes place at normal speed.
- "very fast"
- "fast"
- "normal"
- "very slow"
- "slow"
finalImage (enum): One of the folllwing:
- "gray"
- "inverse"
- "card"
- "white"
- "black"
audioClip: 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.
value_1: 
style (enum): The style of the iOS status bar.
- "default": The default mode for the device.
- "translucent": Semi-transparent status bar (in this case the stack appears underneath it).
- "opaque": A black status bar (in this case the stack appears below it).

Description:
Use the <visual effect> <command> to add a special effect the next time there is a move to another <card>.

When you issue a <visual effect> <command>, it is stored to be used the next time you navigate to another <card> in the same window with the <go>, <find>, or <pop> <command>. Usually, you place the <visual effect> <command> immediately before these <command|commands> in a <handler>, like this:

  visual effect dissolve -- sets up the effect
  go to card Index     -- effect is seen during the go

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 <visual effect> <command> in one <handler> and the navigation <command> in another <handler>. All visual effects are cleared when all pending <handler|handlers> <exit>.

The <visual effect> <command> affects only navigation within a window. If you want to create a transition effect when moving between <stacks>, use the go...in window form of the go <command> :

  visual effect wipe down
  go stack Index in window Part 2 -- replaces stack on screen

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:

  visual effect shrink to center to black
  visual effect stretch from center to card
  go card Showoff

The speed of visual effects is controlled by the setting of the effectRate <property>.

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 lock screen <command>.

Visual effects do not affect the rectangle of a player whose alwaysBuffer <property> is set to false. For visual effects to be seen in a <player|player's> rectangle, the <player|player's> <alwaysBuffer> must be true.

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.

If either the dontUseQT or <dontUseQTEffects> <property> is set to true, only the built-in visual effects can be used, and the additional effects generated by the <answer effect> <command> are not available.

For technical information about QuickTime special effects, see Apple Computer's QuickTime developer documentation at http://developer.apple.com/techpubs/quicktime/qtdevdocs/REF/refEffects.3d.htm.

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 http://developer.apple.com/macosx/coreimage.html.

The ability to use Core Image transition effects together with the enhanced syntax for parameter passing was introduced in version 2.6.

Changes:
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.

References: dontUseQTEffects (property), alwaysBuffer (property), multiEffect (property), stacks (function), card (keyword), black (keyword), exit (control_st), player (object), pop (command), go (command), answer effect (command), find (command), command (glossary), handler (glossary), property (glossary)

Tags: multimedia
