Print Friendly

# Class Ext.Fx

Package: | Ext
Class: | Fx
Extends: | Object
Defined In: | Fx.js

A class to provide basic animation and visual effects support. Note: This class is automatically applied to the Ext.Element interface when included, so all effects calls should be performed via Element. Conversely, since the effects are not actually defined in Element, Ext.Fx must be included in order for the Element effects to work.

It is important to note that although the Fx methods and many non-Fx Element methods support "method chaining" in that they return the Element object itself as the method return value, it is not always possible to mix the two in a single method chain. The Fx methods use an internal effects queue so that each effect can be properly timed and sequenced. Non-Fx methods, on the other hand, have no such internal queueing and will always execute immediately. For this reason, while it may be possible to mix certain Fx and non-Fx method calls in a single chain, it may not always provide the expected results and should be done with care.

Motion effects support 8-way anchoring, meaning that you can choose one of 8 different anchor points on the Element that will serve as either the start or end point of the animation. Following are all of the supported anchor positions:

    Value  Description
    -----  -----------------------------
    tl     The top left corner
    t      The center of the top edge
    tr     The top right corner
    l      The center of the left edge
    r      The center of the right edge
    bl     The bottom left corner
    b      The center of the bottom edge
    br     The bottom right corner

Although some Fx methods accept specific custom config parameters, the ones shown in the Config Options section below are common options that can be passed to any Fx method.
Properties - Methods - Events - Config Options

## Public Properties

This class has no public properties.

## Public Methods

