Chapter 4: The Display List

One of the most dramatic changes introduced by ActionScript 3.0, particularly for designers accustomed to prior versions of ActionScript, is the way in which visual elements are added to an application at runtime. In prior versions of ActionScript, a separate approach was used to add most kinds of visual assets at runtime, requiring varied syntax. Management of those assets—particularly depth management—and creating and destroying objects, were also fairly restrictive and could be relatively involved depending on what you were trying to accomplish.

ActionScript 3.0 brings with it an entirely new way of handling visual assets. It's called the display list. It's a hierarchical list of all visual elements in your file. It includes common objects such as movie clips, but also objects such as shapes and sprites that either didn't previously exist or could not be created programmatically.

In this chapter, we'll look at the following topics:

• The Sum of Its Parts. Understanding the display list means understanding its parts. In addition to knowing the kinds of objects that can be part of the display list, it's also important to grasp the simple difference between display objects and display object containers.
• Adding and Removing Children. The best part of the display list is how easy and consistent it is to add objects to, and remove objects from, the list.
• Managing Object Names, Positions, and Data Types. In addition to adding and removing display objects, you will need to manipulate existing members of the display list. You will likely need to find an object, either by name or position in the list, or even identify an object's data type as a particular display object class.
• Changing the Hierarchy. It's also much easier than ever before to manage asset depths (z-order, or the visual stacking order controlled by ActionScript, rather than timeline layers), and to change the familial relationship of assets. Moving a child from one parent to another is a breeze.
• A Dynamic Navigation Bar. As a quick demonstration of using the display list, we'll show you how to dynamically generate a very simple navigation bar.

This excerpt is from Learning ActionScript 3.0. Learning ActionScript 3.0 gives you a solid foundation in the Flash language and demonstrates how you can use it for practical, everyday projects. The book does more than give you a handful of sample scripts, defining how ActionScript and Flash work. It gives you a clear look into essential topics such as logic, event handling, displaying content, migrating legacy projects to ActionScript 3.0, classes, and much more. Written for those new to the language, this book doesn't rely exclusively on prior knowledge of object-oriented programming (OOP). Instead, it helps you expand your skillset by first focusing on clear, concise examples in the timeline, evolving into OOP examples over time-allowing you to choose the programming approach with which you are most comfortable.

Section 4.1: The Sum of Its Parts

Figure 4-1: The visual layout of the simple file structure

If you start thinking about the display list by thinking about what you see in any given application, you're half-way home. In addition to contributing to the structure of the new event model, discussed in , the display list is responsible for maintaining the visual and spatial assets in your file. You will use the display list to create and destroy visual assets, to manage their coexistence, and manage how they interrelate.

Let's take a look at the contents of the display list of a simple file structure. shows that this file has a shape, a text element, and a movie clip, and inside the movie clip is a bitmap. shows the display list of the same structure.

At the top of the list is the stage. Although you can access the stage from many objects in the display list, it's easiest to think of the stage as the foundation on which everything is built. It also helps to think of the stage as the ultimate container within which all your visual assets reside at runtime. The container analogy will soon become central to this discussion. The stage contains everything.

Figure 4-2: The display list of the sample filee

Next is the main timeline, which is also referenced using the root display object instance variable. (See the sidebar, "_root versus root" for more information.) Like the stage, a Flash file requires one timeline within which all other assets are contained. Because of event propagation, it is common to use the main timeline as a location to add event listeners when writing scripts in the timeline. In that context, the main timeline is typically referenced using the this identifier, as in "this object being currently referenced within the context of the script." (For more information about event listeners and event propagation, see . For more information about this, see Chapter 2.)

Below the main timeline in the display list hierarchy are all the visual assets in the file. Included in the sample display list are the aforementioned shape, text, and movie clip assets, and inside the movie clip is the bitmap.

You may notice in that everything is subtitled as a display object or display object container. This is key to understanding and working with the display list effectively. It probably follows that everything in the display list is a display object. However, some display objects can contain other elements and therefore also display object containers.

For example, a shape is a display objects, as are bitmaps and videos. However, none of these items can have children, so the display list lineage ends there. A movie clip can have children, such as other movie clips therein. Therefore, although a movie clip is a display object, it is also a display object container. This concept of display objects also possibly being containers is useful when traversing the display list, determining whether a display object has children, moving a child from one parent to another, and so on.

Display List Classes

In just a moment, we'll walk through a typical ActionScript display list that demonstrates the distinction between display objects and display object containers. First, however, take a look at the individual classes that contribute to the display list, as shown in Figure 4-3.

Figure 4-3: The Display List classes

We discussed classes in Chapter 1, and we'll be using them extensively as we delve deeper into the book. For now, however, and in this context, just think of these classes as objects that can be part of the display list. As you look through Figure 4-3, for instance, you'll recognize Shape, Bitmap, Video, and so on.