Chapter 31: Deploying Desktop Applications with Adobe AIR 971 FIGURE 31.9 An AIR installer’s confirmation screen Uninstalling AIR applications You uninstall an AIR desktop application in the same manner as most other native applications. Follow these steps to uninstall AIR applications in Windows: 1. Go to the Windows Control Panel. 2. Select Add or Remove Programs on Windows XP or Uninstall a program on Windows Vista or Windows 7. 3. Select the application entry. 4. Click Remove on Windows XP or Uninstall on Windows Vista or Windows 7. 5. When the Adobe AIR Setup dialog box appears, click Uninstall to remove AIR from your system. To uninstall an AIR application on Mac OS X, just delete the application package file from the /Applications folder by dragging it into the trash. Note Running the AIR installation package file after the application is installed also results in displaying the setup dialog box and displays the uninstall option. n Flex Application Tips and Tricks with AIR As described earlier in this chapter, the subject of developing Flex applications for desktop deploy- ment with AIR is too large for a single chapter. There are, however, a few specific things you do a bit differently in a desktop application, and there are many Flex SDK features that are available only when you’re developing for AIR. These include: 40_488959-ch31.indd 97140_488959-ch31.indd 971 3/5/10 2:49 PM3/5/10 2:49 PM Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. Part V: Additional Subjects 972 l Debugging AIR applications in Flash Builder l Rendering and managing HTML-based and PDF-based content l Using the WindowedApplication component as the application’s root element l Creating channels at runtime for communicating with Remoting gateways In this section, I briefly describe some of these programming and development techniques. On the Web If you want to review the sample applications described in this section, extract the contents of the chap- ter31.zip file into the root folder of the chapter30 Flex desktop application project. Each sample applica- tion includes both an application file and an application descriptor file. n Debugging AIR applications in Flash Builder For the most part, debugging an AIR application in Flash Builder is just like debugging a Web- based Flex application. You have access to all the same debugging tools, including the trace() function, breakpoints, and the capability to inspect the values of application variables when the application is suspended. When you run a Flex application from within Flash Builder in either standard or debug mode, Flash Builder uses ADL (AIR Debug Launcher) in the background. In some cases, ADL can stay in system memory with hidden windows even after an AIR application session has apparently been closed. The symptom for this condition is that when you try to run or debug that or another application, Flash Builder simply does nothing. Because a debugging session is still in memory, Flash Builder can’t start a new one. Follow these steps to recover from this condition in Windows: 1. Open the Windows Task Manager. 2. In the Processes pane, locate and select the entry for adl.exe . 3. Click End Process to force ADL to shut down. 4. Close Task Manager, and return to Flash Builder. Follow these steps to recover from this condition on the Mac: 1. In the Apple menu, select Force Quit. 2. In the Force Quit dialog box, select adl and click the Force Quit button. 3. Close the Force Quit dialog box, and return to Flash Builder. You should now be able to start your next AIR application session successfully. One common sce- nario that can result in this problem is when a runtime error occurs during execution of startup code. For example, if you make a call to a server-based resource from an application-level creation 40_488959-ch31.indd 97240_488959-ch31.indd 972 3/5/10 2:49 PM3/5/10 2:49 PM Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. Chapter 31: Deploying Desktop Applications with Adobe AIR 973 Complete event handler and an unhandled fault occurs, the application window might never become visible. If you’re running the application in debug mode, you can commonly clear the ADL from memory by terminating the debugging session from within Flash Builder. When running in standard mode, however, the ADL can be left in memory with the window not yet visible. To solve this issue, it’s a good idea to explicitly set the application’s initial windows as visible. In the application descriptor file, the <initialWindow> element’s child <visible> property is commented out by default. Because this value defaults to false , if the window construction code never succeeds to a runtime error, you’re left with an invisible window and ADL still in memory. To solve this, open the application’s descriptor file, uncomment the <visible> element, and set its value to true : <visible>true</visible> Working with HTML-based content The Flex framework offers two ways of creating a Web browser object within any application: l The HTMLLoader class is extended from the Sprite class and can be used in any Flash or Flex application. Because this class doesn’t extend from UIComponent , you can’t add it to a Flex container with simple MXML code or by using the addChild() or addElement() methods. l The HTML control is extended from UIComponent and can be instantiated with either MXML or ActionScript code. The HTML control is quite a bit easier to use and provides the same functionality as HTMLLoader . Declaring an instance of the control results in a Web browser instance that can freely navigate to any location on the Web (assuming the client system is currently connected). Instantiating the HTML control As with all visual controls, the HTML control can be instantiated in MXML or ActionScript code. After it’s been instantiated, its location property determines which Web page is displayed. This HTML object, for example, displays Adobe’s home page and expands to fill all available space within the application: <mx:HTML id=”myHTML” width=”100%” height=”100%” location=”http://www.adobe.com”/> When you assign the HTML control’s id property, you can then reset its location as needed from any ActionScript code. This statement resets the HTML control’s location to the Wiley home page: myHTML.location = “http://www.wiley.com”; The application in Listing 31.2 uses an HTTPService object to retrieve an RSS listing from a URL. When the user selects an item from the ComboBox that presents the RSS items, a bit of ActionScript code causes the HTML object to navigate to the selected Web page. 40_488959-ch31.indd 97340_488959-ch31.indd 973 3/5/10 2:49 PM3/5/10 2:49 PM Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. Part V: Additional Subjects 974 Note Because the structure of an RSS feed is consistent regardless of the data provider, this application should work with any RSS feed from any data provider. n LISTING 31.2 A Flex desktop application displaying Web pages from an RSS feed <?xml version=”1.0” encoding=”utf-8”?> <s:WindowedApplication xmlns:fx=”http://ns.adobe.com/mxml/2009” xmlns:s=”library://ns.adobe.com/flex/spark” xmlns:mx=”library://ns.adobe.com/flex/mx” width=”900” height=”600” creationComplete=”app_creationCompleteHandler(event)”> <fx:Declarations> <s:HTTPService id=”photosXML” url=”{feedURL}” result=”resultHandler(event)” fault=”faultHandler(event)”/> </fx:Declarations> <fx:Script> <![CDATA[ import mx.collections.ArrayCollection; import mx.controls.Alert; import mx.events.FlexEvent; import mx.rpc.events.FaultEvent; import mx.rpc.events.ResultEvent; private const feedURL:String = “http://www.wiley.com/WileyCDA/feed/RSS_WILEY2_ALLNEWTITLES.xml”; [Bindable] private var feed:ArrayCollection; private function resultHandler(event:ResultEvent):void { feed = event.result.rss.channel.item as ArrayCollection; feedSelector.selectedIndex = 0; updateHTML(); } private function faultHandler(event:FaultEvent):void { Alert.show(event.fault.faultString, event.fault.faultCode); } private function updateHTML():void { myHTML.location = feedSelector.selectedItem.link; } protected function app_creationCompleteHandler(event:FlexEvent):void { photosXML.send(); } 40_488959-ch31.indd 97440_488959-ch31.indd 974 3/5/10 2:49 PM3/5/10 2:49 PM Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. Chapter 31: Deploying Desktop Applications with Adobe AIR 975 ]]> </fx:Script> <s:layout> <s:VerticalLayout paddingTop=”20” paddingLeft=”10” paddingRight=”10”/> </s:layout> <s:HGroup> <s:Label text=”Select a title:”/> <s:DropDownList id=”feedSelector” width=”700” dataProvider=”{feed}” labelField=”title” change=”updateHTML()”/> </s:HGroup> <mx:HTML id=”myHTML” width=”100%” height=”100%”/> </s:WindowedApplication> On the Web The code in Listing 31.2 is available in the Web site files in the chapter31 project as NewTitlesReader. mxml . n Figure 31.10 shows the completed application, displaying the contents of the RSS feed in the DropDownList and a currently selected Web page in the HTML component. FIGURE 31.10 A simple RSS feed application displaying Web pages in an HTML component instance 40_488959-ch31.indd 97540_488959-ch31.indd 975 3/5/10 2:49 PM3/5/10 2:49 PM Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. Part V: Additional Subjects 976 Navigating with the HTML control In addition to the location property, the HTML control implements these methods that enable you to control navigation with ActionScript code: l historyBack() . Navigates back one step in the control’s history list. l historyForward() . Navigates back one step in the control’s history list. l historyGo(steps:int) . Navigates the number of steps. The value of the steps argument can be positive to move forward or negative to move back. As described earlier, the runtime doesn’t include a copy of Acrobat Reader but instead requires that this software package is already installed on the client system. You can find out whether the cur- rent client system is capable of displaying Acrobat PDF documents by evaluating the HTML con- trol’s static pdfCapability property. The property’s value is matched to constants in a PDFCapability class with these values and meanings: l ERROR_INSTALLED_READER_NOT_FOUND . No version of Acrobat Reader is installed. l ERROR_INSTALLED_READER_TOO_OLD . Acrobat Reader is installed, but it’s older than version 8.1. l ERROR_PREFERED_READER_TOO_OLD . Acrobat Reader 8.1 or later is installed, but another older version is viewed by the operating system as the preferred application for PDF documents. l STATUS_OK . Acrobat Reader 8.1 or later is installed. The application in Listing 31.3 is a simple Web browser application. The application’s navi- gate() function examines the file extension of a document requested by a client application. If the file extension is .pdf and Acrobat Reader 8.1 or later isn’t detected, the application displays an error to the user. LISTING 31.3 A browser application reading PDF content <?xml version=”1.0” encoding=”utf-8”?> <s:WindowedApplication xmlns:fx=”http://ns.adobe.com/mxml/2009” xmlns:s=”library://ns.adobe.com/flex/spark” xmlns:mx=”library://ns.adobe.com/flex/mx” width=”1024” height=”768”> <fx:Script> <![CDATA[ import mx.controls.Alert; [Bindable] private var myURL:String = “http://”; private function navigate():void { 40_488959-ch31.indd 97640_488959-ch31.indd 976 3/5/10 2:49 PM3/5/10 2:49 PM Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. Chapter 31: Deploying Desktop Applications with Adobe AIR 977 myURL = urlInput.text; if (myURL.substr(0,4) != “http”) { myURL = “http://” + myURL; } var fileExtension:String = myURL.substr(myURL.length-3, 3); if (fileExtension.toLowerCase() == “pdf” && HTML.pdfCapability != HTMLPDFCapability.STATUS_OK) { Alert.show(“This request requires Acrobat Reader 8.1 or later”, “Acrobat Error”); } else { myHTML.location = myURL; status = myURL; } } ]]> </fx:Script> <s:layout> <s:VerticalLayout paddingTop=”20” paddingLeft=”10” paddingRight=”10”/> </s:layout> <s:HGroup verticalAlign=”middle”> <s:Label text=”My AIR Web Browser” fontWeight=”bold” fontSize=”14”/> <mx:Spacer width=”25”/> <s:Label text=”New URL:” fontWeight=”bold” fontSize=”10”/> <s:TextInput id=”urlInput” text=”{myURL}” enter=”navigate()”/> <s:Button label=”Go” click=”navigate()”/> </s:HGroup> <mx:HTML id=”myHTML” width=”100%” height=”100%”/> </s:WindowedApplication> On the Web The code in Listing 31.3 is available in the Web site files in the chapter31 project as AIRWebBrowser. mxml . n Using the WindowedApplication component Flex applications designed for desktop deployment typically use <s:WindowedApplication> as the application root element. A beginning desktop application’s code looks like this: <?xml version=”1.0” encoding=”utf-8”?> <s:WindowedApplication xmlns:fx=”http://ns.adobe.com/mxml/2009” xmlns:s=”library://ns.adobe.com/flex/spark” xmlns:mx=”library://ns.adobe.com/flex/mx”> 40_488959-ch31.indd 97740_488959-ch31.indd 977 3/5/10 2:49 PM3/5/10 2:49 PM Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. Part V: Additional Subjects 978 <fx:Declarations> <!-- Place non-visual elements (e.g., services, value objects) here --> </fx:Declarations> </s:WindowedApplication> The WindowedApplication component is extended from Application and provides all the application-level functionality you expect from a typical Flex application. It also adds these capa- bilities that are unique to Flex desktop applications: l Native menus can be displayed and integrated into the overall application look and feel. l The application can be integrated with a dock or system tray icon to provide easy access to common application functions. l The application can display operating system-specific “chrome” (the graphics in the appli- cation window’s border, title bar, and control icons). l A status bar can be displayed at the bottom of the application window for string-based sta- tus messages. Here’s one example: The WindowedApplication component can display a status bar at the bot- tom of the application window. This display is controlled by two of the WindowedApplication component’s properties: l showStatusBar:Boolean . When this property is true (the default), the application window displays a status bar. l status:String . The string value displayed in the status bar. The following modified custom updateHTML() function from the NewTitlesReader applica- tion updates the application’s status bar with the title of the currently selected RSS item: private function updateHTML():void { myHTML.location = feedSelector.selectedItem.link; status = “Current Title: “ + feedSelector.selectedItem.title; } Creating Remoting channels at runtime When a Web-based Flex application communicates with an application server that supports Flash Remoting (known as the Remoting Service in LiveCycle Data Services and BlazeDS), it typically uses a channel definition with dynamic expressions that evaluate at runtime to the location of the server from which the application was downloaded. This is the default my-amf channel delivered with BlazeDS: <channel-definition id=”my-amf” class=”mx.messaging.channels.AMFChannel”> <endpoint 40_488959-ch31.indd 97840_488959-ch31.indd 978 3/5/10 2:49 PM3/5/10 2:49 PM Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. Chapter 31: Deploying Desktop Applications with Adobe AIR 979 url=”http://{server.name}:{server.port}/{context.root}/ messagebroker/amf” class=”flex.messaging.endpoints.AMFEndpoint”/> </channel-definition> The <endpoint> element’s url attribute uses dynamic expressions to evaluate the server name and port and the context root of the hosting instance of BlazeDS. This approach doesn’t work with desktop applications deployed with AIR, because the concept of “the current application server” doesn’t have any meaning in a desktop application. Instead, you must provide the explicit location of the server-based application to which Remoting requests should be sent at runtime. You can solve this in one of two ways: l If the location of the server providing Remoting Services is always the same, you can define a custom channel in the application’s services configuration file with a hard-coded url : <endpoint url=”http://www.mycompany.com/messagebroker/amf” class=”flex.messaging.endpoints.AMFEndpoint”/> l For flexibility and the capability to set a url at runtime, declare a channel in either MXML or ActionScript code. The RemoteObject component has a channelSet property, cast as a class named ChannelSet , that contains one or more instances of the AMFChannel component. To declare a runtime channel in MXML, nest the <mx:ChannelSet> tag inside a <mx:RemoteObject> tag pair’s <mx:channelSet> property. Then nest one or more <mx:AMFChannel> tags, and assign each a uri property pointing to the selected server and its Remoting url . Note If you declare more than one AMFChannel tag inside the channelSet , they’re treated as a list in order of preference. The client application always tries to use the first channel; if there’s a communication failure, it goes to the next one, and so on. n The following RemoteObject instance declares a single AMFChannel at runtime: <s:RemoteObject id=”myRO” destination=”myRemotingDestination”> <s:channelSet> <s:ChannelSet> <s:channels> <s:AMFChannel uri=”http://myserver/messagebroker/amf”/> </s:channels> </s:ChannelSet> </s:channelSet> </s:RemoteObject> 40_488959-ch31.indd 97940_488959-ch31.indd 979 3/5/10 2:49 PM3/5/10 2:49 PM Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. Part V: Additional Subjects 980 You can accomplish the same result with ActionScript. The following ActionScript code creates a ChannelSet object, populates it with a single AMFChannel object, and adds it to the RemoteObject component: var endpointURL:String = “http://myserver/messagebroker/amf”; var cs:ChannelSet = new ChannelSet(); var customChannel:Channel = new AMFChannel(“myCustomAMF”, endpointURL); cs.addChannel(customChannel); myRemoteObject.channelSet = cs; Tip You also can create channels at runtime for use with the Message Service, Proxy Service, and Data Management Service when using LiveCycle Data Services or BlazeDS. n Note When communicating with remote servers using the HTTPService or WebService components in a desktop application, you don’t have to deal with the cross-domain security constraint as you do with Web-based Flex applications. Because the application loads locally, it isn’t subject to the restrictions of the Web browser’s security sandbox and can make connections freely over the Web just like any other local application. n A Conclusion about Adobe AIR In addition to the features described in this chapter, AIR applications can accomplish the following tasks that aren’t possible with Flex Web applications: l Full screen and spanned monitor display l Integration with native visual components such the operating system’s window and menu systems l Creation of applications with transparency that serve as widgets l Reading and writing files and folders on the local file system l Persisting data in SQLite, a local database embedded in the runtime l Interacting with the system clipboard, including drag-and-drop to and from AIR applica- tions and the OS l Synchronization of data managed on the server by LiveCycle Data Services l Access to all network services supported by the Flex framework The subject of building and deploying AIR-based desktop applications is worthy of an entire book, and in fact there are many such books available. In particular, check out the Adobe AIR Bible (from Wiley, of course!). 40_488959-ch31.indd 98040_488959-ch31.indd 980 3/5/10 2:49 PM3/5/10 2:49 PM Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. [...]... with host component, 44 6 44 7 creating, 44 4 44 6 FXG graphics, adding to, 44 9 45 1 overview, 44 4 skin parts, adding required, 44 8 44 9 skin states, declaring required, 44 7 44 8 CustomAppSkinComplete.mxml file, 45 1 CustomAppSkin.mxml file, 44 8, 44 9 CustomButton component, 348 CustomButton.mxml file, 348 CustomButtonSkinComplete.mxml file, 46 0 CustomButtonSkin.mxml file, 46 2 CustomDragAndDrop.mxml file, 397... property, 148 custom skin for applying with style sheet declaration, 45 3 assigning skin, 45 1 45 2 associating with host component, 44 6 44 7 creating, 44 4 44 6 FXG graphics, adding to, 44 9 45 1 loading at runtime, 45 4 45 5 overview, 44 4 skin parts, adding required, 44 8 44 9 skin states, declaring required, 44 7 44 8 dimensions, controlling, 130–131 layout property, setting, 131–1 34 MenuBar control, 49 6 overview,... with, 43 2 43 9 in Flex applications, 43 9 44 1 overview, 43 2 MXML, declaring in arbitrary shapes, drawing with Path class, 42 3 42 5 elliptical shapes, drawing, 42 2 42 3 filters, applying, 43 1 43 2 gradient fills, 42 5 42 8 gradient strokes, 42 1 42 2 lines, drawing, 42 1 overview, 101, 42 0 43 2 rectangular shapes, drawing, 42 2 42 3 reusing graphic elements, 42 8 43 0 scaling graphic elements, 43 0 overview, 41 9 42 0... 55–57 Adobe Creative Suite, 19, 42 0, 43 2 43 9 See also specific programs by name Adobe Developer Center Web site, 879 Adobe Dreamweaver, 93–96 Adobe Fireworks, 43 7 43 9 Adobe Flash Builder 4 See Flash Builder 4 Adobe Flash Catalyst, 4, 5, 10 Adobe Flash Player See Flash Player Adobe Flex 4 See Flex 4 Adobe Flex 4 SDK Command Prompt option, 28 Adobe Illustrator, 43 3 43 7, 43 9 Adobe Integrated Runtime See... ActionScript code with, 1 24 128 overview, 26 searching for code, 58– 64 setter functions in, generating, 546 – 549 user interface, 49 –55 Flash Builder 4 Premium Edition, 4, 32 Flash Builder 4 Standard Edition, 31 Flash Builder Premium license, 648 Flash Catalyst, Adobe, 4, 5, 10 Flash CS5 Professional, 20 Flash Lite, 20 Flash perspective, Flash Builder, 75 Flash Player See also Proxy Service ActionScript Virtual... global search and replace, 61 global selector, CSS, 346 , 352–353, 355, 360 globally unique package name, 141 Go to File for Breakpoint button, 183 gradient fills, 42 5 42 8, 43 5 43 7, 43 8 43 9 gradient strokes, 42 1 42 2 GradientDemos.mxml file, 42 7 GradientEntry class, 42 2, 42 7 42 8 GradientStroke class, 42 1 42 2 Graphic class, 42 1 graphic design, with Flash Builder, 10 root element, 43 3 graphical... control, 644 data collection, using as, 48 5 48 6 DataGrid control, 615, 616 menu control, 49 3, 49 4 overview, 571 pie charts, 649 PieSeries series class, 659 ViewStack, using as, 48 7 48 8 DataSeries class, 652 Data/Services view, Flash Builder, 712, 7 14, 715, 847 , 933 date application, 943 – 944 Date class, 945 date controls, 273–275 DateChooser control, 273–275, 307–308, 518–520 DateField control, 273–2 74, 275,... flash- unicode-table.xml file, 302 flashvars variable, 130, 726 flat data, grouping, 644 – 645 flat presentation, Package Explorer view, 52 Flex 1.x, 106 Flex 2, 105, 106–107 Flex 3, 105, 106–107 Flex 3 .4 projects, 46 Flex 4 development tools, 26–28 documentation, 29 versus Flash Builder, 4, 7 Flash Player, 18–26 versus Flash Professional development, 8–11 Flex applications, 4 8 namespace prefixes, 107 namespaces,... data, 644 – 645 GroupingCollection class, 644 GroupingCollection2 class, 644 GroupingField objects, 644 groupName property, 269–270 H H command, 42 4 Halo theme, 342 hard-coded data providers, 575–577 hard-coded XML structure, declaring, 752 hasFormat() method, 395 HBox container, 312–313, 3 14 315, 317–318, 48 8 48 9 HBoxDemo.mxml file, 3 14 HEAD method, 725 section, applets, 92 Header component, 47 4 header()... custom label function, 653–6 54 custom namespace prefix, 144 , 549 custom perspective, Eclipse, 42 custom pop-up windows, 503, 521–529 custom resource bundles, 947 –953 Custom section, Components view, 146 , 162 custom skins binding to component, 45 1 45 5 for other Spark components assigning with CSS, 46 1 46 2 creating new skin, 45 5 46 0 customizing skin, 46 2 46 7 overview, 44 4 for Spark Application component . graphics, adding to, 44 9 45 1 loading at runtime, 45 4 45 5 overview, 44 4 skin parts, adding required, 44 8 44 9 skin states, declaring required, 44 7 44 8 dimensions,. Builder 4. See Flash Builder 4 Adobe Flash Catalyst, 4, 5, 10 Adobe Flash Player. See Flash Player Adobe Flex 4. See Flex 4 Adobe Flex 4 SDK Command Prompt