Macromedia Flash8 Bible

Flash 8 includes several User Interface (or UI) components, which provide user interface elements and functionality frequently used by developers. You should be able to find a use for some or all of these components at one time or another. Let's take a look at what each of the core UI components does and how to use them in your movies. After dragging any component instance to your Stage, open up the Property inspector and select the Parameters tab to view the parameters discussed in this section.

The parameters for each component we discuss in the following sections are also the respective names of each component's properties. Note that not all of a component's properties may be exposed in the Property inspector.

Button Component

This component is essentially a standard button with built-in up, over, and down states. The button is designed to resemble an HTML form button (such as a submit button), but with the Halo theme for V2 components. The Button component, shown in Figure 33-7, is very easy to use and can aid in quick development of mockups or be modified to suit more aesthetically inclined productions.

Figure 33-7: The Button component as it appears in a Flash movie at run time

Parameters

The Button parameters are perhaps some of the easiest to manage. As with other components, you can enter text for the button's label and set a function to execute when the button is pressed.

• icon: This optional parameter specifies the linkage ID of a symbol in the Library that will appear next to the label text of the button. The placement of the label in relation to the icon symbol is determined by the labelPlacement parameter (discussed later in this list).

• label: This is the text appearing on the button face. The default text is simply "Button."

• labelPlacement: This optional parameter is a menu with left, right, top, or bottom options. This setting determines how the label text is aligned to the button's icon symbol. The default value is right. If you do not use an icon symbol for the instance, this setting has no effect.

• selected and toggle: These two parameters work together to enable a Button component instance to act as an on/off button. As a toggle button, the rim of the instance displays an "on" color (green is the default Halo theme) if selected is set to true. The selected property has no effect if toggle is not set to true. The default value for both the selected and toggle parameters is false.

How it Works

An instance of a Button component can have regular, disabled, or active states, which can be customized graphically. It is a very quick way to add interactivity to your movie. For additional functionality of the button, you will need to write ActionScript using the Button methods.

CheckBox Component

The CheckBox component, as the name implies, is a user interface element that has a selection box next to text. As with HTML form check boxes, the CheckBox component enables you to easily add form options to a Flash movie. The CheckBox component returns a true or false value. If the box is checked, it returns a true value; if not, it returns false. These states are shown in Figure 33-8.

Figure 33-8: A selected (true) check box, left, and a cleared (false) check box, right

Parameters

CheckBox parameters can be changed to customize the default label text and its placement in relation to the check box graphic. You can also set the initial state and have the option of setting a function, executing as soon as the button state changes.

• label: This is the name appearing next to the check box. The default value is set to "CheckBox."

• labelPlacement: This parameter sets the label to the left, right (default), top, or bottom of the check box.

  Tip

  Make sure to set the height of the instance appropriately to accommodate top and bottom alignment.

• selected: Assigning a true value checks the box initially, although the default value for this is set to false (unchecked).

How it Works

The CheckBox component has a hit area that encompasses the check box itself, as well as the label next to it. The width of a CheckBox instance can be transformed to accommodate more text. Added functionality using ActionScript is possible by using the methods, events, and properties of the CheckBox class.

ComboBox Component

The ComboBox component is similar to any standard HTML form drop-down list. When you click the component instance, a list of options appears below the default value in the list. You can also navigate the list using the up-arrow, down-arrow, Page Up, Page Down, Home, and End keys. This component is very useful and essentially has the following two different functionalities:

• As a regular combo box, the component can display a list of choices from which the user can select an option. If the combo box has focus, the user can type a letter to jump to a label starting with the same letter (see Figure 33-9).

• As an editable combo box, a user can enter text into the top field to specify a value that is not displayed in the list. The typed value is the active value for the ComboBox instance. Figure 33-10 shows a value being entered into the ComboBox instance at run time.

Figure 33-9: A standard ComboBox instance, shown closed (left) and open (right)

Figure 33-10: An editable ComboBox instance, shown with default display (left) and entered text (right)

Parameters

ComboBox parameters can be changed to set labels and data for each item in the drop-down box, set the top of the pull-down to be a text input box (an editable combo box), and customize how many items are viewable when the arrow is selected.

• data: This array is composed of values that correspond to each label value entered in the array for the labels parameter. For example, if you had a label value of "Red," you may want a data value of "0xFF0000." Similarly, if you have a catalog of items, the product's name may be the label value and its catalog number may be the data value. The user does not see the data value(s).

  Note

  When you set values for the data or labels array in the Property inspector, the values will be typed as strings. You need to set the data values in ActionScript if you want to type the values differently.

