Displaying images with the TileList component

The ActionScript 3.0 TileList component presents images or other display objects as tiles that are arranged in rows and columns. A tile is the intersection of a row and a column and is also commonly called a cell in list-based components. You can specify the number of rows and columns that are visible in the tile list and scroll either vertically or horizontally to view content that extends beyond its borders.

A TileList object uses a cell renderer class to display each tile. The default cell renderer for the TileList component is the ImageCell class, which displays a thumbnail image and a single-line text label. The following example represents a typical TileList application.

To get the source files for this example, download TileList_basic.zip from the top of this page.

This article covers the following topics: adding the TileList component to your application, using a data provider to add content to a TileList component, merging and sorting TileList data providers, calculating TileList cell layout, customizing the TileList component using styles, and customizing tile appearance using a custom cell renderer.

You can add an instance of the TileList component to your application either at authoring time using Flash or at runtime by using ActionScript 3.0. The following procedures show how to add a tile list containing four images to a Flash application.

This example uses the addItem() method, which TileList inherits from the SelectableList class, to add content to the TileList instance. By default, the label property of an item is used to display the label of the item and the source property holds the data for the item.

To add the TileList component to your application during authoring:

1. Create a new Flash file (ActionScript 3.0).
2. Drag a TileList component to the Stage and enter the following values for it in the Property inspector (Window > Properties):
   • Give it an instance name of myTileList.
   • Set X to 50.
   • Set Y to 50.
3. With the TileList component still selected, enter the following values for it in the Component inspector (Window > Component Inspector):
   • Set the direction parameter to vertical.
   • Set the columnCount parameter to 1.
   • Set the columnWidth parameter to 200.
   • Set the rowCount parameter to 1.
   • Set the rowHeight parameter to 140.
4. Open the Actions panel (Window > Actions), select Frame 1 in the main Timeline, and enter the following ActionScript code, which adds four images to the TileList instance:

5. Select Control > Test Movie to run the application. You see a tile list with four images in it as shown previously in this article

The following procedure uses ActionScript to add a TileList instance to the application at runtime. It also dynamically sets the position of the tile list, the column width and row height, and the number of columns and rows that are visible.

To add the TileList component to your application using ActionScript

1. Create a new Flash file (ActionScript 3.0).
2. Drag the TileList component from the Components panel to the Library panel.
3. Open the Actions panel, select Frame 1 in the main Timeline, and enter the following ActionScript code:

4. Select Control > Test Movie to run the application.

Result

To get the source files for this example, download TileList_AS.zip at the top of this page.

In addition to using the TileList addItem() method, you can add content to a TileList by setting its dataProvider property. The property accepts a DataProvider object that represents the data model of the items to be viewed in the tile list. A data provider is a data source that is typically a linear collection of data such as an Array or an XML object. Using a DataProvider object is a more powerful way to add content to a tile list because its API also allows you to access, remove, merge, and sort items.

Using the Values collection dialog box

The easiest way to create a data provider for the TileList component is by assigning values to the dataProvider parameter in the Component inspector. When you double-click the dataProvider parameter, Flash displays the Values collection dialog box.

For each item that you want to assign to the TileList, click the Plus sign (+) to add a new item and enter values for the label and the source parameters. The source value specifies the content that you want to appear in a tile and the label allows you to add a text label to it. Click the Minus sign (–) to delete an item or click the up or down arrows to move items up or down in the list. The following example adds to the tile list the same items that we saw in the preceding examples.

Using ActionScript

Another way to create a DataProvider object is with ActionScript. Use the new operator with the DataProvider class constructor function, passing the data source as an argument. The data source can be an array or an XML object that contains the data items. The following example creates a DataProvider using an array as the data source:

1. Create a new Flash file (ActionScript 3.0).
2. Drag the TileList component from the Components panel to the Stage and give it an instance name of myTileList.
3. Open the Actions panel, select Frame 1 in the main Timeline, and enter the following ActionScript code:

4. Select Control > Test Movie to run the application.

The following ActionScript code supplies the same content in an ActionScript 3.0 XML object instead of an array. It also sets the scroll direction to horizontal and reverses the columnCount and rowCount values.

