Google Git
Sign in
apache / flex-site / ec799639d0bc0fab0451242bf01d2720166d9a1a / . / content / doc / flex / using / flx_controls_ctr.html
blob: c928100fa5bf5acf8868caface95537f5049745a [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="en-us" xml:lang="en-us">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<meta name="DC.Type" content="topic"/>
<meta name="DC.Title" content="UI Controls"/>
<meta name="DC.Format" content="XHTML"/>
<meta name="DC.Identifier" content="WS2db454920e96a9e51e63e3d11c0bf69084-7ff8_verapache"/>
<link rel="stylesheet" type="text/css" href="commonltr.css"/>
<title>UI Controls</title>
</head>
<body id="WS2db454920e96a9e51e63e3d11c0bf69084-7ff8_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7ff8_verapache"><!-- --></a>
<h1 class="topictitle1">UI Controls</h1>
<div>
<p>UI Controls are user-interface components such as Button,
TextArea, and CheckBox controls. Flex has
two types of controls: basic and data provider. For information
on data provider controls, see <a href="flx_dpcontrols_dpc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d7e_verapache">MX
data-driven controls</a>.</p>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fff_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fff_verapache"><!-- --></a>
<h2 class="topictitle2">About UI controls</h2>
<div>
<p>
<em>UI controls</em> are
user-interface components, such as <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/Button.html" target="_blank">Button</a>, <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/TextArea.html" target="_blank">TextArea</a>,
and <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/CheckBox.html" target="_blank">CheckBox</a> controls.
You place UI controls in containers, which are user-interface components
that provide a hierarchical structure for controls and other containers.
Typically, you define a container, and then insert UI controls or
other containers in it. </p>
<p>At the root of your MXML application is the <samp class="codeph">&lt;s:Application&gt;</samp> tag.
This tag represents a base container that covers the entire Adobe<sup>®</sup> Flash<sup>®</sup> Player
or Adobe AIR™ drawing surface. You can place
controls or containers directly under the <samp class="codeph">&lt;s:Application&gt;</samp> tag
or in other containers. For more information on containers, see <a href="flx_containers_intro_cn.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ffa_verapache">Introduction
to containers</a>.</p>
<p>Flex provides a set of UI controls built for the Spark architecture.
To take advantage of the skinning architecture in Spark, use the
Spark controls whenever possible. The MX controls are also supported.
You can use a combination of MX and Spark controls in an application. </p>
<p>To use Spark controls, include the Spark namespace (default prefix: <samp class="codeph">s</samp>)
in your Application tag. To use MX controls, include the MX namespace
(default prefix: <samp class="codeph">mx</samp>) in your Application tag. </p>
<div class="p">
<pre class="codeblock">xmlns:s = "library://ns.adobe.com/flex/spark"
xmlns:mx = "library://ns.adobe.com/flex/mx"</pre>
</div>
<p>Most controls have the following characteristics:</p>
<ul>
<li>
<p>MXML API for declaring the control and the values of
its properties and events</p>
</li>
<li>
<p>ActionScript API for calling the control’s methods and setting
its properties at run time</p>
</li>
<li>
<p>Customizable appearance by using styles, skins, and fonts</p>
</li>
</ul>
<p>The MXML and ActionScript APIs let you create and configure a
control. The following MXML code example creates a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/TextInput.html" target="_blank">TextInput</a> control
in a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/Form.html" target="_blank">Form</a> container: </p>
<pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!--controls\TextInputInForm.mxml--&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:Form width="400" height="100"&gt;
&lt;s:FormItem label="Card Name"&gt;
&lt;s:TextInput id="cardName"/&gt;
&lt;/s:FormItem&gt;
&lt;/s:Form&gt;
&lt;/s:Application&gt;</pre>
<p>Although you commonly use MXML as the language for building applications
in Flex, you can also use ActionScript to configure controls. For
example, the following code example populates a Spark <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/DataGrid.html" target="_blank">DataGrid</a> control
by providing an Array of items as the value of the DataGrid control’s <samp class="codeph">dataProvider</samp> property: </p>
<pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!--controls\DataGridConfigAS.mxml--&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
private function myGrid_initialize():void {
myGrid.dataProvider = new ArrayCollection([
{Artist:'Steve Goodman', Album:'High and Outside', Price:8.99},
{Artist:'Carole King', Album:'Tapestry', Price:11.99},
{Artist:'The Beach Boys', Album:'Pet Sounds', Price:13.99},
{Artist:'Original Cast', Album:'Camelot', Price:9.99} ]);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:DataGrid id="myGrid"
width="350" height="150"
color="#7B0974"
creationComplete="myGrid_initialize();"/&gt;
&lt;/s:Application&gt;</pre>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7ffe_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7ffe_verapache"><!-- --></a>
<h3 class="topictitle3">Text controls</h3>
<div>
<p>Several Flex components display text or take text input,
as the following table shows:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e185">
<p>Type of text</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e191">
<p>Spark control</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e197">
<p>MX control</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e185 ">
<p>Editable, single-line text </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e191 ">
<p>TextInput</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e197 ">
<p>TextInput</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e185 ">
<p>Editable, multiline text </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e191 ">
<p>TextArea</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e197 ">
<p>TextArea</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e185 ">
<p>Noneditable, single-line text </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e191 ">
<p>Label</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e197 ">
<p>Label</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e185 ">
<p>Noneditable, multiline text </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e191 ">
<p>Label</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e197 ">
<p>Text</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e185 ">
<p>Noneditable, richly formatted text </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e191 ">
<p>RichText</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e197 ">
<p>n/a</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e185 ">
<p>Editable, richly formatted text </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e191 ">
<p>RichEditableText</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e197 ">
<p>n/a</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e185 ">
<p>Compound control that contains a multiline
text field and controls that let you format text by selecting such
characteristics as font, size, weight, and alignment</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e191 ">
<p>n/a</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e197 ">
<p>RichTextEditor</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>
These
controls can display plain text that all has the same appearance.
The controls can also display rich text formatted by using a subset
of the standard HTML formatting tags. For information on using text
controls, see <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d84_verapache">MX
text controls</a>.</p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7c73_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7c73_verapache"><!-- --></a>
<h3 class="topictitle3">Data provider controls</h3>
<div>
<p>
Several
Flex components, such as the MX <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/DataGrid.html" target="_blank">DataGrid</a> and <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/Tree.html" target="_blank">Tree</a> controls,
and the Spark <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/ComboBox.html" target="_blank">ComboBox</a> and <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/List.html" target="_blank">List</a> controls,
take input data from a data provider. A <em>data provider</em> is
a collection of objects, similar to an array. For example, a Tree
control reads data from the data provider to define the structure
of the tree and any associated data assigned to each tree node. </p>
<p>The data provider creates a level of abstraction between Flex
components and the data that you use to populate them. You can populate
multiple components from the same data provider, switch data providers
for a component at runtime, and modify the data provider so that
changes are reflected by all components that use the data provider. </p>
<p>Consider that the data provider is the model, and the components
are the view onto the model. By separating the model from the view,
you can change one without changing the other. </p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7ffc_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7ffc_verapache"><!-- --></a>
<h3 class="topictitle3">Menu controls</h3>
<div>
<p>
Several
MX controls create or interact with menus, as the following table
shows:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e447">
<p>MX control (in mx.controls package)</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e453">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e447 ">
<p>Menu</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e453 ">
<p>A visual menu that can have cascading submenus</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e447 ">
<p>MenuBar</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e453 ">
<p>A horizontal bar with multiple submenus</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e447 ">
<p>PopUpMenuButton</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e453 ">
<p>A Menu control that opens when you click
a button</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>In Spark, you can create custom menu-type controls using the <a href="flx_controls_ctr.html#WSb04c7610c3432839-69935906121d15620a8-8000_verapache">PopUpAnchor control</a>. </p>
<p>For information on menu controls, see <a href="flx_menucontrols_mc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d7b_verapache">Menu-based
controls</a>.</p>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7ffa_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7ffa_verapache"><!-- --></a>
<h2 class="topictitle2">Working with controls</h2>
<div>
<p>Controls share a common class hierarchy. Therefore, you
use a similar procedure to configure all controls. </p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7ff9_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7ff9_verapache"><!-- --></a>
<h3 class="topictitle3">Class hierarchy of controls</h3>
<div>
<p>
Controls
are ActionScript objects derived from the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/display/Sprite.html" target="_blank">flash.display.Sprite</a>, <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/core/FlexSprite.html" target="_blank">mx.core.FlexSprite</a>,
and <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/core/UIComponent.html" target="_blank">mx.core.UIComponent</a> classes,
as the following diagram shows. Controls inherit the properties,
methods, events, styles, skin parts, skin states, and effects of
these superclasses:</p>
<div class="figborder"><span class="figdesc">Class hierarchy of controls</span>
<img src="images/ctr_hierarchy_FLSprite_Controls.png"/>
</div>
<p>The Sprite, FlexSprite, and UIComponent classes are the base
classes for all Flex components. Subclasses of the UIComponent class
can have shape, draw themselves, and be invisible. Each subclass
can participate in tabbing. Subclasses can accept low-level events
like keyboard and mouse input. They can be disabled so that they
do not receive mouse and keyboard input.</p>
<p>For information on the interfaces inherited by controls from
the Sprite and UIComponent classes, see <a href="flx_components_cmp.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fff_verapache">Visual
components</a>. </p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7ff8_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7ff8_verapache"><!-- --></a>
<h3 class="topictitle3">Sizing controls</h3>
<div>
<p>
All controls
define rules for determining their size in an application. For example, a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/Button.html" target="_blank">Button</a> control
sizes itself to fit its label text and optional icon image. An Image control
sizes itself to the size of the imported image. Each control has
a default height and a default width. The default size of each standard
control is specified in the description of each control. </p>
<p>The default size of a control is not necessarily a fixed value.
For example, for a Button control, the default size is large enough
to fit its label text and optional icon image. At runtime, Flex
calculates the default size of each control and, by default, does
not resize a control from its default size. </p>
<p>
Set the <samp class="codeph">height</samp> and <samp class="codeph">width</samp> attributes
in MXML to percentages, such as 50%, or the <samp class="codeph">percentHeight</samp> and <samp class="codeph">percentWidth</samp> properties
in ActionScript to percentage values, such as 50, to allow Flex
to resize the control in the corresponding direction. Flex attempts
to fit the control to the percentage of its parent container that
you specify. If there isn’t enough space available, the percentages are
scaled, while retaining their relative values. </p>
<p>For example, you can set the width of a comments box to scale
with its parent container as the parent container changes size:</p>
<pre class="codeblock"> &lt;s:TextArea id="comments" width="100%" height ="20"/&gt; </pre>
<p>You can also specify explicit sizes for a control in MXML or
ActionScript by setting the <samp class="codeph">height</samp> and <samp class="codeph">width</samp> properties
to numeric pixel values. The following example sets the height and
width of the <samp class="codeph">addr2</samp> TextInput control to 20 pixels and
100 pixels, respectively:</p>
<pre class="codeblock"> &lt;s:TextInput id="addr2" width="100" height ="20"/&gt;</pre>
<p>To resize a control at runtime, use ActionScript to set its <samp class="codeph">width</samp> and <samp class="codeph">height</samp> properties.
For example, the click event listener for the following Button control increases
the value of the <samp class="codeph">width </samp>property of the <samp class="codeph">addr2</samp> TextInput
control by ten pixels:</p>
<pre class="codeblock"> &lt;s:Button id="button1" label="Slide" height="20"
  click="addr2.width+=10;"/&gt; </pre>
<div class="note"><span class="notetitle">Note:</span> The preceding technique works even if the <samp class="codeph">width</samp> property
was originally set as a percentage value. The stored values of the <samp class="codeph">width</samp> and <samp class="codeph">height</samp> properties
are always in pixels.</div>
<p>Many components have arbitrarily large maximum sizes, which means
that Flex can make them as large as necessary to fit the requirements
of your application. While some components have a defined nonzero
minimum size, most have a minimum size of 0. You can use the <samp class="codeph">maxHeight</samp>, <samp class="codeph">maxWidth</samp>, <samp class="codeph">minHeight</samp>,
and <samp class="codeph">minWidth</samp> properties to set explicit size ranges
for each component. </p>
<p>
For more information
on sizing components, see <a href="flx_size_position_sp.html#WS2db454920e96a9e51e63e3d11c0bf69084-7e4c_verapache">Laying
out components</a>. </p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7ff7_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7ff7_verapache"><!-- --></a>
<h3 class="topictitle3">Positioning controls</h3>
<div>
<p>
You
place controls inside containers. Most containers have predefined
layout rules that automatically determine the position of their
children. The Spark <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/Group.html" target="_blank">Group</a> container
positions children using BasicLayout, which is absolute positioning.
The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/HGroup.html" target="_blank">HGroup</a> container
positions children with a horizontal layout. The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/HGroup.html" target="_blank">VGroup</a> container
positions children with a vertical layout. The MX <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/containers/Canvas.html" target="_blank">Canvas</a> container
absolutely positions its children. </p>
<p>To absolutely position a control, you set its <samp class="codeph">x</samp> and <samp class="codeph">y</samp> properties
to specific horizontal and vertical pixel coordinates within the
container. These coordinates are relative to the upper-left corner
of the container, where the upper-left corner is at coordinates
(0,0). Values for <samp class="codeph">x</samp> and <samp class="codeph">y</samp> can
be positive or negative integers. You can use negative values to
place a control outside the visible area of the container. You can
then use ActionScript to move the child to the visible area, possibly
as a response to an event. </p>
<p>The following example places the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/TextInput.html" target="_blank">TextInput</a> control
150 pixels to the right and 150 pixels down from the upper-left
corner of a Canvas container:</p>
<pre class="codeblock"> &lt;s:TextInput id="addr2" width="100" height ="20" x="150" y="150"/&gt;</pre>
<p>To reposition a control within an absolutely-positioned container
at runtime, you set its <samp class="codeph">x</samp> and <samp class="codeph">y</samp> properties.
For example, the <samp class="codeph">click</samp> event listener for the following Button
control moves the TextInput control down ten pixels from its current position:</p>
<pre class="codeblock"> &lt;s:Button id="button1" label="Slide" height="20" x="0" y="250"
click="addr2.y = addr2.y+10;"/&gt; </pre>
<p>
For detailed
information about control positioning, including container-relative positioning,
see <a href="flx_size_position_sp.html#WS2db454920e96a9e51e63e3d11c0bf69084-7e4c_verapache">Laying
out components</a>. </p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7ff6_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7ff6_verapache"><!-- --></a>
<h3 class="topictitle3">Changing the appearance of controls</h3>
<div>
<p>
Styles,
skins, and fonts let you customize the appearance of controls. They describe
aspects of components that you want components to have in common. Each
control defines a set of styles, skins, and fonts that you can set.
Some of these characteristics are specific to a particular type
of control, and others are more general. In Spark, the skin controls
all visual elements of a component, including layout. See <a href="flx_gumboskinning_gs.html#WSC8DB0C28-F7A6-48ff-9899-7957415A0A49_verapache">About
Spark skins</a>.</p>
<p>Flex provides several different ways for you to configure the
appearance of your controls. For example, you can set styles for
a specific control in the control’s MXML tag, in CSS, or by using
ActionScript. You can set styles globally for all instances of a
specific control in an application by using the <samp class="codeph">&lt;fx:Style&gt;</samp> tag.</p>
<p>A <em>theme</em> defines the appearance of an application. A theme
can define something as simple as the color scheme or common font
for an application. It can also be a complete reskinning of all
the components. The current theme for your application defines the
styles that you can set on the controls within it. That means some
style properties might not always be settable. For more information, see <a href="flx_styles_st.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fee_verapache">Styles
and themes</a>. </p>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7da0_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7da0_verapache"><!-- --></a>
<h2 class="topictitle2">Alert control</h2>
<div>
<p>The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/Alert.html" target="_blank">Alert</a> control
is part of the MX component set. There is no Spark equivalent. </p>
<p>
All
Flex components can call the static <samp class="codeph">show()</samp> method
of the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/Alert.html" target="_blank">Alert</a> class
to open a modal dialog box that contains a message and an optional
title, buttons, and icons. The following example shows an Alert
control pop-up dialog box: </p>
<div class="figborder">
<img src="images/ctr_alert.png"/>
</div>
<p>The Alert control closes when you select a button in the control,
or press the Escape key. </p>
<p>The <samp class="codeph">Alert.show()</samp> method has the following syntax: </p>
<pre class="codeblock"> public static show(
  text:String,
  title:String=null,
  flags:uint=mx.controls.Alert.OK,
  parent:Sprite=null,
  clickListener:Function=null,
  iconClass:Class=null,
  defaultButton:uint=mx.controls.Alert.OK
 ):Alert</pre>
<p>This method returns an Alert control object. </p>
<p>
The
following table describes the arguments of the <samp class="codeph">show()</samp> method: </p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e927">
<p>Argument</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e933">
<p>Description </p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e927 ">
<div class="p">
<pre class="codeblock">text</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e933 ">
<p>(Required) Specifies the text message displayed
in the dialog box. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e927 ">
<div class="p">
<pre class="codeblock">title</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e933 ">
<p>Specifies the dialog box title. If omitted,
displays a blank title bar.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e927 ">
<div class="p">
<pre class="codeblock">flags</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e933 ">
<p>Specifies the buttons to display in the
dialog box. The options are as follows:</p>
<p>
<samp class="codeph">mx.controls.Alert.OK</samp> —
OK button</p>
<p>
<samp class="codeph">mx.controls.Alert.YES</samp> — Yes button</p>
<p>
<samp class="codeph">mx.controls.Alert.NO</samp> —
No button</p>
<p>
<samp class="codeph">mx.controls.Alert.CANCEL</samp> — Cancel
button</p>
<p>Each option is a bit value and can be combined with
other options by using the pipe '|' operator. The buttons appear
in the order listed here regardless of the order specified in your
code. The default value is <samp class="codeph">mx.controls.Alert.OK</samp>. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e927 ">
<div class="p">
<pre class="codeblock">parent</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e933 ">
<p>The parent object of the Alert control.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e927 ">
<div class="p">
<pre class="codeblock">clickListener</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e933 ">
<p>Specifies the listener for click events
from the buttons. </p>
<p>The event object passed to this handler
is an instance of the CloseEvent class. The event object contains
the <samp class="codeph">detail</samp> field, which is set to the button flag
that was clicked (<samp class="codeph">mx.controls.Alert.OK</samp>, <samp class="codeph">mx.controls.Alert.CANCEL</samp>, <samp class="codeph">mx.controls.Alert.YES</samp>,
or <samp class="codeph">mx.controls.Alert.NO</samp>).</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e927 ">
<div class="p">
<pre class="codeblock">iconClass</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e933 ">
<p>Specifies an icon to display to the left
of the message text in the dialog box. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e927 ">
<div class="p">
<pre class="codeblock">defaultButton</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e933 ">
<p>Specifies the default button by using one
of the valid values for the <samp class="codeph">flags</samp> argument. This
is the button that is selected when the user presses the Enter key.
The default value is <samp class="codeph">Alert.OK</samp>. </p>
<p>Pressing
the Escape key triggers the Cancel or No button.</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>To use the Alert control, you first import the Alert class into
your application, then call the <samp class="codeph">show()</samp> method,
as the following example shows: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\alert\AlertSimple.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.controls.Alert;
]]&gt;
&lt;/fx:Script&gt;
&lt;s:VGroup&gt;
&lt;s:TextInput id="myInput"
width="150"
text=""/&gt;
&lt;s:Button id="myButton"
label="Copy Text"
click="myText.text = myInput.text;
Alert.show('Text Copied!', 'Alert Box', mx.controls.Alert.OK);"/&gt;
&lt;s:TextInput id="myText"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
<p>In this example, selecting the Button control copies text from
the TextInput control to the TextArea control, and displays the
Alert control. </p>
<p>You can also define an event listener for the Button control,
as the following example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\alert\AlertSimpleEvent.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.controls.Alert;
private function alertListener():void {
myText.text = myInput.text;
Alert.show("Text Copied!", "Alert Box", Alert.OK);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:VGroup&gt;
&lt;s:TextInput id="myInput"
width="150"
text=""/&gt;
&lt;s:Button id="myButton"
label="Copy Text"
click="alertListener();"/&gt;
&lt;s:TextInput id="myText"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
<div class="note"><span class="notetitle">Note:</span> After the <samp class="codeph">show()</samp> method creates
the dialog box, Flex continues processing of your application; it
does not wait for the user to close the dialog box.</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7f9d_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7f9d_verapache"><!-- --></a>
<h3 class="topictitle3">Sizing the Alert control</h3>
<div>
<p>The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/Alert.html" target="_blank">Alert</a> control
automatically sizes itself to fit its text, buttons, and icon. You
can explicitly size an Alert control by using the Alert object returned
from the <samp class="codeph">show()</samp> method, as the following example
shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\alert\AlertSize.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.controls.Alert;
import mx.events.CloseEvent;
// Define variable to hold the Alert object.
public var myAlert:Alert;
private function openAlert():void {
myAlert = Alert.show("Copy Text?", "Alert",
Alert.OK | Alert.CANCEL);
// Set the height and width of the Alert control.
myAlert.height=250;
myAlert.width=250;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:VGroup&gt;
&lt;s:TextInput id="myInput"
width="150"
text=""/&gt;
&lt;s:Button id="myButton"
label="Copy Text"
click="openAlert();"/&gt;
&lt;s:TextInput id="myText"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
<p>In this example, you set the <samp class="codeph">height</samp> and <samp class="codeph">width</samp> properties
of the Alert object to explicitly size the control. </p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7f9c_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7f9c_verapache"><!-- --></a>
<h3 class="topictitle3">Using event listeners with the
Alert control</h3>
<div>
<p>The next example adds an event listener to the Alert control
dialog box. An event listener lets you perform processing when the
user selects a button of the Alert control. The event object passed
to the event listener is of type <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/events/CloseEvent.html" target="_blank">CloseEvent</a>. </p>
<p>
In the
next example, you only copy the text when the user selects the OK
button in the Alert control:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\alert\AlertEvent.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.controls.Alert;
import mx.events.CloseEvent;
private function alertListener(eventObj:CloseEvent):void {
// Check to see if the OK button was pressed.
if (eventObj.detail==Alert.OK) {
myText.text = myInput.text;
}
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:VGroup&gt;
&lt;s:TextInput id="myInput"
width="150"
text="" /&gt;
&lt;s:Button id="myButton"
label="Copy Text"
click='Alert.show("Copy Text?", "Alert",
Alert.OK | Alert.CANCEL, this,
alertListener, null, Alert.OK);'/&gt;
&lt;s:TextInput id="myText"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
<p>In this example, you define an event listener for the Alert control.
Within the body of the event listener, you determine which button
was pressed by examining the <samp class="codeph">detail</samp> property of
the event object. The event object is an instance of the CloseEvent
class. If the user pressed the OK button, copy the text. If the
user pressed any other button, or pressed the Escape key, do not
copy the text. </p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7f9b_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7f9b_verapache"><!-- --></a>
<h3 class="topictitle3">Specifying an Alert control icon</h3>
<div>
<p>
You
can include an icon in the Alert control that appears to the left
of the Alert control text. This example modifies the example from
the previous section to add the <samp class="codeph">Embed</samp> metadata
tag to import the icon. For more information on importing resources,
see <a href="flx_usingas_ua.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ffe_verapache">Using
ActionScript</a>. </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\alert\AlertIcon.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.controls.Alert;
import mx.events.CloseEvent;
[Embed(source="assets/alertIcon.jpg")]
[Bindable]
public var iconSymbol:Class;
private function alertListener(eventObj:CloseEvent):void {
// Check to see if the OK button was pressed.
if (eventObj.detail==Alert.OK) {
myText.text = myInput.text;
}
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:VGroup&gt;
&lt;s:TextInput id="myInput"
width="150"
text=""/&gt;
&lt;s:Button id="myButton"
label="Copy Text"
click='Alert.show("Copy Text?", "Alert",
Alert.OK | Alert.CANCEL, this,
alertListener, iconSymbol, Alert.OK );'/&gt;
&lt;s:TextInput id="myText"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d9f_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d9f_verapache"><!-- --></a>
<h2 class="topictitle2">Button and ToggleButton control</h2>
<div>
<p>The Button and ToggleButton controls are part of both the
MX and Spark component sets. While you can use the MX controls in
your application, it’s best to use the Spark controls instead.</p>
<div class="p">
<div class="note"><span class="notetitle">Note:</span> In MX, you create a toggle button by setting the <samp class="codeph">toggle</samp> property
of the MX Button control to <samp class="codeph">true</samp>. in Spark, the
ToggleButton is a separate component.</div>
</div>
<p>
The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/Button.html" target="_blank">Button</a> control
is a commonly used rectangular button. Button controls look like
they can be pressed, and have a text label, an icon, or both on
their face. You can optionally specify graphic skins for each of
several Button states. </p>
<p>You can create a normal Button control or a ToggleButton control.
A normal Button control stays in its pressed state for as long as
the mouse button is down after you select it. A ToggleButton stays
in the pressed state until you select it a second time. The ToggleButton
control is available in Spark. In MX, the Button control contains
a <samp class="codeph">toggle</samp> property that provides similar functionality.</p>
<p>Buttons typically use event listeners to perform an action when
the user selects the control. When a user clicks the mouse on a
Button control, and the Button control is enabled, it dispatches
a <samp class="codeph">click</samp> event and a <samp class="codeph">buttonDown</samp> event.
A button always dispatches events such as the <samp class="codeph">mouseMove</samp>, <samp class="codeph">mouseOver</samp>, <samp class="codeph">mouseOut</samp>, <samp class="codeph">rollOver</samp>, <samp class="codeph">rollOut</samp>, <samp class="codeph">mouseDown</samp>,
and <samp class="codeph">mouseUp</samp> events whether enabled or disabled.</p>
<p>
You
can use customized graphic skins to customize your buttons to match
your application’s look and functionality. You can give the Button
and ToggleButton controls different skins. The control can change
the image skins dynamically. The following table describes the skin
states (Spark) and skin styles (MX) available for the Button and
ToggleButton controls:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e1362">
<p>Spark Button skin states</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e1368">
<p>Spark ToggleButton skin states</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e1374">
<p>MX Button skin styles</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e1362 ">
<p>disabled</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e1368 ">
<p>disabled</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e1374 ">
<p>disabledSkin</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e1362 ">
<p>down</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e1368 ">
<p>disabledAndSelected</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e1374 ">
<p>downSkin</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e1362 ">
<p>over</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e1368 ">
<p>down</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e1374 ">
<p>overSkin</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e1362 ">
<p>up</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e1368 ">
<p>downAndSelected</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e1374 ">
<p>selectedDisabledSkin</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e1362 ">
<p>---</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e1368 ">
<p>over</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e1374 ">
<p>selectedDownSkin</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e1362 ">
<p>---</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e1368 ">
<p>overAndSelected</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e1374 ">
<p>selectedOverSkin</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e1362 ">
<p>---</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e1368 ">
<p>up</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e1374 ">
<p>selectedUpSkin</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e1362 ">
<p>---</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e1368 ">
<p>upAndSelected</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e1374 ">
<p>upSkin</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7ff4_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7ff4_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a Button control </h3>
<div>
<p>
You
define a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/Button.html" target="_blank">Button</a> control
in MXML by using the <samp class="codeph">&lt;s:Button&gt;</samp> tag, as the following
example shows. Specify an <samp class="codeph">id</samp> value if you intend
to refer to the button elsewhere in your MXML, either in another
tag or in an ActionScript block. The following code creates a Button
control with the label “Hello world!”: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\button\ButtonLabel.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:Button id="button1"
label="Hello world!"
width="100"/&gt;
&lt;/s:Application&gt;</pre>
<p>In Spark, all visual elements of a component, including layout,
are controlled by the skin. For more information on skinning, see <a href="flx_gumboskinning_gs.html#WSC8DB0C28-F7A6-48ff-9899-7957415A0A49_verapache">About
Spark skins</a>.</p>
<p>In MX, a Button control’s icon, if specified, and label are centered
within the bounds of the Button control. You can position the text
label in relation to the icon by using the <samp class="codeph">labelPlacement</samp> property,
which accepts the values <samp class="codeph">right</samp>, <samp class="codeph">left</samp>, <samp class="codeph">bottom</samp>,
and <samp class="codeph">top</samp>.</p>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7ff4_verapache__WS2db454920e96a9e51e63e3d11c0bf63b33-7ff2_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7ff4_verapache__WS2db454920e96a9e51e63e3d11c0bf63b33-7ff2_verapache"><!-- --></a><h4 class="sectiontitle">Sizing
a Button control</h4>
<p>
By
default, Flex stretches the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/Button.html" target="_blank">Button</a> control
width to fit the size of its label, any icon, plus six pixels of
padding around the icon. You can override this default width by
explicitly setting the <samp class="codeph">width</samp> property of the Button
control to a specific value or to a percentage of its parent container.
If you specify a percentage value, the button resizes between its
minimum and maximum widths as the size of its parent container changes.</p>
<p>If
you explicitly size a Button control so that it is not large enough
to accommodate its label, the label is truncated and terminated
by an ellipsis (...). The full label displays as a tooltip when
you move the mouse over the Button control. If you have also set
a tooltip by using the <samp class="codeph">toolTip</samp> property, the tooltip
is displayed rather than the label text. Text that is vertically
larger than the Button control is also clipped. </p>
<p>If you explicitly
size a Button control so that it is not large enough to accommodate
its icon, icons larger than the Button control extend outside the
Button control’s bounding box.</p>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7ff4_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7db7_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7ff4_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7db7_verapache"><!-- --></a><h4 class="sectiontitle">Button
control user interaction</h4>
<p>
When a user clicks the mouse on a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/Button.html" target="_blank">Button</a> control,
the Button control dispatches a <samp class="codeph">click</samp> event, as
the following example shows: </p>
<pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- controls\button\ButtonClick.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.controls.Alert;
protected function myBtn_clickHandler(event:MouseEvent):void {
Alert.show("Goodbye!");
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:Button id="myBtn"
x="83" y="92"
label="Hello World!"
click="myBtn_clickHandler(event)"/&gt;
&lt;/s:Application&gt;</pre>
<p>In this example, clicking the
Button triggers an Alert control to appear with a message to the
user. </p>
<p>If a Button control is enabled, it behaves as follows:</p>
<ul>
<li>
<p>When the user moves the pointer over the Button control,
the Button control displays its rollover appearance.</p>
</li>
<li>
<p>When the user clicks the Button control, focus moves to the
control and the Button control displays its pressed appearance.
When the user releases the mouse button, the Button control returns
to its rollover appearance.</p>
</li>
<li>
<p>If the user moves the pointer off the Button control while
pressing the mouse button, the control’s appearance returns to the
rollover state and it retains focus.</p>
</li>
<li>
<p>For MX controls, if the <samp class="codeph">toggle</samp> property
is set to <samp class="codeph">true</samp>, the state of the Button control
does not change until the user releases the mouse button over the control.
For the Spark ToggleButton, this statement applies to the <samp class="codeph">selected</samp> property.</p>
</li>
</ul>
<p>If
a Button control is disabled, it displays its disabled appearance,
regardless of user interaction. In the disabled state, all mouse
or keyboard interaction is ignored.</p>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7ff4_verapache__WS2db454920e96a9e51e63e3d11c0bf63b33-7ff3_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7ff4_verapache__WS2db454920e96a9e51e63e3d11c0bf63b33-7ff3_verapache"><!-- --></a><h4 class="sectiontitle">Embedding
an icon in a Button control</h4>
<p>The Button controls define
a style property, <samp class="codeph">icon</samp>, that you use to add an
icon to the button. A button icon can be a GIF, JPEG, PNG, SVG,
or SWF file.</p>
<div class="note"><span class="notetitle">Note:</span> For the MX Button control, icons must be embedded
at compile time. You cannot load the icon at runtime.</div>
<p>Use
the <samp class="codeph">@Embed</samp> syntax in the <samp class="codeph">icon</samp> property
value to embed an icon file. Or you can bind to an image that you
defined within a script block by using <samp class="codeph">[Embed]</samp> metadata.
If you must reference your button graphic at runtime, you can use
an Image control instead of a Button control.</p>
<p>For more information
on embedding resources, see <a href="flx_embed_em.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fce_verapache">Embedding
assets</a>. </p>
<p>The following code example creates a Spark
Button control with a label and icon.</p>
<div class="p">
<pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- controls\button\ButtonLabelIconSpark.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import assets.*;
import mx.controls.Alert;
protected function myClickHandler():void{
Alert.show("Thanks for submitting.")
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:Button id="iconButton"
width="100" height="30"
x="10" y="10"
label="Submit to"
icon="@Embed('assets/logo.jpg')"
click="myClickHandler();"/&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d9e_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d9e_verapache"><!-- --></a>
<h2 class="topictitle2">MX ButtonBar and MX ToggleButtonBar controls</h2>
<div>
<p>The ButtonBar control is part of both the MX and Spark
component sets. Spark does not define a separate ToggleButtonBar
control. You can use the Spark ButtonBar control to replicate the
functionality of the MX ToggleButtonBar control. While you can use
the MX controls in your application, it’s best to use the Spark
controls instead. For information on Spark ButtonBar, see <a href="flx_spark_dpcontrols_sdp.html#WSc2368ca491e3ff92-59bf082612135c9e688-8000_verapache">Spark
ButtonBar and TabBar controls</a>.</p>
<p>
The
MX <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/ButtonBar.html" target="_blank">ButtonBar</a> and <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/ToggleButtonBar.html" target="_blank">ToggleButtonBar</a> controls
define a horizontal or vertical row of related buttons with a common
appearance. The controls define a single event, the <samp class="codeph">itemClick</samp> event,
that is dispatched when any button in the control is selected. </p>
<p>
The ButtonBar
control defines group of buttons that do not retain a selected state.
When you select a button in a ButtonBar control, the button changes
its appearance to the selected state. When you release the button,
it returns to the deselected state. </p>
<p>
The ToggleButtonBar
control defines a group of buttons that maintain their state, either
selected or deselected. Only one button in the ToggleButtonBar control can
be in the selected state. That means when you select a button in
a ToggleButtonBar control, the button stays in the selected state
until you select a different button. </p>
<p>If you set the <samp class="codeph">toggleOnClick</samp> property of the
ToggleButtonBar control to <samp class="codeph">true</samp>, selecting the
currently selected button deselects it. By default the <samp class="codeph">toggleOnClick</samp> property
is <samp class="codeph">false</samp>.</p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7feb_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7feb_verapache"><!-- --></a>
<h3 class="topictitle3">Creating an MX ButtonBar control</h3>
<div>
<p>You create a ButtonBar control in MXML by using the <samp class="codeph">&lt;mx:ButtonBar&gt;</samp> tag,
as the following example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\bar\BBarSimple.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;mx:ButtonBar horizontalGap="5"&gt;
&lt;mx:dataProvider&gt;
&lt;fx:String&gt;Flex&lt;/fx:String&gt;
&lt;fx:String&gt;Installer&lt;/fx:String&gt;
&lt;fx:String&gt;FlexJS&lt;/fx:String&gt;
&lt;fx:String&gt;TourDeFlex&lt;/fx:String&gt;
&lt;/mx:dataProvider&gt;
&lt;/mx:ButtonBar&gt;
&lt;/s:Application&gt; </pre>
<p>This example creates a row of four Button controls. </p>
<p>To create a ToggleButtonBar control, replace the <samp class="codeph">&lt;mx:ButtonBar&gt;</samp> tag
with the <samp class="codeph">&lt;mx:ToggleButtonBar&gt;</samp> tag. For the
ToggleButtonBar control, the <samp class="codeph">selectedIndex</samp> property
determines which button is selected when the control is created.
The default value for <samp class="codeph">selectedIndex</samp> is 0 and selects
the leftmost button in the bar. Setting the <samp class="codeph">selectedIndex</samp> property
to -1 deselects all buttons in the bar. Otherwise, the syntax is
the same for both controls.</p>
<p>The <samp class="codeph">dataProvider</samp> property specifies the labels
of the four buttons. You can also populate the <samp class="codeph">dataProvider</samp> property
with an Array of Objects, where each object can have up to three
fields: <samp class="codeph">label</samp>, <samp class="codeph">icon</samp>, and <samp class="codeph">toolTip</samp>. </p>
<p>In the following example, an Array of Objects specifies a label
and icon for each button:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\bar\BBarLogo.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;mx:ButtonBar horizontalGap="5"&gt;
&lt;mx:dataProvider&gt;
&lt;fx:Object label="Flex"
icon="@Embed(source='assets/Flexlogo.gif')"/&gt;
&lt;fx:Object label="Installer"
icon="@Embed(source='assets/Dirlogo.gif')"/&gt;
&lt;fx:Object label="FlexJS"
icon="@Embed(source='assets/Dlogo.gif')"/&gt;
&lt;fx:Object label="TourDeFlex"
icon="@Embed(source='assets/CFlogo.gif')"/&gt;
&lt;/mx:dataProvider&gt;
&lt;/mx:ButtonBar&gt;
&lt;/s:Application&gt;</pre>
<p>A ButtonBar or ToggleButtonBar control creates Button controls
based on the value of its <samp class="codeph">dataProvider</samp> property.
Even though ButtonBar and ToggleButtonBar are subclasses of Container,
do not use the methods <samp class="codeph">Container.addChild()</samp> and <samp class="codeph">Container.removeChild()</samp> to
add or remove Button controls. Instead, use methods <samp class="codeph">addItem()</samp> and <samp class="codeph">removeItem()</samp> to
manipulate the <samp class="codeph">dataProvider</samp> property. A ButtonBar
or ToggleButtonBar control automatically adds or removes children
based on changes to the <samp class="codeph">dataProvider</samp> property. </p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fea_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fea_verapache"><!-- --></a>
<h3 class="topictitle3">Handling MX ButtonBar events</h3>
<div>
<p>The MX ButtonBar and MX ToggleButtonBar controls dispatch
an item<samp class="codeph">Click</samp> event when you select a button. The
event object passed to the event listener is of type <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/events/ItemClickEvent.html" target="_blank">ItemClickEvent</a>.
From within the event listener, you access properties of the event
object to determine the index of the selected button and other information.
The index of the first button is 0. For more information about the
event object, see the description of the ItemClickEvent class in
the <em>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/" target="_blank">ActionScript 3.0 Reference for the Adobe
Flash Platform</a>
</em>.</p>
<p>The ToggleButtonBar control in the following example defines
an event listener, named <samp class="codeph">clickHandler()</samp>, for the <samp class="codeph">itemClick</samp> event. </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\bar\BBarEvent.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.events.ItemClickEvent;
private var savedIndex:int = 99999;
private function clickHandler(event:ItemClickEvent):void {
if (event.index == savedIndex) {
myTA.text=""
}
else {
savedIndex = event.index;
myTA.text="Selected button index: " +
String(event.index) + "\n" +
"Selected button label: " +
event.label;
}
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:VGroup&gt;
&lt;mx:ToggleButtonBar
horizontalGap="5"
itemClick="clickHandler(event);"
toggleOnClick="true"
selectedIndex="-1"&gt;
&lt;mx:dataProvider&gt;
&lt;fx:String&gt;Flex&lt;/fx:String&gt;
&lt;fx:String&gt;Installer&lt;/fx:String&gt;
&lt;fx:String&gt;FlexJS&lt;/fx:String&gt;
&lt;fx:String&gt;TourDeFlex&lt;/fx:String&gt;
&lt;/mx:dataProvider&gt;
&lt;/mx:ToggleButtonBar&gt;
&lt;s:TextArea id="myTA" width="250" height="100"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt; </pre>
<p>In this example, the click handler displays the index and label
of the selected button in a TextArea control in response to an <samp class="codeph">itemClick</samp> event.
If you press the selected button a second time, the button is deselected,
and the sample click handler clears the text area. </p>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d9d_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d9d_verapache"><!-- --></a>
<h2 class="topictitle2">CheckBox control</h2>
<div>
<p>The CheckBox control is part of both the MX and Spark component
sets. While you can use the MX CheckBox control in your application,
it’s best to use the Spark CheckBox control instead.</p>
<p>The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/CheckBox.html" target="_blank">CheckBox</a> control
is a commonly used graphical control that can contain a check mark
or not. You can use CheckBox controls to gather a set of <samp class="codeph">true</samp> or <samp class="codeph">false</samp> values
that aren’t mutually exclusive. </p>
<p>You can add a text label to a CheckBox control and place it to
the left, right, top, or bottom. Flex clips the label of a CheckBox
control to fit the boundaries of the control. </p>
<p>
When
a user clicks a CheckBox control or its associated text, the CheckBox
control changes its state from checked to unchecked, or from unchecked
to checked. </p>
<p>A CheckBox control can have one of two disabled states, checked
or unchecked. By default, a disabled CheckBox control displays a
different background and check mark color than an enabled CheckBox
control. </p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d70_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d70_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a CheckBox control</h3>
<div>
<p>
You
use the <samp class="codeph">&lt;s:CheckBox&gt;</samp> tag to define a CheckBox
control in MXML, as the following example shows. Specify an <samp class="codeph">id</samp> value
if you intend to refer to a component elsewhere in your MXML, either
in another tag or in an ActionScript block: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\checkbox\CBSimple.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:VGroup&gt;
&lt;s:CheckBox width="100" label="Employee?"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt; </pre>
<p>You can also use the <samp class="codeph">selected</samp> property to generate
a checkbox that is checked by default:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\checkbox\CBSelected.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:VGroup&gt;
&lt;s:CheckBox width="100" label="Employee?" selected="true"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt; </pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7db6_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7db6_verapache"><!-- --></a>
<h3 class="topictitle3">CheckBox control user interaction</h3>
<div>
<p>
When
a CheckBox control is enabled and the user clicks it, the control
receives focus. It displays its checked or unchecked appearance,
depending on its initial state. The entire area of the CheckBox
control is the click area. If the CheckBox control’s text is larger
than its icon, the clickable regions are above and below the icon. </p>
<p>If the user moves the pointer outside the area of the CheckBox
control or its label while pressing the mouse button, the appearance
of the CheckBox control returns to its original state and the control
retains focus. The state of the CheckBox control does not change
until the user releases the mouse button over the control.</p>
<p>Users cannot interact with a CheckBox control when it is disabled.</p>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fa7_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fa7_verapache"><!-- --></a>
<h2 class="topictitle2">ColorPicker control</h2>
<div>
<p>The ColorPicker control is part of the MX component set.
There is no Spark equivalent. </p>
<p>
The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/ColorPicker.html" target="_blank">ColorPicker</a> control
lets users select a color from a drop-down swatch panel. It initially
appears as a preview sample with the selected color. When a user selects
the control, a color swatch panel appears. The panel includes a
sample of the selected color and a color swatch panel. By default,
the swatch panel displays the web-safe colors (216 colors, where
each of the three primary colors has a value that is a multiple
of 33, such as #CC0066).</p>
<p>For complete reference information, see <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/ColorPicker.html" target="_blank">ColorPicker </a> in
the <em>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/" target="_blank">ActionScript 3.0 Reference for the Adobe
Flash Platform</a>
</em>.</p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fa6_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fa6_verapache"><!-- --></a>
<h3 class="topictitle3">About the ColorPicker control</h3>
<div>
<p>When you open the ColorPicker control, the swatch panel
expands over other controls on the application, and normally opens
downwards. If the swatch panel would hit the lower boundary of the
application, but could fit above color picker button, it opens upward.</p>
<p>If you set the <samp class="codeph">showTextField</samp> property to <samp class="codeph">true</samp> (the
default), the panel includes a text box with a label for the selected
color. If you display a text box and set the <samp class="codeph">editable</samp> property
to <samp class="codeph">true</samp> (the default), the user can specify a color
by entering a hexadecimal value.</p>
<p>Flex populates the color swatch panel and the text box from a
data provider. By default, the control uses a data provider that
includes all the web-safe colors. If you use your own data provider
you can specify the following:</p>
<dl>
<dt class="dlterm">The colors to display</dt>
<dd>
<p>You <em>must</em> specify the colors if you use your own dataProvider.</p>
</dd>
<dt class="dlterm">Labels to display in the text box for the colors</dt>
<dd>
<p>If you do not specify text labels, Flex uses the hexadecimal
color values.</p>
</dd>
<dt class="dlterm">Additional information for each color</dt>
<dd>
<p>This information can include any information that is of use
to your application, such as IDs or descriptive comments.</p>
<p>The
following image shows an expanded ColorPicker control that uses
a custom data provider that includes color label values. It also
uses styles to set the sizes of the display elements:</p>
<div class="figborder">
<img src="images/ctr_ColorPicker-provider.png"/>
</div>
</dd>
</dl>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fa5_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fa5_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a ColorPicker control</h3>
<div>
<p>
You
use the <samp class="codeph">&lt;mx:ColorPicker&gt;</samp> tag to define a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/ColorPicker.html" target="_blank">ColorPicker</a> control
in MXML. Specify an <samp class="codeph">id</samp> value if you intend to refer
to a component elsewhere in your MXML, either in another tag or
in an ActionScript block. </p>
<p>The ColorPicker control uses a list-based data provider for the
colors. For more information on this type of data provider, see <a href="flx_about_dataproviders_ab.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fb8_verapache">Data
providers and collections</a>. If you omit the data provider,
the control uses a default data provider with the web-safe colors.
The data provider can be an array of colors or an array of objects.
The following example populates a ColorPicker with a simple array
of colors. </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\colorpicker\CPSimple.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
[Bindable]
public var simpleDP:Array = ['0x000000', '0xFF0000', '0xFF8800',
'0xFFFF00', '0x88FF00', '0x00FF00', '0x00FF88', '0x00FFFF',
'0x0088FF', '0x0000FF', '0x8800FF', '0xFF00FF', '0xFFFFFF'];
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:ColorPicker id="cp" dataProvider="{simpleDP}"/&gt;
&lt;/s:Application&gt;</pre>
<p>
You
typically use events to handle user interaction with a ColorPicker
control. The following example adds an event listener for a <samp class="codeph">change</samp> event
and an <samp class="codeph">open</samp> event to the previous example ColorPicker
control: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\colorpicker\CPEvents.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
//Import the event classes.
import mx.events.DropdownEvent;
import mx.events.ColorPickerEvent;
[Bindable]
public var simpleDP:Array = ['0x000000', '0xFF0000', '0xFF8800',
'0xFFFF00', '0x88FF00', '0x00FF00', '0x00FF88', '0x00FFFF',
'0x0088FF', '0x0000FF', '0x8800FF', '0xFF00FF', '0xFFFFFF'];
public function openEvt(event:DropdownEvent):void {
forChange.text="Opened";
}
public function changeEvt(event:ColorPickerEvent):void {
forChange.text="Selected Item: "
+ event.currentTarget.selectedItem + " Selected Index: "
+ event.currentTarget.selectedIndex;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:VBox&gt;
&lt;mx:TextArea id="forChange"
width="150"/&gt;
&lt;mx:ColorPicker id="cp"
dataProvider="{simpleDP}"
open="openEvt(event);"
change="changeEvt(event);"/&gt;
&lt;/mx:VBox&gt;
&lt;/s:Application&gt;</pre>
<p>The ColorPicker control dispatches <samp class="codeph">open</samp> event
when the swatch panel opens. It dispatches a <samp class="codeph">change</samp> event
when the value of the control changes due to user interaction. The <samp class="codeph">currentTarget</samp> property
of the object passed to the event listener contains a reference
to the ColorPicker control. In this example, the event listeners
use two properties of the ColorPicker control, <samp class="codeph">selectedItem</samp> and <samp class="codeph">selectedIndex</samp>.
Every <samp class="codeph">change</samp> event updates the TextArea control
with the selected item and the item’s index in the control, and
an <samp class="codeph">open</samp> event displays the word <em>Opened</em>. </p>
<p>If you populate the ColorPicker control from an array of color
values, the <samp class="codeph">target.selectedItem</samp> field contains
the hexadecimal color value. If you populate it from an array of
Objects, the <samp class="codeph">target.selectedItem</samp> field contains
a reference to the object that corresponds to the selected item. </p>
<p>The index of items in the ColorPicker control is zero-based,
which means that values are 0, 1, 2, ... , <em>n</em> - 1, where <em>n</em> is
the total number of items; therefore, the <samp class="codeph">target.selectedIndex</samp> value
is zero-based, and a value of 2 in the preceding example refers
to the data provider entry with color 0xFF8800. </p>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fa5_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d58_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fa5_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d58_verapache"><!-- --></a><h4 class="sectiontitle">Using
Objects to populate a ColorPicker control</h4>
<p>
You can populate a ColorPicker
control with an Array of Objects. By default, the ColorPicker uses
two fields in the Objects: one named <samp class="codeph">color</samp>, and
another named <samp class="codeph">label</samp>. The <samp class="codeph">label</samp> field
value determines the text in the swatch panel’s text field. If the
Objects do not have a <samp class="codeph">label</samp> field, the control
uses the <samp class="codeph">color</samp> field value in the text field. You
can use the ColorPicker control’s <samp class="codeph">colorField</samp> and <samp class="codeph">labelField</samp> properties
to specify different names for the color and label fields. The Objects
can have additional fields, such as a color description or an internal
color ID, that you can use in ActionScript.</p>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fa5_verapache__WS2db454920e96a9e51e63e3d11c0bf63b33-7fa3_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fa5_verapache__WS2db454920e96a9e51e63e3d11c0bf63b33-7fa3_verapache"><!-- --></a><h4 class="sectiontitle">Example:
ColorPicker control that uses Objects</h4>
<p>The following example
shows a ColorPicker that uses an Array of Objects with three fields: <samp class="codeph">color</samp>, <samp class="codeph">label</samp>,
and <samp class="codeph">descript</samp>:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\colorpicker\CPObjects.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.events.ColorPickerEvent;
import mx.events.DropdownEvent;
[Bindable]
public var complexDPArray:Array = [
{label:"Yellow", color:"0xFFFF00",
descript:"A bright, light color."},
{label:"Hot Pink", color:"0xFF66CC",
descript:"It's HOT!"},
{label:"Brick Red", color:"0x990000",
descript:"Goes well with warm colors."},
{label:"Navy Blue", color:"0x000066",
descript:"The conservative favorite."},
{label:"Forest Green", color:"0x006600",
descript:"Great outdoorsy look."},
{label:"Grey", color:"0x666666",
descript:"An old reliable."}]
public function openEvt(event:DropdownEvent):void {
descriptBox.text="";
}
public function changeEvt(event:ColorPickerEvent):void {
descriptBox.text=event.currentTarget.selectedItem.label
+ ": " + event.currentTarget.selectedItem.descript;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;fx:Style&gt;
.myStyle {
swatchWidth:25;
swatchHeight:25;
textFieldWidth:95;
}
&lt;/fx:Style&gt;
&lt;!-- Convert the Array to an ArrayCollection. Do this if
you might change the colors in the panel dynamically. --&gt;
&lt;fx:Declarations&gt;
&lt;mx:ArrayCollection id="complexDP" source="{complexDPArray}"/&gt;
&lt;/fx:Declarations&gt;
&lt;mx:VBox&gt;
&lt;mx:TextArea id="descriptBox"
width="150" height="50"/&gt;
&lt;mx:ColorPicker id="cp"
height="50" width="150"
dataProvider="{complexDP}"
change="changeEvt(event);"
open="openEvt(event);"
editable="false"/&gt;
&lt;/mx:VBox&gt;
&lt;/s:Application&gt;</pre>
<p>In this example, the <samp class="codeph">selectedItem</samp> property
contains a reference to the object defining the selected item. The
example uses <samp class="codeph">selectedItem.label</samp> to access the object’s <samp class="codeph">label</samp> property
(the color name), and <samp class="codeph">selectedItem.descript</samp> to
access the object’s <samp class="codeph">descript</samp> property (the color
description). Every <samp class="codeph">change</samp> event updates the <samp class="codeph">TextArea</samp> control
with the <samp class="codeph">label</samp> property of the selected item and
the item’s description. The <samp class="codeph">open</samp> event clears the
current text in the <samp class="codeph">TextArea</samp> control each time
the user opens up the ColorPicker to display the swatch panel.</p>
<p>This
example also uses several of the ColorPicker properties and styles
to specify the control’s behavior and appearance. The <samp class="codeph">editable</samp> property
prevents users from entering a value in the color label box (so
they can only select the colors from the dataProvider). The <samp class="codeph">swatchWidth</samp> and <samp class="codeph">swatchHeight</samp> styles
control the size of the color samples in the swatch panel. The <samp class="codeph">textFieldWidth</samp> style ensures
that the text field is long enough to accommodate the longest color name.</p>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fa5_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d57_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fa5_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d57_verapache"><!-- --></a><h4 class="sectiontitle">Using
custom field names</h4>
<p>In some cases, you might want to use
custom names for the color and label fields. For example, you would
use a custom name if the data comes from an external data source
with custom column names. The following code changes the previous
example to use custom color and label fields called cName and cVal.
It also shows how to use an <samp class="codeph">&lt;mx:dataProvider&gt;</samp> tag
to populate the data provider:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\colorpicker\CPCustomFieldNames.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.events.ColorPickerEvent;
import mx.events.DropdownEvent;
public function openEvt(event:DropdownEvent):void {
descriptBox.text="";
}
public function changeEvt(event:ColorPickerEvent):void {
descriptBox.text=event.currentTarget.selectedItem.cName
+ ": " + event.currentTarget.selectedItem.cDescript;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;fx:Style&gt;
.myStyle {
swatchWidth:25;
swatchHeight:25;
textFieldWidth:95;
}
&lt;/fx:Style&gt;
&lt;mx:VBox&gt;
&lt;mx:TextArea id="descriptBox"
width="150" height="50"/&gt;
&lt;mx:ColorPicker id="cp"
height="50" width="150"
labelField="cName"
colorField="cVal"
change="changeEvt(event)"
open="openEvt(event)"
swatchPanelStyleName="myStyle"
editable="false"&gt;
&lt;mx:dataProvider&gt;
&lt;mx:ArrayCollection&gt;
&lt;mx:source&gt;
&lt;fx:Object cName="Yellow" cVal="0xFFFF00"
cDescript="A bright, light color."/&gt;
&lt;fx:Object cName="Hot Pink" cVal="0xFF66CC"
cDescript="It's HOT!"/&gt;
&lt;fx:Object cName="Brick Red" cVal="0x990000"
cDescript="Goes well with warm colors."/&gt;
&lt;fx:Object cName="Navy Blue" cVal="0x000066"
cDescript="The conservative favorite."/&gt;
&lt;fx:Object cName="Forest Green" cVal="0x006600"
cDescript="Great outdoorsy look."/&gt;
&lt;fx:Object cName="Grey" cVal="0x666666"
cDescript="An old reliable."/&gt;
&lt;/mx:source&gt;
&lt;/mx:ArrayCollection&gt;
&lt;/mx:dataProvider&gt;
&lt;/mx:ColorPicker&gt;
&lt;/mx:VBox&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fa1_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fa1_verapache"><!-- --></a>
<h3 class="topictitle3">User interaction</h3>
<div>
<p>
A <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/ColorPicker.html" target="_blank">ColorPicker</a> control
can be editable or noneditable. In a noneditable ColorPicker control,
the user must select a color from among the swatch panel options. In
an editable ColorPicker control, a user can select swatch panel
items or enter a hexadecimal color value directly into the label
text field at the top of the swatch panel. Users can type numbers
and uppercase or lowercase letters in the ranges a-f and A-F in
the text box; it ignores all other non-numeric characters.</p>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fa1_verapache__WS2db454920e96a9e51e63e3d11c0bf63b33-7fa0_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fa1_verapache__WS2db454920e96a9e51e63e3d11c0bf63b33-7fa0_verapache"><!-- --></a><h4 class="sectiontitle">Mouse
interaction</h4>
<p>You can use the mouse to navigate and select
from the control:</p>
<ul>
<li>
<p>Click the collapsed control to display
or hide the swatch panel.</p>
</li>
<li>
<p>Click any swatch in the swatch panel to select it and close
the panel.</p>
</li>
<li>
<p>Click outside the panel area to close the panel without making
a selection.</p>
</li>
<li>
<p>Click in the text field to move the text entry cursor.</p>
</li>
</ul>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fa1_verapache__WS2db454920e96a9e51e63e3d11c0bf63b33-7f9f_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fa1_verapache__WS2db454920e96a9e51e63e3d11c0bf63b33-7f9f_verapache"><!-- --></a><h4 class="sectiontitle">Keyboard
interaction</h4>
<p>If the ColorPicker is editable and the swatch
panel has the focus, alphabetic keys in the range A-F and a-f and
numeric keys enter text in the color box. The Backspace and Delete
keys remove text in the color text box. You can also use the following
keystrokes to control the ColorPicker:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e2514">
<p>Key</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e2520">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e2514 ">
<p>Control+Down Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e2520 ">
<p>Opens the swatch panel and puts the focus
on the selected swatch.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e2514 ">
<p>Control+Up Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e2520 ">
<p>Closes the swatch panel, if open.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e2514 ">
<p>Home</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e2520 ">
<p>Moves the selection to the first color in
a row of the swatch panel. Has no effect if there is a single column.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e2514 ">
<p>End</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e2520 ">
<p>Moves the selection to the last color in
a row of the swatch panel. Has no effect if there is a single column.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e2514 ">
<p>Page Up</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e2520 ">
<p>Moves the selection to the top color in
a column of the swatch panel. Has no effect if there is a single
row.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e2514 ">
<p>Page Down</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e2520 ">
<p>Moves the selection to the bottom color
in a column of the swatch panel. Has no effect if there is a single row.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e2514 ">
<p>Escape</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e2520 ">
<p>Closes the swatch panel without changing
the color in the color picker.</p>
<p>Most Web browsers do not support
using this key.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e2514 ">
<p>Enter</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e2520 ">
<p>Selects the current color from the swatch
panel and closes the swatch panel; equivalent to clicking a color swatch.
If the focus is on the text field of an editable ColorPicker, selects
the color specified by the field text.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e2514 ">
<p>Arrows</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e2520 ">
<p>When the swatch panel is open, moves the
focus to the next color left, right, up, and down in the swatch grid.
On a single-row swatch panel, Up and Right Arrow keys are equivalent,
and Down and Left Arrow keys are equivalent.</p>
<p>On a multirow
swatch panel, the selection wraps to the beginning or end of the
next or previous line. On a single-row swatch panel, pressing the
key past the beginning or end of the row loops around on the row.</p>
<p>When
the swatch panel is closed, but has the focus, pressing the Up and
Down arrow keys has no effect. The Left and Right Arrow keys change
the color picker selection, moving through the colors as if the
panel were open.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="note"><span class="notetitle">Note:</span> When the swatch panel
is open, you cannot use the Tab and Shift+Tab keys to move the focus
to another object.</div>
</div>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d9b_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d9b_verapache"><!-- --></a>
<h2 class="topictitle2">DateChooser and DateField controls</h2>
<div>
<p>The DateChooser and DateField controls are part of the
MX component set. There is no Spark equivalent. </p>
<p>The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/DateChooser.html" target="_blank">DateChooser</a> and <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/DateField.html" target="_blank">DateField</a> controls
let users select dates from graphical calendars. The DateChooser
control user interface is the calendar. The DateField control has
a text field that uses a date chooser popup to select the date as
a result. The DateField properties are a superset of the DateChooser
properties.</p>
<p>For complete reference information, see <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/DateChooser.html" target="_blank">DateChooser</a> and <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/DateField.html" target="_blank">DateField</a> in
the <em>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/" target="_blank">ActionScript 3.0 Reference for the Adobe
Flash Platform</a>
</em>.</p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fd5_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fd5_verapache"><!-- --></a>
<h3 class="topictitle3">About the DateChooser control</h3>
<div>
<p>
The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/DateChooser.html" target="_blank">DateChooser</a> control
displays the name of a month, the year, and a grid of the days of
the month. It contains columns labeled for the days of the week.
This control is useful in applications where you want a continually
visible calendar. The user can select a single date from the grid.
The control contains forward and back arrow buttons to let you change
the month and year. You can disable the selection of certain dates,
and limit the display to a range of dates. </p>
<p>The following image shows a DateChooser control: </p>
<div class="figborder">
<img src="images/ctr_dateChooser.png"/>
</div>
<p>Changing the displayed month does not change the selected date.
Therefore, the currently selected date is not always visible. The
DateChooser control resizes as necessary to accommodate the width
of the weekday headings. Therefore, if you use day names, instead
of letters, as headings, the calendar is wide enough to show the
full day names.</p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fd4_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fd4_verapache"><!-- --></a>
<h3 class="topictitle3">About the DateField control</h3>
<div>
<p>
The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/DateField.html" target="_blank">DateField</a> control
is a text field that displays the date with a calendar icon on its
right side. When a user clicks anywhere inside the bounding box
of the control, a date chooser that is identical to the DateChooser
control pops up. If no date has been selected, the text field is
blank and the current month is displayed in the date chooser.</p>
<p>When the date chooser is open, users can click the month scroll
buttons to scroll through months and years, and select a date. When
the user selects a date, the date chooser closes and the text field
displays the selected date.</p>
<p>This control is useful in applications where you want a calendar
selection tool, but want to minimize the space that the date information
takes up.</p>
<p>The following example shows two images of a DateField control.
On the left is the DateField control with the date chooser closed;
the calendar icon appears on the right side of the text box. To
the right is a DateField control with the date chooser open: </p>
<div class="figborder">
<img src="images/ctr_datefields.png"/>
</div>
<p>You can use the DateField control anywhere you want a user to
select a date. For example, you can use a DateField control in a
hotel reservation system, with certain dates selectable and others
disabled. You can also use the DateField control in an application
that displays current events, such as performances or meetings,
when a user selects a date.</p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fd3_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fd3_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a DateChooser or DateField
control</h3>
<div>
<p>You define a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/DateChooser.html" target="_blank">DateChooser</a> control
in MXML by using the <samp class="codeph">&lt;mx:DateChooser&gt;</samp> tag.
You define a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/DateField.html" target="_blank">DateField</a> control
in MXML by using the <samp class="codeph">&lt;mx:DateField&gt;</samp> tag.
Specify an <samp class="codeph">id</samp> value if you intend to refer to a
component elsewhere in your MXML, either in another tag or an ActionScript
block.</p>
<p>
The
following example creates a DateChooser control; to create a DateField control,
simply change <samp class="codeph">&lt;mx:DateChooser&gt;</samp> to <samp class="codeph">&lt;mx:DateField&gt;</samp>.
The example uses the <samp class="codeph">change</samp> event of the DateChooser
control to display the selected date in several different formats. </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\date\DateChooserEvent.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.events.CalendarLayoutChangeEvent;
private function useDate(eventObj:CalendarLayoutChangeEvent):void {
// Make sure selectedDate is not null.
if (eventObj.currentTarget.selectedDate == null) {
return
}
//Access the Date object from the event object.
day.text=eventObj.currentTarget.selectedDate.getDay();
date.text=eventObj.currentTarget.selectedDate.getDate();
month.text=eventObj.currentTarget.selectedDate.getMonth() + 1;
year.text=eventObj.currentTarget.selectedDate.getFullYear();
wholeDate.text= (eventObj.currentTarget.selectedDate.getMonth() + 1) +
"/" + (eventObj.currentTarget.selectedDate.getDate() +
"/" + eventObj.currentTarget.selectedDate.getFullYear());
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:DateChooser id="date1" change="useDate(event)"/&gt;
&lt;s:Form x="200"&gt;
&lt;s:FormItem label="Day of week"&gt;
&lt;s:TextInput id="day" width="100"/&gt;
&lt;/s:FormItem&gt;
&lt;s:FormItem label="Day of month"&gt;
&lt;s:TextInput id="date" width="100"/&gt;
&lt;/s:FormItem&gt;
&lt;s:FormItem label="Month"&gt;
&lt;s:TextInput id="month" width="100"/&gt;
&lt;/s:FormItem&gt;
&lt;s:FormItem label="Year"&gt;
&lt;s:TextInput id="year" width="100"/&gt;
&lt;/s:FormItem&gt;
&lt;s:FormItem label="Date"&gt;
&lt;s:TextInput id="wholeDate" width="100"/&gt;
&lt;/s:FormItem&gt;
&lt;/s:Form&gt;
&lt;/s:Application&gt;</pre>
<p>Notice that the first line of the event listener determines if
the <samp class="codeph">selectedDate</samp> property is null. This check is
necessary because selecting the currently selected date while holding
down the Control key deselects it, sets the <samp class="codeph">selectedDate</samp> property
to null, then dispatches the <samp class="codeph">change</samp> event. </p>
<div class="note"><span class="notetitle">Note:</span> The code that determines the value of the <samp class="codeph">wholeDate</samp> field
adds 1 to the month number because the DateChooser control uses
a zero-based month system. In this system, January is month 0 and
December is month 11.</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fd2_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fd2_verapache"><!-- --></a>
<h3 class="topictitle3">Using the Date class</h3>
<div>
<p>
The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/DateChooser.html" target="_blank">DateChooser</a> and <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/DateField.html" target="_blank">DateField</a> controls
use the <samp class="codeph">selectedDate</samp> property to store the currently
selected date, as an object of type Date. You can create Date objects
to represent date and time values, or access the Date in the <samp class="codeph">selectedDate</samp> property. </p>
<p>The Date class has many methods that you can use to manipulate
a date. For more information on the Date class, see the <em>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/" target="_blank">ActionScript 3.0 Reference for the Adobe
Flash Platform</a>
</em>. </p>
<p>In MXML, you can create and configure a Date object by using
the <samp class="codeph">&lt;mx:Date&gt;</samp> tag. This tag exposes the setter
methods of the Date class as MXML properties so that you can initialize
a Date object. For example, the following code creates a DateChooser
control and sets the selected date to April 10, 2005. Notice that months
are indexed starting at 0:</p>
<pre class="codeblock"> &lt;mx:DateChooser id="date1"&gt;
  &lt;mx:selectedDate&gt;
  &lt;fx:Date month="3" date="10" fullYear="2005"/&gt;
  &lt;/mx:selectedDate&gt;
 &lt;/mx:DateChooser&gt; </pre>
<p>The following example uses inline ActionScript to set the initial
selected date for a DateField control:</p>
<pre class="codeblock"> &lt;mx:DateField id="date3" selectedDate="{new Date (2005, 3, 10)}"/&gt;</pre>
<p>You can also set the <samp class="codeph">selectedDate</samp> property in
a function, as the following example shows:</p>
<pre class="codeblock"> &lt;fx:Script&gt;
  &lt;![CDATA[
  private function initDC():void {
  date2.selectedDate=new Date (2005, 3, 10);
  }
  ]]&gt;
 &lt;/fx:Script&gt;
 
 &lt;mx:DateChooser id="date2" creationComplete="initDC();"/&gt;</pre>
<p>You can use property notation to access the ActionScript setter
and getter methods of the <samp class="codeph">selectedDate</samp> property
Date object. For example, the following line displays the four-digit
year of the selected date in a text box: </p>
<pre class="codeblock"> &lt;s:TextInput text="{date1.selectedDate.fullYear}"/&gt; </pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fd1_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fd1_verapache"><!-- --></a>
<h3 class="topictitle3">Specifying header, weekday, and
today’s day text styles</h3>
<div>
<p>The following date chooser properties let you specify text
styles for regions of the control:</p>
<ul>
<li>
<p>
<samp class="codeph">headerStyleName</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">weekDayStyleName</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">todayStyleName</samp>
</p>
</li>
</ul>
<p>These properties let you specify styles for the text in the header,
weekday list, and today’s date. You cannot use these properties
to set non-text styles such as <samp class="codeph">todayColor</samp>.</p>
<p>The following example defines a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/DateChooser.html" target="_blank">DateChooser</a> control
that has bold, blue header text in a 16-pixel Times New Roman font.
The day-of-week headers are in bold, italic, green, 15-pixel Courier
text, and today’s date is bold, orange, 12-pixel Times New Roman
text. Today’s date background color is gray, and is set directly
in the <samp class="codeph">&lt;mx:DateChooser&gt;</samp> tag.</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\date\DateChooserStyles.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Style&gt;
.myHeaderStyle{
color:#6666CC;
font-family:Times New Roman, Times, serif;
font-size:16px; font-weight:bold;}
.myTodayStyle{
color:#CC6633;
font-family:Times New Roman, Times, serif;
font-size:12px; font-weight:bold;}
.myDayStyle{
color:#006600;
font-family:Courier New, Courier, mono;
font-size:15px; font-style:italic; font-weight:bold;}
&lt;/fx:Style&gt;
&lt;mx:DateChooser
headerStyleName="myHeaderStyle"
todayStyleName="myTodayStyle"
todayColor="#CCCCCC"
weekDayStyleName="myDayStyle"/&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fd0_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fd0_verapache"><!-- --></a>
<h3 class="topictitle3">Specifying selectable dates</h3>
<div>
<p>The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/DateChooser.html" target="_blank">DateChooser</a> control
has the following properties that let you specify which dates a
user can select:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e3056">
<p>Property</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e3062">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3056 ">
<div class="p">
<pre class="codeblock">disabledDays</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3062 ">
<p>An array of days of the week that the user
cannot select. Often used to disable weekend days.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3056 ">
<div class="p">
<pre class="codeblock">disabledRange</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3062 ">
<p>An array of dates that the user cannot select.
The array can contain individual Date objects, objects specifying date
ranges, or both.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3056 ">
<div class="p">
<pre class="codeblock">selectableRange</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3062 ">
<p>A single range of dates that the user can
select. The user can navigate only among the months that include
this range; in these months any dates outside the range are disabled.
Use the <samp class="codeph">disabledRange</samp> property to disable dates
within the selectable range.</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>The following example shows a DateChooser control that has the
following characteristics:</p>
<ul>
<li>
<p>The <samp class="codeph">selectableRange</samp> property limits
users to selecting dates in the range January 1 - March 15, 2006.
Users can only navigate among the months of January through March
2006. </p>
</li>
<li>
<p>The <samp class="codeph">disabledRanges</samp> property prevents users
from selecting January 11 or any day in the range January 23 - February
10. </p>
</li>
<li>
<p>The <samp class="codeph">disabledDays</samp> property prevents users
from selecting Saturdays or Sundays.</p>
</li>
</ul>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\date\DateChooserSelectable.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;mx:DateChooser
selectableRange="{{rangeStart: new Date(2006,0,1),
rangeEnd: new Date(2006,2,15)}}"
disabledRanges="{[new Date(2006,0,11),
{rangeStart: new Date(2006,0,23), rangeEnd: new Date(2006,1,10)}]}"
disabledDays="{[0,6]}"/&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fcf_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fcf_verapache"><!-- --></a>
<h3 class="topictitle3">Setting DateChooser and DateField
properties in ActionScript</h3>
<div>
<p>
Properties
of the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/DateChooser.html" target="_blank">DateChooser</a> and <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/DateField.html" target="_blank">DateField</a> controls
take values that are scalars, Arrays, and Date objects. While you
can set most of these properties in MXML, it can be easier to set
some in ActionScript. </p>
<p>For example, the following code example uses an array to set
the <samp class="codeph">disabledDays</samp> property. Sunday (0) and Saturday
(6) are disabled, which means that they cannot be selected in the
calendar. This example sets the <samp class="codeph">disabledDays</samp> property
in two different ways, by using tags and by using tag attributes:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\date\DateChooserDisabledOption.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;!-- Use tags.--&gt;
&lt;mx:DateField&gt;
&lt;mx:disabledDays&gt;
&lt;fx:Number&gt;0&lt;/fx:Number&gt;
&lt;fx:Number&gt;6&lt;/fx:Number&gt;
&lt;/mx:disabledDays&gt;
&lt;/mx:DateField&gt;
&lt;!-- Use tag attributes.--&gt;
&lt;mx:DateField disabledDays="[0,6]"/&gt;
&lt;/s:Application&gt;</pre>
<p>The following example sets the <samp class="codeph">dayNames</samp>, <samp class="codeph">firstDayOfWeek</samp>, <samp class="codeph">headerColor</samp>,
and <samp class="codeph">selectableRange</samp> properties of a DateChooser
control by using an <samp class="codeph">initialize</samp> event: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\date\DateChooserInitializeEvent.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.events.DateChooserEvent;
private function dateChooser_init():void {
myDC.dayNames=['Sun', 'Mon', 'Tue',
'Wed', 'Th', 'Fri', 'Sat'];
myDC.firstDayOfWeek = 3;
myDC.setStyle("headerColor", 0xff0000);
myDC.selectableRange = {rangeStart: new Date(2009,0,1),
rangeEnd: new Date(2012,0,10)};
}
private function onScroll():void {
myDC.setStyle("fontStyle", "italic");
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:DateChooser id="myDC"
width="200"
creationComplete="dateChooser_init();"
scroll="onScroll();"/&gt;
&lt;/s:Application&gt;</pre>
<p>To set the <samp class="codeph">selectableRange</samp> property, the code
creates two Date objects that represent the first date and last
date of the range. Users can only select dates within the specified
range. This example also changes the <samp class="codeph">fontStyle</samp> of
the DateChooser control to <samp class="codeph">italics</samp> after the first
time the user scrolls it. </p>
<p>You can select multiple dates in a DateChooser control by using
the <samp class="codeph">selectedRanges</samp> property. This property contains
an Array of objects. Each object in the Array contains two dates:
a start date and an end date. By setting the dates within each object
to the same date, you can select any number of individual dates
in the DateChooser. </p>
<p>The following example uses an XML object to define the date for
the DateChooser control. It then iterates over the XML object and
creates an object for each date. These objects are then used to
determine what dates to select in the DateChooser:</p>
<pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- controls\date\ProgrammaticDateChooserSelector.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"
creationComplete="init()"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
private function init():void {
dc1.displayedMonth = 1;
dc1.displayedYear = 2008;
}
public function displayDates():void {
var dateRanges:Array = [];
for (var i:int=0; i&lt;shows.show.length(); i++) {
var cDate:Date =
new Date(shows.show[i].showDate.toString());
var cDateObject:Object =
{rangeStart:cDate, rangeEnd:cDate};
dateRanges.push(cDateObject);
}
dc1.selectedRanges = dateRanges;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;!-- Define the data for the DateChooser --&gt;
&lt;fx:Declarations&gt;
&lt;fx:XML id="shows" format="e4x"&gt;
&lt;data&gt;
&lt;show&gt;
&lt;showID&gt;1&lt;/showID&gt;
&lt;showDate&gt;02/28/2008&lt;/showDate&gt;
&lt;showTime&gt;10:45am/11:15am&lt;/showTime&gt;
&lt;/show&gt;
&lt;show&gt;
&lt;showID&gt;2&lt;/showID&gt;
&lt;showDate&gt;02/23/2008&lt;/showDate&gt;
&lt;showTime&gt;7:00pm&lt;/showTime&gt;
&lt;/show&gt;
&lt;/data&gt;
&lt;/fx:XML&gt;
&lt;/fx:Declarations&gt;
&lt;mx:DateChooser id="dc1"
showToday="false"
creationComplete="displayDates();"/&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fce_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fce_verapache"><!-- --></a>
<h3 class="topictitle3">Formatting dates with the DateField
control</h3>
<div>
<p>You can use the <samp class="codeph">formatString</samp> property
of the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/DateField.html" target="_blank">DateField</a> control
to format the string in the control’s text field. The <samp class="codeph">formatString</samp> property
can contain any combination of "MM", "DD", "YY", “YYYY”, delimiter,
and punctuation characters. The default value is "MM/DD/YYYY".</p>
<p>In the following example, you select a value for the <samp class="codeph">formatString</samp> property from
the drop-down list:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\date\DateFieldFormat.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;mx:HBox&gt;
&lt;mx:ComboBox id="cb1"&gt;
&lt;mx:ArrayCollection&gt;
&lt;fx:String&gt;MM/DD/YY&lt;/fx:String&gt;
&lt;fx:String&gt;MM/DD/YYYY&lt;/fx:String&gt;
&lt;fx:String&gt;DD/MM/YY&lt;/fx:String&gt;
&lt;fx:String&gt;DD/MM/YYYY&lt;/fx:String&gt;
&lt;fx:String&gt;DD MM, YYYY&lt;/fx:String&gt;
&lt;/mx:ArrayCollection&gt;
&lt;/mx:ComboBox&gt;
&lt;mx:DateField id="date2"
editable="true"
width="100"
formatString="{cb1.selectedItem}"/&gt;
&lt;/mx:HBox&gt;
&lt;/s:Application&gt;</pre>
<p>The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/DateField.html" target="_blank">DateField</a> control
also lets you specify a formatter function. A formatter function
converts the date to a string in your preferred format for display
in the control’s text field. The DateField <samp class="codeph">labelFunction</samp> property
and the Spark DateTimeFormatter class help you format dates.</p>
<p>By default, the date in the DateField control text field is formatted
in the form "MM/DD/YYYY". You use the <samp class="codeph">labelFunction</samp> property
of the DateField control to specify a function to format the date
displayed in the text field and return a String containing the date.
The function has the following signature:</p>
<pre class="codeblock"> public function formatDate(<em>currentDate</em>:Date):String {
  ...
  return dateString;
 }</pre>
<p>
You
can choose a different name for the function, but it must take a
single argument of type Date and return the date as a String for
display in the text field. The following example defines the function<samp class="codeph"> formatDate()</samp> to
display the date in the form dd-mm-yyyy, such as 03-12-2011. This
function uses a Spark DateTimeFormatter object to do the formatting: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\date\DateChooserFormatter.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
private function formatDateTime(date:Date):String {
return dtf.format(date);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;fx:Declarations&gt;
&lt;s:DateTimeFormatter id="dtf" dateTimePattern="MM-dd-yyyy"/&gt;
&lt;/fx:Declarations&gt;
&lt;mx:DateField id="df" labelFunction="formatDateTime" parseFunction="{null}"/&gt;
&lt;/s:Application&gt;</pre>
<p>The <samp class="codeph">parseFunction</samp> property specifies a function
that parses the date entered as text in the text field of the DateField
control and returns a Date object to the control. If you do not
allow the user to enter a date in the text field, set the <samp class="codeph">parseFunction</samp> property
to <samp class="codeph">null</samp> when you set the <samp class="codeph">labelFunction</samp> property.</p>
<p>If you want to let the user enter a date in the control’s text
field, specify a function to the <samp class="codeph">parseFunction</samp> property
that converts the text string to a Date object for use by the DateField
control. If you set the <samp class="codeph">parseFunction</samp> property,
it should typically perform the reverse of the function specified
to the <samp class="codeph">labelFunction</samp> property.</p>
<p>The function specified to the <samp class="codeph">parseFunction</samp> property
has the following signature:</p>
<pre class="codeblock"> public function parseDate(<em>valueString</em>:String, <em>inputFormat</em>:String):Date {
  ...
  return newDate
 }</pre>
<p>Where the <samp class="codeph">valueString</samp> argument contains the
text string entered by the user in the text field, and the <samp class="codeph">inputFormat</samp> argument
contains the format of the string. For example, if you only allow
the user to enter a text string by using two characters for month,
day, and year, then pass "MM/DD/YY" to the <samp class="codeph">inputFormat</samp> argument. </p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7db3_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7db3_verapache"><!-- --></a>
<h3 class="topictitle3">User interaction</h3>
<div>
<p>
The
date chooser includes arrow buttons that let users move between
months. Users can select a date with the mouse by clicking the desired
date. </p>
<p>Clicking a forward month arrow advances a month; clicking the
back arrow displays the previous month. Clicking forward a month
on December, or back on January, moves to the next (or previous)
year. Clicking a date selects it. By default, the selected date
is indicated by a green background around the date and the current
day is indicated by a black background with the date in white. Clicking the
currently selected date deselects it. </p>
<p>The following keystrokes let users navigate <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/DateChooser.html" target="_blank">DateChooser</a> and <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/DateField.html" target="_blank">DateField </a>controls:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e3427">
<p>Key</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e3433">
<p>Use</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3427 ">
<p>Left Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3433 ">
<p>Moves the selected date to the previous
enabled day in the month. Does not move to the previous month. Use
the Shift key plus the Left Arrow key to access disabled days.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3427 ">
<p>Right Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3433 ">
<p>Moves the selected date to the next enabled
day in the month. Does not move to the next month. Use the Shift
key plus the Right Arrow key to access disabled days.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3427 ">
<p>Up Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3433 ">
<p>Moves the selected date up the current day
of week column to the previous enabled day. Does not move to the
previous month. Use the Shift key plus the Up Arrow key to access
disabled days.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3427 ">
<p>Down Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3433 ">
<p>Moves the selected date down the current
day of week column to next enabled day. Does not move to the next
month. Use the Shift key plus the Down Arrow key to access disabled
days.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3427 ">
<p>Page Up</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3433 ">
<p>Displays the calendar for the previous month.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3427 ">
<p>Page Down</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3433 ">
<p>Displays the calendar for the next month.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3427 ">
<p>Home</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3433 ">
<p>Moves the selection to the first enabled
day of the month.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3427 ">
<p>End</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3433 ">
<p>Moves the selection to the last enabled
day of the month.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3427 ">
<p>+</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3433 ">
<p>Move to the next year.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3427 ">
<p>-</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3433 ">
<p>Move to the previous year.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3427 ">
<p>Control+Down Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3433 ">
<p>DateField only: open the DateChooser control.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3427 ">
<p>Control+Up Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3433 ">
<p>DateField only: close the DateChooser control.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3427 ">
<p>Escape</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3433 ">
<p>DateField only: cancel operation. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3427 ">
<p>Enter</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3433 ">
<p>DateField only: selects the date and closes
the DateChooser control. </p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="note"><span class="notetitle">Note:</span> The user must select the control before using
navigation keystrokes. In a DateField control, all listed keystrokes
work only when the date chooser is displayed.</div>
</div>
</div>
</div>
<div class="nested1" id="WSc5cd04c102ae3e97-33ad5caa12c719dc7c8-8000_verapache"><a name="WSc5cd04c102ae3e97-33ad5caa12c719dc7c8-8000_verapache"><!-- --></a>
<h2 class="topictitle2">Image control</h2>
<div>
<p>
Flex
supports several image formats, including GIF, JPEG, and PNG. You
can import these images into your applications by using the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/Image.html" target="_blank">Spark Image</a> control
or <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/primitives/BitmapImage.html" target="_blank">BitmapImage</a>.
To load SWF files, you use the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/SWFLoader.html" target="_blank">SWFLoader</a> control.</p>
<p>The Image control is part of both MX and Spark component sets.
While you can use the MX Image control in your application, it’s
best to use the Spark Image control instead.</p>
<p>Flex provides the following image controls:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e3716">
<p>Image control</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e3722">
<p>Use</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3716 ">
<p>BimapImage </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3722 ">
<p>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/primitives/BitmapImage.html" target="_blank">BitmapImage</a> is
a light-weight image control that can load both local and remote
assets. You typically use the BitmapImage when you don’t require
a broken image icon or a preloader.</p>
<p>The BitmapImage also supports
runtime loading of images. However, when you load images at runtime, you
should be aware of the security restrictions of Flash Player or
AIR. For more information, see <a href="flx_security2_se.html#WS2db454920e96a9e51e63e3d11c0bf69084-7f9b_verapache">Security</a>.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3716 ">
<p>Spark Image</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3722 ">
<p>The Spark Image is a skinnable component
that leverages a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/primitives/BitmapImage.html" target="_blank">BitmapImage</a> class
as its main skin part. </p>
<p>The Spark Image control provides a
preloader as well as a broken image icon to indicate an invalid
image state. The image loader and the broken-image icon are both
customizable. For example, you can provide a broken image icon representing
an invalid URL, or provide a progress bar as the image loads. The
Spark Image control also provides customizable skinning for borders,
frames, and loading states. For more information, see <a href="flx_controls_ctr.html#WSc5cd04c102ae3e97-33ad5caa12c719dc7c8-7ffa_verapache">Skinning
the Spark Image control</a>.</p>
<p>The Spark Image control lets
you load local and trusted assets, as well as remote and untrusted
assets. Security restrictions are applicable in case of untrusted
assets. For more information, see <a href="flx_controls_ctr.html#WSc5cd04c102ae3e97-33ad5caa12c719dc7c8-7ffd_verapache">Loading
images using a customizable load interface</a>.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3716 ">
<p>SWFLoader</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e3722 ">
<p>Flex also includes the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/SWFLoader.html" target="_blank">SWFLoader</a> control
for loading applications built in Flex. You typically use the Image control
for loading static graphic files, and use the SWFLoader control
for loading SWF files and applications built in Flex. The Image
control is also designed for use in custom item renderers and item
editors. </p>
<p>For more information on the SWFLoader control, see <a href="flx_controls_ctr.html#WS2db454920e96a9e51e63e3d11c0bf69084-7f9c_verapache">SWFLoader
control</a>. </p>
</td>
</tr>
</tbody>
</table>
</div>
<p>The following example shows a BitmapImage embedded at compile
time and a BitmapImage loaded at runtime:</p>
<div class="p">
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\image\ImageBitmapImageExample.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"
width="700"&gt;
&lt;s:Panel title="BitmapImage Examples" width="600"&gt;
&lt;s:layout&gt;
&lt;s:HorizontalLayout horizontalAlign="center"/&gt;
&lt;/s:layout&gt;
&lt;s:BorderContainer width="50%" height="100%"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout
verticalAlign="middle"
horizontalAlign="center"/&gt;
&lt;/s:layout&gt;
&lt;s:Label text="BitmapImage embedded at compile time"/&gt;
&lt;s:BitmapImage id="embimg" source="@Embed(source='fblogo.jpg')"
height="50" width="50"/&gt;
&lt;/s:BorderContainer&gt;
&lt;s:BorderContainer width="50%" height="100%"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout
verticalAlign="middle"
horizontalAlign="center"/&gt;
&lt;/s:layout&gt;
&lt;s:Label text="BitmapImage loaded at runtime"/&gt;
&lt;s:BitmapImage id="runtimeimg" source="../assets/flexlogo.jpg"
height="50" width="50"/&gt;
&lt;/s:BorderContainer&gt;
&lt;/s:Panel&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
<div class="nested2" id="WSc5cd04c102ae3e97-33ad5caa12c719dc7c8-7fff_verapache"><a name="WSc5cd04c102ae3e97-33ad5caa12c719dc7c8-7fff_verapache"><!-- --></a>
<h3 class="topictitle3">About loading images</h3>
<div>
<p>Flex supports loading GIF, JPEG, and PNG files at runtime,
and also embedding GIF, JPEG, and PNG files at compile time. The
method you choose depends on the file types of your images and your
application parameters.</p>
<p>Embedded images load immediately, because they are already part
of the Flex SWF file. However, they add to the size of your application
and slow down the application initialization process. Embedded images
also require you to recompile your applications whenever your image
files change. For an overview of resource embedding, see <a href="flx_embed_em.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fce_verapache">Embedding
assets</a>. </p>
<p>The alternative to embedding a resource is to load the resource
at runtime. You can load a resource from the local file system in
which the SWF file runs. You can also access a remote resource,
typically though an HTTP request over a network. These images are
independent of your application built with Flex, so you can change
them without causing a recompile operation as long as the names
of the modified images remain the same. The referenced images add
no additional overhead to an application’s initial loading time.
However, you can sometimes experience a delay when you use the images
and load them into Adobe Flash Player or AIR. </p>
<p>A SWF file can access one type of external resource only, either
local or over a network; it cannot access both types. You determine
the type of access allowed by the SWF file by using the <samp class="codeph">use-network</samp> flag
when you compile your application. When <samp class="codeph">use-network</samp> flag
is set to <samp class="codeph">false</samp>, you can access resources in the
local file system, but not over the network. The default value is <samp class="codeph">true</samp>,
which allows you to access resources over the network, but not in
the local file system. </p>
<p>For more information on the <samp class="codeph">use-network</samp> flag,
see <a href="flx_compilers_cpl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ffd_verapache">Flex
compilers</a>.</p>
<p>When you load images at runtime, you should be aware of the security
restrictions of Flash Player or AIR. For example, you can reference
an image by using a URL, but the default security settings only
permit applications built in Flex to access resources stored on
the same domain as your application. To access images on other servers,
ensure that the domain that you are loading from uses a crossdomain.xml
file. </p>
<p>For more information on application security, see <a href="flx_security2_se.html#WS2db454920e96a9e51e63e3d11c0bf69084-7f9b_verapache">Security</a>.</p>
</div>
</div>
<div class="nested2" id="WSc5cd04c102ae3e97-33ad5caa12c719dc7c8-7ffe_verapache"><a name="WSc5cd04c102ae3e97-33ad5caa12c719dc7c8-7ffe_verapache"><!-- --></a>
<h3 class="topictitle3">Loading and embedding images with
Spark Image and BitmapImage controls</h3>
<div>
<p>The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/Image.html" target="_blank">Spark Image</a> control
and <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/primitives/BitmapImage.html" target="_blank">BitmapImage</a> support
the following actions when you load an image:</p>
<div class="section"><h4 class="sectiontitle">Specifying the image path</h4>
<p>The value of
the <samp class="codeph">source</samp> property of a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/Image.html" target="_blank">Spark Image</a> control
or <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/primitives/BitmapImage.html" target="_blank">BitmapImage</a> specifies
a relative or absolute path, or URL to the imported image file.
If the value is relative, it is relative to the directory that contains
the file that uses the tag. </p>
<p>
The <samp class="codeph">source</samp> property
has the following forms: </p>
<ol>
<li>
<p>
<samp class="codeph">source="@Embed(source='relativeOrAbsolutePath')"</samp>
</p>
<p>The
referenced image is packaged within the generated SWF file at compile time
when Flex creates the SWF file for your application. You can embed
GIF, JPEG, and PNG files. When embedding an image, the value of
the <samp class="codeph">source</samp> property must be a relative or absolute
path to a file on the Flex developer’s local file system; it cannot
be a URL. </p>
<p>The following example embeds a JPEG image into
an application that is built in Flex: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\image\ImageSimpleEmbed.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:Image id="loader1" source="@Embed(source='logo.jpg')"/&gt;
&lt;/s:Application&gt;</pre>
<p>In this example, the size of
the image is the default size of the image file.</p>
</li>
<li>
<p>
<samp class="codeph">source="relativeOrAbsolutePathOrURL"</samp>
</p>
<p>Flex
loads the referenced image file at runtime, typically from a location
that is deployed on a web server; the image is not packaged as part
of the generated SWF file. You can only reference GIF, JPEG, and
PNG files. </p>
<p>The following example accesses a JPEG image at
runtime: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\image\ImageSimple.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:Image id="loader1" source="assets/flexlogo.jpg"/&gt;
&lt;/s:Application&gt;</pre>
<p>Because you did not use <samp class="codeph">@Embed</samp> in
the <samp class="codeph">source</samp> property, Flex loads the image at runtime.
In this case, the location is the same directory as the page that
embedded the SWF file.</p>
<p>When the <samp class="codeph">use-network</samp> flag
is set to <samp class="codeph">false</samp>, you can access resources in the local
file system, but not over the network. The default value is <samp class="codeph">true</samp>,
which allows you to access resources over the network, but not in
the local file system.</p>
</li>
</ol>
<p>
In many applications, you create a directory
to hold your application images. Commonly, that directory is a subdirectory
of your main application directory. The <samp class="codeph">source</samp> property
supports relative paths to images, which let you specify the location
of an image file relative to your application directory. </p>
<p>The
following example stores all images in an assets subdirectory of
the application directory:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\image\ImageSimpleAssetsDir.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:Image id="loader1" source="@Embed(source='assets/logo.jpg')"/&gt;
&lt;/s:Application&gt;</pre>
<p>The following example uses
a relative path to reference an image in an assets directory at
the same level as the application’s root directory:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\image\ImageSimpleAssetsDirTop.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:Image id="loader1" source="@Embed(source='../assets/logo.jpg')"/&gt;
&lt;/s:Application&gt;</pre>
<p>You can also reference an image
by using a URL, but the default security settings only permit applications
to access resources stored on the same domain as your application.
To access images on other servers, make sure that the domain that you
are loading the image from uses a crossdomain.xml file that allows
cross-domain access. </p>
<p>Cross-domain image loading is supported
with restrictions. You can load local and trusted assets, as well
as remote and untrusted assets. When you use untrusted assets, security
restrictions are applicable. When a cross-domain image is loaded
from an untrusted source, the security policy does not allow access
to the image content. Then, the <samp class="codeph">trustedSource</samp> property
of the BimapImage and Spark Image is set to <samp class="codeph">false</samp>,
and the following image properties do not function: </p>
<ul>
<li>
<p>
<samp class="codeph">BitmapFillMode.REPEAT</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">scaleGrid</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">smooth</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">smoothingQuality</samp>
</p>
</li>
</ul>
<p>Any advanced
operations on the image data, such as, high-quality scaling or tiling,
are not supported.</p>
<p>For more information, see <a href="flx_security2_se.html#WS2db454920e96a9e51e63e3d11c0bf69084-7f9b_verapache">Security</a>.</p>
<p>The
following example shows how to reference an image by using a URL: </p>
<pre class="noswf">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\image\ImageSimpleAssetsURL.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:Image id="image1"
source="http://localhost:8100/flex/assets/logo.jpg"/&gt;
&lt;/s:Application&gt;</pre>
<div class="note"><span class="notetitle">Note:</span> You can use
relative URLs for images hosted on the same web server as the application,
but load these images over the Internet rather than access them
locally.</div>
</div>
<div class="section"><h4 class="sectiontitle">Using an image multiple times</h4>
<p>You can
use the same image multiple times in your application by using the normal
image import syntax each time. Flex only loads the image once, and
then references the loaded image as many times as necessary.</p>
</div>
</div>
</div>
<div class="nested2" id="WSc5cd04c102ae3e97-33ad5caa12c719dc7c8-7ffb_verapache"><a name="WSc5cd04c102ae3e97-33ad5caa12c719dc7c8-7ffb_verapache"><!-- --></a>
<h3 class="topictitle3">Sizing and scaling an image</h3>
<div>
<p>You can size and scale images using both the Spark Image
and BimapImage controls.</p>
<div class="section"><h4 class="sectiontitle">Sizing an image</h4>
<p>
Flex sets the height and width of
an imported image to the height and width settings in the image
file. By default, Flex does not resize the image. </p>
<p>To set
an explicit height or width for an imported image, set its <samp class="codeph">height</samp> and <samp class="codeph">width</samp> properties
of the image control. Setting the <samp class="codeph">height</samp> or <samp class="codeph">width</samp> property prevents
the parent from resizing it. The <samp class="codeph">scaleContent</samp> property
has a default value of <samp class="codeph">true</samp>; therefore, Flex scales
the image as it resizes it to fit the specified height and width.
The aspect ratio is maintained by default for a Spark Image, so the
image may not completely fill the designated space. Set the <samp class="codeph">scaleContent</samp> property
to <samp class="codeph">false</samp> to disable scaling. </p>
<p>When you resize
a BitmapImage, the aspect ratio is not maintained, by default. To ensure
that you maintain the aspect ratio, change the value of the <samp class="codeph">scaleMode</samp> property
from <samp class="codeph">stretch</samp> to <samp class="codeph">letterbox</samp> or <samp class="codeph">zoom</samp>.
For more information about image aspect ratios, see below.</p>
<p>One
common use for resizing an image is to create image thumbnails.
In the following example, the image has an original height and width
of 100 by 100 pixels. By specifying a height and width of 20 by
20 pixels, you create a thumbnail of the image.</p>
<div class="p">
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\image\ImageSimpleThumbnail.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:BitmapImage id="image1"
source="@Embed(source='logo.jpg')"
width="20" height="20"
smooth="true" smoothingQuality="high"/&gt;
&lt;s:BitmapImage id="image2"
source="@Embed(source='logo.jpg')"/&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>When you downscale a BimapImage,
the default quality for scaled bitmaps, <samp class="codeph">BitmapSmoothingQuality.DEFAULT</samp>,
is used.</p>
<p>If you want to preserve the aspect ratio when creating
image thumbnails, and achieve the best quality result when downscaling
a BitmapImage, set the <samp class="codeph">smoothingQuality</samp> property
to <samp class="codeph">BitmapSmoothingQuality.HIGH</samp>. The <samp class="codeph">smoothingQuality</samp> property
is applicable only when you set the <samp class="codeph">smooth</samp> property
of the BitmaImage to <samp class="codeph">true</samp>. When you do so, a multi-bit-rate
step algorithm is applied to the image, resulting in a much higher
quality downscale than the default. This option is useful in creating
high-quality image thumbnails.</p>
<p>To let Flex resize the image
as part of laying out your application, set the <samp class="codeph">height</samp> and <samp class="codeph">width</samp> properties
to a percentage value. Flex attempts to resize components with percentage
values for these properties to the specified percentage of their
parent container. You can also use the <samp class="codeph">maxHeight</samp> and <samp class="codeph">maxWidth</samp> and <samp class="codeph">minHeight</samp> and <samp class="codeph">minWidth</samp> properties
to limit resizing. For more information on resizing, see <a href="flx_containers_intro_cn.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ffa_verapache">Introduction
to containers</a>.</p>
</div>
<div class="section"><h4 class="sectiontitle">Maintaining aspect ratio when sizing </h4>
<p>
The aspect ratio of an
image is the ratio of its width to its height. For example, a standard
NTSC television set uses an aspect ratio of 4:3, and an HDTV set
uses an aspect ratio of 16:9. A computer monitor with a resolution
of 640 by 480 pixels also has an aspect ratio of 4:3. A square has
an aspect ratio of 1:1.</p>
<p>All images have an inherent aspect
ratio. When you use the <samp class="codeph">height</samp> and <samp class="codeph">width</samp> properties
of the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/Image.html" target="_blank">Image</a> control
to resize an image, Flex preserves the aspect ratio of the image,
by default, so that it does not appear distorted. </p>
<p>By preserving
the aspect ratio of the image, Flex might not draw the image to
fill the entire height and width specified for the <samp class="codeph">&lt;s:Image&gt;</samp> tag.
For example, if your original image is a square 100 by 100 pixels,
which means it has an aspect ratio of 1:1, and you use the following
statement to load the image: </p>
<pre class="codeblock"> &lt;s:Image source="myImage.jpg" height="200" width="200"/&gt;</pre>
<p>The
image increases to four times its original size and fills the entire
200 x 200 pixel area.</p>
<p>The following example sets the height
and width of the same image to 150 by 200 pixels, an aspect ratio
of 3:4: </p>
<pre class="codeblock"> &lt;s:Image source="myImage.jpg" height="150" width="200"/&gt;</pre>
<p>In
this example, you do not specify a square area for the resized image.
Flex maintains the aspect ratio of a Spark Image by default because
the <samp class="codeph">scaleMode</samp> property is set to <samp class="codeph">letterbox</samp>.
Therefore, Flex sizes the image to 150 by 150 pixels, the largest
possible image that maintains the aspect ratio and conforms to the
size constraints. The other 50 by 150 pixels remain empty. However,
the <samp class="codeph">&lt;s:Image&gt;</samp> tag reserves the empty pixels
and makes them unavailable to other controls and layout elements.</p>
<p>To
ensure that you maintain the aspect ratio when you resize a BitmapImage, change
the value of the <samp class="codeph">scaleMode</samp> property from <samp class="codeph">stretch</samp> to <samp class="codeph">letterbox</samp> or <samp class="codeph">zoom</samp>.</p>
<p>When
you resize an image, you can apply the required alignment properties.
The Spark Image and BitmapImage both have <samp class="codeph">horizontalAlign</samp> and <samp class="codeph">verticalAlign</samp> properties
that you can specify, as required. </p>
<p>By default, the <samp class="codeph">horizontalAlign</samp> and <samp class="codeph">verticalAlign</samp> properties
are set to <samp class="codeph">center</samp>. For example, when you resize
an image that has an original height and width of 1024 by 768 to
a height and width of 100 by 100, there is extra space at the top
and bottom of the image. You can set the the <samp class="codeph">horizontalAlign</samp> and <samp class="codeph">verticalAlign</samp> properties
as required to overcome the extra space.</p>
<p>
You
can also use a Resize effect to change the width and height of an
image in response to a trigger. As part of configuring the Resize
effect, you specify a new height and width for the image. Flex maintains
the aspect ratio of the image by default, so it resizes the image
as much as possible to conform to the new size, while maintaining
the aspect ratio. For example, place your pointer over the image
in this example to enlarge it, and then move the mouse off the image
to shrink it to its original size:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\image\ImageResize.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.effects.Resize;
]]&gt;
&lt;/fx:Script&gt;
&lt;fx:Declarations&gt;
&lt;s:Resize id="resizeBig"
widthFrom="22" widthTo="44"
heightFrom="27" heightTo="54"/&gt;
&lt;s:Resize id="resizeSmall"
widthFrom="44" widthTo="22"
heightFrom="54" heightTo="27"/&gt;
&lt;/fx:Declarations&gt;
&lt;s:Image width="22" height="27"
source="@Embed('logo.jpg')"
rollOverEffect="{resizeBig}"
rollOutEffect="{resizeSmall}"/&gt;
&lt;/s:Application&gt; </pre>
<p>For more information on the
Resize effect, see <a href="flx_behaviors_be.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fec_verapache">Introduction
to effects</a>. </p>
</div>
<div class="section"><h4 class="sectiontitle">Scaling images using fillMode and scaleMode properties</h4>
<p>You
use the <samp class="codeph">fillMode</samp> image property to determine how
an image fills into a region. </p>
<p>You can use the <samp class="codeph">fillMode</samp> property
in a tag or in ActionScript, and set one of the following values:</p>
<ul>
<li>
<p>
<samp class="codeph">scale</samp>: scales the image to fill the bounding
region. </p>
</li>
<li>
<p>
<samp class="codeph">clip</samp>: displays the image in its original
size. If the image is larger than the bounding region, the image
is clipped to the size of the bounding region. If the image is smaller
than the bounding region, an empty space is left. </p>
</li>
<li>
<p>
<samp class="codeph">repeat</samp>: repeats or tiles the image and fills
into the dimensions of the bounding region.</p>
</li>
</ul>
<p>When
you set the <samp class="codeph">fillMode</samp> property to <samp class="codeph">scale</samp> ,
you can set the <samp class="codeph">scaleMode</samp> property to <samp class="codeph">stretch</samp>, <samp class="codeph">letterbox</samp>,
or <samp class="codeph">zoom</samp>.</p>
<p>When you use the <samp class="codeph">fillMode</samp> property
in ActionScript, you use <samp class="codeph">BitmapFillMode.CLIP</samp>, <samp class="codeph">BitmapFillMode.REPEAT</samp>,
or <samp class="codeph">BitmapFillMode.SCALE</samp>. </p>
<p>To stretch the
image content to fit the bounding region, set the attribute value
to <samp class="codeph">BitmapScaleMode.STRETCH</samp>. If you set the value
to <samp class="codeph">BitmapScaleMode.LETTERBOX</samp>, the image content
is sized to fit the region boundaries while maintaining the same
aspect ratio as the original unscaled image. For <samp class="codeph">BitmapScaleMode.ZOOM</samp>,
the image content is scaled to fit with respect to the original
unscaled image's aspect ratio. This results in cropping along one
axis.</p>
<p>The following example shows the Flex logo scaled in
the letterbox-mode and stretch-mode using the <samp class="codeph">fillMode</samp> and <samp class="codeph">scaleMode</samp> properties:</p>
<div class="p">
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\image\ImageScaling.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:controlBarContent&gt;
&lt;s:Form&gt;
&lt;s:FormItem label="scaleMode:"&gt;
&lt;s:DropDownList id="ddl" selectedItem="letterbox"&gt;
&lt;s:dataProvider&gt;
&lt;s:ArrayList source="[letterbox,scale]" /&gt;
&lt;/s:dataProvider&gt;
&lt;/s:DropDownList&gt;
&lt;/s:FormItem&gt;
&lt;/s:Form&gt;
&lt;/s:controlBarContent&gt;
&lt;s:Image id="image"
source="assets/flexlogo.jpg"
height="20" width="20"
fillMode="scale"
scaleMode="{ddl.selectedItem}"
left="20" right="20" top="20" bottom="20" /&gt;
&lt;/s:Application&gt; </pre>
</div>
<p>For more code examples,
see <a href="http://blog.flexexamples.com" target="_blank">Peter
deHaan's blog</a>.</p>
</div>
</div>
</div>
<div class="nested2" id="WSc5cd04c102ae3e97-33ad5caa12c719dc7c8-7ffa_verapache"><a name="WSc5cd04c102ae3e97-33ad5caa12c719dc7c8-7ffa_verapache"><!-- --></a>
<h3 class="topictitle3">Skinning the Spark Image control</h3>
<div>
<p>The Spark Image control lets you customize the appearance
of you image through skinning. </p>
<p>When you use the <samp class="codeph">&lt;s:Image&gt;</samp> tag to import
an image, a default skin class, <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/skins/spark/ImageSkin.html" target="_blank">ImageSkin</a>,
is created. The default skin provides a simple image skin that has
a content loader with a generic progress bar and a broken image
icon to reflect invalid content. </p>
<p>The ImageSkin class provides Spark and wireframe-themed skins
that let you customize the content loader and the icon to identify
images that failed to load. You also have customizable skinning
for borders, frames, and loading states.</p>
<p>The ImageSkin class defines the following optional skin parts:</p>
<div class="p">
<ul>
<li>
<p>
<samp class="codeph">imageDisplay:BitmapImage</samp>: Lets you
specify the image to display for invalid content or loading error.</p>
</li>
<li>
<p>
<samp class="codeph">ProgressIndicator:Range</samp>: Lets you specify
the range, maximum, and minimum values of the progress bar. Use
the <samp class="codeph">stepSize</samp> property to specify the amount by
which the value changes when the <samp class="codeph">changeValueByStep()</samp> method
is called.</p>
</li>
</ul>
</div>
<p>For information about the different skin states, see the source
code for the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/skins/spark/ImageSkin.html" target="_blank">ImageSkin</a> class. </p>
<p>For examples on customizing skins and icons for the Spark Image
control, see Peter deHann’s <a href="http://www.adobe.com/go/learn_flexsparkimageskinexample_en" target="_blank">blog post</a>. </p>
</div>
</div>
<div class="nested2" id="WSc5cd04c102ae3e97-33ad5caa12c719dc7c8-7ffc_verapache"><a name="WSc5cd04c102ae3e97-33ad5caa12c719dc7c8-7ffc_verapache"><!-- --></a>
<h3 class="topictitle3">Caching and queuing of images</h3>
<div>
<p>The ContentCache class supports caching and queuing of
remote image assets, and can be associated with the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/primitives/BitmapImage.html" target="_blank">BitmapImage</a> or <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/Image.html" target="_blank">Spark Image</a> controls. </p>
<p>You set the caching and queuing properties for the image content
loader as follows:</p>
<div class="p">
<pre class="codeblock">&lt;fx:Declarations&gt;
&lt;s:ContentCache id="imgcache" enableCaching="true" enableQueueing="true"
maxActiveRequests="1" maxCacheEntries="10"/&gt;
&lt;/fx:Declarations&gt;</pre>
</div>
<p>To have a content loader with only queuing capabilities and no
caching capabilities, set <samp class="codeph">enableCaching</samp> to <samp class="codeph">false</samp>.</p>
<p>The difference that you notice in image-loading when you use
the caching-queuing mechanism can be significant, especially with
large images. Without caching, large images can take several seconds
to load. For example, you can use caching and queuing to prevent
image-flickering in a scrolling list.</p>
<p>The ContentCache class provides the following methods and properties
to manage caching and queuing:</p>
<div class="section"><h4 class="sectiontitle">Caching properties</h4>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e4634">
<p>Property name</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e4640">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e4634 ">
<p>
<samp class="codeph">maxCacheEntries</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e4640 ">
<p>Specifies the number of cache entries that
can be stored at a given time. When the cache entries exceed the
specified number, the least recent cache entries are automatically
removed. The default value is 100.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e4634 ">
<p>
<samp class="codeph">enableQueuing</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e4640 ">
<p>Enables queuing of images. The default value
is <samp class="codeph">false</samp>.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e4634 ">
<p>
<samp class="codeph">enableCaching</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e4640 ">
<p>Enables caching of images. The default value
is <samp class="codeph">true</samp>.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e4634 ">
<p>
<samp class="codeph">maxActiveRequests</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e4640 ">
<p>Specifies the number of pending load requests
that can be active at a given time when image-queuing is enabled.
The default value is 2.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section"><h4 class="sectiontitle">Caching methods</h4>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e4749">
<p>Method name</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e4755">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e4749 ">
<p>
<samp class="codeph">load()</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e4755 ">
<p>Returns the requested image using the <samp class="codeph">ContentRequest </samp>instance.
If the image is still loading, <samp class="codeph">ContentRequest</samp> returns
a value of <samp class="codeph">false</samp>. If the requested image is found
in the cache, <samp class="codeph">ContentRequest</samp> returns a value of <samp class="codeph">complete</samp>.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e4749 ">
<p>
<samp class="codeph">removeAllCacheEntries()</samp>
</p>
<p>
<samp class="codeph">removeCacheEntry()</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e4755 ">
<p>Removes cache entries.</p>
<p>Use <samp class="codeph">removeCacheEntry()</samp> to
remove a single cache entry that's no longer needed. Use <samp class="codeph">removeAllCacheEntries()</samp> to
remove all the cached content.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e4749 ">
<p>
<samp class="codeph">getCacheEntry()</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e4755 ">
<p>Checks for a pre-existing cache entry, and
if found, obtains a reference to the cache entry. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e4749 ">
<p>
<samp class="codeph">addCacheEntry()</samp>
<samp class="codeph"/>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e4755 ">
<p>Adds a new cache entry. Use<samp class="codeph"> addCacheEntry</samp> to
manually add a cache entry.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section"><h4 class="sectiontitle">Queuing methods</h4>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e4893">
<p>Method</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e4899">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e4893 ">
<p>
<samp class="codeph">prioritize()</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e4899 ">
<p>Forces all pending requests of the specified
contentLoaderGrouping to be moved to the top of the request list,
when image-queuing is enabled. Any active URL requests at that time
are canceled and requeued if their contentLoaderGrouping does not
match the prioritized content grouping.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e4893 ">
<p>
<samp class="codeph">removeAllQueueEntries()</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e4899 ">
<p>Cancels all the queued requests.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section"><h4 class="sectiontitle">Example on caching and queuing images</h4>
<p>The
following example shows loading of images using the contentLoader. Caching
and queuing are enabled and custom item renderers are used.</p>
<div class="p">
<pre class="noswf">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\image\ImageCaching.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Style&gt;
@namespace s "library://ns.adobe.com/flex/spark";
@namespace mx "library://ns.adobe.com/flex/mx";
s|Image {
enableLoadingState: true;
}
&lt;/fx:Style&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayList;
protected var arrList:ArrayList = new ArrayList();
protected function init():void {
var rand:String = new Date().time.toString()
var arr:Array = [];
arr.push({src:"http://localhost:8100/flex/assets/fblogo.jpg?" + rand, cache:ldr});
arr.push({src:"http://localhost:8100/flex/assets/flexlogo.jpg?" + rand, cache:ldr});
arrList = new ArrayList(arr);
dataGrp.dataProvider = arrList;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;fx:Declarations&gt;
&lt;s:ContentCache id="ldr" enableQueueing="true"
maxActiveRequests="1" maxCacheEntries="10"/&gt;
&lt;/fx:Declarations&gt;
&lt;s:Panel title="Loading images using the caching-queuing mechanism" x="20" y="20"&gt;
&lt;s:controlBarContent&gt;
&lt;s:Button label="Load Images" click="init();"/&gt;
&lt;/s:controlBarContent&gt;
&lt;s:DataGroup id="dataGrp"&gt;
&lt;s:layout&gt;
&lt;s:TileLayout /&gt;
&lt;/s:layout&gt;
&lt;s:itemRenderer&gt;
&lt;fx:Component&gt;
&lt;s:ItemRenderer dataChange="imageDisplay.source = data.src;"&gt;
&lt;s:Image id="imageDisplay" contentLoaderGrouping="gr1"
contentLoader="{data.cache}" width="200" height="200" /&gt;
&lt;/s:ItemRenderer&gt;
&lt;/fx:Component&gt;
&lt;/s:itemRenderer&gt;
&lt;/s:DataGroup&gt;
&lt;/s:Panel&gt;
&lt;/s:Application&gt;</pre>
<div class="note"><span class="notetitle">Note:</span> You can replace
the URLs in the example to access images over the Internet rather
than access them locally.</div>
</div>
</div>
</div>
</div>
<div class="nested2" id="WSc5cd04c102ae3e97-33ad5caa12c719dc7c8-7ffd_verapache"><a name="WSc5cd04c102ae3e97-33ad5caa12c719dc7c8-7ffd_verapache"><!-- --></a>
<h3 class="topictitle3">Loading images using a customizable
load interface</h3>
<div>
<p>Flex provides a customizable content loader, <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/core/IContentLoader.html" target="_blank">IContentLoader</a>,
to load images. The IContentLoader has a simple interface that contains
a <samp class="codeph">load</samp> method to manage the load requests. For
a given source, which is usually a URL, the <samp class="codeph">load</samp> method returns
the requested resources using the <samp class="codeph">ContentRequest</samp>instance.
The <samp class="codeph">ContentRequest</samp> instance provides the load progress
information and also notifies any content validation errors.</p>
<p>The <samp class="codeph">load</samp> method also provides a <samp class="codeph">contentLoaderGrouping</samp> instance
to manage multiple load requests as a group. For example, the ContentCache's queuing
methods allows requests to be prioritized by <samp class="codeph">contentLoaderGrouping</samp>. </p>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d96_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d96_verapache"><!-- --></a>
<h2 class="topictitle2">HRule and VRule controls</h2>
<div>
<p>The HRule and VRule controls are part of the MX component
set. There is no Spark equivalent. </p>
<p>
The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/HRule.html" target="_blank">HRule</a> (Horizontal
Rule) control creates a single horizontal line and the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/VRule.html" target="_blank">VRule</a> (Vertical
Rule) control creates a single vertical line. You typically use
these controls to create dividing lines within a container. </p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7f95_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7f95_verapache"><!-- --></a>
<h3 class="topictitle3">Creating HRule and VRule controls</h3>
<div>
<p>
You
define HRule and VRule controls in MXML by using the <samp class="codeph">&lt;mx:HRule&gt;</samp> and <samp class="codeph">&lt;mx:VRule&gt;</samp> tags,
as the following example shows. Specify an <samp class="codeph">id</samp> value
if you intend to refer to a component elsewhere in your MXML, either
in another tag or an ActionScript block. </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\rule\RuleSimple.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:VGroup&gt;
&lt;mx:Label text="Above"/&gt;
&lt;mx:HRule/&gt;
&lt;mx:Label text="Below"/&gt;
&lt;s:HGroup&gt;
&lt;mx:Label text="Left"/&gt;
&lt;mx:VRule/&gt;
&lt;mx:Label text="Right"/&gt;
&lt;/s:HGroup&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
<p>You can also use properties of the HRule and VRule controls to
specify line width, stroke color, and shadow color, as the following
example shows: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\rule\RuleProps.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:VGroup&gt;
&lt;mx:Label text="Above"/&gt;
&lt;mx:HRule shadowColor="0xff0000"/&gt;
&lt;mx:Label text="Below"/&gt;
&lt;s:HGroup&gt;
&lt;mx:Label text="Left"/&gt;
&lt;mx:VRule strokeWidth="10" strokeColor="0x00ff00"/&gt;
&lt;mx:Label text="Right"/&gt;
&lt;/s:HGroup&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7f94_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7f94_verapache"><!-- --></a>
<h3 class="topictitle3">Sizing HRule and VRule controls</h3>
<div>
<p>
For
the HRule and VRule controls, the <samp class="codeph">strokeWidth</samp> property
determines how Flex draws the line, as follows: </p>
<ul>
<li>
<p>If you set the <samp class="codeph">strokeWidth</samp> property
to 1, Flex draws a 1-pixel-wide line.</p>
</li>
<li>
<p>If you set the <samp class="codeph">strokeWidth</samp> property to 2,
Flex draws the rule as two adjacent 1-pixel-wide lines, horizontal
for an HRule control or vertical for a VRule control. This is the
default value.</p>
</li>
<li>
<p>If you set the <samp class="codeph">strokeWidth</samp> property to a
value greater than 2, Flex draws the rule as a hollow rectangle
with 1-pixel-wide edges.</p>
</li>
</ul>
<p>The following example shows all three options: </p>
<div class="figborder">
<img src="images/ctr_vrsw.png"/>
<dl>
<dt class="dlterm">
<strong>A.</strong>
</dt>
<dd>strokeWidth = 1</dd>
<dt class="dlterm">
<strong>B.</strong>
</dt>
<dd>default strokeWidth = 2</dd>
<dt class="dlterm">
<strong> C.</strong>
</dt>
<dd>strokeWidth = 10</dd>
</dl>
</div>
<p>If you set the <samp class="codeph">height</samp> property of an HRule control
to a value greater than the <samp class="codeph">strokeWidth</samp> property,
Flex draws the rule within a rectangle of the specified height,
and centers the rule vertically within the rectangle. The height
of the rule is the height specified by the <samp class="codeph">strokeWidth</samp> property. </p>
<p>If you set the <samp class="codeph">width</samp> property of a VRule control
to a value greater than the <samp class="codeph">strokeWidth</samp> property,
Flex draws the rule within a rectangle of the specified width, and
centers the rule horizontally within the rectangle. The width of
the rule is the width specified by the <samp class="codeph">strokeWidth</samp> property. </p>
<p>If you set the <samp class="codeph">height</samp> property of an HRule control
or the <samp class="codeph">width</samp> property of a VRule control to a value
smaller than the <samp class="codeph">strokeWidth</samp> property, the rule
is drawn as if it had a <samp class="codeph">strokeWidth</samp> property equal
to the <samp class="codeph">height</samp> or <samp class="codeph">width</samp> property.</p>
<div class="note"><span class="notetitle">Note:</span> If the <samp class="codeph">height</samp> and <samp class="codeph">width</samp> properties
are specified as percentage values, the actual pixel values are
calculated before the <samp class="codeph">height</samp> and <samp class="codeph">width</samp> properties
are compared to the <samp class="codeph">strokeWidth</samp> property.</div>
<p>The <samp class="codeph">strokeColor</samp> and <samp class="codeph">shadowColor</samp> properties
determine the colors of the HRule and VRule controls. The <samp class="codeph">strokeColor</samp> property
specifies the color of the line as follows:</p>
<ul>
<li>
<p>If you set the <samp class="codeph">strokeWidth</samp> property
to 1, specifies the color of the entire line.</p>
</li>
<li>
<p>If you set the <samp class="codeph">strokeWidth</samp> property to 2,
specifies the color of the top line for an HRule control, or the
left line for a VRule control.</p>
</li>
<li>
<p>If you set the <samp class="codeph">strokeWidth</samp> property to a
value greater than 2, specifies the color of the top and left edges
of the rectangle. </p>
</li>
</ul>
<p>The <samp class="codeph">shadowColor</samp> property specifies the shadow
color of the line as follows: </p>
<ul>
<li>
<p>If you set the <samp class="codeph">strokeWidth</samp> property
to 1, does nothing.</p>
</li>
<li>
<p>If you set the <samp class="codeph">strokeWidth</samp> property to 2,
specifies the color of the bottom line for an HRule control, or
the right line for a VRule control. </p>
</li>
<li>
<p>If you set the <samp class="codeph">strokeWidth</samp> property to a
value greater than 2, specifies the color of the bottom and right
edges of the rectangle. </p>
</li>
</ul>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7f93_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7f93_verapache"><!-- --></a>
<h3 class="topictitle3">Setting style properties</h3>
<div>
<p>
The <samp class="codeph">strokeWidth</samp>, <samp class="codeph">strokeColor</samp>,
and <samp class="codeph">shadowColor</samp> properties are style properties.
Therefore, you can set them in MXML as part of the tag definition,
set them by using the <samp class="codeph">&lt;fx:Style&gt;</samp> tag in MXML,
or set them by using the <samp class="codeph">setStyle()</samp> method in ActionScript. </p>
<p>The following example uses the <samp class="codeph">&lt;fx:Style&gt;</samp> tag
to set the default value of the <samp class="codeph">strokeColor</samp> property
of all <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/HRule.html" target="_blank">HRule</a> controls
to <samp class="codeph">#00FF00</samp> (lime green), and the default value
of the <samp class="codeph">shadowColor</samp> property to <samp class="codeph">#0000FF</samp> (blue).
This example also defines a class selector, called <samp class="codeph">thickRule</samp>,
with a <samp class="codeph">strokeWidth</samp> of 5 that you can use with any
instance of an HRule control or <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/VRule.html" target="_blank">VRule</a> control:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\rule\RuleStyles.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Style&gt;
@namespace mx "library://ns.adobe.com/flex/mx";
.thickRule {strokeWidth:5}
mx|HRule {strokeColor:#00FF00; shadowColor:#0000FF}
&lt;/fx:Style&gt;
&lt;mx:HRule styleName="thickRule"/&gt;
&lt;/s:Application&gt; </pre>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d95_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d95_verapache"><!-- --></a>
<h2 class="topictitle2">HSlider and VSlider controls</h2>
<div>
<p>The HSlider and VSlider controls are part of both the MX
and Spark component sets. While you can use the MX HSlider and VSlider
controls in your application, it’s best to use the Spark controls
instead.</p>
<p>
You
can use the slider controls to select a value by moving a slider
thumb between the end points of the slider track. The current value
of the slider is determined by the relative location of the thumb
between the end points of the slider. The slider end points correspond
to the slider’s minimum and maximum values. </p>
<p>By default, the minimum value of a slider is 0 and the maximum
value is 10. The current value of the slider can be any value in
a continuous range between the minimum and maximum values. It can
also be one of a set of discrete values, depending on how you configure
the control.</p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fc8_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fc8_verapache"><!-- --></a>
<h3 class="topictitle3">About slider controls</h3>
<div>
<p>
Flex
provides two slider controls: the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/HSlider.html" target="_blank">HSlider</a> (Horizontal
Slider) control, which creates a horizontal slider, and the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/VSlider.html" target="_blank">VSlider</a> (Vertical
Slider) control, which creates a vertical slider. The slider controls
contain a track and a slider thumb. You can optionally show or hide
tooltips and data tips, which show the data value as the user drags
the slider thumb. The slider controls do not contain a label property, but
you can add labels to the component skin.</p>
<p>The following code example shows a horizontal slider and a vertical
slider with different properties set. In the horizontal slider,
the values increment and decrement by a value of 0.25. In the vertical
slider, the data tip is hidden but a tool tip is visible.</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\slider\HSliderSimple.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:Group&gt;
&lt;s:layout&gt;
&lt;s:HorizontalLayout paddingTop="10"
paddingLeft="10"/&gt;
&lt;/s:layout&gt;
&lt;s:HSlider id="horizontalBar"
snapInterval=".25"/&gt;
&lt;s:VSlider id="volumeBar"
showDataTip="false"
toolTip="Volume"/&gt;
&lt;/s:Group&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fc7_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fc7_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a slider control</h3>
<div>
<p>
You define an HSlider control in
MXML by using the <samp class="codeph">&lt;s:HSlider&gt;</samp> tag. Define a
VSlider control by using the <samp class="codeph">&lt;s:VSlider&gt;</samp> tag.
Specify an <samp class="codeph">id</samp> value if you intend to refer to a
component elsewhere, either in another tag or in an ActionScript
block. </p>
<p>You can bind the <samp class="codeph">value</samp> property of a slider
to another control to display the current value of the slider. The
following example binds the <samp class="codeph">value</samp> property to a Label
box. Because the <samp class="codeph">liveDragging</samp> style property is
set to <samp class="codeph">true</samp>, the value in the text box updates
as the slider moves. The <samp class="codeph">dataTipPrecision</samp> property is
set to 0 to show whole numbers.</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\slider\HSliderBinding.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:Group&gt;
&lt;s:layout&gt;
&lt;s:HorizontalLayout paddingTop="10"
paddingLeft="10"/&gt;
&lt;/s:layout&gt;
&lt;s:HSlider id="mySlider"
liveDragging="true"
dataTipPrecision="0"/&gt;
&lt;s:Label text="The slider value is: {Math.round(mySlider.value)}"/&gt;
&lt;/s:Group&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fc6_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fc6_verapache"><!-- --></a>
<h3 class="topictitle3">Using slider events</h3>
<div>
<p>
The slider controls let the user
select a value by moving the slider thumb between the minimum and
maximum values of the slider. You typically use events with the
slider to recognize when the user has moved the thumb and to determine
the current value associated with the slider. </p>
<p>The slider controls can dispatch the events described in the
following table:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e5594">
<p>Event</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e5600">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e5594 ">
<div class="p">
<pre class="codeblock">change</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e5600 ">
<p>Dispatches when the user moves the thumb.
If the <samp class="codeph">liveDragging</samp> property is <samp class="codeph">true</samp>,
the event is dispatched continuously as the user moves the thumb.
If <samp class="codeph">liveDragging</samp> is <samp class="codeph">false</samp>, the
event is dispatched when the user releases the slider thumb.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e5594 ">
<div class="p">
<pre class="codeblock">thumbDrag</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e5600 ">
<p>Dispatches when the user moves a thumb.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e5594 ">
<div class="p">
<pre class="codeblock">thumbPress</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e5600 ">
<p>Dispatches when the user selects a thumb
by using the pointer.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e5594 ">
<div class="p">
<pre class="codeblock">thumbRelease</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e5600 ">
<p>Dispatches when the user releases the pointer
after a <samp class="codeph">thumbPress</samp> event occurs.</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>The following code example uses a <samp class="codeph">change</samp> event
to enable a Submit button when the user releases the slider thumb: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\slider\HSliderEvent.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
public function changeRB():void {
myButton.enabled=true;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:Group&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout paddingTop="10"
paddingLeft="10"/&gt;
&lt;/s:layout&gt;
&lt;s:HSlider id="mySlider"
thumbRelease="changeRB()"/&gt;
&lt;s:Button id="myButton" enabled="false" label="Submit"/&gt;
&lt;/s:Group&gt;
&lt;/s:Application&gt;</pre>
<p>By default, the <samp class="codeph">liveDragging</samp> property of the
slider control is set to <samp class="codeph">false</samp>. A value of <samp class="codeph">false</samp> means
that the control dispatches the <samp class="codeph">change</samp> event when
the user releases the slider thumb. If you set <samp class="codeph">liveDragging</samp> to <samp class="codeph">true</samp>,
the control dispatches the <samp class="codeph">change</samp> event continuously
as the user moves the thumb, as shown in <a href="flx_controls_ctr.html#WS2db454920e96a9e51e63e3d11c0bf63b33-7fc7_verapache">Creating
a slider control</a>.</p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fc4_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fc4_verapache"><!-- --></a>
<h3 class="topictitle3">Using data tips</h3>
<div>
<p>
By default, when you select a slider
thumb, a data tip appears, showing the current value of the slider.
As you move the selected thumb, the data tip shows the new slider
value. You can disable data tips by setting the <samp class="codeph">showDataTip</samp> property
to <samp class="codeph">false</samp>. </p>
<p>You can use the <samp class="codeph">dataTipFormatFunction</samp> property
to specify a callback function to format the data tip text. This
function takes a single String argument containing the data tip
text. It returns a String containing the new data tip text, as the
following example shows: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\slider\HSliderDataTip --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
private function myDataTipFunc(val:String):String {
return "Current value: " + String(val);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:layout&gt;
&lt;s:HorizontalLayout paddingTop="10"
paddingLeft="10"/&gt;
&lt;/s:layout&gt;
&lt;s:HSlider
height="80"
dataTipFormatFunction="myDataTipFunc"/&gt;
&lt;/s:Application&gt;</pre>
<p>In this example, the data tip function prefixes the data tip
text with the String "Current value:". You can modify this example
to insert other characters, such as a dollar sign ($), on the data
tip.</p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fc3_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fc3_verapache"><!-- --></a>
<h3 class="topictitle3">Keyboard navigation</h3>
<div>
<p>
The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/HSlider.html" target="_blank">HSlider</a> and <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/VSlider.html" target="_blank">VSlider</a> controls
have the following keyboard navigation features when the slider
control has focus: </p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e5830">
<p>Key</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e5836">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e5830 ">
<p>Left Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e5836 ">
<p>Decrement the value of an HSlider control
by one value interval or, if you do not specify a value interval,
by one pixel. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e5830 ">
<p>Right Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e5836 ">
<p>Increment the value of a HSlider control
by one value interval or, if you do not specify a value interval,
by one pixel.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e5830 ">
<p>Home</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e5836 ">
<p>Moves the thumb of an HSlider control to
its minimum value. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e5830 ">
<p>End</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e5836 ">
<p>Moves the thumb of an HSlider control to
its maximum value. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e5830 ">
<p>Up Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e5836 ">
<p>Increment the value of an VSlider control
by one value interval or, if you do not specify a value interval,
by one pixel.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e5830 ">
<p>Down Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e5836 ">
<p>Decrement the value of a VSlider control
by one value interval or, if you do not specify a value interval,
by one pixel.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d92_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d92_verapache"><!-- --></a>
<h2 class="topictitle2">LinkBar control</h2>
<div>
<p>The LinkBar control is part of the MX component set. There
is no Spark equivalent. </p>
<p>
A <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/LinkBar.html" target="_blank">LinkBar</a> control
defines a horizontal or vertical row of <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/LinkButton.html" target="_blank">LinkButton</a> controls
that designate a series of link destinations. You typically use
a LinkBar control to control the active child container of a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/containers/ViewStack.html" target="_blank">ViewStack</a> container,
or to create a standalone set of links. </p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fe8_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fe8_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a LinkBar control</h3>
<div>
<p>One of the most common uses of a LinkBar control is to
control the active child of a ViewStack container. For an example,
see <a href="flx_navigators_na.html#WS2db454920e96a9e51e63e3d11c0bf69084-7e4d_verapache">MX
ViewStack navigator container</a>. </p>
<p>You can also use a LinkBar control on its own to create a set
of links in your application. In the following example, you define
an itemClick handler for the LinkBar control to respond to user
input, and use the <samp class="codeph">dataProvider</samp> property of the LinkBar
to specify its label text: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\bar\LBarSimple.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;mx:LinkBar borderStyle="solid"
itemClick="navigateToURL(new URLRequest('http://www.adobe.com/' +
String(event.label).toLowerCase()), '_blank');"&gt;
&lt;mx:dataProvider&gt;
&lt;fx:String&gt;Flex&lt;/fx:String&gt;
&lt;fx:String&gt;Installer&lt;/fx:String&gt;
&lt;fx:String&gt;FlexJS&lt;/fx:String&gt;
&lt;fx:String&gt;TourDeFlex&lt;/fx:String&gt;
&lt;/mx:dataProvider&gt;
&lt;/mx:LinkBar&gt;
&lt;/s:Application&gt; </pre>
<p>In this example, you use the <samp class="codeph">&lt;mx:dataProvider&gt;</samp> tag
to define the label text. The event object passed to the <samp class="codeph">itemClick</samp> handler
contains the label selected by the user. The handler for the <samp class="codeph">itemClick</samp> event
constructs an HTTP request to the website based on the label, and
opens that page in a new browser window. </p>
<p>You can also bind data to the <samp class="codeph">dataProvider</samp> property
to populate the LinkBar control, as the following example shows: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\bar\LBarBinding.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
[Bindable]
private var linkData:ArrayCollection = new ArrayCollection([
{label:'Flex', url:'http://flex.apache.org/products/Flex/'},
{label:'Installer', url:'http://flex.apache.org/products/Installer/'},
{label:'FlexJS', url:'http://flex.apache.org/products/FlexJS/'},
{label:'TourDeFlex', url:'http://flex.apache.org/products/TourDeFlex/'}]);
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:LinkBar
dataProvider="{linkData}"
horizontalAlign="right"
borderStyle="solid"
itemClick="navigateToURL(new URLRequest(event.item.url), '_blank');"&gt;
&lt;/mx:LinkBar&gt;
&lt;/s:Application&gt;</pre>
<p>A LinkBar control creates LinkButton controls based on the value
of its <samp class="codeph">dataProvider</samp> property. Even though LinkBar
is a subclass of Container, do not use methods such as <samp class="codeph">Container.addChild()</samp> and <samp class="codeph">Container.removeChild()</samp> to
add or remove LinkButton controls. Instead, use methods such as <samp class="codeph">addItem()</samp> and <samp class="codeph">removeItem()</samp> to
manipulate the <samp class="codeph">dataProvider</samp> property. A LinkBar
control automatically adds or removes the necessary children based
on changes to the <samp class="codeph">dataProvider</samp> property. </p>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d93_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d93_verapache"><!-- --></a>
<h2 class="topictitle2">LinkButton control</h2>
<div>
<p>The LinkButton control is part of the MX component set.
There is no Spark equivalent. </p>
<p>
The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/LinkButton.html" target="_blank">LinkButton</a> control
creates a single-line hypertext link that supports an optional icon.
You can use a LinkButton control to open a URL in a web browser. </p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fcb_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fcb_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a LinkButton control</h3>
<div>
<p>
You
define a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/LinkButton.html" target="_blank">LinkButton</a> control
in MXML by using the <samp class="codeph">&lt;mx:LinkButton&gt;</samp> tag, as
the following example shows. Specify an <samp class="codeph">id</samp> value
if you intend to refer to a component elsewhere in your MXML, either
in another tag or in an ActionScript block: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\button\LBSimple.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;mx:HBox&gt;
&lt;mx:LinkButton label="link1"/&gt;
&lt;mx:LinkButton label="link2"/&gt;
&lt;mx:LinkButton label="link3"/&gt;
&lt;/mx:HBox&gt;
&lt;/s:Application&gt;</pre>
<p>The following code contains a single LinkButton control that
opens a URL in a web browser window: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\button\LBURL.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;mx:LinkButton label="ADBE"
width="100"
click="navigateToURL(new URLRequest('http://quote.yahoo.com/q?s=ADBE'), 'quote')"/&gt;
&lt;/s:Application&gt;</pre>
<p>This example uses the <samp class="codeph">navigateToURL()</samp> method
to open the URL. </p>
<p>The LinkButton control automatically provides visual cues when
you move your mouse pointer over or click the control. The previous
code example contains no link handling logic but does change color
when you move your mouse pointer over or click a link.</p>
<p>The following code example contains LinkButton controls for navigating
in a ViewStack navigator container:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\button\LBViewStack.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;mx:VBox&gt;
&lt;!-- Put the links in an HBox container across the top. --&gt;
&lt;mx:HBox&gt;
&lt;mx:LinkButton label="Link1"
click="viewStack.selectedIndex=0;"/&gt;
&lt;mx:LinkButton label="Link2"
click="viewStack.selectedIndex=1;"/&gt;
&lt;mx:LinkButton label="Link3"
click="viewStack.selectedIndex=2;"/&gt;
&lt;/mx:HBox&gt;
&lt;!-- This ViewStack container has three children. --&gt;
&lt;mx:ViewStack id="viewStack"&gt;
&lt;mx:VBox width="150"&gt;
&lt;mx:Label text="One"/&gt;
&lt;/mx:VBox&gt;
&lt;mx:VBox width="150"&gt;
&lt;mx:Label text="Two"/&gt;
&lt;/mx:VBox&gt;
&lt;mx:VBox width="150"&gt;
&lt;mx:Label text="Three"/&gt;
&lt;/mx:VBox&gt;
&lt;/mx:ViewStack&gt;
&lt;/mx:VBox&gt;
&lt;/s:Application&gt;</pre>
<p>A LinkButton control’s label is centered within the bounds of
the LinkButton control. You can position the text label in relation
to the icon by using the <samp class="codeph">labelPlacement</samp> property,
which accepts the values <samp class="codeph">right</samp>, <samp class="codeph">left</samp>, <samp class="codeph">bottom</samp>, and <samp class="codeph">top</samp>.</p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7db0_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7db0_verapache"><!-- --></a>
<h3 class="topictitle3">LinkButton control user interaction</h3>
<div>
<p>
When
a user clicks a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/LinkButton.html" target="_blank">LinkButton</a> control,
the LinkButton control dispatches a <samp class="codeph">click</samp> event.
If a LinkButton control is enabled, the following happens: </p>
<ul>
<li>
<p>When the user moves the mouse pointer over the LinkButton
control, the LinkButton control changes its rollover appearance.</p>
</li>
<li>
<p>When the user clicks the LinkButton control, the input focus
moves to the control and the LinkButton control displays its pressed
appearance. When the user releases the mouse button, the LinkButton
control returns to its rollover appearance.</p>
</li>
<li>
<p>If the user moves the mouse pointer off the LinkButton control
while pressing the mouse button, the control’s appearance returns
to its original state and the control retains input focus.</p>
</li>
<li>
<p>If the toggle property is set to <samp class="codeph">true</samp>, the
state of the LinkButton control does not change until the mouse
button is released over the control.</p>
</li>
</ul>
<p>If a LinkButton control is disabled, it appears as disabled,
regardless of user interaction. In the disabled state, the control
ignores all mouse or keyboard interaction.</p>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d8d_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d8d_verapache"><!-- --></a>
<h2 class="topictitle2">NumericStepper control</h2>
<div>
<p>The NumericStepper control is part of both the MX and Spark
component sets. While you can use the MX NumericStepper control
in your application, it’s best to use the Spark control instead.</p>
<p>
You
can use the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/NumericStepper.html" target="_blank">NumericStepper</a> control
to select a number from an ordered set. The NumericStepper control
consists of a single-line input text field and a pair of arrow buttons
for stepping through the valid values. You can use the Up Arrow and
Down arrow keys to cycle through the values. </p>
<p>If the user clicks the up arrow, the value displayed increases
by one unit of change. If the user holds down the arrow, the value
increases or decreases until the user releases the mouse button.
When the user clicks the arrow, it is highlighted to provide feedback
to the user. </p>
<p>Users can also type a legal value directly into the text field.
Although editable <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/ComboBox.html" target="_blank">ComboBox</a> controls
provide similar functionality, NumericStepper controls are sometimes
preferred because they do not require a drop-down list that can obscure
important data. </p>
<p>NumericStepper control arrows always appear to the right of the
text field.</p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d6d_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d6d_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a NumericStepper control</h3>
<div>
<p>
You
define a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/NumericStepper.html" target="_blank">NumericStepper</a> control
in MXML by using the <samp class="codeph">&lt;s:NumericStepper&gt;</samp> tag,
as the following example shows. Specify an <samp class="codeph">id</samp> value
if you intend to refer to a component elsewhere in your MXML, either
in another tag or in an ActionScript block: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\numericstepper\NumStepSimple.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:NumericStepper id="nstepper1"
value="6"
stepSize="2"
maximum="100"/&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fd9_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fd9_verapache"><!-- --></a>
<h3 class="topictitle3">Sizing a NumericStepper control</h3>
<div>
<p>
When
the control is resized, the width of the Up and Down arrow buttons
in the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/NumericStepper.html" target="_blank">NumericStepper</a> control
do not change size. If the NumericStepper control is sized greater
than the default height, the associated stepper buttons appear pinned
to the top and the bottom of the control. </p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fd8_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fd8_verapache"><!-- --></a>
<h3 class="topictitle3">User interaction</h3>
<div>
<p>If the user clicks the Up or Down arrow button, the value
displayed increases by one unit of change. If the user presses either
of the arrow buttons for more than 200 milliseconds, the value in
the input field increases or decreases, based on step size, until
the user releases the mouse button or the maximum or minimum value
is reached.</p>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fd8_verapache__WS2db454920e96a9e51e63e3d11c0bf63b33-7fd7_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fd8_verapache__WS2db454920e96a9e51e63e3d11c0bf63b33-7fd7_verapache"><!-- --></a><h4 class="sectiontitle">Keyboard
navigation</h4>
<p>
The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/NumericStepper.html" target="_blank">NumericStepper</a> control
has the following keyboard navigation features: </p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e6376">
<p>Key</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e6382">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e6376 ">
<p>Down Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e6382 ">
<p>Value decreases by one unit.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e6376 ">
<p>Up Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e6382 ">
<p>Value increases by one unit.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e6376 ">
<p>Left Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e6382 ">
<p>Moves the insertion point to the left within
the NumericStepper control’s text field.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e6376 ">
<p>Right Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e6382 ">
<p>Moves the insertion point to the right within
the Numeric Stepper control’s text field.</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>To use the keyboard to navigate through
the stepper, it must have focus.</p>
</div>
</div>
</div>
</div>
<div class="nested1" id="WSb04c7610c3432839-69935906121d15620a8-8000_verapache"><a name="WSb04c7610c3432839-69935906121d15620a8-8000_verapache"><!-- --></a>
<h2 class="topictitle2">PopUpAnchor control</h2>
<div>
<p>The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/PopUpAnchor.html" target="_blank">PopUpAnchor</a> control
is part of the Spark component set. There is no MX equivalent. </p>
<p>The PopUpAnchor control displays a pop-up component in a layout.
It has no visual appearance, but it has dimensions. The PopUpAnchor
control is used in the DropDownList control. The PopUpAnchor displays
the pop-up component by adding it to the PopUpManager, and then
sizes and positions the pop-up component relative to itself. Because
the pop-up component is managed by the PopUpManager, it appears
above all other controls.</p>
<p>With the PopUpAnchor control, you can create various kinds of
popup functionality, such as the following:</p>
<div class="p">
<ul>
<li>
<p>Click a button and a form to submit feedback pops
up</p>
</li>
<li>
<p>Click a button, and a search field pops up</p>
</li>
<li>
<p>Mouse over the top of an application and a menu drops down</p>
</li>
<li>
<p>In a calendar tool, double-click an appointment block to
open an Edit dialog</p>
</li>
</ul>
</div>
</div>
<div class="nested2" id="WSb04c7610c3432839-7b644078121d1b2e86e-8000_verapache"><a name="WSb04c7610c3432839-7b644078121d1b2e86e-8000_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a pop-up component with
PopUpAnchor</h3>
<div>
<p>Define a PopUpAnchor control in MXML by using the <samp class="codeph">&lt;s:PopUpAnchor&gt;</samp> tag. as
the following example shows. Specify an <samp class="codeph">id</samp> value
if you intend to refer to a component elsewhere in your MXML, either
in another tag or in an ActionScript block.</p>
<p>Use the PopUpAnchor with two other components: the control that
opens the popup, and the component that pops up (referred to as
the pop-up component). The value of the <samp class="codeph">popUp</samp> property
is the pop-up component. </p>
<p>The following example creates an application with a button labeled
Show slider. Click the button, and a VSlider component pops up.
When you select a value using the slider, the <samp class="codeph">thumbRelease</samp> event
is triggered and the popup closes.</p>
<div class="p">
<pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- controls\popup\PopUpSimple.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:HGroup&gt;
&lt;s:Button label="Show slider"
click="slide.displayPopUp = true"/&gt;
&lt;s:PopUpAnchor id="slide"&gt;
&lt;s:VSlider
maxHeight="40"
thumbRelease="slide.displayPopUp = false"/&gt;
&lt;/s:PopUpAnchor&gt;
&lt;/s:HGroup&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested2" id="WSb04c7610c34328397ff27ed6121d1b78c9a-8000_verapache"><a name="WSb04c7610c34328397ff27ed6121d1b78c9a-8000_verapache"><!-- --></a>
<h3 class="topictitle3">Sizing and positioning a popup
component</h3>
<div>
<p>The PopUpAnchor control sizes and positions the component
that pops up (the pop-up component) relative to itself. If the pop-up
doesn’t fit, it will flip the position. ABOVE -&gt; BELOW, RIGHT
-&gt; LEFT, etc. If it still doesn’t fit, it will go back to the
original position and call the pop-up until it is fully on screen.</p>
<p>The width of the pop-up component is determined in the following
order:</p>
<div class="p">
<ul>
<li>
<p>If <samp class="codeph">popUpWidthMatchesAnchorWidth</samp> is
true, use the actual width of the PopUpAnchor</p>
</li>
<li>
<p>Use the pop-up component’s <samp class="codeph">explicitWidth</samp> value,
if specified</p>
</li>
<li>
<p>Use the pop-up component's <samp class="codeph">measuredWidth</samp> value</p>
</li>
</ul>
</div>
<p>The height of the pop-up component is determined in the following
order:</p>
<div class="p">
<ul>
<li>
<p>If <samp class="codeph">popUpHeightMatchesAnchorHeight</samp> is
true, use the actual height of the PopUpAnchor control</p>
</li>
<li>
<p>Use the popup’s <samp class="codeph">explicitHeight</samp> value, if
specified</p>
</li>
<li>
<p>Use the pop-up component's <samp class="codeph">measuredHeight</samp> value</p>
</li>
</ul>
</div>
<p>The <samp class="codeph">popUpPosition</samp> property controls the position
of the pop-up component. Valid values are static properties of the
PopUpPosition class and are as follows:</p>
<div class="p">
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e6668">
<p>Value</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e6674">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e6668 ">
<p>
<samp class="codeph">above</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e6674 ">
<p>The bottom of the popup is adjacent to the
top of the PopUpAnchor control. The left edge of the popup is vertically aligned
with the left edge of the PopUpAnchor control.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e6668 ">
<p>
<samp class="codeph">below</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e6674 ">
<p>The top of the popup is adjacent to the
bottom of the PopUpAnchor control. The left edge of the pop-up is
vertically aligned with the left edge of the PopUpAnchor control.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e6668 ">
<p>
<samp class="codeph">left</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e6674 ">
<p>The right edge of the popup is adjacent
to the left edge of the PopUpAnchor control. The top edge of the
popup is horizontally aligned with the top edge of the PopUpAnchor
control.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e6668 ">
<p>
<samp class="codeph">right</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e6674 ">
<p>The left edge of the popup is adjacent to
the right edge of the PopUpAnchor control. The top edge of the popup
is horizontally aligned with the top edge of the PopUpAnchor control.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e6668 ">
<p>
<samp class="codeph">center</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e6674 ">
<p>The horizontal and vertical center of the
popup is positioned at the horizontal and vertical center of the
PopUpAnchor control. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e6668 ">
<p>
<samp class="codeph">topLeft</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e6674 ">
<p>The popup is positioned at the same default
top-left position as the PopUpAnchor control.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="nested2" id="WSb04c7610c34328397ff27ed6121d1b78c9a-7ffe_verapache"><a name="WSb04c7610c34328397ff27ed6121d1b78c9a-7ffe_verapache"><!-- --></a>
<h3 class="topictitle3">Transforming and animating a popup
component</h3>
<div>
<p>Transformations include scaling, rotation, and skewing.
Transformations that are applied to the PopUpAnchor control or its
ancestors before the pop-up component opens are always applied to
the pop-up component when it opens. However, if such changes are
applied while the pop-up is open, the changes are not applied to
the pop-up until the next time the pop-up opens. To apply transformations
to the pop-up while it is open, call the <samp class="codeph">updatePopUpTransform()</samp> method. </p>
<p>You can apply effects to animate the showing and hiding of the
pop-up. Because transformations made on the PopUpAnchor control
apply to its pop-up, you can apply effects to either the PopUpAnchor
control or its pop-up component. </p>
<p>Consider the following when deciding whether to apply an effect
on the PopUpAnchor control or its pop-up component:</p>
<div class="p">
<ul>
<li>
<p>Apply Move, Fade, Resize, and Zoom effects to the
PopUpAnchor control. Applying these effects to the PopUpAnchor control
allows the effect to respect some of the PopUpAnchor control's layout
constraints.</p>
</li>
<li>
<p>Apply Mask and Shader effects on the pop-up component directly.
These effects require applying a mask to the target or taking a
bitmap snapshot of the target.</p>
</li>
<li>
<p>If the effect is applied to the PopUpAnchor or its ancestors
while the pop-up component is open, call <samp class="codeph">updatePopUpTransform()</samp>.
Calling this method reapplies the effect to the popup while the
effect plays.</p>
</li>
</ul>
</div>
<p>The following example uses states to control the display of the
popup component. It uses transitions to play animations between
states. When you click the Email button, an e-mail form fades into
the application. Click Send or Cancel, and the e-mail form fades
out. By only including the PopUpAnchor in the emailOpen state (<samp class="codeph">includeIn="emailOpen"</samp>),
the form is only instantiated when it is displayed.</p>
<div class="p">
<pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx" &gt;
&lt;s:layout&gt;
&lt;s:HorizontalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Style&gt;
.popUpBox
{
backgroundColor : #e9e9e9;
borderStyle : "solid";
paddingTop : 2;
paddingBottom : 2;
paddingLeft : 2;
paddingRight : 2;
}
&lt;/fx:Style&gt;
&lt;s:states&gt;
&lt;s:State name="normal" /&gt;
&lt;s:State name="emailOpen" /&gt;
&lt;/s:states&gt;
&lt;s:transitions&gt;
&lt;mx:Transition fromState="*" toState="*"&gt;
&lt;mx:Sequence&gt;
&lt;s:Fade target="{emailPopUp.popUp}"
duration="250"/&gt;
&lt;/mx:Sequence&gt;
&lt;/mx:Transition&gt;
&lt;/s:transitions&gt;
&lt;s:Group x="60"&gt;
&lt;s:Button label="Send email"
click="currentState = 'emailOpen'"/&gt;
&lt;s:PopUpAnchor id="emailPopUp"
left="0" bottom="0"
popUpPosition="below"
styleName="popUpBox"
includeIn="emailOpen"
displayPopUp.normal="false"
displayPopUp.emailOpen="true"&gt;
&lt;mx:Form&gt;
&lt;mx:FormItem label="From :"&gt;
&lt;s:TextInput/&gt;
&lt;/mx:FormItem&gt;
&lt;mx:FormItem label="To :"&gt;
&lt;s:TextInput/&gt;
&lt;/mx:FormItem&gt;
&lt;mx:FormItem label="Subject :"&gt;
&lt;s:TextInput/&gt;
&lt;/mx:FormItem&gt;
&lt;mx:FormItem label="Message :"&gt;
&lt;s:TextArea width="100%"
height="100"
maxChars="120"/&gt;
&lt;/mx:FormItem&gt;
&lt;mx:FormItem direction="horizontal"&gt;
&lt;s:Button label="Send"
click="currentState = 'normal'"/&gt;
&lt;s:Button label="Cancel"
click="currentState = 'normal'" /&gt;
&lt;/mx:FormItem&gt;
&lt;/mx:Form&gt;
&lt;/s:PopUpAnchor&gt;
&lt;/s:Group&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>You can also control when the PopUpAnchor is destroyed. See <a href="flx_using_states_us.html#WS2db454920e96a9e51e63e3d11c0bf63611-7ffa_verapache">Create
and apply view states</a>, particularly the sections on <a href="flx_using_states_us.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ddd_verapache">Controlling
when to create added children</a> and <a href="flx_using_states_us.html#WSce19a0e5a003e2ed751bcef6120fd146f63-8000_verapache">Controlling
caching of objects created in a view state</a>. These sections
discuss the <samp class="codeph">itemCreationPolicy</samp> and <samp class="codeph">itemDestructionPolicy</samp> properties.</p>
<p>The following example displays a Search button with an animated
popup. Click the button, and a text input field and a Find now button
pops up on the right. Click the Find button, and the text input
field and Find now button are hidden. The animation plays directly
on the popup components. </p>
<div class="p">
<pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Style&gt;
.popUpBox
{
backgroundColor : #e9e9e9;
borderStyle : "solid";
paddingTop : 2;
paddingBottom : 2;
paddingLeft : 2;
paddingRight : 2;
}
&lt;/fx:Style&gt;
&lt;fx:Declarations&gt;
&lt;mx:Sequence id="hideSearch"&gt;
&lt;s:Scale target="{searchPopUp.popUp}"
scaleXFrom="1"
scaleXTo=".1"
duration="250"/&gt;
&lt;mx:SetPropertyAction target="{searchPopUp}"
name="displayPopUp"
value="false"/&gt;
&lt;/mx:Sequence&gt;
&lt;mx:Sequence id="showSearch"&gt;
&lt;mx:SetPropertyAction target="{searchPopUp}"
name="displayPopUp"
value="true"/&gt;
&lt;s:Scale target="{searchPopUp.popUp}"
scaleXFrom=".1"
scaleXTo="1"
duration="200"/&gt;
&lt;/mx:Sequence&gt;
&lt;/fx:Declarations&gt;
&lt;s:HGroup&gt;
&lt;s:Button label="Search database" click="showSearch.play() "/&gt;
&lt;s:PopUpAnchor id="searchPopUp"
left="0" right="0"
popUpPosition="right"
styleName="popUpBox"&gt;
&lt;s:HGroup&gt;
&lt;s:TextInput id="searchField"
width="80" /&gt;
&lt;s:Button label="Find now"
click="hideSearch.play();"/&gt;
&lt;/s:HGroup&gt;
&lt;/s:PopUpAnchor&gt;
&lt;/s:HGroup&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7b18_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7b18_verapache"><!-- --></a>
<h2 class="topictitle2">PopUpButton control</h2>
<div>
<p>The PopUpButton control is part of the MX component set.
There is no Spark equivalent. </p>
<p>
The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/PopUpButton.html" target="_blank">PopUpButton</a> control
consists of two horizontal buttons: a main button, and a smaller
button called the pop-up button, which only has an icon. The main button
is a Button control. </p>
<p>The pop-up button, when clicked, opens a second control called
the pop-up control. Clicking anywhere outside the PopUpButton control,
or in the pop-up control, closes the pop-up control</p>
<p>The PopUpButton control adds a flexible pop-up control interface
to a Button control. One common use for the PopUpButton control
is to have the pop-up button open a List control or a Menu control
that changes the function and label of the main button. </p>
<p>The PopUpButton control is not limited to displaying menus; it
can display any control as the pop-up control. A workflow application
that lets users send a document for review, for example, could use
a Tree control as a visual indication of departmental structure.
The PopUpButton control’s pop-up button would display the tree,
from which the user could pick the message recipients.</p>
<p>The control that pops up does not have to affect the main button’s
appearance or action; it can have an independent action instead.
You could create an undo PopUpButton control, for example, where
the main button undoes only the last action, and the pop-up control
is a List control that lets users undo multiple actions by selecting
them. </p>
<p>The PopUpButton control is a subclass of the Button control and
inherits all of its properties, styles, events, and methods, with
the exception of the <samp class="codeph">toggle</samp> property and the styles
used for a selected button. </p>
<p>The control has the following characteristics:</p>
<ul>
<li>
<p>The <samp class="codeph">popUp</samp> property specifies the pop-up
control (for example, List or Menu).</p>
</li>
<li>
<p>The <samp class="codeph">open()</samp> and <samp class="codeph">close()</samp> methods
lets you open and close the pop-up control programmatically, rather
than by using the pop-up button.</p>
</li>
<li>
<p>The <samp class="codeph">open</samp> and <samp class="codeph">close</samp> events
are dispatched when the pop-up control opens and closes.</p>
</li>
<li>
<p>You use the <samp class="codeph">popUpSkin</samp> and <samp class="codeph">arrowButtonWidth</samp> style
properties to define the PopUpButton control’s appearance. </p>
</li>
</ul>
<p>For detailed descriptions, see <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/PopUpButton.html" target="_blank">PopUpButton</a> in <em>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/" target="_blank">ActionScript 3.0 Reference for the Adobe
Flash Platform</a>
</em>. </p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fee_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fee_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a PopUpButton control</h3>
<div>
<p>
You
use the <samp class="codeph">&lt;mx:PopUpButton&gt;</samp> tag to define a
PopUpButton control in MXML. Specify an <samp class="codeph">id</samp> value
if you intend to refer to a component elsewhere in your MXML, either
in another tag or in an ActionScript block. </p>
<p>In the following example, you use the PopUpButton control to
open a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/Menu.html" target="_blank">Menu</a> control.
Once opened, the Menu control, or any pop-up control, functions
just as it would normally. You define an event listener for the
Menu control’s change event to recognize when the user selects a
menu item, as the following example shows: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\button\PopUpButtonMenu.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"
height="600" width="600"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.controls.*;
import mx.events.*;
private var myMenu:Menu;
// Initialize the Menu control,
// and specify it as the pop up object
// of the PopUpButton control.
private function initMenu():void {
myMenu = new Menu();
var dp:Object = [
{label: "New Folder"},
{label: "Sent Items"},
{label: "Inbox"}
];
myMenu.dataProvider = dp;
myMenu.addEventListener("itemClick", changeHandler);
popB.popUp = myMenu;
}
// Define the event listener for the Menu control's change event.
private function changeHandler(event:MenuEvent):void {
var label:String = event.label;
popTypeB.text=String("Moved to " + label);
popB.label = "Put in: " + label;
popB.close();
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:VBox&gt;
&lt;mx:Label text="Main button mimics the last selected menuItem."/&gt;
&lt;mx:PopUpButton id="popB"
label="Edit"
width="135"
creationComplete="initMenu();"/&gt;
&lt;mx:Spacer height="50"/&gt;
&lt;mx:TextInput id="popTypeB"/&gt;
&lt;/mx:VBox&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7b15_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7b15_verapache"><!-- --></a>
<h3 class="topictitle3">User interaction</h3>
<div>
<p>You navigate the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/PopUpButton.html" target="_blank">PopUpButton</a> control
in the following ways:</p>
<ul>
<li>
<p>Moving the mouse over any part of the PopUpButton control
highlights the button border and the main button or the pop-up button.</p>
</li>
<li>
<p>Clicking the button dispatches the <samp class="codeph">click</samp> event.</p>
</li>
<li>
<p>Clicking the pop-up button pops up the pop-up control and
dispatches an <samp class="codeph">open</samp> event. </p>
</li>
<li>
<p>Clicking anywhere outside the PopUpButton control, or in
the pop-up control, closes the pop-up control and dispatches a <samp class="codeph">close</samp> event.</p>
</li>
</ul>
<p>The following keystrokes let users navigate the PopUpButton control: </p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e7116">
<p>Key</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e7122">
<p>Use</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e7116 ">
<p>Spacebar</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e7122 ">
<p>Behaves like clicking the main button.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e7116 ">
<p>Control+Down Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e7122 ">
<p>Opens the pop-up control and initiates an <samp class="codeph">open</samp> event.
The pop-up control’s keyboard handling takes effect.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e7116 ">
<p>Control+Up Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e7122 ">
<p>Closes the pop-up control and initiates
a <samp class="codeph">close</samp> event.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="note"><span class="notetitle">Note:</span> You cannot use the Tab key to leave an opened
pop-up control; you must make a selection or close the control with
the Control+Up Arrow key combination.</div>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d8c_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d8c_verapache"><!-- --></a>
<h2 class="topictitle2">ProgressBar control</h2>
<div>
<p>The ProgressBar control is part of the MX component set.
There is no Spark equivalent. </p>
<p>
The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/ProgressBar.html" target="_blank">ProgressBar</a> control
provides a visual representation of the progress of a task over
time. There are two types of ProgressBar controls: determinate and
indeterminate. A <em>determinate</em> ProgressBar control is a linear
representation of the progress of a task over time. You can use
this when the user is required to wait for an extended period of
time, and the scope of the task is known. </p>
<p>An <em>indeterminate</em> ProgressBar control represents time-based
processes for which the scope is not yet known. As soon as you can
determine the scope, you should use a determinate ProgressBar control.</p>
<p>The following example shows both types of ProgressBar controls:</p>
<div class="figborder">
<img src="images/ctr_progressbar-example.png"/>
<dl>
<dt class="dlterm">
<strong>Top.</strong>
</dt>
<dd>Determinate ProgressBar control</dd>
<dt class="dlterm">
<strong>Bottom.</strong>
</dt>
<dd>Indeterminate ProgressBar control</dd>
</dl>
</div>
<p>Use the ProgressBar control when the user is required to wait
for completion of a process over an extended period of time. You
can attach the ProgressBar control to any kind of loading content.
A label can display the extent of loaded contents when enabled.</p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7f99_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7f99_verapache"><!-- --></a>
<h3 class="topictitle3">ProgressBar control modes</h3>
<div>
<p>
You
use the <samp class="codeph">mode</samp> property to specify the operating
mode of the ProgressBar control. The ProgressBar control supports
the following modes of operation: </p>
<dl>
<dt class="dlterm">event</dt>
<dd>
<p>Use the <samp class="codeph">source</samp> property to specify a loading
process that emits <samp class="codeph">progress</samp> and <samp class="codeph">complete</samp> events.
For example, the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/SWFLoader.html" target="_blank">SWFLoader</a> and <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/Image.html" target="_blank">Image</a> controls
emit these events as part of loading a file. You typically use a
determinate ProgressBar in this mode. The ProgressBar control only
updates if the value of the <samp class="codeph">source </samp>property extends
the EventDispatcher class. This is the default mode. </p>
<p>You
also use this mode if you want to measure progress on multiple loads;
for example, if you reload an image, or use the SWFLoader and Image
controls to load multiple images.</p>
</dd>
<dt class="dlterm">polled</dt>
<dd>
<p>Use the <samp class="codeph">source</samp> property to specify a loading
process that exposes the <samp class="codeph">bytesLoaded</samp> and <samp class="codeph">bytesTotal</samp> properties.
For example, the SWFLoader and Image controls expose these properties.
You typically use a determinate ProgressBar in this mode.</p>
</dd>
<dt class="dlterm">manual</dt>
<dd>
<p>Set the <samp class="codeph">maximum</samp>, <samp class="codeph">minimum</samp>,
and <samp class="codeph">indeterminate</samp> properties along with calls to
the <samp class="codeph">setProgress()</samp> method. You typically use an
indeterminate ProgressBar in this mode.</p>
</dd>
</dl>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7f98_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7f98_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a ProgressBar control</h3>
<div>
<p>
You
use the <samp class="codeph">&lt;mx:ProgressBar&gt;</samp> tag to define a
ProgressBar control in MXML, as the following example shows. Specify
an <samp class="codeph">id</samp> value if you intend to refer to a component
elsewhere in your MXML, either in another tag or in an ActionScript block. </p>
<p>The following example uses the default event mode to track the
progress of loading an image by using the Image control:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\pbar\PBarSimple.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
public function initImage():void {
image1.load('../assets/DSC00034.JPG');
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:VBox id="vbox0"
width="600" height="600"&gt;
&lt;mx:Canvas&gt;
&lt;mx:ProgressBar width="200" source="image1"/&gt;
&lt;/mx:Canvas&gt;
&lt;s:Button id="myButton"
label="Show"
click="initImage();"/&gt;
&lt;mx:Image id="image1"
height="500" width="600"
autoLoad="false"
visible="true"/&gt;
&lt;/mx:VBox&gt;
&lt;/s:Application&gt;</pre>
<p>After you run this example the first time, the large image will
typically be stored in your browser’s cache. Before running this
example a second time, clear your browser’s cache so that you can
see the ProgressBar control complete. If you do not clear your browser’s
cache, Flash Player loads the image from the cache and the ProgressBar
control might go from 0% to 100% too quickly to see it tracking any
progress in between.</p>
<p>In this mode, the Image control issues <samp class="codeph">progress</samp> events
during the load, and a <samp class="codeph">complete</samp> event when the
load completes. </p>
<p>The <samp class="codeph">&lt;mx:Image&gt;</samp> tag exposes the <samp class="codeph">bytesLoaded</samp> and <samp class="codeph">bytesTotal</samp> properties,
so you could also use <samp class="codeph">polled</samp> mode, as the following
example shows:</p>
<pre class="codeblock"> &lt;mx:ProgressBar width="200" source="image1" mode="polled"/&gt;</pre>
<p>In manual mode, <samp class="codeph">mode="manual"</samp>, you use an indeterminate
ProgressBar control with the <samp class="codeph">maximum</samp> and <samp class="codeph">minimum</samp> properties
and the <samp class="codeph">setProgress()</samp> method. The <samp class="codeph">setProgress()</samp> method
has the following method signature: </p>
<pre class="codeblock"> setProgress(Number <em>completed</em>, Number <em>total</em>)</pre>
<dl>
<dt class="dlterm">
<samp class="codeph">completed</samp>
</dt>
<dd>
<p>Specifies the progress made in the task, and must be between
the <samp class="codeph">maximum</samp> and <samp class="codeph">minimum</samp> values.
For example, if you were tracking the number of bytes to load, this
would be the number of bytes already loaded. </p>
</dd>
<dt class="dlterm">
<samp class="codeph">total</samp>
</dt>
<dd>
<p>Specifies the total task. For example, if you were tracking
bytes loaded, this would be the total number of bytes to load. Typically,
this is the same value as <samp class="codeph">maximum</samp>. </p>
<p>To measure
progress, you make explicit calls to the <samp class="codeph">setProgress()</samp> method
to update the ProgressBar control. </p>
</dd>
</dl>
<p>To measure progress, you make explicit calls to the <samp class="codeph">setProgress()</samp> method
to update the ProgressBar control. </p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7f97_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7f97_verapache"><!-- --></a>
<h3 class="topictitle3">Defining the label of a ProgressBar
control</h3>
<div>
<p>
By
default, the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/ProgressBar.html" target="_blank">ProgressBar</a> displays
the label <em>LOADING xx%</em>, where <em>xx</em> is the percent of
the image loaded. You use the <samp class="codeph">label</samp> property to
specify a different text string to display. </p>
<p>The <samp class="codeph">label</samp> property lets you include the following
special characters in the label text string:</p>
<dl>
<dt class="dlterm">%1</dt>
<dd>
<p>Corresponds to the current number of bytes loaded.</p>
</dd>
<dt class="dlterm">%2</dt>
<dd>
<p>Corresponds to the total number of bytes.</p>
</dd>
<dt class="dlterm">%3</dt>
<dd>
<p>Corresponds to the percent loaded.</p>
</dd>
<dt class="dlterm">%%</dt>
<dd>
<p>Corresponds to the % sign. </p>
<p>For example, to define
a label that displays as:</p>
<pre class="codeblock"> Loading Image 1500 out of 78000 bytes, 2%</pre>
<p>use
the following code: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\pbar\PBarLabel.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
public function initImage():void {
image1.load('../assets/DSC00034.JPG');
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:VBox id="vbox0"
width="600" height="600"&gt;
&lt;mx:Canvas&gt;
&lt;mx:ProgressBar
width="300"
source="image1"
mode="polled"
label="Loading Image %1 out of %2 bytes, %3%%"
labelWidth="400"
/&gt;
&lt;/mx:Canvas&gt;
&lt;s:Button id="myButton"
label="Show"
click="initImage();"
/&gt;
&lt;mx:Image id="image1"
height="500" width="600"
autoLoad="false"
visible="true"
/&gt;
&lt;/mx:VBox&gt;
&lt;/s:Application&gt;</pre>
<p>As with the previous example,
be sure to clear your browser’s cache before running this example
a second time.</p>
</dd>
</dl>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d8b_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d8b_verapache"><!-- --></a>
<h2 class="topictitle2">RadioButton control </h2>
<div>
<p>The RadioButton and RadioButtonGroup controls are part
of both the MX and Spark component sets. While you can use the MX
controls in your application, it’s best to use the Spark controls
instead.</p>
<p>
The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/RadioButton.html" target="_blank">RadioButton</a> control
is a single choice in a set of mutually exclusive choices. A RadioButton
group is composed of two or more RadioButton controls with the same
group name. Only one member of the group can be selected at any
given time. Selecting an deselected group member deselects the currently
selected RadioButton control in the group. </p>
<p>While grouping RadioButton instances in a RadioButtonGroup is
optional, a group lets you do things like set a single event handler
on a group of buttons, rather than on each individual button. The
RadioButtonGroup tag goes in the <samp class="codeph">&lt;fx:Declarations&gt;</samp> tag.</p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d6f_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d6f_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a RadioButton control</h3>
<div>
<p>
You
define a RadioButton control in MXML by using the <samp class="codeph">&lt;s:RadioButton&gt;</samp> tag,
as the following example shows. Specify an <samp class="codeph">id</samp> value
if you intend to refer to a component elsewhere in your MXML, either
in another tag or in an ActionScript block. </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\button\RBSimple.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:VGroup&gt;
&lt;s:RadioButton groupName="cardtype"
id="americanExpress"
label="American Express"
width="150"/&gt;
&lt;s:RadioButton groupName="cardtype"
id="masterCard"
label="MasterCard"
width="150"/&gt;
&lt;s:RadioButton groupName="cardtype"
id="visa"
label="Visa"
width="150"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
<p>For each RadioButton control in the group, you can optionally
define an event listener for each button’s <samp class="codeph">click</samp> event.
When a user selects a RadioButton control, Flex calls the event
handler associated with that button’s <samp class="codeph">click</samp> event, as
the following code example shows: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\button\RBEvent.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import flash.events.Event;
private function handleAmEx(event:Event):void {
// Handle event.
myTA.text="Got Amex";
}
private function handleMC(event:Event):void {
// Handle event.
myTA.text="Got MasterCard";
}
private function handleVisa(event:Event):void {
// Handle event.
myTA.text="Got Visa";
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:VGroup&gt;
&lt;s:RadioButton groupName="cardtype"
id="americanExpress"
label="American Express"
width="150"
click="handleAmEx(event);"/&gt;
&lt;s:RadioButton groupName="cardtype"
id="masterCard"
label="MasterCard"
width="150"
click="handleMC(event);"/&gt;
&lt;s:RadioButton groupName="cardtype"
id="visa"
label="Visa"
width="150"
click="handleVisa(event);"/&gt;
&lt;s:TextArea id="myTA"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d8a_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d8a_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a group by using the &lt;s:RadioButtonGroup&gt;
tag</h3>
<div>
<p>
The
previous example created a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/RadioButton.html" target="_blank">RadioButton</a> group
by using the <samp class="codeph">groupName</samp> property of each RadioButton
control. To set functionality such as a single event handler on
the group, use the <samp class="codeph">&lt;s:RadioButtonGroup&gt;</samp> tag,
as the following example shows: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\button\RBGroupSimple.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.events.ItemClickEvent;
private function handleCard(event:ItemClickEvent):void {
//Print the value of the selected RadioButton in the Text Area
var cardValue:Object = cardtype.selectedValue;
myTA.text="You selected " + cardValue;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;fx:Declarations&gt;
&lt;s:RadioButtonGroup id="cardtype"
itemClick="handleCard(event);"/&gt;
&lt;/fx:Declarations&gt;
&lt;s:VGroup&gt;
&lt;s:RadioButton group="{cardtype}"
id="americanExpress"
label="American Express"
width="150"/&gt;
&lt;s:RadioButton group="{cardtype}"
id="masterCard"
label="MasterCard"
width="150"/&gt;
&lt;s:RadioButton group="{cardtype}"
id="visa"
label="Visa"
width="150"/&gt;
&lt;s:TextArea id="myTA"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
<p>In this example, the <samp class="codeph">id</samp> property of the <samp class="codeph">&lt;s:RadioButtonGroup&gt;</samp> tag
defines the group name. use data binding to associate the group
name with the <samp class="codeph">group</samp> property of each RadioButton
control. </p>
<p>The single <samp class="codeph">itemClick</samp> event listener is defined
for all buttons in the group. The <samp class="codeph">id</samp> property is
required when you use the <samp class="codeph">&lt;s:RadioButtonGroup&gt;</samp> tag.
The RadioButtonGroup is declared using the <samp class="codeph">&lt;fx:Declarations&gt;</samp> tag.</p>
<p>The <samp class="codeph">itemClick</samp> event listener for the group can
take a different action depending on which button was selected,
as the following example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\button\RBGroupEvent.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.controls.Alert;
import mx.events.ItemClickEvent;
private function handleCard(event:ItemClickEvent):void {
if (event.currentTarget.selectedValue == "AmEx") {
Alert.show("You selected American Express.");
} else if (event.currentTarget.selectedValue == "MC") {
Alert.show("You selected MasterCard.");
} else {
Alert.show("You selected Visa.");
}
}
]]&gt;
&lt;/fx:Script&gt;
&lt;fx:Declarations&gt;
&lt;s:RadioButtonGroup id="cardtype"
itemClick="handleCard(event);"/&gt;
&lt;/fx:Declarations&gt;
&lt;s:VGroup&gt;
&lt;s:RadioButton group="{cardtype}"
id="americanExpress"
value="AmEx"
label="American Express"
width="150"/&gt;
&lt;s:RadioButton group="{cardtype}"
id="masterCard"
value="MC"
label="MasterCard"
width="150"/&gt;
&lt;s:RadioButton group="{cardtype}"
id="visa"
value="Visa"
label="Visa"
width="150"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
<p>In the <samp class="codeph">itemClick</samp> event listener, the <samp class="codeph">selectedValue</samp> property
of the RadioButtonGroup control in the event object is set to the
value of the <samp class="codeph">value</samp> property of the selected RadioButton
control. If you omit the <samp class="codeph">value</samp> property, Flex sets
the <samp class="codeph">selectedValue</samp> property to the value of the <samp class="codeph">label</samp> property.</p>
<p>You can still define a <samp class="codeph">click</samp> event listener
for the individual buttons, even though you also define one for
the group.</p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7daa_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7daa_verapache"><!-- --></a>
<h3 class="topictitle3">RadioButton user interaction</h3>
<div>
<p>
If
a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/RadioButton.html" target="_blank">RadioButton</a> control
is enabled, when the user moves the pointer over an deselected RadioButton
control, the button displays its rollover appearance. When the user
clicks an deselected RadioButton control, the input focus moves to
the control and the button displays its false pressed appearance.
When the mouse button is released, the button displays the true
state appearance. The previously selected RadioButton control in
the group returns to its false state appearance. </p>
<p>If the user moves the pointer off the RadioButton control while
pressing the mouse button, the control’s appearance returns to the
false pressed state. The control retains input focus.</p>
<p>If a RadioButton control is not enabled, the RadioButton control
and RadioButton group display the disabled appearance, regardless
of user interaction. In the disabled state, all mouse or keyboard
interaction is ignored.</p>
<p>
The
RadioButton and <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/RadioButtonGroup.html" target="_blank">RadioButtonGroup</a> controls
have the following keyboard navigation features:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e7853">
<p>Key</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d139196e7859">
<p>Action</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e7853 ">
<p>Control+arrow keys</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e7859 ">
<p>Move focus among the buttons without selecting
a button.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e7853 ">
<p>Spacebar</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d139196e7859 ">
<p>Select a button. </p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d88_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d88_verapache"><!-- --></a>
<h2 class="topictitle2">HScrollBar and VScrollBar controls</h2>
<div>
<p>The HScrollBar and VScrollBar controls are part of both
the MX and Spark component sets. While you can use the MX controls
in your application, it’s best to use the Spark controls instead.</p>
<p>
The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/VScrollBar.html" target="_blank">VScrollBar</a> (vertical
ScrollBar) control and <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/HScrollBar.html" target="_blank">HScrollBar</a> (horizontal
ScrollBar) controls let the user control the portion of data that
is displayed when there is too much data to fit in the display area. </p>
<p>Although you can use the VScrollBar control and HScrollBar control
as stand-alone controls, they are usually combined with other components
as part of a custom component to provide scrolling functionality. </p>
<p>Scrollbar controls consists of four parts: two arrow buttons,
a track, and a thumb. The position of the thumb and display of the
buttons depends on the current state of the control. The width of
the control is equal to the largest width of its subcomponents (arrow
buttons, track, and thumb). Every subcomponent is centered in the
scroll bar.</p>
<p>The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/supportClasses/ScrollBarBase.html" target="_blank">ScrollBarBase</a> control
uses four parameters to calculate its display state:</p>
<ul>
<li>
<p>Minimum range value</p>
</li>
<li>
<p>Maximum range value</p>
</li>
<li>
<p>Current position value; must be within the minimum and maximum
range values</p>
</li>
<li>
<p>Viewport size; represents the number of items in the range
that can be displayed at once and must be equal to or less than
the range</p>
</li>
</ul>
<p>For more information on using these controls with Spark containers,
see <a href="flx_containers_intro_cn.html#WSC5AF600B-9793-4dfd-AD9D-B9FC098869A8_verapache">Scrolling Spark
containers</a>.</p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7f91_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7f91_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a scrollbar control</h3>
<div>
<p>
Define
a scrollbar control in MXML by using the <samp class="codeph">&lt;s:VScrollBar&gt;</samp> tag
for a vertical scrollbar or the <samp class="codeph">&lt;s:HScrollBar&gt;</samp> tag
for a horizontal scrollbar, as the following example shows. Specify
an <samp class="codeph">id</samp> value if you intend to refer to a component
elsewhere in your MXML, either in another tag or in an ActionScript block. </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\bar\SBarSimple.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.events.ScrollEvent;
// Event handler function to display the scroll location.
private function myScroll():void {
showPosition.text = "VScrollBar properties summary:" + '\n' +
"------------------------------------" + '\n' +
"Current scroll position: " +
bar.value + '\n' +
"The maximum scroll position: " +
bar.maximum + '\n' +
"The minimum scroll position: " +
bar.minimum;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:VGroup&gt;
&lt;s:Label
width="100%"
text="Click on the ScrollBar control to view its properties."/&gt;
&lt;s:VScrollBar id="bar"
height="100%"
minimum="0"
maximum="{this.width - 20}"
stepSize="50"
pageSize="100"
repeatDelay="1000"
repeatInterval="500"
change="myScroll();"/&gt;
&lt;s:TextArea id="showPosition"
height="100%"
width="100%" /&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7f90_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7f90_verapache"><!-- --></a>
<h3 class="topictitle3">Sizing a scrollbar control</h3>
<div>
<p>
The
scrollbar control does not display correctly if it is sized smaller
than the height of the Up arrow and Down arrow buttons. There is
no error checking for this condition. It’s best to hide the scrollbar
control in such a condition. If there is not enough room for the
thumb, the thumb is made invisible. </p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7f8f_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7f8f_verapache"><!-- --></a>
<h3 class="topictitle3">User interaction</h3>
<div>
<p>
Use
the mouse to click the various portions of the scrollbar control,
which dispatches events to listeners. The object listening to the
scrollbar control is responsible for updating the portion of data
displayed. The scrollbar control updates itself to represent the
new state after the action has taken place. </p>
</div>
</div>
</div>
<div class="nested1" id="WSb04c7610c3432839-13869d09121418556f1-7ffc_verapache"><a name="WSb04c7610c3432839-13869d09121418556f1-7ffc_verapache"><!-- --></a>
<h2 class="topictitle2">Scroller control</h2>
<div>
<p>The Scroller control is part of the Spark component set.
There is no MX equivalent. </p>
<p>The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/Scroller.html" target="_blank">Scroller</a> control
contains a pair of scroll bars and a viewport. A viewport displays
a rectangular subset of the area of a component, rather than displaying the
entire component. You can use the Scroller control to make any container that
implements the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/core/IViewport.html" target="_blank">IViewport</a> interface,
such as Group, scrollable.</p>
<p>The scroll bars control the viewport's vertical and horizontal
scroll position. They reflect the viewport's actual size and content
size. Scroll bars are displayed according to the Scroller's vertical
and horizontal scroll policy properties. By default, the policy
is set to <samp class="codeph">"auto"</samp>. This value indicates that scroll
bars are displayed when the content within a viewport is larger
than the actual size of the viewport. </p>
<p>For more information on using this control with Spark containers,
see <a href="flx_containers_intro_cn.html#WSC5AF600B-9793-4dfd-AD9D-B9FC098869A8_verapache">Scrolling Spark
containers</a>.</p>
</div>
<div class="nested2" id="WSc78f87379113c38b3a63e0312219803011-8000_verapache"><a name="WSc78f87379113c38b3a63e0312219803011-8000_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a Scroller control</h3>
<div>
<p>You define a Scroller control in MXML by using the <samp class="codeph">&lt;s:Scroller&gt;</samp> tag.
Specify an <samp class="codeph">id</samp> value if you intend to refer to a
component elsewhere in your MXML, either in another tag or in an
ActionScript block. </p>
<p>In the following example, the Group container <samp class="codeph">myGroup</samp> is
the viewport for this scroller. The content in the viewport is the
loaded image. The layout of the application is controlled by the
VGroup container.</p>
<div class="p">
<pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- controls\Scroller\ScrollerImage.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"
width="450" height="450"&gt;
&lt;s:VGroup paddingLeft="10" paddingTop="10"&gt;
&lt;s:Scroller width="400" height="400"&gt;
&lt;s:Group id="myGroup" &gt;
&lt;s:Image id="loader1"
source="@Embed(source='../assets/strawberries.jpg')"/&gt;
&lt;/s:Group&gt;
&lt;/s:Scroller&gt;
&lt;s:Label
fontSize="14" fontFamily="Arial"
text= "Scroll to see fresh summer strawberries"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested2" id="WSc78f87379113c38b3a63e0312219803011-7fff_verapache"><a name="WSc78f87379113c38b3a63e0312219803011-7fff_verapache"><!-- --></a>
<h3 class="topictitle3">Sizing a Scroller control</h3>
<div>
<p>You can size the width and height of the Scroller control
directly or size the viewport container. The VScrollBar and HScrollBar
classes bind to the viewport's scroll position and actual and content
sizes. </p>
</div>
</div>
<div class="nested2" id="WSc78f87379113c38b3a63e0312219803011-7ffe_verapache"><a name="WSc78f87379113c38b3a63e0312219803011-7ffe_verapache"><!-- --></a>
<h3 class="topictitle3">Skinning a Scroller control</h3>
<div>
<p>The Scroller skin provides scroll bars and manages layout
according to the verticalScrollPolicy and horizontalScrollPolicy
properties in the Scroller class. </p>
<p>The Scroller skin layout cannot be changed because it must handle
the vertical and horizontal scroll policies. Scroller skins can
only provide replacement scroll bars.</p>
</div>
</div>
</div>
<div class="nested1" id="WSb04c7610c3432839-13869d09121418556f1-7ffb_verapache"><a name="WSb04c7610c3432839-13869d09121418556f1-7ffb_verapache"><!-- --></a>
<h2 class="topictitle2">Spinner control</h2>
<div>
<p>The Spinner control is part of the Spark component set.
There is no MX equivalent. </p>
<p>The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/Spinner.html" target="_blank">Spinner</a> control
lets users step through an allowed set of values and select a value
by clicking up or down buttons. It is a base class for the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/NumericStepper.html" target="_blank">NumericStepper</a> control.
You could use Spinner to create controls with a different input
or display than the standard text input field used in NumericStepper.
Another possibility is to use a Spinner control to control tabs
or a menu by assigning different values to tabs or menu items. </p>
</div>
<div class="nested2" id="WSc78f87379113c38b14aa9d7012219b1da04-8000_verapache"><a name="WSc78f87379113c38b14aa9d7012219b1da04-8000_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a Spinner control</h3>
<div>
<p>You define a Spinner control in MXML by using the <samp class="codeph">&lt;s:Spinner&gt;</samp> tag.
Specify an <samp class="codeph">id</samp> value if you intend to refer to a
component elsewhere in your MXML, either in another tag or in an
ActionScript block. </p>
<p>The following example shows a Spinner control that allows wrapping
back to the minimum value once the maximum value is reached. The <samp class="codeph">allowValueWrap</samp> property
is false by default. The <samp class="codeph">snapInterval</samp> property
is set to 2. When you click the up (or increment) button for the
first time, the value of the Spinner control is set to 4. </p>
<div class="p">
<pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- \controls\spinner\SpinnerSimple.mxml--&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
private function onClickHandler(event:Event):void {
message.text += "You selected "+ mySpinner.value + "\n";
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:VGroup paddingTop="10" paddingLeft="10"&gt;
&lt;s:HGroup&gt;
&lt;s:Label text="Use the arrows to change value"/&gt;
&lt;s:Spinner id="mySpinner"
click="onClickHandler(event);"
minimum="2"
maximum="20"
snapInterval="2"
allowValueWrap="true"/&gt;
&lt;/s:HGroup&gt;
&lt;s:TextArea id="message"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7f9c_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7f9c_verapache"><!-- --></a>
<h2 class="topictitle2">SWFLoader control</h2>
<div>
<p>The SWFLoader control is part of the MX component set.
There is no Spark equivalent of this control. </p>
<p>
The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/SWFLoader.html" target="_blank">SWFLoader</a> control
lets you load one Flex application into another Flex application
as a SWF file. It has properties that let you scale its contents.
It can also resize itself to fit the size of its contents. By default,
content is scaled to fit the size of the SWFLoader control. The
SWFLoader control can also load content on demand programmatically,
and monitor the progress of a load operation.</p>
<p>When loading an applications into a main application, you should
be aware of the following factors:</p>
<div class="p">
<dl>
<dt class="dlterm">Versioning</dt>
<dd>
<p>SWF files produced with earlier versions of Flex or ActionScript
may not work properly when loaded with the SWFLoader control. You
can use the <samp class="codeph">loadForCompatibility</samp> property of the
SWFLoader control to ensure that applications loaded into a main
application works, even if the applications were compiled with a
different version of the compiler.</p>
</dd>
<dt class="dlterm">Security</dt>
<dd>
<p>When loading applications, especially ones that were created
by a third-party, you should consider loading them into their own
SecurityDomain. While this places additional limitations on the
level of interoperability between the main application and the application,
it ensures that the content is safe from attack.</p>
</dd>
</dl>
</div>
<p>For more information about creating and loading applications,
see <a href="flx_loading_applications_la.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d14_verapache">Developing and
loading sub-applications</a>.</p>
<p>
The SWFLoader
control also lets you load the contents of a GIF, JPEG, PNG, SVG, or
SWF file into your application, where the SWF file does not contain
a Flex application, or a ByteArray representing a SWF, GIF, JPEG,
or PNG. </p>
<p>For more information, see <a href="flx_controls_ctr.html#WSc5cd04c102ae3e97-33ad5caa12c719dc7c8-8000_verapache">Image
control</a>. For more information on using the SWFLoader control
to load a Flex application, see <a href="flx_controls_ctr.html#WS2db454920e96a9e51e63e3d11c0bf69084-7f02_verapache">Externalizing
application classes</a>
<em>.</em>
</p>
<div class="note"><span class="notetitle">Note:</span> Flex also includes the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/Image.html" target="_blank">Image</a> control
for loading GIF, JPEG, PNG, SVG, or SWF files. You typically use
the Image control for loading static graphic files and SWF files, and
use the SWFLoader control for loading Flex applications as SWF files.
The Image control is also designed to be used in custom cell renderers
and item editors. </div>
<p>A SWFLoader control cannot receive focus. However, content loaded
into the SWFLoader control can accept focus and have its own focus
interactions. </p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7efa_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7efa_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a SWFLoader control</h3>
<div>
<p>
You
define a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/SWFLoader.html" target="_blank">SWFLoader</a> control
in MXML by using the <samp class="codeph">&lt;mx:SWFLoader&gt;</samp> tag, as
the following example shows. Specify an <samp class="codeph">id</samp> value
if you intend to refer to a component elsewhere in your MXML, either
in another tag or in an ActionScript block: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\swfloader\SWFLoaderSimple.mxml--&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:VGroup&gt;
&lt;mx:SWFLoader id="loader1" source="FlexApp.swf"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
<p>Like the Image control, you can also use the Embed statement
with the SWFLoader control to embed the image in your application,
as the following example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\swfloader\SWFLoaderSimpleEmbed.mxml--&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;mx:SWFLoader id="loader1" source="@Embed(source='FlexApp.swf')"/&gt;
&lt;/s:Application&gt;</pre>
<p>When using the SWFLoader control with an SVG file, you can only
load it by using an Embed statement; you cannot load an SVG file
at run time. For more information about embedding resources, see
the description for the Image control at <a href="flx_controls_ctr.html#WSc5cd04c102ae3e97-33ad5caa12c719dc7c8-8000_verapache">Image
control</a>, and <a href="flx_embed_em.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fce_verapache">Embedding
assets</a>.</p>
<p>This technique works well with SWF files that add graphics or
animations to an application but are not intended to have a large
amount of user interaction. If you import SWF files that require
a large amount of user interaction, you should build them as custom
components. </p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7f91_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7f91_verapache"><!-- --></a>
<h3 class="topictitle3">Interacting with a loaded Flex
application</h3>
<div>
<p>The following example, in the file FlexApp.mxml, shows
a simple Flex application that defines two Label controls, a variable,
and a method to modify the variable:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\swfloader\FlexApp.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"
height="100" width="200"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
[Bindable]
public var varOne:String = "This is a public variable.";
public function setVarOne(newText:String):void {
varOne=newText;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:VGroup&gt;
&lt;s:Label id="lblOne" text="I am here."/&gt;
&lt;s:Label text="{varOne}"/&gt;
&lt;s:Button label="Nested Button" click="setVarOne('Nested button pressed.');"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
<p>You compile this example into the file FlexApp.SWF, and then
use the SWFLoader control to load it into another Flex application,
as the following example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\swfloader\SWFLoaderInteract.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"
backgroundColor="gray"
height="200"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.managers.SystemManager;
[Bindable]
public var loadedSM:SystemManager;
// Initialize variables with information from
// the loaded application.
private function initNestedAppProps():void {
loadedSM = SystemManager(myLoader.content);
// Enable the buttons after the application loads.
b1.enabled = true;
b2.enabled = true;
b3.enabled = true;
}
// Update the Label control in the outer application
// from the Label control in the loaded application.
public function updateLabel():void {
lbl.text=loadedSM.application["lblOne"].text;
}
// Write to the Label control in the loaded application.
public function updateNestedLabels():void {
loadedSM.application["lblOne"].text = "I was just updated.";
loadedSM.application["varOne"] = "I was just updated.";
}
// Write to the varOne variable in the loaded application
// using the setVarOne() method of the loaded application.
public function updateNestedVarOne():void {
loadedSM.application["setVarOne"]("Updated varOne!");
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:VGroup&gt;
&lt;s:Label id="lbl"/&gt;
&lt;mx:SWFLoader id="myLoader" width="300"
source="FlexApp.swf"
complete="initNestedAppProps();"/&gt;
&lt;s:Button id="b1" label="Update Label Control in Outer Application"
click="updateLabel();"
enabled="false"/&gt;
&lt;s:Button id="b2" label="Update Nested Controls"
click="updateNestedLabels();"
enabled="false"/&gt;
&lt;s:Button id="b3" label="Update Nested varOne"
click="updateNestedVarOne();"
enabled="false"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
<p>In this example, the FlexApp.swf file is in the same directory
as the main application. Modify the path to the file appropriately
for your application.</p>
<p>Notice that this application loads the SWF file at run time;
it does not embed it. For information on embedding a Flex application
by using the SWFLoader tag, see <a href="flx_embed_em.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fce_verapache">Embedding
assets</a>. </p>
<p>You use the <samp class="codeph">complete</samp> event of the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/SWFLoader.html" target="_blank">SWFLoader</a> control
to initialize a variable with a reference to the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/managers/SystemManager.html" target="_blank">SystemManager</a> object
for the loaded Flex application.</p>
<p>When a user clicks the first <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/Button.html" target="_blank">Button</a> control
in the outer application, Flex copies the text from the Label control
in the loaded application to the Label control in the outer application. </p>
<p>When a user clicks the second Button control, Flex writes the
text to the Label control and to the <em>varOne</em> variable defined
in the loaded application. </p>
<p>When a user clicks the third Button control, the <em>setVarOne()</em> method
of the loaded application writes to the <em>varOne</em> variable defined
in the loaded application. </p>
<div class="p">
<div class="note"><span class="notetitle">Note:</span> When working with loaded SWF files, consider using modules
rather than the SWFLoader control. For more information on creating
modular applications, see <a href="flx_modular_md.html#WS2db454920e96a9e51e63e3d11c0bf69084-7f22_verapache">Modular
applications</a>. </div>
</div>
<p>The level of interoperability between a main application and
a loaded application depends on the type of loaded application:</p>
<div class="p">
<dl>
<dt class="dlterm">Sandboxed</dt>
<dd>
<p>Sandboxed applications are loaded into their own security domains,
and can be multi-versioned. Using sandboxed applications is the recommended
practice for third-party applications. In addition, if your loaded applications
use RPC or DataServices-related functionality, you should load them as
sandboxed. For more information, see <a href="flx_loading_applications_la.html#WS2db454920e96a9e51e63e3d11c0bf69084-7f0d_verapache">Developing
sandboxed applications</a>.</p>
</dd>
<dt class="dlterm">Multi-versioned</dt>
<dd>
<p>Multi-versioned applications are those that can be compiled with
different versions of the Flex framework than the main application
that loads them. Their interoperability with the main application
and other loaded applications is more limited than single-versioned
applications. For more information, see <a href="flx_loading_applications_la.html#WS2db454920e96a9e51e63e3d11c0bf69084-7f0c_verapache">Developing
multi-versioned applications</a>.</p>
</dd>
<dt class="dlterm">Single-versioned</dt>
<dd>
<p>Single-versioned applications are applications that are guaranteed
to have been compiled with the same version of the compiler as the main
application. They have the greatest level of interoperability with
the main application, but they also require that you have complete
control over the source of the loaded applications. For more information,
see <a href="flx_loading_applications_la.html#WS2db454920e96a9e51e63e3d11c0bf69084-7f0b_verapache">Creating
and loading sub-applications</a>.</p>
</dd>
</dl>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7f02_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7f02_verapache"><!-- --></a>
<h3 class="topictitle3">Externalizing application classes</h3>
<div>
<p>To reduce the size of the applications that you load by
using the SWFLoader control, you can instruct the loaded application
to externalize framework classes that are also included by the loading
application. The result is that the loaded application is smaller
because it only includes the classes it requires, while the framework
code and other dependencies are included in the loading application. </p>
<p>To externalize framework classes, you generate a linker report
from the loading application by using <samp class="codeph">link-report</samp> option
to the mxmlc command. You then use the <samp class="codeph">load-externs</samp> option
to the mxmlc compiler to specify this report when you compile the
loaded application. </p>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7f02_verapache__WS2db454920e96a9e51e63e3d11c0bf63b33-7fbe_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7f02_verapache__WS2db454920e96a9e51e63e3d11c0bf63b33-7fbe_verapache"><!-- --></a><h4 class="sectiontitle">Externalize
framework classes</h4>
<ol>
<li>
<p>Generate the linker report for
the loading application:</p>
<pre class="codeblock"> mxmlc -link-report=report.xml MyApplication.mxml</pre>
</li>
<li>
<p>Compile the loaded application by using the link report:</p>
<pre class="codeblock"> mxmlc -load-externs=report.xml MyLoadedApplication.mxml</pre>
</li>
<li>
<p>Compile the loading application:</p>
<pre class="codeblock"> mxmlc MyApplication.mxml</pre>
</li>
</ol>
<div class="note"><span class="notetitle">Note:</span> If you externalize the loaded application’s dependencies
by using the <samp class="codeph">load-externs</samp> option, your loaded application
might not be compatible with future versions of Flex. Therefore,
you might be required to recompile the application. To ensure that
a future Flex application can load your application, compile that
module with all the classes it requires. </div>
<p>For more information,
see <a href="flx_compilers_cpl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ffd_verapache">Flex
compilers</a>.</p>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fbd_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fbd_verapache"><!-- --></a>
<h3 class="topictitle3">Sizing a SWFLoader control</h3>
<div>
<p>
You
use the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/SWFLoader.html" target="_blank">SWFLoader</a> control’s <samp class="codeph">scaleContent</samp> property
to control the sizing behavior of the SWFLoader control. When the <samp class="codeph">scaleContent</samp> property
is set to <samp class="codeph">true</samp>, Flex scales the content to fit
within the bounds of the control. However, images will still retain
their aspect ratio by default. </p>
</div>
</div>
<div class="nested2" id="WSda78ed3a750d6b8f6914a86d1250e4520e4-8000_verapache"><a name="WSda78ed3a750d6b8f6914a86d1250e4520e4-8000_verapache"><!-- --></a>
<h3 class="topictitle3">Styling loaded applications</h3>
<div>
<p>When you use the SWFLoader control to load a loaded application,
the loaded application uses the same rules for applying styles as
modules.</p>
<p>For more information, see <a href="flx_modular_md.html#WSda78ed3a750d6b8f1b97f82d12508050aa0-8000_verapache">Using
styles with modules</a>.</p>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d86_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d86_verapache"><!-- --></a>
<h2 class="topictitle2">MX TabBar control</h2>
<div>
<p>The TabBar control is part of both the MX and Spark component
sets. While you can still use the MX control in your application,
it’s best to use the Spark control instead. For information on Spark
TabBar, see <a href="flx_spark_dpcontrols_sdp.html#WSc2368ca491e3ff92-59bf082612135c9e688-8000_verapache">Spark
ButtonBar and TabBar controls</a>.</p>
<p>
A <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/TabBar.html" target="_blank">TabBar</a> control
defines a horizontal or vertical row of tabs. The following shows an
example of a TabBar control: </p>
<div class="figborder">
<img src="images/ctr_tabbar.png"/>
</div>
<p>As with the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/LinkBar.html" target="_blank">LinkBar</a> control,
you can use a TabBar control to control the active child container
of a ViewStack container. The syntax for using a TabBar control
to control the active child of a ViewStack container is the same
as for a LinkBar control. For an example, see <a href="flx_navigators_na.html#WS2db454920e96a9e51e63e3d11c0bf69084-7e4d_verapache">MX
ViewStack navigator container</a>. </p>
<p>While a TabBar control is similar to a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/containers/TabNavigator.html" target="_blank">TabNavigator</a> container,
it does not have any children. For example, you use the tabs of
a TabNavigator container to select its visible child container.
You can use a TabBar control to set the visible contents of a single
container to make that container’s children visible or invisible
based on the selected tab. </p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fe6_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fe6_verapache"><!-- --></a>
<h3 class="topictitle3">Creating an MX TabBar control</h3>
<div>
<p>
You
use the <samp class="codeph">&lt;mx:TabBar&gt;</samp> tag to define a TabBar
control in MXML. Specify an <samp class="codeph">id</samp> value if you intend
to refer to a component elsewhere in your MXML, either in another
tag or in an ActionScript block.</p>
<p>You specify the data for the TabBar control by using the <samp class="codeph">&lt;mx:dataProvider&gt;</samp> child
tag of the <samp class="codeph">&lt;mx:TabBar&gt;</samp> tag. The <samp class="codeph">&lt;mx:dataProvider&gt;</samp> tag
lets you specify data in several different ways. In the simplest
case for creating a TabBar control, you use the <samp class="codeph">&lt;mx:dataProvider&gt;</samp> and <samp class="codeph">&lt;fx:String&gt;</samp> tags
to specify the text for each tab, as the following example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\bar\TBarSimple.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;mx:TabBar&gt;
&lt;mx:dataProvider&gt;
&lt;fx:String&gt;Alabama&lt;/fx:String&gt;
&lt;fx:String&gt;Alaska&lt;/fx:String&gt;
&lt;fx:String&gt;Arkansas&lt;/fx:String&gt;
&lt;/mx:dataProvider&gt;
&lt;/mx:TabBar&gt;
&lt;/s:Application&gt; </pre>
<p>The <samp class="codeph">&lt;fx:String&gt;</samp> tags define the text for
each tab in the TabBar control. </p>
<p>You can also use the <samp class="codeph">&lt;fx:Object&gt;</samp> tag to
define the entries as an array of objects, where each object contains
a <samp class="codeph">label</samp> property and an associated data value,
as the following example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\bar\TBarObject.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;mx:TabBar&gt;
&lt;mx:dataProvider&gt;
&lt;fx:Object label="Alabama" data="Montgomery"/&gt;
&lt;fx:Object label="Alaska" data="Juneau"/&gt;
&lt;fx:Object label="Arkansas" data="Little Rock"/&gt;
&lt;/mx:dataProvider&gt;
&lt;/mx:TabBar&gt;
&lt;/s:Application&gt; </pre>
<p>The <samp class="codeph">label</samp> property contains the state name and
the <samp class="codeph">data</samp> property contains the name of its capital.
The <samp class="codeph">data</samp> property lets you associate a data value
with the text label. For example, the <samp class="codeph">label</samp> text
could be the name of a color, and the associated data value could
be the numeric representation of that color. </p>
<p>By default, Flex uses the value of the <samp class="codeph">label</samp> property
to define the tab text. If the object does not contain a <samp class="codeph">label</samp> property,
you can use the <samp class="codeph">labelField</samp> property of the TabBar
control to specify the property name containing the tab text, as
the following example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\bar\TBarLabel.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;mx:TabBar labelField="state"&gt;
&lt;mx:dataProvider&gt;
&lt;fx:Object state="Alabama" data="Montgomery"/&gt;
&lt;fx:Object state="Alaska" data="Juneau"/&gt;
&lt;fx:Object state="Arkansas" data="Little Rock"/&gt;
&lt;/mx:dataProvider&gt;
&lt;/mx:TabBar&gt;
&lt;/s:Application&gt; </pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fe5_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fe5_verapache"><!-- --></a>
<h3 class="topictitle3">Passing data to an MX TabBar control </h3>
<div>
<p>
Flex
lets you populate a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/TabBar.html" target="_blank">TabBar</a> control
from an ActionScript variable definition or from a Flex data model.
When you use a variable, you can define it to contain one of the
following: </p>
<ul>
<li>
<p>A label (string)</p>
</li>
<li>
<p>A label (string) paired with data (scalar value or object)</p>
</li>
</ul>
<p>The following example populates a TabBar control from a variable:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\bar\TBarVar.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
[Bindable]
private var STATE_ARRAY:ArrayCollection = new ArrayCollection([
{label:"Alabama", data:"Montgomery"},
{label:"Alaska", data:"Juneau"},
{label:"Arkansas", data:"LittleRock"}
]);
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:TabBar &gt;
&lt;mx:dataProvider&gt;
{STATE_ARRAY}
&lt;/mx:dataProvider&gt;
&lt;/mx:TabBar&gt;
&lt;/s:Application&gt; </pre>
<p>You can also bind a Flex data model to the <samp class="codeph">dataProvider</samp> property.
For more information on using data models, see <a href="flx_datamodels_dm.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ff3_verapache">Storing
data</a>. </p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fe4_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fe4_verapache"><!-- --></a>
<h3 class="topictitle3">Handling MX TabBar control events</h3>
<div>
<p>
The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/TabBar.html" target="_blank">TabBar</a> control
defines an item<samp class="codeph">Click</samp> event that is broadcast when
a user selects a tab. The event object contains the following properties: </p>
<ul>
<li>
<p>
<samp class="codeph">label</samp> String containing the label of
the selected tab. </p>
</li>
<li>
<p>
<samp class="codeph">index</samp> Number containing the index of the
selected tab. Indexes are numbered from 0 to <em>n</em> - 1, where <em>n</em> is
the total number of tabs. The default value is 0, corresponding
to the first tab.</p>
</li>
</ul>
<p>The following example code shows a handler for the <samp class="codeph">itemClick </samp>event
for this TabBar control: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\bar\TBarEvent.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.events.ItemClickEvent;
import mx.controls.TabBar;
import mx.collections.ArrayCollection;
[Bindable]
private var STATE_ARRAY:ArrayCollection = new ArrayCollection([
{label:"Alabama", data:"Montgomery"},
{label:"Alaska", data:"Juneau"},
{label:"Arkansas", data:"LittleRock"}
]);
private function clickEvt(event:ItemClickEvent):void {
// Access target TabBar control.
var targetComp:TabBar = TabBar(event.currentTarget);
forClick.text="label is: " + event.label + "\nindex is: " +
event.index + "\ncapital is: " +
targetComp.dataProvider[event.index].data;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:VGroup&gt;
&lt;mx:TabBar id="myTB" itemClick="clickEvt(event);"&gt;
&lt;mx:dataProvider&gt;
{STATE_ARRAY}
&lt;/mx:dataProvider&gt;
&lt;/mx:TabBar&gt;
&lt;s:TextArea id="forClick" width="250" height="100"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt; </pre>
<p>In this example, every <samp class="codeph">itemClick</samp> event updates
the TextArea control with the tab label, selected index, and the
selected data from the TabBar control’s <samp class="codeph">dataProvider</samp> Array.</p>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d7f_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d7f_verapache"><!-- --></a>
<h2 class="topictitle2">MX VideoDisplay control</h2>
<div>
<p>The VideoDisplay control is part of both the MX and Spark
component sets. While you can still use the MX control in your application,
it’s best to use the Spark control instead. Continue to use the
MX VideoDisplay control to work with cue points or stream live video
from a local camera using the <samp class="codeph">attachCamera()</samp> method
of the Camera class.</p>
<p>
Flex supports
the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/VideoDisplay.html" target="_blank">VideoDisplay</a> control
to incorporate streaming media into Flex applications. Flex supports
the Flash Video File (FLV) file format with this control. </p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fb0_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fb0_verapache"><!-- --></a>
<h3 class="topictitle3">Using media in Flex</h3>
<div>
<p>
Media,
such as movie and audio clips, are used more and more to provide
information to web users. As a result, you need to provide users
with a way to stream the media, and then control it. The following
examples are usage scenarios for media controls: </p>
<ul>
<li>
<p>Showing a video message from the CEO of your company</p>
</li>
<li>
<p>Streaming movies or movie previews</p>
</li>
<li>
<p>Streaming songs or song snippets</p>
</li>
<li>
<p>Providing learning material in the form of media</p>
</li>
</ul>
<p>
The streaming VideoDisplay control
makes it easy to incorporate streaming media into Flash presentations.
Flex supports the Flash Video File (FLV) file format with this control.
You can use this control with video and audio data. When you use
the VideoDisplay control by itself, your application provides no
mechanism for its users to control the media files.</p>
<div class="note"><span class="notetitle">Note:</span> The VideoDisplay control does not support scan
forward and scan backward functionality. Also, the VideoDisplay
control does not support accessibility or styles.</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7faf_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7faf_verapache"><!-- --></a>
<h3 class="topictitle3">About the MX VideoDisplay control</h3>
<div>
<p>
Flex creates an MX <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/VideoDisplay.html" target="_blank">VideoDisplay</a> control
with no visible user interface. It is simply a control to hold and
play media. </p>
<div class="note"><span class="notetitle">Note:</span> The user cannot see anything unless some video
media is playing.</div>
<p>The <samp class="codeph">playheadTime</samp> property of the control holds
the current position of the playhead in the video file, measured
in seconds. Most events dispatched by the control include the playhead
position in the associated event object. One use of the playhead
position is to dispatch an event when the video file reaches a specific
position. For more information, see <a href="flx_controls_ctr.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d5a_verapache">Adding
a cue point to the MX VideoDisplay control</a>.</p>
<p>The VideoDisplay control also supports the <samp class="codeph">volume</samp> property.
This property takes a value from 0.0 to 1.00; 0.0 is mute and 1.00
is the maximum volume. The default value is 0.75.</p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fae_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fae_verapache"><!-- --></a>
<h3 class="topictitle3">Setting the size of the MX VideoDisplay
control</h3>
<div>
<p>The appearance of any video media playing in a VideoDisplay
control is affected by the following properties:</p>
<ul>
<li>
<p>
<samp class="codeph">maintainAspectRatio </samp>
</p>
</li>
<li>
<p>
<samp class="codeph">height </samp>
</p>
</li>
<li>
<p>
<samp class="codeph">width </samp>
</p>
</li>
</ul>
<p>When you set <samp class="codeph">maintainAspectRatio</samp> to <samp class="codeph">true</samp> (the
default), the control adjusts the size of the playing media after
the control size has been set. The size of the media is set to maintain
its aspect ratio. </p>
<p>If you omit both <samp class="codeph">width</samp> and <samp class="codeph">height</samp> properties
for the control, Flex makes the control the size of the playing
media. If you specify only one property, and the <samp class="codeph">maintainAspectRatio</samp> property
is <samp class="codeph">false</samp>, the size of the playing media determines
the value of the other property. If the <samp class="codeph">maintainAspectRatio</samp> property
is <samp class="codeph">true</samp>, the media retains its aspect ratio when
resizing. </p>
<p>The following example creates a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/VideoDisplay.html" target="_blank">VideoDisplay</a> control:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\videodisplay\VideoDisplaySimple.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;mx:VBox&gt;
&lt;mx:VideoDisplay
source="../assets/MyVideo.flv"
height="250"
width="250"
/&gt;
&lt;/mx:VBox&gt;
&lt;/s:Application&gt;</pre>
<p>
By default,
Flex sizes the VideoDisplay control to the size of the media. If
you specify the <samp class="codeph">width</samp> or <samp class="codeph">height</samp> property
of the control, and either is smaller than the media’s dimensions,
Flex does not change the size of the component. Instead, Flex sizes
the media to fit within the component. If the control’s playback area
is smaller than the default size of the media, Flex shrinks the
media to fit inside the control. </p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fad_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fad_verapache"><!-- --></a>
<h3 class="topictitle3">Using methods of the MX VideoDisplay
control</h3>
<div>
<p>You can use the following methods of the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/VideoDisplay.html" target="_blank">VideoDisplay</a> control
in your application: <samp class="codeph">close()</samp>, <samp class="codeph">load()</samp>, <samp class="codeph">pause()</samp>, <samp class="codeph">play()</samp>,
and <samp class="codeph">stop()</samp>. The following example uses the <samp class="codeph">pause()</samp> and <samp class="codeph">play()</samp> methods
in event listener for two Button controls to pause or play an FLV
file:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\videodisplay\VideoDisplayStopPlay.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"
creationComplete="myVid.pause();"&gt;
&lt;mx:VBox&gt;
&lt;mx:VideoDisplay id="myVid"
source="../assets/MyVideo.flv"
height="250"
width="250"
/&gt;
&lt;mx:HBox&gt;
&lt;mx:Button label="||" click="myVid.pause();"/&gt;
&lt;mx:Button label="&amp;gt;" click="myVid.play();"/&gt;
&lt;/mx:HBox&gt;
&lt;/mx:VBox&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d5a_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d5a_verapache"><!-- --></a>
<h3 class="topictitle3">Adding a cue point to the MX VideoDisplay
control</h3>
<div>
<p>
You can use cue points to trigger events
when the playback of your media reaches a specified location. To
use cue points, you set the <samp class="codeph">cuePointManagerClass</samp> property
to mx.controls.videoClasses.CuePointManager to enable cue point
management, and then pass an Array of cue points to the <samp class="codeph">cuePoints</samp> property
of the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/VideoDisplay.html" target="_blank">VideoDisplay</a> control.
Each element of the Array contains two fields. The <samp class="codeph">name</samp> field
contains an arbitrary name of the cue point. The <samp class="codeph">time</samp> field
contains the playhead location, in seconds, of the VideoDisplay
control with which the cue point is associated. </p>
<p>When the playhead of the VideoDisplay control reaches a cue point,
it dispatches a <samp class="codeph">cuePoint</samp> event, as the following
example shows: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\videodisplay\VideoDisplayCP.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"
height="450"
creationComplete="myVid.pause();"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.events.CuePointEvent;
import mx.controls.videoClasses.CuePointManager;
private function cpHandler(event:CuePointEvent):void {
cp.text+="Got to " + event.cuePointName + " cuepoint @ " +
String(event.cuePointTime) + " seconds in.\n";
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:VBox&gt;
&lt;mx:VideoDisplay id="myVid"
source="../assets/MyVideo.flv"
cuePointManagerClass="mx.controls.videoClasses.CuePointManager"
cuePoint="cpHandler(event);"
height="250"
width="250"
&gt;
&lt;mx:cuePoints&gt;
&lt;fx:Object name="first" time="5"/&gt;
&lt;fx:Object name="second" time="10"/&gt;
&lt;/mx:cuePoints&gt;
&lt;/mx:VideoDisplay&gt;
&lt;mx:Label text="{myVid.playheadTime}"/&gt;
&lt;mx:TextArea id="cp" height="100" width="250"/&gt;
&lt;/mx:VBox&gt;
&lt;mx:HBox&gt;
&lt;mx:Button label="||" click="myVid.pause();"/&gt;
&lt;mx:Button label="&amp;gt;" click="myVid.play();"/&gt;
&lt;/mx:HBox&gt;
&lt;/s:Application&gt;</pre>
<p>In this example, the event listener writes a String to the TextArea
control when the control reaches a cue point. The String contains
the name and time of the cue point. </p>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d5a_verapache__WS2db454920e96a9e51e63e3d11c0bf63b33-7fab_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d5a_verapache__WS2db454920e96a9e51e63e3d11c0bf63b33-7fab_verapache"><!-- --></a><h4 class="sectiontitle">Adding
a cue point by using the CuePointManager class</h4>
<p>You can
set cue points for the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/VideoDisplay.html" target="_blank">VideoDisplay</a> control
by using the <samp class="codeph">cuePointManager</samp> property. This property
is of type <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/videoClasses/CuePointManager.html" target="_blank">CuePointManager</a>,
where the CuePointManager class defines methods that you use to
programmatically manipulate cue points, as the following example
shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\videodisplay\VideoDisplayCPManager.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"
height="450"
creationComplete="myVid.pause();"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.events.CuePointEvent;
[Bindable]
private var myCuePoints:Array = [
{ name: "first", time: 5},
{ name: "second", time: 10}
];
// Set cue points using methods of the CuePointManager class.
private function initCP():void {
myVid.cuePointManager.setCuePoints(myCuePoints);
}
private var currentCP:Object=new Object();
private function cpHandler(event:CuePointEvent):void {
cp.text += "Got to " + event.cuePointName + " cuepoint @ " +
String(event.cuePointTime) + " seconds in.\n";
// Remove cue point.
currentCP.name=event.cuePointName;
currentCP.time=event.cuePointTime;
myVid.cuePointManager.removeCuePoint(currentCP);
// Display the number of remaining cue points.
cp.text += "# cue points remaining: " +
String(myVid.cuePointManager.getCuePoints().length) + ".\n";
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:VBox&gt;
&lt;mx:VideoDisplay id="myVid"
cuePointManagerClass="mx.controls.videoClasses.CuePointManager"
source="../assets/MyVideo.flv"
cuePoint="cpHandler(event);"
height="250"
width="250"
/&gt;
&lt;mx:Label text="{myVid.playheadTime}"/&gt;
&lt;mx:TextArea id="cp" height="100" width="250"/&gt;
&lt;/mx:VBox&gt;
&lt;mx:HBox&gt;
&lt;mx:Button label="&amp;gt;" click="cp.text='';initCP();myVid.play();"/&gt;
&lt;/mx:HBox&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7faa_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7faa_verapache"><!-- --></a>
<h3 class="topictitle3">Streaming video from a camera to
the MX VideoDisplay control</h3>
<div>
<p>
You can use the <samp class="codeph">VideoDisplay.attachCamera()</samp> method
to configure the control to display a video stream from a camera,
as the following example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\videodisplay\VideoDisplayCamera.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
// Define a variable of type Camera.
import flash.media.Camera;
public var cam:Camera;
public function initCamera():void {
// Initialize the variable.
cam = Camera.getCamera();
myVid.attachCamera(cam)
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:VideoDisplay id="myVid"
width="320" height="240"
creationComplete="initCamera();"/&gt;
&lt;/s:Application&gt;</pre>
<p>In this example, you create a Camera object in the event handler
for the <samp class="codeph">creationComplete</samp> event of the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/VideoDisplay.html" target="_blank">VideoDisplay</a> control,
then pass the Camera object as the argument to the <samp class="codeph">attachCamera()</samp> method. </p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63b33-7fa9_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63b33-7fa9_verapache"><!-- --></a>
<h3 class="topictitle3">Using the MX VideoDisplay control
with Flash Media Server </h3>
<div>
<p>
You
can use the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/VideoDisplay.html" target="_blank">VideoDisplay</a> control
to play a media stream from Adobe<sup>®</sup> Flash<sup>®</sup> Media Server, without needing to register
the Flex application with the server. The following code shows a
simple example that uses the video-on-demand (vod) service that
is available in Flash Media Server 3.5 and later:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\videodisplay\VideoDisplayFMS.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:layout&gt;
&lt;s:HorizontalLayout/&gt;
&lt;/s:layout&gt;
&lt;s:Label text="RTMP FMS 3.5"/&gt;
&lt;mx:VideoDisplay
source="rtmp://examplesserver/vod/edge_codeJam.flv"/&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested1" id="WSc78f87379113c38b-669905c51221a3b97af-8000_verapache"><a name="WSc78f87379113c38b-669905c51221a3b97af-8000_verapache"><!-- --></a>
<h2 class="topictitle2">Spark VideoPlayer and VideoDisplay controls</h2>
<div>
<p>
The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/VideoPlayer.html" target="_blank">VideoPlayer</a> control
lets you play progressively downloaded or streaming video. It supports
multi-bit rate streaming and live video when used with a server that
supports these features, such as Flash Media Server 3.5 or later.</p>
<p>The VideoPlayer control contains a full UI to let users control
playback of video. It contains a play/pause toggle button; a scrub
bar to let users seek through video; a volume bar; a timer; and
a button to toggle in and out of fullscreen mode. </p>
<p>Flex also offers the Spark <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/VideoDisplay.html" target="_blank">VideoDisplay</a> control,
which plays video without any chrome, skin, or UI. The Spark VideoDisplay
has the same methods and properties as the Spark VideoPlayer control.
It is useful when you do not want the user to interact with the
control, or when you want to fully customize the interactivity but
not reskin the VideoPlayer control.</p>
<p>Both VideoPlayer and VideoDisplay support playback of FLV and
F4V file formats, as well as MP4-based container formats.</p>
</div>
<div class="nested2" id="WS19f279b149e7481c-6a9b22512c2c68c966-8000_verapache"><a name="WS19f279b149e7481c-6a9b22512c2c68c966-8000_verapache"><!-- --></a>
<h3 class="topictitle3">About OSMF</h3>
<div>
<p>The underlying implementation of the Spark VideoDisplay
and VideoPlayer classes rely on the Open Source Media Framework
(OSMF) classes.</p>
<p>You can use the OSMF classes to extend the VideoPlayer and VideoDisplay classes.
For example, you can use OSMF to incorporate advertising, reporting, cue
points, and DVR functionality. </p>
<p>You can also use OSMF classes to implement your own player. For
an example of this, see <a href="http://www.brooksandrus.com/blog/2010/02/10/osmf-flex-example/" target="_blank">OSMF + Flex Example</a>.</p>
<p>For more information about OSMF, see <a href="http://www.opensourcemediaframework.com/" target="_blank">Open
Source Media Framework</a>
</p>
</div>
</div>
<div class="nested2" id="WSc78f87379113c38b-669905c51221a3b97af-7ffe_verapache"><a name="WSc78f87379113c38b-669905c51221a3b97af-7ffe_verapache"><!-- --></a>
<h3 class="topictitle3">Spark VideoPlayer events</h3>
<div>
<p>The VideoPlayer control dispatches several different types
of events that you can use to monitor and control playback. The
event objects associated with each event dispatched by the VideoPlayer
control is defined by a class in the org.osmf.events.* package. </p>
<div class="p">The following example handles the <samp class="codeph">complete</samp> and <samp class="codeph">mediaPlayerStateChange</samp> events
dispatched by the VideoPlayer control: <pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- controls\videoplayer\VideoPlayerEvent.mxml--&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import org.osmf.events.MediaPlayerStateChangeEvent;
import org.osmf.events.TimeEvent;
protected function vpCompleteHandler(event:TimeEvent):void {
myTA.text = "Video complete - restarting."
}
protected function vpMediaPlayerStateChangeHandler(event:MediaPlayerStateChangeEvent):void {
if (event.state == "loading")
myTA.text = "loading ...";
if (event.state == "playing")
myTA.text = "playing ...";
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:VideoPlayer
source="rtmp://examplesserver/vod/mp4:_cs4promo_1000.f4v"
width="350" height="250"
loop="true"
complete="vpCompleteHandler(event);"
mediaPlayerStateChange="vpMediaPlayerStateChangeHandler(event);"/&gt;
&lt;s:TextArea id="myTA" width="350" height="25"/&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>The VideoPlayer control dispatches the <samp class="codeph">complete</samp> event
when the video completes. The event object for the complete event
is of type <a href="org/osmf/events/TimeEvent.html" target="_blank">org.osmf.events.TimeEvent</a>. </p>
<p>The VideoPlayer control dispatches the <samp class="codeph">mediaPlayerStateChange</samp> event when
the state of the control changes. The control has several states,
including the <samp class="codeph">buffering</samp>, <samp class="codeph">loading</samp>, <samp class="codeph">playing</samp>,
and <samp class="codeph">ready</samp> states. The event object for the <samp class="codeph">mediaPlayerStateChange</samp> event
is of <a href="org/osmf/events/MediaPlayerStateChangeEvent.html" target="_blank">org.osmf.events.MediaPlayerStateChangeEvent</a>.
The event handler for the <samp class="codeph">mediaPlayerStateChange</samp> event uses
the <samp class="codeph">state</samp> property of the event object to determine
the new state of the control.</p>
</div>
</div>
<div class="nested2" id="WSa41fb1fd58a1982d1108117f123a6626bcf-8000_verapache"><a name="WSa41fb1fd58a1982d1108117f123a6626bcf-8000_verapache"><!-- --></a>
<h3 class="topictitle3">Setting the video source for the
Spark VideoPlayer control</h3>
<div>
<p>The VideoPlayer component supports playback of local media,
streaming media, and progressively downloaded media. You can play
back both live and recorded media. </p>
<p>To play back a single media file, use the <samp class="codeph">source</samp> attribute.
The correct value for the <samp class="codeph">source</samp> attribute is the
path to the file. Use the correct syntax in the URL: HTTP for progressive
download and RTMP for streaming from Flash Media Server. If using
Flash Media Server, use the correct prefixes or extensions. </p>
<p>The following code plays a local FLV file, phone.flv, that resides
in the assets folder in the same project folder as the SWF file:</p>
<p>
<samp class="codeph">&lt;s:VideoPlayer source="assets/phone.flv"/&gt;</samp>
</p>
<p>The following code plays a single F4V file from Flash Media Server,
using the video-on-demand service that Flash Media Server 3.5 and
later provides. The use of the MP4 prefix and the F4V file extension
are required. The MP4 prefix is always required; the F4V file extension
is required when the name of the file to be loaded contains a file
extension.</p>
<pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- controls\videoplayer\VideoPlayerSimple.mxml--&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:VideoPlayer
source="rtmp://examplesserver/vod/mp4:_cs4promo_1000.f4v"
width="350" height="250"
loop="true"/&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
<div class="nested2" id="WS19f279b149e7481c2576c2bc12c2cbb5bc4-8000_verapache"><a name="WS19f279b149e7481c2576c2bc12c2cbb5bc4-8000_verapache"><!-- --></a>
<h3 class="topictitle3">Using dynamic streaming</h3>
<div>
<p>The Spark VideoPlayer and VideoDisplay components support
dynamic streaming (also known as <em>multi-bitrate streaming</em> or <em>adaptive streaming</em>)
for on-demand and live content. To use dynamic streaming, you encode
a stream at several different bit rates. During playback, Flash
Player dynamically switches among the streams based on connection
quality and other metrics to provide the best experience. </p>
<div class="p">You can do dynamic streaming over RTMP and HTTP. On-demand and
live dynamic streaming over RTMP require Flash Media Server. RTMP
streaming has the following benefits over HTTP streaming:<ul>
<li>
<p>RTMPe for lightweight content protection</p>
</li>
<li>
<p>RTMP quality of service</p>
</li>
<li>
<p>Absolute timecodes</p>
</li>
<li>
<p>Enhanced buffering</p>
</li>
</ul>
</div>
<p>Live HTTP Dynamic Streaming requires Flash Media Server. On-demand
HTTP Dynamic Streaming requires an Apache HTTP Server Origin Module
and a File Packager tool. These tools are available as free downloads
from <a href="http://www.adobe.com/products/httpdynamicstreaming/" target="_blank">http://www.adobe.com/products/httpdynamicstreaming/</a>.</p>
</div>
<div class="nested3" id="WS19f279b149e7481c108e976f12c2d76ba3e-8000_verapache"><a name="WS19f279b149e7481c108e976f12c2d76ba3e-8000_verapache"><!-- --></a>
<h4 class="topictitle4">Dynamic streaming over HTTP</h4>
<div>
<div class="p">To use live and on-demand dynamic streaming over HTTP,
point the <samp class="codeph">source</samp> property of the VideoDisplay or
VideoPlayer class to an *.f4m file:<pre class="codeblock">&lt;s:VideoPlayer source="http://mysite.com/dynamic_Streaming.f4m" autoPlay="false"/&gt;</pre>
</div>
<p>HTTP Dynamic Streaming is not designed to be used with the DynamicStreamingVideoSource
or the DynamicStreamingVideoItem classes. Use those classes to stream
media over RTMP with Flash Media Server.</p>
<p>Before your can dynamically stream your video content over HTTP,
use the File Packager to package the file. The File Packager converts
the media file to fragments and creates an F4M manifest file to
point to the pieces of the package. You must also install the Apache
HTTP Origin Module on your web server to serve the streams. </p>
<p>For more information about HTTP Dynamic Streaming, see <a href="http://www.adobe.com/go/learn_fms_httpdynstream_en" target="_blank">Adobe HTTP Dynamic Streaming</a>.</p>
</div>
</div>
<div class="nested3" id="WS7568cbd5c81a0ea67583136b12402d76594-8000_verapache"><a name="WS7568cbd5c81a0ea67583136b12402d76594-8000_verapache"><!-- --></a>
<h4 class="topictitle4">Dynamic streaming over RTMP</h4>
<div>
<p>Flash Media Server 3.5 and later supports live and on-demand
dynamic streaming over RTMP. To perform dynamic streaming with Flash
Media Server, use the DynamicStreamingVideoSource class. </p>
<p>The DynamicStreamingVideoSource object contains multiple stream
items, each of which represents the same video stream encoded at
a different bitrate. </p>
<p>The following example uses the DynamicStreamingVideoSource object
to define streams of different qualities:</p>
<div class="p">
<pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- controls\VideoPlayer\VideoPlayerFMS.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx" &gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;s:VideoPlayer id="myPlayer"
width="500" height="300"&gt;
&lt;s:source&gt;
&lt;s:DynamicStreamingVideoSource id="mySVS"
host="rtmp://examplesserver/vod/"&gt;
&lt;s:DynamicStreamingVideoItem id="needs_replacing150"
streamName="MP4:_PS_needs_replacing_150.f4v"
bitrate="150" /&gt;
&lt;s:DynamicStreamingVideoItem id="needs_replacing500"
streamName="MP4:_PS_needs_replacing_500.f4v"
bitrate="500" /&gt;
&lt;s:DynamicStreamingVideoItem id="needs_replacing1000"
streamName="MP4:_PS_needs_replacing_1000.f4v"
bitrate="1000" /&gt;
&lt;/s:DynamicStreamingVideoSource&gt;
&lt;/s:source&gt;
&lt;/s:VideoPlayer&gt;
&lt;s:TextArea width="500" height="50"
text="Please wait while the video loads..."/&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
</div>
<div class="nested2" id="WS7568cbd5c81a0ea639a60d5612402eb1394-8000_verapache"><a name="WS7568cbd5c81a0ea639a60d5612402eb1394-8000_verapache"><!-- --></a>
<h3 class="topictitle3">Playing back live video with the
Spark VideoPlayer control</h3>
<div>
<p>To play back live video, use a DynamicStreamingVideoSource
object and set the <samp class="codeph">streamType</samp> attribute to <samp class="codeph">live</samp>:</p>
<div class="p">
<pre class="codeblock">&lt;s:VideoPlayer&gt;
&lt;s:DynamicStreamingVideoSource host="rtmp://localhost/live/" streamType="live"&gt;
&lt;s:DynamicStreamingVideoItem streamName="myStream.flv"/&gt;
&lt;/s:DynamicStreamingVideoSource&gt;
&lt;/s:VideoPlayer&gt;</pre>
</div>
<p>The VideoPlayer is the client application that plays back video.
To capture and stream the live video, you can use a tool like Flash
Media Live Encoder, which captures and streams live video to Flash
Media Server. If you don’t use Flash Media Live Encoder, you’ll
need to create a custom publishing application. For information
on creating a custom video capture application, see the <a href="http://www.adobe.com/go/learn_fms_livepub" target="_blank">Flash Media Server documentation</a>.</p>
</div>
</div>
<div class="nested2" id="WSc78f87379113c38b-669905c51221a3b97af-7ffd_verapache"><a name="WSc78f87379113c38b-669905c51221a3b97af-7ffd_verapache"><!-- --></a>
<h3 class="topictitle3">Setting the size of the Spark VideoPlayer
control</h3>
<div>
<p>The appearance of any video media playing in a VideoPlayer
control is affected by the following properties:</p>
<ul>
<li>
<p>
<samp class="codeph">scaleMode </samp>
</p>
</li>
<li>
<p>
<samp class="codeph">height </samp>
</p>
</li>
<li>
<p>
<samp class="codeph">width </samp>
</p>
</li>
</ul>
<p>The <samp class="codeph">scaleMode</samp> property only works when you set
the <samp class="codeph">height</samp> or <samp class="codeph">width</samp> property.
It adjusts the size of the playing media after the control size
has been set. Possible values are <samp class="codeph">none</samp>, <samp class="codeph">stretch</samp>, <samp class="codeph">letterbox</samp>,
and <samp class="codeph">zoom</samp>.</p>
<p>If you omit both <samp class="codeph">width</samp> and <samp class="codeph">height</samp> properties
for the control, Flex sizes the control to fit the size of the playing
media. If you specify only one property, and set the <samp class="codeph">scaleMode</samp> property,
the size of the playing media determines the value of the other
property. If you do not set the <samp class="codeph">scaleMode</samp> property,
the media retains its aspect ratio when resizing. </p>
<p>If you explicitly set the <samp class="codeph">width</samp> and <samp class="codeph">height</samp> properties,
be sure the values are appropriate for the size of video that plays.</p>
<p>
By default,
Flex sizes the VideoPlayer control to the size of the media. If
you specify the <samp class="codeph">width</samp> or <samp class="codeph">height</samp> property
of the control, and either is smaller than the media’s dimensions,
Flex does not change the size of the component. Instead, Flex sizes
the media to fit within the component. If the control’s playback area
is smaller than the default size of the media, Flex shrinks the
media to fit inside the control. </p>
<p>The sample video used here is larger than the specified component
size, but the width and height ratio are still appropriate to the
video size. If you were to remove the width and height properties
from the code, however, you would see that the VideoPlayer component
is automatically sized to the size of the video.</p>
</div>
</div>
<div class="nested2" id="WS19f279b149e7481c-3a09859512db929dae0-8000_verapache"><a name="WS19f279b149e7481c-3a09859512db929dae0-8000_verapache"><!-- --></a>
<h3 class="topictitle3">Using the Spark VideoDisplay control</h3>
<div>
<p>The Spark VideoDisplay control is the same as the Spark
VideoPlayer control, except that it does not have a UI associated
with it. You must manually create controls that perform functions
such as play, stop, and pause.</p>
<div class="p">The following example uses a Spark VideoDisplay control, and
exposes the <samp class="codeph">play()</samp> and <samp class="codeph">pause()</samp> methods
with Button controls:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- controls\videodisplay\SparkVideoDisplayStopPlay.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"
creationComplete="myVid.pause();"&gt;
&lt;s:VGroup&gt;
&lt;s:VideoDisplay id="myVid"
source="../assets/MyVideo.flv"
height="250"
width="250"
/&gt;
&lt;s:HGroup&gt;
&lt;s:Button label="||" click="myVid.pause();"/&gt;
&lt;s:Button label="&amp;gt;" click="myVid.play();"/&gt;
&lt;/s:HGroup&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<p>Adobe, Adobe AIR, Adobe Flash, Adobe Flash Media Live Encoder, Adobe Flash Media Server, Adobe Flash Platform and Adobe Flash Player are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries and are used by permission from Adobe. No other license to the Adobe trademarks are granted.</p>
</div>
</body>
</html>