• editable: This parameter is set to define whether the ComboBox instance can have text entered into the top of the list to specify a value not listed in the menu. This typed value can be passed as data to the movie using the value property of the ComboBox class.

• labels: This array of values determines the list of text entries that the user sees when viewing the drop-down box.

• rowCount: The number entered here represents how many labels are seen on the dropdown box before a scroll bar appears. The default value is set to 5.

How it Works

When you click the data or labels field in the Property inspector, you will notice a magnifying glass icon next to the drop-down area. This button, when clicked, opens a Values panel where you can enter the array of values using the + or - buttons.

Functionality can be added using ActionScript, and the ComboBox class's methods, properties, and event handlers can be used with each instance of this component.

List Component

The List component also enables you to create lists just as the ComboBox does, but the list menu is always visible (see Figure 33-11). If there are more items than the height of the instance allows, a scroll bar is automatically added to the list. This component enables selection of one or more items. As with the ComboBox component, keyboard navigation is allowed, and a zero-based index system is used for the arrays populating the label and data parameters.

Figure 33-11: The List component at run time

Parameters

The List component parameters include an additional option to select multiple values. Other settings in this tab are similar in function to components we mentioned earlier.

• data: This parameter is an array of values associated with the values set in the labels parameter.

• labels: Values entered into this area will be the labels on each list item.

• multipleSelection: This is set to either true or false. A true value enables end-users to select multiple values at once when holding down the Ctrl or z key. The default value of false allows only one selection to be active at any time.

• rowHeight: This parameter controls the pixel height of each item in the list. This value does not control the size of the text used for each item. Rather, it indicates the active "hit" area of the item. If you specify a value that's smaller than the pixel height of the text, cropping of the item's label is the result. The default value is 20 pixels.

How it Works

This component's functionality is very similar to that of the ComboBox component. The main difference in a List component is the visibility of the labels and the ability to select multiple values. If you wish to add functionality using ActionScript, the methods, property, and events of the List class are used.

RadioButton Component

The RadioButton component looks and feels similar to those found in HTML forms. Based on the design of radio button functionality, only one radio button can be selected within a group of buttons. Figure 33-12 shows a group of RadioButton instances in a Flash movie.

Figure 33-12: A group of RadioButton instances

Parameters

The RadioButton component has the unique attribute for setting a Group name, which will associate the instance with others on the Stage. Other parameters resemble those of components we discussed earlier.

• data: The value entered here is associated with the label value of the RadioButton instance.

• groupName: The value of this parameter specifies which group of RadioButton instances on the Stage the particular instance is associated with. Therefore, only one radio dot appears in this group at one time. You can have several groups, each with its own set of associated RadioButton instances. The default value is radioGroup.

• label: This is the text you see alongside the RadioButton instance.

• labelPlacement: By default, the label placement is set to the right of the radio button. The acceptable options include left, right, top, and bottom.

• selected: This parameter sets the initial state of the button to be true or false (default). A false selection is clear. All buttons having the same group name will allow only one radio button to be selected at one time. If you set more than one RadioButton instance in the same group to initially have a true value, the last instance will be selected when you publish your movie.

How it Works

The groupName parameter is important to understand. Groups of buttons can be added to your document, and in each group, only one button can be selected at a time. You can resize the width and height of an instance with the Free Transform tool, the Property inspector, or the Transform panel to accommodate your label alignment parameter. The hit area of the RadioButton instance surrounds both the button and the label area. Added functionality can be controlled using the RadioButton class's methods, properties, and events in ActionScript.

ScrollPane Component

The ScrollPane component is potentially a very powerful and diverse tool. It adds a window with vertical and horizontal scroll bars on either side and is used to display linked Movie Clip symbols from the Library on to the Stage. Because the component features scroll bars, you are able to accommodate more content within a smaller footprint on the Stage. Figure 33-13 shows a ScrollPane instance displaying a linked Movie Clip symbol.

Figure 33-13: The ScrollPane component at run time

Parameters

Parameters for the ScrollPane component will link it to a Movie Clip symbol and also control how your end-user will be able to manipulate the ScrollPane content. You can also control scroll bar positioning and visibility with these parameters:

• contentPath: Enter a text string set to the Linkage ID of the Movie Clip you want to appear in the ScrollPane instance.

  Tip

  The ScrollPane component can also use external paths (or URLs) for displayed content, including external image files (.jpeg, .png, and .gif) or .swf files.

• hLineScrollSize: This value determines how much the content in the ScrollPane instance will move when the left and right arrows along the horizontal scroll bar are pressed. The default value is 5 pixels.

• hPageScrollSize: This parameter specifies how much the content moves when the user clicks the scroll track on either side of the horizontal scroll bar's middle scroller. The default value is 20 pixels.

