Google Git
Sign in
apache / flex-site / ec799639d0bc0fab0451242bf01d2720166d9a1a / . / content / doc / flex / using / flx_components_cmp.html
blob: 9a84939d8eb2ec3744487d1c5747557530365a0a [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="Visual components"/>
<meta name="DC.Format" content="XHTML"/>
<meta name="DC.Identifier" content="WS2db454920e96a9e51e63e3d11c0bf69084-7fff_verapache"/>
<link rel="stylesheet" type="text/css" href="commonltr.css"/>
<title>Visual components</title>
</head>
<body id="WS2db454920e96a9e51e63e3d11c0bf69084-7fff_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7fff_verapache"><!-- --></a>
<h1 class="topictitle1">Visual components</h1>
<div>
<p>
You
use visual components to build Flex applications.
Visual components have a flexible set of characteristics that let
you control and configure them as necessary to meet your application’s
requirements.</p>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf63825-7ffd_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63825-7ffd_verapache"><!-- --></a>
<h2 class="topictitle2">About visual components </h2>
<div>
<p>
Flex includes
a component-based development model that you use to develop your
application and its user interface. You can use the prebuilt visual
components included with Flex, extend components to add new properties
and methods, and create components as required by your application.</p>
<p>Visual components are extremely flexible and provide you with
a great deal of control over the component’s appearance, how the
component responds to user interactions, the font and size of any
text included in the component, the size of the component in the
application, and many other characteristics. </p>
<p>The characteristics of visual components include the following:</p>
<dl>
<dt class="dlterm">Size</dt>
<dd>
<p>Height and width of a component. All visual components have
a default size. You can use the default size, specify your own size,
or let Flex resize a component as part of laying out your application. </p>
</dd>
<dt class="dlterm">Events</dt>
<dd>
<p>Application or user actions that require a component response.
Events include component creation, mouse actions such as moving
the mouse over a component, and button clicks.</p>
</dd>
<dt class="dlterm">Styles</dt>
<dd>
<p>Characteristics such as font, font size, and text alignment.
These are the same styles that you define and use with Cascading
Style Sheets (CSS). </p>
</dd>
<dt class="dlterm">Effects</dt>
<dd>
<p>Visible or audible changes to the component triggered by
an application or user action. Examples of effects are moving or
resizing a component based on a mouse click. </p>
</dd>
<dt class="dlterm">Skins</dt>
<dd>
<p>Classes that control a visual component’s appearance. </p>
</dd>
</dl>
</div>
</div>
<div class="nested1" id="WS92a952957940f5c1611f737312188328b93-8000_verapache"><a name="WS92a952957940f5c1611f737312188328b93-8000_verapache"><!-- --></a>
<h2 class="topictitle2">Spark and MX components</h2>
<div>
<p>Flex defines two sets of components: Spark and MX. The
Spark components are new for Flex 4 and are defined in the spark.*
packages. The MX components shipped in previous releases of Flex
and are defined in the mx.* packages. </p>
<p>The main differences between Spark and MX components are how
you use CSS styles with the components and how you skin them. For
the container components, there are additional differences about
how the containers perform layout. </p>
<p>Spark and MX define some of the same components. For example,
Spark defines a button control in the spark.components package,
and MX defines a button control in the mx.controls package. When
a component is available in both Spark and MX, it’s best to use
the Spark component.</p>
<p>Spark and MX also define components that are unique. For example,
Spark defines components to perform three dimensional effects. MX
defines data visualization components, such as the DataGrid and
AdvancedDataGrid controls, not included in Spark. Your applications
often contains a mixture of Spark and MX components.</p>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf63825-8000_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63825-8000_verapache"><!-- --></a>
<h2 class="topictitle2">Class hierarchy for visual components </h2>
<div>
<p>Flex visual components are implemented as a class hierarchy
in ActionScript. Therefore, each visual component in your application
is an instance of an ActionScript class. The following image shows
this hierarchy in detail up to the Object class: </p>
<div class="figborder">
<img src="images/cmp_hierarchy_FLSprite_Vcomp.png" alt="Flex visual components are implemented as a class hierarchy in ActionScript"/>
</div>
<p>All visual components are derived from the UIComponent class
and its superclasses, the Flex Sprite through Object classes, and
inherit the properties and methods of their superclasses. In addition,
visual components inherit other characteristics of the superclasses,
including event, style, and effect definitions. </p>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf63825-7ff2_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63825-7ff2_verapache"><!-- --></a>
<h2 class="topictitle2">Using the UIComponent class</h2>
<div>
<p>
The UIComponent class is the base
class for all Flex visual components. For detailed documentation,
see <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/core/UIComponent.html" target="_blank">UIComponent</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="WS2db454920e96a9e51e63e3d11c0bf63825-7ff1_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63825-7ff1_verapache"><!-- --></a>
<h3 class="topictitle3">Commonly used UIComponent properties </h3>
<div>
<p>
The
following table lists only the most commonly used properties of
components that extend the UIComponent 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="d123935e238">
<p>Property</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d123935e244">
<p>Type</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d123935e250">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e238 ">
<div class="p">
<pre class="codeblock">doubleClickEnabled</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e244 ">
<p>Boolean</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e250 ">
<p>Setting to <samp class="codeph">true</samp> lets the
component dispatch a <samp class="codeph">doubleClickEvent</samp> when a user
presses and releases the mouse button twice in rapid succession
over the component. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e238 ">
<div class="p">
<pre class="codeblock">enabled</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e244 ">
<p>Boolean</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e250 ">
<p>Setting to <samp class="codeph">true</samp> lets the
component accept keyboard focus and mouse input. The default value
is <samp class="codeph">true</samp>. </p>
<p>If you set <samp class="codeph">enabled</samp> to <samp class="codeph">false</samp> for
a container, Flex dims the color of the container and all of its
children, and blocks user input to the container and to all its
children. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e238 ">
<div class="p">
<pre class="codeblock">height</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e244 ">
<p>Number</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e250 ">
<p>The height of the component, in pixels. </p>
<p>In
MXML tags, but not in ActionScript, you can set this property as
a percentage of available space by specifying a value such as 70%;
in ActionScript, you must use the <samp class="codeph">percentHeight</samp> property.</p>
<p>The
property always returns a number of pixels. In ActionScript, you
use the <samp class="codeph">perCent</samp>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e238 ">
<div class="p">
<pre class="codeblock">id</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e244 ">
<p>String</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e250 ">
<p>Specifies the component identifier. This
value identifies the specific instance of the object and should
not contain any white space or special characters. Each component
in a Flex document must have a unique <samp class="codeph">id</samp> value.
For example, if you have two custom components, each component can
include one, and only one Button control with the id "okButton".</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e238 ">
<div class="p">
<pre class="codeblock">percentHeight</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e244 ">
<p>Number</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e250 ">
<p>The height of the component as a percentage
of its parent container, or for the Application container, the full
height of the browser. Returns <samp class="codeph">NaN</samp> if a percent-based
width has never been set or if a <samp class="codeph">height</samp> property
was set after the <samp class="codeph">percentHeight</samp> was set.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e238 ">
<div class="p">
<pre class="codeblock">percentWidth</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e244 ">
<p>Number</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e250 ">
<p>The width of the component as a percentage
of its parent container, or for the Application container, the full
span of the browser. Returns <samp class="codeph">NaN</samp> if a percent-based
width has never been set or if a <samp class="codeph">width</samp> property
was set after the <samp class="codeph">percentWidth</samp> was set.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e238 ">
<div class="p">
<pre class="codeblock">styleName</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e244 ">
<p>String</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e250 ">
<p>Specifies the style class selector to apply
to the component.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e238 ">
<div class="p">
<pre class="codeblock">toolTip</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e244 ">
<p>String</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e250 ">
<p>Specifies the text string displayed when
the mouse pointer hovers over that component.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e238 ">
<div class="p">
<pre class="codeblock">visible</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e244 ">
<p>Boolean</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e250 ">
<p>Specifies whether the container is visible
or invisible. The default value is <samp class="codeph">true</samp>, which
specifies that the container is visible. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e238 ">
<div class="p">
<pre class="codeblock">width</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e244 ">
<p>Number </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e250 ">
<p>The width of the component, in pixels. </p>
<p>In
MXML tags, but not in ActionScript, you can set this property as
a percentage of available space by specifying a value such as 70%;
in ActionScript, you must use the <samp class="codeph">percentWidth</samp> property. </p>
<p>The
property always returns a number of pixels. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e238 ">
<div class="p">
<pre class="codeblock">x</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e244 ">
<p>Number</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e250 ">
<p>The component’s <samp class="codeph">
<em>x </em>
</samp>position
within its parent container. Setting this property directly has
an effect only if the parent container uses absolute positioning.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e238 ">
<div class="p">
<pre class="codeblock">y</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e244 ">
<p>Number</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e250 ">
<p>The component’s <samp class="codeph">
<em>y</em>
</samp> position
within its parent container. Setting this property directly has
an effect only if the parent container uses absolute positioning.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63825-7ff5_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63825-7ff5_verapache"><!-- --></a>
<h3 class="topictitle3">Using components in MXML and ActionScript </h3>
<div>
<p>
Every
Flex component has an MXML API and an ActionScript API. A component’s MXML
tag attributes are equivalent to its ActionScript properties, styles,
effects, and events. You can use both MXML and ActionScript when
working with components. </p>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf63825-7ff5_verapache__WS2db454920e96a9e51e63e3d11c0bf63825-7ff4_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63825-7ff5_verapache__WS2db454920e96a9e51e63e3d11c0bf63825-7ff4_verapache"><!-- --></a><h4 class="sectiontitle">Configure
a component</h4>
<ol>
<li>
<p>Set the value of a component property,
event, style, or effect declaratively in an MXML tag, or at run
time in ActionScript code. </p>
</li>
<li>
<p>Call a component’s methods at run time in ActionScript code.
The methods of an ActionScript class are not exposed in the MXML
API. </p>
</li>
</ol>
<p>The following example creates a Spark Button
control in MXML. When the user clicks the Button control, it updates
the text of a Spark TextArea control by using an ActionScript function. </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- components\ButtonApp.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[
public function handleClick():void {
text1.text="Thanks for the click!";
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:Button id="button1"
label="Click here!"
width="100"
fontSize="12"
click="handleClick();"/&gt;
&lt;s:TextArea id="text1"/&gt;
&lt;/s:Application&gt;</pre>
<p>This example has the following
elements:</p>
<ul>
<li>
<p>The<samp class="codeph"> id</samp> property is inherited
by the Button control from the UIComponent class. You use it to
specify an identifier for the component. This property is optional,
but you must specify it if you want to access the component in ActionScript. </p>
</li>
<li>
<p>The<samp class="codeph"> label</samp> property is defined by the Button
control. It specifies the text that appears in the button.</p>
</li>
<li>
<p>The<samp class="codeph"> width</samp> property is inherited from the
UIComponent class. It optionally specifies the width of the button,
in pixels. </p>
</li>
<li>
<p>The <samp class="codeph">Button</samp> control dispatches a <samp class="codeph">click</samp> event
when a user presses and releases the main mouse button. The MXML <samp class="codeph">click</samp> attribute
specifies the ActionScript code to execute in response to the event.</p>
</li>
<li>
<p>The<samp class="codeph"> fontSize</samp> style is inherited from the
UIComponent class. It specifies the font size of the label text,
in pixels. </p>
</li>
</ul>
<div class="note"><span class="notetitle">Note:</span> The numeric values
specified for font size in Flex are actual character sizes in pixels.
These values are not equivalent to the relative font size specified
in HTML by using the <samp class="codeph">&lt;font&gt;</samp> tag.</div>
<p>The <samp class="codeph">click</samp> event
attribute can also take ActionScript code directly as its value, without
your having to specify it in a function. Therefore, you can rewrite
this example as the following code shows: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- components\ButtonAppAS.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:Button id="button1"
label="Click here!"
width="100"
fontSize="12"
click="text1.text='Thanks for the click!';"/&gt;
&lt;s:TextArea id="text1"/&gt;
&lt;/s:Application&gt;</pre>
<div class="note"><span class="notetitle">Note:</span> Although you
can specify multiple lines of ActionScript code (separated by semicolons)
as the value of the <samp class="codeph">click</samp> event attribute, for
readability you should limit the <samp class="codeph">click</samp> event to
only one or two lines of code. </div>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf63825-7ff5_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7dc0_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63825-7ff5_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7dc0_verapache"><!-- --></a><h4 class="sectiontitle">Initializing
components at run time</h4>
<p>
Flex
uses MXML property attributes to initialize your components. However,
you might want to use some logic to determine initial values at
run time. For example, you might want to initialize a component
with the current date or time. Flex must calculate this type of
information when the application executes. </p>
<p>Every component
dispatches several events during its life cycle. In particular,
all components dispatch the following events that let you specify
ActionScript to initialize a component:</p>
<dl>
<dt class="dlterm">preInitialize</dt>
<dd>
<p>Dispatched when a component has been created in a rough state, and
no children have been created.</p>
</dd>
<dt class="dlterm">initialize</dt>
<dd>
<p>Dispatched when a component and all its children have been
created, but before the component size has been determined.</p>
</dd>
<dt class="dlterm">creationComplete</dt>
<dd>
<p>Dispatched when the component has been laid out and the component
is visible (if appropriate).</p>
<p>You can use the <samp class="codeph">initialize</samp> event
to configure most component characteristics; in particular, use
it to configure any value that affects the component’s size. Use
the <samp class="codeph">creationComplete</samp> event if your initialization
code must get information about the component layout.</p>
<p>The
following example configures Flex to call the <samp class="codeph">initDate()</samp> function
when it initializes the Label control. When Flex finishes initializing
the Label control, and before the application appears, Flex calls
the <samp class="codeph">initDate()</samp> function.</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- components\LabelInit.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 initDate():void {
label1.text += new Date();
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:VGroup&gt;
&lt;s:Label id="label1"
text="Today's Date: "
initialize="initDate();"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
<p>You can also express the previous
example without a function call by adding the ActionScript code
in the component’s definition. The following example does the same
thing, but without an explicit function call:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- components\LabelInitAS.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:Label id="label1"
text="Today's Date:"
initialize="label1.text += new Date();"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
<p>As with other calls that are
embedded within component definitions, you can add multiple ActionScript
statements to the <samp class="codeph">initialize</samp> MXML attribute by separating
each function or method call with a semicolon. The following example
calls the <samp class="codeph">initDate()</samp> function and writes a message
in the flexlog.txt file when the <samp class="codeph">label1</samp> component
is instantiated:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- components\LabelInitASAndEvent.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 initDate():void {
label1.text += new Date();
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:VGroup&gt;
&lt;s:Label id="label1"
text="Today's Date:"
initialize="initDate(); trace('The label is initialized!');"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
<p>By default, on Microsoft Windows,
the flexlog.txt file is written to C:\Documents and Settings\USERNAME\Application
Data\Macromedia\Flash Player\Logs. For the location of this file
on other operating systems, see <a href="flx_logging_lg.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fc9_verapache">Editing
the mm.cfg file</a>.</p>
</dd>
</dl>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63825-7ffb_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63825-7ffb_verapache"><!-- --></a>
<h3 class="topictitle3">Configuring components: syntax
summary</h3>
<div>
<p>The following table summarizes the MXML and ActionScript
component APIs that you use to configure components:</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="d123935e895">
<p> </p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d123935e901">
<p>MXML example</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d123935e907">
<p>ActionScript example</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e895 ">
<p>Read-write property </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e901 ">
<div class="p">
<pre class="codeblock">&lt;s:Panel id="p1" title="My Title" visible="true"/&gt;</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e907 ">
<div class="p">
<pre class="codeblock"><samp class="codeph">p1.title=</samp>"<samp class="codeph">My Title</samp>"<samp class="codeph">;</samp>
tile1.visible=true;</pre>
</div>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e895 ">
<p>Read-only property</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e901 ">
<p>You cannot use a read-only property as an
attribute in MXML. </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e907 ">
<p>To get the value of a read-only property:</p>
<div class="p">
<pre class="codeblock">var theClass:String=mp1.className;</pre>
</div>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e895 ">
<p>Method</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e901 ">
<p>Methods are not available in MXML.</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e907 ">
<div class="p">
<pre class="codeblock">myList.sortItemsBy("data", "DESC");</pre>
</div>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e895 ">
<p>Event </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e901 ">
<div class="p">
<pre class="codeblock">&lt;mx:Accordion id="myAcc"
change="changeHandler (event);"/&gt;</pre>
</div>
<p/>
<p>You
must also define a <samp class="codeph">changeHandler()</samp> function as
shown in the ActionScript example.</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e907 ">
<div class="p">
<pre class="codeblock">private function changeHandler(event:MouseEvent):void
{...}
myButton.addEventListener("click", changeHandler);</pre>
</div>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e895 ">
<p>Style </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e901 ">
<div class="p">
<pre class="codeblock">&lt;s:Panel id="p1"
borderAlpha="0.5"
borderColor="blue"/&gt;</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e907 ">
<p>To set the style:</p>
<div class="p">
<pre class="codeblock">p1.setStyle("borderAlpha", 0.5);
p1.setStyle("borderColor", 'blue');</pre>
</div>
<p/>
<p>To
get the style:</p>
<div class="p">
<pre class="codeblock">var currentBorderAlpha:Number = p1.getStyle("borderAlpha");.</pre>
</div>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e895 ">
<p>Effect</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e901 ">
<div class="p">
<pre class="codeblock">&lt;s:Panel id="p1"
show="scale.end();scale.play();"/&gt;</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d123935e907 ">
<p>Call the effect’s <samp class="codeph">end()</samp> and <samp class="codeph">play()</samp> methods
in an event handler:.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf63825-7ffc_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63825-7ffc_verapache"><!-- --></a>
<h2 class="topictitle2">Sizing visual components</h2>
<div>
<p>The Flex sizing and layout mechanisms provide several ways
for you to control the size of visual components: </p>
<dl>
<dt class="dlterm">Default sizing</dt>
<dd>
<p>Automatically determines the sizes of controls and containers.
To use default sizing, you do not specify the component’s dimensions
or layout constraints.</p>
</dd>
<dt class="dlterm">Explicit sizing</dt>
<dd>
<p>You set the <samp class="codeph">height</samp> and <samp class="codeph">width</samp> properties
to pixel values. When you do this, you set the component dimension
to absolute sizes, and Flex does not override these values. The
following <samp class="codeph">&lt;s:Application&gt;</samp> tag, for example, sets
explicit Application dimensions:</p>
<pre class="codeblock"> &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="300"
  width="600"&gt;</pre>
</dd>
<dt class="dlterm">Percentage-based sizing</dt>
<dd>
<p>You specify the component size as a percentage of its container
size. To do this, you specify the <samp class="codeph">percentHeight</samp> and <samp class="codeph">percentWidth</samp> properties,
or, in an MXML tag, set the <samp class="codeph">height</samp> and <samp class="codeph">width</samp> properties
to percentage values such as 100%. The following code, for example, sets
percentage-based dimensions for an HGroup container:</p>
<pre class="codeblock"> &lt;s:HGroup id="hGroup1"
  height="30%" width="90%"/&gt;</pre>
<p>The following ActionScript
line resets the HGroup width to a different percentage value:</p>
<pre class="codeblock">hGroup1.percentWidth=40;</pre>
</dd>
<dt class="dlterm">Constraint-based layout</dt>
<dd>
<p>You can control size <em>and</em> position by anchoring components
sides, centers, or baselines to locations in their container by
specifying the <samp class="codeph">top</samp>, <samp class="codeph">bottom</samp>, <samp class="codeph">left</samp>, <samp class="codeph">right</samp>, <samp class="codeph">baseline</samp>, <samp class="codeph">horizontalCenter</samp>,
and <samp class="codeph">verticalCenter</samp> styles. You can use constraint-based
layout only for the children of a container that uses absolute layout.
That includes all Spark containers and the MX Application, Panel,
and Canvas containers. The following example uses constraint-based
layout to position an HGroup horizontally, and explicit sizing and
positioning to determine the vertical width and position:</p>
<pre class="codeblock"> &lt;s:HGroup id="hGroup2"
  left="30"right="30"
  y="150"
  height="100"/&gt;</pre>
<p>
You
can mix sizing techniques; however, you must ensure that the mix
is appropriate. Do not specify more than one type of sizing for
a component dimension; for example, do not specify a <samp class="codeph">height</samp> and
a <samp class="codeph">percentHeight</samp> for a component. Also, ensure that
the resulting sizes are appropriate; for example, if you do not want
scroll bars or clipped components, ensure that the sizes of a container’s children
do not exceed the container size. </p>
<p>For detailed information
on how Flex sizes components, and how you can specify sizing, see <a href="flx_size_position_sp.html#WS2db454920e96a9e51e63e3d11c0bf69084-7e4c_verapache">Laying
out components</a>.</p>
</dd>
</dl>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf63825-7ffc_verapache__WS2db454920e96a9e51e63e3d11c0bf63825-7ff6_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63825-7ffc_verapache__WS2db454920e96a9e51e63e3d11c0bf63825-7ff6_verapache"><!-- --></a><h3 class="sectiontitle">Examples
of component sizing</h3>
<p>The following example shows sizing
within an explicitly sized container when some of the container’s
child controls are specified with explicit widths and some with
percentage-based widths. It shows the flexibility and the complexities involved
in determining component sizes. The application logs the component sizes
to flashlog.txt, so you can confirm the sizing effect.</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- components\CompSizing.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="logSizes();"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
private function logSizes():void {
trace("HGroup: "+ hb1.width);
trace("Label: "+ lb1.width);
trace("Image: "+ img1.width);
trace("Button: "+ b1.width);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:HGroup id="hb1" width="250"&gt;
&lt;s:Label id="lb1"
text="Hello"
width="50"/&gt;
&lt;mx:Image id="img1"
source="@Embed(source='assets/flexlogo.jpg')"
width="75%"/&gt;
&lt;s:Button id="b1"
label="Button"
width="25%"/&gt;
&lt;/s:HGroup&gt;
&lt;/s:Application&gt;</pre>
<p>The application consists of
a 250-pixel-wide HGroup container that contains a 50-pixel-wide
label, an image that requests 75% of the container width, and a
button that requests 25% of the container width. The component sizes
are determined as follows:</p>
<ol>
<li>
<p>Flex reserves 50 pixels
for the explicitly sized Label control.</p>
</li>
<li>
<p>Flex puts an 6-pixel gap between components in an HGroup
container by default, so it reserves 12 pixels for the gaps; this
leaves 188 pixels available for the two percentage-based components. </p>
</li>
<li>
<p>The minimum width of the Button component, if you do not
specify an explicit width, fits the label text plus padding around
it. In this case, the minimum size is 70 pixels. However, since
you specified the width as 25%, Flex reserves 25% of the available
188 pixels, or 47 pixels, for the Button control.</p>
</li>
<li>
<p>The percentage-based image requests 75% of 188 pixels, or
141 pixels.</p>
</li>
</ol>
<p>If you change the button and image <samp class="codeph">size</samp> properties
to 50%, each get 50% of the available space, or 94 pixels.</p>
<p>The
following example uses explicit sizing for the Image control and
default sizing for the Button control:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- components\CompSizingExplicit.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="logSizes();"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
private function logSizes():void {
trace("HGroup: "+ hb1.width);
trace("Label: "+ lb1.width);
trace("Image: "+ img1.width);
trace("Button: "+ b1.width);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:HGroup id="hb1" width="250"&gt;
&lt;s:Label id="lb1"
text="Hello"
width="50"/&gt;
&lt;mx:Image id="img1"
source="@Embed(source='assets/flexlogo.jpg')"
width="119" /&gt;
&lt;s:Button id="b1"
label="Button"/&gt;
&lt;/s:HGroup&gt;
&lt;/s:Application&gt;</pre>
<p>Percentage-based sizing removes
the need to explicitly consider the gaps and margins of a container
in sizing calculations, but its greatest benefit applies when containers
resize. Then, the percentage-based children resize automatically based
on the available container size. In the following example, the series
of controls on the left resize as you resize your browser, but the
corresponding controls on the right remain a fixed size because
their container is fixed. Click the first Button control to log
the component sizes to flashlog.txt.</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- components\CompSizingPercent.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 logSizes():void {
trace("HGroup: "+ hb1.width);
trace("Label: "+ lb1.width);
trace("Image: "+ img1.width);
trace("Button: "+ b1.width);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:HGroup width="100%"&gt;
&lt;s:HGroup id="hb1" width="40%"&gt;
&lt;s:Label id="lb1"
text="Hello"
width="50"/&gt;
&lt;mx:Image id="img1"
source="@Embed(source='assets/flexlogo.jpg')"
width="60%"/&gt;
&lt;s:Button id="b1"
label="Button"
width="40%"
click="logSizes();"/&gt;
&lt;/s:HGroup&gt;
&lt;s:HGroup width="260"&gt;
&lt;s:Label
text="Hello"
width="50"/&gt;
&lt;mx:Image
source="@Embed(source='assets/flexlogo.jpg')"
width="119" /&gt;
&lt;s:Button
label="Button"/&gt;
&lt;/s:HGroup&gt;
&lt;/s:HGroup&gt;
&lt;/s:Application&gt;</pre>
<p>For more information about
sizing considerations, see <a href="flx_size_position_sp.html#WS2db454920e96a9e51e63e3d11c0bf69084-7dfc_verapache">Sizing
components</a>. </p>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf63825-7fff_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63825-7fff_verapache"><!-- --></a>
<h2 class="topictitle2">Handling events</h2>
<div>
<p>
Flex applications
are event driven. <em>Events</em> let a programmer know when the user has
interacted with an interface component, and also when important
changes have happened in the appearance or life cycle of a component,
such as the creation or destruction of a component or its resizing. </p>
<p>When an instance of a component dispatches an event, objects
that have registered as <em>listeners</em> for that event are notified.
You define event listeners, also called event <em>handlers</em>, in
ActionScript to process events. You register event listeners for events
either in the MXML declaration for the component or in ActionScript.
For additional examples of the event handling, see <a href="flx_components_cmp.html#WS2db454920e96a9e51e63e3d11c0bf63825-7ff5_verapache">Using
components in MXML and ActionScript </a>.</p>
<p>The following example registers an event listener in MXML that
is processed when you change views in an Accordion container. </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- components\CompIntroEvent.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="300"
height="280"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.controls.Alert;
private function handleAccChange():void {
Alert.show("You just changed views.");
}
]]&gt;
&lt;/fx:Script&gt;
&lt;!-- The Accordion container dispatches a change event when the
selected child container changes. --&gt;
&lt;mx:Accordion id="myAcc"
height="60"
width="200"
change="handleAccChange();"&gt;
&lt;s:NavigatorContent label="Box 1"&gt;
&lt;s:Label text="This is one view."/&gt;
&lt;/s:NavigatorContent&gt;
&lt;s:NavigatorContent label="Box 2"&gt;
&lt;s:Label text="This is another view."/&gt;
&lt;/s:NavigatorContent&gt;
&lt;/mx:Accordion&gt;
&lt;/s:Application&gt;</pre>
<p>You can pass an event object, which contains information about
the event, from the component to the event listener. </p>
<p>For the Accordion container, the event object passed to the event
listener for the <samp class="codeph">change</samp> event is of class IndexChangedEvent.
You can write your event listener to access the event object, as
the following example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- components\CompIntroEventAcc.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="300"
height="280"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
// Import the class that defines the event object.
import mx.events.IndexChangedEvent;
import mx.controls.Alert;
private function handleChange(event:IndexChangedEvent):void {
var currentIndex:int=event.newIndex;
Alert.show("You just changed views.\nThe new index is "
+ event.newIndex + ".");
}
]]&gt;
&lt;/fx:Script&gt;
&lt;!-- The Accordion control dispatches a change event when the
selected child container changes. --&gt;
&lt;mx:Accordion id="myAcc"
height="60"
width="200"
change="handleChange(event);"&gt;
&lt;s:NavigatorContent label="Box 1"&gt;
&lt;s:Label text="This is one view."/&gt;
&lt;/s:NavigatorContent&gt;
&lt;s:NavigatorContent label="Box 2"&gt;
&lt;s:Label text="This is another view."/&gt;
&lt;/s:NavigatorContent&gt;
&lt;/mx:Accordion&gt;
&lt;/s:Application&gt;</pre>
<p>In this example, you access the <samp class="codeph">newIndex</samp> property
of the IndexChangedEvent object to determine the index of the new
child of the Accordion container. For more information on events,
see <a href="flx_events_ev.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ee9_verapache">Events</a>. </p>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf63825-7fff_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7dbb_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63825-7fff_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7dbb_verapache"><!-- --></a><h3 class="sectiontitle">About
the component instantiation life cycle</h3>
<p>
The component instantiation life cycle
describes the sequence of steps that occur when you create a component
object from a component class. As part of that life cycle, Flex
automatically calls component methods, dispatches events, and makes
the component visible. </p>
<p>The following example creates a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/Button.html" target="_blank">Button</a> control
in ActionScript and adds it to a Group container: </p>
<pre class="codeblock"> // Create a Group container.
 var groupContainer:Group = new Group();
 // Configure the Group container.
groupContainer.x = 10;
groupContainer.y = 10;
 
 // Create a Button control.
 var b:Button = new Button()
 // Configure the button control.
 b.label = "Submit";
 ...
 // Add the Button control to the Box container.
 groupContainer.addElement(b);</pre>
<p>The following steps
show what occurs when you execute the code to create the Button
control, and add the control to the container: </p>
<ol>
<li>
<p>You
call the component’s constructor, as the following code shows: </p>
<pre class="codeblock"> // Create a Button control.
 var b:Button = new Button()</pre>
</li>
<li>
<p>You configure the component by setting its properties, as
the following code shows:</p>
<pre class="codeblock"> // Configure the button control.
 b.label = "Submit";</pre>
</li>
<li>
<p>You call the <samp class="codeph">addElement()</samp> method to add
the component to its parent, as the following code shows:</p>
<pre class="codeblock"> // Add the Button control to the Box container.
 groupContainer.addElement(b);</pre>
<p>Flex then performs
the following actions:</p>
</li>
<li>
<p>Sets the <samp class="codeph">parent</samp> property for the component
to reference its parent container. </p>
</li>
<li>
<p>Computes the style settings for the component. </p>
</li>
<li>
<p>Dispatches the <samp class="codeph">preinitialize</samp> event on the
component. The component is in a very raw state when this event
is dispatched. Many components, such as the Button control, create
internal child components to implement functionality. When Flex
dispatches the <samp class="codeph">preinitialize</samp> event, the children (including
the internal children, of a component) have not yet been created. </p>
</li>
<li>
<p>Dispatches the <samp class="codeph">initialize</samp> event on the component.
At this time, all of the component’s children are initialized, but
the component has not been sized or processed for layout. You can
use this event to perform additional processing of the component
before it is laid out. </p>
<p>Because the <samp class="codeph">initialize</samp> event
is dispatched early in the component's startup sequence, make sure
that none of your processing causes the component to invalidate
itself. You typically perform any final processing during the <samp class="codeph">creationComplete</samp> event.</p>
</li>
<li>
<p>Dispatches the <samp class="codeph">childAdd</samp> event on the parent
container. </p>
</li>
<li>
<p>Dispatches the <samp class="codeph">initialize</samp> event on the parent
container. </p>
</li>
<li>
<p>To display the application, a <samp class="codeph">render</samp> event
gets triggered, and Flex does the following: </p>
<ol type="a">
<li>
<p>Flex
completes all processing required to display the component, including laying
out the component.</p>
</li>
<li>
<p>Makes the component visible by setting the <samp class="codeph">visible</samp> property
to <samp class="codeph">true</samp>. </p>
</li>
<li>
<p>Dispatches the <samp class="codeph">creationComplete</samp> event on
the component. The component is sized and processed for layout.
This event is only dispatched once when the component is created. </p>
</li>
<li>
<p>Dispatches the <samp class="codeph">updateComplete</samp> event on the
component. Flex dispatches additional <samp class="codeph">updateComplete</samp> events
whenever the layout, position, size, or other visual characteristic
of the component changes and the component is updated for display. </p>
</li>
</ol>
</li>
</ol>
<p>You
can later remove a component from a container by using the <samp class="codeph">removeElement()</samp> method.
The removed child’s <samp class="codeph">parent</samp> property is set to <samp class="codeph">null</samp>.
If you add the removed child to another container, it retains its
last known state. If there are no references to the component, it
is eventually deleted from memory by the garbage collection mechanism
of Adobe<sup>®</sup> Flash<sup>®</sup> Player.</p>
<p>Given
this sequence of actions, you should use the events as follows:</p>
<ul>
<li>
<p>The <samp class="codeph">preinitialize</samp> event occurs too early
in the component life cycle for most initialization activities.
It is useful, however, in the rare situations where you must set
the properties on a parent before the children are created.</p>
</li>
<li>
<p>To configure a component before Flex has determined its visual
appearance, use the <samp class="codeph">initialize</samp> event. For example,
use this for setting properties that affect its appearance, height,
or width.</p>
</li>
<li>
<p>Use the <samp class="codeph">creationComplete</samp> event for actions
that rely on accurate values for the component’s size or position
when the component is created. If you use this event to perform
an action that changes the visual appearance of the component, Flex
must recalculate its layout, which adds unnecessary processing overhead
to your application.</p>
</li>
<li>
<p>Use the <samp class="codeph">updateComplete</samp> event for actions
that must be performed each time a component’s characteristics change,
not just when the component is created.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf63825-7ff9_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63825-7ff9_verapache"><!-- --></a>
<h2 class="topictitle2">Applying styles</h2>
<div>
<p>
Flex defines
styles for setting some of the characteristics of components, such
as fonts, padding, and alignment. These are the same styles as those
defined and used with Cascading Style Sheets (CSS). Each visual
component inherits many of the styles of its superclasses, and can
define its own styles. Some styles in a superclass might not be
used in a subclass. To determine the styles that a visual component
supports, see the styles section of the page for the component 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>You can set all styles in MXML as tag attributes. Therefore,
you can set the styles of a BorderContainer container and its contents
by using the <samp class="codeph">borderStyle</samp> and <samp class="codeph">borderColor</samp> properties,
as the following example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- components\MXMLStyles.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:BorderContainer id="myBC1"
borderStyle="solid"&gt;
&lt;s:Button label="Submit"/&gt;
&lt;/s:BorderContainer&gt;
&lt;s:BorderContainer id="myBC2"
borderStyle="solid"
borderColor="red"&gt;
&lt;s:Button label="Submit"/&gt;
&lt;/s:BorderContainer&gt;
&lt;/s:Application&gt;</pre>
<p>You can also configure styles in ActionScript by using the <samp class="codeph">setStyle()</samp> method, or
in MXML by using the <samp class="codeph">&lt;fx:Style&gt;</samp> tag. The <samp class="codeph">setStyle()</samp> method
takes two arguments: the style name and the value. The following
example is functionally identical to the previous example:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- components\ComponentsASStyles.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[
private function initBC():void {
myBC2.setStyle("borderColor", "red");
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:BorderContainer id="myBC1"
borderStyle="solid"&gt;
&lt;mx:Button label="Submit"/&gt;
&lt;/s:BorderContainer&gt;
&lt;s:BorderContainer id="myBC2"
borderStyle="solid"
initialize="initBC();"&gt;
&lt;mx:Button label="Submit"/&gt;
&lt;/s:BorderContainer&gt;
&lt;/s:Application&gt;</pre>
<p>When you use the <samp class="codeph">&lt;fx:Style&gt;</samp> tag, you set
the styles by using CSS syntax or a reference to an external file
that contains style declarations, as the following example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- components\TagStyles.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:Style&gt;
.myStyle {borderColor: red;}
&lt;/fx:Style&gt;
&lt;s:BorderContainer id="myBC1"
borderStyle="solid"&gt;
&lt;mx:Button label="Submit"/&gt;
&lt;/s:BorderContainer&gt;
&lt;s:BorderContainer id="myBC2"
borderStyle="solid"
styleName="myStyle"&gt;
&lt;mx:Button label="Submit"/&gt;
&lt;/s:BorderContainer&gt;
&lt;/s:Application&gt;</pre>
<p>
A <em>class selector</em> in
a style definition, defined as a label preceded by a period, defines
a new named style, such as <samp class="codeph">myStyle</samp> in the preceding
example. After you define it, you can apply the style to any component
by using the <samp class="codeph">styleName</samp> property. In the preceding
example, you apply the style to the second BorderContainer container. </p>
<p>
A <em>type selector</em> applies
a style to all instances of a particular component type. The following
example defines the top and bottom margins for all BorderContainer containers:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- components\TypeSelStyles.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:Style&gt;
@namespace s "library://ns.adobe.com/flex/spark";
s|BorderContainer {borderColor: red;}
&lt;/fx:Style&gt;
&lt;s:BorderContainer id="myBC1"
borderStyle="solid"&gt;
&lt;mx:Button label="Submit"/&gt;
&lt;/s:BorderContainer&gt;
&lt;s:BorderContainer id="myBC2"
borderStyle="solid"&gt;
&lt;mx:Button label="Submit"/&gt;
&lt;/s:BorderContainer&gt;
&lt;/s:Application&gt;</pre>
<p>In Flex, some, but not all, styles are inherited from parent
containers to their children and across style types and classes.
Because the <samp class="codeph">borderStyle</samp> style is not inherited,
this example yields results that are identical to the previous examples. </p>
<p>Some Spark and MX components share the same local name. For example,
there is a Spark Button component (in the spark.components.* package)
and a MX Button component (in the mx.controls.* package). To distinguish
between different components that share the same name, you specify
namespaces in your CSS that apply to types. The preceding example
defines the MX s namespace and uses “<samp class="codeph">s</samp>” as an identifier:</p>
<p>For more information on styles, see <a href="flx_styles_st.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fee_verapache">Styles
and themes</a>. </p>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf63825-7ff8_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63825-7ff8_verapache"><!-- --></a>
<h2 class="topictitle2">Applying effects</h2>
<div>
<p>An <em>effect</em> is a visible or audible change to the
component that occurs over a period of time, measured in milliseconds.
Examples of effects are fading, resizing, or moving a component. </p>
<p>Effects let you add animation, motion, and sound to your application
in response to some user or programmatic action. For example, you
can use effects to cause a dialog box to bounce slightly when it
receives focus, or to play a sound when the user enters an invalid
value.</p>
<p>To create the effect, you define a specific effect with a unique
ID in an <samp class="codeph">&lt;fx:Declarations&gt;</samp> tag. The following
example uses two Resize effects for a Button control. One Resize
effect expands the size of the button by 10 pixels when the user
clicks down on the button, and the second resizes it back to its original
size when the user releases the mouse button. </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- components\CompIntroBehaviors.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:Declarations&gt;
&lt;s:Resize id="myResizeEffectUp"
target="{myImage}"
widthBy="10" heightBy="10"/&gt;
&lt;s:Resize id="myResizeEffectDown"
target="{myImage}"
widthBy="-10" heightBy="-10"/&gt;
&lt;/fx:Declarations&gt;
&lt;mx:Image id="myImage"
source="@Embed(source='assets/flexlogo.jpg')"/&gt;
&lt;s:Button label="Resize Me Up"
click="myResizeEffectUp.end();myResizeEffectUp.play();"/&gt;
&lt;s:Button label="Resize Me Down"
click="myResizeEffectDown.end();myResizeEffectDown.play();"/&gt;
&lt;/s:Application&gt;</pre>
<p>For detailed information on using effects, see <a href="flx_behaviors_be.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fec_verapache">Introduction
to effects</a>. </p>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf63825-7ff3_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63825-7ff3_verapache"><!-- --></a>
<h2 class="topictitle2">Applying skins</h2>
<div>
<p>
<em>Skins</em> are classes that a component uses to control
its appearance. These classes are typically written in MXML and
are applied to a component by using the skinClass style property.
Skin classes can include embedded images or other media, FXG, ActionScript,
and any visual component in them.</p>
<p>When creating custom skins, you can use the component’s default
skin as a basis for writing your new skin, or the provided Wireframe
skins that are simpler.</p>
<p>Skin classes have a contract with a component that enforces certain
rules that the skin class and its host component must follow. For
example, if a component uses states (such as “mouseOver” or “mouseDown”),
the skin class must define the appearance of these states. If a
component uses subcomponents (such as a down or up arrow on a slider),
the skin class must define these as skin parts.</p>
<p>Typically, a skin class will define a <samp class="codeph">hostComponent</samp> property
so that is can get a reference to the component that uses it. This
is not required by the skinning contract but is recommended. Skin
classes can also share data with their host component by using data
binding.</p>
<p>All components that are subclasses of SkinnableComponent class
can have a skin class. Many containers cannot be skinned, however.
Only containers that are subclasses of SkinnableContainer can be
skinned.</p>
<p>Spark skins can be loaded and unloaded at run time, and their
properties can be bound to the style properties of the host component. </p>
<p>For more information on skinning, see <a href="flx_skinning_sk.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fed_verapache">Skinning
MX components</a>.</p>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf63825-7ffa_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63825-7ffa_verapache"><!-- --></a>
<h2 class="topictitle2">Changing the appearance of a component
at run time</h2>
<div>
<p>
You
can modify the look, size, or position of a component at run time
by using several component properties, styles, or ActionScript methods,
including the following: </p>
<ul>
<li>
<p>
<samp class="codeph">x</samp> and <samp class="codeph">y</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">width</samp> and <samp class="codeph">height</samp>
</p>
</li>
<li>
<p>styles, by using <samp class="codeph">setStyle(stylename,</samp>
<samp class="codeph">value)</samp>
</p>
</li>
</ul>
<p>You can set the <samp class="codeph">x</samp> and <samp class="codeph">y</samp> properties
of a component only when the component is in a container that uses
absolute positioning; that is, in a Canvas container, or in an Application
or Panel container that has the <samp class="codeph">layout</samp> property
set to <samp class="codeph">absolute</samp>. All other containers perform automatic
layout to set the <samp class="codeph">x</samp> and <samp class="codeph">y</samp> properties
of their children by using layout rules. </p>
<p>For example, you could use the <samp class="codeph">x</samp> and <samp class="codeph">y</samp> properties
to reposition a Button control 15 pixels to the right and 15 pixels
down in response to a Button control click, as the following example
shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- components\ButtonMove.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="150"
height="120"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
public function moveButton():void {
myButton.x += 15;
myButton.y += 15;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:Button id="myButton"
x="15"
y="15"
label="Move"
click="moveButton();"/&gt;
&lt;/s:Application&gt;</pre>
<p>In this application, you can move the Button control without
concern for other components. However, moving a component in an
application that contains multiple components, or modifying one
child of a container that contains multiple children, can cause
one component to overlap another, or in some other way affect the
layout of the application. Therefore, you should be careful when you
perform run-time modifications to container layout.</p>
<p>You can set the <samp class="codeph">width</samp> and <samp class="codeph">height</samp> properties
for a component in any type of container. The following example
increases the <samp class="codeph">width</samp> and <samp class="codeph">height</samp> of
a Button control by 15 pixels each time the user selects it:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- components\ButtonSize.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="150"
height="150"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
public function resizeButton():void {
myButton.height = myButton.height + 15;
myButton.width = myButton.width + 15;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:BorderContainer
height="80"
width="100"&gt;
&lt;s:Button id="myButton"
label="Resize"
click="resizeButton();"/&gt;
&lt;/s:BorderContainer&gt;
&lt;/s:Application&gt;</pre>
<p>If the container that holds the Button does not use absolute
positioning, it repositions its children based on the new size of
the Button control. </p>
<div class="note"><span class="notetitle">Note:</span> The stored values of <samp class="codeph">width</samp> and <samp class="codeph">height</samp> are
always in pixels regardless of whether the values were originally
set as fixed values, as percentages, or not set at all.</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf63825-7fef_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63825-7fef_verapache"><!-- --></a>
<h2 class="topictitle2">Extending components</h2>
<div>
<p>Flex provides several ways for you to extend existing components
or to create components. By extending a component, you can add new
properties or methods to it.</p>
<p>For example, the following MXML component, defined in the file
MyComboBox.mxml, extends the standard Spark ComboBox control to
initialize it with the postal abbreviations of the states in New
England:</p>
<pre class="noswf">&lt;?xml version="1.0"?&gt;
&lt;!-- components\myComponents\MyComboBox.mxml --&gt;
&lt;s:ComboBox 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:dataProvider&gt;
&lt;mx:ArrayList&gt;
&lt;fx:String&gt;CT&lt;/fx:String&gt;
&lt;fx:String&gt;MA&lt;/fx:String&gt;
&lt;fx:String&gt;ME&lt;/fx:String&gt;
&lt;fx:String&gt;NH&lt;/fx:String&gt;
&lt;fx:String&gt;RI&lt;/fx:String&gt;
&lt;fx:String&gt;VT&lt;/fx:String&gt;
&lt;/mx:ArrayList&gt;
&lt;/s:dataProvider&gt;
&lt;/s:ComboBox&gt;</pre>
<p>After you create it, you can use your new component anywhere
in your application by specifying its filename as its MXML tag name,
as the following example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- components\MainMyComboBox.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"
xmlns:MyComps="myComponents.*"
width="150"
height="150"&gt;
&lt;MyComps:MyComboBox id="stateNames"/&gt;
&lt;/s:Application&gt;</pre>
<p>In this example, the new component is in the myComponents subdirectory.
The myComponents.* namespace is mapped to the MyComps identifier.</p>
<p>Flex lets you create custom components by using either of the
following methods. The method you choose depends on your application
and the requirements of your component:</p>
<ul>
<li>
<p>Create components as MXML files and use them as custom
tags in other MXML files. MXML components provide an easy way to
extend an existing component, particularly to modify the behavior
of an existing component or add a basic feature to an existing component.</p>
</li>
<li>
<p>Create components as ActionScript files by subclassing the
UIComponent class or any of its subclasses, and use the resulting
classes as custom tags. ActionScript components provide a powerful
tool for creating new visual or nonvisual components.</p>
</li>
</ul>
<p>For detailed information on creating custom components, see <em>
<a href="flx_createcomps_intro_cci.html#WS2db454920e96a9e51e63e3d11c0bf68268-8000_verapache">Custom
Flex components</a>
</em> .</p>
</div>
<p>Adobe, 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>