Result

To get the source files for this example, download TileList_XML.zip at the top of this page.

The following example adds movie clips to a tile list and shows how to merge and sort data providers as well as how to remove items using the removeAll() method. It uses two DataProvider objects—one for boxes (boxesDp) and one for circles (circlesDp)—to add content to a TileList instance. The example also includes a button that provides for user interaction. Initially, the example calls the loadBoxes() and loadCircles() methods to load the two data providers and fill the tile list with an array of colored boxes. It also sets the button's label to "Merge Circles" and creates an event handler (buttonClickHandler()) that is invoked when the user clicks the button.

When the user clicks the Merge Circles button the buttonClickHandler() method does the following:

• Merges the array of circles into the tile list using the circlesDp DataProvider
• Sorts the TileList content in ascending order by the value of the label
• Sets the button's label to "Sort Descending"

When the user clicks the Sort Descending Button, the buttonClickHandler() method sorts the boxes and circles in descending order by the value of the label and sets the Button's label to "Restore".

When the user clicks the Restore button the buttonClickHandler() method does the following:

• Calls the removeAll() method to delete the contents of the tile list
  
• Calls the loadBoxes() method to restore the initial content to the tile list
  
• Restores the button's label to "Merge Circles"

Follow these steps to implement the example.

1. Create a new Flash file (ActionScript 3.0).
2. Drag the TileList component from the Components panel to the Stage and give it an instance name of myTileList.
3. Drag the Button component from the Components panel to the Stage, give it an instance name of mergeButton and set its label parameter to Merge Circles.
4. Open the Actions panel, select Frame 1 in the main Timeline, and enter the following ActionScript code:

5. Select Control > Test Movie to run the application.

Result

To get the source files for this example, download TileList_merge.zip from the top of this page.

The TileList component provides the following properties that affect the layout of columns and rows and the size of the TileList: columnCount, columnWidth, direction, rowCount, rowWidth and the height and width properties inherited from the UIComponent class. In addition, you can also use the contentPadding style to add padding to the perimeter of the TileList instance. The contentPadding style is described in more detail in the following section on using styles.

To ensure that the tile list's cells lay out the way you want them, Adobe makes the following recommendations:

• Set the columnCount and rowCount properties after you set the columnWidth, rowHeight, and dataProvider properties. The columnCount and rowCount values initially affect the width and height of the component but the component does not maintain them. If they are set with the Property inspector, they are maintained until the component is first drawn.
• Ensure that the height and width values for the component are in agreement with the columnCount, columnWidth, rowCount, rowHeight, and contentPadding values

In other words, the width that you specify for the component should equal the value of columnCount times the value of columnWidth, plus 2 times the value of contentPadding, plus 15 pixels for the width of the scroll bar if the direction property is vertical, causing the scroll bar to appear on the right side of the tile list. Likewise, the height of the tile list should equal the value of rowCount times the value of rowHeight, plus 2 times the value ofcontentPadding, plus 15 pixels for the width of the scroll bar if the direction is horizontal. When the direction is horizontal, the scroll bar appears at the bottom of the TileList. You can use the following formulas to calculate the values for the width and height properties:

width = columnWidth × columnCount + (contentPadding × 2) + 15 if scroll bar direction is vertical
height = rowHeight × rowCount + (contentPadding × 2) + 15 if scroll bar direction is horizontal

For example, the property values shown in the following table would result in the width and height values shown in the last two rows.

Note: The contentPadding value affects both the top and bottom and the right and the left sides of the tile list so you must multiply its value by 2 in calculating the width and the height. Also, the scroll bar only takes effect if the contents exceed the boundaries of the tile list. If the contents will not exceed the boundaries of the tile list, you do not need to account for the 15-pixel width of the scroll bar.

You can customize cell content by setting styles for the tile list. For example, you can change the size and appearance of the labels or assign a value to contentPadding styles to create a border around the content. You can add custom content to the TileList either by extending the CellRenderer class or by implementing the ICellRenderer interface to create a custom cell renderer class. For example, you might want to display a different type of data or alter the appearance of the skins.

