Flex 2 Developer's Guide > Building User Interfaces for
Flex Applications > Using Controls > Image control

Image control

Adobe Flex supports several image formats, including GIF, JPEG, PNG, SVG, and SWF files. You can import these images into your applications by using the Image control.

NOTE

Flex also includes the SWFLoader control for loading Flex 2 applications. You typically use the Image control for loading static graphic files and SWF files, and use the SWFLoader control for loading Flex 2 applications. The Image control is also designed to be used in custom item renderers and item editors. For more information on the SWFLoader control, see SWFLoader control.

Subtopics

About importing images

SVG drawing restrictions

Controlling image importing with the Image control

Techniques for using the Image control

About importing images

Flex supports importing GIF, JPEG, PNG, and SWF files at run time, and embedding GIF, JPEG, PNG, SVG, and SWF at compile time. The method you choose depends on the file types of your images and your application parameters.

Embedded images load immediately, because they are already part of the Flex SWF file. However, they add to the size of your application and slow down the application initialization process. Embedded images also require you to recompile your applications whenever your image files change. For an overview of resource embedding, see Embedding Assets.

The alternative to embedding a resource is to load the resource at run time. You can load a resource from the local file system in which the SWF file runs, or you can access a remote resource, typically though an HTTP request over a network. These images are independent of your Flex application, so you can change them without causing a recompile operation as long as the names of the modified images remain the same. The referenced images add no additional overhead to an application's initial loading time. However, you might experience a delay when you use the images and load them into Adobe Flash Player.

A SWF file can access one type of external resource only, either local or over a network; it cannot access both types. You determine the type of access allowed by the SWF file using the use-network flag when you compile your application. When use-network flag is set to false, you can access resources in the local filesystem, but not over the network. The default value is true, which allows you to access resources over the network, but not in the local filesystem.

For more information on the use-network flag, see Using the Flex Compilers in Building and Deploying Flex 2 Applications.

When you load images at run time, you should be aware of the security restrictions of Flash Player. For example, you can reference an image by using a URL, but the default security settings only permit Flex applications to access resources stored on the same domain as your application. To access images on other servers, you must use a crossdomain.xml file.

For more information on application security, see Applying Flex Security in Building and Deploying Flex 2 Applications.

SVG drawing restrictions

You should be aware of the following restrictions when working with SVG files in Flex:

You can only embed an SVG file in an application; you cannot load one at run time
SMIL and animation are not supported
Masking and filters are not supported
Pattern Fill and some advanced Gradients are not supported
Interactivity and scripting is not supported
SVG text is rendered as nonsearchable and nonselectable SWF shape outlines, meaning it is not rendered as native text in Flash Player

Controlling image importing with the Image control

The Image control supports the following actions when you import an image:

Specifying the image path

The value of the source property of an Image control specifies a relative or absolute path, or URL to the imported image file. If the value is relative, it is relative to the directory that contains the file that uses the tag. For more examples, see Specifying the image path.

The source property has the following forms:

source="@Embed(source='relativeOrAbsolutePath')"
The referenced image is packaged within the generated SWF file at compile-time when Flex creates the SWF file for your application. You can embed GIF, JPEG, PNG, SVG, and SWF files. When you embed an image, the value of the source property must be a relative or absolute path to a file on your local file system; it cannot be a URL.

The following example embeds a JPEG image into a Flex application:
```
<?xml version="1.0"?>

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Image id="loader1" source="@Embed(source='logo.jpg')"/> 
</mx:Application>
```
In this example, the size of the image is the default size of the image file.
source="relativeOrAbsolutePathOrURL"
Flex loads the referenced image file at run time; it is not packaged as part of the generated SWF file. You can only reference GIF, JPEG, PNG, and SWF files. When use-network flag is set to false, you can access resources in the local filesystem, but not over the network. The default value is true, which allows you to access resources over the network, but not in the local filesystem.

The following example access a JPEG image at run time:
```
<?xml version="1.0"?>

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Image id="loader1" source="logo.jpg"/> 
</mx:Application>
```
Because you did not use @Embed in the source property, Flex loads the image at run time.

In many applications, you create a directory to hold your application images. Commonly, that directory is a subdirectory of your main application directory. The source property supports relative paths to images, which lets you specify the location of an image file relative to your application directory.

The following example stores all images in an assets subdirectory of the application directory:

<?xml version="1.0"?>
<!-- controls\image\ImageSimpleAssetsDir.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Image id="loader1" source="@Embed(source='assets/logo.jpg')"/> 
</mx:Application>

The following example uses a relative path to reference an image in an assets directory at the same level as the application's root directory:

<?xml version="1.0"?>
<!-- controls\image\ImageSimpleAssetsDirTop.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Image id="loader1" source="@Embed(source='../assets/logo.jpg')"/> 
</mx:Application>

You can also reference an image using a URL, but the default security settings only permit Flex applications to access resources stored on the same domain as your application. To access images on other servers, you must use a crossdomain.xml file.

The following example shows how to reference an image using a URL:

<?xml version="1.0"?>
<!-- controls\image\ImageSimpleAssetsURL.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Image id="image1" 
        source="http://localhost:8100/flex/assets/logo.jpg"/> 
</mx:Application>

NOTE

You can use relative URLs for images hosted on the same web server as the Flex application, but you must load these images over the Internet rather than access them locally.

Using an image multiple times

You can use the same image multiple times in your application by using the normal image import syntax each time. Flex only loads the image once, and then references the loaded image as many times as necessary.

Sizing an image

Flex sets the height and width of an imported image to the height and width settings in the image file. By default, Flex does not resize the image.

To set an explicit height or width for an imported image, set its height and width properties of the Image control. Setting the height or width property prevents the parent from resizing it. The scaleContent property has a default value of true, therefore, Flex scales the image as it resizes it to fit the specified height and width. The aspect ratio is maintained by default, so the image may not completely fill the designated space. Set the scaleContent property to false to disable scaling. Set the maintainAspectRatio property to false to allow an image to fill all available space regardless of its dimensions. For more information about image aspect ratios, see Maintaining aspect ratio when sizing.

To let Flex resize the image as part of laying out your application, set the height or width properties to a percentage value. Flex attempts to resize components with percentage values for these properties to the specified percentage of their parent container. You can also use the maxHeight and maxWidth and minHeight and minWidth properties to limit resizing. For more information on resizing, see Introducing Containers.

One common use for resizing an image is to create image thumbnails. In the following example, the image has an original height and width of 100 by 100 pixels. By specifying a height and width of 20 by 20 pixels, you create a thumbnail of the image.

<?xml version="1.0"?>
<!-- controls\image\ImageSimpleThumbnail.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Image id="image1" 
        source="logo.jpg" 
        width="20" height="20"/>
    <mx:Image id="image2" 
        source="logo.jpg"/>
</mx:Application>

Flex 2.01