• hScrollPolicy: This parameter controls how the horizontal scroll bar for the window is displayed. The default setting of auto means a horizontal scroll bar only appears if necessary. A value of true ensures it is always visible, and a false value turns it off.

• scrollDrag: Setting this parameter to true enables your users to drag the area within the instance window in order to view the content. A setting of false (default) requires scroll bars to be used instead.

• vLineScrollSize: This parameter functions the same way as the hLineScrollSize parameter, but for the vertical scroll bar of the window.

• vPageScrollSize: This parameter behaves in the same way as the hPageScrollSize parameter, but for the vertical scroll bar of the window.

• vScrollPolicy: This parameter controls if the vertical scroll bar is visible. See the description for the hScrollPolicy for more details.

How it Works

The ScrollPane component can display Movie Clips (or bitmap images) with linkage IDs, so you will need to convert any other symbol types or bitmap images to Movie Clips for the images to display. You can also specify external content as a URL in the contentPath property. The Movie Clip (or bitmap image) simply has to be in the Library and have the Export for ActionScript setting checked in the Linkage Properties dialog box.

TextArea Component

The TextArea component, shown in Figure 33-14, can be thought of as a ScrollPane component for text. The purpose of the TextArea component is to display text or HTML formatted text within a display window, complete with vertical and/or horizontal scroll bars.

Figure 33-14: The TextArea component displaying HTML formatted text

Parameters

The settings for the TextArea component in the Property inspector control the text that is displayed in the instance.

• editable: This parameter controls whether or not the user can change the text in the instance at run time. The default value is true. If it is set to false, the user cannot change the text.

  Caution

  We strongly recommend that you get in the habit of setting the editable parameter to false. You usually won't want users to change the contents of your TextArea component.

• html: This parameter determines how the value for the text parameter is interpreted. If html is set to true, any HTML tags format the text accordingly. If html is set to false, the text parameter displays "as is." The default value is false.

• text: The value of this parameter is the actual text displayed in the instance's text field.

  Tip

  For larger blocks of text, draft the text in a separate text editor and copy and paste the text into the text parameter field of the Property inspector. Alternatively, you can set the text property via ActionScript.

• wordWrap: This parameter controls how the text wraps in the instance. If the parameter is set to true (default), the text wraps at the visible horizontal boundary of the display area. If the parameter is set to false, the text wraps only when a carriage return or line break is specifically embedded in the text value, with a <br/> or <p> tag in HTML formatted text.

How it Works

The TextArea component takes the text parameter value and displays it within the visible area of the instance. The TextArea component can be further enhanced or controlled with ActionScript, by utilizing the methods, properties, and event handlers of the TextArea class.

UIScrollBar Component

The UIScrollBar component, shown in Figure 33-15, was added to the Flash MX 2004 7.2 Updater, and continues to be available in the new release of Flash 8. With the UIScrollBar component, you can scroll your own TextField instances, and you can scroll other MovieClip-based content. The UIScrollBar component can snap to objects on the Stage, and auto-resize its height to match the height of the snapped-to TextField instance.

Figure 33-15: The UIScrollBar component beside a TextField instance

Parameters

The settings for the UIScrollBar component in the Property inspector control the target to which the scroll bar is linked and whether the scroll bar is scrolling horizontal content or vertical content.

• _targetInstanceName: This parameter sets which TextField instance is linked to the UIScrollBar instance. This value is automatically filled in if you snap the UIScrollBar instance to a TextField instance on the Stage at author-time. The TextField instance must be on the same parent timeline as the UIScrollBar instance in order for _targetInstanceName to work properly.

  Tip

  You can also use the setScrollTarget() method of the UIScrollBar class in ActionScript to set the TextField instance target. It's also not a requirement to set a scroll target for a UIScrollBar instance — you can use the setScrollProperties() method of the UIScrollBar class to determine the scroll range of an instance, and use the "scroll" event of the component with listeners to enable scrolling movement. This technique is used with the scrollRect property of the MovieClip class in Chapter 30, "Applying HTML and Text Field Formatting."

• horizontal: This Boolean value (true or false) determines whether the UIScrollBar instance has a vertical (false) or horizontal (true) orientation. The default value is false. If you need to scroll a nonwrapping TextField instance from left to right, you can set the UIScrollBar instance's horizontal property to true and place the UIScrollBar instance below (or above) the TextField instance, as shown in Figure 33-16.

Figure 33-16: A UIScrollBar instance with a horizontal value of true

How it Works

When you set the _targetInstanceName property to the name of a TextField instance, the UIScrollBar component controls the scroll property of that TextField instance. It can determine the range of the scroll bar movement by looking at the TextField instance's maxscroll property.