Flex 2 Developer's Guide

Contents......Page 3 Using this manual......Page 15 Documentation set......Page 16 Typographical conventions......Page 17 Using Flex Programming Languages......Page 19 About MXML......Page 21 Writing a simple application......Page 22 Compiling MXML to SWF Files......Page 23 The relationship of MXML tags to ActionScript classes......Page 24 Developing applications......Page 25 Laying out a user interface using containers......Page 26 Adding user interface controls......Page 27 Using the id property with MXML tags......Page 28 Using XML namespaces......Page 29 Using MXML to trigger run-time code......Page 30 Binding data between components......Page 31 Using RPC services......Page 32 Storing data in a data model......Page 33 Validating data......Page 34 Formatting data......Page 35 Using Cascading Style Sheets (CSS)......Page 36 Using skins......Page 37 Defining custom MXML components......Page 38 Basic MXML syntax......Page 41 Setting component properties......Page 42 Setting properties using constants......Page 43 Including a newline character in a String value......Page 44 Setting Arrays of scalar values......Page 45 Setting Object properties......Page 46 Populating an Object with an Array......Page 47 Populating Arrays of objects......Page 48 Setting properties that contain XML data......Page 49 Setting event properties in MXML......Page 50 Specifying a RegExp value......Page 51 MXML tag rules......Page 52 Using ActionScript in Flex applications......Page 55 About generated ActionScript......Page 56 Using ActionScript blocks in MXML files......Page 58 Referring to Flex components......Page 60 Calling component methods......Page 62 Creating visual Flex components in ActionScript......Page 63 About scope......Page 64 Including ActionScript files......Page 66 Using the source attribute to include ActionScript files......Page 67 Referring to external files that have been included......Page 68 Importing classes and packages......Page 69 One MXML document (Event handling logic in event attribute)......Page 70 One MXML document and one ActionScript file (Event handling logic in separate script file)......Page 71 Creating ActionScript components......Page 72 Performing object introspection......Page 73 Using for..in loops......Page 74 Using the introspection API......Page 75 About events......Page 79 About the bubbling phase......Page 81 About event subclasses......Page 82 Using events......Page 83 Specifying the Event object......Page 85 Registering event listeners......Page 86 Defining event listeners inline......Page 87 Using the addEventListener() method......Page 88 Creating event listener classes......Page 92 Defining multiple listeners for a single event......Page 93 Registering a single listener with multiple components......Page 95 Passing additional parameters to listener functions......Page 96 Manually dispatching events......Page 97 Event propagation......Page 98 About the target and currentTarget properties......Page 99 Capturing phase......Page 100 Bubbling phase......Page 101 Detecting the event phase......Page 102 Stopping propagation......Page 103 Examples......Page 104 Event priorities......Page 105 Using event subclasses......Page 106 Handling keyboard events......Page 108 Understanding the keyCode and charCode properties......Page 109 Handling keyboard-related MouseEvents......Page 110 Building User Interfaces for Flex Applications......Page 113 About visual components......Page 115 Class hierarchy for visual components......Page 116 Commonly used UIComponent properties......Page 117 Using components in MXML and ActionScript......Page 118 Initializing components at run time......Page 120 Configuring components: syntax summary......Page 122 Sizing visual components......Page 123 Examples of component sizing......Page 124 Handling events......Page 126 About the component instantiation life cycle......Page 128 Using styles......Page 130 Using behaviors......Page 133 Changing the appearance of a component at run time......Page 134 Extending components......Page 136 About data providers and collections......Page 139 About data providers......Page 140 Data provider types......Page 141 Data providers and the uid property......Page 142 About collections......Page 144 Collection interfaces......Page 145 Collection classes......Page 146 Using a raw data object as a data provider......Page 147 Using a collection object directly......Page 148 Example: Using a simple data provider......Page 149 Using IList interface methods and properties......Page 151 Using ICollectionView interface methods and properties......Page 153 Sorting......Page 154 Example: Sorting and filtering an ArrayCollection......Page 155 Manipulating the view cursor......Page 157 Getting, adding and removing items......Page 158 Using bookmarks......Page 159 Example: updating an Array Using ICollectionView interface methods and properties......Page 161 Using events and update notifications......Page 164 Using collection events......Page 165 Using the itemUpdated method......Page 167 Disabling and enabling automatic updating......Page 168 Example: modifying data in DataGrid control......Page 169 Data descriptors and hierarchical data provider structure......Page 172 Data descriptor methods and source requirements......Page 173 Using the tag with Tree and menu-based controls......Page 175 Creating a custom data descriptor......Page 177 Using an XML data provider......Page 182 Using the XMLListCollection class......Page 184 Using remote data providers......Page 186 Using a DataService component......Page 187 About ItemPendingError errors......Page 188 Handling ItemPendingError errors......Page 189 Ensuring all data is available before you display a control......Page 191 About sizing and positioning......Page 193 About layout in Flex......Page 194 About component sizing......Page 195 About component positioning......Page 196 Component layout patterns......Page 197 Basic layout rules and considerations......Page 198 Sizing components......Page 199 Commonly used sizing properties......Page 200 Basic sizing characteristics and properties......Page 201 Basic sizing property rules......Page 202 Determining component size......Page 203 Determining container size......Page 204 Example: Determining an HBox container and child sizes......Page 205 Using Flex component sizing techniques......Page 206 Specifying an explicit size......Page 207 Using percentage-based sizing......Page 208 Setting the Application container size......Page 212 Dealing with components that exceed their container size......Page 213 Using padding and custom gaps......Page 215 Using the Spacer control to control layout......Page 216 Disabling automatic positioning temporarily......Page 217 Preventing layout of hidden controls......Page 218 Using absolute positioning......Page 219 Creating a constraint-based layout......Page 221 Example: Using constraint-based layout for a form......Page 222 Contents......Page 225 About controls......Page 226 Using data provider controls......Page 228 Flex controls......Page 229 Working with controls......Page 231 Sizing controls......Page 232 Positioning controls......Page 233 Button control......Page 234 Creating a Button control......Page 235 Sizing a Button control......Page 236 Skinning a Button control......Page 237 PopUpButton control......Page 238 Creating a PopUpButton control......Page 240 User interaction......Page 241 ButtonBar and ToggleButtonBar controls......Page 242 Creating a ButtonBar control......Page 243 Handling ButtonBar events......Page 244 Creating a LinkBar control......Page 245 TabBar control......Page 246 Creating a TabBar control......Page 247 Passing data to a TabBar control......Page 248 Handling TabBar control events......Page 249 Creating a CheckBox control......Page 250 About the RadioButton control......Page 251 Creating a RadioButton control......Page 252 Creating a group using the tag......Page 253 NumericStepper control......Page 255 Keyboard navigation......Page 256 About the DateChooser control......Page 257 About the DateField control......Page 258 Creating a DateChooser or DateField control......Page 259 Using the Date class......Page 260 Specifying header, weekday, and today’s day text styles......Page 261 Setting DateChooser and DateField properties in ActionScript......Page 262 Formatting dates......Page 264 User interaction......Page 265 Creating a LinkButton control......Page 266 LinkButton control user interaction......Page 267 About Slider controls......Page 268 Creating a Slider control......Page 269 Using slider events......Page 271 Using multiple thumbs......Page 273 Keyboard navigation......Page 274 SWFLoader control......Page 275 Interacting with a loaded Flex 2 application......Page 276 Using the SWFLoader control to load a Flex Data Services application......Page 278 About importing images......Page 279 Controlling image importing with the Image control......Page 280 Specifying the image path......Page 281 Sizing an image......Page 282 Maintaining aspect ratio when sizing......Page 283 Positioning the image in a Canvas container......Page 285 Setting visibility......Page 286 Techniques for using the Image control......Page 287 Using media in Flex......Page 289 Setting the size of a media component......Page 290 Adding a cue point......Page 291 Adding a cue point by using the CuePointManager class......Page 292 Streaming video from a camera......Page 293 Using the VideoDisplay control with Flash Media Server 2......Page 294 ColorPicker control......Page 295 About the ColorPicker control......Page 296 Creating a ColorPicker control......Page 297 Example: ColorPicker control that uses Objects......Page 299 Using custom field names......Page 301 Keyboard interaction......Page 302 Alert control......Page 303 Sizing the Alert control......Page 305 Using event listeners with the Alert control......Page 306 Specifying an Alert control icon......Page 307 ProgressBar control modes......Page 308 Creating a ProgressBar control......Page 309 HRule and VRule controls......Page 310 Creating HRule and VRule controls......Page 311 Sizing HRule and VRule controls......Page 312 ScrollBar control......Page 314 User interaction......Page 315 About text controls......Page 317 Using the text property......Page 319 Specifying special characters in the text property......Page 320 Specifying special characters in ActionScript......Page 321 Using the htmlText property......Page 323 Specifying HTML text......Page 324 Escaping special characters in HTML text......Page 326 Anchor tag ( )......Page 327 Font tag ( )......Page 328 Image tag ( )......Page 329 List item tag ( )......Page 331 Underline tag ( )......Page 332 Creating a selection......Page 333 Getting a TextRange object......Page 334 Changing text......Page 335 Example: changing selected text in a RichTextEditor control......Page 336 Label control......Page 337 Sizing a Label control......Page 338 Creating a TextInput control......Page 339 Text control......Page 340 Sizing a Text control......Page 341 TextArea control......Page 342 About the RichTextEditor control......Page 343 Creating a RichTextEditor control......Page 345 Programming RichTextEditor subcontrols......Page 346 Removing and adding RichTextEditor subcontrols.......Page 347 About menu-based controls......Page 351 About menu data providers......Page 352 Menu entry types......Page 353 Menu attributes......Page 354 Example: An Array menu data provider......Page 355 Handling menu-based control events......Page 356 Handling Menu and MenuBar control events......Page 357 Differences between MenuBar and Menu events......Page 359 Example: Using Menu control events......Page 361 Handling PopUpMenuButton control events......Page 364 Menu control......Page 365 Creating a Menu control......Page 366 Example: Creating a simple Menu control......Page 367 Menu control user interaction......Page 368 About the MenuBar control......Page 369 Creating a MenuBar control......Page 370 PopUpMenuButton control......Page 371 About the PopUpMenuButton control......Page 372 Example: Creating a PopUpMenuButton control......Page 373 Using the label property......Page 374 PopUpMenuButton user interaction......Page 375 Contents......Page 377 List control sizing......Page 378 Creating a List control......Page 379 Using a label function......Page 380 Displaying DataTips......Page 381 Displaying ScrollTips......Page 382 Setting variable row height and wrapping List text......Page 383 Specifying an icon to the List control......Page 384 List control user interaction......Page 386 About HorizontaList controls......Page 387 Creating a HorizontalList control......Page 388 Keyboard navigation......Page 390 About the TileList control......Page 391 Creating a TileList control......Page 392 Keyboard navigation......Page 394 About the ComboBox control......Page 395 Creating a ComboBox control......Page 396 Using events with ComboBox controls......Page 397 Populating a ComboBox control using variables and models......Page 399 ComboBox control user interaction......Page 401 About the DataGrid control......Page 403 Creating a DataGrid control......Page 404 Specifying columns......Page 405 Hiding and displaying columns......Page 406 Passing data to a DataGrid control......Page 407 Handling events in a DataGrid control......Page 408 Determining the initial DataGrid sort order......Page 409 Controlling user sorting of DataGrid displays......Page 410 Example: Sorting a DataGrid on multiple columns......Page 411 Keyboard navigation......Page 413 About Tree Controls......Page 414 Creating a Tree control......Page 415 Handling Tree control events......Page 417 Specifying Tree control icons......Page 419 Using icon fields......Page 420 Using the setItemIcon() method......Page 421 Editing a node label at run time......Page 422 Tree Navigation keys......Page 423 About containers......Page 425 About layout containers and navigator containers......Page 426 Using containers......Page 427 Flex containers......Page 431 Class hierarchy for containers......Page 432 Container example......Page 433 Event overview......Page 434 About the creation policy......Page 435 About the initialize and creationComplete events......Page 436 Using the Panel container......Page 438 Defining a default button......Page 440 Using scroll bars......Page 441 Scroll bar layout considerations......Page 442 Controlling scroll delay and interval......Page 443 About the coordinate systems......Page 444 Using coordinate properties and methods......Page 446 Example: Using the mouse position in a Canvas container......Page 447 About the display list and container children......Page 449 Obtaining the number of child components in a container or application......Page 450 Creating and removing components at run time......Page 451 Example: Creating and removing a child of an VBox container......Page 453 Example: Creating and removing children of an Accordion container......Page 455 Controlling child order......Page 456 Using the Application container......Page 459 Sizing an Application container and its children......Page 460 Changing the Application background......Page 462 Overriding styles with the Style tag......Page 464 Specifying options of the Application container......Page 465 About the Document object......Page 466 Using the mx.core.Application.application property......Page 467 Using the parentDocument property......Page 469 Disabling the download progress bar......Page 470 Download progress bar events......Page 471 Creating a simple subclass of the DownloadProgressBar class......Page 472 Creating a subclass of the DownloadProgressBar class......Page 474 Creating a subclass of Sprite......Page 476 Contents......Page 479 Canvas layout container......Page 480 Creating a Canvas Control by using absolute positioning......Page 481 Preventing overlapping children......Page 482 Repositioning children at run time......Page 483 Box, HBox, and VBox layout containers......Page 484 Creating a Box, HBox, or VBox container......Page 485 Creating a ControlBar container......Page 486 ApplicationControlBar layout container......Page 487 Creating an ApplicationControlBar container......Page 488 DividedBox, HDividedBox, and VDividedBox layout containers......Page 490 Creating a DividedBox, HDividedBox, or VDividedBox container......Page 491 Using the dividers......Page 492 About forms......Page 493 Creating forms......Page 494 Creating a FormHeading control......Page 495 Creating a FormItem container......Page 496 Example: A simple form......Page 497 Aligning and spacing Form container children......Page 498 Sizing and positioning Form container children......Page 500 Defining a default button......Page 501 Specifying required fields......Page 502 Storing and validating form data......Page 503 Using Form controls to hold your form data......Page 504 Validating form control contents data on user entry......Page 505 Using a Flex data model to store form data......Page 506 Using Flex validators with form models......Page 507 Populating a Form control from a data model......Page 508 Submitting data to a server......Page 509 Grid layout container......Page 512 Creating a Grid layout container......Page 513 Setting the row and column span......Page 516 Panel layout container......Page 518 Creating a Panel layout container......Page 519 Adding a ControlBar container to a Panel container......Page 520 Tile layout container......Page 521 Creating a Tile layout container......Page 522 Sizing and positioning a child in a Tile container......Page 523 TitleWindow layout container......Page 524 Creating a pop-up window......Page 525 Removing a pop-up window......Page 528 Using TitleWindow and PopUpManager events......Page 529 Centering a pop-up window......Page 530 Passing data to and from a pop-up window......Page 531 Passing data using events......Page 533 Using the addPopUp() method......Page 535 About navigator containers......Page 539 ViewStack navigator container......Page 540 Creating a ViewStack container......Page 541 Applying behaviors to a ViewStack container......Page 544 TabNavigator container......Page 545 Creating a TabNavigator container......Page 546 TabNavigator container Keyboard navigation......Page 548 Accordion navigator container......Page 549 Creating an Accordion container......Page 550 Accordion container Keyboard navigation......Page 551 Using Button controls to navigate an Accordion container......Page 552 Controlling the appearance of accordion buttons......Page 553 Customizing the User Interface......Page 555 About behaviors......Page 557 About applying behaviors......Page 558 About factory and instance classes......Page 559 Available effects......Page 561 Available triggers......Page 565 Applying behaviors in MXML......Page 566 Applying behaviors in MXML using styles......Page 567 Applying behaviors in ActionScript......Page 568 Playing an effect backward......Page 570 Ending an effect......Page 571 Creating a reusable effect......Page 572 Applying behaviors in ActionScript using styles......Page 573 Applying behaviors using the Effect.target and Effect.targets properties......Page 575 Using embedded fonts with effects......Page 577 Creating composite effects......Page 578 Using the AnimateProperty effect......Page 581 Repeating effects......Page 582 Using a sound effect......Page 583 Using a mask effect......Page 585 Creating a custom mask function......Page 586 Handling effect events......Page 587 Handling tween effect events......Page 589 Using an easing function......Page 590 Using a Flex easing function......Page 591 Creating a custom easing function......Page 592 Disabling container layout for effects......Page 593 Improving performance when resizing Panel containers......Page 595 Setting UIComponent.cachePolicy on the effect target......Page 596 About styles......Page 599 Local style definitions......Page 600 Inline styles......Page 601 About style value formats......Page 602 Length format......Page 603 Time format......Page 604 Color format......Page 605 Using Cascading Style Sheets......Page 606 About property and selector names......Page 607 About inheritance in CSS......Page 608 About class selectors......Page 609 About type selectors......Page 610 About selector precedence......Page 611 Embedding resources in style sheets......Page 612 Style inheritance order......Page 613 Inheritance exceptions......Page 615 About supported styles......Page 616 Using external style sheets......Page 617 About the default style sheet......Page 618 Using the Application type selector......Page 619 Using the StyleManager class......Page 620 Using the setStyle() and getStyle() methods......Page 623 Setting styles......Page 624 Using inline styles......Page 626 Using filters in Flex......Page 628 Using themes......Page 629 Creating a theme SWC file......Page 631 Creating a theme style sheet......Page 632 Compiling a theme SWC file......Page 633 Using a configuration file to compile theme SWC files......Page 634 About fonts......Page 637 Using device fonts......Page 638 Using embedded fonts......Page 639 Embedded font syntax......Page 640 Locating embedded fonts......Page 641 Embedding fonts in ActionScript......Page 642 Detecting embedded fonts......Page 643 Using multiple typefaces......Page 645 Setting character ranges......Page 647 Setting ranges in flex-config.xml......Page 648 Detecting available ranges......Page 649 Embedding double-byte fonts......Page 650 About embedding FlashType fonts......Page 651 About FlashType style properties......Page 652 Creating Flash 8 files with embedded FlashType fonts......Page 653 Embedding FlashType fonts into Flex applications......Page 655 Resolving run-time errors......Page 659 About skinning......Page 661 Resources for skins......Page 662 Graphical skinning......Page 663 Using style sheets to apply skins......Page 664 Using the setStyle() method......Page 665 Using SWF files as skins......Page 666 Programmatic skins recipe......Page 668 Selecting a superclass......Page 670 Implementing the updateDisplayList() method......Page 671 Implementing measuredWidth and measuredHeight getters......Page 673 Making properties styleable......Page 674 Accessing the parent component......Page 677 Compiling programmatic skins......Page 678 Drawing programmatically......Page 679 Applying programmatic skins......Page 682 Using inline syntax......Page 683 Reskinning ToolTips......Page 684 Creating themes......Page 686 About item renderers......Page 687 Default item rendering and cell editing......Page 688 Using custom item renderers and item editors......Page 690 Item renderer and item editor architecture......Page 692 About item renderer and item editor interfaces......Page 693 Application layout with item renderers and item editors......Page 694 Using a drop-in item renderer or item editor......Page 695 Using an inline item renderer or item editor......Page 696 Using a component as an item renderer or item editor......Page 698 Using editable controls in an item renderer......Page 699 Setting the itemRenderer or itemEditor property in ActionScript......Page 700 Accessing the listData property......Page 701 Creating drop-in item renderers and item editors......Page 703 Using drop-in item renderers and item editors......Page 704 Creating a simple inline item renderer or item editor......Page 707 Creating a complex inline item renderer or item editor......Page 709 Items allowed in an inline component......Page 710 Defining the scope in an tag......Page 711 Creating a reusable inline item renderer or item editor......Page 713 Creating item renderers and item editor components......Page 714 Creating an item renderer component......Page 715 Overriding the data property......Page 717 About using the creationComplete and dataChange events......Page 718 Creating an item renderer in ActionScript......Page 719 Example: Using an item renderer with the TileList and HorizontalList controls......Page 720 Example: Using an item renderer with a DataGrid control......Page 722 Example: Using an item renderer with a List control......Page 723 Example: Using an item renderer with a Tree control......Page 724 The cell editing process......Page 727 Creating an editable cell......Page 728 Returning data from an item editor......Page 729 Defining a property to return data......Page 730 Sizing and positioning an item editor......Page 732 Making an item editor that responds to the Enter key......Page 734 Using the cell editing events......Page 735 Accessing cell data and the item editor in an event listener......Page 737 Determining the reason for an itemEditEnd event......Page 739 Example: Preventing a cell from being edited......Page 742 Example: Modifying data passed to or received from an item editor......Page 743 Example: Passing multiple values back from an item editor......Page 745 Example: Using an item renderer as an item editor......Page 749 Example: Using a data validator in a custom item editor......Page 751 Example: Using a custom item editor with a List control......Page 752 Using a DateField or ComboBox control as a drop-in item editor......Page 754 Example: Using a custom item editor with a Tree control......Page 755 About ToolTips......Page 759 Creating ToolTips......Page 760 Setting styles in ToolTips......Page 762 Using ToolTip events......Page 763 Using ToolTips with NavBar controls......Page 764 Enabling and disabling ToolTips......Page 765 Setting delay times......Page 766 Using dynamic ToolTip text......Page 768 Creating custom ToolTips......Page 769 Using error tips......Page 771 About the Cursor Manager......Page 775 Using the Cursor Manager......Page 776 Creating and removing a cursor......Page 777 Setting a busy cursor......Page 778 Using the showBusyCursor property......Page 780 Understanding the localization workflow......Page 781 Using the ResourceBundle metadata tag......Page 782 Using localized objects and embedded assets......Page 783 Localized properties file and class search order......Page 786 Creating the application SWF file......Page 787 Creating a localized SWC file......Page 788 Example: Building a simple localized application......Page 790 Flex Programming Topics......Page 791 About Repeater components......Page 793 Declaring the Repeater component in MXML......Page 794 Basic principles of the Repeater component......Page 796 Creating dynamic loops with the Repeater component......Page 799 Referencing repeated child components......Page 801 Referencing nested Repeater components......Page 802 Event handlers in Repeater components......Page 804 Accessing specific instances of repeated components......Page 806 Using a Repeater component in a custom MXML component......Page 809 How a Repeater component executes......Page 811 Considerations when using a Repeater component......Page 812 About view states......Page 815 Use case: Login interface......Page 816 Use case: Custom item renderer......Page 817 Applying view states......Page 818 Defining view states......Page 819 Elements of a view state......Page 820 Example: Login form application......Page 821 Creating a view state in ActionScript......Page 822 Setting component properties......Page 823 Adding and removing components......Page 824 Controlling when to create added children......Page 825 Using the handlerFunction property......Page 829 Example: Setting event listeners......Page 830 Example: Using view states with history management......Page 831 Example: Using view states with a custom item renderer......Page 834 Using view states in custom components......Page 836 Additional state-based application techniques......Page 837 Creating your own override classes......Page 838 About transitions......Page 841 Comparing transitions to effects......Page 842 Defining transitions......Page 843 Defining multiple transitions......Page 845 Defining effect targets......Page 846 Defining the effect start and end values......Page 847 Example: Using transitions......Page 848 Handling events when using transitions......Page 849 Using action effects in a transition......Page 850 Example: Using action effects......Page 852 Filtering effects......Page 854 Example: Using a filter......Page 856 Defining a custom filter......Page 857 Writing a filter function......Page 859 Example: Using a custom effect filter......Page 862 Tips......Page 864 Troubleshooting......Page 865 About the drag-and-drop operation......Page 867 Using drag-and-drop with list-based controls......Page 868 Examples: List control......Page 870 Example: DataGrid control......Page 872 Example: Tree control......Page 873 Drag-and-drop events......Page 874 The drag-and-drop operation......Page 875 Example: Simple drag-and-drop operation......Page 876 Starting a drag-and-drop operation......Page 878 Writing the initiator event listener......Page 879 Specifying the drag proxy image......Page 881 Handling the dragEnter event......Page 882 Handling the dragOver event......Page 883 Handling the dragExit event......Page 884 Example: All drag-and-drop events......Page 885 Dragging an image......Page 888 Examples of embedding assets......Page 891 Accessing assets at run time......Page 892 Supported file types......Page 893 Embed parameters......Page 894 About the source parameter......Page 895 About setting the path to the embedded asset......Page 896 Using the [Embed] metadata tag......Page 897 Embedding assets in style sheets......Page 898 Embedding JPEG, GIF, and PNG images......Page 899 Embedding SVG images......Page 900 Embedding sounds......Page 901 Embedding SWF symbols......Page 902 Embedding SWF files that represent Flex 2 applications......Page 903 Using scale-9 formatting with embedded images......Page 904 About history management......Page 907 Using standard history management......Page 908 Using custom history management......Page 909 Implementing the saveState() and loadState() methods......Page 910 Encoding navigation state data......Page 912 Using history manage