Flash CS3 Documentation

ActionScript 2.0 Language Reference > ActionScript classes > Button > filters (Button.filters property)

filters (Button.filters property)

An indexed array containing each filter object currently associated with the button. The flash.filters package contains several classes that define specific filters that you can use.

Filters can be applied in the Flash authoring tool at design-time, or at runtime using ActionScript code. To apply a filter using ActionScript, you must make a temporary copy of the entire Button.filters array, modify the temporary array, and then assign the value of the temporary array back to the Button.filters array. You cannot directly add a new filter object to the Button.filters array. The following code has no effect on the target button, named myButton:

myButton.filters[0].push(myDropShadow);

To add a filter using ActionScript, you must follow these steps (assume that the target button is named myButton):

• Create a new filter object using the constructor function of your chosen filter class.
• Assign the value of the myButton.filters array to a temporary array, such as one named myFilters.
• Add the new filter object to the temporary array, myFilters.
• Assign the value of the temporary array to the myButton.filters array.

If the filters array is empty, you need not use a temporary array. Instead, you can directly assign an array literal that contains one or more filter objects that you have created.

To modify an existing filter object, whether it was created at design-time or at runtime, you must use the technique of modifying a copy of the filters array:

• Assign the value of the myButton.filters array to a temporary array, such as one named myFilters.
• Modify the property using the temporary array, myFilters. For example, if you want to set the quality property of the first filter in the array, you could use the following code: myList[0].quality = 1;
• Assign the value of the temporary array to the myButton.filters array.

To clear the filters for a button, set filters to an empty array ([]).

At load time, if a button has an associated filter, it is marked to cache itself as a transparent bitmap. From this point forward, as long as the button has a valid filter list, the player caches the button as a bitmap. This bitmap is used as a source image for the filter effects. Each button usually has two sets of bitmaps: one with the original unfiltered source button and another for the final images (in each of the four button states) after filtering. The final image set is used when rendering. As long as the button does not change, the final image does not need updating.

If you are working with a filters array that contains multiple filters and you need to track the type of filter assigned to each array index, you can maintain your own filters array and use a separate data structure to track the type of filter associated with each array index. There is no simple way to determine the type of filter associated with each filters array index.

Availability: ActionScript 1.0; Flash Player 8

Example

The following example adds a drop shadow filter to a button named myButton.

import flash.filters.DropShadowFilter;
var myDropFilter:DropShadowFilter = new DropShadowFilter(6, 45, 0x000000, 50, 5, 5, 1, 2, false, false, false); 
var myFilters:Array = myButton.filters;
myFilters.push(myDropFilter);
myButton.filters = myFilters;

The following example changes the quality setting of the first filter in the array to 15 (this example works only if at least one filter object has been associated with the myButton text field).

var myList:Array = myButton.filters;
myList[0].quality = 15;
myButton.filters = myList;

See also

cacheAsBitmap (Button.cacheAsBitmap property)

Flash CS3