Google Git
Sign in
apache / flex-site / ec799639d0bc0fab0451242bf01d2720166d9a1a / . / content / doc / flex / using / flx_containers_intro_cn.html
blob: c6603f4b4fb21aa4ee8d20d6948a408354bab9a6 [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="Introduction to containers"/>
<meta name="DC.Format" content="XHTML"/>
<meta name="DC.Identifier" content="WS2db454920e96a9e51e63e3d11c0bf69084-7ffa_verapache"/>
<link rel="stylesheet" type="text/css" href="commonltr.css"/>
<title>Introduction to containers</title>
</head>
<body id="WS2db454920e96a9e51e63e3d11c0bf69084-7ffa_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7ffa_verapache"><!-- --></a>
<h1 class="topictitle1">Introduction to containers</h1>
<div>
<p>Containers provide a hierarchical structure that lets you
control the layout characteristics of child components. </p>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf62b90-7fff_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf62b90-7fff_verapache"><!-- --></a>
<h2 class="topictitle2">About containers</h2>
<div>
<p>
A <em>container</em> defines
a rectangular region of the drawing surface of Adobe<sup>®</sup> Flash<sup>®</sup> Player. Within this region, you define
the components, including controls and containers, that you want
to appear. Components defined within a container are called <em>children</em>.
Flex provides a wide variety of containers,
ranging from simple boxes, panels, and forms to accordions that
provide built-in navigation among its children.</p>
<p>At the root of an application written in Flex is a single container,
called the application container, that represents the entire Flash
Player drawing surface. The application container holds all other
containers and controls. For more information, see <a href="flx_app_container_apc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ee7_verapache">Application
containers </a>.</p>
<p>A container uses a set of rules to control the layout of its
children, including sizing and positioning. Flex defines layout
rules to simplify the design and implementation of rich Internet
applications, while also providing enough flexibility to let you
create a diverse set of applications. </p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf62b90-7ffd_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf62b90-7ffd_verapache"><!-- --></a>
<h3 class="topictitle3">About layout containers and navigator
containers</h3>
<div>
<p>
Flex defines two types of containers: </p>
<dl>
<dt class="dlterm">Layout containers</dt>
<dd>
<p>Control the sizing and positioning of the children defined within
them. Children can be controls or other containers. For more information on
Spark layout containers, see <a href="flx_groups_containers_gc.html#WSD42D542D-CEFF-47e2-AFD5-C11F3E9B5AE2_verapache">Spark
containers </a>. For more information on MX layout containers,
see <a href="flx_layouts_lo.html#WS2db454920e96a9e51e63e3d11c0bf69084-7e4b_verapache">MX
layout containers</a>.</p>
</dd>
<dt class="dlterm">Navigator containers</dt>
<dd>
<p>Control user movement, or navigation, among multiple child
containers. Navigators only take MX containers or the Spark NavigatorContent
container as children. The individual child containers, not the
navigator container itself, control the layout and positioning of
their children. For more information, see <a href="flx_navigators_na.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fb9_verapache">MX
navigator containers</a>.</p>
</dd>
</dl>
</div>
</div>
<div class="nested2" id="WS3A51CD4F-F921-4d64-9C1A-BD7109975520_verapache"><a name="WS3A51CD4F-F921-4d64-9C1A-BD7109975520_verapache"><!-- --></a>
<h3 class="topictitle3">About Spark and MX containers</h3>
<div>
<p>Flex defines two sets of containers: MX and Spark. The
Spark containers are defined in the spark.components package. The
MX containers are defined in the mx.core and mx.containers packages. </p>
<p>While you can use MX containers to perform most of the same layout
that you can perform using the Spark containers, it’s best to use
the Spark containers when possible. </p>
</div>
<div class="nested3" id="WS045F4940-597B-434f-A3D0-54DC8C700677_verapache"><a name="WS045F4940-597B-434f-A3D0-54DC8C700677_verapache"><!-- --></a>
<h4 class="topictitle4">About container children</h4>
<div>
<p>One of the main differences between Spark and MX containers
is that an MX container can only use components that implement the
IUIComponent interface as its children. The UIComponent class implements
the IUIComponent interface, so you can use all Flex components and
containers as children of an MX container. </p>
<p>The Spark Group and SkinnableContainer containers can hold children
that implement the IVisualElement interface. These components include
all subclasses of the UIComponent class, and any subclasses of the
GraphicElement class. Many of the classes in the spark.primitives
package, such as Rect and Ellipse, are subclasses of the GraphicElement
class. Therefore, you can use those classes as children of a Spark
container to add graphics to the container. </p>
<p>The Spark SkinnableDataContainer and Spark DataGroup containers
can hold children that implement the IUIComponent interface, and
hold data items such as a String, Number, or Object. You must define
an item renderer to control the display of the data item. For more
information, see <a href="flx_groups_containers_gc.html#WS64909091-7042-4fb8-A243-8FD4E2990264_verapache">The
Spark DataGroup and Spark SkinnableDataContainer containers</a>.</p>
</div>
</div>
<div class="nested3" id="WS2db454920e96a9e51e63e3d11c0bf62b90-7ffe_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf62b90-7ffe_verapache"><!-- --></a>
<h4 class="topictitle4">About layout</h4>
<div>
<p>Containers implement a default layout algorithm so you
do not have to spend time defining it. Instead, you concentrate
on the information that you deliver, and the options that you provide
for your users, and not worry about implementing all the details
of user action and application response. In this way, Flex provides
the structure that lets you quickly and easily develop an application with
a rich set of features and interactions. </p>
<p>Layout rules also offer the advantage that your users soon grow
accustomed to them. That is, by standardizing the rules of user
interaction, your users do not have to think about how to navigate
the application, but can instead concentrate on the content that
the application offers. </p>
<p>One of the main differences between Spark and MX containers is
that the layout algorithm for MX containers is fixed, but for Spark
containers it is selectable. Therefore, MX defines a different container
for each type of layout. Spark defines a smaller set of containers,
but lets you switch the layout algorithm to make them more flexible.</p>
<p>The MX Canvas, MX Application, and MX Panel containers, and all
Spark containers, can use <em>absolute</em> layout. With absolute
layout, you explicitly specify the children’s <em>x</em> and <em>y</em> positions
in the container. Alternatively, you can use<em> constraint-based layout</em> to
anchor the sides, baseline, or center of the children relative to
the parent. </p>
<p>Absolute layout provides a greater level of control over sizing
and positioning than does automatic layout. But absolute layout
provides this control at the cost of making you explicitly specify
the positions of all container children.</p>
<p>Spark and MX containers let you define custom layout rules. For
Spark, you can define a custom layout class and apply it to a Spark
container. For MX, create a subclass of one of the MX containers
and override its layout mechanism. </p>
<p>For more information on layout, see <a href="flx_size_position_sp.html#WS2db454920e96a9e51e63e3d11c0bf69084-7e4c_verapache">Laying
out components</a>.</p>
</div>
</div>
<div class="nested3" id="WS34283599-8547-43ff-A89E-A67CAEABC8B0_verapache"><a name="WS34283599-8547-43ff-A89E-A67CAEABC8B0_verapache"><!-- --></a>
<h4 class="topictitle4">About skinning</h4>
<div>
<p>Skinning is the process of changing the appearance of a
component by modifying or replacing its visual elements. These elements
can be made up of bitmap images, SWF files, or vector images. All
MX containers are skinnable.</p>
<p>Most, but not all, Spark containers are skinnable. The Spark
Group and DataGroup containers are not skinnable. These containers
provide a lightweight mechanism that you use to perform layout.
They do not support skinning to ensure that they add minimal overhead
to your application. If you need to modify the visual appearance,
use a skinnable Spark container instead. </p>
<p>For more information, see <a href="flx_gumboskinning_gs.html#WS53116913-F952-4b21-831F-9DE85B647C8A_verapache">Spark
Skinning</a>
<a href="flx_layoutperformance_lp.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ee5_verapache">Improving
startup performance</a> and <a href="flx_skinning_sk.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fed_verapache">Creating
Halo Skins</a>.</p>
</div>
</div>
<div class="nested3" id="WS2FCF2174-EFDB-4d01-8D29-5A964D794ADA_verapache"><a name="WS2FCF2174-EFDB-4d01-8D29-5A964D794ADA_verapache"><!-- --></a>
<h4 class="topictitle4">About the creation policy</h4>
<div>
<p>Containers define a creation policy that specifies when
its children are created. By default, a container delays creating
its children until they are needed by the application. This process
is called <em>deferred instantiation</em>. Since all children are
not created at application start up, your application appears to
run faster. </p>
<p>You can control the creation policy for a container. For example,
you can create all children at startup, or you can explicitly determine
when a child is created. </p>
<p>You can use the following creation policies:</p>
<ul>
<li>
<p>
<samp class="codeph">ContainerCreationPolicy.AUTO</samp> The container
delays creating children until they are needed.</p>
<p>For navigator
containers such as the MX ViewStack, MX TabNavigator, and MX Accordion
containers, the container creates its direct children immediately, but
waits to create the descendants of each child until the child needs
to be displayed. As a result, only the initially required child
or children of a container get processed past the preinitialization
stage. An auto creation policy produces the best startup time because
fewer components are created initially.</p>
</li>
<li>
<p>
<samp class="codeph">ContainerCreationPolicy.ALL </samp>All container
children are created and initialized before the container is initialized. </p>
</li>
<li>
<p>
<samp class="codeph">ContainerCreationPolicy.NONE</samp> Requires the
container to explicitly create every child instance.</p>
</li>
</ul>
<p>For detailed information on creation policies, see <a href="flx_layoutperformance_lp.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ee5_verapache">Improving
Startup Performance</a>.</p>
</div>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf62b90-7ffc_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf62b90-7ffc_verapache"><!-- --></a>
<h2 class="topictitle2">Using containers</h2>
<div>
<p>
The
rectangular region of a container encloses its <em>content area</em>,
the area that contains its child components. The size of the region
around the content area is defined by the container. That region
can include extra space, or padding, around the content area and
an optional border around the container. </p>
<p>The following image shows a container and its content area, padding,
and borders: </p>
<div class="figborder">
<img src="images/cn_container_content_area.png" alt="A container and its content area, padding, and borders"/>
<dl>
<dt class="dlterm">
<strong>A.</strong>
</dt>
<dd>Left padding</dd>
<dt class="dlterm">
<strong>B.</strong>
</dt>
<dd>Right padding</dd>
<dt class="dlterm">
<strong>C.</strong>
</dt>
<dd>Container</dd>
<dt class="dlterm">
<strong>D.</strong>
</dt>
<dd>Content area</dd>
<dt class="dlterm">
<strong>E.</strong>
</dt>
<dd>Top padding</dd>
<dt class="dlterm">
<strong>F.</strong>
</dt>
<dd>Bottom padding</dd>
</dl>
</div>
<p>Although you can create an entire application by using a single
container, typical applications use multiple containers. For example,
the following image shows an application that uses three containers:</p>
<div class="figborder">
<img src="images/cn_HBoxLayoutContainer.png" alt="An application that uses three layout containers"/>
<dl>
<dt class="dlterm">
<strong>A.</strong>
</dt>
<dd>Parent container</dd>
<dt class="dlterm">
<strong>B.</strong>
</dt>
<dd>Child containers</dd>
</dl>
</div>
<p>
In this example,
the two child containers are nested within a parent container and
are referred to as children of the parent container. The child containers themselves
contain child UI components. </p>
<p>The parent container in the previous figure arranges its children
in a single horizontal row and oversees the sizing and positioning
characteristics of the child containers. For example, you can control
the distance, or gap, between children in a container by using the <samp class="codeph">horizontalGap</samp> and <samp class="codeph">verticalGap</samp> properties.
The two child containers are responsible for laying out their own children.</p>
<p> The following image shows the preceding example with the parent
container configured to use a vertical layout:</p>
<div class="figborder">
<img src="images/cn_VBoxLayoutContainer.png" alt="The outermost container changed to a VBox layout container"/>
<dl>
<dt class="dlterm">
<strong>A.</strong>
</dt>
<dd>Parent container</dd>
<dt class="dlterm">
<strong>B.</strong>
</dt>
<dd>Child containers</dd>
</dl>
</div>
<p>The primary use of a container is to arrange its children, where
the children are either controls or other containers. The following
image shows a Spark Panel container that has three child components:</p>
<div class="figborder">
<img src="images/cn_container.png" alt="VBox container that has three child components"/>
<dl>
<dt class="dlterm">A.</dt>
<dd>TextInput control</dd>
<dt class="dlterm">B.</dt>
<dd>Button
control</dd>
<dt class="dlterm">C.</dt>
<dd>TextArea control</dd>
</dl>
</div>
<p>In this example, a user enters a ZIP code into the TextInput
control, and then clicks the Button control to see the current temperature
for the specified ZIP code in the TextArea control. </p>
<p>Flex supports form-based applications through its MX Form layout
container. In a Form container, Flex can automatically align labels,
uniformly size text input controls, and display input error notifications.
The following image shows a Form container: </p>
<div class="figborder">
<img src="images/cn_form_example.png" alt="Form container"/>
<dl>
<dt class="dlterm">A.</dt>
<dd>Form container</dd>
<dt class="dlterm">B.</dt>
<dd>TextInput
control</dd>
<dt class="dlterm">C.</dt>
<dd>ComboBox control </dd>
<dt class="dlterm">D.</dt>
<dd>Button
control</dd>
</dl>
</div>
<p>Navigator containers, such as the MX TabNavigator and MX Accordion containers,
have built-in navigation controls that let you organize information from
multiple child containers in a way that makes it easy for a user
to move through it. The following image shows an Accordion container:</p>
<div class="figborder"><span class="figdesc">
<strong>A.</strong> Accordion buttons</span>
<img src="images/cn_accordion_example.png" alt="Accordion container"/>
</div>
<p>You use the Accordion buttons to move among the different child
containers. The Accordion container defines a sequence of child
panels, but displays only one panel at a time. To navigate a container,
the user clicks the navigation button that corresponds to the child
panel that they want to access.</p>
<p>Accordion containers support the creation of multistep procedures.
The preceding image shows an Accordion container that defines four
panels of a complex form. To complete the form, the user enters
data into all four panels. Accordion containers let users enter
information in the first panel, click the Accordion button to move
to the second panel, and then move back to the first if they want
to edit the information. For more information, see <a href="flx_navigators_na.html#WS2db454920e96a9e51e63e3d11c0bf69084-7e59_verapache">Accordion navigator
container</a>.</p>
</div>
<div class="nested2" id="WS8E14610C-57E0-4ebc-99E7-46D4CADD1C0D_verapache"><a name="WS8E14610C-57E0-4ebc-99E7-46D4CADD1C0D_verapache"><!-- --></a>
<h3 class="topictitle3">Spark containers</h3>
<div>
<div class="p">The following table describes the Spark containers defined
in the spark.components package:
<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="d128852e663">
<p>Container</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d128852e669">
<p>Type</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d128852e675">
<p>Description</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d128852e681">
<p>For more information</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e663 ">
<p>Application</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e669 ">
<p>Layout</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e675 ">
<p>The first container in an application. The
default layout is absolute.</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e681 ">
<p>
<a href="flx_app_container_apc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ee7_verapache">Using
Application Containers</a>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e663 ">
<p>BorderContainer</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e669 ">
<p>Layout</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e675 ">
<p>Defines a set of CSS styles that control
the appearance of the border and background fill of the container. </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e681 ">
<p>
<a href="flx_groups_containers_gc.html#WS03d33b8076db57b9466e6a52123e854e5d5-8000_verapache">The
Spark Border container</a>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e663 ">
<p>DataGroup</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e669 ">
<p>Layout</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e675 ">
<p>Simple container that lays out it children,
including data items, based on the specified layout. The default layout
is absolute. </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e681 ">
<p>
<a href="flx_groups_containers_gc.html#WS64909091-7042-4fb8-A243-8FD4E2990264_verapache">The
Spark DataGroup and Spark SkinnableDataContainer container</a>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e663 ">
<p>Group</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e669 ">
<p>Layout</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e675 ">
<p>Simple container that lays out it children,
including graphic children, based on the specified layout. The default
layout is absolute. </p>
<p>Flex defines subclasses of Group: HGroup
with horizontal layout, VGroup with vertical layout, and TileGroup with
tile layout.</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e681 ">
<p>
<a href="flx_groups_containers_gc.html#WSF1E2E7DD-8FA6-408d-9652-4B5E57A85A5A_verapache">The
Spark Group and Spark SkinnableContainer container</a>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e663 ">
<p>NavigatorContent</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e669 ">
<p>Layout</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e675 ">
<p>Simple container that can be used in an
MX navigator container, such as the ViewStack, TabNavigator and Accordion
containers. </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e681 ">
<p>
<a href="flx_groups_containers_gc.html#WSb96f4baaef289fcf-2107ed10123b8e266e7-8000_verapache">The
Spark NavigatorContent container</a>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e663 ">
<p>Panel</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e669 ">
<p>Layout</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e675 ">
<p>Displays a title bar, a caption, a border,
and its children. The default layout is absolute.</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e681 ">
<p>
<a href="flx_groups_containers_gc.html#WS842193BB-33E4-4bdc-9FD8-D76515B11FAE_verapache">The
Spark Panel layout container</a>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e663 ">
<p>SkinnableContainer</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e669 ">
<p>Layout</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e675 ">
<p>Skinnable container that lays out it children,
including graphic children, based on the specified layout. This container
supports skinning. The default layout is vertical. </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e681 ">
<p>
<a href="flx_groups_containers_gc.html#WSF1E2E7DD-8FA6-408d-9652-4B5E57A85A5A_verapache">The
Spark Group and Spark SkinnableContainer container</a>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e663 ">
<p>SkinnableDataContainer</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e669 ">
<p>Layout</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e675 ">
<p>Skinnable container that lays out it children,
including data items, based on the specified layout. This container
supports skinning. The default layout is vertical. </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e681 ">
<p>
<a href="flx_groups_containers_gc.html#WS64909091-7042-4fb8-A243-8FD4E2990264_verapache">The
Spark DataGroup and Spark SkinnableDataContainer container</a>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e663 ">
<p>SkinnablePopUpContainer</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e669 ">
<p>Layout</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e675 ">
<p>Skinnable container that lays out its children
in a skinnable container opened as a pop up window.</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e681 ">
<p>
<a href="flx_groups_containers_gc.html#WS67cd75b2532ad652-1abb110512d5bda966d-8000_verapache">The
Spark SkinnablePopUpContainer container</a>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e663 ">
<p>TitleWindow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e669 ">
<p>Layout</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e675 ">
<p>Skinnable Panel container that is optimized
for use as a pop-up window.</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e681 ">
<p>
<a href="flx_groups_containers_gc.html#WS6c678f7b363d5da52e8f1ca1124a0430dcf-8000_verapache">The
Spark TitleWindow container</a>
</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf62b90-7ffb_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf62b90-7ffb_verapache"><!-- --></a>
<h3 class="topictitle3">MX containers</h3>
<div>
<p>The following table describes the MX containers defined
in the mx.core and mx.components packages:</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="d128852e1043">
<p>Container</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d128852e1049">
<p>Type</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d128852e1055">
<p>Description</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d128852e1061">
<p>For more information</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1043 ">
<p>Accordion</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1049 ">
<p>Navigator</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1055 ">
<p>Organizes information in a series of child
panels, where one panel is active at any time. </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1061 ">
<p>
<a href="flx_navigators_na.html#WS2db454920e96a9e51e63e3d11c0bf69084-7e59_verapache">Accordion
navigator container</a>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1043 ">
<p>Application</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1049 ">
<p>Layout</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1055 ">
<p>The first container in an application. The
default layout is absolute.</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1061 ">
<p>
<a href="flx_app_container_apc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ee7_verapache">Using
Application Containers</a>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1043 ">
<p>ApplicationControlBar</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1049 ">
<p>Layout</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1055 ">
<p>Holds components that provide global navigation
and application commands. Can be docked at the top of an Application
container.</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1061 ">
<p>
<a href="flx_layouts_lo.html#WS2db454920e96a9e51e63e3d11c0bf69084-7e58_verapache">ApplicationControlBar
layout container</a>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1043 ">
<p>Box (HBox and VBox)</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1049 ">
<p>Layout</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1055 ">
<p>Displays content in a uniformly spaced row
or column. An HBox container horizontally aligns its children; a
VBox container vertically aligns its children. </p>
<p>It’s best
to use the Spark containers when possible, instead of the MX Box
container. </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1061 ">
<p>
<a href="flx_layouts_lo.html#WS2db454920e96a9e51e63e3d11c0bf69084-7e57_verapache">Box,
HBox, and VBox layout containers</a>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1043 ">
<p>Canvas</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1049 ">
<p>Layout</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1055 ">
<p>Defines a container in which you must explicitly position
its children. </p>
<p>It’s best to use the Spark containers with BasicLayout
when possible, instead of the MX Canvas container. </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1061 ">
<p>
<a href="flx_layouts_lo.html#WS2db454920e96a9e51e63e3d11c0bf69084-7e56_verapache">Canvas
layout container</a>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1043 ">
<p>ControlBar</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1049 ">
<p>Layout</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1055 ">
<p>Places controls at the lower edge of a Panel
or TitleWindow container.</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1061 ">
<p>
<a href="flx_layouts_lo.html#WS2db454920e96a9e51e63e3d11c0bf69084-7e55_verapache">ControlBar
layout container</a>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1043 ">
<p>DividedBox (HDividedBox and VDividedBox)</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1049 ">
<p>Layout</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1055 ">
<p>Lays out its children horizontally or vertically, much
like a Box container, except that it inserts an adjustable divider
between the children.</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1061 ">
<p>
<a href="flx_layouts_lo.html#WS2db454920e96a9e51e63e3d11c0bf69084-7e54_verapache">DividedBox,
HDividedBox, and VDividedBox layout containers</a>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1043 ">
<p>Form</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1049 ">
<p>Layout</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1055 ">
<p>Arranges its children in a standard form
format. </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1061 ">
<p>
<a href="flx_layouts_lo.html#WS2db454920e96a9e51e63e3d11c0bf69084-7e53_verapache">Form,
FormHeading, and FormItem layout containers</a>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1043 ">
<p>Grid</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1049 ">
<p>Layout</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1055 ">
<p>Arranges children as rows and columns of
cells, much like an HTML table.</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1061 ">
<p>
<a href="flx_layouts_lo.html#WS2db454920e96a9e51e63e3d11c0bf69084-7e52_verapache">Grid
layout container</a>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1043 ">
<p>Panel</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1049 ">
<p>Layout</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1055 ">
<p>Displays a title bar, a caption, a border,
and its children. </p>
<p>It's best to use the Spark Panel
container when possible, instead of the MX Panel container. </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1061 ">
<p>
<a href="flx_layouts_lo.html#WS2db454920e96a9e51e63e3d11c0bf69084-7e51_verapache">Panel
layout container</a>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1043 ">
<p>TabNavigator</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1049 ">
<p>Navigator</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1055 ">
<p>Displays a container with tabs to let users
switch between different content areas. </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1061 ">
<p>
<a href="flx_navigators_na.html#WS2db454920e96a9e51e63e3d11c0bf69084-7e50_verapache">TabNavigator
container</a>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1043 ">
<p>Tile</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1049 ">
<p>Layout</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1055 ">
<p>Defines a layout that arranges its children
in multiple rows or columns. </p>
<p>It’s best to use the Spark containers
with the TileLayout when possible, instead of the MX Tile container. </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1061 ">
<p>
<a href="flx_layouts_lo.html#WS2db454920e96a9e51e63e3d11c0bf69084-7e4f_verapache">Tile
layout container</a>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1043 ">
<p>TitleWindow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1049 ">
<p>Layout</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1055 ">
<p>Displays a popup window that contains a
title bar, a caption, border, a close button, and its children.
The user can move the container. </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1061 ">
<p>
<a href="flx_layouts_lo.html#WS2db454920e96a9e51e63e3d11c0bf69084-7e4e_verapache">TitleWindow
layout container</a>
</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1043 ">
<p>ViewStack</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1049 ">
<p>Navigator</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1055 ">
<p>Defines a stack of containers that displays
a single container at a time.</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1061 ">
<p>
<a href="flx_navigators_na.html#WS2db454920e96a9e51e63e3d11c0bf69084-7e4d_verapache">ViewStack
navigator container</a>
</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf62b90-7ff9_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf62b90-7ff9_verapache"><!-- --></a>
<h3 class="topictitle3">Container example</h3>
<div>
<p>
The
following example creates an application that uses a Spark Group
container with three child controls, where the Group container lays
out its children vertically: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- containers\intro\Panel3Children.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;s:Group&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;s:TextInput id="myinput" text="enter zip code"/&gt;
&lt;s:Button id="mybutton" label="GetWeather"/&gt;
&lt;s:TextArea id="mytext" height="20"/&gt;
&lt;/s:Group&gt;
&lt;/s:Application&gt;</pre>
<p>The Group container uses basic layout by default. Use the <samp class="codeph">layout</samp> property
of a Spark container to configure its layout. In the previous example,
you set the layout of the Group container to vertical. </p>
<div class="p">The Group container has subclasses that you can use as shortcuts
in your application: HGroup defines a Group container with horizontal
layout, VGroup defines a Group container with veritical layout,
and TileGroup defines a Group container with tile layout. The following
example modifies the previous example to use the VGroup container: <pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- containers\intro\Panel3Children.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;s:VGroup&gt;
&lt;s:TextInput id="myinput" text="enter zip code"/&gt;
&lt;s:Button id="mybutton" label="GetWeather"/&gt;
&lt;s:TextArea id="mytext" height="20"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>To actually retrieve weather information, you must set up a web
service, pass it the entered ZIP code from a <samp class="codeph">click</samp> event,
and use the returned information to populate the TextArea control. </p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf62b90-7ff8_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf62b90-7ff8_verapache"><!-- --></a>
<h3 class="topictitle3">Using container events</h3>
<div>
<div class="p">All containers and components support events. Containers
dispatch the following events:
<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="d128852e1595">
<p>Spark container</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d128852e1601">
<p>MX container</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d128852e1607">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1595 ">
<p>
<samp class="codeph">elementAdd</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1601 ">
<p>
<samp class="codeph">childAdd</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1607 ">
<p>Dispatched after a child is added to the
container.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1595 ">
<p>
<samp class="codeph">elementRemove</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1601 ">
<p>
<samp class="codeph">childRemove</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1607 ">
<p>Dispatched before a child is removed from
the container.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1595 ">
<p/>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1601 ">
<p>
<samp class="codeph">childIndexChanged</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1607 ">
<p>Dispatched after a child’s index in the
container has changed. </p>
<p>Spark containers dispatch multiple <samp class="codeph">itemAdd</samp> and <samp class="codeph">itemRemove</samp> events. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1595 ">
<p/>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1601 ">
<p>
<samp class="codeph">scroll</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1607 ">
<p>Dispatched when the user manually scrolls
the container.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1595 ">
<p>
<samp class="codeph">contentCreationComplete</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1601 ">
<p/>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1607 ">
<p>Dispatched after all container children
are created, and before the children dispatch the <samp class="codeph">creationComplete</samp> event.
This event is not available for Group and DataGroup.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="p">All components dispatch the following events after they are added
to or removed from a container:
<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="d128852e1770">
<p>Event</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d128852e1776">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1770 ">
<p>
<samp class="codeph">add</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1776 ">
<p>Dispatched by a component after the component
has been added to its container and the parent and the child are
in a consistent state. This event is dispatched after the container
has dispatched the <samp class="codeph">childAdd</samp> event and all changes
that need to be made as a result of the addition have happened.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1770 ">
<p>
<samp class="codeph">remove</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1776 ">
<p>Dispatched by a component after the component
has been removed from its parent container. This event is dispatched
after the container has dispatched the <samp class="codeph">childRemove</samp> event
and all changes that need to be made as a result of the removal
have happened.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="p">Several events are dispatched by all components, but need special
consideration when dispatched by containers. This is particularly
true for navigator containers, such as TabNavigator, where some
children might not be created when the container is created. These
events include the following:
<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="d128852e1846">
<p>Event</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d128852e1852">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1846 ">
<p>
<samp class="codeph">preinitialize</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1852 ">
<p>Dispatched when the component has been attached
to its parent container, but before the component has been initialized,
or any of its children have been created. In most cases, this event
is dispatched too early for an application to use to configure a
component.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1846 ">
<p>
<samp class="codeph">initialize</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1852 ">
<p>Dispatched when a component has finished
its construction and its initialization properties have been set.
At this point, all the component’s immediate children have been
created (they have at least dispatched their <samp class="codeph">preinitialize</samp> event),
but they have not been laid out. Exactly when initialize events
are dispatched depends on the container’s creation policy.</p>
<p>Flex
dispatches the <samp class="codeph">initialize</samp> event for a container
after it attaches all the container’s direct child controls and
the container’s initially required children have dispatched a <samp class="codeph">preinitialize</samp> event.</p>
<p>When
a container or control dispatches the <samp class="codeph">initialize</samp> event,
its initial properties have been set, but its width and height have
not yet been calculated, and its position has not been calculated.
The <samp class="codeph">initialize</samp> event is useful for configuring
a container’s children. For example, you can use the container’s <samp class="codeph">initialize</samp> event
to programmatically add children or set a container scroll bar’s styles.
You can use a container or component’s <samp class="codeph">initialize</samp> event
to initialize the data provider for a control.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1846 ">
<p>
<samp class="codeph">creationComplete</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e1852 ">
<p>Dispatched when the component, and all its
child components, and all their children, and so on, have been created,
laid out, and are visible.</p>
<p>Flex dispatches the <samp class="codeph">creationComplete</samp> event
for a container when those children that are initially required
are fully processed and drawn on the screen, including all required
children of the children, and so on. Create a listener for the <samp class="codeph">creationComplete</samp> event,
for example, if you must have the children’s dimensions and positions
in your event handler. Do not use the <samp class="codeph">creationComplete</samp> event
for actions that set layout properties, as doing so results in excess
processing time.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="p">The following example uses the <samp class="codeph">creationComplete</samp> event
to open an Alert box when the children of the HGroup container are
fully processed and drawn:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- containers\intro\Panel3ChildrenEvent.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.controls.Alert;
private function handleCreationComplete():void {
Alert.show("MyHGroup created.");
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:HGroup id="MyHGroup"
creationComplete="handleCreationComplete();"&gt;
&lt;s:TextInput id="myinput" text="enter zip code"/&gt;
&lt;s:Button id="mybutton" label="GetWeather"/&gt;
&lt;s:TextArea id="mytext" height="20"/&gt;
&lt;/s:HGroup&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>To better understand the order in which Flex dispatches events,
consider the following application outline.</p>
<p>
</p>
<pre class="codeblock"> OuterSkinnableContainer
  InnerSkinnableContainer1
  InnerLabel1
  InnerSkinnableContainer2
  InnerLabel2</pre>
<p>The <samp class="codeph">preinitialize</samp>, <samp class="codeph">initialize</samp>, <samp class="codeph">contentCreationComplete</samp>,
and <samp class="codeph">creationComplete</samp> events for the containers
and controls are dispatched in the following order. The indentation
corresponds to the indentation in the previous outline:</p>
<pre class="codeblock"> OuterSkinnableContainer preinitialize
  InnerSkinnableContainer1 preinitialize
  InnerLabel1 preinitialize
  InnerLabel1 initialize
InnerSkinnableContainer1 contentCreationComplete
  InnerSkinnableContainer1 initialize
  InnerSkinnableContainer2 preinitialize
  InnerLabel2 preinitialize
  InnerLabel2 initialize
InnerSkinnableContainer2 contentCreationComplete
   InnerSkinnableContainer2 initialize
OuterSkinnableContainer contentCreationComplete
 OuterSkinnableContainer initialize
  InnerLabel2 creationComplete
  InnerLabel1 creationComplete
  InnerSkinnableContainer2 creationComplete
  InnerSkinnableContainer1 creationComplete
 OuterSkinnableContainer creationComplete</pre>
<p>Notice that for the terminal controls, such as the Label controls,
the controls are preinitialized and then immediately initialized.
For containers, preinitialization starts with the outermost container
and works inward on the first branch, and then initialization works
outward on the same branch. This process continues until all initialization
is completed. </p>
<p>Then, the <samp class="codeph">creationComplete</samp> event is dispatched
first by the leaf components, and then by their parents, and so
on, until the application dispatches the <samp class="codeph">creationComplete</samp> event.
The order of the <samp class="codeph">creationComplete</samp> event is the
most deeply nested components dispatch the event first, then the
next most deeply nested, up to the application container. For components
at the same nesting level, the order of the <samp class="codeph">creationComplete</samp> events
is undefined.</p>
<p>The <samp class="codeph">initialize</samp> event is useful with a container
that is an immediate child of a navigator container with the <samp class="codeph">ContainerCreationPolicy.AUTO</samp> creation policy.
For example, by default, when an MX ViewStack is initialized, the
first visible child container dispatches an <samp class="codeph">initialize</samp> event.
Then, as the user moves to each additional child of the container,
the event gets dispatched for that child container.</p>
<p>The following example defines an event listener for the <samp class="codeph">creationComplete</samp> event,
which is dispatched when the user first navigates to Pane 2 of an
MX Accordion navigator container: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- containers\intro\AccordionInitEvent.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.controls.Alert;
public function pane2_initialize():void {
Alert.show("Pane 2 has been created.");
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:Accordion width="200" height="100" creationPolicy="auto"&gt;
&lt;mx:VBox id="pane1" label="Pane 1"&gt;
&lt;mx:Label text="This is pane 1."/&gt;
&lt;/mx:VBox&gt;
&lt;mx:VBox id="pane2"
label="Pane 2"
creationComplete="pane2_initialize();"&gt;
&lt;mx:Label text="This is pane 2."/&gt;
&lt;/mx:VBox&gt;
&lt;/mx:Accordion&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf62b90-7ff4_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf62b90-7ff4_verapache"><!-- --></a>
<h3 class="topictitle3">Disabling containers</h3>
<div>
<p>
All
containers support the <samp class="codeph">enabled</samp> property. By default,
this property is set to <samp class="codeph">true</samp> to enable user interaction
with the container and with the container’s children. If you set <samp class="codeph">enabled</samp> to <samp class="codeph">false</samp>,
Flex dims the color of the container and of all its children, and
blocks user input to the container and to all its children. </p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf62b90-7ff2_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf62b90-7ff2_verapache"><!-- --></a>
<h3 class="topictitle3">Defining a default button</h3>
<div>
<p>
You
use the <samp class="codeph">defaultButton</samp> property of a container to
define a default Button control within a container. Pressing the
Enter key while focus is on any control activates the Button control
as if it was explicitly selected. </p>
<p>For example, a login form displays TextInput controls for a user
name and password and a submit Button control. Typically, the user
types a user name, tabs to the password field, types the password,
and presses the Enter key to submit the login information without
explicitly selecting the Button control. To define this type of
interaction, set the <samp class="codeph">defaultButton</samp> property of
the Form control to the <samp class="codeph">id</samp> of the submit Button
control, as the following example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- containers\intro\ContainerDefaultB.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
public function submitLogin():void {
text1.text="You just tried to log in.";
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:Panel title="Default Button Example"&gt;
&lt;s:Form defaultButton="{mySubmitBtn}"&gt;
&lt;s:FormItem label="Username:"&gt;
&lt;s:TextInput id="username" width="100"/&gt;
&lt;/s:FormItem&gt;
&lt;s:FormItem label="Password:"&gt;
&lt;s:TextInput id="password" width="100"
displayAsPassword="true"/&gt;
&lt;/s:FormItem&gt;
&lt;s:FormItem&gt;
&lt;s:Button id="mySubmitBtn" label="Login"
click="submitLogin();"/&gt;
&lt;/s:FormItem&gt;
&lt;/s:Form&gt;
&lt;/s:Panel&gt;
&lt;s:Label id="text1" width="150"/&gt;
&lt;/s:Application&gt;</pre>
<div class="note"><span class="notetitle">Note:</span> The Enter key has a special purpose in the ComboBox
control. When the drop-down list of a ComboBox control is open,
pressing Enter selects the currently highlighted item in the ComboBox
control; it does not activate the default button. Also, when the
cursor is in a TextArea control, pressing Enter adds a newline;
it does not activate the default button.</div>
</div>
</div>
</div>
<div class="nested1" id="WS8DF44A60-B4B0-491f-A359-1B193DEB18D6_verapache"><a name="WS8DF44A60-B4B0-491f-A359-1B193DEB18D6_verapache"><!-- --></a>
<h2 class="topictitle2">Spark containers</h2>
<div>
<p>Spark containers provide a hierarchical structure to arrange
and configure their children. </p>
</div>
<div class="nested2" id="WSEA7276D1-A757-4050-8629-06794F994237_verapache"><a name="WSEA7276D1-A757-4050-8629-06794F994237_verapache"><!-- --></a>
<h3 class="topictitle3">Layout with Spark containers</h3>
<div>
<div class="p">Spark containers have a default layout scheme, but let
you switch the layout to suit your application requirements. The
layout classes are defined in the spark.layouts package, and include
the following classes: <ul>
<li>
<p>BasicLayout Use absolute positioning,
or layout constraints. </p>
</li>
<li>
<p>HorizontalLayout Lay out children in a single horizontal
row.</p>
</li>
<li>
<p>TileLayout Lay out children in multiple rows and columns.</p>
</li>
<li>
<p>VerticalLayout Lay out children in a single vertical column. </p>
</li>
</ul>
</div>
<p>For example, the default layout of the Group container is BasicLayout,
which means you must set the position of each container child. For
the SkinnableContainer container, the default layout is BasicLayout.
You can use any of the layout classes with the Spark containers. </p>
<p>For more information, see <a href="flx_groups_containers_gc.html#WSD42D542D-CEFF-47e2-AFD5-C11F3E9B5AE2_verapache">Using
Spark Containers</a>.</p>
</div>
</div>
<div class="nested2" id="WS6C9ED688-BEA3-40b5-A25D-3DCED0F6ED40_verapache"><a name="WS6C9ED688-BEA3-40b5-A25D-3DCED0F6ED40_verapache"><!-- --></a>
<h3 class="topictitle3">Skinning Spark containers</h3>
<div>
<p>The Spark Group, DataGroup, and BorderContainer containers
do not support skinning. All other Spark containers support skinning
so that you can control the visual aspects of the container. </p>
<p>For more information, see <a href="flx_gumboskinning_gs.html#WS53116913-F952-4b21-831F-9DE85B647C8A_verapache">Creating
Spark Skins</a>.</p>
</div>
</div>
<div class="nested2" id="WSC5AF600B-9793-4dfd-AD9D-B9FC098869A8_verapache"><a name="WSC5AF600B-9793-4dfd-AD9D-B9FC098869A8_verapache"><!-- --></a>
<h3 class="topictitle3">Scrolling Spark containers</h3>
<div>
<div class="p">The following example shows a Spark Group container that
contains a child Image control:<pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- containers\spark\SparkNoViewportNoSB.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;s:Group width="100" height="100"&gt;
&lt;s:Image width="300" height="400"
source="@Embed(source='/assets/logo.jpg')"/&gt;
&lt;/s:Group&gt;
&lt;/s:Application&gt; </pre>
</div>
<p>The size of the Image control is larger than that of its parent
Group container. By default, the child extends past the boundaries
of the parent container. </p>
<p>Rather than allow the child to extend past the boundaries of
the parent container, you can clip the child to the container boundaries.
With clipping enabled, you can control the part of the underlying
image to show in the container. To clip the children to the container
boundaries, use a viewport and scroll bars. </p>
</div>
<div class="nested3" id="WS03d33b8076db57b912d5551012406be690c-8000_verapache"><a name="WS03d33b8076db57b912d5551012406be690c-8000_verapache"><!-- --></a>
<h4 class="topictitle4">Configuring a Spark viewport</h4>
<div>
<p>A viewport is any class that implements the IViewport interface.
The Spark Group and DataGroup containers implement this interface,
so they can function as viewports. All subclasses of Group and DataGroup
can also function as viewports. </p>
<p>A viewport defines a logical content area that encompasses all
of the children of the container. It also defines a rectangular
area, called the visible window, of the logical content area. The
visible window is the subset of the logical area of a container
that you want to display.</p>
<p>The following figure shows a Group container with a child Image
control that is larger than the area of the Group container: </p>
<div class="p">
<div class="figborder">
<img src="images/cn_logo_with_viewport.png"/>
<dl>
<dt class="dlterm">A.</dt>
<dd>Group container</dd>
<dt class="dlterm">B.</dt>
<dd>Area of
the visible window </dd>
<dt class="dlterm">C.</dt>
<dd>Visible
window of the Group container that appears in the application</dd>
</dl>
</div>
</div>
<p>The application user only sees that part of the container enclosed
by the visible window.</p>
<p>You use the following properties of the Spark container to configure
the viewport:</p>
<div class="p">
<ul>
<li>
<p>
<samp class="codeph">contentHeight</samp> and <samp class="codeph">contentWidth</samp> specify
the size of the logical content area of the container. This is the
area occupied by all of the container’s children.</p>
</li>
<li>
<p>
<samp class="codeph">height</samp> and <samp class="codeph">width</samp> specify
the size of the visible window of the container. </p>
</li>
<li>
<p>
<samp class="codeph">verticalScrollPosition</samp> and <samp class="codeph">horizontalScrollPosition</samp> specify
the origin of the visible window in the container’s coordinate system. The
default value is (0,0) corresponding to the upper-left corner of
the container.</p>
</li>
<li>
<p>
<samp class="codeph">clipAndEnableScrolling</samp>, if <samp class="codeph">true</samp>,
specifies to clip the children to the boundaries of the container.
If <samp class="codeph">false</samp>, the container children extend past the container
boundaries, regardless of the size specification of the container.
The default value is <samp class="codeph">false</samp>.</p>
</li>
</ul>
The following
example sets the <samp class="codeph">clipAndEnableScrolling</samp> property
to <samp class="codeph">true</samp> to clip the container’s children to the
container boundaries: </div>
<div class="p">
<pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- containers\spark\SparkViewport.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;s:Group width="100" height="100"
clipAndEnableScrolling="true"&gt;
&lt;s:Image width="300" height="400"
source="@Embed(source='/assets/logo.jpg')"/&gt;
&lt;/s:Group&gt;
&lt;/s:Application&gt; </pre>
</div>
<p>In this example, you set the <samp class="codeph">width</samp> and <samp class="codeph">height</samp> of
the container, corresponding to the visible window, to 100 by 100
pixels. </p>
<p>By default, the visible window is located at the coordinates
(0,0) in the container. Use the <samp class="codeph">verticalScrollPosition</samp> and <samp class="codeph">horizontalScrollPosition</samp> properties
to set its location, as the following example shows:</p>
<div class="p">
<pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- containers\spark\SparkViewportSet.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark" &gt;
&lt;s:Group width="100" height="100"
horizontalScrollPosition="50" verticalScrollPosition="50"
clipAndEnableScrolling="true"&gt;
&lt;s:Image width="300" height="400"
source="@Embed(source='/assets/logo.jpg')"/&gt;
&lt;/s:Group&gt;
&lt;/s:Application&gt; </pre>
</div>
</div>
</div>
<div class="nested3" id="WS03d33b8076db57b912d5551012406be690c-7fff_verapache"><a name="WS03d33b8076db57b912d5551012406be690c-7fff_verapache"><!-- --></a>
<h4 class="topictitle4">Adding scroll bars to a Spark container</h4>
<div>
<div class="p">The visible window of a viewport on its own is not movable
by the application user. However, you can combine a viewport with
scroll bars so the user can scroll the visible window to see the
entire container. Scroll bars let you display an object that is
larger than the available screen space or display more objects than fit
in the current size of the container, as the following image shows: <div class="figborder">
<img src="images/cn_scrollpane.png" alt="Flex container with scroll bars"/>
<dl>
<dt class="dlterm">
<strong>A.</strong>
</dt>
<dd>Image at full size</dd>
<dt class="dlterm">
<strong>B.</strong>
</dt>
<dd>Image in a container with scroll bars</dd>
</dl>
</div>
</div>
<p>Add scroll bars to Spark containers in the following ways:</p>
<div class="p">
<ul>
<li>
<p>For viewport containers such as Group and DataGroup,
add HScrollBar and VScrollBar components. </p>
</li>
<li>
<p>For viewport containers such as Group and DataGroup, wrap
the container in a Scroller component. The Scroller component displays
a single child component with horizontal and vertical scroll bars. </p>
</li>
<li>
<p>For any skinnable Spark container, create a skin for the
container that uses the Scroller component. For information on creating
a scrollable skin, see <a href="flx_gumboskinning_gs.html#WSDF962B50-1B1B-461d-9454-7680C9532850_verapache">Add scroll
bars to Spark containers</a>.</p>
</li>
</ul>
</div>
<div class="p">In the following example, you add the HScrollBar and VScrollBar
components to the application: <pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- containers\spark\SparkScrollViewportSetSB.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark" &gt;
&lt;s:layout&gt;
&lt;s:HorizontalLayout/&gt;
&lt;/s:layout&gt;
&lt;s:VGroup&gt;
&lt;s:Group id="myGroup" width="100" height="100"
clipAndEnableScrolling="true"
horizontalScrollPosition="50" verticalScrollPosition="50"&gt;
&lt;s:Image width="300" height="400"
source="@Embed(source='/assets/logo.jpg')"/&gt;
&lt;/s:Group&gt;
&lt;s:HScrollBar viewport="{myGroup}" width="100"/&gt;
&lt;/s:VGroup&gt;
&lt;s:VScrollBar viewport="{myGroup}" height="100"/&gt;
&lt;/s:Application&gt; </pre>
</div>
<p>Use the <samp class="codeph">viewport</samp> property of a scroll bar component
to specify the viewport associated with it. In this example, you
associate the myGroup container with the scoll bars. As you manipulate
the HScrollBar component, it modifies the <samp class="codeph">horizontalScrollPosition</samp> property
of the group container. The VScrollBar component modifies the <samp class="codeph">verticalScrollPosition</samp> property. </p>
<p>In the following example, you add scroll bars to the Spark Group
container by wrapping the container in the Scroller component:</p>
<div class="p">
<pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- containers\spark\SparkScroll.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark" &gt;
&lt;s:Scroller width="100" height="100"&gt;
&lt;s:Group&gt;
&lt;s:Image width="300" height="400"
source="@Embed(source='/assets/logo.jpg')"/&gt;
&lt;/s:Group&gt;
&lt;/s:Scroller&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>The Scroller component can only wrap a single component. The
child of a Scroller tag must implement the IViewport interface,
which is implemented by the Spark Group and DataGroup containers. </p>
<p>The Scroller component sets the <samp class="codeph">height</samp> and <samp class="codeph">width</samp> properties,
rather than its child. Alternatively, you can omit the size settings
on the Scroller component and let the application determine its
size. </p>
<p>To ensure that scroll bars appear, do not set explicit sizes
on the child of the Scroller. If you set the size of the child explicitly,
then that size becomes the size of the child and no scroll bars
appear. Instead, use constraints to size the Scroller (such as setting
the <samp class="codeph">height</samp> property to 100%). </p>
<p>If the Scroller is unconstrained, it sizes itself to be as big
as the viewport. When you constrain the size of the Scroller a size
smaller than the child, the Scroller displays scroll bars so that
you can view the entire child. </p>
<p>Notice that the Group container did not set the <samp class="codeph">clipAndEnableScrolling</samp> property
to <samp class="codeph">true</samp>. The Scroller component automatically sets
the <samp class="codeph">clipAndEnableScrolling</samp> property to <samp class="codeph">true</samp> for
any viewport within it. Scroll bars only appear if required by the
viewport. </p>
<p>Use the <samp class="codeph">Scroller.ensureElementIsVisible()</samp> method
to scroll a component into view. Simply pass the component as an
argument to the <samp class="codeph">ensureElementIsVisible()</samp> method.</p>
<p>The default skin for the scroll bars defines the minimum height
of a vertical scroll bar and the minimum width of a vertical scroll
bar as 35 pixels. If the size of the scroll bar is less than 35
pixels, the thumb is hidden.</p>
<p>The default property of the Scroller tag is <samp class="codeph">viewport</samp>.
The previous example omits this tag, but you can specify it explicitly,
as the following example shows:</p>
<div class="p">
<pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- containers\spark\SparkScrollViewport.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;s:Scroller width="100" height="100"&gt;
&lt;s:viewport&gt;
&lt;s:Group&gt;
&lt;s:Image width="300" height="400"
source="@Embed(source='/assets/logo.jpg')"/&gt;
&lt;/s:Group&gt;
&lt;/s:viewport&gt;
&lt;/s:Scroller&gt;
&lt;/s:Application&gt; </pre>
</div>
<p>You can combine scroll bars with explicit settings for the container’s
viewport. The viewport settings determine the initial position of
the viewport, and then you can use the scroll bars to move it, as
the following example shows:</p>
<div class="p">
<pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- containers\spark\SparkScrollViewportSet.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark" &gt;
&lt;s:Scroller width="100" height="100"&gt;
&lt;s:Group
horizontalScrollPosition="50"
verticalScrollPosition="50"&gt;
&lt;s:Image width="300" height="400"
source="@Embed(source='/assets/logo.jpg')"/&gt;
&lt;/s:Group&gt;
&lt;/s:Scroller&gt;
&lt;/s:Application&gt; </pre>
</div>
<p>Not all Spark containers implement the IViewPort interface. Therefore,
those containers, such as the BorderContainer and SkinnableContainer
containers, cannot be used as the direct child of the Scroller component. </p>
<p>However, all Spark containers can have a Scroller component as
a child component. For example, to use scroll bars on a child of
the Spark BorderContainer container, wrap the child in a Scroller
component, as the following example shows:</p>
<div class="p">
<pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- containers\spark\SparkScrollBorder.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark" &gt;
&lt;s:BorderContainer width="100" height="100"
borderWeight="3" borderStyle="solid"&gt;
&lt;s:Scroller width="100%" height="100%"&gt;
&lt;s:Group
horizontalScrollPosition="50"
verticalScrollPosition="50"&gt;
&lt;s:Image width="300" height="400"
source="@Embed(source='/assets/logo.jpg')"/&gt;
&lt;/s:Group&gt;
&lt;/s:Scroller&gt;
&lt;/s:BorderContainer&gt;
&lt;/s:Application&gt; </pre>
</div>
<div class="p">The previous example used the Scroller component to make a child
of the BorderContainer container scrollable. To make the entire
BorderContainer container scrollable, wrap it in a Group container.
Then, make the Group container the child of the Scroller component,
as the following example shows: <pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- containers\spark\SparkScrollBorderOuter.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark" &gt;
&lt;s:Scroller width="100" height="100"&gt;
&lt;s:Group&gt;
&lt;s:BorderContainer
borderWeight="3" borderStyle="solid"&gt;
&lt;s:Image width="300" height="400"
source="@Embed(source='/assets/logo.jpg')"/&gt;
&lt;/s:BorderContainer&gt;
&lt;/s:Group&gt;
&lt;/s:Scroller&gt;
&lt;/s:Application&gt; </pre>
</div>
</div>
</div>
</div>
</div>
<div class="nested1" id="WS6DB252F3-BC93-4c6e-B95D-724CF2E928D7_verapache"><a name="WS6DB252F3-BC93-4c6e-B95D-724CF2E928D7_verapache"><!-- --></a>
<h2 class="topictitle2">MX containers</h2>
<div>
<p>MX containers include layout containers and navigators.
MX navigators can only take MX components as children. </p>
</div>
<div class="nested2" id="WS65E6F931-7BCF-483a-B52C-974E7965FD04_verapache"><a name="WS65E6F931-7BCF-483a-B52C-974E7965FD04_verapache"><!-- --></a>
<h3 class="topictitle3">Layout with MX containers</h3>
<div>
<p>All MX containers have a predefined layout. Some containers,
such as Application and Panel do let you switch among several possible
layouts, but most containers do not. For example, the VBox container
always lays out its children in a vertical column, and the Tile
container always lays out its children multiple rows and columns. </p>
</div>
</div>
<div class="nested2" id="WSF73B153C-F7B2-426d-AB9A-9AC892BA7E4C_verapache"><a name="WSF73B153C-F7B2-426d-AB9A-9AC892BA7E4C_verapache"><!-- --></a>
<h3 class="topictitle3">Skinning MX containers</h3>
<div>
<p>MX containers support skinning so that you can control
the visual aspects of the container. For more information on skinning
MX containers, see <a href="flx_skinning_sk.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fed_verapache">Creating
Skins</a>.</p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7e41_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7e41_verapache"><!-- --></a>
<h3 class="topictitle3">Scrolling MX containers</h3>
<div>
<p>
MX containers
support automatic scroll bars, which let you display an object that is
larger than the available screen space or display more objects than
fit in the current size of the container, as the following image
shows: </p>
<div class="figborder">
<img src="images/cn_scrollpane.png" alt="Flex container with scroll bars"/>
<dl>
<dt class="dlterm">
<strong>A.</strong>
</dt>
<dd>Image at full size</dd>
<dt class="dlterm">
<strong>B.</strong>
</dt>
<dd>Image in an HBox container</dd>
</dl>
</div>
<p>Automatic scroll bars appear by default when the container children
are larger than the container, and the <samp class="codeph">clipContent</samp> property
of the container is <samp class="codeph">true</samp>. The default value of <samp class="codeph">clipContent</samp> is <samp class="codeph">true</samp>. </p>
<p>In the following example, you use an HBox container to let users
scroll an image, rather than rendering the complete image at its
full size. In this example, you explicitly set the size of the HBox
container to 75 by 75 pixels, a size smaller than the imported image.
If you omit the sizing restrictions on the HBox container, it attempts
to use its default size, which is a size large enough to hold the
image:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- containers\intro\HBoxScroll.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;mx:HBox width="75" height="75"&gt;
&lt;mx:Image source="@Embed(source='assets/logo.jpg')"/&gt;
&lt;/mx:HBox&gt;
&lt;/s:Application&gt;</pre>
<p>By default, Flex draws scroll bars only when the contents of
a container are larger than that container. To force the container
to draw scroll bars, you can set the <samp class="codeph">horizontalScrollPolicy</samp> and <samp class="codeph">verticalScrollPolicy</samp> properties
to <samp class="codeph">on</samp>. </p>
</div>
<div class="nested3" id="WS2db454920e96a9e51e63e3d11c0bf62b90-7ff0_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf62b90-7ff0_verapache"><!-- --></a>
<h4 class="topictitle4">Using container scroll properties</h4>
<div>
<p>The following container properties and styles control scroll
bar appearance and behavior:</p>
<ul>
<li>
<p>
The <samp class="codeph">horizontalScrollPolicy</samp> and <samp class="codeph">verticalScrollPolicy</samp> properties
control the display of scroll bars. By default, both properties
are set to <samp class="codeph">auto</samp>, which configures Flex to include
scroll bars only when necessary. You can set these properties to <samp class="codeph">on</samp> to
configure Flex to always include scroll bars, or set the properties
to <samp class="codeph">off</samp> to configure Flex to never include scroll
bars. In ActionScript, you can use constants in the ScrollPolicy
class, such as <samp class="codeph">ScrollPolicy.ON</samp>, to represent these
values.</p>
</li>
<li>
<p>The <samp class="codeph">horizontalLineScrollSize</samp> and <samp class="codeph">verticalLineScrollSize</samp> properties
determine how many pixels to scroll when the user selects the scroll
bar arrows. The <samp class="codeph">verticalLineScrollSize</samp> property
also controls the amount of scrolling when using the mouse wheel.
The default value is five pixels. </p>
</li>
<li>
<p>The <samp class="codeph">horizontalPageScrollSize</samp> and <samp class="codeph">verticalPageScrollSize</samp> properties
determine how many pixels to scroll when the user selects the scroll
bar track. The default value is 20 pixels. </p>
<div class="note"><span class="notetitle">Note:</span> If
the <samp class="codeph">clipContent</samp> property is <samp class="codeph">false</samp>,
a container lets its child extend past its boundaries. Therefore,
no scroll bars are necessary, and Flex never displays them, even
if you set <samp class="codeph">horizontalScrollPolicy</samp> and <samp class="codeph">verticalScrollPolicy</samp> to <samp class="codeph">on</samp>.</div>
</li>
</ul>
</div>
</div>
<div class="nested3" id="WS2db454920e96a9e51e63e3d11c0bf62b90-7fef_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf62b90-7fef_verapache"><!-- --></a>
<h4 class="topictitle4">Scroll bar layout considerations</h4>
<div>
<p>Your configuration of scroll bars can affect the layout
of your application. For example, if you set the <samp class="codeph">horizontalScrollPolicy</samp> and <samp class="codeph">verticalScrollPolicy</samp> properties
to <samp class="codeph">on</samp>, the container always includes scroll bars,
even if they are not necessary. Each scroll bar is 16 pixels wide. Therefore,
turning them on when they are not needed is similar to increasing
the size of the right and bottom padding of the container by 16
pixels. </p>
<p>If you keep the default values of <samp class="codeph">auto</samp> for the <samp class="codeph">horizontalScrollPolicy</samp> and <samp class="codeph">verticalScrollPolicy</samp> properties,
Flex lays out the application as if the properties are set to <samp class="codeph">off</samp>.
That is, the scroll bars are not counted as part of the layout. </p>
<p>If you do not keep in mind this behavior, your application might
have an inappropriate appearance. For example, if you have an HBox
container that is 30 pixels high and 100 pixels wide and has two
buttons that are each 22 pixels high and 40 pixels wide, the children
are contained fully inside the HBox container, and no scroll bars
appear. However, if you add a third button, the children exceed
the width of the HBox container, and Flex adds a horizontal scroll
bar at the bottom of the container. The scroll bar is 16 pixels
high, which reduces the height of the content area of the container
from 30 pixels to 14 pixels. This means that the Button controls,
which are 22 pixels high, are too tall for the HBox, and Flex, by default,
adds a vertical scroll bar.</p>
<p>Consider the following example:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- components\ScrollHBox.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;mx:HBox width="400"&gt;
&lt;mx:Button label="Label 1"
width="50%"
minWidth="200"/&gt;
&lt;mx:Button label="Label 2"
width="40%"
minWidth="150"/&gt;
&lt;mx:Button label="Label 3"/&gt;
&lt;/mx:HBox&gt;
&lt;/s:Application&gt;</pre>
<p>In this example, the default width of the fixed-size button is
66 pixels, so there are 324 pixels of space available for the percentage-based
buttons after accounting for the gap between components. The minimum
widths of the first and second buttons are greater than the percentage-based
values, so Flex assigns those buttons the set widths of 200 and
150 pixels, even though the HBox container only has 324 pixels free.
The HBox container uses scroll bars to provide access to its contents
because they now consume more space than the container itself.</p>
<div class="figborder">
<img src="images/sp_sizingsample8.png" alt="HBox container using scroll bars"/>
</div>
<p>Notice that the addition of the scroll bar doesn’t increase the
height of the container from its initial value. Flex considers scroll
bars in its sizing calculations only if you explicitly set the scroll
policy to <samp class="codeph">ScrollPolicy.ON</samp>. So, if you use an auto
scroll policy (the default), the scroll bar overlaps the buttons.
To prevent this behavior, you can set the <samp class="codeph">height</samp> property
for the HBox container or allow the HBox container to resize by
setting a percentage-based width. Remember that changing the height
of the HBox container causes other components in your application
to move and resize according to their own sizing rules. The following example
adds an explicit height and permits you to see the buttons and the
scroll bar:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- components\ScrollHBoxExplicitHeight.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;mx:HBox width="400" height="42"&gt;
&lt;mx:Button label="Label 1"
width="50%"
minWidth="200"/&gt;
&lt;mx:Button label="Label 2"
width="40%"
minWidth="150"/&gt;
&lt;mx:Button label="Label 3"/&gt;
&lt;/mx:HBox&gt;
&lt;/s:Application&gt;</pre>
<p>Flex draws the following application:</p>
<div class="figborder">
<img src="images/sp_sizingsample5.png" alt="An explicit height and permits you to see the buttons and the scroll bar"/>
</div>
<p>Alternatively, you can set the HBox control’s <samp class="codeph">horizontalScrollPolicy</samp> property
to <samp class="codeph">ScrollPolicy.ON</samp>. This reserves space for the
scroll bar during the initial layout pass, so it fits without overlapping
the buttons or setting an explicit height. This also correctly handles
the situation where the scroll bars change their size when you change
skinning or styles. This technique places an empty scroll bar area
on the container if it does not need scrolling, however.</p>
</div>
</div>
<div class="nested3" id="WS2db454920e96a9e51e63e3d11c0bf62b90-7fee_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf62b90-7fee_verapache"><!-- --></a>
<h4 class="topictitle4">Controlling scroll delay and interval </h4>
<div>
<p>Scroll bars have two styles that affect how they scroll:</p>
<ul>
<li>
<p>The <samp class="codeph">repeatDelay</samp> style specifies the
number of milliseconds to wait after the user selects a scroll button
before repeating scrolling. </p>
</li>
<li>
<p>The <samp class="codeph">repeatInterval</samp> style specifies the number
of milliseconds to wait between each repeated scroll while the user
keeps the scroll arrows selected.</p>
<p>These settings are styles
of the scroll bar subcontrol, not of the container, and, therefore,
require a different treatment than properties such as <samp class="codeph">horizontalScrollPolicy</samp>.
The following example sets the scroll policy consistently for all
scroll bars in the application:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- containers\intro\HBoxScrollDelay.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Style&gt;
@namespace s "library://ns.adobe.com/flex/spark";
@namespace mx "library://ns.adobe.com/flex/mx";
mx|HScrollBar, mx|VScrollBar {
repeatDelay: 2000;
repeatInterval:1000;
}
&lt;/fx:Style&gt;
&lt;mx:HBox id="hb1" width="75" height="75"&gt;
&lt;mx:Image source="@Embed(source='assets/logo.jpg')"/&gt;
&lt;/mx:HBox&gt;
&lt;/s:Application&gt;</pre>
<p>This example results in the
same scrollable logo as shown in <a href="flx_containers_intro_cn.html#WS2db454920e96a9e51e63e3d11c0bf69084-7e41_verapache">Using
scroll bars</a>, but the scroll bars behave differently. When
the user clicks and holds the mouse button down over any of the
scroll bar arrows or the scroll bar track, the image initially scrolls
once, waits two seconds, and then scrolls at a rate of one line
or page a second.</p>
<p>To set a style on a single scroll bar, use
a line such as the following in the event listener for the <samp class="codeph">initialize</samp> event
for the application or the control with the scroll bar:</p>
<pre class="codeblock"> ScrollBar(hb1.horizontalScrollBar).setStyle("repeatDelay", 2000);</pre>
<p>In
this case, <samp class="codeph">hb1</samp> is an HBox control. All containers
have <samp class="codeph">horizontalScrollBar</samp> and <samp class="codeph">verticalScrollBar </samp>properties
that represent the container’s ScrollBar subcontrols, if they exist.
Cast these properties to the ScrollBar class, because their type
is the IScrollBar interface, not the ScrollBar class.</p>
</li>
</ul>
</div>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf62b90-7fe9_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf62b90-7fe9_verapache"><!-- --></a>
<h2 class="topictitle2">Creating and managing container children
at run time</h2>
<div>
<p>
You
typically use MXML to lay out the user interface of your application,
and use ActionScript for event handling and run-time control of
the application. You can also use ActionScript to create component
instances at run time. For example, you could use MXML to define
an empty Accordion container and use ActionScript to add panels
to the container in response to user actions. </p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf62b90-7fe8_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf62b90-7fe8_verapache"><!-- --></a>
<h3 class="topictitle3">About the display list and container
children</h3>
<div>
<p>
Flash Player
maintains a tree of visible (or potentially visible) objects that
make up your application. The root of the tree is the Spark Application
or MX Application object, and child containers and components are
branches and leaf nodes of the tree. That tree is known as the <em>display list</em>.
When you add child components to a container or remove child components
from a container, you are adding and removing them from the display
list. You can also change their relative positions by changing their
positions in the display list.</p>
<p>Although the display list is a tree rooted at the top of the
application, when you manipulate a container’s children by ’s methods
and properties, you only access the container’s direct children.
Treat the container’s children as items in a list, where the first
child has an index of 0.</p>
</div>
</div>
<div class="nested2" id="WS2AD35652-B62C-46fb-93DD-853582281180_verapache"><a name="WS2AD35652-B62C-46fb-93DD-853582281180_verapache"><!-- --></a>
<h3 class="topictitle3">Using the container API for managing
container children</h3>
<div>
<div class="p">Spark Group and SkinnableContainer containers, and all
MX containers, provide properties and methods that you use to manage
the container’s children. Because the Spark Group and SkinnableContainer
containers can hold many types of children, the methods that you
use to manipulate its children refer to the children by a generic
name of <em>element</em>. <div class="note"><span class="notetitle">Note:</span> This section does not apply to the
Spark DataGroup and Spark SkinnableDataContainer. Those containers
use a data provider to define their children. You manage the children
of those containers in the same way that you manage any data provider control.
For more information, see <a href="flx_about_dataproviders_ab.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fb8_verapache">Data
providers and collections</a> and <a href="flx_groups_containers_gc.html#WS64909091-7042-4fb8-A243-8FD4E2990264_verapache">The
Spark DataGroup and Spark SkinnableDataContainer containers</a>.</div>
</div>
<div class="p">The following table shows these properties and methods:
<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="d128852e3090">
<p>Spark container</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d128852e3096">
<p>MX container</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d128852e3102">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3090 ">
<p>
<samp class="codeph">numElements</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3096 ">
<p>
<samp class="codeph">numChildren</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3102 ">
<p>Number of children in the container.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3090 ">
<p>
<samp class="codeph">addElement()</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3096 ">
<p>
<samp class="codeph">addChild()</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3102 ">
<p>Adds a child to the container as the last
child.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3090 ">
<p>
<samp class="codeph">addElementAt()</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3096 ">
<p>
<samp class="codeph">addChildAt()</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3102 ">
<p>Add a child at a specific index in the container.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3090 ">
<p/>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3096 ">
<p>
<samp class="codeph">getChildren()</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3102 ">
<p>Returns an Array containing all children.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3090 ">
<p>
<samp class="codeph">getElementAt()</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3096 ">
<p>
<samp class="codeph">getChildAt()</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3102 ">
<p>Return a child at the specified index.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3090 ">
<p/>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3096 ">
<p>
<samp class="codeph">getChildByName()</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3102 ">
<p>Return a child with the specified id.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3090 ">
<p>
<samp class="codeph">getElementIndex()</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3096 ">
<p>
<samp class="codeph">getChildIndex()</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3102 ">
<p>Returns the index of a child.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3090 ">
<p>
<samp class="codeph">removeAllElements()</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3096 ">
<p>
<samp class="codeph">removeAllChildren()</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3102 ">
<p>Removes all container children.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3090 ">
<p>
<samp class="codeph">removeElement()</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3096 ">
<p>
<samp class="codeph">removeChild()</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3102 ">
<p>Remove the first child.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3090 ">
<p>
<samp class="codeph">removeElementAt()</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3096 ">
<p>
<samp class="codeph">removeChildAt()</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3102 ">
<p>Remove the child at the specified index</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3090 ">
<p>
<samp class="codeph">setElementIndex()</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3096 ">
<p>
<samp class="codeph">setChildIndex()</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3102 ">
<p>Set the index of a child.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3090 ">
<p>
<samp class="codeph">swapElements()</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3096 ">
<p>
<samp class="codeph">swapChildren()</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3102 ">
<p>Swap the indexes of two children</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3090 ">
<p>
<samp class="codeph">swapElementsAt()</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3096 ">
<p>
<samp class="codeph">swapChildrenAt()</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3102 ">
<p>Swap the indexes of two children.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="p">
<div class="note"><span class="notetitle">Note:</span> Make sure that you use the correct method for your type
of container, either Spark or MX. Using the wrong method can cause
unexpected results. </div>
</div>
<div class="section" id="WS2AD35652-B62C-46fb-93DD-853582281180_verapache__WS2db454920e96a9e51e63e3d11c0bf62b90-7fe7_verapache"><a name="WS2AD35652-B62C-46fb-93DD-853582281180_verapache__WS2db454920e96a9e51e63e3d11c0bf62b90-7fe7_verapache"><!-- --></a><h4 class="sectiontitle">Obtaining
the number of child components in a container or application</h4>
<p>Use
the <samp class="codeph">numElements</samp> or <samp class="codeph">numChildren</samp> property
to obtain a count of the number of direct child components that
the container has in the display list. The following application
gets the number of children in the application and a Group container.
The Group control has five label controls, and therefore has five children.
The Application container has the Group and Button controls as its children,
and therefore has two children.</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- containers\intro\VBoxNumChildren.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
// Import the Alert class.
import mx.controls.Alert;
public function calculateChildren():void {
var myText:String = new String();
myText="The Group container has " +
myGroup.numElements + " children.";
myText+="\nThe application has " +
numElements + " children.";
Alert.show(myText);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:VGroup id="myGroup"&gt;
&lt;s:Label text="This is label 1."/&gt;
&lt;s:Label text="This is label 2."/&gt;
&lt;s:Label text="This is label 3."/&gt;
&lt;s:Label text="This is label 4."/&gt;
&lt;s:Label text="This is label 5."/&gt;
&lt;/s:VGroup&gt;
&lt;s:Button label="Show Children" click="calculateChildren();"/&gt;
&lt;/s:Application&gt;</pre>
<p>In the main MXML application
file, the file that contains the <samp class="codeph">&lt;s:Application&gt;</samp> tag,
the current scope is always the Application object. Therefore, the
reference to the <samp class="codeph">numElements</samp> property without an
object prefix refers to the <samp class="codeph">numElements</samp> property
of the Application object. For more information on accessing the
root application, see <a href="flx_usingas_ua.html#WS2db454920e96a9e51e63e3d11c0bf69084-7e3e_verapache">About
scope</a>.</p>
</div>
<div class="section" id="WS2AD35652-B62C-46fb-93DD-853582281180_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7e3f_verapache"><a name="WS2AD35652-B62C-46fb-93DD-853582281180_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7e3f_verapache"><!-- --></a><h4 class="sectiontitle">Accessing
display-only children</h4>
<p>The MX Container class defines the <samp class="codeph">rawChildren</samp> property
that contains the full display list of all the children of a container.
This list includes all the container’s children, plus the DisplayObjects
that implement the container’s <em>chrome</em> (display elements),
such as its border and the background image. </p>
<p>The <samp class="codeph">numChildren</samp> property
and accessor methods let you count and access only child components.
However, the container might contain style elements and skins, such
as the border and background. The container’s <samp class="codeph">rawChildren</samp> property
lets you access all children of a container, including the component “content
children” and the skin and style “display children.” The object
returned by the <samp class="codeph">rawChildren</samp> property implements
the IChildList interface. You then use methods and properties of
this interface, such as <samp class="codeph">getChildAt()</samp>, to access and
manipulate all the container’s children. </p>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf62b90-7fe5_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf62b90-7fe5_verapache"><!-- --></a>
<h3 class="topictitle3">Creating and removing components
at run time</h3>
<div>
<p>To create a component instance at run time, you define
it, set any properties, and then add it as a child of a parent container
by calling the <samp class="codeph">addElement()</samp> or <samp class="codeph">addChild()</samp> method
on the parent container. </p>
<p>The <samp class="codeph">addElement()</samp> method has the following signature:</p>
<div class="p">
<pre class="codeblock">addElement(element:IVisualElement):IVisualElement</pre>
</div>
<p>The <samp class="codeph">element</samp> argument specifies the component
to add to the container. </p>
<p>The <samp class="codeph">addChild()</samp> method has the following signature:</p>
<pre class="codeblock"> addChild(<em>child</em>:DisplayObject):DisplayObject </pre>
<p>The <samp class="codeph">child</samp> argument specifies the component to
add to the container. </p>
<div class="note"><span class="notetitle">Note:</span> Although the <samp class="codeph">child</samp> argument
of the <samp class="codeph">addChild()</samp> method is specified as type DisplayObject,
the argument must implement the IUIComponent interface to be added
as a child of a container. All Flex components implement this interface.</div>
<p>For example, the following application creates a Group container
with an Button control called myButton:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- containers\intro\ContainerAddChild.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import spark.components.Button;
public function addButton():void {
var myButton:Button = new Button();
myButton.label = "New Button";
myGroup.addElement(myButton);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:Group id="myGroup" initialize="addButton();"/&gt;
&lt;/s:Application&gt;</pre>
<p>This example creates the control when the application is loaded
rather than in response to any user action. However, you could add
a new button when the user presses an existing button, as the following
example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- containers\intro\ContainerAddChild2.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import spark.components.Button;
public function addButton():void {
var myButton:Button = new Button();
myButton.label = "New Button";
myGroup.addElement(myButton);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:HGroup id="myGroup"&gt;
&lt;s:Button label="Add Button" click="addButton();"/&gt;
&lt;/s:HGroup&gt;
&lt;/s:Application&gt;</pre>
<p>You use the <samp class="codeph">removeElement()</samp> or <samp class="codeph">removeChild()</samp> method
to remove a control from a container. If the child is no longer
referenced anywhere else in your application after the call, it
gets destroyed by a garbage collection process. The following example
removes a button from the application when the user presses it:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- containers\intro\ContainerRemoveChild.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
public function removeButton():void {
myGroup.removeElement(myButton);
}
private function resetApp():void {
if (myGroup.numElements == 0) {
myGroup.addElement(myButton);
}
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:Group id="myGroup"&gt;
&lt;s:Button id="myButton"
label="Remove Me"
click="removeButton();"/&gt;
&lt;/s:Group&gt;
&lt;s:Button label="Reset" click="resetApp();"/&gt;
&lt;/s:Application&gt;</pre>
<p>For additional methods that you can use with container children,
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>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf62b90-7fe5_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7e3d_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf62b90-7fe5_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7e3d_verapache"><!-- --></a><h4 class="sectiontitle">Example:
Creating and removing a child of a container</h4>
<p>The following
example uses MXML to define a container that contains two Button
controls. You use one Button control to add an CheckBox control
to the container, and one Button control to delete it. </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- containers\intro\ContainerComponentsExample.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
// Import the CheckBox class.
import spark.components.CheckBox;
// Define a variable to hold the new CheckBox control.
private var myCheckBox:CheckBox;
// Define a variable to track if the CheckBox control
// is in the display list.
private var checkBoxDisplayed:Boolean = false;
public function addCB():void {
// Make sure the check box isn't being displayed.
if(checkBoxDisplayed==false){
// Create the check box if it does not exist.
if (!myCheckBox) {
myCheckBox = new CheckBox();
}
// Add the check box.
myCheckBox.label = "New CheckBox";
myGroup.addElement(myCheckBox);
checkBoxDisplayed=true;
}
}
public function delCB():void {
// Make sure a CheckBox control exists.
if(checkBoxDisplayed){
myGroup.removeElement(myCheckBox);
checkBoxDisplayed=false;
}
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:VGroup id="myGroup"&gt;
&lt;s:Button label="Add CheckBox"
click="addCB();"/&gt;
&lt;s:Button label="Remove CheckBox"
click="delCB();"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf62b90-7fe5_verapache__WS2db454920e96a9e51e63e3d11c0bf62b90-7fe3_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf62b90-7fe5_verapache__WS2db454920e96a9e51e63e3d11c0bf62b90-7fe3_verapache"><!-- --></a><h4 class="sectiontitle">Example:
Creating and removing children of an Accordion container</h4>
<div class="p">The
following example adds panels to and removes them from an MX Accordion container.
The Accordion container initially contains one panel. Each time
you select the Add HBox button, it adds a new HBox container to
the Accordion container. <div class="note"><span class="notetitle">Note:</span> MX navigators can only take MX containers
and the Spark NavigatorContent container as children. You cannot
use other Spark containers as direct children of a navigator container.
Instead, wrap the Spark container in an MX container on in a Spark
NavigatorContent container when adding the Spark container to a
navigator. </div>
</div>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- containers\intro\ContainerComponentsExample2.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
/* Import HBox class. */
import mx.containers.HBox;
/* Array of created containers. */
private var myHBoxes:Array = [];
public function addHBox():void {
/* Create new HBox container. */
var newHBox:HBox = new HBox();
newHBox.label="Label: " + String(myHBoxes.length);
/* Add it to the Accordion container, and to the
Array of HBox containers. */
myHBoxes.push(myAcc.addChild(newHBox));
}
public function delHBox():void {
/* If there is at least one HBox container in the Array,
remove it. */
if (myHBoxes.length&gt;= 1) {
myAcc.removeChild(myHBoxes.pop());
}
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:VGroup&gt;
&lt;mx:Accordion id="myAcc" height="150" width="150"&gt;
&lt;mx:HBox/&gt;
&lt;/mx:Accordion&gt;
&lt;s:Button label="Add HBox" click="addHBox();"/&gt;
&lt;s:Button label="Remove HBox" click="delHBox();"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf62b90-7fe2_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf62b90-7fe2_verapache"><!-- --></a>
<h3 class="topictitle3">Controlling child order</h3>
<div>
<p>You can control the order of children by adding them in
a specific order. You can also control them as follows:</p>
<ul>
<li>
<p>By using the <samp class="codeph">addElementAt()</samp> or <samp class="codeph">addChildAt()</samp> method
to specify where among the component’s children to add a child</p>
<div class="note"><span class="notetitle">Note:</span> As with the <samp class="codeph">addChild()</samp> method,
although the <samp class="codeph">child</samp> argument of the <samp class="codeph">addChildAt()</samp> method
is specified as type DisplayObject, the argument must implement
the IUIComponent interface to be added as a child of a container.
All Flex components implement this interface.</div>
</li>
<li>
<p>By using the <samp class="codeph">setElementAt()</samp> or <samp class="codeph">setChildIndex()</samp> method
to specify the location of a specific child among a component’s
children in the display list</p>
</li>
</ul>
<p>The following example modifies the previous example. It uses
the <samp class="codeph">addElementAt()</samp> method to add the CheckBox control
as the first child (index 0) of the VGroup. It also has a Reorder
children button that uses the <samp class="codeph">setChildIndex()</samp> method
to move a CheckBox control down the display list until it is the
last child in the VGroup container. </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- containers\intro\ContainerComponentsReorder.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
// Import the CheckBox and Alert classes.
import spark.components.CheckBox;
import mx.controls.Alert;
// Define a variable to hold the new CheckBox control.
private var myCheckBox:CheckBox;
// Define a variable to track if the CheckBox control
// is in the display list.
private var checkBoxDisplayed:Boolean = false;
public function addCB():void {
// Make sure the check box isn't being displayed.
if(checkBoxDisplayed==false){
// Create the check box if it does not exist.
if (!myCheckBox) {
myCheckBox = new CheckBox();
}
// Add the check box as the first child of the container.
myCheckBox.label = "New CheckBox";
myGroup.addElementAt(myCheckBox, 0);
checkBoxDisplayed=true;
}
}
public function delCB():void {
// Make sure a CheckBox control exists.
if(checkBoxDisplayed){
myGroup.removeElement(myCheckBox);
checkBoxDisplayed=false;
}
}
public function reorder():void {
// Make sure a CheckBox control exists.
if(checkBoxDisplayed==true)
{
// Don't try to move the check box past the end
// of the children. Because indexes are 0 based,
// the last child index is one less
// than the number of children.
if (myGroup.getElementIndex(myCheckBox) &lt; myGroup.numElements-1)
{
// Increment the checkBoxIndex variable and use it to
// set the index of the check box among the VBox children.
myGroup.setElementIndex(myCheckBox,
myGroup.getElementIndex(myCheckBox) + 1);
}
}
else {
Alert.show("Add the check box before you can move it");
}
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:VGroup id="myGroup"&gt;
&lt;s:Button label="Add CheckBox" click="addCB();"/&gt;
&lt;s:Button label="Remove CheckBox" click="delCB();"/&gt;
&lt;s:Button label="Reorder children" click="reorder();"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7de0_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7de0_verapache"><!-- --></a>
<h2 class="topictitle2">Flex coordinate systems</h2>
<div>
<p>In your application, you might have to determine the location
of a component, or modify its location at run time. Adobe Flash
and Flex support three coordinate systems for different purposes:</p>
<ul>
<li>
<p>global</p>
</li>
<li>
<p>local</p>
</li>
<li>
<p>content</p>
</li>
</ul>
<p>You can use Flex properties and methods to convert between coordinate systems.</p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf62b90-7fec_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf62b90-7fec_verapache"><!-- --></a>
<h3 class="topictitle3">About the coordinate systems</h3>
<div>
<p>
The
following table describes the coordinate systems: </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="d128852e3804">
<p>Coordinate system</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d128852e3810">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3804 ">
<p>global</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3810 ">
<p>Coordinates are relative to the upper-left
corner of the Stage in Adobe Flash Player and Adobe<sup>®</sup> AIR™, that is, the outermost edge of the application.</p>
<p>The
global coordinate system provides a universal set of coordinates
that are independent of the component context. Uses for this coordinate
system include determining distances between objects and as an intermediate
point in converting between coordinates relative to a subcontrol
into coordinates relative to a parent control. </p>
<p>The MouseEvent
class includes <samp class="codeph">stageX</samp> and <samp class="codeph">stageY</samp> properties
that are in the global coordinate system.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3804 ">
<p>local</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3810 ">
<p>Coordinates are relative to the upper-left
corner of the component. </p>
<p>Flex uses the local coordinate system
for mouse pointer locations; all components have <samp class="codeph">mouseX</samp> and <samp class="codeph">mouseY</samp> properties
that use the local coordinate system. </p>
<p>The MouseEvent class
includes localX and localY properties that are in the local coordinate
system. Also, the Drag Manager uses local coordinates in drag-and-drop
operations. The <samp class="codeph">doDrag()</samp> method’s <samp class="codeph">xOffset</samp> and <samp class="codeph">yOffset</samp> properties,
for example, are offsets relative to the local coordinates.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3804 ">
<p>content</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e3810 ">
<p>Coordinates are relative to the upper-left
corner of the component’s content. Unlike the local and global coordinates, the
content coordinates include all the component’s content area, including
any regions that are currently clipped and must be accessed by scrolling
the component. Thus, if you scrolled down a Canvas container by
100 pixels, the upper-left corner of the visible content is at position
0, 100 in the content coordinates.</p>
<p>You use the content coordinate
system to set and get the positions of children of a container that
uses absolute positioning. (For more information on absolute positioning,
see <a href="flx_size_position_sp.html#WS2db454920e96a9e51e63e3d11c0bf69084-7e5a_verapache">About
component positioning</a>.)</p>
<p>The UIComponent <samp class="codeph">contentMouseX</samp> and <samp class="codeph">contentMouseY</samp> properties
report the mouse pointer location in the content coordinate system.</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>The following image shows these coordinate systems and how they
relate to each other.</p>
<div class="figborder">
<img src="images/cn_coordinates_2.png" alt="Container coordinate systems and how they relate to each other."/>
<dl>
<dt class="dlterm">
<strong>A.</strong>
</dt>
<dd>Content bounds</dd>
<dt class="dlterm">
<strong>B.</strong>
</dt>
<dd>Component bounds</dd>
<dt class="dlterm">
<strong>C.</strong>
</dt>
<dd>Stage bounds</dd>
</dl>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf62b90-7feb_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf62b90-7feb_verapache"><!-- --></a>
<h3 class="topictitle3">Using coordinate properties and
methods</h3>
<div>
<p>In some cases, you have to convert positions between coordinate
systems. Examples where you convert between coordinates include
the following:</p>
<ul>
<li>
<p>The MouseEvent class has properties that provide the
mouse position in the global coordinate system and the local coordinates
of the event target. You use the content coordinates to specify
the locations in any container that uses absolute positioning, such
as an MX Canvas container or a Spark container that uses the BasicLayout
class. To determine the location of the mouse event within the Canvas
container contents, not just the visible region, determine the position
in the content coordinate system.</p>
</li>
<li>
<p>Custom drag-and-drop handlers might have to convert between
the local coordinate system and the content coordinate system when
determining an object-specific drag action; for example, if you
have a control with scroll bars and you want to know the drag (mouse)
location over the component contents. The example in <a href="flx_containers_intro_cn.html#WS2db454920e96a9e51e63e3d11c0bf69084-7e40_verapache">Example:
Using the mouse position in a Canvas container</a> shows this
use.</p>
</li>
<li>
<p>Custom layout containers, where you include both visual elements,
such as scroll bars or dividers, and content elements. For example,
if you have a custom container that draws lines between its children,
you have to know where each child is in the container’s content
coordinates to draw the lines.</p>
</li>
</ul>
<p>Often, you use mouse coordinates in event handlers; when you
do, you should keep in mind the following considerations: </p>
<ul>
<li>
<p>When you handle mouse events, it is best to use the coordinates
from the MouseEvent object whenever possible, because they represent
the mouse coordinates at the time the event was generated. Although
you can use the container’s <samp class="codeph">contentMouseX</samp> and <samp class="codeph">contentMouseY</samp> properties
to get the mouse pointer locations in the content coordinate system,
you should, instead, get the local coordinate values from the event
object and convert them to the content coordinate system.</p>
</li>
<li>
<p>When you use local coordinates that are reported in an event
object, such as the MouseEvent <samp class="codeph">localX</samp> and <samp class="codeph">localY</samp> properties,
remember that the event properties report the local coordinates
of the mouse relative to the event target. The target component
can be a subcomponent of the component in which you determine the
position, such as a UITextField inside a Button component, not the
component itself. In such cases, convert the local coordinates into
the global coordinate system first, and then convert the global coordinates
into the content coordinates container. </p>
</li>
</ul>
<div class="p">All Flex components provide read-only properties and methods
that enable you to use and convert between coordinate systems. The
following table describes these properties and methods:
<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="d128852e4056">
<p>Property or method</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d128852e4062">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e4056 ">
<div class="p">
<pre class="codeblock">contentMouseX</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e4062 ">
<p>Returns the <em>x</em> position of the mouse,
in the content coordinates of the component.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e4056 ">
<div class="p">
<pre class="codeblock">contentMouseY</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e4062 ">
<p>Returns the <em>y</em> position of the mouse,
in the content coordinates of the component.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e4056 ">
<div class="p">
<pre class="codeblock">contentToGlobal (<em>point</em>:Point):Point</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e4062 ">
<p>Converts a Point object with <em>x</em> and <em>y</em> coordinates
from the content coordinate system to the global coordinate system.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e4056 ">
<div class="p">
<pre class="codeblock">contentToLocal (<em>point</em>:Point):Point</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e4062 ">
<p>Converts a Point object from the content
coordinate system to the local coordinate system of the component.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e4056 ">
<div class="p">
<pre class="codeblock">globalToContent <em>(point</em>:Point):Point</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e4062 ">
<p>Converts a Point object from the global
coordinate system to the content coordinate system of the component.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e4056 ">
<div class="p">
<pre class="codeblock">globalToLocal <em>(point</em>:Point):Point</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e4062 ">
<p>Converts a Point object from the global
coordinate system to the local coordinate system of the component.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e4056 ">
<div class="p">
<pre class="codeblock">localToContent <em>(point</em>:Point):Point</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e4062 ">
<p>Converts a Point object from the local coordinate
system to the content coordinate system of the component.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e4056 ">
<div class="p">
<pre class="codeblock">localToGlobal <em>(point</em>:Point):Point</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d128852e4062 ">
<p>Converts a Point object from the local coordinate
system to the global coordinate system.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7e40_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7e40_verapache"><!-- --></a>
<h3 class="topictitle3">Example: Using the mouse position
in a Canvas container</h3>
<div>
<p>The following example shows the use of the <samp class="codeph">localToGlobal()</samp> and <samp class="codeph">globalToContent()</samp> methods
to determine the location of a mouse pointer within a Canvas container
that contains multiple child Canvas containers. </p>
<p>This example is artificial, in that production code would use
the MouseEvent class <samp class="codeph">stageX</samp> and s<samp class="codeph">tageY</samp> properties,
which represent the mouse position in the global coordinate system.
The example uses the <samp class="codeph">localX</samp> and <samp class="codeph">localY</samp> properties,
instead, to show how you can convert between local and content coordinates,
including how first converting to using the global coordinates ensures
the correct coordinate frame of reference.</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- containers\intro\MousePosition.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.controls.Alert;
// Handle the mouseDown event generated
// by clicking in the application.
private function handleMouseDown(event:MouseEvent):void {
// Convert the mouse position to global coordinates.
// The localX and localY properties of the mouse event contain
// the coordinates at which the event occurred relative to the
// event target, typically one of the
// colored internal Canvas containers.
// A production version of this example could use the stageX
// and stageY properties, which use the global coordinates,
// and avoid this step.
// This example uses the localX and localY properties only to
// illustrate conversion between different frames of reference.
var pt:Point = new Point(event.localX, event.localY);
pt = event.target.localToGlobal(pt);
// Convert the global coordinates to the content coordinates
// inside the outer c1 Canvas container.
pt = c1.globalToContent(pt);
// Figure out which quadrant was clicked.
var whichColor:String = "border area";
if (pt.x &lt; 150) {
if (pt.y &lt; 150)
whichColor = "red";
else
whichColor = "blue";
}
else {
if (pt.y &lt; 150)
whichColor = "green";
else
whichColor = "magenta";
}
Alert.show("You clicked on the " + whichColor);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;!-- Canvas container with four child Canvas containers --&gt;
&lt;mx:Canvas id="c1"
borderStyle="none"
width="300" height="300"
mouseDown="handleMouseDown(event);"&gt;
&lt;mx:Canvas
width="150" height="150"
x="0" y="0"
backgroundColor="red"&gt;
&lt;mx:Button label="I'm in Red"/&gt;
&lt;/mx:Canvas&gt;
&lt;mx:Canvas
width="150" height="150"
x="150" y="0"
backgroundColor="green"&gt;
&lt;mx:Button label="I'm in Green"/&gt;
&lt;/mx:Canvas&gt;
&lt;mx:Canvas
width="150" height="150"
x="0" y="150"
backgroundColor="blue"&gt;
&lt;mx:Button label="I'm in Blue"/&gt;
&lt;/mx:Canvas&gt;
&lt;mx:Canvas
width="150" height="150"
x="150" y="150"
backgroundColor="magenta"&gt;
&lt;mx:Button label="I'm in Magenta"/&gt;
&lt;/mx:Canvas&gt;
&lt;/mx:Canvas&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
<p>Adobe, Adobe AIR, Adobe Flash, 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>