The following example creates custom labels and adds padding for the images in a tile list. It creates a TextFormat object and sets its font, color, bold, and size properties to specify the textFormat style for the TileList labels. The example uses the setRendererStyle() method to apply the textFormat style to the tiles, but not to the overall TileList. The setStyle() method sets a text format for the TileList component and all of its tiles; the setRendererStyle() method overrides the text format for the tiles themselves.

The example also sets the contentPadding and imagePadding styles. The contentPadding style is a TileList style that is set with the setStyle() method. It adds a border of the specified number of pixels to the perimeter of the tile list. The imagePadding style is an ImageCell style. The ImageCell class is the default cell renderer for the TileList component. The imagePadding style creates white space of the specified number of pixels around each image in the tile list. This setting reduces the size of the images and does not affect the dimensions of the TileList instance.

To set the textFormat, contentPadding, and imagePadding styles for the TileList images

1. Create a new Flash file (ActionScript 3.0).
2. Drag the TileList component from the Components panel to the Library panel.
3. Open the Actions panel, select Frame 1 in the main Timeline, and enter the following ActionScript code:

Result

To get the source files for this example, download TileList_style.zip from the top of the page.

To display custom cell content, you can create a custom cell renderer class in ActionScript that extends the CellRenderer class or implements the ICellRenderer interface.

The following example creates a custom cell renderer, called MyRenderer, by extending the ImageCell class, which is the default cell renderer class for the TileList. The MyRenderer class creates a static background for the TileList by setting each of the state skins (up, down, over, etc.) to the same skin. It also eliminates the scroll bar and the text overlay, which normally appears behind the label, by setting the scrollPolicy property to off and setting the ImageCell's textOverlayAlpha style to 0.0 to make the overlay transparent. The result of these settings produces a static palette for the images. The example also raises the label from the bottom edge of the image by setting the textPadding style to 15.

There are two parts to this example:

1. the application, which creates a TileList and adds content to it, and
2. the custom cell renderer class, MyRenderer.

The following steps create the application.

1. Create a new Flash file (ActionScript 3.0).
2. Drag the TileList component from the Components panel to the Library panel.
3. Create a new symbol called lightBackground and in its symbol properties, check the box that says Export for ActionScript. Leave the class name as lightBackground.
4. In the new symbol, create a filled rectangle that is 10 pixels wide and 10 pixels tall, without a line border. Select a color for the symbol that reflects its
   name (for example, #66AAAA). Leave the symbol at x-coordinate 0 and y-coordinate 0.
5. Duplicate the lightBackground symbol and name the duplicate symbol mediumBackground. In its symbol properties, check the box that says Export for ActionScript. Leave the class name as mediumBackground. Edit the mediumBackground symbol and change the rectangle's color to something darker, like #338888.
6. Duplicate the mediumBackground symbol and name the duplicate symbol darkBackground. In its symbol properties, check the box that says Export for ActionScript. Leave the class name as darkBackground. Edit the darkBackground symbol and change the rectangle's color to something even darker, like #006666.
7. Open the Actions panel, select Frame 1 in the main Timeline, and enter the following ActionScript code:

8. Save the application and give it a name, such as TileList_render.fla

The next set of steps create the custom cell renderer class, MyRenderer.

1. Create a new ActionScript file.
2. Enter the following ActionScript code in the ActionScript window.

3. Save the document as MyRenderer.as in the same folder where you saved the FLA file.

To run the application:

1. Return to the application document in Flash.
2. Select Control > Test Movie to run the application.
   

Result

To get the source files for this example, download TileList_render.zip from the top of the page.

For more information about this topic, see "Use the TileList component" in Using ActionScript 3.0 Components and the TileList class in the ActionScript 3.0 Component and Language Reference.

Related Flash Quick Starts

• Using the Button component
• Using the Label component
• Getting started with Flash CS4 user interface components
• Creating, populating, and resizing the DataGrid component
• Customizing and sorting the DataGrid component
• Filtering and formatting data in the DataGrid component