Method | Defined By
--- | ---
| fadeIn([`Object options`]) : Element | Fx
Fade an element in (from transparent to opaque). The ending opacity can be specified using the "endOpacity" config o...
| fadeOut([`Object options`]) : Element | Fx
Fade an element out (from opaque to transparent). The ending opacity can be specified using the "endOpacity" config ...
| frame([`String color`], [`Number count`], [`Object options`]) : Element | Fx
Shows a ripple of exploding, attenuating borders to draw attention to an Element. Usage: // default: a single light ...
| ghost([`String anchor`], [`Object options`]) : Element | Fx
Slides the element while fading it out of view. An anchor point can be optionally passed to set the ending point of...
| hasActiveFx() : Boolean | Fx
Returns true if the element has any effects actively running or queued, else returns false.
| hasFxBlock() : Boolean | Fx
Returns true if the element is currently blocking so that no other effect can be queued until this effect is finished...
| highlight([`String color`], [`Object options`]) : Element | Fx
Highlights the Element by setting a color (applies to the background-color by default, but can be changed using the "...
| pause(`Number seconds`) : Element | Fx
Creates a pause before any subsequent queued effects begin. If there are no effects queued after the pause it will h...
| puff([`Object options`]) : Element | Fx
Fades the element out while slowly expanding it in all directions. When the effect is completed, the element will b...
| scale(`Number width`, `Number height`, [`Object options`]) : Element | Fx
Animates the transition of an element's dimensions from a starting height/width to an ending height/width. Usage: //...
| sequenceFx() : Element | Fx
Ensures that all effects queued after sequenceFx is called on the element are run in sequence. This is the opposite ...
| shift(`Object options`) : Element | Fx
Animates the transition of any combination of an element's dimensions, xy position and/or opacity. Any of these prope...
| slideIn([`String anchor`], [`Object options`]) : Element | Fx
Slides the element into view. An anchor point can be optionally passed to set the point of origin for the slide effe...
| slideOut([`String anchor`], [`Object options`]) : Element | Fx
Slides the element out of view. An anchor point can be optionally passed to set the end point for the slide effect. ...
| stopFx() : Element | Fx
Stops any running effects and clears the element's internal effects queue if it contains any additional effects that ...
| switchOff([`Object options`]) : Element | Fx
Blinks the element as if it was clicked and then collapses on its center (similar to switching off a television). Whe...
| syncFx() : Element | Fx
Ensures that all effects queued after syncFx is called on the element are run concurrently. This is the opposite of ...

## Public Events

This class has no public events.

## Config Options

Config Options | Defined By
--- | ---
| afterCls : String | Fx
A css class to apply after the effect
| afterStyle : String/Object/Function | Fx
A style specification string eg "width:100px", or object in the form {width:"100px"}, or a function which returns suc...
| block : Boolean | Fx
Whether the effect should block other effects from queueing while it runs
| callback : Function | Fx
A function called when the effect is finished
| concurrent : Boolean | Fx
Whether to allow subsequently-queued effects to run at the same time as the current effect, or to ensure that they ru...
| duration : Number | Fx
The length of time (in seconds) that the effect should last
| easing : String | Fx
A valid Easing value for the effect
| remove : Boolean | Fx
Whether the Element should be removed from the DOM and destroyed after the effect finishes
| scope : Object | Fx
The scope of the effect function
| stopFx : Boolean | Fx
Whether subsequent effects should be stopped and removed after the current effect finishes
| useDisplay : Boolean | Fx
Whether to use the display style attribute instead of visibility when hiding Elements (only applies to effects that e...

## Method Details

### fadeIn

`public function fadeIn([`Object options`])`
Fade an element in (from transparent to opaque). The ending opacity can be specified using the "endOpacity" config option. Usage:

    // default: fade in from opactiy 0 to 100%
    el.fadeIn();

    // custom: fade in from opcaity 0 to 75% over 2 seconds
    el.fadeIn({ endOpacity: .75, duration: 2});

    // common config options shown with default values
    el.fadeIn({

    	endOpacity: 1, //can be any value between 0 and 1 (e.g. .5)

        easing: 'easeOut',

        duration: .5

    });

Parameters:

- `options` : Object
  (optional) Object literal with any of the Fx config options

Returns:

- `Element`
  The Element

This method is defined by Fx.

### fadeOut

`public function fadeOut([`Object options`])`
Fade an element out (from opaque to transparent). The ending opacity can be specified using the "endOpacity" config option. Usage:

    // default: fade out from the element's current opacity to 0
    el.fadeOut();

    // custom: fade out from the element's current opacity to 25% over 2 seconds
    el.fadeOut({ endOpacity: .25, duration: 2});

    // common config options shown with default values
    el.fadeOut({

    	endOpacity: 0, //can be any value between 0 and 1 (e.g. .5)

        easing: 'easeOut',

        duration: .5

        remove: false,

        useDisplay: false
    });

Parameters:

- `options` : Object
  (optional) Object literal with any of the Fx config options

Returns:

- `Element`
  The Element

This method is defined by Fx.

### frame

`public function frame([`String color`], [`Number count`], [`Object options`])`
Shows a ripple of exploding, attenuating borders to draw attention to an Element. Usage:

    // default: a single light blue ripple
    el.frame();

    // custom: 3 red ripples lasting 3 seconds total
    el.frame("ff0000", 3, { duration: 3 });

    // common config options shown with default values
    el.frame("C3DAF9", 1, {

        duration: 1 //duration of entire animation (not each individual ripple)

        // Note: Easing is not configurable and will be ignored if included
    });

Parameters:

- `color` : String
  (optional) The color of the border. Should be a 6 char hex color without the leading # (defaults to light blue: 'C3DAF9').
- `count` : Number
  (optional) The number of ripples to display (defaults to 1)
- `options` : Object
  (optional) Object literal with any of the Fx config options

Returns:

- `Element`
  The Element

This method is defined by Fx.

### ghost

`public function ghost([`String anchor`], [`Object options`])`
Slides the element while fading it out of view. An anchor point can be optionally passed to set the ending point of the effect. Usage:

    // default: slide the element downward while fading out
    el.ghost();

    // custom: slide the element out to the right with a 2-second duration
    el.ghost('r', { duration: 2 });

    // common config options shown with default values
    el.ghost('b', {

        easing: 'easeOut',

        duration: .5

        remove: false,

        useDisplay: false
    });

Parameters:

- `anchor` : String
  (optional) One of the valid Fx anchor positions (defaults to bottom: 'b')
- `options` : Object
  (optional) Object literal with any of the Fx config options

Returns:

- `Element`
  The Element

This method is defined by Fx.

### hasActiveFx

`public function hasActiveFx()`
Returns true if the element has any effects actively running or queued, else returns false.
Parameters:

- None.

Returns:

- `Boolean`
  True if element has active effects, else false

This method is defined by Fx.

### hasFxBlock

`public function hasFxBlock()`
Returns true if the element is currently blocking so that no other effect can be queued until this effect is finished, else returns false if blocking is not set. This is commonly used to ensure that an effect initiated by a user action runs to completion prior to the same effect being restarted (e.g., firing only one effect even if the user clicks several times).
Parameters:

- None.

Returns:

- `Boolean`
  True if blocking, else false

This method is defined by Fx.

### highlight

`public function highlight([`String color`], [`Object options`])`
Highlights the Element by setting a color (applies to the background-color by default, but can be changed using the "attr" config option) and then fading back to the original color. If no original color is available, you should provide the "endColor" config option which will be cleared after the animation. Usage:

    // default: highlight background to yellow
    el.highlight();

    // custom: highlight foreground text to blue for 2 seconds
    el.highlight("0000ff", { attr: 'color', duration: 2 });

    // common config options shown with default values
    el.highlight("ffff9c", {

        attr: "background-color", //can be any valid css attribute that supports a color value

        endColor: (current color) or "ffffff",

        easing: 'easeIn',

        duration: 1

    });

Parameters:

- `color` : String
  (optional) The highlight color. Should be a 6 char hex color without the leading # (defaults to yellow: 'ffff9c')
- `options` : Object
  (optional) Object literal with any of the Fx config options

Returns:

- `Element`
  The Element

This method is defined by Fx.

### pause

`public function pause(`Number seconds`)`
Creates a pause before any subsequent queued effects begin. If there are no effects queued after the pause it will have no affect. Usage:

    el.pause(1);

Parameters:

- `seconds` : Number
  The length of time to pause (in seconds)

Returns:

- `Element`
  The Element

This method is defined by Fx.

### puff

`public function puff([`Object options`])`
Fades the element out while slowly expanding it in all directions. When the effect is completed, the element will be hidden (visibility = 'hidden') but block elements will still take up space in the document. The element must be removed from the DOM using the 'remove' config option if desired. Usage:

    // default
    el.puff();

    // common config options shown with default values
    el.puff({

        easing: 'easeOut',

        duration: .5,

        remove: false,

        useDisplay: false
    });

Parameters:

- `options` : Object
  (optional) Object literal with any of the Fx config options

Returns:

- `Element`
  The Element

This method is defined by Fx.

### scale

`public function scale(`Number width`, `Number height`, [`Object options`])`
Animates the transition of an element's dimensions from a starting height/width to an ending height/width. Usage:

    // change height and width to 100x100 pixels
    el.scale(100, 100);

    // common config options shown with default values.  The height and width will default to
    // the element's existing values if passed as null.
    el.scale(
    	[element's width],

    	[element's height], {

        easing: 'easeOut',

        duration: .35

    });

Parameters:

- `width` : Number
  The new width (pass null to keep the original width)
- `height` : Number
  The new height (pass null to keep the original height)
- `options` : Object
  (optional) Object literal with any of the Fx config options

Returns:

- `Element`
  The Element

This method is defined by Fx.

### sequenceFx

`public function sequenceFx()`
Ensures that all effects queued after sequenceFx is called on the element are run in sequence. This is the opposite of syncFx.
Parameters:

- None.

Returns:

- `Element`
  The Element

This method is defined by Fx.

### shift

`public function shift(`Object options`)`
Animates the transition of any combination of an element's dimensions, xy position and/or opacity. Any of these properties not specified in the config object will not be changed. This effect requires that at least one new dimension, position or opacity setting must be passed in on the config object in order for the function to have any affect. Usage:

    // slide the element horizontally to x position 200 while changing the height and opacity
    el.shift({ x: 200, height: 50, opacity: .8 });

    // common config options shown with default values.
    el.shift({
    	width: [element's width],

    	height: [element's height],

    	x: [element's x position],

    	y: [element's y position],

    	opacity: [element's opacity],

        easing: 'easeOut',

        duration: .35

    });

Parameters:

- `options` : Object
  Object literal with any of the Fx config options

Returns:

- `Element`
  The Element

This method is defined by Fx.

### slideIn

`public function slideIn([`String anchor`], [`Object options`])`
Slides the element into view. An anchor point can be optionally passed to set the point of origin for the slide effect. This function automatically handles wrapping the element with a fixed-size container if needed. See the Fx class overview for valid anchor point options. Usage:

    // default: slide the element in from the top
    el.slideIn();

    // custom: slide the element in from the right with a 2-second duration
    el.slideIn('r', { duration: 2 });

    // common config options shown with default values
    el.slideIn('t', {

        easing: 'easeOut',

        duration: .5

    });

Parameters:

- `anchor` : String
  (optional) One of the valid Fx anchor positions (defaults to top: 't')
- `options` : Object
  (optional) Object literal with any of the Fx config options

Returns:

- `Element`
  The Element

This method is defined by Fx.

### slideOut

`public function slideOut([`String anchor`], [`Object options`])`
Slides the element out of view. An anchor point can be optionally passed to set the end point for the slide effect. When the effect is completed, the element will be hidden (visibility = 'hidden') but block elements will still take up space in the document. The element must be removed from the DOM using the 'remove' config option if desired. This function automatically handles wrapping the element with a fixed-size container if needed. See the Fx class overview for valid anchor point options. Usage:

    // default: slide the element out to the top
    el.slideOut();

    // custom: slide the element out to the right with a 2-second duration
    el.slideOut('r', { duration: 2 });

    // common config options shown with default values
    el.slideOut('t', {

        easing: 'easeOut',

        duration: .5,

        remove: false,

        useDisplay: false
    });

Parameters:

- `anchor` : String
  (optional) One of the valid Fx anchor positions (defaults to top: 't')
- `options` : Object
  (optional) Object literal with any of the Fx config options

Returns:

- `Element`
  The Element

This method is defined by Fx.

### stopFx

`public function stopFx()`
Stops any running effects and clears the element's internal effects queue if it contains any additional effects that haven't started yet.
Parameters:

- None.

Returns:

- `Element`
  The Element

This method is defined by Fx.

### switchOff

`public function switchOff([`Object options`])`
Blinks the element as if it was clicked and then collapses on its center (similar to switching off a television). When the effect is completed, the element will be hidden (visibility = 'hidden') but block elements will still take up space in the document. The element must be removed from the using the 'remove' config option if desired. Usage:

    // default
    el.switchOff();

    // all config options shown with default values
    el.switchOff({

        easing: 'easeIn',

        duration: .3,

        remove: false,

        useDisplay: false
    });

Parameters:

- `options` : Object
  (optional) Object literal with any of the Fx config options

Returns:

- `Element`
  The Element

This method is defined by Fx.

### syncFx

`public function syncFx()`
Ensures that all effects queued after syncFx is called on the element are run concurrently. This is the opposite of sequenceFx.
Parameters:

- None.

Returns:

- `Element`
  The Element

This method is defined by Fx.

## Config Details

### afterCls

`afterCls : String`
A css class to apply after the effect
This config option is defined by Fx.

### afterStyle

`afterStyle : String/Object/Function`
A style specification string eg "width:100px", or object in the form {width:"100px"}, or a function which returns such a specification that will be applied to the Element after the effect finishes
This config option is defined by Fx.

### block

`block : Boolean`
Whether the effect should block other effects from queueing while it runs
This config option is defined by Fx.

### callback

`callback : Function`
A function called when the effect is finished
This config option is defined by Fx.

### concurrent

`concurrent : Boolean`
Whether to allow subsequently-queued effects to run at the same time as the current effect, or to ensure that they run in sequence
This config option is defined by Fx.

### duration

`duration : Number`
The length of time (in seconds) that the effect should last
This config option is defined by Fx.

### easing

`easing : String`
A valid Easing value for the effect
This config option is defined by Fx.

### remove

`remove : Boolean`
Whether the Element should be removed from the DOM and destroyed after the effect finishes
This config option is defined by Fx.

### scope

`scope : Object`
The scope of the effect function
This config option is defined by Fx.

### stopFx

`stopFx : Boolean`
Whether subsequent effects should be stopped and removed after the current effect finishes
This config option is defined by Fx.

### useDisplay

`useDisplay : Boolean`
Whether to use the display style attribute instead of visibility when hiding Elements (only applies to effects that end with the element being visually hidden, ignored otherwise)
This config option is defined by Fx.

Ext - Copyright © 2006-2007 Ext JS, LLC
All rights reserved.