A Canvas layout container defines a rectangular region in which you place child containers and controls. Unlike all other components, you cannot let Flex lay child controls out automatically. You must use absolute or constraint-based layout to position child components. With absolute layout you specify the x and y positions of the children; with constraint-based layout you specify side, baseline, or center anchors. For detailed information on using these layout techniques, see Sizing and Positioning Components.

For complete reference information, see the Adobe Flex Language Reference.

Creating and using a Canvas control

You define a canvas control in MXML by using the <mx:Canvas> tag. Specify an id value if you intend to refer to a component elsewhere in your MXML, either in another tag or an ActionScript block.

Creating a Canvas Control by using absolute positioning

You can use the x and y properties of each child to specify the child's location in the Canvas container. These properties specify the x and y coordinates of a child relative to the upper-left corner of the Canvas container, where the upper-left corner is at coordinates (0,0). Values for the x and y coordinates can be positive or negative integers. You can use negative values to place a child outside the visible area of the container, and then use ActionScript to move the child to the visible area, possibly as a response to an event.

The following example shows a Canvas container with three LinkButton controls and three Image controls:

The following MXML code creates this Canvas container:

<?xml version="1.0"?>
<!-- containers\layouts\CanvasSimple.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Canvas id="myCanvas" 
      height="200" width="200"
      borderStyle="solid" 
      backgroundColor="white">

      <mx:LinkButton label="Search" 
        x="10" y="30"
        click="navigateToURL(new URLRequest('http://www.adobe.com/cfusion/search/index.cfm'))"/>
      <mx:Image 
        height="50" width="50" 
        x="100" y="10"
        source="@Embed(source='assets/search.jpg')" 
        click="navigateToURL(new URLRequest('http://www.adobe.com/cfusion/search/index.cfm'))"/>

      <mx:LinkButton label="Help" 
        x="10" y="100"
        click="navigateToURL(new URLRequest('http://www.adobe.com/go/gn_supp'))"/>
      <mx:Image 
        height="50" width="50" 
        x="100" y="75"
        source="@Embed(source='assets/help.jpg')" 
        click="navigateToURL(new URLRequest('http://www.adobe.com/go/gn_supp'))"/>

      <mx:LinkButton label="Complaints" 
        x="10" y="170" 
        click="navigateToURL(
            new URLRequest('http://www.adobe.com/go/gn_contact'))"/>
      <mx:Image 
        height="50" width="50" 
        x="100" y="140"
        source="@Embed(source='assets/complaint.jpg')" 
        click="navigateToURL(
            new URLRequest('http://www.adobe.com/go/gn_contact'))"/>
    </mx:Canvas>
</mx:Application>
The executing SWF file for the previous example is shown below:

Creating a Canvas container by using constraint-based layout

You can also use constraint-based layout to anchor any combination of the top, left, right, bottom sides, and baseline of a child at a specific distance from the Canvas edges, or to anchor the horizontal or vertical center of the child at a specific (positive or negative) pixel distance from the Canvas center. To specify a constraint-based layout, use the top, bottom, left, right, baseline, horizontalCenter, and verticalCenter styles. When you anchor the top and bottom, or the left and right sides of the child container to the Canvas sides, if the Canvas control resizes, the children also resize. The following example uses constraint-based layout to position an HBox horizontally, and uses absolute values to specify the vertical width and position:

<?xml version="1.0"?>
<!-- containers\layouts\CanvasConstraint.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Canvas 
        width="150" height="150" 
        backgroundColor="#FFFFFF">

        <mx:HBox id="hBox2"
            left="30"
            right="30" 
            y="50" 
            height="50" 
            backgroundColor="#A9C0E7">
        </mx:HBox>
    </mx:Canvas>
</mx:Application>
The executing SWF file for the previous example is shown below:

The example produces the following image:

Preventing overlapping children

When you use a Canvas container, some of your components may overlap, because the Canvas container ignores its children's sizes when it positions them. Similarly, children components may overlap any borders or padding, because the Canvas container does not adjust the coordinate system to account for them.

In the following example, the size and position of each component is carefully calculated to ensure that none of the components overlap:

<?xml version="1.0"?>
<!-- containers\layouts\CanvasOverlap.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
    width="100" height="100" 
    backgroundGradientColors="[0xFFFFFF, 0xFFFFFF]">

    <mx:Script>
        <![CDATA[
            [Embed(source="assets/BlackBox.jpg")]
            [Bindable]
            public var imgCls:Class;
        ]]>
    </mx:Script> 
    
    <mx:Canvas id="chboard" backgroundColor="#FFFFFF">
        <mx:Image source="{imgCls}" 
            width="10" height="10" x="0" y="0"/>
        <mx:Image source="{imgCls}" 
            width="10" height="10" x="20" y="0"/>
        <mx:Image source="{imgCls}" 
            width="10" height="10" x="40" y="0"/>
        <mx:Image source="{imgCls}" 
            width="10" height="10" x="10" y="10"/>
        <mx:Image source="{imgCls}" 
            width="10" height="10" x="30" y="10"/>
        <mx:Image source="{imgCls}" 
            width="10" height="10" x="0" y="20"/>
        <mx:Image source="{imgCls}" 
            width="10" height="10" x="20" y="20"/>
        <mx:Image source="{imgCls}" 
            width="10" height="10" x="40" y="20"/>
        <mx:Image source="{imgCls}" 
            width="10" height="10" x="10" y="30"/>
        <mx:Image source="{imgCls}" 
            width="10" height="10" x="30" y="30"/>
        <mx:Image source="{imgCls}" 
            width="10" height="10" x="0" y="40"/>
        <mx:Image source="{imgCls}" 
            width="10" height="10" x="20" y="40"/>
        <mx:Image source="{imgCls}" 
            width="10" height="10" x="40" y="40"/>
    </mx:Canvas>
</mx:Application>
The executing SWF file for the previous example is shown below:

This example produces the following image:

If you set the width and height properties of one of the images to 20 pixels but don't change the positions accordingly, that image overlaps other images in the checkerboard. For example, if you replace the seventh <mx:Image> tag in the preceding example with the following line, the resulting image looks like the following image:

<mx:Image source="{imgCls}" width="10" height="10" x="20" y="20"/>

Repositioning children at run time

You can build logic into your application to reposition a child of a Canvas container at run time. For example, in response to a button click, the following code repositions an input text box that has the id value text1 to the position x=110, y=110:

<?xml version="1.0"?>
<!-- containers\layouts\CanvasRepos.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Canvas 
        width="300" height="185" 
        backgroundColor="#FFFFFF">

        <mx:TextInput id="text1" 
            text="Move me" 
            x="10" y="10"
        />
        <mx:Button id="button1" 
            label="Move text1" 
            x="10" y="150" 
            click="text1.x=110; text1.y=110;"
        />
        <mx:Button label="Reset" click="text1.x=10; text1.y=10;" x="111" y="150"/>
    </mx:Canvas>
</mx:Application>
The executing SWF file for the previous example is shown below: