MACROMEDIA FLEX - DEVELOPING COMPONENTS AND THEMES, Manual

Page 1: ...Developing Flex Components and Themes in Flash Authoring ...

Page 2: ...nHelp Graphics Locator WinHelp Hyperviewer WinHelp Inspector and Xtra are either registered trademarks or trademarks of Macromedia Inc and may be registered in the United States or in other jurisdictions including internationally Other product names logos designs titles words or phrases mentioned within this publication may be trademarks service marks or trade names of Macromedia Inc or other enti...

Page 3: ...custom component 31 Adding events to custom components 33 Setting default sizes 37 Styling custom components 38 Skinning custom components 39 Creating compound components 42 CHAPTER 3 Creating Advanced Components in Flash MX 2004 45 About Creating components 45 Writing the component s ActionScript code 46 Skinning custom controls 69 Adding styles 70 Making components accessible 71 Improving compon...

Page 4: ...4 Contents ...

Page 5: ...lex in several ways Depending on what kind of component you want to create you use different tools To extend the class of an existing component and add a new method for example you can write just a single ActionScript class file To create a new tag in MXML you can create a component in MXML using a combination of MXML tags and ActionScript Or to create a new component with new behaviors graphics a...

Page 6: ...late frequently used functionality into components and designers can customize the look and behavior of components by adding methods and events to the components A component can be a simple user interface control such as a Radio Button or a CheckBox or it can contain content such as a Canvas or Data Grid a component can also be nonvisual like the FocusManager that lets you control which object rec...

Page 7: ...ing some type of system resource Examples of managers include the FocusManager and the DepthManager A typical application contains only one instance of a manager and these managers are normally instantiated if they are needed by components that rely on them You generally would not use the instructions in this chapter to create new managers because they are nonvisual Working in the Flash environmen...

Page 8: ... clip symbols Compiled clips cannot be edited but they do have properties that appear in the Property Inspector and in the Component Inspector panel and they include a live preview The components included with Flash MX 2004 have already been converted to compiled clips Classes The ActionScript class file specifies the properties methods and events for the component and defines which if any classes...

Page 9: ...ponents list appears in the Components panel with the other component lists 5 In each new FLA file that you create add the following classpath entry to the top of the local classpath listing LocalData Flex Classes Note You must add the Flex Classes entry to the top of the classpath list For more information on editing your FLA file s classpath settings see Changing the Flash classpath on page 10 A...

Page 10: ...ude the Flex classes in its environment You must download and install a separate set of files and then add them to your classpath settings For more information see Adding Flex classes and components to the Flash IDE on page 8 Changing the Flash classpath This section describes how to change the global and local classpaths Macromedia recommends changing only the local classpath and adding the follo...

Page 11: ...n import mx controls TextInput When importing classes you can use a wildcard to import all classes in a particular package for example import mx controls Flash only imports the necessary classes when compiling the component Flash finds classes that you import by searching the directories in the classpath For most situations your local Flash classpath must consist of at least the following entries ...

Page 12: ...Click the Advanced button The advanced settings appear in the dialog box 6 In the Identifier field enter a fully qualified linkage identifier for example myPackage MyComponent The identifier is used as symbol name and linkage name and as the associated class name It should be the same as the symbol name 7 In the AS 2 0 Class field enter the fully qualified path to the component s ActionScript 2 0 ...

Page 13: ...e Edit in New Window command Editing a symbol in a separate window lets you see the symbol and the main Timeline at the same time The name of the symbol that you are editing appears in the edit bar at the top of the Stage Edit the symbol by changing the window from the Stage view to a view of only the symbol using Edit Symbols mode To enter Edit Symbols mode select the symbol s instance from the E...

Page 14: ...all the graphical assets used by this component 5 Insert a blank Keyframe on the assets layer You should now have two frames on the assets layer 6 Add any graphical assets used by this component on the second frame of your component s assets layer For example if you are creating a custom button add the graphics that represent the button s states up down and so on 7 Drag dependent components onto t...

Page 15: ...ur component symbol 2 Select the second frame of the assets layer 3 Select the dependent component s symbol from the Flex Components drop down list in the Components panel If you do not have a list of Flex Components in your Components panel see Adding Flex classes and components to the Flash IDE on page 8 4 Drag the component onto the Stage in the second frame of your new component s assets layer...

Page 16: ...on panel appears 5 Enter the class name in the AS 2 0 Class text box You must enter the fully qualified class name if the class is in a package Do not include the filename extension For example if the classname is MyComponent as enter MyComponent 6 Click OK Flash transforms the symbol into a component and populates the Parameters box with the component properties that are available in the class fi...

Page 17: ...s as a directory to the other files in the SWC file Source code Contains one or more ActionScript files that contain a class declaration for the component The source code is used only for type checking when extending components and is not compiled by the authoring tool because the compiled bytecode is already in the implementing SWF file The source code might contain intrinsic class definitions th...

Page 18: ...reate SWC files by exporting a component When creating a SWC file Flash reports compile time errors as if you were testing a Flash application This means that once a component is compiled as a SWC file you can be reasonably certain that you will not encounter runtime errors such as type mismatches Note After you create a SWC file you can rename the file but the tag name you use in your MXML file m...

Page 19: ...he actual path a second argument to the program specifies the Flex Components directory For example if Flash is installed in D MM Flash you would run the SWCRepair utility as the following example shows D MM Flash en First Run SWCRepair bin SWCRepair exe C myProjects foo swc D MM Flash en First Run Components Flex Components After you run the SWCRepair utility against a SWC file check whether a lo...

Page 20: ...the Flex server you see notifications from FileWatcherService as you modify your SWC file and then reload the MXML The logging information indicates where the SWC file that Flex is loading is located on the Flex server s hard disk You can also verify that Flex is not loading older versions of SWC files from an unexpected location by setting the create compile report option to true in the flex conf...

Page 21: ...e SWD file contains debugging information for the SWF file You must use SWD files to use the Debug Flash Player to debug your component By default Flash does not include debugging information when exporting the SWC file When you export a SWC file you can include the SWD file in the SWC file by selecting Debugging Permitted in the Publish Settings dialog box As with all settings in the Publish Sett...

Page 22: ...le must match the Linkage Identifier in the original FLA file or the symbolName in the class file When you distribute your components to other developers you can include the following instructions so that they can install and use them immediately To use a SWC file in the Flash authoring environment 1 Copy the SWC file into the Flash_root en First Run Components directory 2 Start the Flash authorin...

Page 23: ...ng components see Chapter 3 Creating Advanced Components in Flash MX 2004 on page 45 Contents Creating simple components 23 Working with component properties 30 Binding properties to a custom component 31 Adding events to custom components 33 Setting default sizes 37 Styling custom components 38 Skinning custom components 39 Creating compound components 42 Creating simple components This section d...

Page 24: ...vironment by adding the Flex components and class files For more information see Adding Flex classes and components to the Flash IDE on page 8 2 In Flash create a new FLA file 3 Edit the FLA file s local classpath settings to include the following two classpath entries LocalData Flex Classes the dot For more information see Changing the Flash classpath on page 10 4 Draw a green square on the Stage...

Page 25: ... contains the following code xml version 1 0 mx Application xmlns mx http www macromedia com 2003 mxml xmlns greensquare mx Application 16 Save the MXML file as greentest mxml You cannot name the file greensquare mxml You must give it a name that is different from the component s name such as greentest mxml 17 Copy the SWC component you created greensquare swc to the same directory as the MXML fil...

Page 26: ...it super init invalidate Required call so that Flex draws the component 6 Save the text file as orangecircle as in the myPackage subdirectory below the directory in which the FLA file is stored This should be a directory that is not in the web application s directory structure since these are source files for your eventual component Furthermore it cannot be the same directory into which you deploy...

Page 27: ...at Flex can compile a SWF from the MXML file 18 Request the MXML file in your browser or a stand alone Flash Player An orange circle should appear Creating the Blue Button This procedure shows you how to extend an existing Flex control In this example it is a button The button s border and text are blue When you insert the Blue Button component into your Flex application it inherits all of the eve...

Page 28: ...ing code to the BlueButton as file class BlueButton extends mx controls Button static var symbolName String BlueButton static var symbolOwner Object BlueButton var className String BlueButton function BlueButton function init Set the label text to blue setStyle color 0x6666CC super init invalidate This script extends the mx controls Button class rather than the base classes UIObject or UIComponent...

Page 29: ...x Components list onto the second frame of the assets layer Flash adds the Button to the Library as a Compiled Clip asset 17 Right click the BlueButton movie clip in the Library and select Component Definition 18 In the Component Definition dialog box set the AS2 0 Class field to BlueButton 19 Click OK Flash converts the symbol to a component 20 Right click the component in the Flash Library and s...

Page 30: ... described in the following sections Creating an instance variable Creating instance variables is simple In the component s ActionScript class file you declare a variable var myName String If the variable declaration does not specify a default value your code must either take into account that myName might be undefined or the user could encounter unexpected results In MXML you set that property us...

Page 31: ...elopers can use the contents of your component as parameters to a web service call or to update the UI The simplest form of binding is to use the curly braces syntax that binds a property of a control to another control s property In the component s ActionScript class you can declare a variable as follows var myName String Fred In your MXML file you then bind the value of a control s property to t...

Page 32: ...x core UIComponent static var symbolName String BindChar static var symbolOwner Object BindChar var className String BindChar function BindChar This example uses a TextField to store and display the character var myCharField TextField function init super init tabEnabled true invalidate function keyDown evt Object Void Triggers the setter on every keystroke char String fromCharCode evt ascii Change...

Page 33: ...nents inherit events such as focusIn focusOut keyDown and keyUp From the UIObject class components inherit events such as mouseDown mouseUp mouseOver and mouseOut For a complete list of UIObject and UIComponent events see Developing Flex Applications Components can emit and consume events In most cases you want your component to emit an event and the MXML application to consume and handle it Custo...

Page 34: ...support a number of navigational mouse events including the following mouseOver mouseOut mouseDown mouseUp These events do not include the click event For a complete list of events supported by visual components see the information about the control in Developing Flex Applications To use the common mouse events you point to a handler in your MXML file You do not need to add any additional code to ...

Page 35: ...geAlpha 0 If you try to use a click handler in the MXML file you get an error similar to the following Error unknown attribute click on greensquare This means that you have to go back to the component s ActionScript class and tell the component to emit a click event You do this by adding a call to dispatchEvent in the component s ActionScript class file You must also include the Event metadata key...

Page 36: ... on page 42 Handling keyboard events Keyboard events are emitted by all components that extend the UIComponent class To make use of keyboard events in your MXML files you should capture the keys and include the value of the key in your event object and then dispatch the keyboard event with the event object The following component class emits the keyDown event so that the Flex application can handl...

Page 37: ...yDown event mx TextArea id ta1 text mx Application Setting default sizes You can set the default size of a custom component by setting the values of the _measuredPreferredWidth and _measuredPreferredHeight properties in the measure method These values will be used if no explicit width and height are specified in the component s MXML tag Your measure function should not set the preferredWidth and p...

Page 38: ...the background To change style properties in custom components use the setStyle method in the component s init function This applies the same style to all instances of the component but Flex application authors can override the settings of the setStyle method in their MXML tags Any style properties that are not explicitly set in the component s class file are inherited from the component s supercl...

Page 39: ...ess of changing the appearance of a control is called skinning Skins can be any kind of graphic that Flash supports from a simple line drawing to a multipart SWF file To skin a component you start with a FLA file just as you would when creating any new component However you add a new symbol to the FLA file that defines the skin in addition to the component s symbol itself The following table descr...

Page 40: ...awing methods of the component For a list of what skins are used by what controls see each control s entry in Developing Flex Applications This section describes a simple method for changing the skin for one of the states of the standard Button control You can use the steps in this procedure to change the skin for any visual control in Flex To create a custom component with a different skin 1 In t...

Page 41: ...ips 10 Return to Edit Symbols mode and edit the component s symbol the first symbol you created 11 Drag the skin symbol you created onto the second frame of the component s assets layer 12 Create a new ActionScript class file In this file extend the existing control set the value of the skin to the new skin name and apply the skin as a clip parameter in the constructObject2 method The following ex...

Page 42: ...ke mx controls Button you must instantiate each of the controls as children of the custom component and arrange them on the screen Properties of the individual controls are not accessible from the MXML author s environment unless you design your class to allow this For example if you create a new component that extends the UIComponent class and uses a Button and a TextArea component you cannot set...

Page 43: ...ame String CompoundComponent function CompoundComponent function init super init invalidate Declare two children member variables var text_mc TextArea var mode_mc Button function createChildren Void if mode_mc undefined createClassObject Button mode_mc 1 if text_mc undefined createClassObject TextArea text_mc 0 preferredWidth 150 editable false mode_mc addEventListener click this mode_mc label Cli...

Page 44: ...44 Chapter 2 Creating Basic Components in Flash MX 2004 ...

Page 45: ... Creating components 45 Writing the component s ActionScript code 46 Skinning custom controls 69 Adding styles 70 Making components accessible 71 Improving component usability 71 Best practices when designing a component 72 Using the ModalText example 73 Troubleshooting 76 About Creating components This section describes the general process for creating a component that extends an existing Flash M...

Page 46: ...ect or UIComponent or another component b Specify symbolName symbolOwner and className c Specify properties that can be set using an MXML tag property clip parameters d Implement the constructObject2 method e Implement the init method f Implement the createChildren method g Implement the measure method h Implement the layoutChildren method i Implement the draw method j Add properties methods and m...

Page 47: ...omponent Provide the className variable var className String MyComponent Define an empty constructor function MyComponent Override the init method and call the parent s init method function init Void Void super init Call invalidate to display graphics invalidate General process for writing a class file Use the following general process when you write a component s ActionScript class file Depending...

Page 48: ...e UIComponent class provides more built in functionality but maintains the flexibility of extending the UIObject class UIObject and UIComponent are the base classes of the component architecture Understanding the principles at work in these two classes is important for building components The following table briefly describes the two base classes Class Extends Description mx core UIComponent UIObj...

Page 49: ...esizes itself by scaling When you change its size using the setSize method the new dimensions are handed to the _width and _height properties of the MovieClip class which scale the subclass The UIComponent mx core UIComponent class is a subclass of the UIObject class It defines high level behaviors that are specific to a graphical object The UIComponent class handles end user interactions such as ...

Page 50: ...ames To help Flash find the proper ActionScript classes and packages and to preserve the component s naming you must set the symbolName symbolOwner and className variables in your component s ActionScript class file The following table describes these variables Property Type Description symbolName String Symbol name for the object name of the ActionScript class The symbol name must be the fully qu...

Page 51: ...d you must call the super constructObject2 method or make manual calls to the init and createChildren methods 3 The init method Flex calls the init method from the parent class s constructObject2 method 4 The createChildren method Flex calls the createChildren method from the parent class s constructObject2 method 5 The measure method Flex calls the measure method 6 The layoutChildren method Flex ...

Page 52: ...lues of these are stored in the initObject so that Flex can apply them to the component during instantiation Clip parameters mirror the set of properties in the Flash UI Property inspector They are used in Flex as a list of properties to be applied during the construction of the object Clip parameters are roughly equivalent to constructor parameters in Java or C although they are not set in the co...

Page 53: ... Object Void Thus when you have a component like the following class MyComponent extends UIComponent private var clipParameters Object someProperty 1 private static var mergedClipParameters mx core UIObject mergeClipParameters MyComponent prototype clipParameters UIComponent prototype clipParameters public var someProperty String You can do this function constuctObject2 initObj Object super constr...

Page 54: ... are set in the MXML tag and stored as clip parameters Flex creates this object implicitly during instantiation of the component Implementing the init method Flash calls the init method when the class is created At a minimum the init method should call the superclass s init method The width height and clip parameters are not properly set until after this method is called function init Void Void su...

Page 55: ...nge this text_mc addEventListener focusOut this if mode_mc undefined createClassObject SimpleButton mode_mc 1 falseUpSkin modeUpSkinName falseOverSkin modeOverSkinName falseDownSkin modeDownSkinName mode_mc addEventListener click this If your component is a container and you do not know exactly which children it contains call the createComponents method This method creates all child objects For mo...

Page 56: ... pendingSelectedIndex property 15 times and then only do the rendering once This is most useful for properties that are computationally expensive to update If setting a property is inexpensive you can avoid using the commitProperties method Implementing the measure method Generally the measure method is only called once when the component is instantiated The component s container sets the initial ...

Page 57: ...nd layoutHeight properties of your component Each component should implement this method The layoutChildren method deprecates the size method which is used primarily by Flash designers to perform the same function Use the width and height properties of the child controls when changing the size of the children These properties are scaled for use inside the component Use the layoutWidth and layoutHe...

Page 58: ...object is invalidated so you should actually call an invalidation method if you want Flex to invoke the draw or redraw method If you do not call an invalidation method the component remains invisible unless you set its visibility property to true in MXML For more information see About invalidation on page 68 Flex also calls the draw method after the layoutChildren method Inside the draw method you...

Page 59: ...e bindable and have other properties For more information see Component metadata on page 59 Component metadata The Flash compiler recognizes component metadata statements in your external ActionScript class files The metadata tags define component attributes data binding properties events and other properties of the component Flash interprets these statements during compilation they are never inte...

Page 60: ...lid property name for the tag s effect For more information see Effect on page 62 Embed Imports JPEG GIF PNG SVG and SWF files at compile time Also imports image assets from SWC files This is functionally equivalent to the MXML Embed syntax as described in Developing Flex Applications Event Describes the events that the component emits For more information see Event on page 62 IconFile Identifies ...

Page 61: ...ble param1 writeonly type DataProvider The Bindable keyword is required when you use the ChangeEvent metadata keyword For more information see ChangeEvent on page 61 ChangeEvent Use the ChangeEvent metadata keyword to generate one or more component events when changes are made to properties The ChangeEvent metadata keyword has the following syntax ChangeEvent event_name property_declaration or get...

Page 62: ...so that more than one event is generated when the property changes as the following example shows ChangeEvent change1 ChangeEvent change2 ChangeEvent change3 Any one of those events indicates a change to the variable They do not all have to occur to indicate a change Effect The Effect metadata keyword defines the name of the property that you can assign to an effect for the MXML tag The Effect met...

Page 63: ...tor of the Flash user interface Prior to the availability of this metadata keyword you had to define the property in the ActionScript class file and in the Component inspector which introduced the possibility of errors because the property was defined in multiple locations Now you define the property only once The Inspectable metadata statement must immediately precede the property s variable decl...

Page 64: ...perty inspector environment String Optional Notes which inspectable properties should not be allowed none which are used only for Flash Flash and which are used only by Flex and not Flash MXML format String Optional Indicates that the property holds a value with a file path listOffset Number Optional Defines the default index of a List value Added for backward compatibility with Flash MX component...

Page 65: ...s an event as an interim trigger You use this keyword for properties that might change often but for which you do not want validation to occur on every change An example of this is if you tied a validator function to the text property of a TextInput control The text property changes on every keystroke but you do not want to validate the property until the user presses the Enter key or changes focu...

Page 66: ...ActionScript Setting a parameter with ActionScript in your MXML application overrides any value set during component authoring The following examples set several component parameters and expose them with the Inspectable metadata keyword in the Component inspector A string parameter Inspectable defaultValue strawberry public var flavorStr String A string list parameter Inspectable enumeration sour ...

Page 67: ...o receive multiple events from the same object you must register for each event Although every component can define unique events events are inherited from the core classes of the architecture mx core UIObject and mx core UIComponent These classes define low level component events such as draw resize move load and others that are fundamental to all components Subclasses of these classes inherit an...

Page 68: ... shows Event click Event declaration class FCheckBox function addEventListener eventName String eventHandler Object eventName is String Event metadata describes the events that this component emits not the ones it consumes For more information on the Event metadata keyword see Event on page 62 About invalidation Macromedia recommends that a component not update itself immediately in most cases but...

