Visual effect

Adds a visual effect transition.

Syntax:

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

Examples:

visual effect dissolve
go next card

hide me
show me with visual effect iris close slowly

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

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 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 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's rectangle, the 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 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 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. The use of QuickTime was deprecated in version 8.1 of LiveCode with new defaults for dontUseQT and dontUseQTEffects as true on all systems apart from pre OS X 10.8. The Windows build of LiveCode no longer supports any QuickTime features and setting the dontUseQT and dontUseQTEffects will have no effect. Additionally QuickTime does not include 64 bit support and therefore can not be supported on OS X 64 bit builds of LiveCode.

Parameters:

• effectName: an encoded QuickTime special effect description generated by answer effect. The name of a Core Image Transition Effect:
  • "plain"
  • "checkerboard"
  • "venetian blinds"
  • "iris close"
  • "iris open"
  • "zoom close"
  • "zoom in"
  • "zoom open"
  • "zoom out"
  • "wipe up"
  • "wipe down"
  • "wipe right"
  • "wipe left"
  • "dissolve"
  • "push up"
  • "push down"
  • "push right"
  • "push left"
  • "reveal up"
  • "reveal down"
  • "reveal right"
  • "reveal left"
  • "shrink to bottom"
  • "shrink to center"
  • "shrink to top"
  • "stretch from bottom"
  • "stretch from center"
  • "stretch from top"
  • "scroll up"
  • "scroll left"
  • "scroll down"
  • "scroll right"
  • "curl up"
  • "curl down"
  • "flip left"
  • "flip right"
• speed: If no speed is specified, the visual effect takes place at normal speed:
  • "very fast"
  • "fast"
  • "normal"
  • "very slow"
  • "slow":
• finalImage:
  • "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: 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).

See also: find (command), exit, stacks (function), player (object), dontUseQT (property), dontUseQTEffects (property), alwaysBuffer (property), multiEffect (property),