Page 69: ...l uses a separate symbol to represent each of its states FalseDown FalseUp Disabled Selected and so on However you can associate your custom symbols called skins with these states At runtime the old and new symbols are exported in the SWF file The old states become invisible to give way to the new symbols This ability to change skins during author time as well as runtime is called skinning To use ...

Page 70: ...d the property is not inherited the value of the style is undefined If the property is inherited it checks the style property of its parent component The parent component returns the property if it has it or checks its parent When the last parent is queried and no style has been found Flex checks for a global style object To set or get styles on an instance of an object you access the UIObject get...

Page 71: ...ponentName enableAccessibility For example the following line enables accessibility for the MyButton component mx accessibility MyButton enableAccessibility When developers add the MyButton component to an application they can use the Accessibility panel to make it available to screen readers Improving component usability After you create the component and prepare it for packaging you can make it ...

Page 72: ...ores the version number in one place include myPackage ComponentVersion as The contents of the ComponentVersion as file are identical to the previous variable declaration as the following example shows static var version String 1 0 0 42 Best practices when designing a component Use the following practices when designing a component Keep the file size as small as possible Make your component as reu...

Page 73: ...e mode by clicking its button Save the following code to the file ModalText as and then generate the SWC file using the FLA file Import all necessary classes import mx core UIComponent import mx controls SimpleButton import mx controls TextInput Modal text sends a change event when the text is changed Event change a Extend UIComponent class ModalText extends UIComponent b Specify symbolName symbol...

Page 74: ...createClassObject TextInput text_mc 0 preferredWidth 80 editable false text_mc addEventListener change this text_mc addEventListener focusOut this if mode_mc undefined createClassObject SimpleButton mode_mc 1 falseUpSkin modeUpSkinName falseOverSkin modeOverSkinName falseDownSkin modeDownSkinName mode_mc addEventListener click this g implement measure The default width is the size of the text plus...

Page 75: ...properties metadata The general pattern for properties is to specify a private holder variable private var __labelPlacement String left Create a getter setter pair so you know when it changes Inspectable defaultValue left enumeration left right function set labelPlacement p String Store the new value __labelPlacement p Add invalidateSize invalidateLayout or invalidate depending on what changed You...

Page 76: ... 800 height 400 ModalText labelPlacement left mx Application Troubleshooting This section describes some common problems and their solutions when creating components for Flex in Flash I get an error don t know how to parse when I try to use the component from MXML This means that the compiler could not find the SWC file or the contents of the SWC file did not list the component The MXML tag must m...

Page 77: ...of your component must be placed in your component symbol For more information see Adding dependent components on page 15 A good practice is to create a hidden frame and place components on that frame Then put a stop action in the preceding frame so the hidden frame never gets played As an example the ModalText symbol has a layer called assets and the stop action on the main layer The component is...

Page 78: ...d preferredHeight properties to see what is setting them You can also verify that the visible property and the _visible property are set to true The _visible property is an internal property used by Flash Player If visible true and _visible false ensure that your component called the invalidate method in its measure or layoutChildren methods The system does not call the invalidate method unless yo...

Page 79: ...constructObject2 method 54 constructor writing for a new component 52 createChildren method 54 creating components adding events 67 code sample for class file 47 component symbol 12 creating SWC files 18 event metadata 68 extending a class 49 process for writing ActionScript 47 selecting a class name 50 selecting a symbol name 50 using metadata statements 59 writing a constructor 52 custom compone...

Page 80: ...nce properties clip parameters 52 instantiation creating children in components 54 troubleshooting custom components 77 78 invalidateProperties method 56 69 invalidation methods 69 L layers symbols 13 layoutChildren method 57 life cycle of components 51 linkage identifier 13 Live Preview SWF files 17 M measure method implementing 56 preferred properties 56 metadata event 68 explained 59 inspectabl...

Page 81: ...ol layers editing for a new component 13 symbol names for custom components 50 symbol owners for custom components 50 symbolName variable 50 symbolOwner variable 50 symbols compiled clips 8 converting to components 15 editing mode 13 editing for components 13 variables 50 syntax for metadata statements 59 T tags for metadata 60 Timeline editing symbols 13 in custom components 49 tiptext See ToolTi...

Page 82: ...82 Index ...