Guia do desenvolvedor do

ACTIONSCRIPT 3.0

 2011 Adobe Systems Incorporated and its licensors. All rights reserved.
Copyright

Guia do Desenvolvedor do ActionScript 3.0 This guide is protected under copyright law, furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in the informational content contained in this guide. This guide is licensed for use under the terms of the Creative Commons Attribution Non-Commercial 3.0 License. This License allows users to copy, distribute, and transmit the guide for noncommercial purposes only so long as (1) proper attribution to Adobe is given as the owner of the guide; and (2) any reuse or distribution of the guide contains a notice that use of the guide is governed by these terms. The best way to provide notice is to include the following link. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/3.0/ Adobe, the Adobe logo, Acrobat, Acrobat Capture, Acrobat Connect, Acrobat Messenger, Acrobat 3D Capture, ActionScript, ActiveTest, Adobe ActionSource, Adobe AIR, Adobe AIR logo, Adobe Audition, Adobe Caslon, Adobe Connect, Adobe DataWarehouse, Adobe Dimensions, Adobe Discover, Adobe Financial Services, Adobe Garamond, Adobe Genesis, Adobe Griffo, Adobe Jenson, Adobe Kis, Adobe OnLocation, Adobe Originals logo, Adobe PDF logo, Adobe Premiere, AdobePS, Adobe SiteSearch, Adobe Type Manager, Adobe Wave, Adobe Wave logo , Adobe WebType, Adobe Wood Type, After Effects, AIR , Alexa, Andreas, Arno, ATM, Authorware, Balzano, Banshee, Benson Scripts, Better by Adobe. , Bickham Script, Birch, Blackoak, Blue Island, Brioso, BusinessCatalyst, Buzzword, Caflisch Script, Cairngorm, Calcite, Caliban, Captivate, Carta, Chaparral, Charlemagne, Cheq, Classroom in a Book, ClickMap, Co-Author, ColdFusion, ColdFusion Builder, Conga Brava, Contribute, Copal, Coriander, Cottonwood, Creative Suite, Critter, Cronos, CS Live, Custom Insight, CustomerFirst, Cutout, Digital Pulse, Director, Distiller, DNG logo, Dreamweaver, DV Rack, Encore, Engaging beyond the Enterprise, ePaper, Ex Ponto, Fireworks, Flash, Flash logo, Flash Access, Flash Access logo, Flash Builder, Flash Cast , FlashCast, Flash Catalyst, FlashHelp, Flash Lite, Flash on., FlashPaper, Flash Platform Services logo , Flex, Flex Builder, Flood, Font Folio, Frame , FrameCenter, FrameConnections, FrameMaker, FrameManager, FrameViewer, FreeHand, Fusaka, Galahad, Giddyup, Giddyup Thangs, GoLive, GoodBarry, Graphite, HomeSite, HBX, HTML Help Studio, HTTP Dynamic Streaming logo , Hypatia, Illustrator, ImageReady, Immi 505, InCopy, InDesign, Ironwood, Jimbo, JRun, Juniper, Kazuraki, Kepler, Kinesis, Kozuka Gothic, Kozuka Mincho, Kuler, Leander Script, Lens Profile Creator logo , Lightroom, Lithos, LiveCycle, Macromedia, Madrone, Mercado, Mesquite, Mezz, Minion, Mojo, Montara, Moonglow, MXML, Myriad, Mythos, Nueva, Nyx, 1-Step RoboPDF, Omniture, Open Screen Project, Open Source Media Framework logo, OpenType logo, Ouch!, Ovation, PageMaker, PageMaker Portfolio, PDF JobReady, Penumbra, Pepperwood, Photoshop, Photoshop logo, Pixel Bender, Poetica, Ponderosa, Poplar, Postino, PostScript, PostScript logo, PostScript 3, PostScript 3i, Powered by XMP, Prana, PSPrinter, Quake, Rad, Reader, Real-Time Analytics, Reliq, RoboEngine, RoboHelp, RoboHTML, RoboLinker, RoboPDF, RoboScreenCapture, RoboSource Control, Rosewood, Roundtrip HTML, Ryo, Sanvito, Sava, Scene7, See Whats Possible , Script Teaser, Shockwave, Shockwave Player logo, Shuriken Boy, Silentium, Silicon Slopes, SiteCatalyst, SiteCatalyst NetAverages, Software Video Camera, Sonata, Soundbooth, SoundEdit, Strumpf, Studz, Tekton, Test&Target, 360Code, Toolbox, Trajan, TrueEdge, Type Reunion, Ultra, Utopia, Vector Keying, Version Cue, VirtualTrak, Visual Call, Visual Communicator, Visual Sciences, Visual Sensor, Visual Server, Viva, Voluta , Warnock, Waters Titling, Wave , Willow, XMP logo, Zebrawood are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. Android is a trademark of Google Inc. ActiveX and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and other countries. Macintosh is a trademark of Apple Inc., registered in the United States and other countries. Java is a trademark or registered trademark of Sun Microsystems, Inc. in the United States and other countries. All other trademarks are the property of their respective owners. Updated Information/Additional Third Party Code Information available at http://www.adobe.com/go/thirdparty. Portions include software under the following terms: This product includes software developed by the Apache Software Foundation (http://www.apache.org/). MPEG Layer-3 audio compression technology licensed by Fraunhofer IIS and Thomson Multimedia (http://www.mp3licensing.com). This software is based in part on the work of the Independent JPEG Group. Speech compression and decompression technology licensed from Nellymoser, Inc. (www.nellymoser.com). Video in Flash Player is powered by On2 TrueMotion video technology. 1992-2005 On2 Technologies, Inc. All Rights Reserved. http://www.on2.com. This product contains either BSAFE and/or TIPEM software by RSA Security, Inc.

Sorenson Spark video compression and decompression technology licensed from Sorenson Media, Inc. Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA Notice to U.S. Government End Users: The Software and Documentation are Commercial Items, as that term is defined at 48 C.F.R. 2.101, consisting of Commercial Computer Software and Commercial Computer Software Documentation, as such terms are used in 48 C.F.R. 12.212 or 48 C.F.R. 227.7202, as applicable. Consistent with 48 C.F.R. 12.212 or 48 C.F.R. 227.7202-1 through 227.7202-4, as applicable, the Commercial Computer Software and Commercial Computer Software Documentation are being licensed to U.S. Government end users (a) only as Commercial Items and (b) with only those rights as are granted to all other end users pursuant to the terms and conditions herein. Unpublished-rights reserved under the copyright laws of the United States. Adobe agrees to comply with all applicable equal opportunity laws including, if appropriate, the provisions of Executive Order 11246, as amended, Section 402 of the Vietnam Era Veterans Readjustment Assistance Act of 1974 (38 USC 4212), and Section 503 of the Rehabilitation Act of 1973, as amended, and the regulations at 41 CFR Parts 60-1 through 60-60, 60-250, and 60-741. The affirmative action clause and regulations contained in the preceding sentence shall be incorporated by reference.

ltima atualizao em 29/3/2011

iii

Contedo
Captulo 1: Trabalho com datas e horas Gerenciamento de datas de calendrio e horas Controle de intervalos de tempo ......................................................................... 1 ..................................................................... 6 ....................................................................................... 4

Exemplo de data e hora: relgio analgico simples

Captulo 2: Trabalho com sequncias de caracteres Noes bsicas de strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Criao de strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 A propriedade length Comparao de strings Concatenao de strings

Trabalho com caracteres em strings

Obteno de representaes de strings de outros objetos Localizao de substrings e padres em strings Exemplos de sequncias de caracteres: arte ASCII

Converso de strings entre maisculas e minsculas

Captulo 3: Trabalho com matrizes Noes bsicas sobre matrizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Matrizes indexadas Matrizes associativas Clonagem de matrizes Extenso da classe Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Matrizes multidimensionais

Exemplo de matriz: PlayList

Captulo 4: Manipulao de erros Noes bsicas da manipulao de erros Tipos de erros Manipulao de erros no ActionScript 3.0

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Trabalho com as verses de depurador dos tempos de execuo do Flash Manipulao de erros sncronos em um aplicativo Criao de classes de erros personalizadas Resposta a eventos e status de erros Comparao das classes Error

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Exemplo de tratamento de erros: aplicativo CustomErrors

Captulo 5: Uso de expresses regulares Noes bsicas de expresses regulares: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Sintaxe da expresso regular . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Mtodos para usar expresses regulares com strings Exemplo de expresses regulares: um analisador Wiki

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Contedo

iv

Captulo 6: Trabalho com XML Noes bsicas sobre XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 A abordagem E4X em relao ao processamento de XML Objetos XML Objetos XMLList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Inicializao de variveis XML Como percorrer estruturas XML Uso de namespaces XML Converso de tipo XML

Montagem e transformao de objetos XML

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Leitura de documentos XML externos

Exemplo XML no ActionScript: carregamento de dados RSS da Web Captulo 7: Manipulao de eventos Noes bsicas sobre a manipulao de eventos O fluxo de eventos Objetos de evento Ouvintes de evento

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Como a manipulao de eventos do ActionScript 3.0 difere das verses anteriores

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Exemplo de tratamento de evento: relgio de alarme Captulo 8: Trabalhar com domnios de aplicativo Captulo 9: Programao de exibio Noes bsicas sobre a programao de exibio Principais classes de exibio Vantagens da abordagem da lista de exibio Trabalho com os objetos de exibio Manipulao de objetos de exibio Animao de objetos Orientao do palco

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Carregamento dinmico do contedo da exibio Exemplo de objeto de exibio: SpriteArranger

Captulo 10: Trabalho com geometria Noes bsicas de geometria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 Uso de objetos Point Uso de objetos Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 . . . . . . . . . . . . . . . . . . . . . . . . . 209 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 Uso de objetos Rectangle

Exemplo de geometria: aplicao de uma transformao de matriz em um objeto de exibio

Captulo 11: Uso da API de desenho Noes bsicas da API de desenho . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 A classe Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 Desenho de linhas e curvas

Desenho de formas utilizando os mtodos incorporados Criao de linhas e preenchimentos gradientes Uso da classe Math com mtodos de desenho

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Contedo

Animao com a API de desenho Uso avanado da API de desenho

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

Exemplo de API de desenho: gerador visual algortmico

Captulo 12: Trabalho com bitmaps Noes bsicas do trabalho com bitmaps Classes Bitmap e BitmapData Manipulao de pixels Cpia de dados de bitmap Rolagem de bitmaps

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

Texturas com funes de rudo Benefcios do mapeamento mip

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

Exemplo de bitmap: lua giratria animada

Decodificao assncrona de imagens de bitmap

Captulo 13: Filtro de objetos de exibio Noes bsicas sobre filtragem de objetos de exibio Criao e aplicao de filtros Filtros de exibio disponveis

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

Exemplo de filtragem de objetos de exibio: bancada do filtro

Captulo 14: Trabalho com sombreadores Pixel Bender Noes bsicas de sombreadores Pixel Bender . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 Carregamento ou incorporao de um sombreador Acesso aos metadados de sombreador Uso de um sombreador . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

Especificao de valores de entrada e de parmetro de sombreador

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303

Captulo 15: Trabalho com clipes de filme Noes bsicas de clipes de filme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316 Trabalho com objetos MovieClip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323 Controle de reproduo de clipe de filme Carregamento de um arquivo SWF externo

Criao de objetos MovieClip com o ActionScript Exemplo de clipe de filme: RuntimeAssetsExplorer

Captulo 16: Trabalho com cinemtica inversa Noes bsicas de cinemtica inversa . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329 Viso geral da animao de armaduras IK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 Obteno de informaes sobre uma armadura IK Movimentao de uma armadura IK Utilizando suspenses Uso de eventos IK

Ocorrncia de IKMover e limitao de seu movimento

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334

Captulo 17: Trabalho em 3D (trs dimenses) Noes bsicas de 3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 Noes bsicas sobre os recursos 3D do Flash Player e o runtime do AIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Contedo

vi

Criao e movimentao de objetos 3D Exemplo: Projeo em perspectiva

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

Projeo de objetos 3D em uma exibio 2D Execuo de transformaes 3D complexas Uso de tringulos para obter efeitos 3D

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

Captulo 18: Princpios bsicos do trabalho com texto Captulo 19: Uso da classe TextField Exibio de texto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358 Seleo e manipulao de texto Captura de entrada de texto Restrio de entrada de texto Formatao de texto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372

Renderizao avanada de texto Trabalho com texto esttico

Exemplo de TextField: formatao de texto estilo jornal

Captulo 20: Uso do Flash Text Engine Criao e exibio de texto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383 Manipulao de eventos no FTE Formatao de texto Trabalho com fontes Controle de texto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398

Exemplo de Flash Text Engine: layout das notcias

Captulo 21: Uso da Text Layout Framework Viso geral do Text Layout Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413 Uso da Text Layout Framework Estruturao de texto com a TLF Formatao de texto com a TLF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426

Importao e exportao de texto com a TLF

Gerenciamento de contineres de texto com a TLF Tratamento de eventos com a TLF

Ativao da seleo de texto, edio e recurso desfazer com a TLF Posicionamento de imagens dentro do texto Captulo 22: Trabalho com som Noes bsicas do trabalho com som Compreenso da arquitetura do som Trabalho com sons incorporados

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431

Carregamento de arquivos de som externos Trabalho com arquivos de fluxo de som Reproduo de sons

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442

Trabalho com udio gerado dinamicamente

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443

Consideraes sobre segurana ao carregar e reproduzir sons Controle do volume e do panorama do som Trabalho com metadados de som

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Contedo

vii

Acesso a dados de som brutos Captura de entrada do som Exemplo de som: Podcast Player

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449

Captulo 23: Trabalho com vdeo Noes bsicas sobre vdeo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462 Noes bsicas sobre formatos de vdeo Noes bsicas sobre a classe Video Carregamento de arquivos de vdeo Controle da reproduo de vdeo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474

Reproduo de vdeo no modo de tela cheia Arquivos de vdeo em fluxo contnuo Noes bsicas sobre pontos de sinalizao Uso de pontos de sinalizao e metadados Tpicos avanados sobre arquivos de vdeo Exemplo de vdeo: jukebox de vdeo

Criao de mtodos de retorno de chamada para metadados e pontos de sinalizao

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493

Utilizando a classe StageVideo para renderizao acelerada por hardware

Captulo 24: Trabalhando com cmeras Noes bsicas sobre a classe Camera . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508 Exibio do contedo da cmera na tela Desenvolvimento do aplicativo de cmera Conexo cmera de um usurio Verificao da instalao das cmeras . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513

Deteco de permisses de acesso cmera Maximizando a qualidade de vdeo da cmera Monitorando o status da cmera

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514

Captulo 25: Uso de gerenciamento de direitos digitais Entendendo o fluxo de trabalho de contedo protegido. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516 Membros e eventos relacionados a DRM da classe NetStream Uso da classe DRMStatusEvent Uso da classe DRMErrorEvent Uso da classe DRMManager Uso da classe DRMContentData Uso da classe DRMAuthenticateEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530

Atualizando o Flash Player para suportar o Flash Access

Captulo 26: Incluso de contedo em PDF no AIR Deteco de recurso de PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532 Carregamento de contedo em PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535 Gravando em script o contedo em PDF

Limitaes conhecidas do contedo em PDF no AIR

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Contedo

viii

Captulo 27: Princpios bsicos da interao do usurio Captura da entrada do usurio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537 Gerenciamento do foco . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539 Descobrindo tipos de entrada

Captulo 28: Entrada do teclado Captura da entrada do teclado . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541 Uso da classe IME Teclados virtuais . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548

Captulo 29: Entrada do mouse Captura da entrada do mouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556 Exemplo de entrada de mouse: WordSearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558

Captulo 30: Toque, multitoque e entrada de gestos Introduo entrada de toque . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563 Descoberta de suporte ao toque Tratamento de eventos de toque Tocar e arrastar Tratamento de Eventos de gestos Soluo de problemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574

Captulo 31: Copiar e colar Princpios bsicos do copiar e colar Copiar e colar HTML no AIR

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578

Leitura e gravao na rea de transferncia do sistema Formatos de dados da rea de transferncia

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580

Captulo 32: Entrada do acelermetro Verificando suporte ao acelermetro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587 Detectando mudanas no acelermetro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588

Captulo 33: Arrastar e soltar no AIR Princpios bsicos de arrastar e soltar no AIR Suporte ao gesto de arrastar para fora Arrastar e soltar em HTML Suporte ao gesto de arrastar para dentro

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598

Arrastar dados para fora de um elemento HTML

Arrastar dados para dentro de um elemento HTML

Exemplo: Substituio do comportamento padro de arrastar para dentro HTML Tratamento de arquivos soltos em caixas de proteo HTML de no-aplicativo Soltando promessas de arquivo

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606

Captulo 34: Trabalho com menus Noes bsicas do menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615 Criao de menus nativos (AIR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625 Sobre menus de contexto em HTML (AIR) Exibio de menus nativos pop-up (AIR)

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Contedo

ix

Tratamento de itens de menu

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627

Exemplo de menu nativo: menu de janela e de aplicativo (AIR)

Captulo 35: cones da barra de tarefas no AIR Sobre cones na barra de tarefas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631 cones de encaixe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634 cones da bandeja do sistema

cones e botes da barra de tarefas do Windows

Captulo 36: Trabalho com o sistema de arquivos Uso da classe FileReference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636 Usar a API do sistema de arquivos do AIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651

Captulo 37: Armazenamento de dados locais Objetos compartilhados . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687 Armazenamento local criptografado . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696

Captulo 38: Trabalho com bancos de dados SQL locais no AIR Sobre bancos de dados SQL locais . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 700 Criao e modificao de um banco de dados . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740 Manipulao de dados de um banco de dados SQL Uso da criptografia com bancos de dados SQL

Uso de operaes de banco de dados sncronas e assncronas Estratgias para trabalhar com bancos de dados SQL

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763

Captulo 39: Trabalhar com matrizes de bytes Ler e escrever um ByteArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766 Exemplo de ByteArray: leitura de um arquivo .zip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 772

Captulo 40: Noes bsicas de rede e comunicao Interfaces de rede . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780 Mudanas na conectividade de rede . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 781 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 784 Registro do Sistema de Nome de Domnios (DNS)

Captulo 41: Soquetes Soquetes TCP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 786 Soquetes UDP (AIR) Endereos IPv6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799

Captulo 42: Comunicao HTTP Carregamento de dados externos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 801 Solicitaes do servio da Web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 810 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 818 Abertura de um URL em outro aplicativo

Captulo 43: Comunicao com outras instncias do Flash Player e AIR Sobre a classe Local . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 820 Envio de mensagens entre dois aplicativos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 822 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 824 Conexo a contedo em domnios diferentes e a aplicativos AIR

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Contedo

Captulo 44: Comunicao com processos nativos do AIR Viso geral das comunicaes do processo nativo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 827 Abertura e fechamento de um processo nativo Comunicao com um processo nativo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 828 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 830 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 829

Consideraes de segurana para a comunicao do processo nativo Captulo 45: Uso da API externa Noes bsicas de uso da API externa Requisitos e vantagens da API externa Uso da classe ExternalInterface

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 833 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835 . . . . . . . . . . . . . . . . . . . . . 840 . . . 846

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836

Exemplo de API externa: comunicaa entre ActionScript e JavaScript em um navegador da Web

Exemplo de API externa: comunicao entre ActionScript e um aplicativo de desktop que usa o controle de ActiveX Captulo 46: Ambiente do sistema cliente Noes bsicas do ambiente do sistema cliente Uso da classe System Uso da classe Capabilities

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 852

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 853 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 855

Exemplo de recursos: deteco de capacidades do sistema

Captulo 47: Chamada e encerramento do aplicativo AIR Chamada do aplicativo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 860 Captura de argumentos de linha de comando Invocao de um aplicativo AIR do navegador Encerramento do aplicativo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866 Invocando um aplicativo AIR no logon do usurio

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 868

Captulo 48: Trabalho com informaes de tempo de execuo do AIR e de sistema operacional Gerenciamento de associaes de arquivos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 870 Obteno da verso do tempo de execuo e do nvel de patch Deteco de recursos do AIR Rastreamento de presena do usurio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 871 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 871 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872

Captulo 49: Trabalho com janelas nativas do AIR Princpios bsicos das janelas nativas no AIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 873 Criao de janelas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 880 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 889 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 899 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 900 Gerenciamento de janelas

Monitorando eventos de janela Exibio de janelas em tela cheia

Captulo 50: Exibio de telas no AIR Princpios bsicos das telas de exibio no AIR Enumerao das telas

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 903

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 904

Captulo 51: Impresso Noes bsicas de impresso Impresso de uma pgina

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 907 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 908 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 912

Tarefas do tempo de execuo e impresso de sistema do Flash Configurao de tamanho, escala e orientao Tcnicas avanadas de impresso

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 914

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Contedo

xi

Exemplo de impresso: impresso de vrias pginas Exemplo de impresso: escala, corte e resposta

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 916 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 920

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 918

Exemplo de impresso: configurao de pgina e opes de impresso Captulo 52: Geolocation Detectando mudanas de geolocalizao

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 923

Captulo 53: Internacionalizao de aplicativos Introduo internacionalizao de aplicativos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 926 Viso geral do pacote flash.globalization Determinando a localidade Formatando nmeros Formatando data e hora . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 927 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 928 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 932 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 936 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 938 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 939

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 930 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 934

Formatando valores de moeda

Classificando e comparando strings

Converso de caracteres maisculos e minsculos

Exemplo: Internacionalizao de um aplicativo de acionamento de aes

Captulo 54: Localizao de aplicativos Seleo de cdigo de idiomas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 944 Localizao de contedo Flex Localizao de contedo Flash Localizao de aplicativos AIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 946

Localizao de datas, horas e moedas

Captulo 55: Sobre o ambiente HTML Viso geral do ambiente HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 948 AIR e Webkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 951

Captulo 56: Programao de HTML e JavaScript no AIR Sobre a classe HTMLLoader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 967 Como evitar erros JavaScript relacionados segurana Acesso s classes API do AIR no JavaScript Sobre URLs no AIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 969 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 974 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 976

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 975 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 978 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 982 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 984 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 986

Como tornar objetos ActionScript disponveis para JavaScript Acesso a objetos HTML DOM e JavaScript do ActionScript Incorporao de contedo SWF em HTML Converso de objetos Date e RegExp Uso de bibliotecas do ActionScript em uma pgina HTML Manipulao de folha de estilos HTML do ActionScript

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 984

Contedo cross-scripting em caixas de proteo de segurana distintas Captulo 57: Script no continer HTML do AIR Exibio de propriedades de objetos HTMLLoader Rolagem de contedo HTML Acesso lista de histrico de HTML

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 991

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 994 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 995 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 996 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 996

Definio do agente do usurio usado ao carregar contedo HTML

Configurao de codificao de caractere para uso de contedo HTML.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Contedo

xii

Definio de interfaces do usurio como navegadores para contedo HTML Criao de subclasses da classe HTMLLoader

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008

Captulo 58: Tratamento de eventos relacionados a HTML no AIR eventos HTMLLoader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1010 Tratamento de eventos DOM com o ActionScript Resposta a excees JavaScript no capturadas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1010 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1011 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1013

Tratamento de eventos de tempo de execuo com JavaScript

Captulo 59: Exibio de contedo HTML em aplicativos mveis Objetos StageWebView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1016 Contedo Histrico Foco . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1017 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1018 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1019 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1022 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1024 Eventos de navegao

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1020

Captura de bitmap Exibindo anncios

Captulo 60: Segurana Viso geral da segurana da Plataforma Flash Caixas de proteo de segurana Controles de permisso Restrio de APIs de rede Carregamento de contedo Cross-scripting

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1027

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1029

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1033 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1042 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1044 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1045 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1052 . . . . . . . . . . . . . . . . 1058

Segurana de modo de tela cheia

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1048 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1054 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1058 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1059 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1059 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1063

Acesso mdia carregada como dados Carregamento de dados

Carregamento de contedo incorporado de arquivos SWF importados em um domnio de segurana Trabalho com contedo legado Controle do acesso URL de sada Objetos compartilhados Segurana do AIR Configurao de permisses de LocalConnection

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1061

Acesso a cmera, microfone, rea de transferncia, mouse e teclado

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1063

Captulo 61: Como Usar Exemplos do ActionScript Tipos de Exemplos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1085 Execuo de exemplos do ActionScript 3.0 no Flash Professional Execuo de exemplos do ActionScript 3.0 no Flash Builder Execuo de exemplos do ActionScript 3.0 em dispositivos mveis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1086 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1089 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1088

Captulo 62: Suporte SQL em bancos de dados locais Sintaxe SQL para a qual h suporte . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1094 Suporte ao tipo de dados . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1116

Captulo 63: ID, argumentos e mensagens detalhadas de erro SQL

ltima atualizao em 29/3/2011

Captulo 1: Trabalho com datas e horas

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Data e hora talvez no sejam tudo, mas normalmente so um fator chave nos aplicativos de software. O ActionScript 3.0 oferece formas teis para gerenciar datas de calendrio, horas e intervalos de tempo. Duas classes principais permitem gerenciar data e hora: a classe Date e a nova classe Timer do pacote flash.utils. Datas e horas so informaes comuns usadas nos programas ActionScript. Por exemplo, voc talvez precise saber o dia da semana atual ou medir o tempo que o usurio gasta em uma tela especfica, entre muitas outras possibilidades. No ActionScript, voc pode usar a classe Date para representar um nico ponto temporal, incluindo informaes de data e hora. Em uma ocorrncia de Date esto includos valores de unidades individuais de data e hora, como ano, ms, data, dia da semana, hora, minutos, segundos, milissegundos e fuso horrio. Para usos mais avanados, o ActionScript tambm inclui a classe Timer, que pode ser usada para realizar aes aps um determinado atraso ou em intervalos repetidos.

Mais tpicos da Ajuda

Date flash.utils.Timer

Gerenciamento de datas de calendrio e horas

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Todas as funes de gerenciamento de datas de calendrio e horas do ActionScript 3.0 esto concentradas na classe Date de nvel superior. A classe Date contm mtodos e propriedades que permitem manipular datas e horas no horrio UTC ou em um fuso horrio especfico local. O UTC uma definio de horrio padro basicamente igual ao horrio do Meridiano de Greenwich (GMT).

Criao de objetos de Date

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe Date tem um dos mtodos de construtor mais versteis de todas as classes bsicas. possvel cham-la de quatro formas diferentes. Primeiro, se no houver nenhum parmetro, o construtor Date() retornar um objeto de Date que contm data e hora atuais, com base no seu fuso horrio local. Eis um exemplo:
var now:Date = new Date();

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com datas e horas

Segundo, se houver um nico parmetro numrico, o construtor Date() ir trat-lo como o nmero de milissegundos desde 1 de janeiro de 1970 e retornar um objeto de Date correspondente. Observe que o valor de milissegundos fornecido tratado como o nmero de milissegundos desde 1 de janeiro de 1970, em UTC. No entanto, o objeto Date mostra valores no seu fuso horrio local, a no ser que voc use mtodos especficos de UTC para recuper-los e exibilos. Se voc criar um novo objeto Date usando um nico parmetro de milissegundos, leve em considerao a diferena de fuso entre o horrio local e o UTC. As seguintes instrues criam um objeto Date definido como meia-noite do dia 1 de janeiro de 1970, em UTC:
var millisecondsPerDay:int = 1000 * 60 * 60 * 24; // gets a Date one day after the start date of 1/1/1970 var startTime:Date = new Date(millisecondsPerDay);

Terceiro, possvel transmitir vrios parmetros numricos para o construtor Date(). Esses parmetros so tratados como ano, ms, dia, hora, minuto, segundo e milissegundo, respectivamente, e um objeto Date correspondente retornado. Supe-se que esses parmetros de entrada esto no horrio local, no no UTC. As seguintes instrues obtm um objeto Date definido como meia-noite do dia 1 de janeiro de 2000, no horrio local:
var millenium:Date = new Date(2000, 0, 1, 0, 0, 0, 0);

Quarto, possvel transmitir um parmetro com uma nica string para o construtor Date(). O construtor tentar analisar os componentes de data ou hora dessa string e retornar um objeto Date correspondente. Se voc usar essa abordagem, recomendado colocar o construtor Date() entre um bloco try..catch para detectar qualquer erro de anlise. O construtor Date() aceita diversos formatos diferentes de seqncias de caracteres (que esto listados na Referncia do ActionScript 3.0 para a plataforma Adobe Flash). A instruo a seguir inicializa um novo objeto Date usando um valor de string:
var nextDay:Date = new Date("Mon May 1 2006 11:30:00 AM");

Se o construtor Date() no conseguir analisar o parmetro de string, no lanar uma exceo. No entanto, o objeto Date resultante ter um valor de data invlido.

Obteno de valores de unidade de tempo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc pode extrair valores para vrias unidades de tempo de um objeto Date usando propriedades ou mtodos da classe Date. Cada propriedade a seguir fornece o valor de uma unidade de tempo no objeto Date:

A propriedade fullYear A propriedade month, que est em um formato numrico que vai de 0 para janeiro at 11 para dezembro A propriedade date, que o nmero do calendrio do dia do ms, no intervalo de 1 a 31 A propriedade day, que o dia da semana em formato numrico, com 0 para domingo A propriedade hours, no intervalo de 0 a 23 A propriedade minutes A propriedade seconds A propriedade milliseconds
Na realidade, a classe Date fornece diversas maneiras para obter cada um desses valores. Voc pode obter, por exemplo, o valor do ms de um objeto Date de quatro formas diferentes:

A propriedade month O mtodo getMonth()

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com datas e horas

A propriedade monthUTC O mtodo getMonthUTC()

Os quatro mtodos so praticamente iguais em termos de eficincia, de modo que voc pode usar a abordagem mais adequada para seu aplicativo. Todas as propriedades listadas acima representam componentes do valor de data total. Por exemplo, a propriedade milliseconds nunca ser maior do que 999, pois, quando atingir o nmero 1000, o valor da propriedade seconds aumentar em uma unidade e a propriedade milliseconds ser zerada. Se desejar obter o valor do objeto Date em termos de milissegundos desde 1 de janeiro de 1970 (UTC), use o mtodo getTime(). Seu correspondente, o mtodo setTime(), permite alterar o valor de um objeto Date existente usando os milissegundos desde 1 de janeiro de 1970 (UTC).

Execuo de clculos aritmticos de data e hora

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior possvel realizar operaes de adio e subtrao em datas e horas com a classe Date. Os valores de Date so mantidos internamente em termos de milissegundos, de modo que voc deve converter outros valores em milissegundos antes de adicion-los ou subtra-los dos objetos Date. Se o seu aplicativo efetua vrios clculos aritmticos de data e hora, crie constantes que armazenam valores comuns de unidade de tempo em milissegundos, conforme mostrado a seguir:
public static const millisecondsPerMinute:int = 1000 * 60; public static const millisecondsPerHour:int = 1000 * 60 * 60; public static const millisecondsPerDay:int = 1000 * 60 * 60 * 24;

Agora fcil efetuar clculos aritmticos de data usando unidades de tempo padro. O cdigo a seguir define um valor de data como uma hora do horrio atual usando os mtodos getTime() e setTime():
var oneHourFromNow:Date = new Date(); oneHourFromNow.setTime(oneHourFromNow.getTime() + millisecondsPerHour);

Outra maneira de definir um valor de data criar um novo objeto Date usando um nico parmetro de milissegundos. Por exemplo, o cdigo a seguir adiciona 30 dias a uma data para calcular outra:
// sets the invoice date to today's date var invoiceDate:Date = new Date(); // adds 30 days to get the due date var dueDate:Date = new Date(invoiceDate.getTime() + (30 * millisecondsPerDay));

Em seguida, a constante millisecondsPerDay multiplicada por 30 para representar o perodo de 30 dias e o resultado adicionado ao valor invoiceDate e usado para definir o valor dueDate.

Converso entre fusos horrios

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Clculos aritmticos de data e hora so teis quando voc deseja converter datas de um fuso horrio para outro. O mtodo getTimezoneOffset() serve para isso, pois retorna o valor como a diferena de minutos entre o fuso horrio do objeto Date e o UTC. Ele retorna um valor em minutos porque nem todos os fusos horrios so definidos como incrementos de horas inteiras - alguns tm diferenas de meia hora em relao s zonas vizinhas.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com datas e horas

O exemplo a seguir usa a diferena de fuso para converter uma data do horrio local em UTC. Para fazer a converso, primeiro calcula-se o valor do fuso horrio em milissegundos e, depois, ajusta-se o valor de Date de acordo com o resultado:
// creates a Date in local time var nextDay:Date = new Date("Mon May 1 2006 11:30:00 AM"); // converts the Date to UTC by adding or subtracting the time zone offset var offsetMilliseconds:Number = nextDay.getTimezoneOffset() * 60 * 1000; nextDay.setTime(nextDay.getTime() + offsetMilliseconds);

Controle de intervalos de tempo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Ao desenvolver aplicativos usando o Adobe Flash CS4 Professional, voc tem acesso linha do tempo, que oferece uma progresso uniforme quadro a quadro do seu aplicativo. No entanto, em projetos exclusivamente do ActionScript, necessrio usar outros mecanismos de controle de tempo.

Loops versus timers

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Em algumas linguagens de programao, voc deve desenvolver seus prprios esquemas de controle de tempo usando instrues de loop como for ou do..while. As instrues de loop geralmente so executadas conforme permitido pela mquina local, ou seja, o aplicativo executado mais rapidamente em algumas mquinas e mais lentamente em outras. Se o seu aplicativo precisa de um intervalo de tempo consistente, associe-o a um calendrio ou relgio real. Muitos aplicativos, como jogos, animaes e controladores em tempo real, precisam de mecanismos de tempo regulares que se adaptem a cada mquina. A classe Timer do ActionScript 3.0 fornece uma soluo incrvel. Usando o modelo de eventos do ActionScript 3.0, a classe Timer envia eventos de tempo sempre que um intervalo especificado atingido.

A classe Timer
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O melhor modo de manipular funes de controle de tempo no ActionScript 3.0 usar a classe Timer (flash.utils.Timer) para enviar eventos sempre que um intervalo for atingido. Para iniciar um timer, voc precisa criar primeiro uma ocorrncia da classe Timer, informando com que freqncia um evento de tempo deve ser gerado e quantas vezes isso deve ser feito antes de parar. Por exemplo, o cdigo a seguir cria uma ocorrncia de Timer que envia um evento por segundo e continua durante 60 segundos:
var oneMinuteTimer:Timer = new Timer(1000, 60);

O objeto Timer envia um objeto TimerEvent sempre que o intervalo especificado atingido. Um tipo de evento do objeto TimerEvent timer (definido pela constante TimerEvent.TIMER). Um objeto TimerEvent contm as mesmas propriedades de um objeto Event padro.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com datas e horas

Se a ocorrncia de Timer for definida como um nmero fixo de intervalos, um evento timerComplete (definido pela constante TimerEvent.TIMER_COMPLETE) tambm ser enviado quando o intervalo final for atingido. Veja um pequeno aplicativo de exemplo que mostra a classe Timer em ao:
package { import flash.display.Sprite; import flash.events.TimerEvent; import flash.utils.Timer; public class ShortTimer extends Sprite { public function ShortTimer() { // creates a new five-second Timer var minuteTimer:Timer = new Timer(1000, 5); // designates listeners for the interval and completion events minuteTimer.addEventListener(TimerEvent.TIMER, onTick); minuteTimer.addEventListener(TimerEvent.TIMER_COMPLETE, onTimerComplete); // starts the timer ticking minuteTimer.start(); } public function onTick(event:TimerEvent):void { // displays the tick count so far // The target of this event is the Timer instance itself. trace("tick " + event.target.currentCount); } public function onTimerComplete(event:TimerEvent):void { trace("Time's Up!"); } } }

Ao ser criada, a classe ShortTimer cria uma ocorrncia de Timer que ser acionada uma vez por segundo durante cinco segundos. Em seguida, so adicionados dois ouvintes ao timer: um que ouve cada acionamento e outro que ouve o evento timerComplete. Em seguida, comea o acionamento do timer e, a partir desse ponto, o mtodo onTick() executado em intervalos de um segundo. O mtodo onTick() simplesmente exibe a contagem de acionamentos atual. Depois de cinco segundos, o mtodo
onTimerComplete() executado, informando que o tempo acabou.

Ao executar este exemplo, voc deve ver as seguintes linhas na janela do console ou rastreamento, na velocidade de uma linha por segundo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com datas e horas

tick 1 tick 2 tick 3 tick 4 tick 5 Time's Up!

Funes de controle de tempo do pacote flash.utils

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O ActionScript 3.0 contm vrias funes de controle de tempo similares s que estavam disponveis no ActionScript 2.0. Essas funes so fornecidas no nvel do pacote flash.utils e funcionam da mesma maneira como no ActionScript 2.0.
Funo
clearInterval(id:uint):void clearTimeout(id:uint):void getTimer():int

Descrio Cancela uma chamada setInterval() especificada. Cancela uma chamada setTimeout() especificada. Retorna o nmero de milissegundos desde que o Adobe Flash Player ou o Adobe AIR foi inicializado.

setInterval(closure:Function, delay:Number, ... arguments):uint setTimeout(closure:Function, delay:Number, ... arguments):uint

Executa uma funo em um intervalo especificado (em milissegundos).

Executa uma funo especificada aps um atraso especificado (em milissegundos).

Essas funes esto includas no ActionScript 3.0 por questes de compatibilidade com verses anteriores. A Adobe no recomenda utiliz-las em novos aplicativos do ActionScript 3.0. Em geral, mais fcil e mais eficiente usar a classe Timer em seus aplicativos.

Exemplo de data e hora: relgio analgico simples

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Um nico exemplo de relgio analgico ilustra esses dois conceitos de data e hora:

Obteno de data e hora atuais e extrao de valores para horas, minutos e segundos Utilizao de Timer para definir o ritmo de um aplicativo
Para obter os arquivos de aplicativo desse exemplo, consulte www.adobe.com/go/learn_programmingAS3samples_flash_br. Os arquivos do aplicativo SimpleClock esto localizados na pasta Amostras/SimpleClock. O aplicativo consiste nos seguintes arquivos:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com datas e horas

Arquivo SimpleClockApp.mxml ou SimpleClockApp.fla com/example/programmingas3/simpleclock/SimpleClock.as com/example/programmingas3/simpleclock/AnalogClockFace.as

Descrio O arquivo principal do aplicativo no Flash (FLA) ou no Flex (MXML).

O arquivo de aplicativo principal. Desenha a superfcie de um relgio redondo e os ponteiros de horas, minutos e segundos com base na hora.

Definio da classe SimpleClock

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O exemplo do relgio simples, mas uma boa idia para organizar at mesmo aplicativos simples que podem ser expandidos com facilidade no futuro. Para tanto, o aplicativo SimpleClock usa a classe SimpleClock para manipular as tarefas de inicializao e controle de tempo e usa outra classe chamada AnalogClockFace para exibir realmente a hora. Veja o cdigo que define e inicializa a classe SimpleClock (observe que, na verso Flash, SimpleClock estende a classe Sprite):
public class SimpleClock extends UIComponent { /** * The time display component. */ private var face:AnalogClockFace; /** * The Timer that acts like a heartbeat for the application. */ private var ticker:Timer;

A classe tem duas propriedades importantes:

A propriedade face, que uma ocorrncia da classe AnalogClockFace A propriedade ticker, que uma ocorrncia da classe Timer
A classe SimpleClock usa um construtor padro. O mtodo initClock() realiza o trabalho de configurao real, criando a superfcie do relgio e iniciando o acionamento da ocorrncia de Timer.

Criao da superfcie do relgio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior As prximas linhas do cdigo SimpleClock criam a superfcie do relgio que usada para exibir a hora:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com datas e horas

/** * Sets up a SimpleClock instance. */ public function initClock(faceSize:Number = 200) { // creates the clock face and adds it to the display list face = new AnalogClockFace(Math.max(20, faceSize)); face.init(); addChild(face); // draws the initial clock display face.draw();

O tamanho da superfcie pode ser transmitido para o mtodo initClock(). Se nenhum valor de faceSize for transmitido, ser usado o tamanho padro de 200 pixels. Em seguida, o aplicativo inicializa a face e adiciona-a lista de exibio utilizando o mtodo addChild() herdado da classe DisplayObjectContainer. O mtodo AnalogClockFace.draw() chamado para exibir a superfcie do relgio uma vez, mostrando a hora atual.

Incio do timer
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Assim que a superfcie do relgio criada, o mtodo initClock() configura um timer:
// creates a Timer that fires an event once per second ticker = new Timer(1000); // designates the onTick() method to handle Timer events ticker.addEventListener(TimerEvent.TIMER, onTick); // starts the clock ticking ticker.start();

Primeiro, esse mtodo percorre uma ocorrncia de Timer que enviar um evento por segundo (a cada 1000 milissegundos). Como nenhum outro parmetro repeatCount transmitido para o construtor Timer(), o Timer ser repetido indefinidamente. O mtodo SimpleClock.onTick() ser executado uma vez por segundo quando o evento timer for recebido:
public function onTick(event:TimerEvent):void { // updates the clock display face.draw(); }

O mtodo AnalogClockFace.draw() simplesmente desenha a superfcie e os ponteiros do relgio.

Exibio do horrio atual

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A maior parte do cdigo na classe AnalogClockFace envolve a configurao dos elementos de exibio da superfcie do relgio. Ao ser inicializado, o AnalogClockFace desenha um contorno circular, coloca um rtulo de texto numrico em cada marcao de hora e cria trs objetos Shape, um para cada ponteiro do relgio (horas, minutos e segundos).

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com datas e horas

Assim que o aplicativo SimpleClock executado, o mtodo AnalogClockFace.draw() chamado a cada segundo do seguinte modo:
/** * Called by the parent container when the display is being drawn. */ public override function draw():void { // stores the current date and time in an instance variable currentTime = new Date(); showTime(currentTime); }

Este mtodo salva a hora atual em uma varivel para que o horrio no mude no meio do desenho dos ponteiros do relgio. Em seguida, o mtodo showTime() chamado para exibir os ponteiros do seguinte modo:
/** * Displays the given Date/Time in that good old analog clock style. */ public function showTime(time:Date):void { // gets the time values var seconds:uint = time.getSeconds(); var minutes:uint = time.getMinutes(); var hours:uint = time.getHours(); // multiplies by 6 to get degrees this.secondHand.rotation = 180 + (seconds * 6); this.minuteHand.rotation = 180 + (minutes * 6); // Multiply by 30 to get basic degrees, then // add up to 29.5 degrees (59 * 0.5) // to account for the minutes. this.hourHand.rotation = 180 + (hours * 30) + (minutes * 0.5); }

Primeiro, este mtodo extrai os valores para horas, minutos e segundos do horrio atual. Depois, esses valores so usados para calcular o ngulo de cada ponteiro. Como faz uma rotao completa em 60 segundos, o ponteiro dos segundos gira 6 graus a cada segundo (360/60). O ponteiro dos minutos gira do mesmo modo em cada minuto. O ponteiro das horas tambm atualizado a cada minuto e pode avanar um pouco medida que os minutos passam. Ele gira 30 graus por hora (360/12), mas tambm gira meio grau por minuto (30 graus dividido por 60 minutos).

ltima atualizao em 29/3/2011

10

Captulo 2: Trabalho com sequncias de caracteres

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe String contm mtodos que permitem trabalhar com strings de texto. Strings so importantes ao trabalhar com muitos objetos. Os mtodos descritos aqui so teis para trabalhar com sequncias de caracteres usadas em objetos como TextField, StaticText, XML, ContextMenu e FileReference. Strings so seqncias de caracteres. O ActionScript 3.0 oferece suporte a caracteres ASCII e Unicode.

Mais tpicos da Ajuda

String RegExp parseFloat() parseInt()

Noes bsicas de strings

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Em linguagem de programao, uma string um valor de texto, uma seqncia de letras, nmeros ou outros caracteres combinados em um nico valor. Por exemplo, esta linha de cdigo cria uma varivel com o tipo de dados String e atribui um valor de string literal quela varivel:
var albumName:String = "Three for the money";

Conforme mostrado nesse exemplo, no ActionScript possvel denotar um valor de string incluindo o texto entre aspas duplas ou simples. Estes so vrios exemplos adicionais de strings:
"Hello" "555-7649" "http://www.adobe.com/"

Ao manipular uma parte de texto no ActionScript, voc est trabalhando com um valor de string. A classe String do ActionScript o tipo de dados que pode ser usado para trabalhar com valores de texto. As ocorrncias de strings so usadas com freqncia para propriedades, parmetros de mtodos e assim por diante em muitas outras classes ActionScript. Conceitos e termos importantes A lista de referncia a seguir contm termos importantes relacionados a sequncias de caracteres que voc encontrar:
ASCII Um sistema que representa caracteres de texto e smbolos em programas de computador. O sistema ASCII

oferece suporte ao alfabeto ingls de 26 letras, mais um conjunto limitado de caracteres adicionais.
Caractere A menor unidade de dados de texto (uma nica letra ou smbolo).

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sequncias de caracteres

11

Concatenao Juno de vrios valores de strings com a adio de um ao final do outro, criando um novo valor de

string.
String vazia Uma string que no contm nenhum texto, espao em branco ou outros caracteres, escrita como "". Um

valor de string vazia diferente de uma varivel String com um valor nulo, uma varivel String nula uma varivel que no tem uma ocorrncia de String atribuda a ela, enquanto que uma string vazia tem uma ocorrncia com um valor que no contm nenhum caractere.
String Um valor textual (seqncia de caracteres). Literal de string (ou string literal) Um valor de string escrito explicitamente em cdigo como um valor de texto includo entre aspas duplas ou aspas simples. Substring Uma string que faz parte de outra string. Unicode Um sistema padro que representa caracteres de texto e smbolos em programas de computador. O sistema

Unicode permite usar qualquer caractere em qualquer sistema de gravao.

Criao de strings
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe String usada para representar dados de string (textuais) no ActionScript 3.0. As strings do ActionScript oferecem suporte a caracteres ASCII e Unicode. A maneira mais simples de criar uma string usar uma string literal. Para declarar um string literal, use caracteres de aspas duplas retas (") ou de aspas simples ('). Por exemplo, as duas strings a seguir so equivalentes:
var str1:String = "hello"; var str2:String = 'hello';

Tambm possvel declarar uma string usando o operador new, da seguinte maneira:
var str1:String = new String("hello"); var str2:String = new String(str1); var str3:String = new String(); // str3 == ""

As duas strings a seguir so equivalentes:

var str1:String = "hello"; var str2:String = new String("hello");

Para usar aspas simples (') em uma string literal definida com delimitadores de aspas simples ('), use o caractere de escape barra invertida (\). De maneira semelhante, para usar aspas duplas (") em uma string literal definida com delimitadores de aspas duplas ("), use o caractere de escape barra invertida (\). As duas strings a seguir so equivalentes:
var str1:String = "That's \"A-OK\""; var str2:String = 'That\'s "A-OK"';

possvel escolher o uso de aspas simples ou de aspas duplas com base em quaisquer aspas simples ou duplas existentes em uma string literal, como no exemplo a seguir:
var str1:String = "ActionScript <span class='heavy'>3.0</span>"; var str2:String = '<item id="155">banana</item>';

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sequncias de caracteres

12

Lembre-se de que o ActionScript diferencia aspas simples retas (') e aspas simples esquerda ou direita (' ou ' ). O mesmo verdadeiro para aspas duplas. Use aspas retas para delinear strings literais. Ao colar texto de outra origem no ActionScript, use os caracteres corretos. Conforme mostrado na tabela a seguir, possvel usar o caractere de escape de barra invertida (\) para definir outros caracteres em strings literais:
Seqncia de escape
\b \f \n \r \t \unnnn

Caractere Backspace Feed de formulrio Nova linha Retorno de carro Tabulao O caractere Unicode com o cdigo de caractere especificado pelo nmero hexadecimal nnnn; por exemplo, \u263a o caractere smiley. O caractere ASCII com o cdigo de caractere especificado pelo nmero hexadecimal nn Aspas simples Aspas duplas Caractere de barra invertida simples

\\xnn \' \" \\

A propriedade length
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Cada string tem uma propriedade length que igual ao nmero de caracteres da string:
var str:String = "Adobe"; trace(str.length); // output: 5

Uma string vazia e uma string nula tm um comprimento de 0, conforme mostrado no exemplo a seguir:
var str1:String = new String(); trace(str1.length); // output: 0 str2:String = ''; trace(str2.length);

// output: 0

Trabalho com caracteres em strings

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Cada caractere em uma string tem uma posio de ndice na string (um inteiro). A posio do ndice do primeiro caractere 0. Por exemplo, na seguinte string, o caractere y est na posio 0 e o caractere w est na posio 5:
"yellow"

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sequncias de caracteres

13

possvel examinar caracteres individuais em vrias posies em uma string usando os mtodos charAt() e charCodeAt(), como neste exemplo:
var str:String = "hello world!"; for (var i:int = 0; i < str.length; i++) { trace(str.charAt(i), "-", str.charCodeAt(i)); }

Quando esse cdigo executado, a seguinte sada produzida:

h e l l o w o r l d ! - 104 - 101 - 108 - 108 - 111 32 - 119 - 111 - 114 - 108 - 100 - 33

Tambm possvel usar cdigos de caracteres para definir uma string usando o mtodo fromCharCode(), como no exemplo a seguir:
var myStr:String = String.fromCharCode(104,101,108,108,111,32,119,111,114,108,100,33); // Sets myStr to "hello world!"

Comparao de strings
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior possvel usar os seguintes operadores para comparar strings: <, <=, !=, ==, => e >. Esses operadores podem ser usados com declaraes condicionais, como if ewhile, como no exemplo a seguir:
var str1:String = "Apple"; var str2:String = "apple"; if (str1 < str2) { trace("A < a, B < b, C < c, ..."); }

Ao usar esses operadores com strings, o ActionScript considera o valor de cdigo de cada caractere na string, comparando da esquerda para a direita, como no seguinte exemplo:
trace("A" < "B"); // true trace("A" < "a"); // true trace("Ab" < "az"); // true trace("abc" < "abza"); // true

Use os operadores == e != para comparar strings umas com as outras e para comparar strings com outros tipos de objetos, conforme mostrado no exemplo a seguir:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sequncias de caracteres

14

var str1:String = "1"; var str1b:String = "1"; var str2:String = "2"; trace(str1 == str1b); // true trace(str1 == str2); // false var total:uint = 1; trace(str1 == total); // true

Obteno de representaes de strings de outros objetos

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior possvel obter uma representao de String de qualquer tipo de objeto. Todos os objetos tm um mtodo toString() para essa finalidade:
var n:Number = 99.47; var str:String = n.toString(); // str == "99.47"

Ao usar o operador de concatenao + com uma combinao de objetos String que no so strings, no necessrio usar o mtodo toString(). Para obter detalhes sobre concatenao, consulte a seo a seguir. A funo global String() retorna o mesmo valor para um determinado objeto que o valor retornado pelo objeto de chamada do mtodo toString().

Concatenao de strings
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A concatenao de strings significa utilizar duas strings e uni-las seqencialmente em uma. Por exemplo, possvel usar o operador + para concatenar duas strings:
var str1:String = "green"; var str2:String = "ish"; var str3:String = str1 + str2; // str3 == "greenish"

Tambm possvel usar o operador += para produzir o mesmo resultado, conforme mostrado no exemplo a seguir:
var str:String = "green"; str += "ish"; // str == "greenish"

Alm disso, a classe String inclui um mtodo concat() que pode ser usado da seguinte maneira:
var str1:String = "Bonjour"; var str2:String = "from"; var str3:String = "Paris"; var str4:String = str1.concat(" ", str2, " ", str3); // str4 == "Bonjour from Paris"

Se voc usar o operador + (ou o operador +=) com o objeto String e um objeto no-String, o ActionScript converter automaticamente o objeto no-String em um objeto String para avaliar a expresso, conforme mostrado neste exemplo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sequncias de caracteres

15

var str:String = "Area = "; var area:Number = Math.PI * Math.pow(3, 2); str = str + area; // str == "Area = 28.274333882308138"

No entanto possvel usar parnteses para agrupamento para fornecer contexto para o operador +, conforme mostrado no exemplo a seguir:
trace("Total: $" + 4.55 + 1.45); // output: Total: $4.551.45 trace("Total: $" + (4.55 + 1.45)); // output: Total: $6

Localizao de substrings e padres em strings

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Substrings so strings dentro de uma string. Por exemplo, a string "abc" tem as seguinte substrings: "", "a", "ab", "abc", "b", "bc", "c". possvel usar os mtodos do ActionScript para localizar substrings de uma string. Padres so definidos no ActionScript por strings ou por expresses regulares. Por exemplo, a expresso regular a seguir define um padro especfico, as letras A, B e C seguidas por um caractere de dgito (as barras so delimitadores de expresses regulares):
/ABC\d/

O ActionScript inclui mtodos para localizao de padres em strings e para substituir correspondncias localizadas com substrings de substituio. Esses mtodos so descritos nas sees a seguir. Expresses regulares podem definir padres intrincados. Para obter mais informaes, consulte Uso de expresses regulares na pgina 76.

Localizao de uma substring pela posio do caractere

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os mtodos substr() e substring() so semelhantes. Os dois retornam uma substring de uma string. Os dois utilizam dois parmetros. Nos dois mtodos, o primeiro parmetro a posio do caractere inicial na string fornecida. No entanto, no mtodo substr(), o segundo parmetro o length da substring a ser retornada e, no mtodo substring(), o segundo parmetro a posio do caractere no end da substring (que no includa na string retornada). Este exemplo mostra a diferena entre esses dois mtodos:
var str:String = "Hello from Paris, Texas!!!"; trace(str.substr(11,15)); // output: Paris, Texas!!! trace(str.substring(11,15)); // output: Pari

O mtodo slice() funciona de maneira semelhante ao mtodo substring(). Quando recebe dois inteiros no negativos como parmetros, ele funciona exatamente da mesma forma. No entanto o mtodo slice() pode utilizar inteiros negativos como parmetros e nesse caso a posio do caractere utilizada a partir do final da string, conforme mostrado no exemplo a seguir:
var str:String = "Hello from Paris, trace(str.slice(11,15)); // output: trace(str.slice(-3,-1)); // output: trace(str.slice(-3,26)); // output: trace(str.slice(-3,str.length)); // trace(str.slice(-8,-3)); // output: Texas!!!"; Pari !! !!! output: !!! Texas

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sequncias de caracteres

16

possvel combinar inteiros no negativos e negativos como os parmetros do mtodo slice().

Localizao da posio do caractere de uma substring correspondente

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior possvel usar os mtodos indexOf() e lastIndexOf() para localizar substrings dentro de uma string, conforme mostrado no exemplo a seguir:
var str:String = "The moon, the stars, the sea, the land"; trace(str.indexOf("the")); // output: 10

Observe que o mtodo indexOf() faz distino entre maisculas e minsculas. possvel especificar um segundo parmetro para indicar a posio do ndice na string na qual iniciar a pesquisa, da seguinte maneira:
var str:String = "The moon, the stars, the sea, the land" trace(str.indexOf("the", 11)); // output: 21

O mtodo lastIndexOf() localiza a ltima ocorrncia de uma substring na string:

var str:String = "The moon, the stars, the sea, the land" trace(str.lastIndexOf("the")); // output: 30

Se voc incluir um segundo parmetro com o mtodo lastIndexOf(), a pesquisa ser conduzida naquela posio do ndice na string operando retroativamente (da direita para a esquerda):
var str:String = "The moon, the stars, the sea, the land" trace(str.lastIndexOf("the", 29)); // output: 21

Criao de uma matriz de substrings segmentadas por um delimitador

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior possvel usar o mtodo split() para criar uma matriz de substrings que dividida com base em um delimitador. Por exemplo, possvel segmentar uma string delimitada por vrgula ou por tabulao em vrias strings. O exemplo a seguir mostra como dividir uma matriz em substrings com o caractere e comercial (&) como o delimitador:
var queryStr:String = "first=joe&last=cheng&title=manager&StartDate=3/6/65"; var params:Array = queryStr.split("&", 2); // params == ["first=joe","last=cheng"]

O segundo parmetro do mtodo split(), que opcional, define o tamanho mximo da matriz retornada. Tambm possvel usar uma expresso regular como o caractere delimitador:
var str:String = "Give me\t5." var a:Array = str.split(/\s+/); // a == ["Give","me","5."]

Para obter mais informaes, consulte Uso de expresses regulares na pgina 76 e a Referncia do ActionScript 3.0 para a plataforma Adobe Flash.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sequncias de caracteres

17

Localizao de padres em sequncias de caracteres e substituio de subsequncias de caracteres

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe String inclui os seguintes mtodos para trabalhar com padres em strings:

Use os mtodos match() e search() para localizar substrings que correspondem a um padro. Use o mtodo replace() para localizar substrings que correspondem a um padro e substitu-las por uma
substring especificada. Esses mtodos so descritos nas sees a seguir. possvel usar strings ou expresses regulares para definir padres usados nesses mtodos. Para obter mais informaes sobre expresses regulares, consulte Uso de expresses regulares na pgina 76. Localizao de substrings correspondentes O mtodo search() retorna a posio do ndice da primeira substring que corresponde a um determinado padro, conforme mostrado neste exemplo:
var str:String = "The more the merrier."; // (This search is case-sensitive.) trace(str.search("the")); // output: 9

Tambm possvel usar expresses regulares para definir o padro a ser correspondido, conforme mostrado no exemplo a seguir:
var pattern:RegExp = /the/i; var str:String = "The more the merrier."; trace(str.search(pattern)); // 0

A sada do mtodo trace() 0, porque o primeiro caractere na string a posio 0 do ndice. O sinalizador i definido na expresso regular, portanto a pesquisa no faz distino entre maisculas e minsculas. O mtodo search() localiza apenas uma correspondncia e retorna sua posio inicial no ndice, mesmo que o sinalizador g (global) esteja definido na expresso regular. O exemplo a seguir mostra uma expresso regular mais intrincada que corresponde a uma string entre aspas duplas:
var pattern:RegExp = /"[^"]*"/; var str:String = "The \"more\" the merrier."; trace(str.search(pattern)); // output: 4 str = "The \"more the merrier."; trace(str.search(pattern)); // output: -1 // (Indicates no match, since there is no closing double quotation mark.)

O mtodo match() funciona de maneira semelhante. Ele pesquisa uma substring correspondente. No entanto quando voc usa o sinalizador global em um padro de expresso regular, como no exemplo a seguir, match() retorna uma matriz de substrings correspondentes:
var str:String = "[email protected], [email protected]"; var pattern:RegExp = /\w*@\w*\.[org|com]+/g; var results:Array = str.match(pattern);

A matriz results definida como o seguinte:

["[email protected]","[email protected]"]

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sequncias de caracteres

18

Para obter mais informaes sobre expresses regulares, consulte Uso de expresses regulares na pgina 76. Substituio de substrings correspondentes possvel usar o mtodo replace() para pesquisar um padro especificado em uma string e substituir correspondncias pela string de substituio especificada, conforme mostrado no exemplo a seguir:
var str:String = "She sells seashells by the seashore."; var pattern:RegExp = /sh/gi; trace(str.replace(pattern, "sch")); //sche sells seaschells by the seaschore.

Observe que, neste exemplo, as strings correspondentes no fazem distino entre maisculas e minsculas porque o sinalizador i (ignoreCase) est definido na expresso regular, e vrias correspondncias so substitudas porque o sinalizador g (global) est definido. Para obter mais informaes, consulte Uso de expresses regulares na pgina 76. possvel incluir os seguintes cdigos de substituio $na string de substituio. O texto de substituio mostrado na tabela a seguir inserido no lugar do cdigo de substituio $:
$ Code
$$ $& $`

Texto de substituio $ A substring correspondida. A parte da string que precede a substring correspondida. Esse cdigo usa o caractere aspas simples retas esquerdas (`), no aspas simples retas (') ou aspas simples inglesas esquerdas (' ). A parte da string que segue a substring correspondida. Esse cdigo usa as aspas simples retas (' ). A n correspondncia de grupo entre parnteses capturado, em que n um nico dgito, 1 a 9, e $n no seguido por um dgito decimal. A nn correspondncia de grupo entre parnteses capturado, em que nn um nmero decimal de dois dgitos (01 a 99). Se a nn captura estiver indefinida, o texto de substituio ser uma string vazia.

$' $n $nn

Por exemplo, veja a seguir o uso dos cdigos de substituio $2 e $1 que representam o primeiro e o segundo grupos de captura correspondidos:
var str:String = "flip-flop"; var pattern:RegExp = /(\w+)-(\w+)/g; trace(str.replace(pattern, "$2-$1")); // flop-flip

Tambm possvel usar uma funo como o segundo parmetro do mtodo replace(). O texto correspondente substitudo pelo valor retornado da funo.
var str:String = "Now only $9.95!"; var price:RegExp = /\$([\d,]+.\d+)+/i; trace(str.replace(price, usdToEuro)); function usdToEuro(matchedSubstring:String, capturedMatch1:String, str:String):String { var usd:String = capturedMatch1; usd = usd.replace(",", ""); var exchangeRate:Number = 0.853690; var euro:Number = parseFloat(usd) * exchangeRate; const euroSymbol:String = String.fromCharCode(8364); return euro.toFixed(2) + " " + euroSymbol; } index:int,

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sequncias de caracteres

19

Ao usar uma funo como o segundo parmetro do mtodo replace(), os seguintes argumentos so passados para a funo:

A parte correspondente da string. Quaisquer correspondncias de grupos entre parnteses capturadas. O nmero de argumentos transmitidos dessa
maneira ir variar dependendo do nmero de correspondncias parentticas. possvel determinar o nmero de correspondncias entre parnteses verificando arguments.length - 3 no cdigo da funo.

A posio de ndice na string em que a correspondncia comea. A string completa.

Converso de strings entre maisculas e minsculas

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Conforme mostrado no exemplo a seguir, os mtodos toLowerCase() e toUpperCase() convertem caracteres alfabticos da string em minsculas e maisculas, respectivamente:
var str:String = "Dr. Bob Roberts, #9." trace(str.toLowerCase()); // dr. bob roberts, #9. trace(str.toUpperCase()); // DR. BOB ROBERTS, #9.

Aps a execuo desses mtodos, a string de origem permanece inalterada. Para transformar a string de origem, use o seguinte cdigo:
str = str.toUpperCase();

Esses mtodos funcionam com caracteres estendidos, no simplesmente com a a z e A a Z:

var str:String = "Jos Bara"; trace(str.toUpperCase(), str.toLowerCase()); // JOS BARA jos bara

Exemplos de sequncias de caracteres: arte ASCII

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Este exemplo de Arte ASCII mostra vrios recursos para trabalhar com a classe String no ActionScript 3.0, incluindo o seguinte:

O mtodo split() da classe String usado para extrair valores de uma string delimitada por caracteres
(informaes de imagem em um arquivo de texto delimitado por tabulao).

Vrias tcnicas de manipulao de string, incluindo split(), concatenao e extrao de uma parte da string
usando substring() e substr(), so usadas para colocar a primeira letra de cada palavra em maiscula nos ttulos de imagem.

O mtodo getCharAt() usado para obter um nico caractere de uma string (para determinar o caractere ASCII
correspondente a um valor de bitmap em escala de cinza).

A concatenao de string usada para criar a representao de arte ASCII de uma imagem com um caractere de
cada vez.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sequncias de caracteres

20

O termo arte ASCII faz referncia a representaes de texto de uma imagem, na qual uma grade de caracteres de fonte monoespaada, como caracteres Courier New, plotam a imagem. A imagem a seguir mostra um exemplo de arte ASCII produzida pelo aplicativo:

A verso da arte ASCII do grfico mostrada direita.

Para obter os arquivos de aplicativo deste exemplo, consulte www.adobe.com/go/learn_programmingAS3samples_flash_br. Os arquivos do aplicativo ASCIIArt podem ser encontrados na pasta Amostras/AsciiArt. O aplicativo consiste nos seguintes arquivos:
Arquivo AsciiArtApp.mxml ou AsciiArtApp.fla com/example/programmingas3/asciiArt/AsciiArtBuilder.as A classe que fornece a funcionalidade principal do aplicativo, incluindo a extrao de metadados da imagem de um arquivo de texto, carregamento de imagens e gerenciamento do processo de converso de imagem para texto. A classe que fornece o mtodo parseBitmapData() para converso de dados de imagem em uma verso String. Uma classe que representa uma imagem de bitmap carregada. Uma classe que representa metadados para uma imagem arte ASCII (como ttulo, URL do arquivo de imagem, etc.) Uma pasta que contm imagens usadas pelo aplicativo. O arquivo de texto delimitado por tabulao que contm informaes sobre as imagens a serem carregadas pelo aplicativo. Descrio O arquivo principal do aplicativo no Flash (FLA) ou no Flex (MXML)

com/example/programmingas3/asciiArt/BitmapToAsciiConverter.as

com/example/programmingas3/asciiArt/Image.as

com/example/programmingas3/asciiArt/ImageInfo.as

imagem/ txt/ImageData.txt

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sequncias de caracteres

21

Extrao de valores delimitados por tabulao

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Este exemplo usa a prtica comum de armazenar dados do aplicativo separados do prprio aplicativo. Dessa maneira, se os dados forem alterados (por exemplo, se outra imagem for adicionada ou um ttulo da imagem for alterado) no haver necessidade de recriar o arquivo SWF. Nesse caso, os metadados da imagem, incluindo o ttulo da imagem, a URL do arquivo real da imagem e alguns valores que so usados para manipular a imagem so armazenados em um arquivo de texto (o arquivo txt\ImageData.ttx do projeto). O contedo do arquivo de texto o seguinte:
FILENAMETITLEWHITE_THRESHHOLDBLACK_THRESHHOLD FruitBasket.jpgPear, apple, orange, and bananad810 Banana.jpgA picture of a bananaC820 Orange.jpgorangeFF20 Apple.jpgpicture of an apple6E10

O arquivo usa um formato delimitado por tabulao especfico. A primeira linha uma linha de ttulo. As linhas restantes contm os seguintes dados para cada bitmap a ser carregado:

O nome do arquivo do bitmap. O nome de exibio do bitmap. Os valores de limite de branco e de limite de preto dos bitmaps. Esses so valores hexadecimais acima e abaixo dos
quais um pixel deve ser considerado completamente branco ou completamente preto. Assim que o aplicativo iniciado, a classe AsciiArtBuilder carrega e analisa o contedo do arquivo de texto para criar a pilha de imagens que ir exibir usando o seguinte cdigo do mtodo parseImageInfo() da classe AsciiArtBuilder:
var lines:Array = _imageInfoLoader.data.split("\n"); var numLines:uint = lines.length; for (var i:uint = 1; i < numLines; i++) { var imageInfoRaw:String = lines[i]; ... if (imageInfoRaw.length > 0) { // Create a new image info record and add it to the array of image info. var imageInfo:ImageInfo = new ImageInfo(); // Split the current line into values (separated by tab (\t) // characters) and extract the individual properties: var imageProperties:Array = imageInfoRaw.split("\t"); imageInfo.fileName = imageProperties[0]; imageInfo.title = normalizeTitle(imageProperties[1]); imageInfo.whiteThreshold = parseInt(imageProperties[2], 16); imageInfo.blackThreshold = parseInt(imageProperties[3], 16); result.push(imageInfo); } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sequncias de caracteres

22

Todo o contedo do arquivo de texto contido em uma nica ocorrncia de String, a propriedade _imageInfoLoader.data. Usando o mtodo split() com o caractere de nova linha ("\n") como um parmetro, a ocorrncia de String dividida em uma matriz (linhas) cujos elementos so as linhas individuais do arquivo de texto. Em seguida, o cdigo usa um loop para trabalhar com cada uma das linhas (exceto a primeira, porque ela contm apenas cabealhos em vez do contedo real). Dentro do loop, o mtodo split() usado uma vez novamente para dividir o contedo da nica linha em um conjunto de valores (o objeto Array denominado imageProperties). O parmetro usado com o mtodo split() nesse caso o caractere de tabulao ("\t"), porque os valores de cada linha esto delineados por caracteres de tabulao.

Uso de mtodo String para normalizar ttulos de imagens

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Uma da decises de design desse aplicativo que todos os ttulos de imagens so exibidos usando um formato padro, com a primeira letra de cada palavra colocada em maiscula (exceto por algumas palavras que normalmente no so colocadas em maisculas em ttulos em ingls). Em vez de assumir que o arquivo de texto contm ttulos formatados de maneira apropriada, o aplicativo formata os ttulos enquanto eles esto sendo extrados do arquivo de texto. Na listagem de cdigo anterior, como parte da extrao de valores individuais de metadados da imagem, a seguinte linha de cdigo usada:
imageInfo.title = normalizeTitle(imageProperties[1]);

Nesse cdigo, o ttulo da imagem do arquivo de texto passado pelo mtodo normalizeTitle() antes de ser armazenado no objeto ImageInfo:
private { var var for { } return words.join(" "); } function normalizeTitle(title:String):String words:Array = title.split(" "); len:uint = words.length; (var i:uint; i < len; i++) words[i] = capitalizeFirstLetter(words[i]);

Esse mtodo usa o mtodo split() para dividir o ttulo em palavras individuais (separadas pelo caractere espao), passa cada palavra pelo mtodo capitalizeFirstLetter() e, em seguida, usa o mtodo join() da classe Array para combinar as palavras em uma nica string novamente. Como o nome sugere, o mtodo capitalizeFirstLetter() realmente faz o trabalho de colocar a primeira letra de cada palavra em maiscula:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sequncias de caracteres

23

/** * Capitalizes the first letter of a single word, unless it's one of * a set of words that are normally not capitalized in English. */ private function capitalizeFirstLetter(word:String):String { switch (word) { case "and": case "the": case "in": case "an": case "or": case "at": case "of": case "a": // Don't do anything to these words. break; default: // For any other word, capitalize the first character. var firstLetter:String = word.substr(0, 1); firstLetter = firstLetter.toUpperCase(); var otherLetters:String = word.substring(1); word = firstLetter + otherLetters; } return word; }

Em ingls, o caractere inicial de cada palavra em um ttulo no ser colocado em maiscula se a palavra for uma das seguintes: and, the, in, an, or, at, of ou a (essa uma verso simplificada das regras). Para executar essa lgica, o cdigo primeiro usa uma declarao switch para verificar se a palavra uma das palavras que no devem ser colocadas em letra maiscula. Nesse caso, o cdigo simplesmente ignora a declarao switch. Por outro lado, se a palavra precisar ser colocada em maiscula, isso ser feito em vrias etapas, da seguinte maneira:
1 A primeira letra da palavra extrada usando substr(0, 1) que extrai uma substring a partir do caractere no

ndice 0 (a primeira letra da string, conforme indicado pelo primeiro parmetro 0). A substring ter um caractere de comprimento (indicado pelo segundo parmetro 1).
2 Esse caractere colocado em maiscula usando o mtodo toUpperCase(). 3 Os caracteres restantes da palavra original so extrados usando substring(1) que extrai uma substring no ndice

1 (a segunda letra) at o final da string (indicado pela omisso do segundo parmetro do mtodo substring()).
4 A palavra final criada combinando a primeira letra recm colocada em maiscula com as letras restantes usando

concatenao de strings: firstLetter + otherLetters.

Gerao do texto de arte ASCII

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe BitmapToAsciiConverter fornece a funcionalidade de converter uma imagem de bitmap em sua representao de texto ASCII. Esse processo executado pelo mtodo parseBitmapData() que parcialmente mostrado aqui:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sequncias de caracteres

24

var result:String = ""; // Loop through the rows of pixels top to bottom: for (var y:uint = 0; y < _data.height; y += verticalResolution) { // Within each row, loop through pixels left to right: for (var x:uint = 0; x < _data.width; x += horizontalResolution) { ... // Convert the gray value in the 0-255 range to a value // in the 0-64 range (since that's the number of "shades of // gray" in the set of available characters): index = Math.floor(grayVal / 4); result += palette.charAt(index); } result += "\n"; } return result;

Esse cdigo primeiro define uma ocorrncia de String denominada result que ser usada para criar a verso de arte ASCII da imagem de bitmap. Em seguida, ela executa loop pelos pixels individuais da imagem do bitmap de origem. Usando vrias tcnicas de manipulao de cores (omitidas aqui para resumir), ela converte os valores das cores vermelho, verde e azul de um pixel individual em um valor de escala de cinza nico (um nmero de 0 a 255). Em seguida, o cdigo divide esse valor por 4 (conforme mostrado) para convert-lo em um valor na escala de 0 a 63 que armazenado na varivel index. (A escala de 0 a 63 usada porque a paleta de caracteres ASCII disponveis usado por esse aplicativo contm 64 valores.) A paleta de caracteres definida como uma ocorrncia de String na classe BitmapToAsciiConverter:
// The characters are in order from darkest to lightest, so that their // position (index) in the string corresponds to a relative color value // (0 = black). private static const palette:String = "@#$%&8BMW*mwqpdbkhaoQ0OZXYUJCLtfjzxnuvcr[]{}1()|/?Il!i><+_~-;,. ";

Como a varivel index define qual caractere ASCII na paleta corresponde ao pixel atual na imagem de bitmap, esse caractere recuperado da String palette usando o mtodo charAt(). Em seguida, ele anexado ocorrncia da String result usando o operador de atribuio de concatenao (+=). Alm disso, no final de cada linha de pixels, um caractere de nova linha concatenado ao final da String result, forando uma quebra de linha para criar uma nova linha de pixels de caracteres.

ltima atualizao em 29/3/2011

25

Captulo 3: Trabalho com matrizes

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior As matrizes permitem que voc armazene vrios valores em uma nica estrutura de dados. possvel usar matrizes indexadas simples que armazenam valores usando ndices de nmeros ordinais inteiros e fixos ou matrizes associativas complexas que armazenam valores usando chaves arbitrrias. As matrizes tambm podem ser multidimensionais, contendo elementos que j so matrizes propriamente ditas. Finalmente, voc pode usar um Vetor para uma matriz cujos elementos so ocorrncias do mesmo tipo de dados.

Mais tpicos da Ajuda

Array Vetor

Noes bsicas sobre matrizes

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Em programao comum o trabalho com uma srie de itens, e no com um nico objeto. Por exemplo, talvez voc queira ter uma lista de msicas pronta para ser reproduzida em um aplicativo de player de msica. Voc certamente no optaria por criar uma varivel especfica para cada msica da lista. Seria melhor juntar todos os objetos Song em um pacote e trabalhar com eles como se fossem um grupo. Uma matriz um elemento de programao que funciona como continer para um conjunto de itens, como uma lista de msicas. De modo geral, todos os itens da matriz so ocorrncias da mesma classe, mas isso no uma exigncia no ActionScript. Os itens individuais de uma matriz so conhecidos como elementos da matriz. A matriz pode ser considerada como um arquivador de variveis. As variveis podem ser adicionadas como elementos na matriz, como quando voc coloca uma pasta em seu arquivador. Voc pode trabalhar com a matriz como uma nica varivel, como carregar todo o seu arquivo para um outro local. Voc pode trabalhar com as variveis como um grupo, como analisar as pastas uma a uma para buscar informaes. Voc tambm pode acess-las individualmente, como se estivesse abrindo o arquivo e selecionando uma nica pasta. Por exemplo, imagine que est criando um aplicativo de player de msica no qual o usurio pode selecionar vrias msicas e adicion-las a uma lista de reproduo. No cdigo do ActionScript, h um mtodo chamado addSongsToPlaylist(), que aceita uma nica matriz como parmetro. Independentemente da quantidade de msicas que forem adicionadas lista (poucas, muitas ou apenas uma), voc pode chamar o mtodo addSongsToPlaylist() apenas uma vez, transmitindo a matriz que contm os objetos Song. Dentro do mtodo addSongsToPlaylist(), voc pode usar um loop para navegar entre os elementos da matriz (as msicas) uma a uma e adicion-las lista de reproduo. A matriz indexada o tipo de matriz mais comum do ActionScript. Em uma matriz indexada, cada item armazenado em um slot numerado (conhecido como ndice). Os itens so acessados por meio de nmeros, como em endereos. As matrizes indexadas atendem a maior parte das exigncias de programao. A classe Array uma das classes mais comuns utilizada para representar uma matriz indexada.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com matrizes

26

Em geral, uma matriz indexada usada para armazenar vrios itens do mesmo tipo (objetos que so ocorrncias da mesma classe). A classe Array no tem meios de restringir o tipo de itens que ela contm. A classe Vector o tipo de matriz indexada no qual todos os itens de uma nica matriz so do mesmo tipo. O uso da ocorrncia Vector em vez de Array tambm pode proporcionar melhorias no desempenho, alm de outras vantagens. A classe Vector est disponvel a partir do Flash Player 10 e do Adobe AIR 1.5. A matriz multidimensional representa um caso especial de utilizao de matrizes indexadas. Uma matriz multidimensional uma matriz indexada cujos elementos so matrizes indexadas que, por sua vez, contm outros elementos. A matriz associativa um outro tipo de matriz, que usa uma string key em vez do ndice numrico para identificar elementos individuais. Por fim, o ActionScript 3.0 tambm possui a classe Dictionary, que representa um dicionrio. Um dicionrio uma matriz que permite o uso de qualquer tipo de objeto como uma chave de distino entre elementos. Conceitos e termos importantes A lista a seguir de referncia contm termos importantes que voc vai encontrar ao programar as rotinas de tratamento de matrizes e vetores:
Matriz Um objeto que serve como continer para agrupar vrios objetos. Operador de acesso ([]) matriz Um par de colchetes que circundam um ndice ou uma chave e identifica

exclusivamente um elemento de matriz. Essa sintaxe usada aps um nome de varivel de matriz para especificar um nico elemento da matriz, em vez de especific-la inteira.
Matriz associativa Uma matriz que usa chaves de string para identificar elementos individuais. Tipo base O tipo de dados dos objetos que uma ocorrncia de Vector pode armazenar. Dictionary Matriz cujos itens consistem em pares de objetos, conhecidos como chaves e valores. A chave usada no lugar de um ndice numrico para identificar um nico elemento. Elemento Um item nico de uma matriz. ndice O "endereo" numrico usado para identificar um nico elemento em uma matriz indexada. Matriz indexada O tipo padro da matriz que armazena cada elemento em uma posio numerada e usa o nmero

(ndice) para identificar elementos individuais.

Tecla A string ou o objeto usado para identificar um nico elemento em uma matriz associativa ou em um dicionrio. Matriz multidimensional Matriz que contm itens que so matrizes, em vez de valores nicos. T A conveno padro usada nesta documentao para representar o tipo base de uma ocorrncia de Vector, independentemente do tipo base. A conveno T usada para representar um nome de classe, conforme exibido na descrio do parmetro Type. (T corresponde a tipo, como em tipo de dados).. Parmetro de tipo A sintaxe usada com o nome da classe Vector para especificar o tipo base do vetor (o tipo de dados

dos objetos que ele armazena). A sintaxe consiste em um ponto (.), seguido do nome do tipo de dados entre colchetes angulares (<>). Resumindo, teremos algo como: Vector.<T>. Nessa documentao, a classe especificada no parmetro type representada genericamente como T.
Vetor um tipo de matriz cujos elementos so todos ocorrncias do mesmo tipo de dados.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com matrizes

27

Matrizes indexadas
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior As matrizes indexadas armazenam uma srie de um ou mais valores organizados de tal maneira que cada valor pode ser acessado com um valor inteiro sem sinal. O primeiro ndice sempre o nmero 0 e o ndice aumenta em incrementos de 1 para cada elemento subseqente adicionado matriz. No ActionScript 3.0, duas classes so usadas como matrizes indexadas: classes Array e Vector. As matrizes indexadas usam um inteiro de 32 bits sem sinal como nmero do ndice. O tamanho mximo de uma matriz indexada 232 - 1 ou 4.294.967.295. Uma tentativa de criar uma matriz maior que o tamanho mximo resulta em um erro de tempo de execuo. Para acessar um elemento individual de uma matriz indexada, use o operador de acesso matriz ([]) para especificar a posio de ndice do elemento que deseja acessar. Por exemplo, o cdigo a seguir representa o primeiro elemento (o elemento no ndice 0) em uma matriz indexada chamada songTitles:
songTitles[0]

A combinao do nome da varivel de matriz seguido pelo ndice entre colchetes funciona como um identificador nico (em outras palavras, ele pode ser usado da mesma forma que um nome de varivel). Voc pode atribuir um valor para um elemento de matriz indexada usando o nome e o ndice esquerda de uma instruo de atribuio:
songTitles[1] = "Symphony No. 5 in D minor";

Da mesma forma, voc pode recuperar o valor de um elemento de matriz indexada usando o nome e o ndice direita de uma instruo de atribuio:
var nextSong:String = songTitles[2];

Voc tambm pode usar uma varivel entre colchetes em vez de fornecer um valor explcito (a varivel deve conter um valor inteiro no-negativo como uint, um nmero inteiro positivo ou uma ocorrncia de Number de um nmero inteiro positivo). Geralmente, essa tcnica usada para fazer um loop dos elementos de uma matriz indexada e executar uma operao em alguns ou todos os elementos. A lista de cdigos a seguir demonstra essa tcnica: O cdigo usa um loop para acessar cada valor em um objeto Array denominado oddNumbers. Ele usa a instruo trace() para imprimir cada valor da frmula oddNumber[index] = value:
var oddNumbers:Array = [1, 3, 5, 7, 9, 11]; var len:uint = oddNumbers.length; for (var i:uint = 0; i < len; i++) { trace("oddNumbers[" + i.toString() + "] = " + oddNumbers[i].toString()); }

Classe Array A classe Array o primeiro tipo de matriz indexada. Uma ocorrncia de Array pode armazenar valores de qualquer tipo de dados. O mesmo objeto Array pode armazenar objetos de diferentes tipos de dados. Por exemplo, uma nica ocorrncia de Array pode ter um valor String no ndice 0, uma ocorrncia de Number no ndice 1 e um objeto XML no ndice 2. Classe Vector A classe Vector corresponde a outro tipo de matriz indexada que est disponvel no ActionScript 3.0. Uma ocorrncia de Vector uma matriz tipificada, o que significa que todos os elementos dessa ocorrncia possuem o mesmo tipo de dados.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com matrizes

28

Nota: A classe Vector est disponvel a partir do Flash Player 10 e do Adobe AIR 1.5. Quando voc declara uma varivel Vector ou cria ocorrncia de um objeto Vector, est especificando explicitamente os tipos de dados dos objetos que o vetor pode conter. O tipo de dados especificado conhecido como o tipo base do vetor. Nos tempos de execuo e de compilao (no modo restrito), qualquer cdigo que define o valor de um elemento Vector ou recupera um valor de um vetor verificado. Se o tipo de dados do objeto que est sendo adicionado ou recuperado no corresponder ao tipo base do vetor, ocorrer um erro. Alm da restrio de tipo de dados, a classe Vector tem outras restries que a diferenciam da classe Array:

Um vetor uma matriz densa. Um objeto Array pode ter valores nos ndices 0 e 7, mesmo se no tiver valores nas
posies de 1 a 6. Entretanto, um vetor deve ter um valor (ou null) em cada ndice.

Um vetor pode ter tamanho fixo, opcionalmente. Isso significa que o nmero de elementos contidos no vetor no
pode ser alterado.

Os limites de acesso aos elementos de um vetor so verificados. No possvel ler um valor de um ndice maior que
o elemento final (tamanho - 1). Nunca defina um valor com um ndice que exceda o ndice final atual (em outras palavras, voc s pode definir um valor em um ndice existente ou no ndice [length]). Como resultado das restries, uma instncia Vector tem duas vantagens principais sobre uma instncia de Matriz cujos elementos so instncias de uma nica classe:

Desempenho: a iterao e o acesso ao elemento da matriz so muito mais rpidos ao usar uma ocorrncia de Vector
do que ao usar uma de Array.

Segurana do tipo: o compilador pode identificar erros de tipo de dados no modo restrito. Exemplos de erros desse
tipo incluem a atribuio de valor de um tipo de dados incorreto ao um vetor ou a espera do tipo de dados errado na leitura de um valor de um vetor. Em tempo de execuo, os tipos de dados tambm so verificados durante a adio ou leitura de dados de um objeto Vector. Observe, entretanto, que ao usar o mtodo push() ou unshift() para adicionar valores a um vetor, os tipos de dados dos argumentos no so verificados durante a compilao. Quando usar esses mtodos, os valores sero verificados no tempo de execuo.

Confiabilidade: a verificao de intervalo de tempo de execuo (ou a verificao de comprimento fixo) aumenta a
confiabilidade significativamente nas Matrizes. Com exceo das restries adicionais e vantagens, a classe Vector muito parecida com a classe Array. As propriedades e os mtodos de um objeto Vector so semelhantes em grande parte, idnticos aos de um Array. Na maioria dos casos, quando voc usa uma Matriz em que todos os elementos tm o mesmo tipo de dados, uma instncia de Vector tem preferncia.

Criao de matrizes
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior possvel usar diversas tcnicas para criar uma ocorrncia de Array ou Vector. No entanto, as tcnicas para criao de cada tipo de matriz apresentam diferenas entre si.

Criao de uma ocorrncia de Array

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior possvel criar um objeto Array ao chamar o construtor Array() ou ao usar a sintaxe literal de matriz. A funo de construtor Array() pode ser usada de trs modos: Primeiro, se voc chama o construtor sem nenhum argumento, obtm uma matriz vazia. Voc pode usar a propriedade length da classe Array para verificar se a matriz no tem nenhum elemento. Por exemplo, o cdigo a seguir chama o construtor Array() sem nenhum argumento:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com matrizes

29

var names:Array = new Array(); trace(names.length); // output: 0

Segundo, se voc usar um nmero como o nico parmetro do construtor Array(), uma matriz com esse comprimento ser criada, com o valor de cada elemento definido como undefined. O argumento deve ser um nmero inteiro sem sinal entre os valores 0 e 4.294.967.295. Por exemplo, o cdigo a seguir chama o construtor Array() com um nico argumento numrico:
var names:Array = new Array(3); trace(names.length); // output: 3 trace(names[0]); // output: undefined trace(names[1]); // output: undefined trace(names[2]); // output: undefined

Terceiro, se voc chama o construtor e transmite uma lista de elementos como parmetros, uma matriz com elementos correspondem a cada parmetro criada. O cdigo a seguir transmite trs argumentos para o construtor Array():
var names:Array = new Array("John", "Jane", "David"); trace(names.length); // output: 3 trace(names[0]); // output: John trace(names[1]); // output: Jane trace(names[2]); // output: David

Voc tambm pode criar matrizes com literais de matriz. Um literal de matriz pode ser atribudo diretamente a uma varivel de matriz, como mostra o exemplo a seguir:
var names:Array = ["John", "Jane", "David"];

Criao de uma ocorrncia de Vector

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Voc pode criar uma ocorrncia de Vector ao chamar o construtor Vector.<T>(). Voc tambm pode criar um vetor ao chamar a funo global Vector.<T>(). Essa funo converte um objeto especificado em uma ocorrncia de Vector. No Flash Professional CS5 e posterior, Flash Builder 4 e posterior, e Flex 4 e posterior, voc tambm pode criar uma instncia de vetor usando a sintaxe literal Vector. Quando voc declara uma varivel de vetor (ou do mesmo modo, um parmetro de mtodo de vetor ou um tipo de retorno de mtodo), est especificando o tipo base da varivel de vetor. O tipo base tambm especificado quando voc cria uma ocorrncia de Vector ao chamar o construtor Vector.<T>(). Em outras palavras, sempre que usar o termo Vector no ActionScript, ele estar acompanhado por um tipo base. O tipo base do vetor especificado por meio de uma sintaxe de parmetro de tipo. O parmetro de tipo segue imediatamente a palavra Vector no cdigo. Esse parmetro consiste em um ponto (.), seguido do nome de classe base entre colchetes angulares (<>), conforme apresentado no exemplo a seguir:
var v:Vector.<String>; v = new Vector.<String>();

Na primeira linha do exemplo, a varivel v est declarada como uma ocorrncia de Vector.<String>. Em outras palavras, ela representa uma matriz indexada que pode conter apenas ocorrncias de String. A segunda linha chama o construtor Vector() para criar uma ocorrncia do mesmo tipo de vetor, ou seja, um vetor cujos elementos so objetos String. Esse construtor atribui o objeto a v.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com matrizes

30

Uso do construtor Vector.<T>() construtor Caso voc use o construtor Vector.<T>() sem quaisquer argumentos, uma ocorrncia de Vector vazia ser criada. Voc pode verificar se um vetor est vazio ao conferir sua propriedade length. Por exemplo, o cdigo a seguir chama o construtor Vector.<T>() sem argumentos:
var names:Vector.<String> = new Vector.<String>(); trace(names.length); // output: 0

Voc pode predefinir a quantidade de elementos que um vetor precisa ter inicialmente, se tiver essa informao antecipadamente. Para criar um vetor com um determinado nmero de elementos, transfira o nmero de elementos como o primeiro parmetro (o parmetro length). Os elementos Vector so preenchidos com ocorrncias do tipo base, j que no podem ficar vazios. Se o tipo base um tipo de referncia que permite valores null, todos os elementos contero null. Caso contrrio, os elementos contero o valor padro para a classe. Por exemplo, uma varivel uint no pode ser null. Conseqentemente, o cdigo a seguir que lista o vetor chamado ages criado com sete elementos contendo o valor 0:
var ages:Vector.<uint> = new Vector.<uint>(7); trace(ages); // output: 0,0,0,0,0,0,0

Por fim, ao usar o construtor Vector.<T>(), voc tambm poder criar um vetor de tamanho fixo ao passar true para o segundo parmetro (o parmetro fixed). Nesse caso o vetor criado com o nmero de elementos especificado e esse nmero no pode ser alterado. Note, no entanto, que ainda ser possvel mudar os valores dos elementos de um vetor de tamanho fixo. Como utilizar o construtor de sintaxe literal Vector No Flash Professional CS5 e posterior, Flash Builder 4 e posterior e no Flex 4 e posterior, voc pode transmitir uma lista de valores ao construtor Vector.<T>() para especificar os valores iniciais do vetor:
// var v:Vector.<T> = new <T>[E0, ..., En-1 ,]; // For example: var v:Vector.<int> = new <int>[0,1,2,];

As seguintes informaes se aplicam a esta sintaxe:

A vrgula posterior opcional. Os itens vazios na matriz no so suportados; uma instruo como var
emite um erro de compilador.
v:Vector.<int> = new <int>[0,,2,]

Voc no pode especificar um comprimento padro da instncia Vector. Em vez disso, o comprimento o mesmo
que o nmero de elementos na lista de inicializao.

Voc no pode especificar se a instncia Vector tem um comprimento fixo. Em vez disso, use a propriedade fixed. A perda de dados ou os erros podem ocorrer se os itens passaram como os valores que no correspondem ao tipo
especificado. Por exemplo:
var v:Vector.<int> = new <int>[4.2]; // compiler error when running in strict mode trace(v[0]); //returns 4 when not running in strict mode

Uso do construtor Vector.<T>() funo global Alm do construtor Vector.<T>() e construtores da sintaxe literal Vector, voc tambm pode usar o Vector.<T>() para criar um objeto Vector. A funo global Vector.<T>() uma funo de converso. Quando a funo global Vector.<T>() chamada, voc est especificando o tipo base do vetor que o mtodo retorna. Com isso, uma nica matriz indexada (ocorrncia de Array ou Vector) passada como um argumento. Em seguida, o mtodo retorna um vetor com o tipo base especificado, contendo os valores do argumento da matriz de origem. A listagem de cdigo a seguir exibe a sintaxe necessria para chamar a funo global Vector.<T>():

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com matrizes

31

var friends:Vector.<String> = Vector.<String>(["Bob", "Larry", "Sarah"]);

A funo global Vector.<T>() executa a converso do tipo de dados em dois nveis. Primeiro, uma ocorrncia de Vector retornada quando uma ocorrncia de Array passada para a funo. Segundo, quando a matriz de origem uma ocorrncia de Array ou Vector, a funo tenta converter os elementos da matriz de origem em valores do tipo base. A converso usa regras de converso de tipo de dados padro do ActionScript. Por exemplo, a listagem de cdigo a seguir converte os valores de string na matriz de origem para nmeros inteiros no vetor resultante. A parte decimal do primeiro valor ("1.5") est truncada e o terceiro valor no-numrico ("Waffles") convertido para 0 no resultado:
var numbers:Vector.<int> = Vector.<int>(["1.5", "17", "Waffles"]); trace(numbers); // output: 1,17,0

Se no for possvel converter nenhum dos elementos de origem, ocorrer um erro. Quando o cdigo chama a funo global Vector.<T>(), se um elemento da matriz de origem uma ocorrncia de uma subclasse do tipo base especificado, o elemento adicionado ao vetor resultante (no h ocorrncia de erros). O uso da funo global Vector.<T>() o nico modo de converter um vetor com tipo base T em um vetor com tipo base que seja uma superclasse de T.

Insero de elementos de matriz

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A maneira mais simples de adicionar um elemento a uma matriz indexada usar o operador de acesso matriz ([]). Para definir um valor de um elemento de matriz indexada, use o nome de objeto Array ou Vector e o nmero de ndice esquerda de uma instruo de atribuio:
songTitles[5] = "Happy Birthday";

Se a matriz ou o vetor ainda no tiver um elemento no ndice, esse ndice ser criado e o valor ser armazenado nele. Se houver um valor no ndice, o novo valor substituir o existente. Um objeto Array permite a criao de um elemento em qualquer ndice. Entretanto, com um objeto Vector voc somente poder atribuir um valor a um ndice existente ou ao prximo ndice disponvel. O prximo ndice disponvel corresponde propriedade length do objeto Vector. A maneira mais segura de adicionar um novo elemento a um objeto Vector usar um cdigo como na listagem a seguir:
myVector[myVector.length] = valueToAdd;

Trs mtodos da classe Array e Vector - push(), unshift() e splice() - permitem inserir elementos em uma matriz indexada. O mtodo push() anexa um ou mais elementos ao final de uma matriz. Em outras palavras, o ltimo elemento inserido na matriz com o mtodo push() ter o maior nmero de ndice. O mtodo unshift() insere um ou mais elementos no incio de uma matriz, sempre no nmero de ndice 0. O mtodo splice() insere qualquer nmero de itens em um ndice especificado na matriz. O exemplo a seguir demonstra os trs mtodos. Uma matriz chamada planetas criada para armazenar os nomes dos planetas de acordo com a proximidade ao Sol. Primeiro, o mtodo push() chamado para adicionar o item inicial, Marte. Segundo, o mtodo unshift() chamado para inserir o item que pertence ao incio da matriz, Mercrio. Finalmente, o mtodo splice() chamado para inserir os itens Vnus e Terra depois de Mercrio, mas antes de Marte. O primeiro argumento enviado para splice(), o inteiro 1, direciona a insero para comear no ndice 1. O segundo argumento enviado para splice(), o inteiro 0, indica que nenhum item deve ser excludo. Finalmente, o terceiro e quarto argumentos enviados para splice(), Vnus e Terra, so os itens que devem ser inseridos.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com matrizes

32

var planets:Array = new Array(); planets.push("Mars"); // array contents: Mars planets.unshift("Mercury"); // array contents: Mercury,Mars planets.splice(1, 0, "Venus", "Earth"); trace(planets); // array contents: Mercury,Venus,Earth,Mars

Os mtodos push() e unshift() retornam um inteiro sem sinal que representa o comprimento da matriz modificada. O mtodo splice() retorna uma matriz vazia quando usado para inserir elementos, o que pode parecer estranho, mas faz mais sentido de acordo com a versatilidade do mtodo splice(). Voc pode usar o mtodo splice() no s para inserir elementos em uma matriz, mas tambm para remover elementos de uma matriz. Quando usado para remover elementos, o mtodo splice() retorna uma matriz que contm os elementos removidos. Nota: Se a propriedade fixed do objeto Vector for true, o nmero total de elementos do vetor no poder ser alterado. Se voc tentar adicionar um novo elemento a um vetor de tamanho fixo por meio de tcnicas aqui descritas, ocorrer um erro.

Recuperao de valores e remoo de elementos de matriz

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A maneira mais simples de recuperar o valor de um elemento de uma matriz indexada usar o operador de acesso matriz ([]). Para recuperar o valor de um elemento de matriz indexada, use o nome de objeto Array ou Vector e o nmero de ndice direita de uma instruo de atribuio:
var myFavoriteSong:String = songTitles[3];

Voc pode tentar recuperar um valor de uma matriz ou vetor usando um ndice onde no houver elementos. Nesse caso, um objeto Array retorna um valor indefinido e um vetor emite uma exceo RangeError. Trs mtodos das classes Array e Vector - pop(), shift() e splice() - permitem a remoo de elementos. O mtodo pop() remove um elemento do final da matriz. Em outras palavras, ele remove o elemento com o nmero de ndice mais alto. O mtodo shift() remove um elemento do incio da matriz, ou seja, sempre remove o elemento com o nmero de ndice 0. O mtodo splice(), que tambm pode ser usado para inserir elementos, remove um nmero arbitrrio de elementos comeando no nmero de ndice especificado pelo primeiro argumento enviado ao mtodo. O exemplo a seguir usa os trs mtodos para remover elementos de uma ocorrncia de Array. Uma matriz chamada
oceanos criada para armazenar os nomes dos grandes corpos de gua. Alguns nomes da matriz referem-se a lagos,

no a oceanos, e precisam ser removidos. Primeiro, o mtodo splice() usado para remover os itens Aral e Superior, e inserir os itens Atlntico e ndico. O primeiro argumento enviado para splice(), o inteiro 2, indica que a operao deve comear com o terceiro item da lista, que est no ndice 2. O segundo argumento, 2, indica que dois itens devem ser removidos. Os argumentos restantes, Atlntico e ndico, so os valores que devem ser inseridos no ndice 2. Segundo, o mtodo pop() usado para remover o ltimo elemento da matriz, Huron. Finalmente, o mtodo shift() usado para remover o primeiro item da matriz, Vitria.
var oceans:Array = ["Victoria", "Pacific", "Aral", "Superior", "Indian", "Huron"]; oceans.splice(2, 2, "Arctic", "Atlantic"); // replaces Aral and Superior oceans.pop(); // removes Huron oceans.shift(); // removes Victoria trace(oceans);// output: Pacific,Arctic,Atlantic,Indian

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com matrizes

33

Os mtodos pop() e shift() retornam o item que foi removido. Para uma ocorrncia de Array, o tipo de dados do valor de retorno Object porque as matrizes podem armazenar valores de qualquer tipo de dados. Para uma ocorrncia de Vector, o tipo de dados do valor de retorno o tipo base do vetor. O mtodo splice() retorna uma matriz ou um vetor que contm os valores removidos. Voc pode alterar o exemplo de matriz oceanos para que a chamada do mtodo splice() atribua a matriz retornada a uma nova varivel Array, como mostra o exemplo a seguir:
var lakes:Array = oceans.splice(2, 2, "Arctic", "Atlantic"); trace(lakes); // output: Aral,Superior

Talvez aparea um cdigo que usa o operador delete em um elemento de objeto Array. O operador delete define o valor de um elemento Array como undefined, mas no remove o elemento da matriz. Por exemplo, o cdigo a seguir usa o operador delete no terceiro elemento da matriz oceanos, mas o comprimento da matriz continua sendo 5:
var oceans:Array = ["Arctic", "Pacific", "Victoria", "Indian", "Atlantic"]; delete oceans[2]; trace(oceans);// output: Arctic,Pacific,,Indian,Atlantic trace(oceans[2]); // output: undefined trace(oceans.length); // output: 5

Voc pode truncar uma matriz ou um vetor usando uma propriedade de matriz length. Se a propriedade length de uma matriz indexada for definida como um comprimento menor do que o atual, a matriz ser truncada, o que remove os elementos armazenados nos nmeros de ndice maiores do que o novo valor de length menos 1. Por exemplo, se a matriz oceanos fosse classificada de modo que todas as entradas vlidas estivessem no incio da matriz, a propriedade length poderia ser usada para remover as entradas no final da matriz, como mostra o cdigo a seguir:
var oceans:Array = ["Arctic", "Pacific", "Victoria", "Aral", "Superior"]; oceans.length = 2; trace(oceans); // output: Arctic,Pacific

Nota: Se a propriedade fixed do objeto Vector for true, o nmero total de elementos do vetor no poder ser alterado. Se voc tentar remover um elemento ou truncar um vetor de tamanho fixo usando as tcnicas aqui descritas, ocorrer um erro.

Classificao de uma matriz

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Existem trs mtodos - reverse(), sort() e sortOn() - que permitem alterar a ordem de uma matriz indexada, classificando-a ou invertendo-a. Todos esses mtodos modificam a matriz existente. A tabela a seguir resume esses mtodos e seus respectivos comportamentos para objetos Array e Vector:
Mtodo
reverse()

Comportamento de Array Altera a ordem dos elementos de modo de que o ltimo elemento se transforma no primeiro, o penltimo no segundo e assim por diante. Permite a classificao dos elementos da matriz de diversos modos predefinidos, como ordem alfabtica ou numrica. Tambm possvel especificar um algoritmo de classificao personalizada.

Comportamento de Vector Idntico ao comportamento de Array

sort()

Classifica os elementos de acordo com o algoritmo de classificao personalizada especificado

sortOn()

Permite a classificao de objetos que possuem uma ou mais Indisponvel na classe Vector. propriedades em comum, especificando a(s) propriedade(s) que podem ser usadas como chaves de classificao.

O mtodo reverse() O mtodo reverse() no assume nenhum parmetro e no retorna um valor, mas permite alternar a ordem da matriz do estado atual para a ordem inversa. O exemplo a seguir inverte a ordem dos oceanos listados na matriz oceanos:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com matrizes

34

var oceans:Array = ["Arctic", "Atlantic", "Indian", "Pacific"]; oceans.reverse(); trace(oceans); // output: Pacific,Indian,Atlantic,Arctic

Classificao bsica com o mtodo sort() (somente para a classe Array) Para uma ocorrncia de Array, o mtodo sort() reorganiza os elementos de uma matriz usando a ordem de classificao padro. A ordem de classificao padro deve ter as seguintes caractersticas:

A classificao diferencia maisculas de minsculas, isto , os caracteres maisculos precedem os minsculos. Por
exemplo, a letra D precede a letra b.

A classificao crescente, ou seja, os cdigos de caracteres menores (como A) precedem os maiores (como B). A classificao coloca valores idnticos perto um do outro, mas no em uma ordem especfica. A classificao baseia-se em strings, ou seja, os elementos so convertidos em strings antes de serem comparados
(por exemplo, 10 vem antes de 3 porque a string "1" tem um cdigo de caractere menor do que o da string "3"). Talvez voc precise classificar uma matriz sem diferenciar maisculas de minsculas, em ordem decrescente ou sua matriz pode conter elementos que devem ser classificados numericamente em vez de em ordem alfabtica. O mtodo sort() de classe Array tem um parmetro options que permite a alterao de cada caracterstica da ordem de classificao padro. As opes so definidas por um conjunto de constantes estticas da classe Array, como mostra a lista a seguir:

Array.CASEINSENSITIVE: essa opo no diferencia maisculas de minsculas durante a classificao. Por

exemplo, a letra minscula b precede a letra maiscula D.

Array.DESCENDING: essa opo inverte a classificao crescente padro. Por exemplo, a letra B precede a letra A. Array.UNIQUESORT: essa opo interrompe a classificao quando dois valores idnticos so encontrados. Array.NUMERIC: essa opo faz a classificao numrica, de modo que 3 vem antes de 10.

O exemplo a seguir destaca algumas dessas opes. Uma matriz chamada poetas criada e classificada com diversas opes diferentes.
var poets:Array = ["Blake", "cummings", "Angelou", "Dante"]; poets.sort(); // default sort trace(poets); // output: Angelou,Blake,Dante,cummings poets.sort(Array.CASEINSENSITIVE); trace(poets); // output: Angelou,Blake,cummings,Dante poets.sort(Array.DESCENDING); trace(poets); // output: cummings,Dante,Blake,Angelou poets.sort(Array.DESCENDING | Array.CASEINSENSITIVE); // use two options trace(poets); // output: Dante,cummings,Blake,Angelou

Classificao padro com o mtodo sort() (somente para as classes Array e Vector) Alm da classificao bsica disponvel para um objeto Array, tambm possvel definir uma regra de classificao personalizada. Essa tcnica a nica forma do mtodo sort() disponvel para a classe Vector. Para definir uma classificao padro, escreva uma funo de classificao personalizada e passe-a como um argumento para o mtodo sort().

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com matrizes

35

Por exemplo, se houver uma lista de nomes e cada elemento da lista tiver o nome completo da pessoa, mas voc quiser classificar a lista pelo sobrenome, use uma funo de classificao personalizada para analisar cada elemento e use o sobrenome na funo de classificao. O cdigo a seguir mostra como isso pode ser feito com uma funo personalizada que usada como um parmetro para o mtodo Array.sort():
var names:Array = new Array("John Q. Smith", "Jane Doe", "Mike Jones"); function orderLastName(a, b):int { var lastName:RegExp = /\b\S+$/; var name1 = a.match(lastName); var name2 = b.match(lastName); if (name1 < name2) { return -1; } else if (name1 > name2) { return 1; } else { return 0; } } trace(names); // output: John Q. Smith,Jane Doe,Mike Jones names.sort(orderLastName); trace(names); // output: Jane Doe,Mike Jones,John Q. Smith

A funo de classificao personalizada orderLastName() usa uma expresso regular para extrair o sobrenome de cada elemento a ser usado para a operao de comparao. O identificador da funo orderLastName usado como o nico parmetro ao chamar o mtodo sort() na matriz nomes. A funo de classificao aceita dois parmetros, a e b, porque atua em dois elementos de matriz ao mesmo tempo. O valor de retorno da funo de classificao indica como os elementos devem ser classificados:

O valor de retorno -1 indica que o primeiro parmetro, a, precede o segundo, b. O valor de retorno 1 indica que o segundo parmetro, b, precede o primeiro, a. O valor de retorno 0 indica que os elementos tm a mesma precedncia de classificao.
O mtodo sortOn() (somente para a classe Array) O mtodo sortOn() foi desenvolvido para objetos Array com elementos que contm objetos. Esses objetos devem ter pelo menos uma propriedade comum que pode ser usada como a chave de classificao. O uso do mtodo sortOn() para outros tipos de matriz gera resultados inesperados. Nota: A classe Vector no inclui um mtodo sortOn(). Esse mtodo est disponvel apenas para objetos Array. O exemplo a seguir revisa a matriz poetas para que cada elemento seja um objeto, em vez de uma string. Cada objeto armazena o sobrenome e o ano de nascimento do poeta.
var poets:Array = new Array(); poets.push({name:"Angelou", born:"1928"}); poets.push({name:"Blake", born:"1757"}); poets.push({name:"cummings", born:"1894"}); poets.push({name:"Dante", born:"1265"}); poets.push({name:"Wang", born:"701"});

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com matrizes

36

Voc pode usar o mtodo sortOn() para classificar a matriz pela propriedade born. O mtodo sortOn() define dois parmetros, fieldName e options. O argumento fieldName deve ser especificado como uma string. No exemplo a seguir, sortOn() chamado com dois argumentos, "born" e Array.NUMERIC. O argumento Array.NUMERIC usado para assegurar que a classificao seja feita numericamente, no em ordem alfabtica. Isso til mesmo quando todos os nmeros tm o mesmo nmero de dgitos porque garante que a classificao continuar apresentando o comportamento esperado se um nmero com mais ou menos dgitos for adicionado posteriormente matriz.
poets.sortOn("born", Array.NUMERIC); for (var i:int = 0; i < poets.length; ++i) { trace(poets[i].name, poets[i].born); } /* output: Wang 701 Dante 1265 Blake 1757 cummings 1894 Angelou 1928 */

Classificao sem modificao da matriz original (somente para a classe Array) Geralmente, os mtodos sort() e sortOn() modificam uma matriz. Se desejar classificar uma matriz sem modificar a existente, transmita a constante Array.RETURNINDEXEDARRAY como parte do parmetro options. Essa opo instrui os mtodos a retornar uma nova matriz que reflete a classificao e deixar a matriz original inalterada. A matriz retornada pelos mtodos uma simples matriz de nmeros de ndice que reflete a nova ordem de classificao e no contm nenhum elemento da matriz original. Por exemplo, para classificar a matriz poetas por ano de nascimento sem modific-la, inclua a constante Array.RETURNINDEXEDARRAY como parte do argumento transmitido para o parmetro options. O exemplo a seguir armazena as informaes de ndice retornadas em uma matriz chamada ndices e usa a matriz ndices junto com a matriz poetas inalterada para classificar os poetas por ano de nascimento:
var indices:Array; indices = poets.sortOn("born", Array.NUMERIC | Array.RETURNINDEXEDARRAY); for (var i:int = 0; i < indices.length; ++i) { var index:int = indices[i]; trace(poets[index].name, poets[index].born); } /* output: Wang 701 Dante 1265 Blake 1757 cummings 1894 Angelou 1928 */

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com matrizes

37

Consulta de uma matriz

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Quatro mtodos das classes Array e Vector - concat(), join(), slice() e toString() - consultam a matriz em busca de informaes, mas no a modificam. Os mtodos concat() e slice() retornam novas matrizes, enquanto os mtodos join() e toString() retornam strings. O mtodo concat() pega uma nova matriz ou lista de elementos como argumentos e a combina com a matriz existente para criar uma nova. O mtodo slice() tem dois parmetros, devidamente chamados de startIndex e endIndex, e retorna uma nova matriz que contm uma cpia dos elementos "fatiados" a partir da matriz existente. A fatia comea com o elemento em startIndex e termina com o elemento bem antes de endIndex. A mxima a mesma: O elemento em endIndex no includo no valor de retorno. O exemplo a seguir usa concat() e slice() para criar novas matrizes com elementos de outras matrizes:
var array1:Array = ["alpha", "beta"]; var array2:Array = array1.concat("gamma", "delta"); trace(array2); // output: alpha,beta,gamma,delta var array3:Array = array1.concat(array2); trace(array3); // output: alpha,beta,alpha,beta,gamma,delta var array4:Array = array3.slice(2,5); trace(array4); // output: alpha,beta,gamma

Voc pode usar os mtodos join() e toString() para consultar a matriz e retornar seu contedo como uma string. Se nenhum parmetro for usado para o mtodo join(), os dois mtodos tero o mesmo comportamento: eles retornaro uma string que contm uma lista delimitada por vrgulas de todos os elementos da matriz. O mtodo join(), diferente do mtodo toString(), aceita um parmetro chamado delimiter, que permite escolher o smbolo a ser usado como separador entre cada elemento na string retornada. O exemplo a seguir cria uma matriz chamada rios e chama join() e toString() para retornar os valores na matriz como uma string. O mtodo toString() usado para retornar valores separados por vrgula (riverCSV), enquanto o mtodo join() usado para retornar valores separados pelo caractere +.
var rivers:Array = ["Nile", "Amazon", "Yangtze", "Mississippi"]; var riverCSV:String = rivers.toString(); trace(riverCSV); // output: Nile,Amazon,Yangtze,Mississippi var riverPSV:String = rivers.join("+"); trace(riverPSV); // output: Nile+Amazon+Yangtze+Mississippi

Um problema do mtodo join() que deve ser levado em considerao o fato de as ocorrncias de Array ou Vector aninhadas sempre serem retornadas com valores separados por vrgula, independentemente do separador especificado para os elementos principais da matriz, como mostra o exemplo a seguir:
var nested:Array = ["b","c","d"]; var letters:Array = ["a",nested,"e"]; var joined:String = letters.join("+"); trace(joined); // output: a+b,c,d+e

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com matrizes

38

Matrizes associativas
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Uma matriz associativa, s vezes chamadas de hash ou mapa, usa chaves em vez de ndices numricos para organizar os valores armazenados. Cada chave de uma matriz associativa uma string exclusiva que usada para acessar um valor armazenado. Uma matriz associativa uma ocorrncia da classe Object, o que indica que cada chave corresponde a um nome de propriedade. As matrizes associativas so colees no ordenadas de pares de chave e valor. Seu cdigo no deve esperar que as chaves de uma matriz associativa estejam em uma ordem especfica. O ActionScript 3.0 tambm inclui um tipo avanado de matriz associativa chamado dicionrio. Os dicionrios, que so ocorrncias da classe Dictionary no pacote flash.utils, usa chaves que podem ser de qualquer tipo de dados. Em outras palavras, as chaves de dicionrio no esto limitadas aos valores do tipo String.

Matrizes associativas com chaves de string

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior H duas maneiras de criar matrizes associativas no ActionScript 3.0. A primeira alternativa usar uma ocorrncia de Object. Ao usar essa ocorrncia, ser possvel inicializar a matriz com um literal de objeto. Uma ocorrncia da classe Object, tambm chamada de objeto genrico, tem a mesma funcionalidade de uma matriz associativa. Cada nome de propriedade do objeto genrico serve como a chave que fornece acesso a um valor armazenado. O exemplo a seguir cria uma matriz associativa chamada monitorInfo, usando um literal de objeto para inicializar a matriz com dois pares de chave e valor:
var monitorInfo:Object = {type:"Flat Panel", resolution:"1600 x 1200"}; trace(monitorInfo["type"], monitorInfo["resolution"]); // output: Flat Panel 1600 x 1200

Se no for necessrio inicializar a matriz no tempo da declarao, use o construtor Object para criar a matriz da seguinte maneira:
var monitorInfo:Object = new Object();

Depois que a matriz criada com um literal de objeto ou um construtor da classe Object, voc pode adicionar novos valores matriz usando o operador de acesso matriz ([]) ou o operador de ponto (.). O exemplo a seguir adiciona dois novos valores a monitorArray:
monitorInfo["aspect ratio"] = "16:10"; // bad form, do not use spaces monitorInfo.colors = "16.7 million"; trace(monitorInfo["aspect ratio"], monitorInfo.colors); // output: 16:10 16.7 million

Observe que a chave chamada aspect ratio contm um caractere de espao. Isso possvel com o operador de acesso matriz ([]), mas gera um erro se a tentativa for feita com o operador ponto. No recomendado usar espaos em nomes de chave. A segunda maneira de criar uma matriz associativa usar o construtor Array (ou o construtor de qualquer classe dinmica) e usar o operador de acesso matriz ([]) ou o operador de ponto (.) para adicionar os pares de chave e valor matriz. Se declarar que a matriz associativa do tipo Array, voc no poder usar um literal de objeto para inicializar a matriz. O exemplo a seguir cria uma matriz associativa chamada monitorInfo usando o construtor Array e adiciona uma chave chamada type e uma chave chamada resolution, junto com seus valores:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com matrizes

39

var monitorInfo:Array = new Array(); monitorInfo["type"] = "Flat Panel"; monitorInfo["resolution"] = "1600 x 1200"; trace(monitorInfo["type"], monitorInfo["resolution"]); // output: Flat Panel 1600 x 1200

No h nenhuma vantagem em usar o construtor Array para criar uma matriz associativa. Voc no pode usar a propriedade Array.length ou algum mtodo da classe Array com matrizes associativas, mesmo se o construtor Array ou o tipo de dados Array for usado. O uso do construtor Array mais adequado para a criao de matrizes indexadas.

Matrizes associativas com chaves de objeto (Dicionrios)

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior possvel usar a classe Dictionary para criar uma matriz associativa que usa objetos para chaves em vez de strings. Essas matrizes s vezes so chamadas de dicionrios, hashes ou mapas. Pense, por exemplo, em um aplicativo que determina o local de um objeto Sprite com base em sua associao com um recipiente especfico. Voc pode usar um objeto Dictionary para mapear cada objeto Sprite para um recipiente. O cdigo a seguir cria trs ocorrncias da classe Sprite que servem como chaves para o objeto Dictionary. Cada chave recebe o valor GroupA ou GroupB. Os valores podem ser de qualquer tipo de dados, mas, nesse exemplo, GroupA e GroupB so ocorrncias da classe Object. Posteriormente, voc poder acessar o valor associado a cada chave com o operador de acesso matriz ([]), como mostra o cdigo a seguir:
import flash.display.Sprite; import flash.utils.Dictionary; var groupMap:Dictionary = new Dictionary(); // objects to use var spr1:Sprite = var spr2:Sprite = var spr3:Sprite = as keys new Sprite(); new Sprite(); new Sprite();

// objects to use as values var groupA:Object = new Object(); var groupB:Object = new Object(); // Create new key-value pairs in dictionary. groupMap[spr1] = groupA; groupMap[spr2] = groupB; groupMap[spr3] = groupB; if (groupMap[spr1] { trace("spr1 is } if (groupMap[spr2] { trace("spr2 is } if (groupMap[spr3] { trace("spr3 is } == groupA) in groupA"); == groupB) in groupB"); == groupB) in groupB");

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com matrizes

40

Iterao com chaves de objeto possvel percorrer o contedo de um objeto Dictionary com um loop for..in ou um loop for each..in. O loop for..in permite percorrer o contedo com base nas chaves, enquanto o loop for each..in baseia-se nos valores associados a cada chave. Use o loop for..in para acessar diretamente as chaves de um objeto Dictionary. Voc tambm pode acessar os valores do objeto Dictionary com o operador de acesso matriz ([]). O cdigo a seguir usa o exemplo anterior do dicionrio groupMap para mostrar como percorrer um objeto Dictionary com o loop for..in:
for (var key:Object in groupMap) { trace(key, groupMap[key]); } /* output: [object Sprite] [object Object] [object Sprite] [object Object] [object Sprite] [object Object] */

Use o loop for each..in para acessar diretamente os valores de um objeto Dictionary. O cdigo a seguir tambm usa o dicionrio groupMap para mostrar como percorrer um objeto Dictionary com o loop for each..in:
for each (var item:Object in groupMap) { trace(item); } /* output: [object Object] [object Object] [object Object] */

Gerenciamento de memria e chaves de objeto O Adobe Flash Player e o Adobe AIR usam um sistema de coleta de lixo para recuperar a memria que no mais usada. Quando um objeto no tem nenhuma referncia apontada para ele, est qualificado para a coleta de lixo e a memria recuperada na prxima vez em que o sistema executado. Por exemplo, o cdigo a seguir cria um novo objeto e atribui uma referncia do objeto varivel myObject:
var myObject:Object = new Object();

Contanto que exista alguma referncia ao objeto, o sistema de coleta de lixo no recuperar a memria ocupada pelo objeto. Se o valor de myObject for alterado de modo que aponte para um objeto diferente ou seja definido como o valor null, a memria ocupada pelo objeto original se qualificar para a coleta de lixo, mas somente se no houver nenhuma outra referncia ao objeto original. Se myObject for usado como uma chave em um objeto Dictionary, outra referncia ao objeto original estar sendo criado. Por exemplo, o cdigo a seguir cria duas referncias a um objeto: a varivel myObject e a chave no objeto myMap:
import flash.utils.Dictionary; var myObject:Object = new Object(); var myMap:Dictionary = new Dictionary(); myMap[myObject] = "foo";

Para que o objeto mencionado por myObject se qualifique para a coleta de lixo, remova todas as referncias a ele. Nesse caso, altere o valor de myObject e exclua a chave myObject de myMap, como mostra o cdigo a seguir:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com matrizes

41

myObject = null; delete myMap[myObject];

Como alternativa, voc pode usar o parmetro useWeakReference do construtor Dictionary para que todas as chaves de dicionrio sejam referncias fracas. O sistema de coleta de lixo ignora as referncias fracas e, desse modo, um objeto que tem apenas referncias fracas se qualifica para a coleta de lixo. Por exemplo, no cdigo a seguir, no necessrio excluir a chave myObject de myMap para que o objeto se qualifique para coleta de lixo:
import flash.utils.Dictionary; var myObject:Object = new Object(); var myMap:Dictionary = new Dictionary(true); myMap[myObject] = "foo"; myObject = null; // Make object eligible for garbage collection.

Matrizes multidimensionais
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior As matrizes multidimensionais contm outras matrizes como elementos. Por exemplo, considere uma lista de tarefas armazenada como uma matriz indexada de strings:
var tasks:Array = ["wash dishes", "take out trash"];

Se desejar armazenar uma lista separada de tarefas para cada dia da semana, voc poder criar uma matriz multidimensional com um elemento para cada dia da semana. Cada elemento contm uma matriz indexada, similar matriz tarefas, que armazena a lista de tarefas. possvel usar qualquer combinao de matrizes indexadas ou associativas em matrizes multidimensionais. Os exemplos das sees a seguir usam duas matrizes indexadas ou uma matriz associativa de matrizes indexadas. Se desejar, experimente outras combinaes para praticar.

Duas matrizes indexadas

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Ao usar duas matrizes indexadas, voc pode visualizar o resultado como uma tabela ou uma planilha. Os elementos da primeira matriz representam as linhas da tabela, enquanto os elementos da segunda matriz representam as colunas. Por exemplo, a seguinte matriz multidimensional usa duas matrizes indexadas para rastrear as listas de tarefas de cada dia da semana. A primeira matriz, masterTaskList, criada com o construtor da classe Array. Cada elemento da matriz representa um dia da semana; o ndice 0 representa segunda-feira e o ndice 6 representa domingo. Esses elementos podem ser considerados linhas da tabela. Voc pode criar a lista de tarefas de cada dia atribuindo um literal de matriz a cada um dos sete elementos que podem ser criados na matriz masterTaskList. Os literais de matriz representam as colunas da tabela.
var masterTaskList:Array = new Array(); masterTaskList[0] = ["wash dishes", "take out trash"]; masterTaskList[1] = ["wash dishes", "pay bills"]; masterTaskList[2] = ["wash dishes", "dentist", "wash dog"]; masterTaskList[3] = ["wash dishes"]; masterTaskList[4] = ["wash dishes", "clean house"]; masterTaskList[5] = ["wash dishes", "wash car", "pay rent"]; masterTaskList[6] = ["mow lawn", "fix chair"];

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com matrizes

42

Voc pode acessar itens individuais em qualquer lista de tarefas, usando o operador de acesso matriz ([]). O primeiro conjunto de colchetes representa o dia da semana e o segundo representa a lista de tarefas desse dia. Por exemplo, para recuperar a segunda tarefa da lista de quarta-feira, use primeiro o ndice 2 para quarta-feira e, em seguida, use o ndice 1 para a segunda tarefa da lista.
trace(masterTaskList[2][1]); // output: dentist

Para recuperar a primeira tarefa da lista de domingo, use o ndice 6 para domingo e o ndice 0 para a primeira tarefa da lista.
trace(masterTaskList[6][0]); // output: mow lawn

Matriz associativa com uma matriz indexada

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para facilitar o acesso a matrizes individuais, voc pode usar uma matriz associativa para os dias da semana e uma matriz indexada para as listas de tarefas. A matriz associativa permite usar a sintaxe de ponto ao fazer referncia a um dia da semana especfico, mas aumenta o tempo de processamento de tempo de execuo para acessar cada elemento da matriz associativa. O exemplo a seguir usa uma matriz associativa como base de uma lista de tarefas, com um par de chave e valor para cada dia da semana:
var masterTaskList:Object = new Object(); masterTaskList["Monday"] = ["wash dishes", "take out trash"]; masterTaskList["Tuesday"] = ["wash dishes", "pay bills"]; masterTaskList["Wednesday"] = ["wash dishes", "dentist", "wash dog"]; masterTaskList["Thursday"] = ["wash dishes"]; masterTaskList["Friday"] = ["wash dishes", "clean house"]; masterTaskList["Saturday"] = ["wash dishes", "wash car", "pay rent"]; masterTaskList["Sunday"] = ["mow lawn", "fix chair"];

A sintaxe de ponto deixa o cdigo mais legvel, evitando vrios conjuntos de colchetes.
trace(masterTaskList.Wednesday[1]); // output: dentist trace(masterTaskList.Sunday[0]);// output: mow lawn

possvel percorrer a lista de tarefas usando um loop for..in, mas necessrio usar o operador de acesso matriz ([] em vez da sintaxe de ponto para acessar o valor associado a cada chave. Como masterTaskList uma matriz associativa, os elementos no so recuperados necessariamente na ordem esperada, como mostra o exemplo a seguir:
for (var day:String in masterTaskList) { trace(day + ": " + masterTaskList[day]) } /* output: Sunday: mow lawn,fix chair Wednesday: wash dishes,dentist,wash dog Friday: wash dishes,clean house Thursday: wash dishes Monday: wash dishes,take out trash Saturday: wash dishes,wash car,pay rent Tuesday: wash dishes,pay bills */

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com matrizes

43

Clonagem de matrizes
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe Array no tem nenhum mtodo incorporado para fazer cpias de matrizes. Voc pode criar uma cpiasuperficial de uma matriz chamando os mtodos concat() ou slice() sem nenhum argumento. Em uma cpia superficial, se a matriz original tiver elementos que so objetos, somente as referncias aos objetos sero copiadas, no os objetos propriamente ditos. A cpia aponta para os mesmos objetos da original. Qualquer alterao feita nos objetos refletida nas duas matrizes. Em uma cpia profunda, todos os objetos encontrados na matriz original tambm so copiados para que a nova matriz no aponte para os mesmos objetos da matriz original. A cpia profunda requer mais de uma linha de cdigo, que normalmente chama uma funo de criao. Essa funo pode ser criada como uma funo do utilitrio global ou como um mtodo de uma subclasse de Array. O exemplo a seguir define uma funo chamada clone() que faz a cpia profunda. O algoritmo emprestado de uma tcnica comum de programao Java. A funo cria uma cpia profunda serializando a matriz em uma ocorrncia da classe ByteArray e lendo a matriz de volta em uma nova matriz. Essa funo aceita um objeto para que possa ser usada com matrizes indexadas e associativas, como mostra o cdigo a seguir:
import flash.utils.ByteArray; function clone(source:Object):* { var myBA:ByteArray = new ByteArray(); myBA.writeObject(source); myBA.position = 0; return(myBA.readObject()); }

Extenso da classe Array

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe Array uma das poucas classes principais que no final, ou seja, voc pode criar sua prpria subclasse de Array. Esta seo mostra um exemplo de como criar uma subclasse de Array e discute alguns problemas que podem ocorrer durante o processo. Como mencionado anteriormente, as matrizes no ActionScript no so tipificadas, mas possvel criar uma subclasse de Array que aceita elementos somente de um tipo de dados especfico. O exemplo das sees a seguir define uma subclasse de Array chamada TypedArray que limita seus elementos aos valores do tipo de dados especificado no primeiro parmetro. A classe TypedArray apresentada simplesmente como um exemplo que mostra como estender a classe Array e talvez no seja adequada para fins de produo por diversos motivos. Primeiro, a verificao de tipo ocorre durante o tempo de execuo, no no tempo de compilao. Segundo, quando um mtodo TypedArray encontra uma discordncia, esta ignorada e nenhuma exceo lanada, embora os mtodos possam ser facilmente modificados para lanar excees. Terceiro, a classe no pode impedir o uso do operador de acesso matriz para inserir valores de qualquer tipo na matriz. Quarto, o estilo de codificao favorece a simplicidade por meio da otimizao do desempenho.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com matrizes

44

Nota: Voc pode usar a tcnica descrita aqui para criar uma matriz tipificada. No entanto, recomenda-se o uso de um objeto Vector. Uma ocorrncia de Vector uma matriz true type e fornece desempenho e outros aprimoramentos em relao classe Array ou qualquer subclasse. O objetivo desta discusso demonstrar como criar uma subclasse Array. Declarao da subclasse Use a palavra-chave extends para indicar que uma classe subclasse de Array. Uma subclasse de Array deve usar o atributo dynamic, assim como a classe Array. Caso contrrio, a subclasse no funcionar adequadamente. O cdigo a seguir mostra a definio da classe TypedArray, que contm uma constante para armazenar o tipo de dados, um mtodo de construtor e os quatro mtodos que permitem adicionar elementos matriz. O cdigo de cada mtodo omitido neste exemplo, mas descrito e explicado em detalhes nas sees a seguir:
public dynamic class TypedArray extends Array { private const dataType:Class; public function TypedArray(...args) {} AS3 override function concat(...args):Array {} AS3 override function push(...args):uint {} AS3 override function splice(...args) {} AS3 override function unshift(...args):uint {} }

Os quatro mtodos de substituio usam o espao para nomes AS3 em vez do atributo public porque este exemplo supe que a opo -as3 do compilador est definida como true e a opo -es est definida como false. Essas so as configuraes padro do Adobe Flash Builder e do Adobe Flash Professional. Se voc for um desenvolvedor experiente que prefere usar prottipos herdados, faa duas pequenas alteraes na classe TypedArray para compil-la com a opo -es do compilador definida como true. Primeiro, remova todas as ocorrncias do atributo override e substitua o espao para nomes AS3 pelo atributo public. Segundo, substitua Array.prototype nas quatro ocorrncias de super. construtor TypedArray O construtor de subclasse cria um desafio interessante porque aceita uma lista de argumentos de comprimento arbitrrio. O desafio agora transmitir os argumentos para o superconstrutor a fim de criar a matriz. Se voc transmitir a lista de argumentos como uma matriz, o superconstrutor ir consider-la como um nico argumento do tipo Array e a matriz resultante ter sempre um elemento. O modo tradicional de manipular a transmisso de listas de argumentos usar o mtodo Function.apply(), que trata uma matriz de argumentos como seu segundo parmetro, mas a converte em uma lista de argumentos ao executar a funo. Infelizmente, o mtodo Function.apply() no pode ser usado com construtores. A nica opo restante recriar a lgica do construtor Array no construtor TypedArray. O cdigo a seguir mostra o algoritmo usado no construtor da classe Array, que pode ser reutilizado no construtor da subclasse de Array:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com matrizes

45

public dynamic class Array { public function Array(...args) { var n:uint = args.length if (n == 1 && (args[0] is Number)) { var dlen:Number = args[0]; var ulen:uint = dlen; if (ulen != dlen) { throw new RangeError("Array index is not a 32-bit unsigned integer ("+dlen+")"); } length = ulen; } else { length = n; for (var i:int=0; i < n; i++) { this[i] = args[i] } } } }

O construtor TypedArray compartilha a maior parte do cdigo do construtor Array, com apenas quatro alteraes no cdigo. Primeiro, a lista de parmetros inclui um novo parmetro obrigatrio de classe de tipo que permite especificar o tipo de dados da matriz. Segundo, a varivel dataType atribuda ao tipo de dados transmitido ao construtor. Terceiro, na instruo else, o valor da propriedade length atribudo depois do loop for para que length inclua somente os argumentos do tipo correto. Quarto, o corpo do loop for usa a verso de substituio do mtodo push() para que apenas os argumentos do tipo de dados correto sejam adicionados matriz. O exemplo a seguir mostra a funo do construtor TypedArray:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com matrizes

46

public dynamic class TypedArray extends Array { private var dataType:Class; public function TypedArray(typeParam:Class, ...args) { dataType = typeParam; var n:uint = args.length if (n == 1 && (args[0] is Number)) { var dlen:Number = args[0]; var ulen:uint = dlen if (ulen != dlen) { throw new RangeError("Array index is not a 32-bit unsigned integer ("+dlen+")") } length = ulen; } else { for (var i:int=0; i < n; i++) { // type check done in push() this.push(args[i]) } length = this.length; } } }

Mtodos de substituio de TypedArray A classe TypedArray substitui os quatro mtodos da classe Array que permitem adicionar elementos a uma matriz. Em cada caso, o mtodo de substituio adiciona uma verificao de tipo que impede a adio de elementos que no so do tipo de dados correto. Posteriormente, cada mtodo chama sua prpria verso de superclasse. O mtodo push() percorre a lista de argumentos com um loop for..in e faz uma verificao de tipo em cada argumento. Todos os argumentos que no so do tipo correto so removidos da matriz args com o mtodo splice(). Quando o loop for..in termina, a matriz args contm valores somente do tipo dataType. A verso de superclasse de push() chamada com a matriz args atualizada, como mostra o cdigo a seguir:
AS3 override function push(...args):uint { for (var i:* in args) { if (!(args[i] is dataType)) { args.splice(i,1); } } return (super.push.apply(this, args)); }

O mtodo concat() cria uma matriz TypedArray temporria chamada passArgs para armazenar os argumentos aprovados na verificao de tipo. Isso permite a reutilizao do cdigo de verificao de tipo existente no mtodo push(). O loop for..in percorre a matriz args e chama push() em cada argumento. Como passArgs tipificada como TypedArray, a verso TypedArray de push() executada. Em seguida, o mtodo concat() chama sua prpria verso de superclasse, como mostra o cdigo a seguir:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com matrizes

47

AS3 override function concat(...args):Array { var passArgs:TypedArray = new TypedArray(dataType); for (var i:* in args) { // type check done in push() passArgs.push(args[i]); } return (super.concat.apply(this, passArgs)); }

O mtodo splice() usa uma lista arbitrria de argumentos, mas os dois primeiros argumentos sempre fazem referncia a um nmero de ndice e ao nmero de elementos a serem excludos. por esse motivo que o mtodo de substituio splice() executa a verificao de tipo somente para os elementos da matriz args nas posies de ndice 2 ou superior. interessante observar que o cdigo parece ser uma chamada recursiva para splice() no loop for, mas no porque args do tipo Array e no TypedArray, o que significa que a chamada para args.splice() uma chamada para a verso de superclasse do mtodo. Quando o loop for..in termina, a matriz args contm apenas os valores do tipo correto nas posies de ndice 2 ou superior e splice() chama sua prpria verso de superclasse, como mostra o cdigo a seguir:
AS3 override function splice(...args):* { if (args.length > 2) { for (var i:int=2; i< args.length; i++) { if (!(args[i] is dataType)) { args.splice(i,1); } } } return (super.splice.apply(this, args)); }

O mtodo unshift(), que adiciona elementos ao incio de uma matriz, tambm aceita uma lista arbitrria de argumentos. O mtodo de substituio unshift() usa um algoritmo muito parecido com o usado pelo mtodo push(), como mostra o exemplo a seguir:
AS3 override function unshift(...args):uint { for (var i:* in args) { if (!(args[i] is dataType)) { args.splice(i,1); } } return (super.unshift.apply(this, args)); } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com matrizes

48

Exemplo de matriz: PlayList

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O exemplo Lista de reproduo demonstra tcnicas de trabalho com matrizes, no mbito de um aplicativo de lista de reproduo que gerencia uma lista de msicas. Estas tcnicas so:

Criao de uma matriz indexada Adio de itens a uma matriz indexada Classificao de uma matriz de objetos por propriedades diferentes, usando opes de classificao diferentes Converso de uma matriz em uma string delimitada por caracteres
Para obter os arquivos do aplicativo para este exemplo, consulte www.adobe.com/go/learn_programmingAS3samples_flash_br. Os arquivos do aplicativo Lista de reproduo esto localizados na pasta Amostras/Lista de reproduo. O aplicativo consiste nos seguintes arquivos:
Arquivo PlayList.mxml ou PlayList.fla com/example/programmingas3/playlist/PlayList.as Uma classe que representa uma lista de msicas. Usa um Array para armazenar a lista e gerencia a ordenao dos itens da lista. O objeto de valor que representa informaes sobre uma nica msica. Os itens gerenciados pela classe PlayList so ocorrncias de Song. Uma pseudo enumerao cujos valores disponveis representam as propriedades da classe Song por meio da qual uma lista de objetos Song pode ser classificada. Descrio O arquivo principal do aplicativo no Flash (FLA) ou no Flex (MXML).

com/example/programmingas3/playlist/Song.as

com/example/programmingas3/playlist/SortProperty.as

Viso geral da classe PlayList

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe PlayList gerencia um conjunto de objetos Song. Ela tem mtodos pblicos e adiciona uma msica lista de reproduo (o mtodo addSong()), alm de classificar as msicas na lista (o mtodo sortList()). Alm disso, a classe inclui uma propriedade de acesso somente leitura, songList, que fornece acesso ao conjunto real de msicas da lista de reproduo. Internamente, a classe PlayList mantm um registro das msicas usando uma varivel de Array privada:
public class PlayList { private var _songs:Array; private var _currentSort:SortProperty = null; private var _needToSort:Boolean = false; ... }

Alm da varivel _songs de Array, que usada pela classe PlayList para manter um registro da lista de msicas, duas outras classes privadas mantm um registro que indica se a lista precisa ser classificada (_needToSort) e qual propriedade classifica a lista de msicas em um determinado momento (_currentSort).

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com matrizes

49

Assim como com todos os objetos, declarar uma ocorrncia de Array apenas metade do trabalho de criao de uma matriz. Antes de acessar propriedades ou mtodos de uma ocorrncia de Array, essa classe deve ser instanciada, o que feito no construtor da classe PlayList.
public function PlayList() { this._songs = new Array(); // Set the initial sorting. this.sortList(SortProperty.TITLE); }

A primeira linha do construtor instancia a varivel _songs, que fica pronta para ser usada. Alm disso, o mtodo sortList() chamado para definir a propriedade sort-by inicial.

Adio de uma msica lista

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Quando o usurio insere uma nova msica do aplicativo, o cdigo no formulrio de entrada de dados chama o mtodo addSong() da classe PlayList.
/** * Adds a song to the playlist. */ public function addSong(song:Song):void { this._songs.push(song); this._needToSort = true; }

Em addSong(), o mtodo push() da matriz _songs chamado e adiciona o objeto Song que foi transmitido para addSong() como um novo elemento dessa matriz. Com o mtodo push(), o novo elemento adicionado ao final da matriz, independentemente de alguma classificao que tenha sido aplicada anteriormente. Isso significa que, depois que o mtodo push() chamado, a lista de msicas provavelmente no ser mais classificada corretamente, de modo que a varivel _needToSort ser definida como true. Teoricamente, o mtodo sortList() poderia ser chamado imediatamente, no sendo mais necessrio manter o registro que indica se a lista deve ou no ser classificada em um determinado momento. No entanto, na prtica, no necessrio classificar a lista de msicas imediatamente antes que ela seja recuperada. Adiando a operao de classificao, o aplicativo no executar uma classificao desnecessria se, por exemplo, vrias msicas forem adicionadas lista antes de ser recuperada.

Classificao da lista de msicas

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Como as ocorrncias de Song gerenciadas pela lista de reproduo so objetos complexos, os usurios do aplicativo talvez queiram classificar a lista de reproduo de acordo com propriedades diferentes, como o ttulo da msica ou o ano de publicao. No aplicativo PlayList, a tarefa de classificar a lista de msicas tem trs partes: identificar a propriedade que classifica a lista, indicar as opes de classificao que devem ser usadas ao classificar de acordo com essa propriedade e executar a operao de classificao real.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com matrizes

50

Propriedades de classificao Um objeto Song mantm o registro de vrias propriedades, incluindo o ttulo da msica, o artista, o ano de publicao, o nome do arquivo e um conjunto de gneros definido pelo usurio ao qual a msica pertence. Entre essas propriedades, apenas as trs primeiras so prticas para classificao. Para facilitar o entendimento dos desenvolvedores, o exemplo inclui a classe SortProperty, que age como uma enumerao com valores que representam as propriedades disponveis para classificao.
public static const TITLE:SortProperty = new SortProperty("title"); public static const ARTIST:SortProperty = new SortProperty("artist"); public static const YEAR:SortProperty = new SortProperty("year");

A classe SortProperty contm trs constantes (TITLE, ARTIST e YEAR), que armazenam uma string com o nome real da propriedade associada da classe Song que pode ser usada para classificao. No restante do cdigo, sempre que uma propriedade de classificao for indicada, o membro de enumerao ser usado. Por exemplo, no construtor PlayList, a lista classificada inicialmente chamando o mtodo sortList() do seguinte modo:
// Set the initial sorting. this.sortList(SortProperty.TITLE);

Como a propriedade de classificao especificada como SortProperty.TITLE, as msicas so classificadas de acordo com o ttulo. Classificao por propriedade e especificao das opes de classificao A classificao real da lista de msicas realizada pela classe PlayList no mtodo sortList() do seguinte modo:
/** * Sorts the list of songs according to the specified property. */ public function sortList(sortProperty:SortProperty):void { ... var sortOptions:uint; switch (sortProperty) { case SortProperty.TITLE: sortOptions = Array.CASEINSENSITIVE; break; case SortProperty.ARTIST: sortOptions = Array.CASEINSENSITIVE; break; case SortProperty.YEAR: sortOptions = Array.NUMERIC; break; } // Perform the actual sorting of the data. this._songs.sortOn(sortProperty.propertyName, sortOptions); // Save the current sort property. this._currentSort = sortProperty; // Record that the list is sorted. this._needToSort = false; }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com matrizes

51

Quando a classificao feita por ttulo ou artista, faz sentido classificar em ordem alfabtica, mas, quando a classificao feita por ano, mais lgico realizar uma classificao numrica. A instruo switch usada para definir a opo de classificao adequada, armazenada na varivel sortOptions, de acordo com o valor especificado no parmetro sortProperty. Aqui, mais uma vez, os membros de enumerao nomeados so usados para diferenciar as propriedades, em vez de valores codificados. Quando a propriedade e as opes de classificao so determinadas, a matriz _songs realmente classificada chamando o mtodo sortOn() e transmitindo esses dois valores como parmetros. A propriedade de classificao atual registrada, o que indica que a lista de msicas est classificada no momento.

Combinao de elementos de matriz em uma string delimitada por caracteres

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Alm de usar uma matriz para manter a lista de msicas na classe PlayList, neste exemplo, as matrizes tambm so usadas na classe Song para ajudar a gerenciar a lista de gneros aos quais pertencem as msicas. Veja este snippet da definio da classe Song:
private var _genres:String; public function Song(title:String, artist:String, year:uint, filename:String, genres:Array) { ... // Genres are passed in as an array // but stored as a semicolon-separated string. this._genres = genres.join(";"); }

Ao criar uma nova ocorrncia de Song, o parmetro genres que usado para especificar os gneros das msicas definido como uma ocorrncia de Array. Desse modo, fcil agrupar vrios gneros em uma nica varivel que pode ser transmitida para o construtor. No entanto, internamente, a classe Song mantm os gneros na varivel _genres privada como uma ocorrncia de String separada por ponto-e-vrgula. O parmetro Array convertido em uma string separada por ponto-e-vrgula chamando seu mtodo join() com o valor de string literal ";" como o delimitador especificado. Com o mesmo token, os acessadores de genres permitem que os gneros sejam definidos ou recuperados como uma matriz:
public function get genres():Array { // Genres are stored as a semicolon-separated String, // so they need to be transformed into an Array to pass them back out. return this._genres.split(";"); } public function set genres(value:Array):void { // Genres are passed in as an array, // but stored as a semicolon-separated string. this._genres = value.join(";"); }

O acessador genresset se comporta exatamente como o construtor: aceita uma matriz e chama o mtodo join() para convert-la em uma string separada por ponto-e-vrgula. O acessador get executa a operao oposta: o mtodo split() da varivel _genres chamado, dividindo a string em uma matriz de valores que usa o delimitador especificado (o valor de string literal ";" como antes).

ltima atualizao em 29/3/2011

52

Captulo 4: Manipulao de erros

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Tratar um erro significa incluir lgica em seu aplicativo para reagir a um erro ou solucion-lo. Os erros so gerados quando um aplicativo compilado ou quando um aplicativo compilado estiver em execuo. Quando o aplicativo manipula erros e o erro encontrado, acontece algo em resposta, em vez de ficar sem resposta (quando qualquer processo que criou o erro falha discretamente). Usado corretamente, a manipulao de erros ajuda a proteger o aplicativos e seus usurios de um comportamento inesperado. No entanto, o tratamento de erros uma ampla categoria que inclui responder a muitos tipos de erros que so lanados durante a compilao ou enquanto um aplicativo est em execuo. Essa discusso concentra-se em como tratar erros em tempo de execuo (gerados durante a execuo de um aplicativo), nos tipos diferentes de erros que podem ser gerados e nas vantagens do sistema de tratamento de erros no ActionScript 3.0.

Noes bsicas da manipulao de erros

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O erro em tempo de execuo algo que d errado no seu cdigo de ActionScript e que impede a execuo do contedo do ActionScript da forma pretendida. Para garantir que o seu cdigo do ActionScript seja executado corretamente para os usurios, voc deve escrev-lo no aplicativo que manipula o erro (que o corrige, contorna ou pelo menos deixa o usurio saber o que aconteceu). Esse processo chamado de manipulao de erros. O tratamento de erros uma ampla categoria que inclui responder a muitos tipos de erros que so lanados durante a compilao ou enquanto um aplicativo est em execuo. Os erros que acontecem em tempo de compilao, em geral, so mais fceis de identificar; necessrio corrigi-los para concluir o processo de criao de um arquivo SWF. Os erros de tempo de execuo podem ser mais difceis de detectar, porque, para que ocorram, o cdigo com falha deve realmente ser executado. Se um segmento do seu programa tiver vrias ramificaes de cdigo, como uma instruo if..then..A instruo else testa cada condio possvel, com todos os valores de entrada possveis que os usurios reais podem usar, para confirmar que o seu cdigo no possui erros. Os erros de tempo de execuo podem ser divididos em duas categorias: erros de programa so erros no seu cdigo do ActionScript, como especificar o tipo de dados errado para o parmetro de um mtodo; erros lgicos so erros na lgica (na verificao de dados e manipulao de valores) do seu programa, tal como usar a frmula errada para calcular taxas de juros em um aplicativo bancrio. Novamente, os dois tipos de erros, em geral, podem ser detectados e corrigidos com antecedncia, testando prontamente o aplicativo. Provavelmente, voc desejar identificar e remover todos os erros do aplicativo antes de lan-lo para os usurios finais. Entretanto, nem todos os erros podem ser previstos ou evitados. Por exemplo, suponha que o aplicativo do ActionScript carregue informaes de um site especfico que esteja fora do seu controle. Se, em algum momento, esse site no estiver disponvel, a parte do seu aplicativo que depende desses dados externos no se comportar corretamente. O aspecto mais importante do tratamento de erros diz respeito preparao para os casos desconhecidos ao tratamento desses erros de maneira elegante. Os usurios precisam continuar usando seu aplicativo, ou pelo menos ver uma mensagem de erro intuitiva explicando o motivo do defeito.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de erros

53

Os erros de tempo de execuo so representados de duas formas no ActionScript:

Classes de erro: muitos erros possuem uma classe de erro associada. Quando ocorre um erro, o tempo de execuo
do Flash (como o Flash Player ou o Adobe AIR) cria uma ocorrncia da classe de erro especfica associada a esse erro em particular. O seu cdigo pode usar as informaes contidas nesse objeto de erro para dar uma resposta apropriada ao erro.

Eventos de erro: s vezes ocorre um erro quando o tempo de execuo do Flash normalmente dispararia um evento.
Nesses casos, disparado um evento de erro. Cada evento de erro possui uma classe associada, e o tempo de execuo do Flash transmite uma instncia dessa classe para os mtodos que so inscritos no evento de erro. Para determinar se um mtodo em particular pode disparar um erro ou um evento de erro, consulte a entrada do mtodo na Referncia do ActionScript 3.0 para a plataforma Adobe Flash. Conceitos e termos importantes A seguinte lista de consulta contm termos importantes para a programao de rotinas de tratamento de erros:
Assncrono Um comando de programa, como uma chamada de mtodo, que no fornece um resultado imediato e, em vez disso, apresenta um resultado (ou erro) na forma de um evento. Catch quando ocorre uma exceo (um erro de tempo de execuo) e seu cdigo obtm essa informao, ele recebe a

instruo catch para detectar a exceo. Depois que uma execuo capturada, o tempo de execuo do Flash para de notificar outro cdigo do ActionScript da exceo.
Verso do deputador Uma verso especial do tempo de execuo do Flash, como a verso de depurao do Flash Player do AIR Debug Launcher (ADL), que contm cdigo para notificar os usurios dos erros em tempo de execuo. Na verso padro do Flash Player ou do Adobe AIR (aquela que a maioria dos usurios possui), os erros que no so manipulados pelo cdigo do ActionScript so ignorados. Nas verses de depurador (que so includas no Adobe Flash CS4 Professional e no Adobe Flash Builder), exibida uma mensagem de aviso quando acontece um erro no manipulado. Exceo Um erro que ocorre enquanto um aplicativo est sendo executado e que o tempo de execuo do Flash no

pode resolver sozinho.

Relanar Quando seu cdigo captura uma exceo, o tempo de execuo do Flash no notifica mais outros objetos da exceo. Se for importante que os outros objetos recebam a exceo, o seu cdigo dever gerar novamente a exceo para reiniciar o processo de notificao. Sncrono Um comando de programa, como uma chamada de mtodo, que fornece um resultado imediato (ou

imediatamente gera um erro), o que significa que a resposta pode ser usada dentro do mesmo bloco de cdigo.
Lanar O ato de notificar o tempo de execuo do Flash (e consequentemente notificar outros objetos e cdigo do

ActionScript) de que um erro ocorreu conhecido como lanar um erro.

Tipos de erros
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Quando desenvolver e executar aplicativos, voc encontrar diferentes tipos de erros e terminologia de erros. A lista a seguir apresenta os principais termos e tipos de erros:

Erros de tempo de compilao so gerados pelo compilador do ActionScript durante a compilao de cdigo. Os
erros de compilao ocorrem quando problemas sintticos no seu cdigo impedem a criao do aplicativo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de erros

54

Erros de tempo de execuo ocorrem quando voc executa o aplicativo depois de compil-lo. Os erros de tempo de
execuo representam os erros causados quando um arquivo SWF reproduzido no tempo de execuo do Flash (como Adobe Flash Player ou Adobe AIR). Na maioria dos casos, voc poder manipular os erros de tempo de execuo assim que eles ocorrerem, relatando-os ao usurio e tomando medidas para manter o aplicativo em execuo. Se o erro for fatal, por exemplo, no for possvel conectar a um site remoto ou carregar os dados necessrios, voc poder usar a manipulao de erros para permitir que o aplicativo seja concludo normalmente.

Os erros sncronos so erros de tempo de execuo que ocorrem no momento em que uma funo chamada; por
exemplo, quando voc tenta usar um mtodo especfico e o argumento que transmite para o mtodo invlido, o tempo de execuo do Flash gera uma exceo. A maioria dos erros ocorre de forma sncrona, no momento em que a instruo executada, e o fluxo de controle transmite imediatamente para a instruo catch mais aplicvel. Por exemplo, o trecho de cdigo a seguir lana um erro de tempo de execuo porque o mtodo browse() no chamado antes de o programa tentar carregar um arquivo:
var fileRef:FileReference = new FileReference(); try { fileRef.upload(new URLRequest("http://www.yourdomain.com/fileupload.cfm")); } catch (error:IllegalOperationError) { trace(error); // Error #2037: Functions called in incorrect sequence, or earlier // call was unsuccessful. }

Nesse caso, um erro de tempo de execuo lanado de forma sncrona porque o Flash Player determinou que o mtodo browse() no foi chamado antes da tentativa de upload do arquivo. Para obter informaes detalhadas sobre manipulao de erros sncronos, consulte Manipulao de erros sncronos em um aplicativo na pgina 58.

Erros Assncronos so erros de tempo de execuo que ocorrem em diversos pontos durante a execuo; eles geram
eventos e os ouvintes de eventos os capturam. Uma operao assncrona aquela na qual uma funo inicia uma operao, mas no espera ela ser concluda. Voc pode criar um ouvinte de eventos de erro que espere o aplicativo ou usurio tentar alguma operao e, se a operao falhar, detecte o erro com um ouvinte de eventos e responda ao evento de erro. Depois, o ouvinte de eventos chama uma funo de manipulador de eventos para responder ao evento de erro da melhor maneira. Por exemplo, o manipulador de eventos pode iniciar uma caixa de dilogo que solicite que o usurio resolva o erro. Considere o exemplo de erro sncrono de carregamento de arquivo apresentado anteriormente. Se voc chamar com xito o mtodo browse() antes de comear a carregar um arquivo, o Flash Player ir despachar vrios eventos. Por exemplo, quando um upload iniciado, o evento open despachado. Quando a operao de upload de arquivo concluda com xito, o evento complete despachado. Como a manipulao de eventos assncrona (isto , no ocorre em momentos especficos, conhecidos e predeterminados), necessrio usar o mtodo addEventListener() para ouvir esses eventos especficos, como mostra o seguinte cdigo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de erros

55

var fileRef:FileReference = new FileReference(); fileRef.addEventListener(Event.SELECT, selectHandler); fileRef.addEventListener(Event.OPEN, openHandler); fileRef.addEventListener(Event.COMPLETE, completeHandler); fileRef.browse(); function selectHandler(event:Event):void { trace("...select..."); var request:URLRequest = new URLRequest("http://www.yourdomain.com/fileupload.cfm"); request.method = URLRequestMethod.POST; event.target.upload(request); } function openHandler(event:Event):void { trace("...open..."); } function completeHandler(event:Event):void { trace("...complete..."); }

Para obter informaes detalhadas sobre manipulao de erros assncronos, consulte Resposta a eventos e status de erros na pgina 63.

Excees no detectadas so erros lanados sem nenhuma lgica correspondente (como uma instruo catch) em
resposta a elas. Se o seu aplicativo lanar um erro, e nenhuma instruo catch apropriada ou manipulador de eventos puderem ser encontrados no nvel atual ou superior para manipular o erro, o erro ser considerado uma exceo no detectada. Quando ocorrer um erro no capturado, o aplicativo gera um erro uncaughtError. Esse evento tambm conhecido como tratamento global de erros. Este evento gerado pelo objeto UncaughtErrorEvents do SWF, que est disponvel atravs da propriedade LoaderInfo.uncaughtErrorEvents. Se no houver nenhum ouvinte registrado para o evento uncaughtError, o aplicativo ignorar os erros no capturados e tentar continuar a execuo, enquanto o erro no fizer o SWF parar. Alm de gerar o evento uncaughtError, as verses de depurador do tempo de execuo do Flash reagem aos erros no capturados por meio do encerramento do script atual. Ento, elas exibem o erro no capturado na sada do comando trace ou gravando a mensagem de erro em um arquivo de log. Se o objeto de exceo for uma instncia da classe Error ou uma de suas subclasses, o mtodo getStackTrace() ser chamado. As informaes de rastreamento da pilha tambm so exibidas na sada do comando trace ou em um arquivo de log. Para obter mais informaes sobre como usar a verso de depurador dos tempos de execuo do Flash, consulte Trabalho com as verses de depurador dos tempos de execuo do Flash na pgina 57. Nota: Durante o processamento de um evento uncaughtError, se um evento de erro for lanado por um manipulador uncaughtError, o manipulador de evento chamado vrias vezes. Isso resulta em um loop infinito de excees. Recomenda-se evitar essa situao.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de erros

56

Manipulao de erros no ActionScript 3.0

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Como muitos aplicativos podem ser executados sem construir a lgica para manipular erros, os desenvolvedores ficam tentados a adiar a criao da manipulao de erros em seus aplicativos. Entretanto, sem isso, um aplicativo pode parar facilmente ou frustrar o usurio caso algo no funcione conforme o esperado. O ActionScript 2.0 possui uma classe Error que permite criar a lgica dentro de funes personalizadas e lanar uma exceo com uma mensagem especfica. Como a manipulao de erros essencial para tornar um aplicativo amigvel, o ActionScript 3.0 inclui uma arquitetura expandida para detectar erros. Nota: Embora a Referncia do ActionScript 3.0 para a plataforma Adobe Flash documente as excees geradas por muitos mtodos, talvez ela no contemple todas as excees possveis de cada mtodo. Um mtodo pode gerar uma exceo para erros de sintaxe ou outros problemas que no so observados explicitamente na descrio do mtodo, mesmo quando a descrio lista algumas das excees que um mtodo gera.

Elementos de manipulao de erros do ActionScript 3.0

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O ActionScript 3.0 inclui vrias ferramentas para manipulao de erros, incluindo:

Classes de erro. O ActionScript 3.0 inclui uma ampla variedade de classes Error para expandir o escopo de situaes
que podem produzir objetos de erro. Cada classe Error ajuda os aplicativos a manipular e responder a condies de erro especficas, quer estejam relacionadas a erros de sistema (como uma condio MemoryError), erros de cdigo (como uma condio ArgumentError), erros de rede e comunicao (como uma condio URIError) ou a outras situaes. Para obter mais informaes sobre cada classe, consulte Comparao das classes Error na pgina 67.

Menos falhas silenciosas. Nas verses anteriores do Flash Player, os erros eram gerados e relatados somente se voc
usasse a instruo throw explicitamente. Para o Flash Player 9 e tempos de execuo do Flash posteriores, mtodos e propriedades originais do ActionScript geram erros de tempo de execuo. Esses erros permitem que voc trate essas excees de maneira mais eficaz quando elas ocorrem, depois reaja individualmente a cada exceo.

Limpar mensagens de erro exibidas durante a depurao. Ao usar a verso de depurador de um tempo de execuo
do Flash, situaes ou cdigos problemticos geram mensagens de erro robustas, o que ajuda a identificar facilmente os motivos da falha de um bloco de cdigo especfico. Essas mensagens tornam mais eficaz a correo dos erros. Para obter mais informaes, consulte Trabalho com as verses de depurador dos tempos de execuo do Flash na pgina 57.

Erros precisos permitem a exibio de claras mensagens de erro aos usurios. Nas verses anteriores do Flash
Player, o mtodo FileReference.upload() retornava um valor booleano de false se a chamada upload() no fosse bem-sucedida, indicando um de cinco erros possveis. Se ocorrer um erro ao chamar o mtodo upload() no ActionScript 3.0, quatro erros especficos ajudam a exibir mensagens de erro mais precisas aos usurios finais.

Manipulao de erros refinada. Erros distintos so lanados para vrias situaes comuns. Por exemplo, no
ActionScript 2.0, antes de um objeto FileReference ser preenchido, a propriedade name tem o valor null (portanto, antes de usar ou exibir a propriedade name, necessrio garantir que o valor seja definido e no seja null). No ActionScript 3.0, se voc tentar acessar a propriedade name antes que ela seja preenchida, o Flash Player ou o AIR lanar IllegalOperationError, informando que o valor no foi definido, e voc pode usar blocos try..catch..finally para manipular o erro. Para obter mais informaes, consulte, Uso das instrues try..catch..finally na pgina 58.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de erros

57

Nenhuma desvantagem de desempenho significativa. O uso de blocos try..catch..finally para manipular

erros exige poucos (ou nenhum dos) recursos adicionais comparado s verses anteriores do ActionScript.

Uma classe ErrorEvent que permite criar ouvintes para eventos de erro assncronos especficos. Para obter mais
informaes, consulte Resposta a eventos e status de erros na pgina 63.

Estratgias de manipulao de erros

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Contanto que o aplicativo no encontre uma condio problemtica, ele poder ser executado com xito se voc no criar uma lgica de manipulao de erros no seu cdigo. Entretanto, se voc no manipular os erros ativamente e seu aplicativo encontrar um problema, seus usurios nunca sabero por que ocorreu uma falha. H diferentes maneiras de abordar a manipulao de erros no seu aplicativo. A lista a seguir resume as trs principais opes para manipular erros:

Usar instrues try..catch..finally. Esses comandos detectaro os erros sncronos que ocorrerem. Voc pode
aninhar essas instrues em uma hierarquia para detectar excees em diversos nveis de execuo de cdigo. Para obter mais informaes, consulte, Uso das instrues try..catch..finally na pgina 58.

Criar seus prprios objetos de erro personalizados. Voc pode usar a classe Error para criar seus prprios objetos
de erro personalizados a fim de controlar operaes especficas no seu aplicativo que no estejam includas nos tipos de erro embutidos. Depois, voc pode usar as instrues try..catch..finally nos seus objetos de erro personalizados. Para obter mais informaes, consulte Criao de classes de erros personalizadas na pgina 62.

Escreva ouvintes e manipuladores de eventos para responder aos eventos de erro. Usando essa estratgia, voc pode
criar manipuladores de erro globais que permitem manipular eventos semelhantes sem duplicar uma grande quantidade de cdigo em try.catch..finally. Voc tem muito mais chances de detectar erros assncronos usando essa abordagem. Para obter mais informaes, consulte Resposta a eventos e status de erros na pgina 63.

Trabalho com as verses de depurador dos tempos de execuo do Flash

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A Adobe fornece aos desenvolvedores edies especiais dos tempos de execuo do Flash para ajudar nos esforos de depurao. Ao instalar o Adobe Flash Professional ou o Adobe Flash Builder, voc obtm uma cpia da verso de depurador do Flash Player. Ao instalar uma dessas ferramentas, voc obtm um utilitrio para a depurao dos aplicativos Adobe AIR, tambm chamado de ADL, tambm fornecida como parte do Adobe AIR SDK. H uma grande diferena na forma como as verses de depurador e de lanamento do Flash Player e do Adobe AIR indicam os erros. As verses de depurador mostram o tipo de erro (como Error, IOError ou EOFError genricos), o nmero de erros e uma mensagem de erro legvel. As verses de lanamento mostram apenas o tipo de erro e o nmero de erros. Por exemplo, considere o seguinte cdigo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de erros

58

try { tf.text = myByteArray.readBoolean(); } catch (error:EOFError) { tf.text = error.toString(); }

Se o mtodo readBoolean() gerar um EOFError na verso de depurador do Flash Player, a seguinte mensagem ser exibida no campo de texto tf: "EOFError: Erro 2030: Fim do arquivo localizado." O mesmo cdigo em uma verso de lanamento do Flash Player ou do Adobe AIR exibiria o seguinte texto: "EOFError: Erro 2030." Nota: Os players depuradores transmitem um evento chamado "allComplete"; evite criar eventos personalizados com o nome "allComplete". Caso contrrio, voc encontrar comportamentos imprevisveis ao depurar. Para manter os recursos e o tamanho mnimos nas verses de lanamento, as sequncias de caracteres de mensagem de erro no esto presentes. Voc pode pesquisar o nmero do erro na documentao (os apndices da Referncia do ActionScript 3.0 para a plataforma Adobe Flash Platform) para correlacionar a uma mensagem de erro. Se preferir, voc pode reproduzir o erro usando as verses de depurador do Flash Player e do AIR para ver a mensagem inteira.

Manipulao de erros sncronos em um aplicativo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A manipulao de erros mais comum a lgica de manipulao de erros sncrona, em que voc insere instrues no cdigo para detectar erros sncronos enquanto um aplicativo est em execuo. Esse tipo de manipulao de erros permite ao aplicativo notar e se recuperar de erros de tempo de execuo quando as funes falham. A lgica para detectar um erro sncrono inclui as instrues try..catch..finally, que literalmente tentam uma operao, detectam qualquer resposta de erro do tempo de execuo do Flash e finalmente executam outra operao para manipular a operao que falhou.

Uso das instrues try..catch..finally

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Durante o trabalho com erros de tempo de execuo sncronos, use as instrues try..catch..finally para detectar erros. Quando ocorre um erro de tempo de execuo, o tempo de execuo do Flash lana uma exceo, o que significa que ele suspende a execuo normal e cria um objeto especial do tipo Error. O objeto Error lanado para o primeiro bloco catch disponvel. A instruo try delimita instrues com potencial para criar erros. A instruo catch sempre usada com uma instruo try. Se for detectado um erro em uma das instrues no bloco try, as instrues catch anexadas a try sero executadas. A instruo finally delimitar as instrues que sero executadas caso ocorra ou no um erro no bloco try. Se no houver nenhum erro, as instrues no bloco finally sero executadas depois que as instrues do bloco try forem concludas. Se houver um erro, a instruo catch apropriada ser executada primeiro, seguida pelas instrues no bloco finally. O cdigo a seguir demonstra a sintaxe para usar as instrues try..catch..finally:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de erros

59

try { // some code that could throw an error } catch (err:Error) { // code to react to the error } finally { // Code that runs whether an error was thrown. This code can clean // up after the error, or take steps to keep the application running. }

Cada instruo catch identifica um tipo especfico de exceo que ela manipula. A instruo catch pode especificar apenas as classes de erro que forem subclasses da classe Error. Cada instruo catch verificada por ordem. Somente a primeira instruo catch que corresponder ao tipo de erro gerado ser executada. Em outras palavras, se voc verificar primeiro a classe Error de alto nvel e depois uma subclasse dela, somente a classe Error de alto nvel ser correspondente. O seguinte cdigo ilustra essa questo:
try { throw new ArgumentError("I am an ArgumentError"); } catch (error:Error) { trace("<Error> " + error.message); } catch (error:ArgumentError) { trace("<ArgumentError> " + error.message); }

O cdigo anterior exibe a seguinte sada:

<Error> I am an ArgumentError

Para detectar corretamente o ArgumentError, os tipos de erro mais especficos devem ser listados primeiro e os mais genricos por ltimo, como mostra o seguinte cdigo:
try { throw new ArgumentError("I am an ArgumentError"); } catch (error:ArgumentError) { trace("<ArgumentError> " + error.message); } catch (error:Error) { trace("<Error> " + error.message); }

Vrios mtodos e propriedades na API do ActionScript lanam erros de tempo de execuo quando encontram erros ao serem executados. Por exemplo, o mtodo close() na classe Sound lanar um IOError se o mtodo no conseguir fechar o fluxo de udio, conforme demonstrado no seguinte cdigo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de erros

60

var mySound:Sound = new Sound(); try { mySound.close(); } catch (error:IOError) { // Error #2029: This URLStream object does not have an open stream. }

medida que voc se familiariza com a Referncia do ActionScript 3.0 para a plataforma Adobe Flash, ir perceber quais mtodos geram excees, como detalhado na descrio de cada mtodo.

A instruo throw
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os tempos de execuo do Flash lanam excees quando encontram erros no seu aplicativo em tempo de execuo. Alm disso, voc mesmo pode lanar excees explicitamente usando a instruo throw. Ao lanar erros explicitamente, a Adobe recomenda que voc lance ocorrncias da classe Error ou de suas subclasses. O cdigo a seguir demonstra uma instruo throw que lana uma ocorrncia da classe Error, MyErr e finalmente chama uma funo, myFunction(), para responder depois que o erro lanado:
var MyError:Error = new Error("Encountered an error with the numUsers value", 99); var numUsers:uint = 0; try { if (numUsers == 0) { trace("numUsers equals 0"); } } catch (error:uint) { throw MyError; // Catch unsigned integer errors. } catch (error:int) { throw MyError; // Catch integer errors. } catch (error:Number) { throw MyError; // Catch number errors. } catch (error:*) { throw MyError; // Catch any other error. } finally { myFunction(); // Perform any necessary cleanup here. }

Observe que as instrues catch so ordenadas de forma que os tipos de dados mais especficos sejam listados primeiro. Se a instruo catch do tipo de dados Number for listada primeiro, a instruo catch para o tipo de dados uint e a instruo catch para o tipo de dados int nunca sero executadas.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de erros

61

Nota: Na linguagem de programao Java, cada funo que pode lanar uma exceo deve declarar esse fato, listando as classes de exceo que pode lanar em uma clusula throws anexada declarao de funo. O ActionScript no requer que voc declare as excees geradas por uma funo.

Exibio de uma mensagem de erro simples

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Uma das grandes vantagens do novo modelo de eventos de exceo e erro que ele permite dizer aos usurios quando e por que uma ao falhou. Cabe a voc escrever o cdigo para exibir a mensagem e oferecer opes em resposta. O cdigo a seguir mostra uma instruo try..catch simples para exibir o erro em um campo de texto:
package { import flash.display.Sprite; import flash.text.TextField; public class SimpleError extends Sprite { public var employee:XML = <EmpCode> <costCenter>1234</costCenter> <costCenter>1-234</costCenter> </EmpCode>; public function SimpleError() { try { if (employee.costCenter.length() != 1) { throw new Error("Error, employee must have exactly one cost center assigned."); } } catch (error:Error) { var errorMessage:TextField = new TextField(); errorMessage.autoSize = TextFieldAutoSize.LEFT; errorMessage.textColor = 0xFF0000; errorMessage.text = error.message; addChild(errorMessage); } } } }

Usando uma ampla variedade de classes de erro e erros do compilador embutidos, o ActionScript 3.0 oferece mais informaes do que as verses anteriores do ActionScript sobre o motivo de uma falha. Essa informao permite criar aplicativos mais estveis com uma manipulao de erros melhor.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de erros

62

Relanamento de erros
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Ao criar aplicativos, h vrias ocasies em que pode ser preciso relanar um erro quando no possvel manipul-lo adequadamente. Por exemplo, o cdigo a seguir mostra um bloco try..catch aninhado, que relana um ApplicationError personalizado quando o bloco catch no consegue manipular o erro:
try { try { trace("<< try >>"); throw new ApplicationError("some error which will be rethrown"); } catch (error:ApplicationError) { trace("<< catch >> " + error); trace("<< throw >>"); throw error; } catch (error:Error) { trace("<< Error >> " + error); } } catch (error:ApplicationError) { trace("<< catch >> " + error); }

O resultado do snippet anterior seria o seguinte:

<< << << << try >> catch >> ApplicationError: some error which will be rethrown throw >> catch >> ApplicationError: some error which will be rethrown

O bloco try aninhado lana um erro ApplicationError personalizado que detectado pelo bloco catch subseqente. Esse bloco catch aninhado pode tentar manipular o erro e, se for bem-sucedido, lanar o objeto ApplicationError ao bloco try..catch delimitador.

Criao de classes de erros personalizadas

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc pode estender uma das classes Error padro para criar suas prprias classes de erro especializadas no ActionScript. H vrios motivos para criar suas prprias classes de erro:

Para identificar erros ou grupos de erros especficos que so exclusivos do seu aplicativo.
Por exemplo, execute aes diferentes para erros lanados por seu prprio cdigo, alm daqueles capturados pelo tempo de execuo do Flash. Voc pode criar uma subclasse da classe Error para controlar o novo tipo de dados de erro em blocos try..catch.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de erros

63

Para fornecer recursos de exibio de erros exclusivos para os erros gerados pelo seu aplicativo.
Por exemplo, voc pode criar um novo mtodo toString() que formata suas mensagens de erro de uma determinada maneira. Voc tambm pode definir o mtodo lookupErrorString() que obtm um cdigo de erro e recupera a mensagem apropriada com base na preferncia de idioma do usurio. Uma classe de erro especializada deve estender a classe Error principal do ActionScript. Veja um exemplo de uma classe AppError especializada que estende a classe Error:
public class AppError extends Error { public function AppError(message:String, errorID:int) { super(message, errorID); } }

O exemplo a seguir mostra o uso de AppError em seu projeto:

try { throw new AppError("Encountered Custom AppError", 29); } catch (error:AppError) { trace(error.errorID + ": " + error.message) }

Nota: Para substituir o mtodo Error.toString() na sua subclasse, atribua-lhe um parmetro ...(rest). A especificao da linguagem ECMAScript, na qual o ActionScript 3.0 tem base, define o mtodo Error.toString() desse modo, enquanto o ActionScript 3.0 adota a mesma definio para garantir a compatibilidade com verses anteriores. Portanto, ao substituir o mtodo Error.toString(), deve haver uma correspondncia exata de parmetros. Os parmetros no devem ser transmitidos para o mtodo toString() em tempo de execuo porque sero ignorados.

Resposta a eventos e status de erros

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Um dos aprimoramentos mais notveis da manipulao de erros no ActionScript 3.0 o suporte manipulao de eventos de erro para responder a erros assncronos enquanto um aplicativo est em execuo. (Para obter uma definio de erros assncronos, consulte Tipos de erros na pgina 53.) Voc pode criar ouvintes e manipuladores de eventos para responder aos eventos de erro. Muitas classes despacham os eventos de erro da mesma forma o fazem com outros eventos. Por exemplo, uma instncia da classe XMLSocket normalmente despacha trs tipos de eventos: Event.CLOSE, Event.CONNECT e DataEvent.DATA. Entretanto, quando ocorre um problema, a classe XMLSocket pode despachar o IOErrorEvent.IOError ou o SecurityErrorEvent.SECURITY_ERROR. Para obter mais informaes sobre ouvintes e manipuladores de eventos, consulteManipulao de eventos na pgina 118.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de erros

64

Os eventos de erro se enquadram em duas categorias:

Eventos de erro que estendem a classe ErrorEvent

A classe flash.events.ErrorEvent contm as propriedades e os mtodos para gerenciar erros relacionados s operaes de rede e comunicao em um aplicativo em tempo de execuo. As classes AsyncErrorEvent, IOErrorEvent e SecurityErrorEvent estendem a classe ErrorEvent. Se voc estiver usando a verso de depurador de um tempo de execuo do Flash, uma caixa de dilogo o informar, em tempo de execuo, sobre qualquer evento de erro sem as funes de ouvinte que o player encontrar.

Eventos de erro baseados no status

Os eventos de erro baseados no status esto relacionados s propriedades netStatus e status das classes de rede e comunicao. Se o tempo de execuo do Flash encontrar um problema ao ler ou gravar dados, o valor das propriedades netStatus.info.level ou status.level (dependendo do objeto de classe usado) ser definido com o valor "error". A resposta a esse erro verificar se a propriedade level contm o valor "error" na funo do manipulador de eventos.

Trabalho com eventos de erro

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe ErrorEvent e suas subclasses contm tipos de erro para manipular erros despachados pelos tempos de execuo do Flash quando tentam ler ou gravar dados. O exemplo a seguir usa uma instruo try..catch e manipuladores de evento de erro para exibir os erros detectados ao tentar ler um arquivo local. Voc pode adicionar cdigo de manipulao mais sofisticado para fornecer opes a um usurio ou manipular o erro automaticamente nos locais indicados pelo comentrio "seu cdigo de manipulao de erros aqui":
package { import import import import import import import import import

flash.display.Sprite; flash.errors.IOError; flash.events.IOErrorEvent; flash.events.TextEvent; flash.media.Sound; flash.media.SoundChannel; flash.net.URLRequest; flash.text.TextField; flash.text.TextFieldAutoSize;

public class LinkEventExample extends Sprite { private var myMP3:Sound; public function LinkEventExample() { myMP3 = new Sound(); var list:TextField = new TextField(); list.autoSize = TextFieldAutoSize.LEFT; list.multiline = true; list.htmlText = "<a href=\"event:track1.mp3\">Track 1</a><br>"; list.htmlText += "<a href=\"event:track2.mp3\">Track 2</a><br>"; addEventListener(TextEvent.LINK, linkHandler); addChild(list); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de erros

65

private function playMP3(mp3:String):void { try { myMP3.load(new URLRequest(mp3)); myMP3.play(); } catch (err:Error) { trace(err.message); // your error-handling code here } myMP3.addEventListener(IOErrorEvent.IO_ERROR, errorHandler); } private function linkHandler(linkEvent:TextEvent):void { playMP3(linkEvent.text); // your error-handling code here } private function errorHandler(errorEvent:IOErrorEvent):void { trace(errorEvent.text); // your error-handling code here } } }

Trabalho com eventos de alterao de status

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os tempos de execuo do Flash alteram dinamicamente o valor das propriedades netStatus.info.level ou status.level para as classes que suportam a propriedade level enquanto uma aplicativo est em execuo. As classes que possuem a propriedade netStatus.info.level so: NetConnection, NetStream e SharedObject. As classes que possuem a propriedade status.level so: HTTPStatusEvent, Camera, Microphone e LocalConnection. Voc pode escrever uma funo de manipulador para responder alterao no valor level e controlar os erros de comunicao. O exemplo a seguir usa uma funo netStatusHandler() para testar o valor da propriedade level. Se a propriedade level indicar que um erro foi encontrado, o cdigo rastreia a mensagem Falha no fluxo de vdeo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de erros

66

package { import import import import import import

flash.display.Sprite; flash.events.NetStatusEvent; flash.events.SecurityErrorEvent; flash.media.Video; flash.net.NetConnection; flash.net.NetStream;

public class VideoExample extends Sprite { private var videoUrl:String = "Video.flv"; private var connection:NetConnection; private var stream:NetStream; public function VideoExample() { connection = new NetConnection(); connection.addEventListener(NetStatusEvent.NET_STATUS, netStatusHandler); connection.addEventListener(SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler); connection.connect(null); } private function netStatusHandler(event:NetStatusEvent):void { if (event.info.level == "error") { trace("Video stream failed") } else { connectStream(); } } private function securityErrorHandler(event:SecurityErrorEvent):void { trace("securityErrorHandler: " + event); } private function connectStream():void { var stream:NetStream = new NetStream(connection); var video:Video = new Video(); video.attachNetStream(stream); stream.play(videoUrl); addChild(video); } } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de erros

67

Comparao das classes Error

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O ActionScript fornece vrias classes Error predefinidas. Mas voc tambm pode usar as mesmas classes Error no seu prprio cdigo. H dois tipos principais de classes Error no ActionScript 3.0: As classes Error principais do ActionScript e as classes Error do pacote flash.error. O pacote flash.error contm classes adicionais para auxiliar no desenvolvimento e na depurao de aplicativos do ActionScript 3.0.

classes Error principais

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior As classes de erro principais incluem as classes ArgumentError, EvalError, RangeError, ReferenceError, SecurityError, SyntaxError, TypeError, URIError e VerifyError. Cada uma dessas classes est localizada no namespace de nvel superior.
Nome da classe Error Descrio Observaes

A classe Error usada para gerar excees e a classe A classe Error serve de classe base para todos os erros de tempo base para as outras classes de exceo definidas no de execuo e a classe base recomendada para qualquer ECMAScript: EvalError, RangeError, ReferenceError, classe de erro personalizada. SyntaxError, TypeError e URIError. A classe ArgumentError representa um erro que Alguns exemplos de erros de argumento incluem: ocorre quando os valores de parmetro fornecidos durante uma chamada de funo no correspondem Foram fornecidos argumentos insuficientes ou excedentes para um mtodo. aos definidos para essa funo.

ArgumentError

EvalError

Um argumento que deveria ser um membro de uma enumerao no .

Uma exceo EvalError lanada se qualquer No ActionScript 3.0, o suporte funo eval() foi removido e parmetro for transmitido para o construtor da classe as tentativas de usar a funo resultam em erro. Function ou se o cdigo do usurio chamar a funo As verses anteriores do Flash Player usavam a funo eval() eval(). para acessar variveis, propriedades, objetos ou clipes de filme pelo nome. Uma exceo RangeError lanada quando um valor Por exemplo, um RangeError lanado pela classe Timer se um numrico fica fora de uma faixa aceitvel. atraso for negativo ou se no for finito. Um RangeError tambm poderia ser lanado se voc tentasse adicionar um objeto de exibio em uma profundidade invlida. Uma exceo de ReferenceError lanada quando h uma tentativa de referncia a uma propriedade no definida em um objeto selado (no dinmico). As verses de compilador do ActionScript antes do ActionScript 3.0 no lanavam um erro quando havia uma tentativa de acesso a uma propriedade no definida. No entanto, o ActionScript 3.0 lana a exceo ReferenceError nessa condio. As excees para variveis no definidas apontam para possveis bugs, ajudando a melhorar a qualidade do software. Entretanto, se voc no est acostumado a inicializar as variveis, esse novo comportamento do ActionScript exige algumas alteraes nos seus hbitos de criao de cdigo.

RangeError

ReferenceError

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de erros

68

Nome da classe SecurityError

Descrio A exceo SecurityError lanada quando ocorre uma violao de segurana e o acesso negado.

Observaes Alguns exemplos de erros de segurana incluem:

Um acesso a propriedade ou uma chamada de mtodo no autorizado feito no outro lado de um limite de caixa de proteo. Foi feita uma tentativa de acessar uma URL no permitida pela caixa de proteo. Foi feita uma tentativa de conexo de soquete a uma porta, mas o arquivo de poltica de soquete necessrio no estava disponvel. Foi feita uma tentativa de acessar a cmera ou o microfone do usurio, e o usurio negou o acesso ao dispositivo.

SyntaxError Uma exceo SyntaxError lanada quando ocorre um erro de anlise no cdigo do ActionScript.

Um SyntaxError pode ser lanado sob as seguintes circunstncias:

TypeError A exceo TypeError lanada quando o tipo real de operando diferente do tipo esperado.

O ActionScript lana excees SyntaxError quando a classe RegExp desmembra uma expresso regular invlida. O ActionScript lana excees SyntaxError quando uma classe XMLDocument desmembra um XML invlido.

Um TypeError pode ser lanado sob as seguintes circunstncias:

Um parmetro real para uma funo ou um mtodo no pde ser forado ao tipo de parmetro formal. Um valor atribudo a uma varivel e no pode ser forado ao tipo da varivel. O lado direito do operador is ou instanceof no um tipo vlido. A palavra-chave super usada ilegalmente. Uma pesquisa de propriedades resulta em mais de uma ligao e, portanto, ambgua. Um mtodo chamado em um objeto incompatvel. Por exemplo, uma exceo TypeError ser lanada se um mtodo na classe RegExp for "enxertado" em um objeto genrico e, depois, chamado.

URIError

Uma exceo URIError lanada quando uma das funes de manipulao de URI global usada de forma incompatvel com sua definio. Uma exceo VerifyError lanada quando encontrado um arquivo SWF malformado ou corrompido.

Um URIError pode ser lanado sob as seguintes circunstncias: Um URI invlido especificado para uma funo da API do Flash Player que espera um URI vlido, como Socket.connect(). Quando um arquivo SWF carrega outro arquivo SWF, o SWF pai pode detectar um VerifyError gerado pelo SWF carregado.

VerifyError

flash.error, classes Error do pacote

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O pacote flash.error contm classes de Error que so consideradas parte da API do tempo de execuo do Flash. Ao contrrio das classes Error descritas, o pacote flash.error comunica eventos de erro especficos dos tempos de execuo do Flash (como Flash Player e Adobe AIR).

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de erros

69

Nome da classe EOFError

Descrio Uma exceo EOFError lanada quando voc tenta ler alm do fim dos dados disponveis.

Observaes Por exemplo, um EOFError mostrado quando um dos mtodos de leitura na interface IDataInput chamado e no h dados suficientes para atender solicitao de leitura. Exemplos de excees de erro de operao ilegal incluem:

IllegalOperationError

Uma exceo IllegalOperationError lanada quando um mtodo no implementado ou quando a implementao no abrange o uso atual.

Uma classe base, como DisplayObjectContainer, fornece mais funcionalidade do que o Palco pode suportar. Por exemplo, se voc tentar obter ou definir uma mscara em Stage (usando stage.mask), o tempo de execuo do Flash lana um IllegalOperationError com a mensagem: "A classe Stage no implementa essa propriedade ou esse mtodo". Uma subclasse herda um mtodo que no requer e para o qual no deseja oferecer suporte. Determinados mtodos de acessibilidade so chamados quando o Flash Player compilado sem o suporte de acessibilidade. Recursos somente de autoria so chamados de uma verso de tempo de execuo do Flash Player. Voc tenta definir o nome de um objeto colocado na linha de tempo.

IOError Uma exceo IOError lanada quando ocorre algum tipo de exceo de E/S.

Por exemplo, voc obtm este erro quando uma operao de leitura/gravao tentada em um soquete que no est conectado ou se desconectou.

MemoryError

Uma exceo MemoryError lanada quando h Por padro, a ActionScript Virtual Machine 2 no uma falha na solicitao de alocao de memria. impe um limite sobre a quantidade de memria que um programa do ActionScript aloca. Em um computador de mesa, as falhas de alocao de memria no so frequentes. Um erro lanado quando o sistema no consegue alocar a memria necessria para uma operao. Por isso, em um computador de mesa, essa exceo rara, a menos que uma solicitao de alocao seja extremamente grande; por exemplo, uma solicitao de 3 bilhes de bytes impossvel porque um programa Microsoft Windows de 32 bits s pode acessar 2 GB de espao de endereamento.

ScriptTimeoutError

Uma exceo ScriptTimeoutError lanada quando um intervalo de tempo limite do script de 15 segundos atingido. Ao detectar uma exceo ScriptTimeoutError, possvel manipular melhor o tempo limite do script. Se no houver um manipulador de excees, a exceo no capturada exibir uma caixa de dilogo com uma mensagem de erro.

Para impedir que um desenvolvedor malintencionado detecte a exceo e permanea em um loop infinito, somente a primeira exceo ScriptTimeoutError lanada durante um determinado script pode ser detectada. Uma exceo ScriptTimeoutError subsequente no poder ser detectada pelo seu cdigo e ir imediatamente para o manipulador de excees no detectadas.

StackOverflowError

A exceo StackOverflowError lanada quando a Uma exceo StackOverflowError pode indicar que pilha disponvel para o script esgotada. ocorreu recurso infinita.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de erros

70

Exemplo de tratamento de erros: aplicativo CustomErrors

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O aplicativo CustomErrors demonstra tcnicas para trabalhar com erros personalizados ao criar um aplicativo. Estas tcnicas so:

Validar um pacote XML Escrever um erro personalizado Lanar erros personalizados Notificar os usurios quando um erro lanado
Para obter os arquivos do aplicativo para este exemplo, consulte www.adobe.com/go/learn_programmingAS3samples_flash_br. Os arquivos do aplicativo CustomErrors podem ser encontrados na pasta Samples/CustomError. O aplicativo consiste nos seguintes arquivos:
Arquivo CustomErrors.mxml ou CustomErrors.fla com/example/programmingas3/errors/ApplicationError.as Uma classe que serve de classe de erro base para as classes FatalError e WarningError. Uma classe que define um erro FatalError lanado pelo aplicativo. Essa classe estende a classe ApplicationError personalizada. Uma classe que define um nico mtodo que valida um pacote XML funcionrio fornecido pelo usurio. Uma classe que define um erro WarningError lanado pelo aplicativo. Essa classe estende a classe ApplicationError personalizada. Descrio O arquivo principal do aplicativo no Flash (FLA) ou no Flex (MXML)

com/example/programmingas3/errors/FatalError.as

com/example/programmingas3/errors/Validator.as

com/example/programmingas3/errors/WarningError.as

Viso geral do aplicativo CustomErrors

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Quando o aplicativo carregado, o mtodo initApp() chamado para os aplicativos Flex ou o cdigo (no funo) de linha de tempo executado para os aplicativos do Flash Professional. Esse cdigo define um pacote XML de exemplo a ser verificado pela classe Validator. O seguinte cdigo executado:
employeeXML = <employee id="12345"> <firstName>John</firstName> <lastName>Doe</lastName> <costCenter>12345</costCenter> <costCenter>67890</costCenter> </employee>; }

O pacote XML exibido posteriormente em uma ocorrncia do componente TextArea no Palco. Esta etapa permite modificar o pacote XML antes de tentar valid-lo novamente.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de erros

71

Quando o usurio clica no boto Validate, o mtodo validateData() chamado. Esse mtodo valida o pacote XML funcionrio usando o mtodo validateEmployeeXML() na classe Validator. O cdigo a seguir mostra o mtodo validateData():
function validateData():void { try { var tempXML:XML = XML(xmlText.text); Validator.validateEmployeeXML(tempXML); status.text = "The XML was successfully validated."; } catch (error:FatalError) { showFatalError(error); } catch (error:WarningError) { showWarningError(error); } catch (error:Error) { showGenericError(error); } }

Primeiro, um objeto XML temporrio criado usando o contedo da ocorrncia do componente TextArea xmlText. Em seguida, o mtodo validateEmployeeXML() na classe Validator personalizada (com.example.programmingas3/errors/Validator.as) chamado e transmite o objeto XML temporrio como um parmetro. Se o pacote XML for vlido, a ocorrncia do componente Label status exibir uma mensagem de xito e o aplicativo ser encerrado. Se o mtodo validateEmployeeXML() lanar um erro personalizado (isto , se ocorrer um FatalError, WarningError ou um Error genrico), a instruo catch apropriada executar e chamar o mtodo showFatalError(), showWarningError() ou showGenericError(). Cada um desses mtodos exibe uma mensagem apropriada em uma rea de texto chamada statusText para notificar o usurio do erro especfico que ocorreu. Cada mtodo tambm atualiza a ocorrncia do componente Label status com uma mensagem especfica. Se ocorrer um erro fatal durante a tentativa de validar o pacote XML funcionrio, a mensagem de erro ser exibida na rea de texto statusText e as ocorrncias dos componentes TextArea xmlText e Button validateBtn sero desativadas, como mostra o seguinte cdigo:
function showFatalError(error:FatalError):void { var message:String = error.message + "\n\n"; var title:String = error.getTitle(); statusText.text = message + " " + title + "\n\nThis application has ended."; this.xmlText.enabled = false; this.validateBtn.enabled = false; hideButtons(); }

Se ocorrer um erro de aviso, em vez de um erro fatal, a mensagem de erro ser exibida na ocorrncia statusText TextArea, mas as ocorrncias dos componentes Button e TextField xmlText no sero desativadas. O mtodo showWarningError() exibe uma mensagem de erro personalizada na rea de texto statusText. A mensagem tambm solicita que o usurio decida se deseja prosseguir com a validao do XML ou cancelar o script. O seguinte trecho mostra o mtodo showWarningError():

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de erros

72

function showWarningError(error:WarningError):void { var message:String = error.message + "\n\n" + "Do you want to exit this application?"; showButtons(); var title:String = error.getTitle(); statusText.text = message; }

Quando o usurio clica no boto Yes ou No, o mtodo closeHandler() chamado. O seguinte trecho mostra o mtodo closeHandler():
function closeHandler(event:CloseEvent):void { switch (event.detail) { case yesButton: showFatalError(new FatalError(9999)); break; case noButton: statusText.text = ""; hideButtons(); break; } }

Se o usurio decidir cancelar o script clicando em Yes, um FatalError ser lanado fazendo com que o aplicativo seja encerrado.

Criao de um validador personalizado

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe Validator personalizada contm um nico mtodo, validateEmployeeXML(). O mtodo validateEmployeeXML() usa um nico argumento, employee, que o pacote XML que voc deseja validar. O mtodo validateEmployeeXML() o seguinte:
public static function validateEmployeeXML(employee:XML):void { // checks for the integrity of items in the XML if (employee.costCenter.length() < 1) { throw new FatalError(9000); } if (employee.costCenter.length() > 1) { throw new WarningError(9001); } if (employee.ssn.length() != 1) { throw new FatalError(9002); } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de erros

73

Para ser validado, um funcionrio deve pertencer a um (e apenas um) centro de custos. Se o funcionrio no pertencer a nenhum centro de custos, o mtodo lanar um FatalError, que emitido ao mtodo validateData() no arquivo do aplicativo principal. Se o funcionrio pertencer a mais de um centro de custos, ser lanado um WarningError. A verificao final no validador XML que o usurio tem exatamente um nmero de seguro social (o n ssn no pacote XML). Se no houver exatamente um n ssn, ser lanado um erro FatalError. Voc pode adicionar outras verificaes ao mtodo validateEmployeeXML(), por exemplo, para garantir que o n ssn contenha um nmero vlido ou que o funcionrio tenha pelo menos um nmero de telefone e um endereo de email definido, e os dois valores sejam vlidos. Tambm possvel modificar o XML de forma que cada funcionrio tenha uma ID exclusiva e especifique a ID do seu gerente.

Definio da classe ApplicationError

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe ApplicationError serve de classe base para as classes FatalError e WarningError. A classe ApplicationError estende a classe Error e define seus prprios mtodos e propriedades personalizados, incluindo a definio de ID e gravidade de um erro, e um objeto XML que contm os cdigos e as mensagens de erro personalizados. Essa classe tambm define duas constantes estticas que so usadas para definir a gravidade de cada tipo de erro. O mtodo do construtor da classe ApplicationError o seguinte:
public function ApplicationError() { messages = <errors> <error code="9000"> <![CDATA[Employee must be assigned to a cost center.]]> </error> <error code="9001"> <![CDATA[Employee must be assigned to only one cost center.]]> </error> <error code="9002"> <![CDATA[Employee must have one and only one SSN.]]> </error> <error code="9999"> <![CDATA[The application has been stopped.]]> </error> </errors>; }

Cada n de erro no objeto XML contm um cdigo numrico exclusivo e uma mensagem de erro. As mensagens de erro podem ser facilmente pesquisadas pelo seu cdigo de erro usando o E4X, como mostra o seguinte mtodo getMessageText():
public function getMessageText(id:int):String { var message:XMLList = messages.error.(@code == id); return message[0].text(); }

O mtodo getMessageText() usa um nico argumento inteiro, id, e retorna uma seqncia de caracteres. O argumento id o cdigo de erro para o erro a ser pesquisado. Por exemplo, transmitir um id de 9001 recupera o erro dizendo que os funcionrios devem ser atribudos apenas a um centro de custos. Se houver mais de um erro com o mesmo cdigo, o ActionScript retornar a mensagem de erro apenas para o primeiro resultado encontrado (message[0] no objeto XMLList retornado).

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de erros

74

O mtodo seguinte nessa classe, getTitle(), no usa nenhum parmetro e retorna um valor de seqncia de caracteres que contm a ID de erro para esse erro especfico. Esse valor usado para ajudar a identificar com facilidade o erro exato que ocorreu durante a validao do pacote XML. O seguinte trecho mostra o mtodo getTitle():
public function getTitle():String { return "Error #" + id; }

O mtodo final na classe ApplicationError toString(). Esse mtodo substitui a funo definida na classe Error para que voc possa personalizar a apresentao da mensagem de erro. O mtodo retorna uma seqncia de caracteres que identifica o nmero do erro especfico e a mensagem que ocorreu.
public override function toString():String { return "[APPLICATION ERROR #" + id + "] " + message; }

Definio da classe FatalError

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe FatalError estende a classe ApplicationError personalizada e define trs mtodos: o construtor FatalError, getTitle() e toString(). O primeiro mtodo, o construtor FatalError, usa um nico argumento inteiro, errorID, define a gravidade do erro usando os valores constantes estticos definidos na classe ApplicationError e obtm a mensagem de erro especfica, chamando o mtodo getMessageText() na classe ApplicationError. O construtor FatalError o seguinte:
public function FatalError(errorID:int) { id = errorID; severity = ApplicationError.FATAL; message = getMessageText(errorID); }

O mtodo seguinte na classe FatalError, getTitle(), substitui o mtodo getTitle() definido anteriormente na classe ApplicationError e anexa o texto "-- FATAL" no ttulo para informar ao usurio que um erro fatal ocorreu. O mtodo getTitle() o seguinte:
public override function getTitle():String { return "Error #" + id + " -- FATAL"; }

O mtodo final nessa classe, toString(), substitui o mtodo toString() definido na classe ApplicationError. O mtodo toString() :
public override function toString():String { return "[FATAL ERROR #" + id + "] " + message; }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de erros

75

Definio da classe WarningError

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe WarningError estende a classe ApplicationError e quase idntica classe FatalError, exceto por duas pequenas alteraes de sequncia de caracteres e por definir a gravidade do erro como ApplicationError.WARNING, em vez de ApplicationError.FATAL, como mostra o seguinte cdigo:
public function WarningError(errorID:int) { id = errorID; severity = ApplicationError.WARNING; message = super.getMessageText(errorID); }

ltima atualizao em 29/3/2011

76

Captulo 5: Uso de expresses regulares

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Uma expresso regular descreve um padro que utilizado para localizar e manipular texto correspondente em strings. As expresses regulares parecem ser strings, mas elas podem incluir cdigos especiais para descrever padres e repetio. Por exemplo, a expresso regular a seguir corresponde a uma string que comea com o caractere A seguido por um ou mais dgitos seqenciais.
/A\d+/

Os tpicos a seguir descrevem a sintaxe bsica para construir expresses regulares. Entretanto, as expresses regulares podem ter muita complexidade e nuances. Voc pode encontrar informaes detalhadas sobre expresses regulares na Web e nas livrarias. Lembre-se de que diferentes ambientes de programao implementam expresses regulares de modos diferentes. O ActionScript 3.0 implementa expresses regulares como definido na especificao de idioma do ECMAScript Edio 3 (ECMA-262).

Mais tpicos da Ajuda

RegExp

Noes bsicas de expresses regulares:

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Uma expresso regular descreve um padro de caracteres. As expresses regulares so normalmente usadas para verificar se um valor de texto est em conformidade com um determinado padro (como a verificao para saber se o nmero de telefone digitado pelo usurio tem o nmero de dgitos adequado) ou para substituir partes de um valor de texto que corresponde a um determinado padro. As expresses regulares podem ser simples. Por exemplo, suponha que voc queira confirmar se uma determinada string corresponde a "ABC" ou substituir cada ocorrncia de "ABC" em uma string por algum outro texto. Nesse caso, voc pode usar a seguinte expresso regular, que define o padro composto pelas letras A, B e C em seqncia:
/ABC/

Observe que o literal de uma expresso regular delineado com o caractere de barra (/). Os padres de expresses regulares tambm podem ser complexos e, s vezes, crptico na aparncia, como a expresso a seguir, para corresponder a uma endereo de email vlido:
/([0-9a-zA-Z]+[-._+&])*[0-9a-zA-Z]+@([-0-9a-zA-Z]+[.])+[a-zA-Z]{2,6}/

Com mais freqncia, voc utilizar expresses regulares para pesquisar padres em strings e substituir caracteres. Nesses casos, voc criar um objeto de expresso regular e o usar como um parmetro para um dos vrios mtodos da classe String. Os seguintes mtodos da classe String usam as expresses regulares como parmetros: match(), replace(), search() esplit(). Para obter mais informaes sobre esses mtodos, consulte Localizao de padres em sequncias de caracteres e substituio de subsequncias de caracteres na pgina 17. A classe RegExp inclui as seguintes opes: test() e exec(). Para obter mais informaes, consulte Mtodos para usar expresses regulares com strings na pgina 90.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de expresses regulares

77

Conceitos e termos importantes A lista de referncia a seguir contm termos importantes que so relevantes a este recurso:
Caractere Escape Um caractere indicando que o caractere seguinte deve ser tratado como um metacaractere em vez de um caractere literal. Na sintaxe de expresses regulares, o caractere de barra invertida (\) o caractere escape; portanto uma barra invertida seguida por outro caractere um cdigo especial e no apenas o prprio caractere. Sinalizador Um caractere que especifica algumas opes sobre como o padro de expresso regular deve ser utilizado, como distinguir entre caracteres maisculos e minsculos. Metacaractere Um caractere que tem um significado especial em um padro de expresso regular, em oposio

representao literal do caractere no padro.

Quantificador Um caractere (ou vrios) indicando quantas vezes uma parte do padro deve se repetir. Por exemplo,

um quantificador utilizado para designar que o cdigo postal dos Estados Unidos deve conter cinco ou nove nmeros.
Expresso regular Uma instruo do programa que define um padro de caracteres que podem ser usados para

confirmar se outras strings correspondem quele padro ou substituir partes de uma string.

Sintaxe da expresso regular

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Esta seo descreve todos os elementos da sintaxe de expresso regular do ActionScript. Como voc ver, as expresses regulares podem ter muita complexidade e nuances. Voc pode encontrar informaes detalhadas sobre expresses regulares na Web e nas livrarias. Lembre-se de que diferentes ambientes de programao implementam expresses regulares de modos diferentes. O ActionScript 3.0 implementa expresses regulares como definido na especificao de idioma do ECMAScript Edio 3 (ECMA-262). Normalmente, voc usa expresses regulares que correspondem a padres mais complicados do que uma string de caracteres simples. Por exemplo, a seguinte expresso regular define o padro composto pelas letras A, B e C em seqncia seguida por qualquer dgito:
/ABC\d/

O cdigo \d representa qualquer dgito. O caractere de barra invertida (\) chamado de caractere escape e combinado ao caractere que o segue (nesse caso a letra d), tendo um significado especial na expresso regular. A expresso regular a seguir define o padro das letras ABC seguido por qualquer nmero de dgitos (observe o asterisco):
/ABC\d*/

O caractere asterisco (*) um metacaractere. Um metacaractere um caractere que tem significado especial nas expresses regulares. O asterisco um tipo especfico de metacaractere chamado de quantificador que usado para quantificar o nmero de repetio de um caractere ou de um grupo de caracteres. Para obter mais informaes, consulte Quantificadores na pgina 82. Alm desse padro, uma expresso regular pode conter sinalizadores, que especificam como ela deve ser correspondida. Por exemplo, a seguinte expresso regular usa o sinalizador i, que especifica que a expresso regular no diferencia maisculas de minsculas na correspondncia de strings:
/ABC\d*/i

Para obter mais informaes, consulte Sinalizadores e propriedades na pgina 87.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de expresses regulares

78

Voc pode usar expresses regulares com os seguintes mtodos da classe String: match(), replace() esearch(). Para obter mais informaes sobre esses mtodos, consulte Localizao de padres em sequncias de caracteres e substituio de subsequncias de caracteres na pgina 17.

Criao de uma ocorrncia de uma expresso regular

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior H duas maneiras de criar uma ocorrncia de expresso regular: Um modo usa caracteres de barra (/) para delinear a expresso regular; o outro usa o construtor new. Por exemplo, as expresses regulares a seguir so equivalentes:
var pattern1:RegExp = /bob/i; var pattern2:RegExp = new RegExp("bob", "i");

As barras delineiam um literal da expresso regular da mesma forma que as aspas delineiam um literal de string. A parte da expresso regular entre as barras define o padro. A expresso regular tambm pode incluir sinalizadores depois da barra delineadora final. Esses sinalizadores so considerados como parte da expresso regular, mas so separados do padro. Ao usar o construtor new, voc usa duas strings para definir a expresso regular. A primeira string define o padro e a segunda string define os sinalizadores como no exemplo a seguir:
var pattern2:RegExp = new RegExp("bob", "i");

Ao incluir uma barra em uma expresso regular que definida utilizando os delineadores de barra, voc deve preceder a barra com um caractere escape de barra invertida (\). Por exemplo, as expresses regulares a seguir correspondem ao padro 1/2:
var pattern:RegExp = /1\/2/;

Para incluir aspas em uma expresso regular que definida com o construtor new, voc deve adicionar uma caractere escape de barra invertida (\) antes das aspas (assim como faria ao definir qualquer literal String). Por exemplo, as expresses regulares a seguir correspondem ao padro eat at "joe's":
var pattern1:RegExp = new RegExp("eat at \"joe's\"", ""); var pattern2:RegExp = new RegExp('eat at "joe\'s"', "");

No use o caractere escape de barra invertida com aspas em expresses regulares que so definidas utilizando os delineadores de barra. Da mesma forma, no use o caractere escape com barras em expresses regulares que so definidas utilizando o construtor new. As expresses regulares a seguir so equivalentes e definem o padro 1/2 "joe's":
var pattern1:RegExp = /1\/2 "joe's"/; var pattern2:RegExp = new RegExp("1/2 \"joe's\"", ""); var pattern3:RegExp = new RegExp('1/2 "joe\'s"', '');

Em uma expresso regular definida com o construtor new, para usar uma metaseqncia que comece com o caractere de barra invertida (\) , como \d (que corresponde a qualquer dgito), digite duas vezes esse caractere de barra invertida:
var pattern:RegExp = new RegExp("\\d+", ""); // matches one or more digits

necessrio digitar o caractere de barra invertida duas vezes nesse caso, pois o primeiro parmetro do mtodo do construtor RegExp() uma string, e, em um literal de string, necessrio digitar um caractere de barra invertida duas vezes para que ele seja reconhecido como um nico caractere de barra invertida. As sees a seguir descrevem a sintaxe para definir os padres de expresses regulares. Para obter mais informaes sobre sinalizadores, consulte Sinalizadores e propriedades na pgina 87.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de expresses regulares

79

Caracteres, metacaracteres e metaseqncias

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A expresso regular mais simples aquela que corresponde a uma seqncia de caracteres, como no exemplo a seguir:
var pattern:RegExp = /hello/;

Entretanto, os seguintes caracteres, conhecidos como metacaracteres , tm significado especial nas expresses regulares:
^ $ \ . * + ? ( ) [ ] { } |

Por exemplo, a expresso regular a seguir corresponde letra A seguida por nenhuma ou mais ocorrncias da letra B (o metacaractere asterisco indica essa repetio), seguida pela letra C:
/AB*C/

Para incluir um metacaractere sem seu significado especial em um padro de expresso regular, voc deve usar o caractere escape de barra invertida (\). Por exemplo, a seguinte expresso regular corresponde letra A seguida pela letra B, seguida por um asterisco e pela letra C:
var pattern:RegExp = /AB\*C/;

Uma metaseqncia, como um metacaractere, tem um significado especial em uma expresso regular. Uma metaseqncia composta por mais de um caractere. As sees a seguir fornecem detalhes sobre o uso de metacaracteres e metaseqncias. Sobre metacaracteres A tabela a seguir resume os metacaracteres que voc pode usar em expresses regulares:
Metacaractere
^ (circunflexo)

Descrio Correspondente ao incio da string. Com o sinalizador m (multiline) definido, o circunflexo tambm corresponde ao incio de uma linha (consulte Sinalizadores e propriedades na pgina 87). Observe que, quando utilizado no incio de uma classe de caracteres, o circunflexo indica negao e no o incio de uma string. Para obter mais informaes, consulte Classes de caracteres na pgina 81. Correspondente ao fim da string. Com o conjunto de sinalizadores m (multiline), $ tambm corresponde posio antes de um caractere de nova linha (\n). Para obter mais informaes, consulte Sinalizadores e propriedades na pgina 87. Elimina o significado do metacaractere especial dos caracteres especiais. Alm disso, use o caractere de barra invertida se voc quiser utilizar o caractere de barra em um literal de expresso regular, como em /1\/2/ (para corresponder ao caractere 1, seguido pelo caractere de barra e pelo caractere 2).

$(sinal de dlar)

(barra invertida) \

. (ponto)

Corresponde a qualquer caractere nico. Um ponto corresponde a um caractere de nova linha (\n) apenas se o sinalizador s (dotall) est definido. Para obter mais informaes, consulte Sinalizadores e propriedades na pgina 87.

* (estrela)

Corresponde ao item anterior repetido nenhuma ou vrias vezes. Para obter mais informaes, consulte Quantificadores na pgina 82.

+ (adio)

Corresponde ao item anterior repetido uma ou vrias vezes. Para obter mais informaes, consulte Quantificadores na pgina 82.

? (ponto de interrogao)

Corresponde ao item anterior repetido nenhuma ou uma vezes. Para obter mais informaes, consulte Quantificadores na pgina 82.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de expresses regulares

80

Metacaractere
(e)

Descrio Define grupos dentro de uma expresso regular. Use os grupos para:

Confinar o escopo do alternador |: /(a|b|c)d/ Definir o escopo de um quantificador: /(walla.){1,2}/ Em referncias anteriores: Por exemplo, \1 na expresso regular a seguir corresponde quilo que correspondeu ao primeiro grupo entre parnteses do padro:
/(\w*) repetido: \1/

Para obter mais informaes, consulte Grupos na pgina 84.

[e]

Define uma classe de caracteres que define possveis correspondncias para um nico caractere:
/[aeiou]/ corresponde a qualquer um dos caracteres especificados.

Nas classes de caracteres, use o hfen (-) para designar um intervalo de caracteres:
/[A-Z0-9]/ corresponde s letras maisculas de A a Z ou de 0 a 9.

Nas classes de caracteres, insira uma barra invertida para eliminar os caracteres ] e -:
/[+\-]\d+/ corresponde a + ou- antes de um ou mais dgitos.

Nas classes de caracteres, outros caracteres - normalmente metacaracteres -, no tratados como caracteres normais (e no metacaracteres), sem a necessidade de usar uma barra invertida:
/[$]/ corresponde a $ou .

Para obter mais informaes, consulte Classes de caracteres na pgina 81.

| (pipe)

Utilizado para alternao, para corresponder parte do lado esquerdo ou do lado direito:
/abc|xyz/ corresponde a abc ouxyz.

Sobre metaseqncias As metaseqncias so seqncias de caracteres que tm significado especial em um padro de expresso regular. A tabela a seguir descreve essas metaseqncias:
Metaseqncia
{n} {n,}

Descrio Especifica um quantificador numrico ou intervalo de quantificador para o item anterior:

/A{27}/ corresponde ao caractereA repetido 27 vezes. /A{3,}/ corresponde ao caractereA repetido 3 vezes. /A{3,5}/ corresponde ao caractere A repetido de 3 a 5 vezes.

e
{n,n}

Para obter mais informaes, consulte Quantificadores na pgina 82.

\b

Corresponde posio entre um caractere de palavra e um diferente de palavra. Se o primeiro ou o ltimo caractere na string for um caractere de palavra, ele tambm corresponder ao incio ou ao fim da string. Corresponde posio entre dois caracteres de palavra. Tambm corresponde posio entre dois caracteres diferentes de palavra. Corresponde a um dgito decimal. Corresponde a qualquer caractere diferente de dgito. Corresponde ao caractere feed de formulrio. Corresponde ao caractere de nova linha.

\B

\d \D \f \n

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de expresses regulares

81

Metaseqncia
\r \s

Descrio Corresponde ao caractere de retorno. Corresponde a qualquer caractere de espao em branco (um caractere de espao, tabulao, nova linha ou retorno). Corresponde a qualquer caractere diferente de um caractere de espao em branco. Corresponde ao caractere de tabulao. Corresponde ao caractere Unicode com o cdigo de caractere especificado pelo nmero hexadecimal nn. Por exemplo, \u263a um caractere smiley. Corresponde ao caractere feed vertical. Corresponde a um caractere de palavra (AZ, az, 0-9 ou_). Observe que \w no corresponde a caracteres diferentes de ingls, como , ou . Corresponde a qualquer caractere diferente de um caractere de palavra. Corresponde ao caractere com o valor ASCII especificado, como definido pelo nmero hexadecimal nn.

\S \t \unnnn

\v \w

\W \\xnn

Classes de caracteres
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc usa as classes de caracteres para especificar uma lista de caracteres que correspondem a uma posio na expresso regular. Voc define as classes de caracteres com colchetes ( [ e ] ). Por exemplo, a expresso regular a seguir define uma classe de caracteres que corresponde a bag, beg, big, bog oubug:
/b[aeiou]g/

Seqncias de eliminao nas classes de caracteres A maioria dos metacaracteres e das metaseqncias que normalmente tem significados especiais em uma expresso regularno tem esses mesmos significados em uma classe de caractere. Por exemplo, em uma expresso regular, o asterisco usado para repetio, mas esse no o caso quando o asterisco aparece em uma classe de caracteres. A classe de caracteres a seguir corresponde ao asterisco literalmente, junto com qualquer outro caractere listado:
/[abc*123]/

Entretanto, os trs caracteres listados na tabela a seguir funcionam como metacaracteres, com significado especial, nas classes de caracteres:
Metacaractere
] -

Significado nas classes de caracteres Define o final de uma classe de caracteres. Define um intervalo de caracteres (consulte a prxima seo, Intervalos de caracteres nas classes de caracteres). Define metaseqncias e elimina o significao especial dos metacaracteres.

Para que qualquer um desses caracteres seja reconhecido como caracteres literais (sem o significado do metacaractere especial), voc deve preced-lo com o caractere escape de barra invertida. Por exemplo, a expresso regular a seguir inclui uma classe de caracteres que corresponde a qualquer um dos quatro smbolos ($, \, ] ou-):
/[$\\\]\-]/

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de expresses regulares

82

Alm dos metacaracteres que mantm seu significado especial, as metaseqncias a seguir funcionam como metaseqncias nas classes de caracteres:
Metaseqncia
\n \r \t \unnnn

Significado nas classes de caracteres Corresponde a um caractere de nova linha. Corresponde a um caractere de retorno. Corresponde a um caractere de tabulao. Corresponde ao caractere com o valor do ponto de cdigo Unicode especificado (como definido pelo nmero hexadecimal nnnn). Corresponde ao caractere com o valor ASCII especificado (como definido pelo nmero hexadecimal nn).

\\xnn

Outros metacaracteres e metaseqncias de expresses regulares so tratados como caracteres normais em uma classe de caracteres. Intervalos de caracteres nas classes de caracteres Use o hfen para especificar um intervalo de caracteres, como A-Z, a-z ou0-9. Esses caracteres devem constituir um intervalo vlido no conjunto de caracteres. Por exemplo, a classe de caracteres a seguir corresponde a qualquer um dos caracteres no intervalo de a-z ou qualquer dgito:
/[a-z0-9]/

Voc tambm pode usar o cdigo de caractere ASCII \\xnn para especificar um intervalo por valor ASCII. Por exemplo, a classe de caracteres a seguir corresponde a qualquer caractere de um conjunto de caracteres ASCII estendido (como e ):
\\x

Classes de caracteres negadas Quando voc usa um caractere circunflexo (^) no incio de uma classe de caracteres, ele nega aquela classe qualquer caractere no listado considerado uma correspondncia. A classe de caracteres a seguir corresponde a qualquer caractere exceto a uma letra minscula (az) ou um dgito:
/[^a-z0-9]/

Voc deve digitar o caractere circunflexo (^) no incio de uma classe de caracteres para indicar a negao. Caso contrrio, voc estar simplesmente adicionando o caractere circunflexo aos caracteres na classe de caracteres. Por exemplo, a classe de caracteres a seguir corresponde a qualquer um dos caracteres de smbolo, incluindo o circunflexo:
/[!.,#+*%$&^]/

Quantificadores
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc usa quantificadores para especificar repeties de caracteres ou seqncias nos padres, como se segue:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de expresses regulares

83

Metacaractere de quantificador
* (estrela) + (adio) ? (ponto de interrogao) {n} {n,}

Descrio

Corresponde ao item anterior repetido nenhuma ou vrias vezes. Corresponde ao item anterior repetido uma ou vrias vezes. Corresponde ao item anterior repetido nenhuma ou uma vezes. Especifica um quantificador numrico ou intervalo de quantificador para o item anterior:
/A{27}/ corresponde ao caractere A repetido 27 vezes. /A{3,}/ corresponde ao caractere A repetido 3 ou mais vezes. /A{3,5}/ corresponde ao caractere A repetido de 3 a 5 vezes.

e
{n,n}

Voc pode aplicar um quantificador a um nico caractere, a uma classe de caracteres ou a um grupo:

/a+/ corresponde ao caracterea repetido uma ou mais vezes. /\d+/ corresponde a um ou mais dgitos. /[abc]+/ corresponde a uma repetio de um ou mais caracteres, cada um a, b ouc. /(very, )*/ corresponde palavravery seguida por uma vrgula e um espao repetido nenhuma ou vrias vezes.

Voc pode usar quantificadores em grupos entre parnteses que tm quantificadores aplicados a eles. Por exemplo, o quantificador a seguir corresponde a strings como word e word-word-word:
/\w+(-\w+)*/

Por padro, as expresses regulares executam o que conhecido como correspondncia greedy. Qualquer subpadro na expresso regular (como .*) tenta corresponder o mximo possvel de caracteres na string antes de avanar para a prxima parte da expresso regular. Por exemplo, considere a seguinte expresso regular e string:
var pattern:RegExp = /<p>.*<\/p>/; str:String = "<p>Paragraph 1</p> <p>Paragraph 2</p>";

A expresso regular corresponde string inteira:

<p>Paragraph 1</p> <p>Paragraph 2</p>

Considere, entretanto, que voc deseja corresponder apenas um grupo <p>...</p>. possvel fazer isso da seguinte forma:
<p>Paragraph 1</p>

Adicione um ponto de interrogao (?) depois de qualquer quantificador para alter-lo para o que conhecido como quantificador lazy. Por exemplo, a seguinte expresso regular, que usa o quantificador lazy *? , corresponde a <p> seguido pelo nmero mnimo de caracteres possveis (lazy) e por </p>:
/<p>.*?<\/p>/

Lembre os seguintes pontos sobre quantificadores:

Os quantificadores {0} e {0,0} no excluem um item de uma correspondncia. No combine vrios quantificadores, como em /abc+*/. O dot (.) no estende linhas a menos que o sinalizador s (dotall) esteja definido, mesmo se for seguido por um
quantificador *. Por exemplo, considere o seguinte cdigo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de expresses regulares

84

var str:String = "<p>Test\n"; str += "Multiline</p>"; var re:RegExp = /<p>.*<\/p>/; trace(str.match(re)); // null; re = /<p>.*<\/p>/s; trace(str.match(re)); // output: <p>Test //

Multiline</p>

Para obter mais informaes, consulte Sinalizadores e propriedades na pgina 87.

Alternao
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Use o caractere | (pipe) em uma expresso regular para que o mecanismo de expresses regulares considere as alternativas para uma correspondncia. Por exemplo, as expresses regulares a seguir correspondem a qualquer uma das palavras cat, dog, pig, rat:
var pattern:RegExp = /cat|dog|pig|rat/;

Voc pode usar parnteses para definir grupos a fim de restringir o escopo do alternador |. A expresso regular a seguir corresponde a cat seguido por nap ounip:
var pattern:RegExp = /cat(nap|nip)/;

Para obter mais informaes, consulte Grupos na pgina 84. As duas expresses regulares a seguir, uma usando o alternador | e a outra usando uma classe de caracteres (definida com [ e ] ), so equivalentes:
/1|3|5|7|9/ /[13579]/

Para obter mais informaes, consulte Classes de caracteres na pgina 81.

Grupos
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc pode especificar um grupo em uma expresso regular utilizando parnteses, como se segue:
/class-(\d*)/

Um grupo uma subseo de um padro. Voc pode usar grupos para fazer as seguintes atividades:

Aplicar um quantificador a mais de um caractere. Delinear subpadres a serem aplicados com alternao (utilizando o caractere |). Capturar correspondncias de substring (por exemplo, utilizando \1 em uma expresso regular para corresponder
um grupo com correspondncia anterior ou utilizando $1 de modo semelhante no mtodo replace() da classe String). As sees a seguir fornecem detalhes sobre o uso de grupos.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de expresses regulares

85

Uso de grupos com quantificadores Se voc no usar um grupo, um quantificador se aplicar ao caractere ou classe de caracteres que o precede, como mostrado a seguir:
var pattern:RegExp = /ab*/ ; // matches the character a followed by // zero or more occurrences of the character b pattern = /a\d+/; // matches the character a followed by // one or more digits pattern = /a[123]{1,3}/; // matches the character a followed by // one to three occurrences of either 1, 2, or 3

Entretanto, voc pode usar um grupo para aplicar um quantificador a mais de um caractere ou classe de caracteres:
var pattern:RegExp = /(ab)*/; // matches zero or more occurrences of the character a // followed by the character b, such as ababab pattern = /(a\d)+/; // matches one or more occurrences of the character a followed by // a digit, such as a1a5a8a3 pattern = /(spam ){1,3}/; // matches 1 to 3 occurrences of the word spam followed by a space

Para obter mais informaes sobre quantificadores, consulte Quantificadores na pgina 82. Uso de grupos com o caractere alternador (|) Voc pode usar grupos para definir o grupo de caracteres aos quais deseja aplicar um caractere alternador (|), como se segue:
var pattern:RegExp = /cat|dog/; // matches cat or dog pattern = /ca(t|d)og/; // matches catog or cadog

Uso de grupos para capturar correspondncias de substrings Quando terminar de definir um grupo entre parnteses padro, poder se referir a ele posteriormente na expresso regular. Isso conhecido como referncia anterior, e essas classificaes de grupos so conhecidas como capturas de grupos. Por exemplo, na expresso regular a seguir, a seqncia \1 corresponde a qualquer substring que correspondeu captura do grupo entre parnteses:
var pattern:RegExp = /(\d+)-by-\1/; // matches the following: 48-by-48

Voc pode especificar at 99 dessas referncias anteriores em uma expresso regular digitando \1, \2, ... , \99. De modo semelhante, no mtodo replace() da classe String, voc pode usar $1$99 para inserir correspondncia de substring de grupos capturados na string de substituio:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de expresses regulares

86

var pattern:RegExp = /Hi, (\w+)\./; var str:String = "Hi, Bob."; trace(str.replace(pattern, "$1, hello.")); // output: Bob, hello.

Alm disso, se voc usar a captura de grupo, o mtodo exec() da classe RegExp e o mtodo match() da classe String retornaro substrings que correspondem captura de grupos:
var pattern:RegExp = /(\w+)@(\w+).(\w+)/; var str:String = "[email protected]"; trace(pattern.exec(str)); // [email protected],bob,example,com

Uso de grupos de no captura e grupos lookahead Um grupo de no captura aquele que usado para agrupamento apenas; ele no "coletado" e no corresponde a referncias anteriores numeradas. Use (?: e ) para definir grupos de no captura, como se segue:
var pattern = /(?:com|org|net);

Por exemplo, observe a diferena entre colocar (com|org) em uma captura versus um grupo de no captura (o mtodo exec() lista os grupos de captura depois da concluso da correspondncia):
var pattern:RegExp = /(\w+)@(\w+).(com|org)/; var str:String = "[email protected]"; trace(pattern.exec(str)); // [email protected],bob,example,com //noncapturing: var pattern:RegExp = /(\w+)@(\w+).(?:com|org)/; var str:String = "[email protected]"; trace(pattern.exec(str)); // [email protected],bob,example

Um tipo especial de grupo de no captura o grupo lookahead, composto por dois tipos: o grupo lookahead positivo e o grupo lookahead negativo. Use (?= e ) para definir um grupo lookahead positivo, que especifica que o subpadro no grupo deve corresponder posio. Entretanto, a poro da string que corresponde ao grupo lookahead positivo pode corresponder aos padres restantes na expresso regular. Por exemplo, como (?=e) um grupo lookahead positivo no cdigo a seguir, o caractere e ao qual ele corresponde pode ser correspondido por uma parte subseqente da expresso regular nesse caso, o grupo de captura, \w*):
var pattern:RegExp = /sh(?=e)(\w*)/i; var str:String = "Shelly sells seashells by the seashore"; trace(pattern.exec(str)); // Shelly,elly

Use (?! e ) para definir um grupo lookahead negativo, que especifica que o subpadro no grupo no deve corresponder posio. Por exemplo:
var pattern:RegExp = /sh(?!e)(\w*)/i; var str:String = "She sells seashells by the seashore"; trace(pattern.exec(str)); // shore,ore

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de expresses regulares

87

Uso de grupos nomeados Um grupo nomeado um tipo de grupo em uma expresso regular que tem um identificador nomeado. Use (?P<name> e ) para definir um grupo nomeado. Por exemplo, as expresses regulares a seguir incluem um grupo nomeado com os dgitos nomeados do identificador:
var pattern = /[a-z]+(?P<digits>\d+)[a-z]+/;

Quando voc use o mtodo exec(), uma correspondncia de grupo nomeado adicionada como uma propriedade da matriz result:
var myPattern:RegExp = /([a-z]+)(?P<digits>\d+)[a-z]+/; var str:String = "a123bcd"; var result:Array = myPattern.exec(str); trace(result.digits); // 123

Aqui est outro exemplo, que usa dois grupos nomeados, com os identificadores name e dom:
var emailPattern:RegExp = /(?P<name>(\w|[_.\-])+)@(?P<dom>((\w|-)+))+\.\w{2,4}+/; var address:String = "[email protected]"; var result:Array = emailPattern.exec(address); trace(result.name); // bob trace(result.dom); // example

Nota: Os grupos nomeados no fazem parte da especificao de linguagem ECMAScript. Eles so um recurso adicionado no ActionScript 3.0.

Sinalizadores e propriedades
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A tabela a seguir lista os cinco sinalizadores que voc pode definir para expresses regulares: Cada sinalizador pode ser acessado como uma propriedade do objeto da expresso regular.
Sinalizador Propriedade
g i global ignoreCase

Descrio Corresponde a mais de uma correspondncia. Correspondncia que no faz distino entre maisculas e minsculas. Aplica-se aos caracteres AZ e az, mas no a caracteres estendidos como e . Com esse sinalizador definido, $ e ^ pode corresponder ao incio e ao fim de uma linha, respectivamente. Com esse sinalizador definido, . (ponto) pode corresponder ao caractere de nova linha (\n). Permite expresses regulares estendidas. Voc pode digitar espaos na expresso regular, que sero ignorados como parte do padro. Isso permite digitar cdigo de expresso regular de modo mais legvel.

multiline

s x

dotall extended

Observe que essas propriedade so somente leitura. Voc pode definir os sinalizadores (g, i, m, s, x) quando definir uma varivel de expresso regular, como se segue:
var re:RegExp = /abc/gimsx;

Entretanto, no possvel definir diretamente as propriedades nomeadas. Por exemplo, o cdigo a seguir resulta em um erro:
var re:RegExp = /abc/; re.global = true; // This generates an error.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de expresses regulares

88

Por padro, a menos que voc os especifique na declarao de expresso regular, os sinalizadores no sero definidos e as propriedades de correspondncia tambm so definidas como false. De modo adicional, h duas outras propriedades de uma expresso regular:

A propriedade lastIndex especifica a posio de ndice na string para a prxima chamada do mtodo exec() or
test() de uma expresso regular.

A propriedade source especifica a string que define a parte padro da expresso regular.
O sinalizador g (global) Quando o sinalizador g (global) no includo, uma expresso regular tem no mais do que uma correspondncia. Por exemplo, com o sinalizador g no incluso na expresso regular, o mtodo String.match() retorna somente uma substring de correspondncia:
var str:String = "she sells seashells by the seashore."; var pattern:RegExp = /sh\w*/; trace(str.match(pattern)) // output: she

Quando o sinalizador g definido, o mtodo Sting.match() retorna vrias correspondncias, como se segue:
var str:String = "she sells seashells by the seashore."; var pattern:RegExp = /sh\w*/g; // The same pattern, but this time the g flag IS set. trace(str.match(pattern)); // output: she,shells,shore

O sinalizador i (ignoreCase) Por padro, as correspondncias de expresses regulares fazem distino entre maisculas e minsculas. Quando voc define o sinalizador i (ignoreCase), a distino entre maisculas e minsculas ignorada. Por exemplo, o s minsculo na expresso regular no corresponde ao S maisculo, o primeiro caractere da string:
var str:String = "She sells seashells by the seashore."; trace(str.search(/sh/)); // output: 13 -- Not the first character

Com o sinalizador i definido, entretanto, a expresso regular corresponde ao S maisculo:

var str:String = "She sells seashells by the seashore."; trace(str.search(/sh/i)); // output: 0

O sinalizador i ignora a distino entre maisculas e minsculas somente para os caracteres AZ e az, mas no para caracteres estendidos como e . O sinalizador m (multiline) Se o sinalizador m (multiline) no estiver definido, ^ corresponde ao incio da string e $ corresponde ao fim da string. Se o sinalizador m estiver definido, esses caracteres correspondero ao incio e ao fim de uma linha, respectivamente. Considere a seguinte string, que inclui um caractere de nova linha:
var str:String = "Test\n"; str += "Multiline"; trace(str.match(/^\w*/g)); // Match a word at the beginning of the string.

Mesmo que o sinalizador g (global) esteja definido na expresso regular, o mtodo match() corresponde a apenas uma substring, pois h apenas uma correspondncia para ^ o incio da string. A sada :
Test

Aqui est o mesmo cdigo com o sinalizador m definido:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de expresses regulares

89

var str:String = "Test\n"; str += "Multiline"; trace(str.match(/^\w*/gm)); // Match a word at the beginning of lines.

Neste momento, a sada inclui as palavras no incio das linhas:

Test,Multiline

Observe que apenas o caractere \n sinaliza o fim de uma linha. Os caracteres a seguir no:

Caractere de retorno (\r) Caractere Unicode separador de linha (\u2028) Caractere Unicode separador de pargrafo (\u2029)
O sinalizador s (dotall) Se o sinalizador s (dotall ou dot all) no estiver definido, um ponto (.) em um padro de expresso regular no corresponde a um caractere de nova linha (\n). Portanto para o exemplo a seguir, no h nenhuma correspondncia:
var str:String = "<p>Test\n"; str += "Multiline</p>"; var re:RegExp = /<p>.*?<\/p>/; trace(str.match(re));

Entretanto, se o sinalizador s estiver definido, o ponto corresponder ao caractere de nova linha:

var str:String = "<p>Test\n"; str += "Multiline</p>"; var re:RegExp = /<p>.*?<\/p>/s; trace(str.match(re));

Nesse caso, a correspondncia a substring inteira dentro das tags <p>, incluindo o caractere de nova linha:
<p>Test Multiline</p>

O sinalizador x (extended) As expresses regulares podem ser difceis de ler, especialmente quando incluem muitos metasmbolos e metaseqncias. Por exemplo:
/<p(>|(\s*[^>]*>)).*?<\/p>/gi

Quando voc usa o sinalizador x (extended) em uma expresso regular, qualquer espao em branco digitado no padro ser ignorado. Por exemplo, a expresso regular a seguir idntica ao exemplo anterior:
/ <p (> | (\s* [^>]* >)) .*? <\/p> /gix

Se o sinalizador x estiver definido e voc quiser uma correspondncia com o caractere de espao em branco, preceda o espao em branco com uma barra invertida. Por exemplo, as duas expresses regulares a seguir so equivalentes:
/foo bar/ /foo \ bar/x

A propriedade lastIndex A propriedade lastIndex especifica a posio de ndice na string no qual a prxima pesquisa ser iniciada. Essa propriedade afeta os mtodos exec() e test() chamados em uma expresso regular que tem o sinalizador g definido como true. Por exemplo, considere o seguinte cdigo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de expresses regulares

90

var pattern:RegExp = /p\w*/gi; var str:String = "Pedro Piper picked a peck of pickled peppers."; trace(pattern.lastIndex); var result:Object = pattern.exec(str); while (result != null) { trace(pattern.lastIndex); result = pattern.exec(str); }

A propriedade lastIndex definida como 0 por padro (para iniciar a pesquisa no incio da string). Depois de cada correspondncia, ela definida para a posio de ndice seguindo a correspondncia. Portanto, a sada para o cdigo precedente a seguinte:
0 5 11 18 25 36 44

Se o sinalizador global estiver definido como false, os mtodos exec() e test() no usam nem definem a propriedade lastIndex. Os mtodos match(), replace() e search() da classe String iniciam todas as pesquisas no incio da string, independentemente da configurao da propriedade lastIndex da expresso regular utilizada na chamada do mtodo. (Contudo, o mtodo match() define lastIndex como 0.) Voc pode definir a propriedade lastIndex para ajustar a posio inicial na string para a correspondncia da expresso regular. A propriedade source A propriedade source especifica a string que define a parte padro de uma expresso regular. Por exemplo:
var pattern:RegExp = /foo/gi; trace(pattern.source); // foo

Mtodos para usar expresses regulares com strings

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe RegExp inclui dois mtodos: exec() etest(). Alm dos mtodos exec() e test() da classe RegExp, a classe String inclui os seguintes mtodos que permitem corresponder expresses regulares em strings: match(), replace(), search() esplice().

O mtodo test()
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O mtodo test() da classe RegExp verifica simplesmente a string fornecida para ver se ela contm uma correspondncia para a expresso regular, como mostra o exemplo a seguir:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de expresses regulares

91

var pattern:RegExp = /Class-\w/; var str = "Class-A"; trace(pattern.test(str)); // output: true

O mtodo exec()
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O mtodo exec() da classe RegExp verifica a string fornecida quanto a uma correspondncia da expresso regular e retorna uma matriz com o seguinte:

A substring de correspondncia Correspondncia de substring para qualquer grupo entre parnteses na expresso regular
A matriz tambm inclui uma propriedade index, indicando a posio de ndice do incio da correspondncia de substring. Por exemplo, considere o seguinte cdigo:
var pattern:RegExp = /\d{3}\-\d{3}-\d{4}/; //U.S phone number var str:String = "phone: 415-555-1212"; var result:Array = pattern.exec(str); trace(result.index, " - ", result); // 7-415-555-1212

Use o mtodo exec() vrias vezes para corresponder vrias substrings quando o sinalizador g (global) est definido para uma expresso regular:
var pattern:RegExp = /\w*sh\w*/gi; var str:String = "She sells seashells by the seashore"; var result:Array = pattern.exec(str); while (result != null) { trace(result.index, "\t", pattern.lastIndex, "\t", result); result = pattern.exec(str); } //output: // 0 3 She // 10 19 seashells // 27 35 seashore

Mtodos String que usam parmetros RegExp

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os seguintes mtodos da classe String usam as expresses regulares como parmetros: match(), replace(), search() esplit(). Para obter mais informaes sobre esses mtodos, consulte Localizao de padres em sequncias de caracteres e substituio de subsequncias de caracteres na pgina 17.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de expresses regulares

92

Exemplo de expresses regulares: um analisador Wiki

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Esse exemplo simples de converso de texto Wiki ilustra vrios usos para expresses regulares:

Converso de linhas de texto que correspondem o padro Wiki de origem s strings de sada HTML apropriadas. Uso de uma expresso regular para converter padres de URL para tags de hiperlinks HTML <a>. Uso de uma expresso regular para converter strings com dlares norte-americanos (como "$9,95") em strings
com euros (como "8,24 "). Para obter os arquivos de aplicativo deste exemplo, consulte www.adobe.com/go/learn_programmingAS3samples_flash_br. Os arquivos de aplicativo WikiEditor podem ser encontrados na pasta Samples/WikiEditor. O aplicativo consiste nos seguintes arquivos:
Arquivo WikiEditor.mxml ou WikiEditor.fla com/example/programmingas3/regExpExamples/WikiParser.as Uma classe que inclui mtodos que usam expresses regulares para converter padres de texto de entrada Wiki em sada HTML equivalente. Uma classe que inclui mtodos que usam expresses regulares para converter strings URL para tags de hiperlinks HTML <a>. Uma classe que inclui mtodos que usam expresses regulares para converter strings de dlar americano em strings de euro. Descrio O arquivo principal do aplicativo no Flash (FLA) ou no Flex (MXML).

com/example/programmingas3/regExpExamples/URLParser.as

com/example/programmingas3/regExpExamples/CurrencyConverter.as

Definio da classe WikiParser

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe WikiParser inclui mtodos que convertem texto de entrada Wiki em sada HTML equivalente. Esse no um aplicativo de converso Wiki muito robusto, mas ele ilustra alguns bons usos de expresses regulares para correspondncia de padro e converso de strings. A funo de construtor, junto com o mtodo setWikiData(), simplesmente inicializa uma string de amostra do texto de entrada Wiki, como se segue:
public function WikiParser() { wikiData = setWikiData(); }

Quando o usurio clica no boto Testar no aplicativo de amostra, o aplicativo chama o mtodo parseWikiString() do objeto WikiParser. Esse mtodo chama vrios outros mtodos, que por sua vez montam a string HTML resultante.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de expresses regulares

93

public function parseWikiString(wikiString:String):String { var result:String = parseBold(wikiString); result = parseItalic(result); result = linesToParagraphs(result); result = parseBullets(result); return result; }

Cada um dos mtodos chamados parseBold(), parseItalic(), linesToParagraphs() e parseBullets() usa o mtodo replace() da string para substituir os padres de correspondncia, definidos por uma expresso regular, para transformar o texto de entrada Wiki em texto no formato HTML. Converso de padres negrito e itlico O mtodo parseBold() procura padro de texto negrito Wiki (como '''foo''') e o transforma em seu equivalente em HTML (como <b>foo</b>), como se segue:
private function parseBold(input:String):String { var pattern:RegExp = /'''(.*?)'''/g; return input.replace(pattern, "<b>$1</b>"); }

Observe que a parte (.?*) de uma presso regular corresponde a vrios caracteres (*) entre os dois padres de definio'''. O quantificador ? torna a correspondncia no greedy, para que uma string como '''aaa''' bbb '''ccc''', a primeira string correspondida ser '''aaa''' e no a string inteira (que comea e termina com o padro '''). Os parnteses na expresso regular definem um grupo de captura, e o mtodo replace() se refere a esse grupo utilizando o cdigo $1 na string de substituio. O sinalizador g (global) na expresso regular garante que o mtodo replace() substitua todas as correspondncias na string (no simplesmente a primeira). O mtodo parseItalic() funciona de forma semelhante ao mtodo parseBold(), exceto pelo fato de ele verificar dois apstrofes ('') como o delimitador para texto itlico (no trs):
private function parseItalic(input:String):String { var pattern:RegExp = /''(.*?)''/g; return input.replace(pattern, "<i>$1</i>"); }

Converso de padres de bullet Como mostra o exemplo a seguir, o mtodo parseBullet() procura o padro de linha de bullet Wiki (como * foo) e o transforma em seu equivalente HTML (como <li>foo</li>):
private function parseBullets(input:String):String { var pattern:RegExp = /^\*(.*)/gm; return input.replace(pattern, "<li>$1</li>"); }

O smbolo ^ no incio de uma expresso regular corresponde ao incio de uma linha. O sinalizador m (multiline) na expresso regular faz com que essa expresso corresponda o smbolo ^ ao incio de uma linha, e no simplesmente ao incio da string. O padro \* corresponde a um caractere asterisco (a barra invertida usada para sinalizar um asterisco literal em vez de um quantificador *).

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de expresses regulares

94

Os parnteses na expresso regular definem um grupo de captura, e o mtodo replace() se refere a esse grupo utilizando o cdigo $1 na string de substituio. O sinalizador g (global) na expresso regular garante que o mtodo replace() substitua todas as correspondncias na string (no simplesmente a primeira). Converso de padres Wiki de pargrafos O mtodo linesToParagraphs() converte cada linha na string Wiki de entrada em uma tag de pargrafo HTML <p>. Essas linhas no mtodo retiram linhas vazias da string Wiki de entrada:
var pattern:RegExp = /^$/gm; var result:String = input.replace(pattern, "");

Os smbolos ^ e $ de uma expresso regular correspondem ao incio e ao fim de uma linha. O sinalizador m (multiline) na expresso regular faz com que essa expresso corresponda o smbolo ^ ao incio de uma linha, e no simplesmente ao incio da string. O mtodo replace() substitui todas as substrings correspondentes (linhas vazias) por uma string vazia (""). O sinalizador g (global) na expresso regular garante que o mtodo replace() substitua todas as correspondncias na string (no simplesmente a primeira).

Converso de URLs para tags HTML <a>

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Quando o usurio clica no boto Testar no aplicativo de amostra, se ele marcou a caixa de seleo urlToATag, o aplicativo chama o mtodo esttico URLParser.urlToATag() para converter as strings URL da string Wiki de entrada em tags HTML <a>.
var var var var var protocol:String = "((?:http|ftp)://)"; urlPart:String = "([a-z0-9_-]+\.[a-z0-9_-]+)"; optionalUrlPart:String = "(\.[a-z0-9_-]*)"; urlPattern:RegExp = new RegExp(protocol + urlPart + optionalUrlPart, "ig"); result:String = input.replace(urlPattern, "<a href='$1$2$3'><u>$1$2$3</u></a>");

A funo do construtor RegExp() usada para montar uma expresso regular (urlPattern) a partir de inmeras partes constituintes. Essas partes constituintes so cada string que define parte do padro da expresso regular. A primeira parte do padro da expresso regular, definida pela string protocol, define um protocolo de URL: http:// ou ftp://. Os parnteses definem um grupo de no captura, indicado pelo smbolo ?. Isso significa que os parnteses so usados simplesmente para definir um grupo para o padro de alternao |; o grupo no corresponder a cdigos de referncia anterior ($1, $2, $3) na string de substituio do mtodo replace(). As outras partes constituintes da expresso regular usam grupos de captura (indicado por parnteses no padro), que so usados nos cdigos de referncia anterior ($1, $2, $3) na string de substituio do mtodo replace(). A parte do padro definido pela string urlPart corresponde a pelo menos um destes caracteres: a-z, 0-9, _ ou-. O quantificador + indica que pelo menos um caractere tem correspondncia. \. indica um caractere de ponto (.) exigido. E o restante corresponde a outra string de pelo menos um destes caracteres: a-z, 0-9, _ ou-. A parte do padro definido pela string optionalUrlPart corresponde a nenhum ou mais destes caracteres: um ponto (.) seguido por qualquer nmero de caracteres alfanumricos (incluindo _ e -). O quantificador * indica que nenhum ou mais caracteres tm correspondncia. A chamada do mtodo replace() aplica a expresso regular e monta a string HTML de substituio, utilizando referncias anteriores.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de expresses regulares

95

O mtodo urlToATag() chama o mtodo emailToATag(), que usa tcnicas semelhantes para substituir padres de email por string de hiperlinks HTML <a>. As expresses regulares utilizadas para corresponder HTTP, FTP e URLs de email nesse arquivo de amostra so muito simples, com o objetivo de exemplificao; h expresses regulares muito mais complicadas para correspondncia com esses URLs.

Converso de strings de dlar americano para strings de euro

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Quando o usurio clica no boto Testar do aplicativo de exemplo, se ele marcou a caixa de seleo dollarToEuro, o aplicativo chama o mtodo esttico CurrencyConverter.usdToEuro() para converter as strings com dlares norteamericanos (como "$9,95") em strings com euros (como "8,24 "), da seguinte maneira:
var usdPrice:RegExp = /\$([\d,]+.\d+)+/g; return input.replace(usdPrice, usdStrToEuroStr);

A primeira linha define um padro simples para correspondncia de strings de dlar americano. Observe que o caractere $ precedido por um caractere escape de barra invertida (\). O mtodo replace() usa a expresso regular como o correspondente padro e chama a funo usdStrToEuroStr() para determinar a string de substituio (um valor em euros). Quando um nome de funo for utilizado como o parmetro secundrio do mtodo replace(), o seguinte ser transmitido como parmetros para a funo chamada:

A parte correspondente da string. Qualquer correspondncia de grupo em parnteses capturado. O nmero de argumentos transmitidos dessa
maneira ir variar dependendo do nmero de correspondncias de grupo entre parnteses capturado. possvel determinar o nmero de correspondncias de grupo entre parnteses capturado, verificando arguments.length -3 no cdigo da funo.

A posio de ndice na string em que a correspondncia comea. A string completa.

O mtodo usdStrToEuroStr() converte padres de string de dlar americano para string de euro, como se segue:
private function usdToEuro(...args):String { var usd:String = args[1]; usd = usd.replace(",", ""); var exchangeRate:Number = 0.828017; var euro:Number = Number(usd) * exchangeRate; trace(usd, Number(usd), euro); const euroSymbol:String = String.fromCharCode(8364); // return euro.toFixed(2) + " " + euroSymbol; }

Observe que args[1] representa o grupo entre parnteses capturado, correspondido pela expresso regular usdPrice. Essa uma parte numrica da string de dlar americano: isto , a quantidade de dlar sem o sinal $. O mtodo aplica uma converso de taxa de cmbio e retorna a string resultante (com o smbolo direita em vez do smbolo $ esquerda).

ltima atualizao em 29/3/2011

96

Captulo 6: Trabalho com XML

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O ActionScript 3.0 inclui um grupo de classes com base na especificao ECMAScript para XML (E4X) (ECMA-357 edio 2). Essas classes incluem recursos avanados e fceis de usar para trabalhar com dados XML. Usando o E4X, voc poder desenvolver cdigos com dados XML mais rpido do que com as tcnicas de programao anteriores. Alm disso, o cdigo produzido ser mais fcil de ler.

Mais tpicos da Ajuda

Classe XML Processando XML com o tutorial E4X no mozilla Especificao ECMA-357

Noes bsicas sobre XML

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior XML uma maneira padro de representar informaes estruturadas com a qual os computadores devem trabalhar com facilidade e que deve ser relativamente fcil para as pessoas gravarem e entenderem. XML uma abreviao de eXtensible Markup Language (Linguagem de markup extensvel). O padro XML est disponvel em www.w3.org/XML/. O XML oferece um modo prtico e padro de classificar dados, facilitando a leitura, o acesso e a manipulao. O XML usa estruturas de rvore e de tag similares s do HTML. Veja um exemplo simples de dados XML:
<song> <title>What you know?</title> <artist>Steve and the flubberblubs</artist> <year>1989</year> <lastplayed>2006-10-17-08:31</lastplayed> </song>

Os dados XML tambm podem ser mais complexos, com tags aninhadas em outras tags, bem como em atributos e outros componentes estruturais. Veja um exemplo mais complexo de dados XML:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com XML

97

<album> <title>Questions, unanswered</title> <artist>Steve and the flubberblubs</artist> <year>1989</year> <tracks> <song tracknumber="1" length="4:05"> <title>What do you know?</title> <artist>Steve and the flubberblubs</artist> <lastplayed>2006-10-17-08:31</lastplayed> </song> <song tracknumber="2" length="3:45"> <title>Who do you know?</title> <artist>Steve and the flubberblubs</artist> <lastplayed>2006-10-17-08:35</lastplayed> </song> <song tracknumber="3" length="5:14"> <title>When do you know?</title> <artist>Steve and the flubberblubs</artist> <lastplayed>2006-10-17-08:39</lastplayed> </song> <song tracknumber="4" length="4:19"> <title>Do you know?</title> <artist>Steve and the flubberblubs</artist> <lastplayed>2006-10-17-08:44</lastplayed> </song> </tracks> </album>

Observe que esse documento XML contm outras estruturas XML completas (como as tags song e seus filhos). Ele tambm demonstra outras estruturas XML como atributos (tracknumber e length nas tags song) e tags que contm outras tags em vez de dados (como a tag tracks). Como comear a usar o XML Se voc tiver pouca ou nenhuma experincia com XML, veja uma breve descrio dos aspectos mais comuns dos dados XML. Os dados XML so gravados em texto sem formatao, com uma sintaxe especfica para organizar as informaes em um formato estruturado. Em geral, um nico conjunto de dados XML conhecido como documento XML. No formato XML, os dados so organizados em elementos (que podem ser itens de dados nicos ou contineres de outros elementos) usando uma estrutura hierrquica. Cada documento XML tem um nico elemento como item de nvel superior ou principal; dentro desse elemento raiz, pode existir uma nica informao, embora provavelmente haja outros elementos que, por sua vez, contm outros elementos e assim por diante. Por exemplo, esse documento XML contm as informaes sobre um lbum de msica:
<song tracknumber="1" length="4:05"> <title>What do you know?</title> <artist>Steve and the flubberblubs</artist> <mood>Happy</mood> <lastplayed>2006-10-17-08:31</lastplayed> </song>

Cada elemento diferenciado por um conjunto de tags o nome do elemento entre os sinais de menor que e maior que. A tag de abertura, que indica o incio do elemento, tem o nome do elemento:
<title>

A tag de fechamento, que marca o final do elemento, tem uma barra antes do nome do elemento:
</title>

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com XML

98

Se um elemento no tiver nenhum contedo, poder ser gravado como um elemento vazio (s vezes chamado de elemento de fechamento automtico). Em XML, esse elemento:
<lastplayed/>

idntico a este elemento:

<lastplayed></lastplayed>

Alm do contedo do elemento contido entre as tags de abertura e fechamento, um elemento tambm pode incluir outros valores, conhecidos como atributos, definidos na tag de abertura. Por exemplo, este elemento XML define um nico atributo chamado length, com o valor "4:19" :
<song length="4:19"></song>

Cada elemento XML tem contedo, que pode ser um nico valor, um ou mais elementos XML ou nada (para um elemento vazio). Mais informaes sobre XML Para saber mais sobre como trabalhar com XML, existem diversos outros livros e recursos, incluindo estes sites:

Tutorial W3Schools XML: http://w3schools.com/xml/ Tutoriais da XMLpitstop, listas de discusso e muito mais: http://xmlpitstop.com/
Classes do ActionScript para trabalhar com XML O ActionScript 3.0 inclui vrias classes que so usadas para trabalhar com informaes estruturadas como XML. As duas classes principais so as seguintes:

XML: representa um nico elemento XML, que pode ser um documento XML com vrios filhos ou um elemento
com um nico valor em um documento.

XMLList: representa um conjunto de elementos XML. Um objeto XMLList usado quando existem vrios
elementos XML que so "irmos" (no mesmo nvel e contidos pelo mesmo pai na hierarquia de documento XML). Por exemplo, uma ocorrncia de XMLList seria o modo mais fcil de trabalhar com este conjunto de elementos XML (supostamente contidos em um documento XML):
<artist type="composer">Fred Wilson</artist> <artist type="conductor">James Schmidt</artist> <artist type="soloist">Susan Harriet Thurndon</artist>

Para usos mais avanados que envolvem namespaces XML, o ActionScript tambm inclui as classes Namespace e QName. Para obter mais informaes, consulte Uso de namespaces XML na pgina 111. Alm das classes internas para trabalhar com XML, o ActionScript 3.0 tambm inclui vrios operadores que fornecem recursos especficos para acessar e manipular dados XML. Essa abordagem de trabalhar com XML usando essas classes e operadores conhecida como ECMAScript para XML (E4X), conforme definido pela especificao ECMA-357 edio 2. Conceitos e termos importantes A lista de referncia a seguir contm termos importantes que voc vai encontrar ao programar as rotinas de tratamento de XML:
Elemento Um nico item em um documento XML, identificado como o contedo contido entre uma tag inicial e uma

tag final (incluindo as tags). Os elementos XML podem conter dados de texto ou outros elementos, ou podem ser vazios.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com XML

99

Elemento vazio Um elemento XML que no contm nenhum elemento filho. Os elementos vazios geralmente so gravados como tags de fechamento (como <element/>). Documento Uma nica estrutura XML. Um documento XML pode conter qualquer nmero de elementos (ou ser

constitudo por apenas um nico elemento vazio); no entanto, um documento XML deve ter um elemento de nvel superior que contm todos os outros elementos do documento.
N Outro nome para um elemento XML. Atributo Um valor nomeado associado a um elemento que est gravado na tag de abertura do elemento no formato
attributename="value", em vez de estar gravado como um elemento filho separado aninhado no elemento.

A abordagem E4X em relao ao processamento de XML

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A especificao ECMAScript para XML define um conjunto de classes e recursos para trabalhar com dados XML. Em conjunto, essas classes e recursos so conhecidos como E4X. O ActionScript 3.0 inclui as seguintes classes E4X: XML, XMLList, QName e Namespace. Os mtodos, as propriedades e os operadores das classes E4X foram desenvolvidos com os seguintes objetivos:

Simplicidade - Sempre que possvel, o E4X facilita a gravao e a compreenso do cdigo para trabalhar com dados XML. Consistncia - Os mtodos e princpios por trs do E4X so consistentes internamente e com outras partes do
ActionScript.

Familiaridade Voc manipula os dados XML com operadores conhecidos, como o operador de ponto (.).
Nota: H uma classe XML diferente no ActionScript 2.0. No ActionScript 3.0, essa classe foi renomeada como XMLDocument, de modo que no entra em conflito com a classe XML do ActionScript 3.0 que faz parte do E4X. No ActionScript 3.0, as classes herdadas (XMLDocument, XMLNode, XMLParser e XMLTag) so includas no pacote flash.xml principalmente para dar suporte a verses anteriores. As novas classes do E4X so classes bsicas; no necessrio importar um pacote para utiliz-las. Veja os detalhes das classes antigas do ActionScript 2.0 XML em flash.xml packagena Referncia do ActionScript 3.0 para a plataforma Adobe Flash. Veja um exemplo de manipulao dos dados com E4X:
var myXML:XML = <order> <item id='1'> <menuName>burger</menuName> <price>3.95</price> </item> <item id='2'> <menuName>fries</menuName> <price>1.45</price> </item> </order>

Normalmente, seu aplicativo carregar dados XML a partir de uma fonte externa, como um servio da Web ou um feed RSS. No entanto, para fins de clareza, os exemplos de cdigo fornecidos aqui atribuem dados XML como literais. Como mostra o cdigo a seguir, o E4X inclui alguns operadores intuitivos, como os operadores de ponto (.) e de identificador de atributo (@), para acessar propriedades e atributos no XML:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com XML

100

trace(myXML.item[0].menuName); // Output: burger trace(myXML.item.(@id==2).menuName); // Output: fries trace(myXML.item.(menuName=="burger").price); // Output: 3.95

Use o mtodo appendChild() para atribuir um novo n filho ao XML, como mostra o snippet a seguir:
var newItem:XML = <item id="3"> <menuName>medium cola</menuName> <price>1.25</price> </item> myXML.appendChild(newItem);

Use os operadores @ e . no s para ler, mas tambm para atribuir dados do seguinte modo:
myXML.item[0].menuName="regular burger"; myXML.item[1].menuName="small fries"; myXML.item[2].menuName="medium cola"; myXML.item.(menuName=="regular burger").@quantity = "2"; myXML.item.(menuName=="small fries").@quantity = "2"; myXML.item.(menuName=="medium cola").@quantity = "2";

Use um loop for para percorrer os ns do XML do seguinte modo:

var total:Number = 0; for each (var property:XML in myXML.item) { var q:int = Number(property.@quantity); var p:Number = Number(property.price); var itemTotal:Number = q * p; total += itemTotal; trace(q + " " + property.menuName + " $" + itemTotal.toFixed(2)) } trace("Total: $", total.toFixed(2));

Objetos XML
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Um objeto XML pode representar um elemento, atributo, comentrios, instruo de processamento ou elemento de texto XML. Um objeto XML pode ter contedo simples ou contedo complexo. Um objeto XML que tem ns filho tem contedo complexo. Um objeto XML ter contedo simples se contiver um dos seguintes itens: um atributo, um comentrio, uma instruo de processamento ou um n de texto. Por exemplo, o objeto XML a seguir tem contedo complexo, incluindo um comentrio e uma instruo de processamento:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com XML

101

XML.ignoreComments = false; XML.ignoreProcessingInstructions = false; var x1:XML = <order> <!--This is a comment. --> <?PROC_INSTR sample ?> <item id='1'> <menuName>burger</menuName> <price>3.95</price> </item> <item id='2'> <menuName>fries</menuName> <price>1.45</price> </item> </order>

Como mostra o exemplo a seguir, agora voc pode usar os mtodos comments() e processingInstructions() para criar novos objetos XML, um comentrio e uma instruo de processamento:
var x2:XML = x1.comments()[0]; var x3:XML = x1.processingInstructions()[0];

propriedades XML
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe XML tem cinco propriedades estticas:

As propriedades ignoreComments e ignoreProcessingInstructions determinam se comentrios ou instrues

de processamento devem ser ignorados quando o objeto XML analisado.

A propriedade ignoreWhitespace determina se os caracteres de espao em branco devem ser ignorados em tags
de elemento e expresses incorporadas que so separadas somente por caracteres de espao em branco.

As propriedades prettyIndenteprettyPrinting so usadas para formatar o texto que retornado pelos mtodos
toString() e toXMLString() da classe XML.

Veja os detalhes dessas propriedades na Referncia do ActionScript 3.0 para a plataforma Adobe Flash.

Mtodos XML
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os mtodos a seguir permitem trabalhar com a estrutura hierrquica dos objetos XML:

appendChild() child() childIndex() children() descendants() elements() insertChildAfter() insertChildBefore()

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com XML

102

parent() prependChild()

Os mtodos a seguir permitem trabalhar com atributos de objetos XML:

attribute() attributes()

Os mtodos a seguir permitem trabalhar com propriedades de objetos XML:

hasOwnProperty() propertyIsEnumerable() replace() setChildren()

Os mtodos a seguir permitem trabalhar com nomes e namespaces qualificados:

addNamespace() inScopeNamespaces() localName() name() namespace() namespaceDeclarations() removeNamespace() setLocalName() setName() setNamespace()

Os mtodos a seguir permitem trabalhar e determinar tipos especficos de contedo XML:

comments() hasComplexContent() hasSimpleContent() nodeKind() processingInstructions() texto()

Os mtodos a seguir servem para converso em strings e formatao de objetos XML:

defaultSettings() setSettings() settings() normalize() toString() toXMLString()

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com XML

103

Existem alguns mtodos adicionais:

contains() copiar() valueOf() length()

Veja a documentao desses mtodos na Referncia do ActionScript 3.0 para a plataforma Adobe Flash.

Objetos XMLList
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Uma ocorrncia de XMLList representa uma coleo arbitrria de objetos XML. Ela contm documentos XML completos, fragmentos de XML ou os resultados de uma consulta XML. Os mtodos a seguir permitem trabalhar com a estrutura hierrquica dos objetos XMLList:

child() children() descendants() elements() parent()

Os mtodos a seguir permitem trabalhar com atributos de objetos XMLList:

attribute() attributes()

Os mtodos a seguir permitem trabalhar com propriedades de XMLList:

hasOwnProperty() propertyIsEnumerable()

Os mtodos a seguir permitem trabalhar e determinar tipos especficos de contedo XML:

comments() hasComplexContent() hasSimpleContent() processingInstructions() texto()

Os mtodos a seguir servem para converso em strings e formatao do objeto XMLList:

normalize() toString() toXMLString()

Existem alguns mtodos adicionais:

contains()

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com XML

104

copiar() length() valueOf()

Veja a documentao desses mtodos na Referncia do ActionScript 3.0 para a plataforma Adobe Flash. Para um objeto XMLList que contm exatamente um elemento XML, voc pode usar todos os mtodos e propriedades da classe XML porque um XMLList com um elemento XML tratado do mesmo modo que um objeto XML. Por exemplo, no cdigo a seguir, como doc.div um objeto XMLList que contm um elemento, voc pode usar o mtodo appendChild() da classe XML:
var doc:XML = <body> <div> <p>Hello</p> </div> </body>; doc.div.appendChild(<p>World</p>);

Para obter uma lista de propriedades e mtodos XML, consulte Objetos XML na pgina 100.

Inicializao de variveis XML

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc pode atribuir um literal XML a um objeto XML do seguinte modo:
var myXML:XML = <order> <item id='1'> <menuName>burger</menuName> <price>3.95</price> </item> <item id='2'> <menuName>fries</menuName> <price>1.45</price> </item> </order>

Como mostra o snippet a seguir, tambm possvel usar o construtor new para criar uma ocorrncia de um objeto XML a partir de uma string que contm dados XML:
var str:String = "<order><item id='1'><menuName>burger</menuName>" + "<price>3.95</price></item></order>"; var myXML:XML = new XML(str);

Se os dados XML da string no estiverem bem formados (por exemplo, se estiver faltando uma tag de fechamento), ocorrer um erro de tempo de execuo. Voc tambm pode transmitir os dados por referncia (de outras variveis) em um objeto XML, como mostra o exemplo a seguir:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com XML

105

var tagname:String = "item"; var attributename:String = "id"; var attributevalue:String = "5"; var content:String = "Chicken"; var x:XML = <{tagname} {attributename}={attributevalue}>{content}</{tagname}>; trace(x.toXMLString()) // Output: <item id="5">Chicken</item>

Para carregar os dados XML a partir de uma URL, use a classe URLLoader, como mostra o exemplo a seguir:
import flash.events.Event; import flash.net.URLLoader; import flash.net.URLRequest; var externalXML:XML; var loader:URLLoader = new URLLoader(); var request:URLRequest = new URLRequest("xmlFile.xml"); loader.load(request); loader.addEventListener(Event.COMPLETE, onComplete); function onComplete(event:Event):void { var loader:URLLoader = event.target as URLLoader; if (loader != null) { externalXML = new XML(loader.data); trace(externalXML.toXMLString()); } else { trace("loader is not a URLLoader!"); } }

Para ler dados XML a partir de uma conexo de soquete, use a classe XMLSocket. Para obter mais informaes, consulte a entrada Classe XMLSocket na Referncia do ActionScript 3.0 para a plataforma Adobe Flash.

Montagem e transformao de objetos XML

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Use o mtodo prependChild() ou o mtodo appendChild() para adicionar uma propriedade ao incio ou ao final de uma lista de propriedades do objeto XML, como mostra o exemplo a seguir:
var var var x = x = x = x1:XML = <p>Line 1</p> x2:XML = <p>Line 2</p> x:XML = <body></body> x.appendChild(x1); x.appendChild(x2); x.prependChild(<p>Line 0</p>); // x == <body><p>Line 0</p><p>Line 1</p><p>Line 2</p></body>

Use o mtodo insertChildBefore() ou o mtodo insertChildAfter() para adicionar uma propriedade antes ou depois de uma propriedade especificada, do seguinte modo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com XML

106

var x:XML = <body> <p>Paragraph 1</p> <p>Paragraph 2</p> </body> var newNode:XML = <p>Paragraph 1.5</p> x = x.insertChildAfter(x.p[0], newNode) x = x.insertChildBefore(x.p[2], <p>Paragraph 1.75</p>)

Como mostra o exemplo a seguir, voc tambm pode usar os operadores de chaves ( { e } ) para possar dados por referncia (de outras variveis) ao criar objetos XML:
var ids:Array = [121, 122, 123]; var names:Array = [["Murphy","Pat"], ["Thibaut","Jean"], ["Smith","Vijay"]] var x:XML = new XML("<employeeList></employeeList>"); for (var i:int = 0; i < 3; i++) { var newnode:XML = new XML(); newnode = <employee id={ids[i]}> <last>{names[i][0]}</last> <first>{names[i][1]}</first> </employee>; x = x.appendChild(newnode) }

possvel atribuir propriedades e atributos a um objeto XML usando o operador =, conforme mostrado a seguir:
var x:XML = <employee> <lastname>Smith</lastname> </employee> x.firstname = "Jean"; x.@id = "239";

Isso define o objeto XML x como:

<employee id="239"> <lastname>Smith</lastname> <firstname>Jean</firstname> </employee>

Voc pode usar os operadores + e += para concatenar objetos XMLList:

var x1:XML = <a>test1</a> var x2:XML = <b>test2</b> var xList:XMLList = x1 + x2; xList += <c>test3</c>

Isso define o objeto XMLList xList como:

<a>test1</a> <b>test2</b> <c>test3</c>

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com XML

107

Como percorrer estruturas XML

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Um dos recursos avanados do XML fornecer dados aninhados complexos por meio de uma string linear de caracteres de texto. Ao carregar dados em um objeto XML, o ActionScript analisa os dados e carrega sua estrutura hierrquica na memria (ou envia um erro de tempo de execuo se os dados XML no estiverem bem formados). Os operadores e mtodos dos objetos XML e XMLList facilitam o percurso pela estrutura de dados XML. Use o operador de dot (.) e o operador de acessador do descendente (..) para acessar as propriedades filho de um objeto XML. Considere o objeto XML a seguir:
var myXML:XML = <order> <book ISBN="0942407296"> <title>Baking Extravagant Pastries with Kumquats</title> <author> <lastName>Contino</lastName> <firstName>Chuck</firstName> </author> <pageCount>238</pageCount> </book> <book ISBN="0865436401"> <title>Emu Care and Breeding</title> <editor> <lastName>Case</lastName> <firstName>Justin</firstName> </editor> <pageCount>115</pageCount> </book> </order>

O objeto myXML.book um objeto XMLList que contm as propriedades filhas do objeto myXML chamado book. Esses dois objetos XML correspondem s duas propriedades book do objeto myXML. O objeto myXML..lastName um objeto XMLList que contm todas as propriedades do descendente com o nome
lastName. Esses dois objetos XML correspondem s duas propriedades lastName do objeto myXML.

O objeto myXML.book.editor.lastName um objeto XMLList que contm todos os filhos com o nome lastName dos filhos com o nome editor dos filhos com o nome book do objeto myXML: nesse caso, um objeto XMLList que contm apenas um objeto XML (a propriedade lastName com o valor "Case").

Acesso a ns pai e filho

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O mtodo parent() retorna o pai de um objeto XML. Voc pode usar os valores ordinais de ndice de uma lista de filhos para acessar objetos filho especficos. Por exemplo, considere um objeto XML myXML que tem duas propriedades filho chamadas book. Cada propriedade filho chamada book tem um nmero de ndice associado:
myXML.book[0] myXML.book[1]

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com XML

108

Para acessar um neto especfico, voc pode especificar nmeros de ndice para os nomes do filho e do neto:
myXML.book[0].title[0]

No entanto, se houver apenas um filho de x.book[0] com o nome title, voc pode omitir a referncia de ndice do seguinte modo:
myXML.book[0].title

Do mesmo modo, se houver apenas um filho de book do objeto x, e se esse objeto filho tiver apenas um objeto title, voc pode omitir as duas referncias de ndice assim:
myXML.book.title

possvel usar o mtodo child() para navegar at os filhos com nomes baseados em uma varivel ou expresso, como mostra o exemplo a seguir:
var myXML:XML = <order> <book> <title>Dictionary</title> </book> </order>; var childName:String = "book"; trace(myXML.child(childName).title) // output: Dictionary

Acesso a atributos
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Use o smbolo @ (operador de identificador de atributo) para acessar atributos em um objeto XML ou XMLList, como mostra o cdigo a seguir:
var employee:XML = <employee id="6401" code="233"> <lastName>Wu</lastName> <firstName>Erin</firstName> </employee>; trace(employee.@id); // 6401

Voc pode usar o smbolo de caractere curinga * com o smbolo @ para acessar todos os atributos de um objeto XML ou XMLList, como no cdigo a seguir:
var employee:XML = <employee id="6401" code="233"> <lastName>Wu</lastName> <firstName>Erin</firstName> </employee>; trace(employee.@*.toXMLString()); // 6401 // 233

Voc pode usar o mtodo attribute() ou attributes() para acessar um atributo especfico ou todos os atributos de um objeto XML ou XMLList, como no cdigo a seguir:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com XML

109

var employee:XML = <employee id="6401" code="233"> <lastName>Wu</lastName> <firstName>Erin</firstName> </employee>; trace(employee.attribute("id")); // 6401 trace(employee.attribute("*").toXMLString()); // 6401 // 233 trace(employee.attributes().toXMLString()); // 6401 // 233

Tambm possvel usar a sintaxe a seguir para acessar atributos, como mostra o seguinte exemplo:
employee.attribute("id") employee["@id"] employee.@["id"]

Cada um equivalente a employee.@id. No entanto, a sintaxe employee.@id recomendada.

Filtragem por valor de elemento ou atributo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc pode usar os operadores de parnteses ( e ) para filtrar elementos com um nome de elemento ou valor de atributo especfico. Considere o objeto XML a seguir:
var x:XML = <employeeList> <employee id="347"> <lastName>Zmed</lastName> <firstName>Sue</firstName> <position>Data analyst</position> </employee> <employee id="348"> <lastName>McGee</lastName> <firstName>Chuck</firstName> <position>Jr. data analyst</position> </employee> </employeeList>

As seguintes expresses so vlidas:

x.employee.(lastName == "McGee") o segundo n employee. x.employee.(lastName == "McGee").firstName a propriedade firstName do segundo n employee. x.employee.(lastName == "McGee").@id o valor do atributo id do segundo n employee. x.employee.(@id == 347) O primeiro n employee. x.employee.(@id == 347).lastName a propriedade lastName do primeiro n employee. x.employee.(@id > 300) um XMLList com as duas propriedades employee. x.employee.(position.toString().search("analyst") > -1) um objeto XMLList com as duas

propriedades position. Se voc tentar filtrar os atributos ou elementos que no existem, lanada uma exceo. Por exemplo, a linha final do cdigo a seguir gera um erro, porque no existe nenhum atributo id no segundo elemento p:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com XML

110

var doc:XML = <body> <p id='123'>Hello, <b>Bob</b>.</p> <p>Hello.</p> </body>; trace(doc.p.(@id == '123'));

Do mesmo modo, a linha final do cdigo a seguir gera um erro, porque no existe nenhuma propriedade b do segundo elemento p:
var doc:XML = <body> <p id='123'>Hello, <b>Bob</b>.</p> <p>Hello.</p> </body>; trace(doc.p.(b == 'Bob'));

Para evitar esses erros, voc pode identificar as propriedades que tm atributos ou elementos correspondentes usando os mtodos attribute() e elements(), como no cdigo a seguir:
var doc:XML = <body> <p id='123'>Hello, <b>Bob</b>.</p> <p>Hello.</p> </body>; trace(doc.p.(attribute('id') == '123')); trace(doc.p.(elements('b') == 'Bob'));

Tambm possvel usar o mtodo hasOwnProperty(), como no seguinte cdigo:

var doc:XML = <body> <p id='123'>Hello, <b>Bob</b>.</p> <p>Hello.</p> </body>; trace(doc.p.(hasOwnProperty('@id') && @id == '123')); trace(doc.p.(hasOwnProperty('b') && b == 'Bob'));

Uso de for..in e for each..em instrues

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O ActionScript 3.0 inclui a instruo for..in e a instruo for each..in para percorrer objetos XMLList. Por exemplo, considere o seguinte objeto XML, myXML, e o objeto XMLList, myXML.item. O objeto XMLList, myXML.item, consiste em dois ns item do objeto XML.
var myXML:XML = <order> <item id='1' quantity='2'> <menuName>burger</menuName> <price>3.95</price> </item> <item id='2' quantity='2'> <menuName>fries</menuName> <price>1.45</price> </item> </order>;

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com XML

111

A instruo for..in permite percorrer um conjunto de nomes de propriedades em um XMLList:

var total:Number = 0; for (var pname:String in myXML.item) { total += myXML.item.@quantity[pname] * myXML.item.price[pname]; }

A instruo for each..in permite percorrer as propriedades em um objeto XMLList:

var total2:Number = 0; for each (var prop:XML in myXML.item) { total2 += prop.@quantity * prop.price; }

Uso de namespaces XML

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os namespaces em um objeto (ou documento) XML identificam o tipo de dados contido no objeto. Por exemplo, ao enviar e fornecer dados XML para um servio da Web que usa o protocolo SOAP, voc declara o namespace na tag de abertura do XML:
var message:XML = <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <soap:Body xmlns:w="http://www.test.com/weather/"> <w:getWeatherResponse> <w:tempurature >78</w:tempurature> </w:getWeatherResponse> </soap:Body> </soap:Envelope>;

O namespace tem um prefixo, soap, e uma URI que define o namespace, http://schemas.xmlsoap.org/soap/envelope/. O ActionScript 3.0 inclui a classe Namespace para trabalhar com namespaces XML. Para o objeto XML do exemplo anterior, voc pode usar a classe Namespace do seguinte modo:
var soapNS:Namespace = message.namespace("soap"); trace(soapNS); // Output: http://schemas.xmlsoap.org/soap/envelope/ var wNS:Namespace = new Namespace("w", "http://www.test.com/weather/"); message.addNamespace(wNS); var encodingStyle:XMLList = message.@soapNS::encodingStyle; var body:XMLList = message.soapNS::Body; message.soapNS::Body.wNS::GetWeatherResponse.wNS::tempurature = "78";

A classe XML inclui os seguintes mtodos para trabalhar com namespaces: addNamespace(), inScopeNamespaces(), localName(), name(), namespace(), namespaceDeclarations(), removeNamespace(), setLocalName(), setName() e setNamespace(). A diretiva de namespace XML padro permite atribuir um namespace padro a objetos XML. Por exemplo, a seguir,
x1 e x2 tm o mesmo namespace padro:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com XML

112

var ns1:Namespace = new Namespace("http://www.example.com/namespaces/"); default xml namespace = ns1; var x1:XML = <test1 />; var x2:XML = <test2 />;

Converso de tipo XML

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc pode converter objetos XML e XMLList em valores de string. Do mesmo modo, possvel converter strings em objetos XML e XMLList. Alm disso, tenha em mente que todos os valores de atributo, nomes e valores de texto XML so strings. As sees a seguir discutem todas essas formas de converso de tipo XML.

Converso de objetos XML e XMLList em strings

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior As classes XML e XMLList incluem um mtodo toString() e um mtodo toXMLString(). O mtodo toXMLString() retorna uma string que inclui todas as tags, atributos, instrues de namespace e contedo do objeto XML. Para objetos XML com contedo complexo (elementos filho), o mtodo toString() exatamente igual ao mtodo toXMLString(). Para objetos XML com contedo simples (aqueles que contm apenas um elemento de texto), o mtodo toString() retorna somente o contedo de texto do elemento, como mostra o exemplo a seguir:
var myXML:XML = <order> <item id='1' quantity='2'> <menuName>burger</menuName> <price>3.95</price> </item> <order>; trace(myXML.item[0].menuName.toXMLString()); // <menuName>burger</menuName> trace(myXML.item[0].menuName.toString()); // burger

Se o mtodo trace() usado sem especificar toString() ou toXMLString(), os dados so convertidos usando o mtodo toString() por padro, como mostra este cdigo:
var myXML:XML = <order> <item id='1' quantity='2'> <menuName>burger</menuName> <price>3.95</price> </item> <order>; trace(myXML.item[0].menuName); // burger

Ao usar o mtodo trace() para depurar o cdigo, voc normalmente usar o mtodo toXMLString() para que trace() gere dados mais completos.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com XML

113

Converso de strings em objetos XML

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior possvel usar o construtor new XML() para criar um objeto XML a partir de uma string, do seguinte modo:
var x:XML = new XML("<a>test</a>");

Se voc tentar converter uma string em XML a partir de uma string que representa um XML invlido ou mal formado, ocorrer um erro de tempo de execuo do seguinte modo:
var x:XML = new XML("<a>test"); // throws an error

Converso de valores de atributo, nomes e valores de texto a partir de strings

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Todos os valores de atributo, nomes e valores de texto XML so tipos de dados String e talvez seja necessrio convertlos em outros tipos de dados. Por exemplo, o cdigo a seguir usa a funo Number() para converter valores de texto em nmeros:
var myXML:XML = <order> <item> <price>3.95</price> </item> <item> <price>1.00</price> </item> </order>; var total:XML = <total>0</total>; myXML.appendChild(total); for each (var item:XML in myXML.item) { myXML.total.children()[0] = Number(myXML.total.children()[0]) + Number(item.price.children()[0]); } trace(myXML.total); // 4.95;

Se esse cdigo no tivesse usado a funo Number(), o cdigo interpretaria o operador + como o operador de concatenao de string e o mtodo trace() na ltima linha seria o seguinte:
01.003.95

Leitura de documentos XML externos

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc pode usar a classe URLLoader para carregar dados XML a partir de uma URL. Para usar o cdigo a seguir em seus aplicativos, substitua o valor XML_URL do exemplo por uma URL vlida:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com XML

114

import flash.events.Event; import flash.net.URLLoader; var myXML:XML = new XML(); var XML_URL:String = "http://www.example.com/Sample3.xml"; var myXMLURL:URLRequest = new URLRequest(XML_URL); var myLoader:URLLoader = new URLLoader(myXMLURL); myLoader.addEventListener(Event.COMPLETE, xmlLoaded); function xmlLoaded(event:Event):void { myXML = XML(myLoader.data); trace("Data loaded."); }

Voc tambm pode usar a classe XMLSocket para configurar uma conexo de soquete XML assncrona com um servidor. Para obter mais informaes, consulte Referncia do ActionScript 3.0 para a plataforma Adobe Flash.

Exemplo XML no ActionScript: carregamento de dados RSS da Web

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O aplicativo de exemplo RSSViewer mostra diversos recursos para trabalhar com XML no ActionScript, incluindo os seguintes:

Uso dos mtodos XML para percorrer dados XML em forma de um feed RSS. Uso dos mtodos XML para montar dados XML em forma de HTML a ser usado em um campo de texto.
O formato RSS muito utilizado para distribuir notcias via XML. Um arquivo de dados RSS simples pode ser parecido com o seguinte:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com XML

115

<?xml version="1.0" encoding="UTF-8" ?> <rss version="2.0" xmlns:dc="http://purl.org/dc/elements/1.1/"> <channel> <title>Alaska - Weather</title> <link>http://www.nws.noaa.gov/alerts/ak.html</link> <description>Alaska - Watches, Warnings and Advisories</description> <item> <title> Short Term Forecast - Taiya Inlet, Klondike Highway (Alaska) </title> <link> http://www.nws.noaa.gov/alerts/ak.html#A18.AJKNK.1900 </link> <description> Short Term Forecast Issued At: 2005-04-11T19:00:00 Expired At: 2005-04-12T01:00:00 Issuing Weather Forecast Office Homepage: http://pajk.arh.noaa.gov </description> </item> <item> <title> Short Term Forecast - Haines Borough (Alaska) </title> <link> http://www.nws.noaa.gov/alerts/ak.html#AKZ019.AJKNOWAJK.190000 </link> <description> Short Term Forecast Issued At: 2005-04-11T19:00:00 Expired At: 2005-04-12T01:00:00 Issuing Weather Forecast Office Homepage: http://pajk.arh.noaa.gov </description> </item> </channel> </rss>

O aplicativo SimpleRSS l os dados RSS na Internet, analisa os dados em busca de cabealhos (ttulos), links e descries e retorna esses dados. A classe SimpleRSSUI fornece a interface de usurio e chama a classe SimpleRSS, que faz todo o processamento XML. Para obter os arquivos do aplicativo para este exemplo, consulte www.adobe.com/go/learn_programmingAS3samples_flash_br. Os arquivos do aplicativo RSSViewer esto localizados na pasta Amostras/RSSViewer. O aplicativo consiste nos seguintes arquivos:
Arquivo RSSViewer.mxml ou RSSViewer.fla com/example/programmingas3/rssViewer/RSSParser.as Uma classe que contm mtodos que usam o E4X para percorrer dados RSS (XML) e gerar uma representao em HTML correspondente. Um arquivo RSS de exemplo. O aplicativo configurado para ler dados RSS na Web, em um feed RSS do Flex hospedado pela Adobe. No entanto, voc pode alterar o arquivo com facilidade para ler dados RSS neste documento, que usa um esquema ligeiramente diferente do feed RSS do Flex. Descrio O arquivo principal do aplicativo no Flash (FLA) ou no Flex (MXML).

RSSData/ak.rss

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com XML

116

Leitura e anlise de dados XML

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe RSSParser inclui um mtodo xmlLoaded() que converte os dados RSS de entrada, armazenados na varivel rssXML, em uma string que contm a sada em formato HTML, rssOutput. Logo do incio do mtodo, o cdigo define o namespace XML padro se os dados RSS de origem inclurem um namespace padro:
if (rssXML.namespace("") != undefined) { default xml namespace = rssXML.namespace(""); }

As prximas linhas percorrem o contedo dos dados XML de origem, examinando cada propriedade de descendente chamada item:
for each (var item:XML in rssXML..item) { var itemTitle:String = item.title.toString(); var itemDescription:String = item.description.toString(); var itemLink:String = item.link.toString(); outXML += buildItemHTML(itemTitle, itemDescription, itemLink); }

As trs primeiras linhas simplesmente definem variveis de string para representar as propriedades de ttulo, descrio e link da propriedade item dos dados XML. Em seguida, a prxima linha chama o mtodo buildItemHTML() para obter os dados HTML em forma de um objeto XMLList, usando as trs novas variveis de string como parmetros.

Montagem de dados XMLList

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os dados HTML (um objeto XMLList) tm uma das seguintes formas:
<b>itemTitle</b> <p> itemDescription <br /> <a href="link"> <font color="#008000">More...</font> </a> </p>

As primeiras linhas do mtodo apagam o namespace XML padro:

default xml namespace = new Namespace();

A diretiva de namespace XML padro tem o escopo do nvel de bloqueio da funo. Isso significa que os escopo dessa instruo o mtodo buildItemHTML(). As prximas linhas montam o XMLList, com base nos argumentos de string transmitidos para a funo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com XML

117

var body:XMLList = new XMLList(); body += new XML("<b>" + itemTitle + "</b>"); var p:XML = new XML("<p>" + itemDescription + "</p>"); var link:XML = <a></a>; link.@href = itemLink; // <link href="itemLinkString"></link> link.font.@color = "#008000"; // <font color="#008000"></font></a> // 0x008000 = green link.font = "More..."; p.appendChild(<br/>); p.appendChild(link); body += p;

Esse objeto XMLList representa dados de string adequados para um campo de texto HTML do ActionScript. O mtodo xmlLoaded() usa o valor de retorno do mtodo buildItemHTML() e o converte em uma string:
XML.prettyPrinting = false; rssOutput = outXML.toXMLString();

Extrao do ttulo do feed RSS e envio de um evento personalizado

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O mtodo xmlLoaded() define uma varivel de string rssTitle, com base nas informaes dos dados XML RSS de origem:
rssTitle = rssXML.channel.title.toString();

Finalmente, o mtodo xmlLoaded() gera um evento, que informa ao aplicativo que os dados esto analisados e disponveis:
dataWritten = new Event("dataWritten", true);

ltima atualizao em 29/3/2011

118

Captulo 7: Manipulao de eventos

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O sistema de tratamento de eventos permite que os programadores respondam s entradas de usurios e eventos do sistema de forma conveniente. O modelo de evento do ActionScript 3.0 no apenas conveniente, mas tambm compatvel com os padres, e bem integrado com a lista de exibio. Com base na especificao de eventos DOM (Document Object Model) de nvel 3 e em uma arquitetura de manipulao de eventos padro do setor, o novo modelo de evento fornece uma ferramenta poderosa e intuitiva para os programadores do ActionScript. O sistema de tratamento de eventos do ActionScript 3.0 interage de perto com a lista de exibio. Para ter uma compreenso bsica da lista de exibio, leia Programao de exibio na pgina 145.

Mais tpicos da Ajuda

Pacote flash.events Especificao de eventos DOM (Document Object Model) de nvel 3

Noes bsicas sobre a manipulao de eventos

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Pense nos eventos como ocorrncias de qualquer tipo no arquivo SWF que interessam a voc como programador. Por exemplo, a maioria dos arquivos SWF oferece suporte a algum tipo de interao do usurio - seja algo simples, como responder ao clique do mouse, ou algo mais complexo, como aceitar e processar dados inseridos em um formulrio. Toda interao do usurio com seu arquivo SWF considerada um evento. Os eventos tambm podem ocorrer sem nenhuma interao direta do usurio, como quando os dados terminam de ser carregados a partir de um servidor ou quando uma cmera acoplada ativada. No ActionScript 3.0, cada evento representado por um objeto, que uma ocorrncia da classe Event ou uma de suas subclasses. O objeto de evento no apenas armazena informaes sobre um evento especfico, mas tambm contm mtodos que facilitam o prprio tratamento. Por exemplo, quando detecta um clique do mouse, o Flash Player ou o AIR cria um objeto de evento (uma ocorrncia da classe MouseEvent) para representar esse evento especfico de clique do mouse. Depois de criar um objeto de evento, o Flash Player ou o AIR o envia, ou seja, o objeto de evento transmitido para o objeto que destino do evento. O objeto que o destino de um objeto de evento enviado chamado de destino do evento. Por exemplo, quando uma cmera acoplada ativada, o Flash Player envia um objeto de evento diretamente ao destino que, nesse caso, o objeto que representa a cmera. No entanto, se o destino do evento estiver na lista de exibio, o objeto ser transmitido pela hierarquia da lista de exibio at atingir o destino do evento. Em alguns casos, o objeto de evento forma "bolhas" na hierarquia da lista de exibio ao longo da mesma rota. Essa profundidade da hierarquia da lista de exibio chamada de fluxo de evento. Voc pode ouvir objetos de evento no seu cdigo usando ouvintes de evento. Ouvintes de evento so as funes ou os mtodos gravados para responder a eventos especficos. Para garantir que seu programa responda a eventos, adicione ouvintes ao destino do evento ou a qualquer objeto da lista de exibio que faa parte do fluxo de um objeto de evento.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de eventos

119

Sempre que gravado, o cdigo do ouvinte de evento segue essa estrutura bsica (os elementos em negrito so alocadores de espao preenchidos de acordo com suas necessidades):
function eventResponse(eventObject:EventType):void { // Actions performed in response to the event go here. } eventTarget.addEventListener(EventType.EVENT_NAME, eventResponse);

Esse cdigo faz duas coisas. Primeiro, ele define uma funo, que a maneira de especificar as aes que sero executadas em resposta ao evento. Em seguida, o mtodo addEventListener() do objeto de origem chamado, basicamente inscrevendo a funo do evento especificado para que, quando o evento acontecer, as aes da funo sejam executadas. Quando o evento realmente acontece, o destino do evento verifica a lista de todos os mtodos e funes registrados como ouvintes de evento. Em seguida, ele chama um por um, passando o objeto de evento como parmetro. Para criar seu prprio ouvinte de evento, necessrio alterar quatro coisas nesse cdigo. Primeiro, voc deve dar funo o nome que deseja usar (essa alterao deve ser feita em dois lugares, onde aparece eventResponse no cdigo). Segundo, voc deve especificar o nome de classe adequado do objeto que enviado pelo evento que deseja ouvir (EventType no cdigo) e tambm deve especificar a constante correta para o evento em questo (EVENT_NAME na listagem). Terceiro, voc deve chamar o mtodo addEventListener() no objeto que enviar o evento (eventTarget neste cdigo). Se desejar, altere o nome da varivel usada como parmetro da funo (eventObject neste cdigo). Conceitos e termos importantes A lista a seguir de referncia contm termos importantes que voc vai encontrar ao escrever rotinas de tratamento de eventos:
Bolhas As bolhas ocorrem para alguns eventos, de forma que um objeto de exibio pai possa responder aos eventos despachados por seus filhos. Fase de bolhas A parte do fluxo de evento no qual um evento se propaga at os objetos de exibio pai. A fase de bolha ocorre depois das fases de captura e destino. Fase de captura A parte do fluxo de evento em que um evento se propaga para baixo, do destino mais geral at o objeto de destino mais especfico. A fase de captura ocorre antes das fases de destino e bolhas. Comportamento padro Alguns eventos incluem um comportamento que normalmente ocorre ao longo do evento e conhecido como comportamento padro. Por exemplo, quando um usurio digita em um campo de texto, ocorre um evento de entrada de texto. O comportamento padro desse evento exibir o caractere que realmente foi digitado no campo de texto, mas voc pode substitu-lo (se, por algum motivo, no desejar exibir o caractere digitado). Envio Para notificar o evento ocorrido para os ouvintes de evento. Evento Algo que acontece em um objeto e que pode ser informado para outros objetos. Fluxo de evento Quando os eventos acontecem em um objeto na lista de exibio (um objeto exibido na tela), todos os objetos que contm o objeto em questo so informados sobre o evento e notificam seus ouvintes. Esse processo comea com o palco e continua na lista de exibio at o objeto real onde ocorreu o evento e, em seguida, retorna ao palco. Esse processo tambm conhecido como fluxo de evento. Objeto de evento Um objeto que contm informaes sobre a ocorrncia de um evento especfico, que enviado para todos os ouvintes assim que o evento acontece. Destino do evento O objeto que realmente envia um evento. Por exemplo, se o usurio clica em um boto que est dentro de uma entidade grfica contida no palco, todos esses objetos despacham eventos, mas o destino do evento o local onde o evento realmente aconteceu nesse caso, o boto clicado.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de eventos

120

Ouvinte Um objeto ou uma funo que foi registrada com um objeto para indicar que deve ser notificado quando

ocorrer um evento especfico.

Fase de destino O ponto do fluxo de evento no qual um evento atingiu o destino mais especfico possvel. A fase de

destino ocorre entre as fases de captura e bolhas.

Como a manipulao de eventos do ActionScript 3.0 difere das verses anteriores

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A diferena mais notvel entre a manipulao de eventos no ActionScript 3.0 e nas verses anteriores do ActionScript o fato de que, no ActionScript 3.0, existe apenas um sistema para manipulao de eventos, enquanto nas verses anteriores existem diversos sistemas diferentes de manipulao de eventos. Esta seo comea com uma viso geral de como era a manipulao de eventos nas verses anteriores do ActionScript e, em seguida, discute como a manipulao de eventos foi alterada para o ActionScript 3.0.

Manipulao de eventos nas verses anteriores do ActionScript

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior As verses anteriores ao ActionScript 3.0 forneciam diversas maneiras diferentes para manipular eventos:

Manipuladores de eventos on() que podem ser colocados diretamente nas ocorrncias de Button e de MovieClip Manipuladores onClipEvent() que podem ser colocados diretamente nas ocorrncias de MovieClip Propriedades de funo de retorno de chamada, como XML.onload e Camera.onActivity Ouvintes de evento registrados ao usar o mtodo addListener() A classe UIEventDispatcher que implementou parcialmente o modelo de evento DOM.
Cada um desses mecanismos tem vantagens e desvantagens. Os manipuladores on() e onClipEvent() so fceis de usar, mas dificultam a manuteno posterior dos projetos porque o cdigo colocado diretamente nos botes e clipes de filme pode ser difcil de localizar. As funes de retorno de chamada tambm so simples de implementar, mas voc s pode usar uma funo por evento. Os ouvintes de evento so mais difceis de implementar porque requerem no s a criao de um objeto de ouvinte e de uma funo, mas tambm o registro do ouvinte com o objeto que gera o evento. No entanto, esse aumento da sobrecarga permite criar vrios objetos de ouvinte e registrar todos eles para o mesmo evento. O desenvolvimento de componentes para o ActionScript 2.0 gerou mais um modelo de evento. Esse novo modelo, incorporado na classe UIEventDispatcher, foi baseado em um subconjunto da especificao de eventos DOM. Os desenvolvedores familiarizados com a manipulao de eventos de componente acharo a transio para o modelo de evento do ActionScript 3.0 relativamente fcil. Infelizmente, a sintaxe usada pelos diversos modelos de evento diferente em alguns pontos. Por exemplo, no ActionScript 2.0, algumas propriedades, como TextField.onChanged, podem ser usadas como uma funo de retorno de chamada ou um ouvinte de evento. No entanto, a sintaxe para registrar objetos de ouvinte diferente, dependendo do uso de uma das seis classes que oferecem suporte aos ouvintes ou da classe UIEventDispatcher. Para as classes Key, Mouse, MovieClipLoader, Selection, Stage e TextField, use o mtodo addListener(), mas, para a manipulao de eventos de componentes, use o mtodo chamado addEventListener().

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de eventos

121

Outra complexidade decorrente dos diferentes modelos de manipulao de eventos o escopo da funo do manipulador de eventos, que variava muito dependendo do mecanismo usado. Em outras palavras, o significado da palavra-chave this no era consistente entre os sistemas de manipulao de eventos.

Manipulao de eventos no ActionScript 3.0

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O ActionScript 3.0 apresenta um nico modelo de manipulao de eventos que substitui os diversos mecanismos diferentes que existiam nas verses anteriores da linguagem. O novo modelo de evento baseia-se na especificao de eventos DOM (Document Object Model) de nvel 3. Embora o formato de arquivo SWF no estejam em conformidade especificamente com o padro DOM, existem similaridades suficientes entre a lista de exibio e a estrutura do DOM que permitem a implementao do modelo de evento DOM. Um objeto na lista de exibio equivalente a um n na estrutura hierrquica DOM e os termos objeto da lista de exibio e n so usados alternadamente nesta discusso. A implementao do Flash Player e do AIR do modelo de evento DOM inclui um conceito chamado comportamento padro. Um comportamento padro uma ao executada pelo Flash Player ou AIR como conseqncia normal de determinados eventos. Comportamentos padro Os desenvolvedores so geralmente responsveis por gravar o cdigo que responde a eventos. No entanto, em alguns casos, como um comportamento normalmente associado a um evento, o Flash Player ou o AIR o executa automaticamente a no ser que o desenvolvedor adicione algum cdigo para cancel-lo. Como o Flash Player ou o AIR exibe o comportamento automaticamente, tais comportamentos so chamados de padro. Por exemplo, quando um usurio insere um texto em um objeto TextField, a expectativa de que o texto ser exibido nesse objeto TextField to comum que o comportamento incorporado no Flash Player e no AIR. Se no desejar que esse comportamento padro ocorra, cancele-o usando o novo sistema de manipulao de eventos. Quando o usurio insere o texto em um objeto TextField, o Flash Player ou o AIR cria uma ocorrncia da classe TextEvent para representar essa entrada do usurio. Para impedir que o Flash Player ou o AIR exiba o texto no objeto TextField, acesse essa ocorrncia especfica de TextEvent e chame o mtodo preventDefault() dessa ocorrncia. Nem todos os comportamentos padro podem ser impedidos. Por exemplo, o Flash Player e o AIR geram um objeto MouseEvent quando o usurio clica duas vezes em uma palavra em um objeto TextField. O comportamento padro, que no pode ser evitado, a palavra realada quando o cursor passa. Vrios tipos de objetos de evento no tm comportamentos padro associados. Por exemplo, o Flash Player envia um objeto de evento connect quando uma conexo de rede estabelecida, mas no h nenhum comportamento padro associado a esse objeto. A documentao API da classe Event e das respectivas subclasses lista cada tipo de evento e descreve todo comportamento padro associado e se esse comportamento pode ser impedido. importante mencionar que os comportamentos padro so associados apenas aos objetos de evento enviados pelo Flash Player ou AIR, e no existem para objetos de evento enviados de modo programtico pelo ActionScript. Por exemplo, voc pode usar os mtodos da classe EventDispatcher para enviar um objeto de evento do tipo textInput, mas esse objeto no ter nenhum comportamento padro associado. Em outras palavras, o Flash Player e o AIR no exibiro um caractere em um objeto TextField em decorrncia de um evento textInput enviado programaticamente.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de eventos

122

Novidades dos ouvintes de evento do ActionScript 3.0 Para desenvolvedores familiarizados com o mtodo addListener() do ActionScript 2.0, talvez seja til descrever as diferenas entre o modelo de ouvinte de evento do ActionScript 2.0 e o do ActionScript 3.0. A lista a seguir descreve as principais diferenas entre os dois modelos de evento:

Para incluir ouvintes de evento no ActionScript 2.0, voc usa addListener() em alguns casos e
addEventListener() em outros, enquanto no ActionScript 3.0, addEventListener() usado em todas as

situaes.

No existe nenhum fluxo de evento no ActionScript 2.0, ou seja, o mtodo addListener() pode ser chamado
somente no objeto que transmite o evento. J no ActionScript 3.0, o mtodo addEventListener() pode ser chamado em qualquer objeto que faa parte do fluxo de evento.

No ActionScript 2.0, os ouvintes de evento podem ser funes, mtodos ou objetos, enquanto que no ActionScript
3.0, apenas funes ou mtodos podem ser ouvintes de evento.

O fluxo de eventos
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O Flash Player ou o AIR envia objetos de evento sempre que ocorre um evento. Se o destino do evento no estiver na lista de exibio, o Flash Player ou o AIR enviar o objeto diretamente para o destino. Por exemplo, o Flash Player envia o objeto de evento progress diretamente para um objeto URLStream. No entanto, se o destino do evento estiver na lista de exibio, o Flash Player enviar o objeto para a lista de exibio e esse objeto ir percorrer a lista at chegar ao destino. O fluxo de evento descreve como um objeto de evento se move pela lista de exibio. A lista de exibio est organizada em uma hierarquia que pode ser descrita como uma rvore. No topo da hierarquia da lista de exibio est o palco, que um continer especial de objeto de exibio que serve como raiz da lista de exibio. O palco representado pela classe flash.display.Stage e s pode ser acessado por meio de um objeto de exibio. Cada objeto de exibio tem uma propriedade chamada stage que faz referncia ao palco desse aplicativo. Quando o Flash Player ou o AIR envia um objeto para um evento relacionado lista de exibio, esse objeto de evento faz uma viagem de ida e volta do palco ao n de destino. A especificao de eventos DOM define o n de destino como o n que representa o destino do evento. Em outras palavras, o n de destino o objeto da lista de exibio onde ocorreu o evento. Por exemplo, se o usurio clicar em um objeto da lista de exibio chamado child1, o Flash Player ou o AIR enviar um objeto de evento usando child1 como n de destino. O fluxo de evento dividido conceitualmente em trs partes. A primeira parte chamada de fase de captura; essa fase compreende todos os ns do palco ao pai do n de destino. A segunda parte chamada de fase de destino e consiste apenas no n de destino. A terceira parte chamada de fase de bubbling. A fase de bubbling composta pelos ns encontrados na viagem de retorno do pai do n de destino ao palco.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de eventos

123

Os nomes das fases faro mais sentido se voc pensar na lista de exibio como uma hierarquia vertical com o palco no topo, como mostra o diagrama a seguir:
Palco

N pai

N filho1

N filho2

Se o usurio clicar no n Child1, o Flash Player ou o AIR enviar um objeto ao fluxo de evento. Como mostra a imagem a seguir, a jornada do objeto comea no palco, vai at o n pai, segue para o n Child1 e volta ao palco, movendo-se pelo n pai novamente at voltar ao palco.
Palco Fase de captura N pai Fase de animao

N filho1 Fase de destino

N filho2

Neste exemplo, a fase de captura inclui o palco e o n pai durante a viagem de ida inicial. A fase de destino consiste no tempo gasto no n Child1. A fase de bubbling inclui o n pai e o palco, pois ambos esto presentes na viagem de volta ao n raiz. O fluxo de evento contribui com um sistema de manipulao de eventos mais avanado do que o anteriormente disponvel para os programadores no ActionScript. Nas verses anteriores do ActionScript, no existe o fluxo de evento, ou seja, os ouvintes de evento podem ser adicionados somente ao objeto que gera o evento. No ActionScript 3.0, possvel adicionar ouvintes de evento no s a um n de destino, mas tambm a qualquer n ao longo do fluxo de evento. A possibilidade de adicionar ouvintes ao longo do fluxo de evento til quando um componente da interface do usurio tem mais de um objeto. Por exemplo, um objeto de boto normalmente contm um objeto de texto que serve como rtulo do boto. Sem poder adicionar um ouvinte ao fluxo de evento, seria necessrio adicionar um ouvinte ao objeto de boto e ao objeto de texto para garantir o recebimento de notificaes sobre eventos de clique que ocorrem em qualquer lugar no boto. No entanto, a existncia do fluxo de evento permite colocar um nico ouvinte no objeto de boto que manipula eventos de clique ocorridos no objeto de texto ou nas reas do objeto de boto que no so obscurecidas pelo objeto de texto. Porm, nem todos os objetos de evento participam das trs fases do fluxo de evento. Alguns tipos de eventos, como
enterFrame e init, so enviados diretamente para o n de destino e no participam da fase de captura, nem da fase

de bubbling. Outros eventos podem ser direcionados para objetos que no esto na lista de exibio, como eventos enviados para uma ocorrncia da classe Socket. Esses objetos de evento tambm vo diretamente para o objeto de destino, sem participar das fases de captura e de bubbling.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de eventos

124

Para descobrir como se comporta um tipo de evento especfico, consulte a documentao da API ou examine as propriedades do objeto de evento. O exame das propriedades do objeto de evento est descrito na prxima seo.

Objetos de evento
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os objetos de evento tm duas finalidades principais no novo sistema de manipulao de eventos. Primeiro, objetos de evento representam eventos reais, armazenando informaes sobre eventos especficos em um conjunto de propriedades. Segundo, objetos de evento contm um conjunto de mtodos que permite tratar objetos de evento e afetar o comportamento do sistema de tratamento de eventos. Para facilitar o acesso a esses mtodos e propriedades, a API do Flash Player define uma classe Event que serve como base para todos os objetos de evento. A classe Event define um conjunto fundamental de propriedades e mtodos comuns a todos os objetos de evento. Esta seo comea com uma discusso sobre as propriedades da classe Event, continua com uma descrio dos mtodos da classe Event e termina explicando por que existem subclasses de Event.

Noes bsicas das propriedades da classe Event

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe Event define diversas propriedades e constantes somente leitura que fornecem informaes importantes sobre um objeto de evento. As seguintes propriedades so especialmente importantes:

Os tipos de objeto de evento so representados por constantes e armazenados na propriedade Event.type. Se for necessrio impedir o comportamento padro de um evento, isso ser representado por um valor booleano e
armazenado na propriedade Event.cancelable.

As informaes de fluxo de evento so contidas nas propriedades restantes.

Tipos de objetos de evento Todo objeto de evento tem um tipo de evento associado. Os tipos de evento so armazenados na propriedade Event.type como valores de seqncia. Isso til para saber o tipo de objeto de evento, de modo que seu cdigo possa distinguir entre objetos de tipos diferentes. Por exemplo, o cdigo a seguir especifica que a funo do ouvinte clickHandler() deve responder a qualquer objeto de evento de clique de mouse transmitido para myDisplayObject:
myDisplayObject.addEventListener(MouseEvent.CLICK, clickHandler);

Vinte e quatro tipos de evento so associados classe Event propriamente dita e representados por constantes da classe Event; alguns deles so mostrados no trecho a seguir da definio da classe Event:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de eventos

125

package flash.events { public class Event { // class constants public static const ACTIVATE:String = "activate"; public static const ADDED:String= "added"; // remaining constants omitted for brevity } }

Essas constantes facilitam a referncia a tipos de evento especficos. Use essas constantes em vez das strings que representam. Se voc digitar o nome de uma constante incorretamente no cdigo, o compilador detectar o erro, mas, se as strings forem utilizadas, um erro tipogrfico talvez no se manifeste no tempo de compilao e gere um comportamento inesperado difcil de depurar. Por exemplo, ao adicionar um ouvinte de evento, use o seguinte cdigo:
myDisplayObject.addEventListener(MouseEvent.CLICK, clickHandler);

em vez de:
myDisplayObject.addEventListener("click", clickHandler);

Informaes de comportamento padro Seu cdigo pode verificar se o comportamento padro de um objeto de evento determinado pode ser impedido, acessando a propriedade cancelable. A propriedade cancelable tem um valor booleano que indica se um comportamento padro pode ou no ser impedido. Voc pode impedir ou cancelar o comportamento padro associado a um pequeno nmero de eventos usando o mtodo preventDefault(). Para obter mais informaes, consulte Cancelamento do comportamento padro do evento em Noes bsicas dos mtodos da classe Event na pgina 126. Informaes sobre o fluxo de evento As demais propriedades da classe Event contm informaes importantes sobre um objeto de evento e sua relao com o fluxo de evento, conforme descrito na lista a seguir:

A propriedade bubbles contm informaes sobre as partes do fluxo nas quais o objeto de evento participa. A propriedade eventPhase indica a fase atual no fluxo de evento. A propriedade target armazena uma referncia ao destino do evento. A propriedade currentTarget armazena uma referncia ao objeto da lista de exibio que est processando o
objeto de evento no momento. A propriedade bubbles Um evento animado se seu objeto participa da fase de bubbling do fluxo de evento, o que significa que o objeto de evento volta do n de destino para seu ancestral at chegar ao palco. A propriedade Event.bubbles armazena um valor booleano que indica se o objeto de evento participa na fase de bubbling. Como todos os eventos que so animados tambm participam nas fases de captura e de destino, qualquer evento animado participa das trs fases do fluxo de evento. Se o valor for true, o objeto de evento participar das trs fases. Se o valor for false, o objeto de evento no participar na fase de bubbling.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de eventos

126

A propriedade eventPhase Voc pode determinar a fase de qualquer objeto de evento investigando a propriedade eventPhase. A propriedade eventPhase contm um valor inteiro sem sinal que representa uma das trs fases do fluxo de evento. A API do Flash Player define uma classe EventPhase separada que contm trs constantes que correspondem a trs valores inteiros sem sinal, como mostra o seguinte trecho de cdigo:
package flash.events { public final class EventPhase { public static const CAPTURING_PHASE:uint = 1; public static const AT_TARGET:uint = 2; public static const BUBBLING_PHASE:uint= 3; } }

Essa constantes correspondem a trs valores vlidos da propriedade eventPhase. Voc pode usar essas constantes para deixar seu cdigo mais legvel. Por exemplo, se desejar assegurar que uma funo myFunc() seja chamada somente se o destino do evento estiver no palco de destino, use o cdigo a seguir para testar essa condio:
if (event.eventPhase == EventPhase.AT_TARGET) { myFunc(); }

A propriedade target A propriedade target armazena uma referncia ao objeto que o destino do evento. Em alguns casos, isso simples, como quando um microfone ativado; o destino do objeto de evento o objeto Microphone. No entanto, se o destino estiver na lista de exibio, a hierarquia da lista deve ser levada em considerao. Por exemplo, se o usurio inserir um clique de mouse em um ponto que inclui objetos sobrepostos da lista de exibio, o Flash Player e o AIR sempre escolhero o objeto mais distante do palco como destino do evento. Para arquivos SWF complexos, especialmente aqueles nos quais os botes so decorados regularmente com objetos filho menores, a propriedade target talvez no seja usada com freqncia porque, em geral, apontar para o objeto filho de um boto, no para o boto. Nesses casos, a prtica comum adicionar ouvintes de evento ao boto e usar a propriedade currentTarget que aponta para o boto, j que a propriedade target pode apontar para um filho do boto. A propriedade currentTarget A propriedade currentTarget contm uma referncia ao objeto que est processando o objeto de evento no momento. Embora possa parecer estranho no saber qual n est processando o objeto de evento que voc est examinando no momento, possvel adicionar uma funo de ouvinte a qualquer objeto de exibio do fluxo desse objeto de evento; a funo de ouvinte pode ser colocada em qualquer lugar. Alm disso, a mesma funo de ouvinte pode ser adicionada a diferentes objetos de exibio. medida que aumenta o tamanho e a complexidade de um projeto, a propriedade currentTarget fica cada vez mais til.

Noes bsicas dos mtodos da classe Event

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior H trs categorias de mtodos da classe Event:

Mtodos utilitrios, que podem criar cpias de um objeto de evento ou convert-lo em uma string

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de eventos

127

Mtodos de fluxo de evento, que removem objetos do fluxo de evento Mtodos de comportamento padro, que impedem o comportamento padro ou verificam se ele foi impedido
Mtodos utilitrios da classe Event Existem dois mtodos de utilitrio na classe Event. O mtodo clone() permite criar cpias de um objeto de evento. O mtodo toString() permite gerar uma representao de string das propriedades de um objeto de evento juntamente com os respectivos valores. Esses dois mtodos so usados internamente pelo sistema de modelo de evento, mais so expostos aos desenvolvedores para uso geral. Para desenvolvedores avanados que criam subclasses de Event, necessrio substituir e implementar verses dos dois mtodos de utilitrio para garantir que a subclasse funcione corretamente. Interrupo do fluxo de evento Voc pode chamar o mtodo Event.stopPropagation() ou o mtodo Event.stopImmediatePropagation() para impedir que um objeto de evento continue seu percurso no fluxo. Os dois mtodos so praticamente idnticos e diferem apenas quanto aos ouvintes de evento do n atual que podem ser executados:

O mtodo Event.stopPropagation() impede que o objeto de evento se mova para o prximo n, mas s depois
que algum outro ouvinte de evento do n atual tenha permisso para ser executado.

O mtodo Event.stopImmediatePropagation() tambm impede que o objeto de evento se mova para o

prximo n, mas no permite que outros ouvintes de evento do n atual sejam executados. Chamar um desses mtodos no afeta a ocorrncia do comportamento padro associado a um evento. Use os mtodos do comportamento padro da classe Event para impedir tal comportamento. Cancelamento do comportamento padro do evento Os dois mtodos envolvidos no cancelamento do comportamento padro so preventDefault() e isDefaultPrevented(). Chame o mtodopreventDefault() para cancelar o comportamento padro associado ao evento. Para verificar se preventDefault() j foi chamado em um objeto de evento, chame o mtodo isDefaultPrevented(), que retorna o valor true se o mtodo j tiver sido chamado; caso contrrio, retornar false. O mtodo preventDefault() s funcionar se o comportamento padro do evento puder ser cancelado. Para verificar isso, consulte a documentao da API para esse tipo de evento ou use o ActionScript para examinar a propriedade cancelable do objeto de evento. O cancelamento do comportamento padro no afeta o progresso de um objeto no fluxo de evento. Use os mtodos de fluxo de evento da classe Event para remover um objeto de evento do fluxo de evento.

Subclasses da classe Event

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Em muitos eventos, o conjunto comum de propriedades definido na classe Event suficiente. No entanto, outros eventos tm caractersticas exclusivas que no podem ser capturadas pelas propriedades disponveis na classe Event. Para esses eventos, o ActionScript 3.0 define vrias subclasses da classe Event. Cada subclasse oferece propriedades e tipos de eventos adicionais exclusivos a essa categoria de eventos. Por exemplo, os eventos relacionados entrada do mouse tm vrias caractersticas exclusivas que no podem ser capturadas pelas propriedades definidas na classe Event. A classe MouseEvent estende a classe Event adicionando dez propriedades que contm informaes como o local do evento de mouse e que indicam se teclas especficas foram pressionadas durante o evento de mouse.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de eventos

128

Uma subclasse de Event tambm contm constantes que representam os tipos de evento associados subclasse. Por exemplo, a classe MouseEvent define constantes para vrios tipos de evento de mouse, incluindo click, doubleClick, mouseDown e mouseUp. Conforme descrito na seo de mtodos de utilitrio da classe Event emObjetos de evento na pgina 124, preciso substituir os mtodos clone() e toString() para oferecer funcionalidade especfica para a subclasse.

Ouvintes de evento
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os ouvintes de evento, tambm chamados de manipuladores de evento, so funes executadas pelo Flash Player e pelo AIR em resposta a eventos especficos. A adio de um ouvinte de evento um processo de duas etapas. Primeiro, crie um mtodo de funo ou classe a ser executado pelo Flash Player ou AIR em resposta ao evento. s vezes, isso chamado de funo de ouvinte ou de manipulador de evento. Segundo, use o mtodo addEventListener() para registrar a funo de ouvinte no destino do evento ou em qualquer objeto da lista de exibio ao longo do fluxo de evento adequado.

Criao de uma funo de ouvinte

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A criao de funes de ouvinte uma das diferenas entre o modelo de evento do ActionScript 3.0 e o modelo de evento DOM. No modelo de evento DOM, existe uma distino clara entre um ouvinte de evento e uma funo de ouvinte: um ouvinte de evento uma ocorrncia de uma classe que implementa a interface EventListener, enquanto a funo de ouvinte um mtodo dessa classe chamado handleEvent(). No modelo de evento DOM, a ocorrncia da classe que contm a funo de ouvinte registrada, no a funo de ouvinte propriamente dita. No modelo de evento do ActionScript 3.0, no existe diferena entre um ouvinte de evento e uma funo de ouvinte. O ActionScript 3.0 no tem uma interface EventListener e as funes de ouvinte podem ser definidas fora de uma classe ou como parte dela. Alm disso, as funes de ouvinte no precisam ser chamadas de handleEvent() - elas podem ser chamadas com qualquer identificador vlido. No ActionScript 3.0, o nome da funo de ouvinte real registrado. Funo de ouvinte definida fora de uma classe O cdigo a seguir cria um arquivo SWF simples que exibe um quadrado vermelho. Uma funo de ouvinte chamada clickHandler(), que no faz parte de uma classe, ouve os eventos de clique de mouse no quadrado vermelho.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de eventos

129

package { import flash.display.Sprite; public class ClickExample extends Sprite { public function ClickExample() { var child:ChildSprite = new ChildSprite(); addChild(child); } } } import flash.display.Sprite; import flash.events.MouseEvent; class ChildSprite extends Sprite { public function ChildSprite() { graphics.beginFill(0xFF0000); graphics.drawRect(0,0,100,100); graphics.endFill(); addEventListener(MouseEvent.CLICK, clickHandler); } } function clickHandler(event:MouseEvent):void { trace("clickHandler detected an event of type: " + event.type); trace("the this keyword refers to: " + this); }

Quando um usurio interage com o arquivo SWF resultante clicando no quadrado, o Flash Player ou AIR gera a seguinte sada de trao:
clickHandler detected an event of type: click the this keyword refers to: [object global]

Observe que o objeto de evento transmitido como um argumento para clickHandler(). Isso permite que a funo de ouvinte examine o objeto de evento. Neste exemplo, use a propriedade type do objeto de evento para certificar-se de que o evento um evento de clique. O exemplo tambm verifica o valor da palavra-chave this. Nesse caso, this representa o objeto global, o que faz sentido porque a funo definida fora de um objeto ou classe personalizado. Funo de ouvinte definida como um mtodo de classe O exemplo a seguir idntico ao anterior que define a classe ClickExample, mas a funo clickHandler() definida como um mtodo da classe ChildSprite:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de eventos

130

package { import flash.display.Sprite; public class ClickExample extends Sprite { public function ClickExample() { var child:ChildSprite = new ChildSprite(); addChild(child); } } } import flash.display.Sprite; import flash.events.MouseEvent; class ChildSprite extends Sprite { public function ChildSprite() { graphics.beginFill(0xFF0000); graphics.drawRect(0,0,100,100); graphics.endFill(); addEventListener(MouseEvent.CLICK, clickHandler); } private function clickHandler(event:MouseEvent):void { trace("clickHandler detected an event of type: " + event.type); trace("the this keyword refers to: " + this); } }

Quando um usurio interage com o arquivo SWF resultante clicando no quadrado vermelho, o Flash Player ou AIR gera a seguinte sada de trao:
clickHandler detected an event of type: click the this keyword refers to: [object ChildSprite]

Observe que a palavra-chave this faz referncia ocorrncia de ChildSprite chamada child. Este comportamento diferente do ActionScript 2.0. Caso j tenha usado componentes no ActionScript 2.0, talvez se lembre que, quando um mtodo de classe era transmitido para UIEventDispatcher.addEventListener(), o escopo do mtodo ia at o componente que transmite o evento em vez da classe na qual o mtodo de ouvinte era definido. Em outras palavras, se voc utilizou essa tcnica no ActionScript 2.0, a palavra-chave this fazia referncia ao componente que transmite o evento, no ocorrncia de ChildSprite. Isso foi um problema significativo para alguns programadores, pois no permitia o acesso a outros mtodos e propriedades da classe que contm o mtodo de ouvinte. Como soluo temporria, os programadores do ActionScript 2.0 podiam usar a classe mx.util.Delegate para alterar o escopo do mtodo de ouvinte. No entanto, isso no mais necessrio porque o ActionScript 3.0 cria um mtodo vinculado quando addEventListener() chamado. Em resultado disso, a palavra-chave this faz referncia ocorrncia de ChildSprite chamada child, e o programador tem acesso a outros mtodos e propriedades da classe ChildSprite.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de eventos

131

Ouvinte de evento que no deve ser usado Existe uma terceira tcnica que permite criar um objeto genrico com uma propriedade que aponta para uma funo de ouvinte atribuda dinamicamente, mas essa tcnica no recomendada. Ela ser discutida aqui porque foi muito usada no ActionScript 2.0, mas no deve ser usada no ActionScript 3.0. Essa tcnica no recomendada porque a palavra-chave this far referncia ao objeto global em vez do objeto de ouvinte. O exemplo a seguir idntico ao exemplo anterior da classe ClickExample, mas a funo de ouvinte definida como parte de um objeto genrico chamado myListenerObj:
package { import flash.display.Sprite; public class ClickExample extends Sprite { public function ClickExample() { var child:ChildSprite = new ChildSprite(); addChild(child); } } } import flash.display.Sprite; import flash.events.MouseEvent; class ChildSprite extends Sprite { public function ChildSprite() { graphics.beginFill(0xFF0000); graphics.drawRect(0,0,100,100); graphics.endFill(); addEventListener(MouseEvent.CLICK, myListenerObj.clickHandler); } } var myListenerObj:Object = new Object(); myListenerObj.clickHandler = function (event:MouseEvent):void { trace("clickHandler detected an event of type: " + event.type); trace("the this keyword refers to: " + this); }

Os resultados do trao sero similares a:

clickHandler detected an event of type: click the this keyword refers to: [object global]

Voc talvez pensasse que this faria referncia a myListenerObj e que a sada de trao seria [object Object], mas a referncia foi feita ao objeto global. Ao transmitir o nome de uma propriedade dinmica como um argumento para addEventListener(), o Flash Player ou AIR no consegue criar um mtodo vinculado. Isso ocorre porque, quando est transmitindo o parmetro listener, voc no est transmitindo nada mais do que o endereo de memria da funo de ouvinte, e o Flash Player e AIR no conseguem vincular esse endereo de memria com a ocorrncia de
myListenerObj.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de eventos

132

Gerenciamento de ouvintes de evento

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc pode gerenciar suas funes de ouvinte usando os mtodos da interface IEventDispatcher. A interface IEventDispatcher a verso ActionScript 3.0 da interface EventTarget do modelo de evento DOM. Embora o nome IEventDispatcher possa transmitir a idia de que o objetivo principal enviar (ou despachar) objetos de evento, os mtodos dessa classe so usados com mais freqncia para registrar, verificar e remover ouvintes de evento. A interface IEventDispatcher define cinco mtodos, como mostra o cdigo a seguir:
package flash.events { public interface IEventDispatcher { function addEventListener(eventName:String, listener:Object, useCapture:Boolean=false, priority:Integer=0, useWeakReference:Boolean=false):Boolean; function removeEventListener(eventName:String, listener:Object, useCapture:Boolean=false):Boolean; function dispatchEvent(eventObject:Event):Boolean; function hasEventListener(eventName:String):Boolean; function willTrigger(eventName:String):Boolean; } }

A API do Flash Player implementa a interface IEventDispatcher com a classe EventDispatcher, que serve como base para todas as classes que podem ser destinos de evento ou fazer parte de um fluxo de evento. Por exemplo, a classe DisplayObject herdada da classe EventDispatcher. Isso significa que todos os objetos da lista de exibio tm acesso aos mtodos da interface IEventDispatcher. Adio de ouvintes de evento O mtodo addEventListener() a fora motriz da interface IEventDispatcher. Voc pode us-lo para registrar suas funes de ouvinte. Os dois parmetros necessrios so type e listener. Use o parmetro type para especificar o tipo de evento. Use o parmetro listener para especificar a funo de ouvinte que ser executada quando o evento ocorrer. O parmetro listener pode ser uma referncia a um mtodo de classe ou funo. No use parnteses quando especificar o parmetro listener. Por exemplo, a funo clickHandler() especificada sem parnteses na seguinte chamada do mtodo addEventListener():
addEventListener(MouseEvent.CLICK, clickHandler)

O parmetro useCapture do mtodo addEventListener() permite controlar a fase do fluxo de evento na qual o ouvinte estar ativo. Se useCapture for definido como true, o ouvinte estar ativo durante a fase de captura do fluxo de evento. Se useCapture for definido como false, o ouvinte estar ativo durante as fases de destinos e de bubbling do fluxo de evento. Para ouvir um evento durante todas as fases do fluxo de evento, chame addEventListener() duas vezes, uma com useCapture definido como true e outra com useCapture definido como false.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de eventos

133

O parmetro priority do mtodo addEventListener() no uma parte oficial do modelo de evento DOM nvel 3. Ele est includo no ActionScript 3.0 para fornecer mais flexibilidade para organizar os ouvintes de evento. Ao chamar addEventListener(), voc pode definir a prioridade desse ouvinte de evento transmitindo um valor inteiro como o parmetro priority. O valor padro 0, mas possvel definir valores inteiros negativos ou positivos. Quanto maior o nmero, mais rapidamente o ouvinte de evento ser executado. Os ouvintes de evento com a mesma prioridade so executados na ordem em que foram adicionados, de modo que o ouvinte adicionado primeiro ser executado antes. O parmetro useWeakReference permite especificar se a referncia funo de ouvinte ser fraca ou normal. Se esse parmetro for definido como true, voc poder evitar situaes nas quais as funes de ouvinte persistem na memria mesmo quando no so mais necessrias. O Flash Player e o AIR usam uma tcnica chamada coleta de lixo para apagar da memria os objetos que no so mais usados. Um objeto no mais necessrio quando no existe nenhuma referncia a ele. O coletor de lixo ignora as referncias fracas e, desse modo, uma funo de ouvinte que tem apenas uma referncia fraca se qualifica para a coleta de lixo. Remoo de ouvintes de eventos Voc pode usar o mtodo removeEventListener() para remover um ouvinte de evento que no seja mais necessrio. uma boa idia remover o ouvinte que no ser mais usado. Entre os parmetros obrigatrios esto eventName e listener, que so os mesmos parmetros obrigatrios no mtodo addEventListener(). No se esquea que possvel ouvir eventos durante todas as fases chamando addEventListener() duas vezes, uma com useCapture definido como true e outra definido como false. Para remover os dois ouvintes de evento, seria necessrio chamar removeEventListener() duas vezes, uma com useCapture definido como true e outra definido como false. Envio de eventos O mtodo dispatchEvent() pode ser usado por programadores avanados para enviar um objeto de evento personalizado para o fluxo de evento. O nico parmetro aceito por esse mtodo uma referncia a um objeto de evento, que deve ser uma ocorrncia da classe Event ou uma subclasse de Event. Assim que enviada, a propriedade target do objeto de evento definida como o objeto no qual dispatchEvent() foi chamado. Verificao da existncia de ouvintes de eventos Os dois mtodos finais da interface IEventDispatcher fornecem informaes teis sobre a existncia de ouvintes de evento. O mtodo hasEventListener() retornar true se um ouvinte de evento for encontrado para um tipo de evento especfico em um determinado objeto da lista de exibio. O mtodo willTrigger() tambm retornar true se um ouvinte for encontrado para um objeto especfico da lista de exibio, mas willTrigger() procurar ouvintes nesse objeto de exibio e em todos os ancestrais desse objeto em todas as fases do fluxo de evento.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de eventos

134

Eventos de erro sem ouvintes

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior As excees, em vez dos eventos, so o principal mecanismo de manipulao de erros no ActionScript 3.0, mas a manipulao de excees no funciona para operaes assncronas, como o carregamento de arquivos. Se ocorrer um erro durante uma operao assncrona, o Flash Player e o AIR enviaro um objeto de evento de erro. Se nenhum ouvinte for criado para o evento de erro, as verses do depurador do Flash Player e do AIR exibiro uma caixa de dilogo com informaes sobre o erro. Por exemplo, a verso do depurador do Flash Player exibe a caixa de dilogo a seguir, que descreve o erro quando o aplicativo tentar carregar um arquivo a partir de URLs invlidas:

A maioria dos eventos de erro baseia-se na classe ErrorEvent e, desse modo, tem uma propriedade chamada text que usada para armazenar a mensagem de erro exibida pelo Flash Player ou AIR. As duas excees so as classes StatusEvent e NetStatusEvent. Essas duas classes tm uma propriedade level (StatusEvent.level e NetStatusEvent.info.level). Quando o valor da propriedade level "error", esses tipos de evento so considerados eventos de erro. Um evento de erro no interrompe a execuo do arquivo SWF. Ele ser manifestado somente como uma caixa de dilogo nas verses do depurador dos plug-ins do navegador e de players dedicados, como uma mensagem no painel de sada do player de criao e como uma entrada no arquivo de log do Adobe Flash Builder. Ele no se manifestar de modo algum nas verses do Flash Player ou do AIR.

Exemplo de tratamento de evento: relgio de alarme

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O exemplo do Alarm Clock consiste em um relgio que permite que o usurio especifique um horrio no qual o alarme deve ser desativado, bem como uma mensagem a ser exibida nesse horrio. O exemplo do Alarm Clock baseia-se no aplicativo SimpleClock da seo Trabalho com datas e horas na pgina 1 e ilustra vrios aspectos do trabalho com eventos ActionScript 3.0, incluindo:

Como ouvir e responder a um evento Notificao de um evento aos ouvintes Criao de um tipo de evento personalizado
Para obter os arquivos do aplicativo Flash Professional dessa amostra, consulte http://www.adobe.com/go/learn_programmingAS3samples_flash_br. Para obter os arquivos do aplicativo Flex dessa amostra, consulte http://www.adobe.com/go/as3examples. Os arquivos do aplicativo Alarm Clock esto localizados na pasta Amostras/AlarmClock. O aplicativo inclui estes arquivos:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de eventos

135

Arquivo AlarmClockApp.mxml ou AlarmClockApp.fla com/example/programmingas3/clock/AlarmClock.as

Descrio O arquivo principal do aplicativo no Flash (FLA) ou no Flex (MXML).

Uma classe que estende a classe SimpleClock, adicionando a funcionalidade do despertador. Uma classe de evento personalizada (uma subclasse de flash.events.Event) que serve como objeto do evento alarm da classe AlarmClock. Desenha a superfcie de um relgio redondo e os ponteiros de horas, minutos e segundos com base na hora (descrito no exemplo de SimpleClock). Um componente da interface do relgio com um recurso simples de marcao da hora (descrito no exemplo de SimpleClock).

com/example/programmingas3/clock/AlarmEvent.as

com/example/programmingas3/clock/AnalogClockFace.as

com/example/programmingas3/clock/SimpleClock.as

Viso geral do Alarm Clock

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O principal recurso do relgio neste exemplo, incluindo o controle da hora e a exibio da superfcie do relgio, reutiliza o cdigo do aplicativo SimpleClock, descrito em Exemplo de data e hora: relgio analgico simples na pgina 6. A classe AlarmClock estende a classe SimpleClock desse exemplo, adicionando a funcionalidade necessria para um despertador, incluindo a definio da hora do alarme e do envio da notificao quando o alarme for desativado. Os eventos so gerados para enviar a notificao sobre algo ocorrido. A classe AlarmClock expe o evento Alarm, que outros objetos podem ouvir para executar as aes desejadas. Alm disso, a classe AlarmClock usa uma ocorrncia da classe Timer para determinar quando o alarme deve ser acionado. Assim como AlarmClock, a classe Timer gera um evento para notificar outros objetos (neste caso, uma ocorrncia de AlarmClock) aps um determinado perodo. Assim como a maioria dos aplicativos do ActionScript, os eventos formam uma parte importante da funcionalidade do aplicativo Alarm Clock de exemplo.

Acionamento do alarme
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Conforme mencionado anteriormente, a nica funcionalidade da classe AlarmClock est relacionada com a definio e o acionamento do alarme. A classe incorporada Timer (flash.utils.Timer) permite que o desenvolvedor defina o cdigo que ser executado aps o perodo especificado. A classe AlarmClock usa uma ocorrncia de Timer para determinar quando o alarme deve ser desativado.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de eventos

136

import flash.events.TimerEvent; import flash.utils.Timer; /** * The Timer that will be used for the alarm. */ public var alarmTimer:Timer; ... /** * Instantiates a new AlarmClock of a given size. */ public override function initClock(faceSize:Number = 200):void { super.initClock(faceSize); alarmTimer = new Timer(0, 1); alarmTimer.addEventListener(TimerEvent.TIMER, onAlarm); }

A ocorrncia de Timer definida na classe AlarmClock chama-se alarmTimer. O mtodo initClock(), que executa as operaes de configurao necessrias para a ocorrncia de AlarmClock, faz duas coisas com a varivel alarmTimer. Primeiro, a varivel percorrida com os parmetros que instruem a ocorrncia de Timer a aguardar 0 milissegundos e acionar o evento timer apenas uma vez. Depois de percorrer alarmTimer, o cdigo chama o mtodo addEventListener() da varivel para indicar se deseja ouvir o evento timer dessa varivel. Uma ocorrncia de Timer funciona enviando o evento timer aps um perodo especificado. A classe AlarmClock no precisa saber quando o evento timer enviado para desativar seu prprio alarme. Chamando addEventListener(), o cdigo de AlarmClock se auto-registra como ouvinte em alarmTimer. Os dois parmetros indicam que a classe AlarmClock deseja ouvir o evento timer (indicado pela constante TimerEvent.TIMER) e que, quando o evento ocorrer, o mtodo onAlarm() da classe AlarmClock deve ser chamado em resposta a esse evento. Para definir o alarme realmente, o mtodo setAlarm() da classe AlarmClock chamado do seguinte modo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de eventos

137

/** * Sets the time at which the alarm should go off. * @param hour The hour portion of the alarm time. * @param minutes The minutes portion of the alarm time. * @param message The message to display when the alarm goes off. * @return The time at which the alarm will go off. */ public function setAlarm(hour:Number = 0, minutes:Number = 0, message:String = "Alarm!"):Date { this.alarmMessage = message; var now:Date = new Date(); // Create this time on today's date. alarmTime = new Date(now.fullYear, now.month, now.date, hour, minutes); // Determine if the specified time has already passed today. if (alarmTime <= now) { alarmTime.setTime(alarmTime.time + MILLISECONDS_PER_DAY); } // Stop the alarm timer if it's currently set. alarmTimer.reset(); // Calculate how many milliseconds should pass before the alarm should // go off (the difference between the alarm time and now) and set that // value as the delay for the alarm timer. alarmTimer.delay = Math.max(1000, alarmTime.time - now.time); alarmTimer.start(); return alarmTime; }

Esse mtodo faz vrias coisas, como armazenar a mensagem do alarme e criar um objeto Date (alarmTime) que representa o momento real em que o alarme desativado. O mais importante nisto tudo, nas vrias linhas finais do mtodo, o fato de o objeto timer da varivel alarmTimer ser definido e ativado. Primeiro, o mtodo reset() chamado, interrompendo o cronmetro e redefinindo-o caso j esteja em execuo. Em seguida, o horrio atual (representado pela varivel now) subtrado do valor da varivel alarmTime para determinar quantos milissegundos devem se passar at o alarme ser desativado. A classe Timer no aciona o evento timer em um tempo absoluto, de modo que essa diferena relativa de tempo atribuda propriedade delay de alarmTimer. Finalmente, o mtodo start() chamado para iniciar o cronmetro realmente. Assim que o perodo especificado termina, alarmTimer envia o evento timer. Com a classe AlarmClock registrou o mtodo onAlarm() como um ouvinte desse evento, quando o evento timer acontece, onAlarm() chamado.
/** * Called when the timer event is dispatched. */ public function onAlarm(event:TimerEvent):void { trace("Alarm!"); var alarm:AlarmEvent = new AlarmEvent(this.alarmMessage); this.dispatchEvent(alarm); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de eventos

138

Um mtodo que registrado como ouvinte de evento deve ser definido com a assinatura apropriada (isto , o conjunto de parmetros e o tipo de retorno do mtodo). Para ser ouvinte do evento timer da classe Timer, um mtodo deve definir um parmetro cujo tipo de dados seja TimerEvent (flash.events.TimerEvent), uma subclasse de Event. Quando chama seus ouvintes de evento, a ocorrncia de Timer transmite uma ocorrncia de TimerEvent como objeto de evento.

Notificao do alarme a outros

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Assim como a classe Timer, a classe AlarmClock fornece um evento que permite que outros cdigos recebam notificaes quando o alarme desativado. Para que uma classe use a estrutura de manipulao de eventos incorporada no ActionScript, essa classe deve implementar a interface flash.events.IEventDispatcher. Normalmente, isso feito por meio da extenso da classe flash.events.EventDispatcher, que fornece uma implementao padro de IEventDispatcher (ou por meio da extenso de uma das subclasses de EventDispatcher). Como descrito anteriormente, a classe AlarmClock estende a classe SimpleClock, que (atravs de uma cadeia de herana) estende a classe EventDispatcher. Tudo isso significa que a classe AlarmClock j tem uma funcionalidade interna para fornecer seus prprios eventos. Outro cdigo pode ser registrado para ser notificado sobre o evento alarm da classe AlarmClock chamando o mtodo addEventListener() que AlarmClock herda de EventDispatcher. Quando uma ocorrncia de AlarmClock est pronta para notificar outro cdigo sobre a gerao do evento alarm, o mtodo dispatchEvent(), que tambm herdado de EventDispatcher, chamado.
var alarm:AlarmEvent = new AlarmEvent(this.alarmMessage); this.dispatchEvent(alarm);

Essas linhas de cdigo foram obtidas do mtodo onAlarm() da classe AlarmClock (mostrada por completo antes). O mtodo dispatchEvent() da ocorrncia de AlarmClock chamado e notifica todos os ouvintes registrados sobre o acionamento do evento alarm da ocorrncia de AlarmClock. O parmetro transmitido para dispatchEvent() o objeto de evento que ser transmitido junto com os mtodos de ouvinte. Nesse caso, uma ocorrncia da classe AlarmEvent, uma subclasse de Event criada especificamente para este exemplo.

Fornecimento de um evento de alarme personalizado

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Todos os ouvintes de evento recebem um parmetro de objeto de evento com informaes sobre o evento especfico que est sendo acionado. Em muitos casos, o objeto de evento uma ocorrncia da classe Event. No entanto, em alguns casos til fornecer informaes adicionais aos ouvintes de evento. Uma maneira comum de fazer isso definir uma nova classe, uma subclasse de Event, e usar uma ocorrncia dessa classe como objeto de evento. Neste exemplo, uma ocorrncia de AlarmEvent usada como objeto quando o evento alarm da classe AlarmClock enviado. A classe AlarmEvent, mostrada aqui, fornece informaes adicionais sobre o evento alarm, especificamente a mensagem de alarme:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de eventos

139

import flash.events.Event; /** * This custom Event class adds a message property to a basic Event. */ public class AlarmEvent extends Event { /** * The name of the new AlarmEvent type. */ public static const ALARM:String = "alarm"; /** * A text message that can be passed to an event handler * with this event object. */ public var message:String; /** *Constructor. *@param message The text to display when the alarm goes off. */ public function AlarmEvent(message:String = "ALARM!") { super(ALARM); this.message = message; } ... }

A melhor maneira de criar uma classe de objeto de evento personalizada definir uma classe que estende a classe Event, como mostrou o exemplo anterior. Para complementar a funcionalidade herdada, a classe AlarmEvent define uma propriedade message que contm o texto da mensagem de alarme associada ao evento; o valor de message transmitido como um parmetro no construtor AlarmEvent. A classe AlarmEvent tambm define a constante ALARM, que pode ser usada para fazer referncia ao evento especfico (alarm) ao chamar o mtodo addEventListener() da classe AlarmClock. Alm de adicionar a funcionalidade personalizada, cada subclasse de Event deve substituir o mtodo clone() herdado como parte da estrutura de manipulao de eventos do ActionScript. As subclasses de Event tambm podem substituir o mtodo toString() herdado para incluir as propriedades do evento personalizado no valor retornado quando o mtodo toString() chamado.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Manipulao de eventos

140

/** * Creates and returns a copy of the current instance. * @return A copy of the current instance. */ public override function clone():Event { return new AlarmEvent(message); } /** * Returns a String containing all the properties of the current * instance. * @return A string representation of the current instance. */ public override function toString():String { return formatToString("AlarmEvent", "type", "bubbles", "cancelable", "eventPhase", "message"); }

O mtodo clone() substitudo precisa retornar uma nova ocorrncia da subclasse personalizada de Event, com todas as propriedades personalizadas definidas para corresponder ocorrncia atual. No mtodo toString() substitudo, o mtodo de utilitrio formatToString() (herdado de Event) usado para fornecer uma string com o nome do tipo personalizado, bem como nomes e valores de todas as propriedades.

ltima atualizao em 29/3/2011

141

Captulo 8: Trabalhar com domnios de aplicativo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O objetivo da classe ApplicationDomain armazenar uma tabela de definies do ActionScript 3.0. Todo cdigo em um arquivo SWF definido para estar presente em um domnio de aplicativo. Domnios de aplicativo so usados para particionar classes que esto no mesmo domnio de segurana. Eles permitem que haja vrias definies da mesma classe e permitem que filhos reutilizem definies de pai. possvel usar domnios de aplicativo carregando um arquivo SWF externo escrito no ActionScript 3.0 usando a API da classe Loader. (Observe que no possvel usar domnios de aplicativo ao carregar uma imagem ou arquivo SWF no ActionScript 1.0 ou no ActionScript 2.0.) Todas as definies do ActionScript 3.0 contidas na classe carregada so armazenadas no domnio do aplicativo. Ao carregar o arquivo SWF, possvel especificar que o arquivo seja includo no mesmo domnio do aplicativo que o objeto Loader, definindo o parmetro applicationDomain do objeto LoaderContext como ApplicationDomain.currentDomain. Colocando o arquivo SWF carregado no mesmo domnio de aplicativo, possvel acessar suas classes diretamente. Isso poder ser til se estiver carregando um arquivo SWF contendo mdia incorporada que permita acesso por meio de nomes de classes associadas ou se voc desejar acessar os mtodos do arquivo SWF carregado. O exemplo a seguir parte da premissa de que ele tem acesso para separar o arquivo Greeter.swf que define um mtodo pblico denominado welcome():

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalhar com domnios de aplicativo

142

package { import import import import import import

flash.display.Loader; flash.display.Sprite; flash.events.*; flash.net.URLRequest; flash.system.ApplicationDomain; flash.system.LoaderContext;

public class ApplicationDomainExample extends Sprite { private var ldr:Loader; public function ApplicationDomainExample() { ldr = new Loader(); var req:URLRequest = new URLRequest("Greeter.swf"); var ldrContext:LoaderContext = new LoaderContext(false, ApplicationDomain.currentDomain); ldr.contentLoaderInfo.addEventListener(Event.COMPLETE, completeHandler); ldr.load(req, ldrContext); } private function completeHandler(event:Event):void { var myGreeter:Class = ApplicationDomain.currentDomain.getDefinition("Greeter") as Class; var myGreeter:Greeter = Greeter(event.target.content); var message:String = myGreeter.welcome("Tommy"); trace(message); // Hello, Tommy } } }

Consulte tambm Exemplo de classe ApplicationDomain da Referncia do ActionScript 3.0 para a plataforma Adobe Flash. Outras coisas que devem ser lembradas ao trabalhar com domnios de aplicativos incluem:

Todo cdigo em um arquivo SWF definido para estar presente em um domnio de aplicativo. O domnio atual
onde seu aplicativo principal executado. O domnio do sistema contm todos os domnios de aplicativos, incluindo o domnio atual, o que significa que ele contm todas as classes do Flash Player.

Todos os domnios de aplicativos, exceto o domnio do sistema, tm um domnio-pai associado. O domnio-pai do

domnio do aplicativo principal o domnio do sistema. As classes carregadas s so definidas quando o pai ainda no as definiu. Voc no pode substituir uma definio de classe loaded por uma definio mais recente. O diagrama a seguir mostra um aplicativo que carrega contedo de vrios arquivos SWF dentro de um nico domnio, domain1.com. Dependendo do contedo carregado, diferentes domnios de aplicativos podem ser usados. O texto a seguir descreve a lgica usada para definir o domnio apropriado do aplicativo para cada arquivo SWF no aplicativo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalhar com domnios de aplicativo

143

Palco

Domnio de segurana: domain1.com

Domnio de aplicativo 1 application1.swf mx.core.Application module1.swf Loader Aplicativo Loader Loader Loader Mdulo Mdulo Domnio de aplicativo 3 module3.swf
C B

Domnio de aplicativo 2 mx.core.Application application2.swf Mdulo

A. Uso A B. Uso B C. Uso C

O arquivo do aplicativo principal application1.swf. Ele contm objetos Loader que carregam contedo de outros arquivos SWF. Neste cenrio, o domnio atual o Domnio do aplicativo 1. Uso A, uso B e uso C ilustram diferentes tcnicas para configurar o domnio do aplicativo apropriado para cada arquivo SWF em um aplicativo.
Uso A Particionar o arquivo SWF filho criando um filho do domnio do sistema. No diagrama, o Domnio do

aplicativo 2 criado como um filho do domnio do sistema. O arquivo application2.swf carregado no Domnio do aplicativo 2 e suas definies de classe so portanto particionadas a partir das classes definidas no application1.swf. Um dos usos dessa tcnica fazer com que um aplicativo antigo carregue uma verso mais nova do mesmo aplicativo sem conflito. No h conflito porque, embora os mesmos nomes de classes sejam usados, elas so particionadas em diferentes domnios de aplicativo. O cdigo a seguir cria um domnio de aplicativo que filho do domnio do sistema, e comea carregando um SWF usando esse domnio de aplicativo:
var appDomainA:ApplicationDomain = new ApplicationDomain(); var contextA:LoaderContext = new LoaderContext(false, appDomainA); var loaderA:Loader = new Loader(); loaderA.load(new URLRequest("application2.swf"), contextA);

Uso B: Adicione novas definies de classe s definies de classe atuais. O domnio do aplicativo do module1.swf definido como o domnio atual (Domnio do aplicativo 1). Isso permite adicionar o conjunto atual de aplicativos das definies de classes com novas definies de classes. Isso pode ser usado para uma biblioteca de tempo de execuo do aplicativo principal. O SWF carregado tratado como uma RSL (biblioteca remota compartilhada). Use essa tcnica para carregar RSLs por meio de um pr-carregador antes do incio do aplicativo.

O cdigo a seguir carrega um SWF definindo seu domnio de aplicativo para o domnio atual:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalhar com domnios de aplicativo

144

var appDomainB:ApplicationDomain = ApplicationDomain.currentDomain; var contextB:LoaderContext = new LoaderContext(false, appDomainB); var loaderB:Loader = new Loader(); loaderB.load(new URLRequest("module1.swf"), contextB);

Uso C: Use as definies de classes pai criando um novo domnio filho do domnio atual. O domnio do aplicativo do module3.swf filho do domnio atual, e o filho usa as verses de todas as classes do pai. Um uso dessa tcnica pode ser um mdulo de um RIA (aplicativo de Internet avanado) de vrias telas, carregado como um filho do aplicativo principal que usa os tipos do aplicativo principal. Se voc puder garantir que todas as classes so sempre atualizadas para serem compatveis com verses anteriores e que o aplicativo carregado sempre mais novo do que as coisas que ele carrega, os filhos usaro as verses do pai. Ter um novo domnio de aplicativo tambm permite descarregar todas as definies de classe para coleta de lixo, se voc puder garantir que referncias ao SWF filho no continuam a existir.

Essa tcnica permite que mdulos carregados compartilhem os objetos singleton do carregador e membros da classe esttica. O cdigo a seguir cria um novo domnio filho do domnio atual e inicia o carregamento de um SWF usando aquele domnio de aplicativo:
var appDomainC:ApplicationDomain = new ApplicationDomain(ApplicationDomain.currentDomain); var contextC:LoaderContext = new LoaderContext(false, appDomainC); var loaderC:Loader = new Loader(); loaderC.load(new URLRequest("module3.swf"), contextC);

ltima atualizao em 29/3/2011

145

Captulo 9: Programao de exibio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os elementos visuais so programados no Adobe ActionScript 3.0 funcionando com objetos de exibio no palco correspondente. Por exemplo, voc pode adicionar, mover, remover e solicitar objetos de exibio, aplicar filtros e mscaras, desenhar grficos de vetores e bitmap, e realizar transformaes em trs dimenses usando a API de programao da exibio do ActionScript. As classes primrias utilizadas para programao de exibio so parte do pacote flash.display. Nota: O Adobe AIR fornece o objeto HTMLoader para renderizar e exibir o contedo em HTML. O HTMLLoader renderiza os elementos visuais do DOM HTML como um nico objeto de exibio. Voc no pode acessar os elementos individuais do DOM diretamente atravs da hierarquia da lista de exibio do ActionScript. Em vez disso, voc acessa esses elementos DOM usando a API DOM separada fornecida pelo HTMLLoader.

Noes bsicas sobre a programao de exibio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Cada aplicativo desenvolvido no ActionScript 3.0 tem uma hierarquia de objetos exibidos, conhecida como lista de exibio, apresentada a seguir. A lista de exibio contm todos os elementos visveis do aplicativo.
Palco Stage

Ocorrncia da classe principal do arquivo SWF

Objeto Display

Continer do objeto Display

Continer do objeto Display

Objeto Display

Continer do objeto Display

Objeto Display

Continer do objeto Display

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

146

Conforme mostrado na ilustrao, os elementos de exibio podem pertencer a um ou mais dos seguintes grupos:

O Palco
O Palco o continer bsico de objetos de exibio. Cada aplicativo tem um objeto Stage, que contm todos os objetos de exibio da tela. O Palco o continer de nvel superior e est no topo da hierarquia da lista de exibio: Cada arquivo SWF tem uma classe ActionScript associada, conhecida como a classe principal do arquivo SWF. Quando um arquivo SWF aberto no Flash Player ou no Adobe AIR, o Flash Player ou o AIR chama a funo do construtor dessa classe, e a ocorrncia criada (que sempre um tipo do objeto de exibio) adicionada como filho do objeto Stage. A classe principal de um arquivo SWF sempre amplia a classe Sprite (para obter mais informaes, consulte Vantagens da abordagem da lista de exibio na pgina 150). Voc pode acessar o palco por meio da propriedade stage de qualquer ocorrncia de DisplayObject. Para obter mais informaes, consulte Configurao de propriedades do palco na pgina 159.

Objetos de exibio
No ActionScript 3.0, todos os elementos que aparecem na tela de um aplicativo so tipos de objetos de exibio. O pacote flash.display contm uma classe DisplayObject, que uma classe-base estendida por uma srie de outras classes. Essas classes diferentes representam tipos diferentes de objetos de exibio, como formas vetoriais, clipes de filme e campos de texto, entre outros. Para obter uma viso geral dessas classes, consulte Vantagens da abordagem da lista de exibio na pgina 150.

Contineres de objeto de exibio

Os contineres so tipos especiais de objeto de exibio que, alm de ter sua prpria representao visual, podem conter objetos filho que tambm so objetos de exibio. A classe DisplayObjectContainer uma subclasse da classe DisplayObject. Um objeto DisplayObjectContainer pode conter vrios objetos de exibio em sua lista defilhos. Por exemplo, a ilustrao a seguir mostra um tipo de objeto DisplayObjectContainer conhecido como Sprite que contm vrios objetos de exibio:
A

A. Um objeto SimpleButton. Esse tipo de objeto de exibio tem estados up, down e over diferentes. B. Um objeto Bitmap. Nesse caso, o objeto Bitmap foi carregado a partir de um JPEG externo por meio de um objeto Loader. C. Um objeto Shape. O quadro de imagem contm um retngulo arredondado que desenhado no ActionScript. Esse objeto Shape tem o filtro Sombra projetada aplicado. D. Um objeto TextField.

No mbito da discusso sobre objetos de exibio, os objetos DisplayObjectContainer tambm so conhecidos como contineres de objeto de exibio ou simplesmente contineres. Conforme mencionado anteriormente, o palco um continer de objetos de exibio.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

147

Embora todos os objetos de exibio visveis sejam herdados da classe DisplayObject, o tipo de cada um de uma subclasse especfica da classe DisplayObject. Por exemplo, existe uma funo de construtor para as classes Shape ou Video, mas no existe nenhum funo assim para a classe DisplayObject. Conceitos e termos importantes A lista de referncia a seguir contm termos importantes que voc vai encontrar ao conhecer o grfico de programao do ActionScript:
Alfa O valor de cor que representa a quantidade de transparncia (melhor dizendo, a quantidade de opacidade) de uma cor. Por exemplo, uma cor com um canal alfa de 60% mostra apenas 60% de sua intensidade total e 40% transparente. Grfico de bitmap Um elemento grfico que definido no computador como uma grade (linhas e colunas) de pixels

coloridos. Em geral, os grficos de bitmap incluem fotos digitais e imagens similares.

Modo de mesclagem Uma especificao de como o contedo de duas imagens sobrepostas deve interagir.

Normalmente, uma imagem opaca em cima de outra imagem simplesmente bloqueia a imagem subjacente para que no fique visvel. No entanto, modos de mesclagem diferentes fazem com que as cores das imagens se misturem de formas diferentes, de modo que o contedo resultante uma combinao das duas imagens.
Lista de exibio A hierarquia de objetos de exibio que ser renderizada como o contedo visvel na tela pelo Flash

Player e pelo AIR. O palco a raiz da lista de exibio e todos os objetos de exibio anexados ao palco ou a um de seus filhos formam a lista de exibio (mesmo que o objeto no seja realmente renderizado, por exemplo, se estiver fora dos limites do palco).
Objeto de exibio Um objeto que representa algum tipo de contedo visual no Flash Player ou no AIR. Apenas objetos de exibio podem ser includos na lista de exibio e todas as classes desses objetos so subclasses de DisplayObject. Continer do objeto de exibio Um tipo especial de objeto de exibio que pode conter objetos de exibio filhos

alm de (geralmente) ter sua prpria representao visual.

Classe principal do arquivo SWF A classe que define o comportamento do objeto de exibio mais externo de um arquivo SWF e que, conceitualmente, a classe do prprio arquivo SWF. Por exemplo, em um SWF criado com autoria em Flash, a classe principal a classe document. Ela contm uma linha do tempo principal que contm todas as outras linhas do tempo; a classe principal do arquivo SWF a classe da qual a linha do tempo principal uma ocorrncia. Mascaramento Tcnica para ocultar algumas partes de uma imagem (ou de exibir apenas algumas partes da imagem).

As partes mascaradas da imagem ficam transparentes, de modo que o contedo subjacente exibido. O termo est relacionado fita isolante do pintor que usada para impedir que algumas reas sejam pintadas.
Palco O continer visual que a base ou o plano de fundo de todo o contedo visual de um SWF. Transformao Ajuste de uma caracterstica visual de um grfico como a rotao do objeto, a alterao da escala, a

inclinao ou distoro da forma ou a alterao da cor.

Grfico vetorial Elemento grfico que definido no computador como linhas e formas desenhadas com caractersticas

especficas (como espessura, comprimento, tamanho, ngulo e posio).

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

148

Principais classes de exibio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O pacote flash.display do ActionScript 3.0 inclui classes para objetos visuais que podem aparecer no Flash Player ou no AIR. A ilustrao a seguir mostra as relaes de subclasse dessas classes principais de objeto de exibio.
DisplayObject

AVM1Movie

Bitmap

InteractiveObject

MorphShape

Shape

StaticText

Video

DisplayObjectContainer SimpleButton

TextField

Loader

Sprite

Stage

MovieClip

A ilustrao mostra a herana das classes de objeto de exibio. Algumas dessas classes, especificamente StaticText, TextField e Video, no esto no pacote flash.display, mas ainda so herdadas da classe DisplayObject. Todas as classes derivadas de DisplayObject herdam seus mtodos e propriedades. Para obter mais informaes, consulte Propriedades e mtodos da classe DisplayObject na pgina 152. possvel percorrer os objetos das seguintes classes contidas no pacote flash.display:

Bitmap - A classe Bitmap pode ser usada para definir objetos de bitmap, carregados a partir de arquivos externos
ou renderizados pelo ActionScript. possvel carregar bitmaps a partir de arquivos externos por meio da classe Loader. possvel carregar arquivos GIF, JPG ou PNG. Alm disso, voc pode criar um objeto BitmapData com dados personalizados e criar um objeto Bitmap que usa esses dados. Voc pode usar os mtodos da classe BitmapData para alterar bitmaps, sejam eles carregados ou criados no ActionScript. Para obter mais informaes, consulte Carregamento de objetos de exibio na pgina 192 e Trabalho com bitmaps na pgina 235.

Loader - A classe Loader pode ser usada para carregar ativos externos (arquivos SWF ou elementos grficos). Para
obter mais informaes, consulte Carregamento dinmico do contedo da exibio na pgina 192.

Shape - A classe Shape pode ser usada para criar grficos vetoriais, como retngulos, linhas, crculos e assim por
diante. Para obter mais informaes, consulte Uso da API de desenho na pgina 214.

SimpleButton - Um objeto SimpleButton a representao do ActionScript do smbolo de um boto criado com a

ferramenta de autoria do Flash. Uma ocorrncia de SimpleButton tem quatro estados de boto: para cima, para baixo, por cima e teste de ocorrncia (a rea que responde aos eventos de mouse e de teclado).

Sprite - Um objeto Sprite pode conter grficos prprios e objetos de exibio filho. A classe Sprite estende a classe
DisplayObjectContainer. Para obter mais informaes, consulte Trabalho com contineres de objeto de exibio na pgina 153 e Uso da API de desenho na pgina 214.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

149

MovieClip - Um objeto MovieClip a forma atribuda pelo ActionScript a um smbolo de clipe de filme criado com
a ferramenta de autoria do Flash. Na prtica, o objeto MovieClip similar a um objeto Sprite, mas tambm tem uma linha do tempo. Para obter mais informaes, consulte Trabalho com clipes de filme na pgina 316. As classes a seguir, que no esto no pacote flash.display, so subclasses de DisplayObject:

A classe TextField, includa no pacote flash.text, um objeto de exibio para entrada e exibio de texto. Para obter
mais informaes, consulte Princpios bsicos do trabalho com texto na pgina 356.

A classe TextLine, includa no pacote flash.text.engine, o objeto de exibio usado para exibir linhas de texto
compostas pelo Flash Text Engine e pelo Text Layout Framework. Para obter mais informaes, consulte Uso do Flash Text Engine na pgina 383 e Uso da Text Layout Framework na pgina 413.

A classe Video, includa no pacote flash.media, um objeto de exibio usado para exibir arquivos de vdeo. Para
obter mais informaes, consulte Trabalho com vdeo na pgina 462. As seguintes classes do pacote flash.display estendem a classe DisplayObject, mas no possvel criar ocorrncias delas. Em vez disso, elas servem como classes pai para outros objetos de exibio, combinando funcionalidades comuns em uma nica classe.

AVM1Movie - A classe AVM1Movie usada para representar arquivos SWF carregados que so criados no
ActionScript 1.0 e 2.0.

DisplayObjectContainer - As classes Loader, Stage, Sprite e MovieClip estendem a classe DisplayObjectContainer.

Para obter mais informaes, consulte Trabalho com contineres de objeto de exibio na pgina 153.

InteractiveObject - InteractiveObject a classe base de todos os objetos usados para interagir com o mouse e o
teclado. Os objetos SimpleButton, TextField, Loader, Sprite, Stage e MovieClip so subclasses de InteractiveObject. Para obter mais informaes sobre como criar a interao do mouse e do teclado, consulte Princpios bsicos da interao do usurio na pgina 537.

MorphShape - Esses objetos so criados quando voc cria uma interpolao de forma na ferramenta de criao do
Flash. No possvel percorr-los usando o ActionScript, mas possvel acess-los a partir da lista de exibio.

Stage - A classe Stage estende a classe DisplayObjectContainer. Existe uma ocorrncia de Stage em cada aplicativo,
que fica no topo da hierarquia da lista de exibio. Para acessar o palco, use a propriedade stage de qualquer ocorrncia de DisplayObject. Para obter mais informaes, consulte Configurao de propriedades do palco na pgina 159. Alm disso, a classe StaticText do pacote flash.text estende a classe DisplayObject, mas no possvel criar uma ocorrncia dela no cdigo. Os campos de texto esttico s podem ser criados no Flash. As classes a seguir no so objetos de exibio nem contineres de objeto de exibio, e no constam da lista de exibio, apesar de exibirem elementos grficos no palco. Essas classes desenham em um retngulo, chamado viewport, posicionado relativamente ao palco.

StageVideo A classe StageVideo exibe contedo de vdeo usando acelerao de hardware, quando possvel. Essa
classe est disponvel a partir do Flash Player 10.2 e do AIR 2.5 (no AIR para perfis de TV). Para mais informaes, consulte Utilizando a classe StageVideo para renderizao acelerada por hardware na pgina 499.

StageWebView A classe StageWebView exibe contedo HTML. Esta classe est disponvel a partir do AIR 2.5.
Para obter mais informaes, consulte Objetos StageWebView na pgina 1016.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

150

Vantagens da abordagem da lista de exibio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior No ActionScript 3.0, existem classes separadas para diferentes tipos de objeto de exibio. No ActionScript 1.0 e 2.0, muitos objetos do mesmo tipo so includos em uma classe: a classe MovieClip. Essa individualizao de classes e a estrutura hierrquica das listas de exibio tm as seguintes vantagens:

Renderizao mais eficiente e menos uso da memria Melhor gerenciamento de profundidade Profundidade completa da lista de exibio Objetos de exibio fora da lista Facilidade de subclassificao dos objetos de exibio

Renderizao mais eficiente e arquivos menores

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior No ActionScript 1.0 e 2.0, voc pode desenhar formas somente em um objeto MovieClip. No ActionScript 3.0, existem classes de objeto de exibio mais simples nas quais possvel desenhar formas. Como essas classes de objeto de exibio do ActionScript 3.0 no incluem um conjunto completo de mtodos e propriedades como o objeto MovieClip, consomem menos recursos da memria e do processador. Por exemplo, cada objeto MovieClip inclui propriedades para a linha do tempo do clipe de filme, enquanto o objeto Shape no faz isso. As propriedades de gerenciamento da linha do tempo podem usar muitos recursos da memria e do processador. No ActionScript 3.0, usar o objeto Shape melhora o desempenho. O objeto Shape tem uma sobrecarga menor do que o objeto MovieClip mais complexo. O Flash Player e o AIR no precisam gerenciar propriedades MovieClip no utilizadas, o que melhora a velocidade e reduz a memria usada pelo objeto.

Melhor gerenciamento de profundidade

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior No ActionScript 1.0 e 2.0, a profundidade era gerenciada por um esquema linear e mtodos como getNextHighestDepth(). O ActionScript 3.0 inclui a classe DisplayObjectContainer, que tem mtodos e propriedades mais prticos para gerenciar a profundidade dos objetos de exibio. No ActionScript 3.0, ao mover um objeto de exibio para uma nova posio da lista de filhos de uma ocorrncia de DisplayObjectContainer, os outros filhos do continer de objeto de exibio so reposicionados automaticamente e designados nas posies de ndice secundrias apropriadas no continer. Alm disso, no ActionScript 3.0, sempre possvel detectar todos os objetos filho de qualquer continer de objeto de exibio. Cada ocorrncia de DisplayObjectContainer tem uma propriedade numChildren, que lista o nmero de filhos no continer de objeto de exibio. Como a lista de filhos de um continer de objeto de exibio sempre uma lista indexada, voc pode examinar todos os objetos da lista desde a posio 0 at a ltima posio de ndice (numChildren - 1). Isso no era possvel com os mtodos e as propriedades de um objeto MovieClip no ActionScript 1.0 e no 2.0.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

151

No ActionScript 3.0, voc pode percorrer com facilidade a lista de exibio na seqncia; no existe nenhuma falha nos nmeros de ndice de uma lista de filhos de um continer de objeto de exibio. Percorrer a lista de exibio e gerenciar a profundidade dos objetos muito mais fcil do que o que era permitido no ActionScript 1.0 e 2.0. No ActionScript 1.0 e 2.0, um clipe de filme podia ter objetos com lacunas intermitentes na ordem de profundidade, o que dificultava percorrer a lista de objetos. No ActionScript 3.0, cada lista de filhos de um continer de objeto de exibio armazenada em cache internamente como uma matriz, resultando em consultas muito rpidas (por ndice). Percorrer todos os filhos de um continer de objeto de exibio tambm muito rpido. No ActionScript 3.0, voc tambm pode acessar os filhos de um continer de objeto de exibio usando o mtodo getChildByName() da classe DisplayObjectContainer.

Profundidade completa da lista de exibio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior No ActionScript 1.0 e 2.0, no era possvel acessar alguns objetos, como formas vetoriais, que eram desenhados na ferramenta de criao do Flash. No ActionScript 3.0, voc pode acessar todos os objetos da lista de exibio - os criados com o ActionScript e todos os objetos criados na ferramenta de criao do Flash. Para obter detalhes, consulte Como percorrer a lista de exibio na pgina 157.

Objetos de exibio fora da lista

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior No ActionScript 3.0, voc pode criar objetos que no esto na lista de exibio visvel. So os chamados objetos de exibio fora da lista. Um objeto de exibio adicionado lista visvel somente quando voc chama o mtodo addChild() ou addChildAt() de uma ocorrncia de DisplayObjectContainer que j foi adicionada lista de exibio. Voc pode usar objetos de exibio fora da lista para montar objetos complexos, como os que tm vrios contineres com vrios objetos de exibio. Mantendo os objetos de exibio fora da lista, voc pode montar objetos complicados sem usar o tempo de processamento para renderizar esses objetos de exibio. Em seguida, voc pode adicionar um objeto fora da lista lista de exibio quando necessrio. Alm disso, possvel mover um filho de um continer de objeto de exibio na lista e fora dela e para qualquer posio desejada.

Facilidade de subclassificao dos objetos de exibio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior No ActionScript 1.0 e 2.0, voc tinha que adicionar com freqncia novos objetos MovieClip a um arquivo SWF para criar formas bsicas ou exibir bitmaps. No ActionScript 3.0, a classe DisplayObject inclui muitas subclasses internas, como Shape e Bitmap. Como as classes do ActionScript 3.0 so mais especializadas para tipos especficos de objetos, mais fcil criar subclasses bsicas das classes internas. Por exemplo, para desenhar um crculo no ActionScript 2.0, era necessrio criar uma classe CustomCircle que estende a classe MovieClip quando um objeto da classe personalizada percorrido. No entanto, essa classe tambm inclua diversos mtodos e propriedades da classe MovieClip (como totalFrames) no apropriados. No ActionScript 3.0, entretanto, possvel criar uma classe CustomCircle que estende o objeto Shape e, desse modo, no inclui mtodos e propriedades no relacionados que esto contidos na classe MovieClip. O cdigo a seguir mostra um exemplo de uma classe CustomCircle:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

152

import flash.display.*; public class CustomCircle extends Shape { var xPos:Number; var yPos:Number; var radius:Number; var color:uint; public function CustomCircle(xInput:Number, yInput:Number, rInput:Number, colorInput:uint) { xPos = xInput; yPos = yInput; radius = rInput; color = colorInput; this.graphics.beginFill(color); this.graphics.drawCircle(xPos, yPos, radius); } }

Trabalho com os objetos de exibio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Agora que voc j conhece os conceitos bsicos de palco, objetos de exibio, contineres de objeto de exibio e lista de exibio, esta seo fornece informaes mais especficas sobre como trabalhar com objetos de exibio no ActionScript 3.0.

Propriedades e mtodos da classe DisplayObject

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Todos os objetos de exibio so subclasses de DisplayObject e, como tal, herda as propriedades e os mtodos da classe DisplayObject. As propriedades herdadas so bsicas e se aplicam a todos os objetos de exibio. Por exemplo, cada objeto de exibio tem uma propriedade x e uma propriedade y que especifica a posio do objeto no continer. No possvel criar uma ocorrncia de DisplayObject usando o construtor da classe DisplayObject. Voc deve criar outro tipo de objeto (que seja uma subclasse de DisplayObject), como Sprite, para percorrer um objeto com o operador new. Alm disso, se desejar criar uma classe personalizada de objeto de exibio, voc deve criar uma subclasse de uma das subclasses que tm uma funo de construtor til (como a classe Shape ou a classe Sprite). Para obter mais informaes, consulte descrio de classeDisplayObject em Referncia do ActionScript 3.0 para a plataforma Adobe Flash.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

153

Adio de objetos de exibio lista de exibio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Ao ser percorrido, o objeto de exibio no aparece na tela (no palco) at que voc adicione a ocorrncia desse objeto a um continer que est na lista de exibio. Por exemplo, no cdigo a seguir, o objeto TextField myText no ficaria visvel se a ltima linha do cdigo fosse omitida. Na ltima linha do cdigo, a palavra-chave this deve fazer referncia a um continer j adicionado lista de exibio.
import flash.display.*; import flash.text.TextField; var myText:TextField = new TextField(); myText.text = "Buenos dias."; this.addChild(myText);

Quando algum elemento visual adicionado ao palco, esse elemento se transforma em filho do objeto Stage. O primeiro arquivo SWF carregado em um aplicativo (por exemplo, aquele incorporado em uma pgina HTML) adicionado automaticamente como filho do objeto Stage. Pode ser um objeto de qualquer tipo que estende a classe Sprite. Todos os objetos de exibio criados sem o ActionScript (por exemplo, por meio da insero de uma tag MXML em um arquivo Flex MXML ou da colocao de um item no Palco no Flash Professional) so adicionados lista de exibio. Embora esses objetos de exibio no sejam adicionados por meio do ActionScript, possvel acess-los usando o ActionScript. Por exemplo, o cdigo a seguir ajusta a largura de um objeto chamado button1 que foi inserido na ferramenta de criao (no por meio do ActionScript):
button1.width = 200;

Trabalho com contineres de objeto de exibio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Se um objeto DisplayObjectContainer for excludo da lista de exibio, ou movido ou transformado de algum modo, cada objeto de exibio de DisplayObjectContainer tambm ser excludo, movido ou transformado. Um continer um tipo de objeto de exibio propriamente dito e pode ser adicionado a outro continer. Por exemplo, a imagem a seguir mostra um continer de objeto de exibio, pictureScreen, que tem uma forma de contorno e outros quatro contineres (do tipo PictureFrame):

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

154

A. Uma forma que define a borda do continer de objeto de exibio pictureScreen B. Quatro contineres de objeto de exibio que so filhos do objeto pictureScreen

Para que um objeto aparea na lista de exibio, voc deve adicion-lo a um continer que esteja na lista. Para fazer isso, use o mtodo addChild() ou o mtodo addChildAt() do objeto de continer. Por exemplo, sem a linha final do cdigo a seguir, o objeto myTextField no seria exibido:
var myTextField:TextField = new TextField(); myTextField.text = "hello"; this.root.addChild(myTextField);

Nesse exemplo de cdigo, this.root aponta para o continer de objeto de exibio MovieClip que tem o cdigo. No seu cdigo real, voc pode especificar um continer diferente.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

155

Use o mtodo addChildAt() para adicionar o filho a uma posio especfica na lista de filhos do continer de objeto de exibio. Essas posies de ndice baseadas em zero da lista de filhos esto relacionadas disposio em camadas (ordem da frente para trs) dos objetos de exibio. Por exemplo, considere os trs objetos de exibio a seguir. Cada objeto foi criado a partir de uma classe personalizada chamada Ball.

A disposio em camadas desses objetos de exibio no continer pode ser ajustada com o mtodo addChildAt(). Por exemplo, considere o seguinte cdigo:
ball_A = new Ball(0xFFCC00, "a"); ball_A.name = "ball_A"; ball_A.x = 20; ball_A.y = 20; container.addChild(ball_A); ball_B = new Ball(0xFFCC00, "b"); ball_B.name = "ball_B"; ball_B.x = 70; ball_B.y = 20; container.addChild(ball_B); ball_C = new Ball(0xFFCC00, "c"); ball_C.name = "ball_C"; ball_C.x = 40; ball_C.y = 60; container.addChildAt(ball_C, 1);

Depois que este cdigo executado, os objetos de exibio so posicionados do seguinte modo no objeto DisplayObjectContainer do continer. Observe a disposio em camadas dos objetos.

Para reposicionar um objeto na parte superior da lista de exibio, basta adicion-lo novamente lista. Por exemplo, depois do cdigo anterior, para mover ball_A at a parte superior da pilha, use esta linha do cdigo:
container.addChild(ball_A);

Este cdigo remove ball_A por completo do seu local na lista de exibio do continer e o adicionam novamente parte superior da lista, que equivale a mov-lo at a parte superior da pilha.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

156

Voc pode usar o mtodo getChildAt() para verificar a ordem de camadas dos objetos de exibio. O mtodo getChildAt() retorna objetos filho de um continer com base no nmero de ndice fornecido. Por exemplo, o cdigo a seguir revela nomes de objetos de exibio em posies diferentes da lista de filhos do objeto DisplayObjectContainer do continer:
trace(container.getChildAt(0).name); // ball_A trace(container.getChildAt(1).name); // ball_C trace(container.getChildAt(2).name); // ball_B

Se voc remover um objeto de exibio da lista de filhos do continer pai, os elementos superiores da lista sero movidos para uma posio inferior no ndice filho. Por exemplo, continuando com o cdigo anterior, o cdigo a seguir mostra como o objeto de exibio que estava na posio 2 no DisplayObjectContainer do continer ser movido para a posio 1 se um objeto de exibio inferior da lista de filhos for removido:
container.removeChild(ball_C); trace(container.getChildAt(0).name); // ball_A trace(container.getChildAt(1).name); // ball_B

Os mtodos removeChild() e removeChildAt() no excluem uma ocorrncia de objeto de exibio por completo. Eles simplesmente a removem da lista de filhos do continer. A ocorrncia ainda pode ser mencionada por outra varivel. Use o operador delete para remover um objeto por completo. Como um objeto de exibio tem apenas um continer pai, voc pode adicionar uma ocorrncia de um objeto de exibio a somente um continer. Por exemplo, o cdigo a seguir mostra que o objeto de exibio tf1 pode existir em apenas um continer (nesse caso, um Sprite, que estende a classe DisplayObjectContainer):
tf1:TextField = new TextField(); tf2:TextField = new TextField(); tf1.name = "text 1"; tf2.name = "text 2"; container1:Sprite = new Sprite(); container2:Sprite = new Sprite(); container1.addChild(tf1); container1.addChild(tf2); container2.addChild(tf1); trace(container1.numChildren); // 1 trace(container1.getChildAt(0).name); // text 2 trace(container2.numChildren); // 1 trace(container2.getChildAt(0).name); // text 1

Se voc adicionar um objeto de exibio que est contido em um continer a outro continer, esse objeto ser removido da lista de filhos do primeiro continer. Alm dos mtodos descritos acima, a classe DisplayObjectContainer define vrios mtodos para trabalhar com objetos de exibio filho, incluindo os seguintes:

contains(): determina se um objeto de exibio filho de DisplayObjectContainer. getChildByName(): recupera um objeto de exibio por nome. getChildIndex(): retorna a posio de ndice de um objeto de exibio. setChildIndex(): altera a posio de um objeto de exibio filho. swapChildren(): alterna a ordem de frente para trs de dois objetos de exibio.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

157

swapChildrenAt(): alterna a ordem de frente para trs de dois objetos de exibio, especificados pelos valores de

ndice. Para obter mais informaes, consulte os respectivos itens na Referncia do ActionScript 3.0 para a plataforma Adobe Flash. Lembre-se de que um objeto de exibio que est fora da lista (no includo em um continer de objeto de exibio que filho do objeto Stage) conhecido como objeto de exibio fora da lista.

Como percorrer a lista de exibio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Como voc observou, a lista de exibio uma estrutura de rvore. Na parte superior da rvore est o palco, que pode conter vrios objetos de exibio. Esses objetos que so contineres propriamente ditos podem ter outros objetos de exibio ou contineres.
Palco Stage

Ocorrncia da classe principal do arquivo SWF

Objeto Display

Continer do objeto Display

Continer do objeto Display

Objeto Display

Continer do objeto Display

Objeto Display

Continer do objeto Display

A classe DisplayObjectContainer inclui propriedades e mtodos para percorrer a lista de exibio por meio das listas de filhos dos contineres de objeto de exibio. Por exemplo, considere o cdigo a seguir, que adiciona dois objetos de exibio, title e pict, ao objeto container (que um Sprite; a classe Sprite estende a classe DisplayObjectContainer):

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

158

var container:Sprite = new Sprite(); var title:TextField = new TextField(); title.text = "Hello"; var pict:Loader = new Loader(); var url:URLRequest = new URLRequest("banana.jpg"); pict.load(url); pict.name = "banana loader"; container.addChild(title); container.addChild(pict);

O mtodo getChildAt() retorna o filho da lista de exibio em uma posio de ndice especfica:
trace(container.getChildAt(0) is TextField); // true

Voc tambm pode acessar objetos filho por nome. Cada objeto de exibio tem uma propriedade de nome e, se voc no design-la, o Flash Player ou AIR atribuir um valor padro, como "instance1". Por exemplo, o cdigo a seguir mostra como usar o mtodo getChildByName() para acessar um objeto de exibio filho com o nome "banana loader":
trace(container.getChildByName("banana loader") is Loader); // true

O mtodo getChildByName() piora mais o desempenho do que o mtodo getChildAt(). Como um continer de objeto de exibio pode ter outros contineres como objetos filho em sua lista de exibio, possvel percorrer a lista inteira do aplicativo como uma rvore. Por exemplo, no trecho de cdigo mostrado anteriormente, assim que a operao de carregamento do objeto pict Loader for concluda, o objeto pict ter um objeto de exibio filho, que o bitmap carregado. Para acessar esse objeto de exibio de bitmap, voc pode gravar pict.getChildAt(0). Voc tambm pode gravar container.getChildAt(0).getChildAt(0) (visto que container.getChildAt(0) == pict). A funo a seguir fornece uma sada trace() pretendida da lista de exibio a partir de um continer:
function traceDisplayList(container:DisplayObjectContainer,indentString:String = ""):void { var child:DisplayObject; for (var i:uint=0; i < container.numChildren; i++) { child = container.getChildAt(i); trace(indentString, child, child.name); if (container.getChildAt(i) is DisplayObjectContainer) { traceDisplayList(DisplayObjectContainer(child), indentString + "") } } }

Adobe Flex O Flex, caso voc o utilize, define muitas classes de objeto de exibio e essas classes substituem os mtodos de acesso lista de exibio da classe DisplayObjectContainer. Por exemplo, a classe Container do pacote mx.core substitui o mtodo addChild() e outros mtodos da classe DisplayObjectContainer (estendida pela classe Container). No caso do mtodo addChild(), a classe substitui o mtodo de tal forma que no possvel adicionar todos os tipos de objeto de exibio a uma ocorrncia de Container no Flex. O mtodo substitudo, nesse caso, exige que o objeto filho que est sendo adicionado seja do tipo mx.core.UIComponent.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

159

Configurao de propriedades do palco

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe Stage substitui a maioria das propriedades e dos mtodos da classe DisplayObject. Se um desses mtodos ou propriedades substitudos for chamado, o Flash Player e o AIR lanaro uma exceo. Por exemplo, o objeto Stage no tem as propriedades x ou y, pois sua posio fixa como o principal continer do aplicativo. As propriedades x e y fazem referncia posio de um objeto de exibio com relao ao seu continer e, como o objeto Stage no est contido em nenhum outro continer, essas propriedades no so aplicveis. Nota: Alguns mtodos e propriedades da classe Stage esto disponveis somente para objetos de exibio que esto na mesma caixa de proteo de segurana do primeiro arquivo SWF carregado. Para obter detalhes, consulte segurana de Palco na pgina 1050.

Controle da taxa de quadros de reproduo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A propriedade frameRate da classe Stage usada para definir a taxa de quadros de todos os arquivos SWF carregados no aplicativo. Para obter mais informaes, consulte Referncia do ActionScript 3.0 para a plataforma Adobe Flash.

Controle do dimensionamento do palco

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Quando a parte da tela que representa o Flash Player ou o AIR redimensionada, o tempo de execuo ajusta automaticamente o contedo do palco para compensar. A propriedade scaleMode da classe Stage determina como o contedo do palco ajustado. Essa propriedade pode ter quatro valores diferentes, definidos como constantes na classe flash.display.StageScaleMode:

StageScaleMode.EXACT_FIT dimensiona o SWF de modo a preencher as novas dimenses do palco sem levar em conta a proporo original do contedo. Os fatores de escala podem no ser os mesmos para largura e altura, o que pode fazer com que o contedo parea espremido ou alongado se a proporo do palco for alterada. StageScaleMode.SHOW_ALL dimensiona o SWF para faz-lo caber inteiramente nas novas dimenses do palco

sem alterar a proporo do contedo. Este modo de escala exibe todo o contedo, mas pode resultar em bordas letterbox, como as barras pretas exibidas durante a exibio de um filme em widescreen em uma televiso padro.

StageScaleMode.NO_BORDER dimensiona o SWF de modo a preencher completamente as novas dimenses do

palco sem alterar a proporo do contedo. Este modo de escala faz uso total da rea de exibio do palco, mas pode resultar em cortes.

StageScaleMode.NO_SCALE no dimensiona o SWF. Se as novas dimenses do palco forem menores, o contedo ser cortado; se forem maiores, o espao adicionado ficar em branco.

Somente no modo de escala StageScaleMode.NO_SCALE, as propriedades stageWidth e stageHeight da classe Stage podem ser usadas para determinar as dimenses de pixel reais do palco redimensionado. Nos outros modos de escala, as propriedades stageWidth e stageHeight sempre refletem a largura e a altura originais do SWF. Alm disso, quando scaleMode definido como StageScaleMode.NO_SCALE e o arquivo SWF redimensionado, o evento resize da classe Stage enviado e permite fazer os ajustes adequados.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

160

Conseqentemente, definir scaleMode como StageScaleMode.NO_SCALE permite que voc tenha mais controle sobre o ajuste do contedo da tela para redimensionar a janela se desejar. Por exemplo, em um arquivo SWF que contm um vdeo e uma barra de controle, voc talvez queira que a barra de controle permanea do mesmo tamanho quando o palco for redimensionado e apenas o tamanho da janela do vdeo seja alterado para acomodar o novo tamanho do palco. Isso demonstrado no exemplo a seguir:
// videoScreen is a display object (e.g. a Video instance) containing a // video; it is positioned at the top-left corner of the Stage, and // it should resize when the SWF resizes. // // // // controlBar is a display object (e.g. a Sprite) containing several buttons; it should stay positioned at the bottom-left corner of the Stage (below videoScreen) and it should not resize when the SWF resizes. flash.display.Stage; flash.display.StageAlign; flash.display.StageScaleMode; flash.events.Event;

import import import import

var swfStage:Stage = videoScreen.stage; swfStage.scaleMode = StageScaleMode.NO_SCALE; swfStage.align = StageAlign.TOP_LEFT; function resizeDisplay(event:Event):void { var swfWidth:int = swfStage.stageWidth; var swfHeight:int = swfStage.stageHeight; // Resize the video window. var newVideoHeight:Number = swfHeight - controlBar.height; videoScreen.height = newVideoHeight; videoScreen.scaleX = videoScreen.scaleY; // Reposition the control bar. controlBar.y = newVideoHeight; } swfStage.addEventListener(Event.RESIZE, resizeDisplay);

Definio do modo de dimensionamento do palco para as janelas do AIR A propriedade de palco scaleMode determina como o palco dimensionado e corta os objetos de exibio filho quando uma janela redimensionada. Apenas o modo noScale deve ser usado no AIR. Nesse modo, o palco no dimensionado. Ao contrrio, o tamanho do palco muda diretamente os limites da janela. Os objetos podem ser cortados se a janela for redimensionada para um tamanho menor. Os modos de dimensionamento de palco so criados para serem usados em ambientes como um navegador de Web, no qual voc nem sempre pode controlar o tamanho ou a proporo de aspecto do palco. Os modos permitem que voc faa a escolha mais adequada quando o palco no corresponde ao tamanho ideal nem proporo de aspecto do seu aplicativo. No AIR, voc sempre tem controle do palco de modo que, na maioria dos casos, a nova disposio do contedo ou o ajuste das dimenses na janela proprocionar melhores resultados do que ativar o dimensionamento do palco.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

161

No navegador e na janela inicial do AIR, a relao entre o tamanho da janela e o fator de escala inicial lida do arquivo SWF carregado. Entretanto, quando voc cria um objeto NativeWindow, o AIR escolhe uma relao arbitrria entre o tamanho da janela e o fator de escala 72:1. Portanto, se a sua janela tem 72x72 pixels, um retngulo de 10x10 adicionado janela desenhado no tamanho correto de 10x10 pixels. Entretanto, se a janela tiver 144x144 pixels, um retngulo de 10x10 pixels ser dimensionado para 20x20 pixels. Se voc insistir em usar um scaleMode que no seja noScale para o palco de uma janela, poder compensar definindo o fator de escala de qualquer objeto de exibio da janela na proporo de 72 pixels para a largura e a altura atuais do palco. Por exemplo, o cdigo a seguir calcula o fator de escala necessrio para um objeto de exibio denominado client:
if(newWindow.stage.scaleMode != StageScaleMode.NO_SCALE){ client.scaleX = 72/newWindow.stage.stageWidth; client.scaleY = 72/newWindow.stage.stageHeight; }

Nota: As janelas Flex e HTML definem automaticamente o palco scaleMode como noScale. Alterar o scaleMode perturba os mecanismos automticos de layout usados nesses tipos de janelas.

Trabalho com o modo de tela cheia

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O modo de tela cheia permite que voc configure o palco de um filme para preencher todo o monitor do visualizador, sem nenhuma borda ou menu de continer. A propriedade displayState da classe Stage usada para ativar e desativar o modo de tela cheia para um SWF. A propriedade displayState pode ser configurada como um dos valores definidos pelas constantes da classe flash.display.StageDisplayState. Para ativar o modo de tela cheia, defina a propriedade displayState como StageDisplayState.FULL_SCREEN:
stage.displayState = StageDisplayState.FULL_SCREEN;

No Flash Player, o modo de tela cheia s pode ser iniciado por meio do ActionScript em resposta a um clique do mouse (incluindo o clique com o boto direito) ou pressionamento de tecla. O contedo do AIR em execuo na caixa de proteo de segurana do aplicativo no requer a ativao do modo de tela cheia em resposta a um gesto do usurio. Para ativar o modo de tela cheia, defina a propriedade displayState como StageDisplayState.NORMAL.
stage.displayState = StageDisplayState.NORMAL;

Alm disso, o usurio pode optar por sair do modo de tela cheia alternando o foco para outra janela ou usando uma de vrias combinaes de tecla: a tecla Esc (todas as plataformas), Control-W (Windows), Command-W (Mac) ou AltF4 (Windows). Ativao do modo de tela cheia no Flash Player Para ativar o modo de tela cheia para um arquivo SWF incorporado a uma pgina HTML, o cdigo HTML a ser incorporado ao Flash Player deve incluir uma tag param e o atributo embed com o nome allowFullScreen e o valor true, do seguinte modo:
<object> ... <param name="allowFullScreen" value="true" /> <embed ... allowfullscreen="true" /> </object>

Na ferramenta de autoria do Flash, selecione Arquivo -> Configuraes de publicao e, na aba HTML da caixa de dilogo Configuraes de publicao, selecione o modelo Somente Flash - Permitir tela cheia.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

162

No Flex, verifique se o modelo HTML inclui as tags <object> e <embed> que do suporte a tela cheia. Se estiver usando JavaScript em uma pgina da Web para gerar as tags incorporadas no SWF, altere o JavaScript para adicionar a tag allowFullScreen param e o atributo. Por exemplo, se a pgina HTML usa a funo AC_FL_RunContent() (que usada pelas pginas HTML geradas pelo Flash Professional e pelo Flash Builder), adicione o parmetro allowFullScreen a essa chamada de funo do seguinte modo:
AC_FL_RunContent( ... 'allowFullScreen','true', ... ); //end AC code

Isso no se aplica aos arquivos SWF em execuo no Flash Player autnomo. Nota: Se voc definir o Modo de janela (wmode no HTML) como Opaco sem janela (opaco) ou Transparente sem janela (transparente), a janela da tela cheia ser sempre opaca O uso do modo de tela cheia com o Flash Player em um navegador tambm apresenta restries de segurana. Essas restries esto descritas em Segurana na pgina 1027. Tamanho do palco e dimensionamento em tela cheia As propriedades Stage.fullScreenHeight e Stage.fullScreenWidth retornam a altura e a largura do monitor utilizado quando se passa para o tamanho de tela cheia, caso a entrada nesse estado ocorra imediatamente. Esses valores podero estar incorretos se o usurio tiver a oportunidade de mudar o navegador de um monitor para outro depois que voc recuper-los, mas antes de entrar no modo de tela cheia. Se voc recuperar esses valores no mesmo manipulador de eventos em que definiu a propriedade Stage.displayState como StageDisplayState.FULL_SCREEN, eles estaro corretos. No caso de usurios que tm diversos monitores, o contedo SWF se expande para ocupar apenas um monitor. O Flash Player e o AIR usam uma mtrica para determinar qual monitor contm a maior parte do SWF e usam esse monitor para o modo de tela cheia. As propriedades fullScreenHeight e fullScreenWidth refletem apenas o tamanho do monitor usado no modo de tela cheia. Para obter mais informaes, consulte Stage.fullScreenHeight e Stage.fullScreenWidth em Referncia do ActionScript 3.0 para a plataforma Adobe Flash. O comportamento de dimensionamento do palco para o modo de tela cheia igual ao de um modo normal; o dimensionamento controlado pela propriedade scaleMode da classe Stage. Se a propriedade scaleMode estiver definida como StageScaleMode.NO_SCALE, as propriedades stageWidth e stageHeight da classe Stage sero alteradas para refletir o tamanho da rea da tela ocupado pelo SWF (a tela inteira, nesse caso); se for visualizado no navegador, o parmetro HTML controlar a configurao. Voc pode usar o evento fullScreen da classe Stage para detectar e responder quando o modo de tela cheia est ativado ou desativado. Por exemplo, voc talvez queira reposicionar, adicionar ou remover itens da tela ao acessar ou sair do modo de tela cheia, como mostra este exemplo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

163

import flash.events.FullScreenEvent; function fullScreenRedraw(event:FullScreenEvent):void { if (event.fullScreen) { // Remove input text fields. // Add a button that closes full-screen mode. } else { // Re-add input text fields. // Remove the button that closes full-screen mode. } } mySprite.stage.addEventListener(FullScreenEvent.FULL_SCREEN, fullScreenRedraw);

Como mostra este cdigo, o objeto do evento fullScreen uma ocorrncia da classe flash.events.FullScreenEvent, que inclui uma propriedade fullScreen que indica se o modo de tela cheia est ativado (true) ou no (false). Suporte para teclado no modo de tela cheia Quando o Flash Player executado em um navegador, todo ActionScript relacionado ao teclado, como eventos de teclado e entrada de texto nas ocorrncias de TextField, desativado no modo de tela cheia. As excees (as teclas que ficam ativadas) so estas:

Teclas selecionadas que no so impressas, especificamente as teclas de seta, a barra de espao e a tecla Tab Os atalhos de teclado que encerram o modo de tela cheia: Esc (Windows e Mac), Control-W (Windows),
Command-W (Mac) e Alt-F4 Essas restries no se aplicam a contedo SWF em execuo no Flash Player independente ou no AIR. O AIR d suporte a um modo de tela cheia interativa que permite entrada do teclado. Dimensionamento em hardware no modo de tela cheia Voc pode usar a propriedade fullScreenSourceRect da classe Stage para configurar o Flash Player ou o AIR para dimensionar uma regio especfica do palco no modo de tela cheia. O Flash Player e o AIR fazem dimensionamento em hardware, se possvel, usando a placa grfica e de vdeo do computador de um usurio, e geralmente exibe contedo mais rapidamente do que no dimensionamento em software. Para tirar vantagem do dimensionamento em hardware, defina o palco inteiro ou parte dele para o modo de tela cheia. O cdigo ActionScript 3.0 a seguir define o palco inteiro para o modo de tela cheia:
import flash.geom.*; { stage.fullScreenSourceRect = new Rectangle(0,0,320,240); stage.displayState = StageDisplayState.FULL_SCREEN; }

Quando essa propriedade definida como um retngulo vlido e a propriedade displayState definida como o modo de tela cheia o Flash Player e o AIR dimensionam a rea especificada. O tamanho real do Palco em pixels no ActionScript no alterado. O Flash Player e o AIR foram um limite mnimo para o tamanho do retngulo de forma a acomodar a mensagem padro "Pressione Esc para sair do modo de tela cheia". Em geral, esse limite est em torno de 260 por 30 pixels, mas pode variar de acordo com a plataforma e a verso do Flash Player.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

164

A propriedade fullScreenSourceRect s pode ser definida quando o Flash Player ou AIR no est no modo de tela cheia. Para usar esta propriedade corretamente, defina-a primeiro e, em seguida, defina a propriedade displayState para o modo de tela cheia. Para ativar o dimensionamento, defina a propriedade fullScreenSourceRect como um objeto de retngulo.
stage.fullScreenSourceRect = new Rectangle(0,0,320,240);

Para desativar o dimensionamento, defina a propriedade fullScreenSourceRect como null.

stage.fullScreenSourceRect = null;

Para aproveitar todos os recursos de acelerao de hardware com o Flash Player, ative-a na caixa de dilogo Configuraes do Flash Player. Para carregar a caixa de dilogo, clique com o boto direito do mouse (Windows) ou clique mantendo a tecla Control pressionada (Mac) dentro do contedo Flash Player exibido no navegador. Selecione a aba Exibir, que a primeira, e clique na caixa de seleo: Habilitar acelerao de hardware. Modos de janela direto e de composio GPU O Flash Player 10 introduz dois modos de janela (direto e composio GPU) que voc pode ativar atravs das configuraes de publicao da ferramenta de autoria do Flash. Esses modos no so suportados no AIR. Para aproveitar as vantagens desses modos, voc deve ativar a acelerao de hardware para o Flash Player. O modo direto usa o caminho mais rpido e direto para enviar grficos para a tela, o que vantajoso para a reproduo de vdeos. A Composio GPU usa a unidade de processamento grfico da placa de vdeo para acelerar a composio. A composio de vdeo o processo de dispor vrias imagens em camadas para criar uma nica imagem de vdeo. Quando a composio acelerada com a GPU, ela pode melhorar o desempenho de converso YUV, correo de cores, rotao ou dimensionamento e mesclagem. Converso YUV refere-se converso de cores de sinais analgicos compostos, que so usados para transmisso, no modelo de cores RGB (vermelho, verde, azul) usado por monitores e cmeras de vdeo. O uso da GPU para acelerar a composio reduz as demandas de memria e de computao que, de outro modo, seriam atribudas CPU. Ele tambm resulta em uma reproduo mais contnua para vdeo com definio padro. Seja cauteloso na implementao desses modos de janela. O uso da composio GPU pode ser dispendioso para a memria e os recursos da CPU. Se no for possvel executar algumas operaes (como modos de mesclagem, filtragem, corte ou mascaramento) na GPU, elas sero feitas pelo software. A Adobe recomenda que voc se restrinja a um arquivo SWF por pgina HTML quando usar esses modos e que no ative esses modos para banners. O recurso Testar filme do Flash no utiliza acelerao de hardware, mas voc pode us-la atravs da opo Publicar visualizao. intil configurar uma taxa de quadros superior a 60 no arquivo SWF, que a taxa mxima de atualizao da tela. Configurar a taxa de quadros com um valor entre 50 e 55 viabiliza quadros descartados, que podem ocorrer por vrios motivos de tempos em tempos. O uso do modo direto exige o Microsoft DirectX 9 com 128 MB de VRAM no Windows e OpenGL para Apple Macintosh, Mac OS X v10.2 ou superior. A composio GPU exige o Microsoft DirectX 9 e suporte para Pixel Shader 2.0 no Windows com 128 MB de VRAM. No Mac OS X e no Linux, a composio GPU exige o OpenGL 1.5 e vrias extenses OpenGL (objeto framebuffer, multitextura, objetos Shader, linguagem de sombreamento, sombreador de fragmentos). possvel ativar os modos de acelerao direto e gpu por arquivo SWF na caixa de dilogo Configuraes de publicao do Flash usando o menu Acelerao de hardware da aba Flash. Se voc clicar em Nenhum, o modo de janela voltar para padro, transparente ou opaco, conforme especificado pela configurao Modo de janela na aba HTML.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

165

Manipulao de eventos de objetos de exibio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe DisplayObject herdada da classe EventDispatcher. Desse modo, todos os objetos de exibio podem participar plenamente no modelo de evento (descrito em Manipulao de eventos na pgina 118). Todos os objetos de exibio podem usar seu mtodo addEventListener() (herdado da classe EventDispatcher) para ouvir um evento especfico, mas somente se o objeto ouvinte fizer parte do fluxo desse evento. Quando o Flash Player ou o AIR envia um objeto de evento, esse objeto faz uma viagem de ida e volta do palco at o objeto de exibio onde ocorreu o evento. Por exemplo, se o usurio clicar em um objeto de exibio chamado child1, o Flash Player enviar um objeto de evento do palco, por meio da hierarquia da lista de exibio, at o objeto de exibio child1. O fluxo do evento conceitualmente dividido em trs fases, como mostra este diagrama:
Palco Fase de captura N pai Fase de animao

N filho1 Fase de destino

N filho2

Para obter mais informaes, consulte Manipulao de eventos na pgina 118. Uma questo importante que deve ser considerada ao trabalhar com eventos de objeto de exibio o efeito que os ouvintes de evento podem ter quando os objetos de exibio removidos automaticamente da memria (lixo coletado) forem removidos da lista de exibio. Se um objeto de exibio tiver objetos inscritos como ouvintes de eventos, esse objeto no ser removido da memria mesmo quando for removido da lista de exibio, pois ainda ter referncias a esses objetos de ouvinte. Para obter mais informaes, consulte Gerenciamento de ouvintes de evento na pgina 132.

Escolha de uma subclasse de DisplayObject

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Com tantas opes disponveis, ao trabalhar com objetos de exibio, uma das decises importantes definir qual objeto ser usado para cada finalidade. Veja algumas diretrizes que podem ajud-lo a tomar essa deciso. Essas mesmas sugestes podem ser usadas quando voc precisa de uma ocorrncia de uma classe ou est escolhendo uma base para criar uma classe:

Se voc no precisar de um objeto que possa ser continer de outros objetos de exibio (isto , precisar de apenas
um que sirva como um elemento de tela autnomo), escolha uma dessas subclasses de DisplayObject ou InteractiveObject, dependendo do uso pretendido:

Bitmap para exibir uma imagem de bitmap. TextField para adicionar texto. Video para exibir vdeo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

166

Shape para uma tela de desenho para desenhar o contedo na tela. Especificamente, se desejar criar uma
ocorrncia para desenhar formas na tela que no ser continer de outros objetos de exibio, use Shape em vez de Sprite ou MovieClip para melhorar o desempenho significativamente.

MorphShape, StaticText ou SimpleButton para itens criados com a ferramenta de autoria do Flash. No
possvel criar ocorrncias dessas classes de modo programtico, mas voc pode criar variveis com esses tipos de dados para fazer referncia aos itens criados com a ferramenta da autoria do Flash.

Se precisar de uma varivel para fazer referncia ao palco principal, use a classe Stage como tipo de dados. Se precisar de um continer para carregar um arquivo SWF ou de imagem externo, use uma ocorrncia de Loader.
O contedo carregado ser adicionado lista de exibio como filho da ocorrncia de Loader. O tipo de dados depende da natureza do contedo carregado, do seguinte modo:

Uma imagem carregada ser uma ocorrncia do Bitmap. Um arquivo SWF carregado gravado no ActionScript 3.0 ser uma ocorrncia de Sprite ou MovieClip (ou uma
ocorrncia de uma subclasse dessas classes, conforme especificado pelo criador do contedo).

Um arquivo SWF carregado gravado no ActionScript 1.0 ou no ActionScript 2.0 ser uma ocorrncia de
AVM1Movie.

Se precisar de um objeto para servir como continer de outros objetos de exibio (esteja voc desenhando ou no
no objeto de exibio com o ActionScript), escolha uma das subclasses de DisplayObjectContainer:

Sprite se o objeto for criado apenas com o ActionScript ou como a classe base de um objeto de exibio
personalizado que ser criado e manipulado somente com o ActionScript.

MovieClip se estiver criando uma varivel para fazer referncia a um smbolo de clipe de filme criado na
ferramenta de criao do Flash.

Se estiver criando uma classe que ser associada a um smbolo de clipe de filme na biblioteca do Flash, escolha uma
destas subclasses de DisplayObjectContainer como sua classe base:

MovieClip se o smbolo de clipe de filme associado tiver contedo em mais de um quadro Sprite se o smbolo de clipe de filme associado tiver contedo somente no primeiro quadro

Manipulao de objetos de exibio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Independentemente do objeto de exibio utilizado, existem diversas manipulaes comuns a todos os objetos de exibio que servem como elementos exibidos na tela. Por exemplo, todos podem ser posicionados na tela, movidos para frente ou para trs na ordem de empilhamento dos objetos de exibio, dimensionados, girados e assim por diante. Como todos os objetos de exibio herdam essa funcionalidade da classe base comum (DisplayObject), tal funcionalidade apresenta o mesmo comportamento demonstrado na manipulao de uma ocorrncia de TextField, de Video, de Shape ou de qualquer outro objeto de exibio. As sees a seguir descrevem em detalhes diversas manipulaes comuns de objeto de exibio.

Alterao da posio
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A manipulao mais bsica de qualquer objeto de exibio seu posicionamento na tela. Para definir a posio de um objeto de exibio, altere as propriedades x e y do objeto.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

167

myShape.x = 17; myShape.y = 212;

O sistema de posicionamento de objetos de exibio trata o palco como um sistema de coordenadas cartesianas (o sistema de grade comum com um eixo x horizontal e um eixo y vertical). A origem do sistema de coordenadas (a coordenada 0,0 onde os eixos x e y se encontram) est no canto superior esquerdo do palco. A partir desse ponto, os valores de x so positivos para a direita e negativos para a esquerda, enquanto (diferente dos sistemas grficos tpicos) os valores de y so positivos para baixo e negativos para cima. Por exemplo, as linhas anteriores do cdigo movem o objeto myShape at a coordenada 17 do eixo x (17 pixel direita da origem) e a coordenada 212 do eixo y (212 pixels abaixo da origem). Por padro, quando um objeto de exibio criado com o ActionScript, as propriedades x e y so definidas como 0, colocando o objeto no canto superior esquerdo do contedo pai.

Alterao da posio em relao ao palco

importante lembrar que as propriedades x e y sempre fazem referncia posio do objeto de exibio em relao coordenada 0,0 dos eixos do objeto de exibio pai. Assim, para uma ocorrncia de Shape (como um crculo) contida em uma ocorrncia de Sprite, se voc definir as propriedades x e y do objeto Shape como 0, o crculo ser colocado no canto superior esquerdo de Sprite, que no necessariamente o canto superior esquerdo do palco. Para posicionar um objeto em relao s coordenadas globais do palco, voc pode usar o mtodo globalToLocal() de qualquer objeto de exibio para converter coordenadas globais (palco) em locais (continer do objeto de exibio), do seguinte modo:
// Position the shape at the top-left corner of the Stage, // regardless of where its parent is located. // Create a Sprite, positioned at x:200 and y:200. var mySprite:Sprite = new Sprite(); mySprite.x = 200; mySprite.y = 200; this.addChild(mySprite); // Draw a dot at the Sprite's 0,0 coordinate, for reference. mySprite.graphics.lineStyle(1, 0x000000); mySprite.graphics.beginFill(0x000000); mySprite.graphics.moveTo(0, 0); mySprite.graphics.lineTo(1, 0); mySprite.graphics.lineTo(1, 1); mySprite.graphics.lineTo(0, 1); mySprite.graphics.endFill(); // Create the circle Shape instance. var circle:Shape = new Shape(); mySprite.addChild(circle); // Draw a circle with radius 50 and center point at x:50, y:50 in the Shape. circle.graphics.lineStyle(1, 0x000000); circle.graphics.beginFill(0xff0000); circle.graphics.drawCircle(50, 50, 50); circle.graphics.endFill(); // Move the Shape so its top-left corner is at the Stage's 0, 0 coordinate. var stagePoint:Point = new Point(0, 0); var targetPoint:Point = mySprite.globalToLocal(stagePoint); circle.x = targetPoint.x; circle.y = targetPoint.y;

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

168

Do mesmo modo, voc pode usar o mtodo localToGlobal() da classe DisplayObject para converter coordenadas locais em coordenadas do palco.

Movimento de objetos de exibio com o mouse

Voc pode permitir que um usurio movimente objetos de exibio com o mouse, utilizando duas tcnicas diferentes no ActionScript. Em ambos os casos, dois eventos de mouse so usados: quando o boto do mouse pressionado, o objeto acionado para seguir o cursor do mouse e, quando solto, o objeto deve parar de segui-lo. A primeira tcnica, usando o mtodo startDrag(), mais simples, porm mais limitada. Quando o boto do mouse pressionado, o mtodo startDrag() do objeto de exibio a ser arrastado chamado. Quando o boto do mouse solto, o mtodo stopDrag() chamado. A classe Sprite define essas duas funes. Portanto, o objeto movimentado deve ser um Sprite ou uma de suas subclasses.
// This code creates a mouse drag interaction using the startDrag() // technique. // square is a MovieClip or Sprite instance). import flash.events.MouseEvent; // This function is called when the mouse button is pressed. function startDragging(event:MouseEvent):void { square.startDrag(); } // This function is called when the mouse button is released. function stopDragging(event:MouseEvent):void { square.stopDrag(); } square.addEventListener(MouseEvent.MOUSE_DOWN, startDragging); square.addEventListener(MouseEvent.MOUSE_UP, stopDragging);

Essa tcnica tem uma limitao bem significativa: somente um item por vez pode ser arrastado com startDrag(). Se um objeto de exibio estiver sendo arrastado e o mtodo startDrag() for chamado em outro objeto de exibio, o primeiro objeto deixar de seguir o mouse imediatamente. Por exemplo, se a funo startDragging() for alterada conforme mostrado aqui, somente o objeto circle ser arrastado, apesar da chamada do mtodo square.startDrag():
function startDragging(event:MouseEvent):void { square.startDrag(); circle.startDrag(); }

Como apenas um objeto pode ser arrastado por vez com startDrag(), o mtodo stopDrag() pode ser chamado em qualquer objeto de exibio e pra sempre que o objeto est sendo arrastado.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

169

Se precisar arrastar mais de um objeto de exibio ou para evitar a possibilidade de conflitos quando houver mais de um objeto que provavelmente use startDrag(), melhor usar a tcnica de acompanhamento do mouse para criar o efeito de desenho. Com essa tcnica, quando o boto do mouse pressionado, uma funo inscrita como ouvinte no evento mouseMove do palco. Essa funo, que chamada sempre que o mouse se move, faz com que o objeto arrastado passe para a coordenada x, y do mouse. Assim que o boto do mouse solto, a funo deixa de ser ouvinte, ou seja, no ser mais chamada quando o mouse se movimentar, e o objeto pra de acompanhar o cursor do mouse. Veja um cdigo que demonstra essa tcnica:
// This code moves display objects using the mouse-following // technique. // circle is a DisplayObject (e.g. a MovieClip or Sprite instance). import flash.events.MouseEvent; var offsetX:Number; var offsetY:Number; // This function is called when the mouse button is pressed. function startDragging(event:MouseEvent):void { // Record the difference (offset) between where // the cursor was when the mouse button was pressed and the x, y // coordinate of the circle when the mouse button was pressed. offsetX = event.stageX - circle.x; offsetY = event.stageY - circle.y; // tell Flash Player to start listening for the mouseMove event stage.addEventListener(MouseEvent.MOUSE_MOVE, dragCircle); } // This function is called when the mouse button is released. function stopDragging(event:MouseEvent):void { // Tell Flash Player to stop listening for the mouseMove event. stage.removeEventListener(MouseEvent.MOUSE_MOVE, dragCircle); } // This function is called every time the mouse moves, // as long as the mouse button is pressed down. function dragCircle(event:MouseEvent):void { // Move the circle to the location of the cursor, maintaining // the offset between the cursor's location and the // location of the dragged object. circle.x = event.stageX - offsetX; circle.y = event.stageY - offsetY; // Instruct Flash Player to refresh the screen after this event. event.updateAfterEvent(); } circle.addEventListener(MouseEvent.MOUSE_DOWN, startDragging); circle.addEventListener(MouseEvent.MOUSE_UP, stopDragging);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

170

Alm de fazer com que um objeto de exibio acompanhe o cursor do mouse, muitas vezes desejvel mover o objeto arrastado at a frente da exibio para que aparea flutuando acima de todos os outros objetos. Por exemplo, suponha que voc tenha dois objetos, um crculo e um quadrado, que possam ser movimentados com o mouse. Se o crculo ficar abaixo do quadrado na lista de exibio e voc clicar e arrastar o crculo para que o cursor fique por cima do quadrado, ir parecer que o crculo desliza ao lado do quadrado, quebrando a iluso de arrastar e soltar. Em vez disso, voc pode definir que, quando for clicado, o crculo deve se mover para cima da lista de exibio e, assim, sempre aparecer em cima de qualquer outro contedo. O cdigo a seguir (adaptado do exemplo anterior) permite que dois objetos de exibio, um crculo e um quadrado, sejam movimentados com o mouse. Sempre que o boto do mouse pressionado em um deles, esse item movido para a parte superior da lista de exibio do palco para que o item arrastado sempre aparea por cima. (O cdigo novo ou alterado com relao listagem anterior exibido em negrito.)
// // // // This code creates a drag-and-drop interaction using the mouse-following technique. circle and square are DisplayObjects (e.g. MovieClip or Sprite instances).

import flash.display.DisplayObject; import flash.events.MouseEvent; var offsetX:Number; var offsetY:Number; var draggedObject:DisplayObject; // This function is called when the mouse button is pressed. function startDragging(event:MouseEvent):void { // remember which object is being dragged draggedObject = DisplayObject(event.target); // Record the difference (offset) between where the cursor was when // the mouse button was pressed and the x, y coordinate of the // dragged object when the mouse button was pressed. offsetX = event.stageX - draggedObject.x; offsetY = event.stageY - draggedObject.y; // move the selected object to the top of the display list stage.addChild(draggedObject); // Tell Flash Player to start listening for the mouseMove event. stage.addEventListener(MouseEvent.MOUSE_MOVE, dragObject); } // This function is called when the mouse button is released. function stopDragging(event:MouseEvent):void { // Tell Flash Player to stop listening for the mouseMove event. stage.removeEventListener(MouseEvent.MOUSE_MOVE, dragObject); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

171

// This function is called every time the mouse moves, // as long as the mouse button is pressed down. function dragObject(event:MouseEvent):void { // Move the dragged object to the location of the cursor, maintaining // the offset between the cursor's location and the location // of the dragged object. draggedObject.x = event.stageX - offsetX; draggedObject.y = event.stageY - offsetY; // Instruct Flash Player to refresh the screen after this event. event.updateAfterEvent(); } circle.addEventListener(MouseEvent.MOUSE_DOWN, startDragging); circle.addEventListener(MouseEvent.MOUSE_UP, stopDragging); square.addEventListener(MouseEvent.MOUSE_DOWN, startDragging); square.addEventListener(MouseEvent.MOUSE_UP, stopDragging);

Para estender esse efeito ainda mais, como para um jogo onde pinos ou cartas so movidos entre pilhas, voc pode adicionar o objeto arrastado lista de exibio do palco quando for tirado e adicion-lo a outra lista de exibio (como a pilha onde solto) quando o boto do mouse for liberado. Finalmente, para aprimorar o efeito, voc poderia aplicar um filtro de sombra projetada no objeto de exibio quando for clicado (quando comear a ser arrastado) e remover a sombra projetada quando o objeto for solto. Para obter detalhes sobre como usar o filtro de sombra projetada e outros filtros de objeto de exibio no ActionScript, consulte Filtro de objetos de exibio na pgina 259.

Viso panormica e rolagem de objetos de exibio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Se houver um objeto de exibio muito grande para a rea na qual deseja exibi-lo, voc pode usar a propriedade scrollRect para definir a rea visvel do objeto de exibio. Alm disso, alterando a propriedade scrollRect em resposta entrada do usurio, voc pode obter uma viso panormica do contedo esquerda e direita e percorrer para cima e para baixo. A propriedade scrollRect uma ocorrncia da classe Rectangle, que combina os valores necessrios para definir uma rea retangular como um nico objeto. Para definir inicialmente a rea visvel do objeto de exibio, crie uma nova ocorrncia de Rectangle e a atribua propriedade scrollRect do objeto de exibio. Posteriormente, para percorrer ou obter a viso panormica, leia a propriedade scrollRect em uma varivel separada de Rectangle e altere a propriedade desejada (por exemplo, altere a propriedade x da ocorrncia de Rectangle para obter a viso panormica ou a propriedade y para percorrer). Em seguida, atribua novamente essa ocorrncia de Rectangle propriedade scrollRect para notificar o objeto de exibio do valor alterado. Por exemplo, o cdigo a seguir define a rea visvel de um objeto TextField chamado bigText que muito pequeno para se adaptar nos limites do arquivo SWF. Quando so clicados, os dois botes chamados up e down chamam funes que fazem com que o contedo do objeto TextField se movimente para cima ou para baixo, modificando a propriedade y da ocorrncia scrollRect de Rectangle.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

172

import flash.events.MouseEvent; import flash.geom.Rectangle; // Define the initial viewable area of the TextField instance: // left: 0, top: 0, width: TextField's width, height: 350 pixels. bigText.scrollRect = new Rectangle(0, 0, bigText.width, 350); // Cache the TextField as a bitmap to improve performance. bigText.cacheAsBitmap = true; // called when the "up" button is clicked function scrollUp(event:MouseEvent):void { // Get access to the current scroll rectangle. var rect:Rectangle = bigText.scrollRect; // Decrease the y value of the rectangle by 20, effectively // shifting the rectangle down by 20 pixels. rect.y -= 20; // Reassign the rectangle to the TextField to "apply" the change. bigText.scrollRect = rect; } // called when the "down" button is clicked function scrollDown(event:MouseEvent):void { // Get access to the current scroll rectangle. var rect:Rectangle = bigText.scrollRect; // Increase the y value of the rectangle by 20, effectively // shifting the rectangle up by 20 pixels. rect.y += 20; // Reassign the rectangle to the TextField to "apply" the change. bigText.scrollRect = rect; } up.addEventListener(MouseEvent.CLICK, scrollUp); down.addEventListener(MouseEvent.CLICK, scrollDown);

Como este exemplo ilustra, ao trabalhar com a propriedade scrollRect de um objeto de exibio, melhor especificar que o Flash Player ou o AIR deve armazenar em cache o contedo do objeto de exibio como um bitmap, usando a propriedade cacheAsBitmap. Ao fazer isso, o Flash Player e o AIR no precisam redesenhar o contedo inteiro do objeto de exibio sempre que for movido e, assim, podem usar o bitmap em cache para renderizar a parte necessria diretamente na tela. Para obter detalhes, consulte Armazenamento em cache de objetos de exibio na pgina 175.

Manipulao do tamanho e dimensionamento de objetos

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior possvel medir e manipular o tamanho de um objeto de exibio de duas formas, usando as propriedades de dimenso (width e height) ou as propriedades de escala (scaleX e scaleY). Todo objeto de exibio tem uma propriedade width e uma propriedade height, que so definidas inicialmente como o tamanho do objeto em pixels. possvel ler os valores dessas propriedades para medir o tamanho do objeto de exibio. Voc tambm pode especificar novos valores para alterar o tamanho do objeto, do seguinte modo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

173

// Resize a display object. square.width = 420; square.height = 420; // Determine the radius of a circle display object. var radius:Number = circle.width / 2;

Se voc alterar a altura ou a largura de um objeto de exibio, esse objeto ser dimensionado, ampliando ou reduzindo seu contedo para ajust-lo na nova rea. Caso o objeto de exibio tenha apenas formas vetoriais, essas formas sero redesenhadas na nova escala, sem prejudicar a qualidade. Todos os elementos grficos de bitmap do objeto de exibio sero dimensionados, no redesenhados. Assim, por exemplo, uma foto digital cuja largura e altura so aumentadas alm das dimenses reais das informaes de pixels na imagem ser pixelizada, ficando irregular. Quando as propriedades width ou height de um objeto de exibio so alteradas, o Flash Player e o AIR tambm atualizam as propriedades scaleX e scaleY. Nota: Os objetos TextField so uma exceo a este comportamento de dimensionamento. Os campos de texto devem fazer o dimensionamento automtico para acomodar textos com quebra e tamanhos de fonte variados, fazendo com que os valores scaleX ou scaleY sejam redefinidos como 1 aps o redimensionamento. No entanto, se voc ajustar os valores scaleX ou scaleY de um objeto TextField, os valores de largura e altura sero alterados para acomodar os valores de dimensionamento especificados. Essas propriedades representam o tamanho relativo do objeto de exibio em comparao com o tamanho original. As propriedades scaleX e scaleY usam valores fracionrios (decimais) para representar porcentagens. Por exemplo, se a largura de um objeto de exibio for alterada para ter metade do tamanho original, a propriedade scaleX ter o valor .5, que indica 50%. Se a altura for dobrada, a propriedade scaleY ter o valor 2, que indica 200%.
// circle is a display object whose width and height are 150 pixels. // At original size, scaleX and scaleY are 1 (100%). trace(circle.scaleX); // output: 1 trace(circle.scaleY); // output: 1 // When you change the width and height properties, // Flash Player changes the scaleX and scaleY properties accordingly. circle.width = 100; circle.height = 75; trace(circle.scaleX); // output: 0.6622516556291391 trace(circle.scaleY); // output: 0.4966887417218543

As alteraes de tamanho no so proporcionais. Em outras palavras, e voc alterar a altura de um quadrado, mas no a largura, suas propores no sero mais as mesmas e o resultado ser um retngulo, em vez de um quadrado. Se desejar fazer alteraes relacionadas ao tamanho de um objeto de exibio, defina os valores das propriedades scaleX e scaleY para redimensionar o objeto, em vez de definir as propriedades width ou height. Por exemplo, este cdigo altera a largura do objeto de exibio chamado square e, em seguida, altera a escala vertical (scaleY) para corresponder escala horizontal, mantendo o tamanho proporcional do quadrado.
// Change the width directly. square.width = 150; // Change the vertical scale to match the horizontal scale, // to keep the size proportional. square.scaleY = square.scaleX;

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

174

Controle da distoro durante o dimensionamento

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Normalmente, quando um objeto de exibio dimensionado (por exemplo, ampliado na horizontal), a distoro resultante distribuda uniformemente no objeto, para que cada parte seja ampliada do mesmo modo. Para elementos grficos e de design, isso provavelmente o que se espera. No entanto, s vezes melhor ter controle sobre as partes do objeto de exibio que so ampliadas e as partes que permanecem inalteradas. Um exemplo comum disso um boto retangular com cantos arredondados. Com o dimensionamento normal, os cantos do boto so ampliados, alterando o raio do canto medida que o boto redimensionado.

No entanto, nesse caso seria melhor ter controle sobre o dimensionamento conseguir designar algumas reas que devem ser dimensionadas (lados retos e o centro) e outras que no devem (os cantos) para que o dimensionamento ocorra sem nenhuma distoro visvel.

Voc pode usar o dimensionamento de 9 fatias (Escala 9) para criar objetos de exibio cujo dimensionamento pode ser controlado. Com o dimensionamento de 9 fatias, o objeto de exibio dividido em 9 retngulos separados (uma grade 3 x 3, como a grade do jogo da velha). Os retngulos no so necessariamente do mesmo tamanho; voc pode desenhar onde as linhas da grade so colocadas. Todo contedo que estiver nos retngulos dos quatro cantos (como os cantos arredondados de um boto) no ser ampliado ou reduzido quando o objeto de exibio for dimensionado. Os retngulos centrais superior e inferior sero dimensionados na horizontal, no na vertical, enquanto os retngulos centrais esquerdo e direito sero dimensionados na vertical, no na horizontal. O retngulo central ser dimensionado tanto na horizontal quanto na vertical.

Com isso em mente, se estiver criando um objeto de exibio e desejar que um determinado contedo nunca seja dimensionado, verifique se as linhas divisrias da grade de dimensionamento de 9 fatias esto colocadas de modo que o contedo fique em um dos retngulos do canto. No ActionScript, definir um valor para a propriedade scale9Grid de um objeto de exibio ativa o dimensionamento de 9 fatias do objeto e define o tamanho dos retngulos na grade de escala 9 do objeto. Use uma ocorrncia da classe Rectangle como valor da propriedade scale9Grid, do seguinte modo:
myButton.scale9Grid = new Rectangle(32, 27, 71, 64);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

175

Os quatro parmetros do construtor de retngulo so a coordenada x, a coordenada y, a largura e a altura. Neste exemplo, o canto superior esquerdo do retngulo colocado no ponto x: 32, y: 27 no objeto de exibio chamado myButton. O retngulo tem 71 pixels de largura e 64 pixels de altura (de modo que a borda direita est na coordenada 103 do eixo x e a borda inferior est na coordenada 92 do eixo y no objeto de exibio).

A rea real contida na regio definida pela ocorrncia de Rectangle representa o retngulo central da grade de escala 9. Os outros retngulos so calculados pelo Flash Player e AIR, estendendo os lados da ocorrncia de Rectangle, conforme mostrado aqui:

Nesse caso, medida que o boto dimensionado para cima ou para baixo, os cantos arredondados no so ampliados ou reduzidos, mas as outras reas se ajustam de acordo com o dimensionamento.

A. myButton.width = 131;myButton.height = 106; B. myButton.width = 73;myButton.height = 69; C. myButton.width = 54;myButton.height = 141;

Armazenamento em cache de objetos de exibio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Sempre que estiver aumentando o tamanho no Flash, seja para criar um aplicativo ou animaes complexas com script, voc precisa levar em conta o desempenho e a otimizao. O Flash Player e o AIR no otimizam contedo que permanece esttico (como uma ocorrncia de Shape retangular). Desse modo, quando voc altera a posio do retngulo, o Flash Player ou o AIR redesenha a ocorrncia de Shape inteira. Voc pode armazenar os objetos de exibio especificados em cache para melhorar o desempenho do arquivo SWF. O objeto de exibio uma superfcie, basicamente uma verso de bitmap dos dados vetoriais da ocorrncia, que so os dados que no devem mudar muito durante o fluxo do arquivo SWF. Portanto, as ocorrncias com o cache ativado no so redesenhadas continuamente medida que o arquivo SWF reproduzido, o que aumenta a velocidade da renderizao. Nota: Voc pode atualizar os dados vetoriais e, quando isso feito, a superfcie recriada. Assim, os dados vetoriais armazenados em cache na superfcie no precisam permanecer iguais para todo o arquivo SWF.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

176

Se voc definir a propriedade cacheAsBitmap do objeto de exibio como true, o cache do objeto de exibio ser uma representao em bitmap do prprio objeto. O Flash Player ou o AIR criam um objeto de superfcie para a ocorrncia, que um bitmap armazenado em cache em vez de dados vetoriais. Se os limites do objeto de exibio forem alterados, a superfcie ser recriada em vez de ser redimensionada. As superfcies podem ser aninhadas com outras superfcies. A superfcie filho copia seu bitmap na superfcie pai. Para obter mais informaes, consulte Ativao do armazenamento em cache de bitmaps na pgina 177. A propriedade opaqueBackground e a propriedade scrollRect da classe DisplayObject esto relacionadas ao armazenamento em cache de bitmaps realizado com a propriedade cacheAsBitmap. Embora essas trs propriedades sejam independentes entre si, as propriedades opaqueBackground e scrollRect funcionam melhor quando um objeto armazenado em cache como um bitmap; voc ver a melhora de desempenho das propriedades opaqueBackground e scrollRect somente quando cacheAsBitmap for definido como true. Para obter mais informaes sobre como percorrer o contedo do objeto de exibio, consulte Viso panormica e rolagem de objetos de exibio na pgina 171. Para obter mais informaes sobre como configurar um plano de fundo opaco, consulte Definio de uma cor de fundo opaca na pgina 178. Para obter informaes sobre o mascaramento do canal alfa, que requer a definio da propriedade cacheAsBitmap como true, consulte Mascaramento de objetos de exibio na pgina 183.

Quando ativar o armazenamento em cache

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A ativao do cache para um objeto de exibio cria uma superfcie, o que tem diversas vantagens, como ajudar na renderizao rpida de animaes vetoriais complexas. Existem diversos cenrios nos quais necessrio ativar o cache. Voc talvez pense que sempre que o cache ativado, o desempenho dos arquivos SWF melhora; no entanto, existem situaes nas quais a ativao do cache no melhora o desempenho ou pode inclusive pior-lo. Esta seo descreve cenrios nos quais o cache deve ser usado e quando objetos de exibio regulares devem ser usados. O desempenho global de dados em cache depende da complexidade dos dados vetoriais das ocorrncias, quanto foram mudados os dados e se foi ou no definida a propriedade opaqueBackground. Se voc estiver mudando regies pequenas, a diferena entre o uso de superfcie e o uso de dados vetoriais pode ser desprezvel. Teste o seu trabalho das duas formas, antes de implantar o aplicativo. Quando usar o armazenamento em cache de bitmaps A seguir, alguns casos comuns nos quais podem ser vistos benefcios significativos quando se ativa o armazenamento em cache de bitmaps.

Imagem de fundo complexa: um aplicativo que contm uma imagem de fundo complexa e detalhada dos dados
vetoriais (talvez uma imagem na qual o comando Traar bitmap tenha sido aplicado ou a arte final criada no Adobe Illustrator). Voc pode animar caracteres no plano de fundo, o que deixa a animao mais lenta porque o plano de fundo precisa gerar regularmente os dados vetoriais mais uma vez. Para melhorar o desempenho, voc pode definir a propriedade opaqueBackground do objeto de exibio de fundo como true. O fundo renderizado como um bitmap e pode se redesenhado rapidamente, de modo que a execuo da animao seja muito mais rpida.

Rolagem de campo de texto: um aplicativo que exibe uma grande quantidade de texto na rolagem do campo de
texto. Voc pode colocar o campo de texto em um objeto de exibio definido como rolvel com limites de rolagem (a propriedade scrollRect). Isso agiliza a rolagem de pixel para a ocorrncia especificada. Quando o usurio rola a ocorrncia do objeto de exibio, o Flash Player ou o AIR move os pixels rolados para cima e gera a regio recmexposta, em vez de gerar novamente todo o campo de texto.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

177

Sistema de janelas: um aplicativo com um sistema complexo de janelas sobrepostas. Cada janela pode ser aberta ou
fechada (por exemplo, as janelas de navegador da web). Se voc marcar cada janela como uma superfcie (definindo a propriedade cacheAsBitmap como true), cada janela isolada e colocada em cache. Os usurios podem arrastar as janelas de modo que se sobreponham, e as janelas no precisam gerar novamente o contedo vetorial.

Mascaramento do canal alfa: ao usar o mascaramento do canal alfa, voc deve definir a propriedade
cacheAsBitmap como true. Para obter mais informaes, consulte Mascaramento de objetos de exibio na

pgina 183. A ativao do cache de bitmaps em todos esses cenrios melhora a resposta e a interatividade do aplicativo, otimizando os grficos vetoriais. Alm disso, sempre que um filtro aplicado em um objeto de exibio, cacheAsBitmap definido automaticamente como true, mesmo que esteja explicitamente definido como false. Se todos os filtros forem desativados do objeto de exibio, a propriedade cacheAsBitmap retornar ao valor definido pela ltima vez. Quando evitar o uso do armazenamento em cache de bitmaps Usando este recurso nas circunstncias erradas pode prejudicar o desempenho do arquivo SWF. Ao usar o cache de bitmaps, lembre-se das seguintes orientaes:

No use em exagero superfcies (objetos de exibio com o cache ativado). Cada superfcie usa mais memria do
que um objeto de exibio normal, o que indica que voc deve ativar as superfcies apenas quando precisar melhorar o desempenho da renderizao. Um bitmap em cache pode usar significativamente mais memria do que um objeto de exibio normal. Por exemplo, se uma ocorrncia de Sprite no palco tem 250 pixels por 250 pixels de tamanho, pode usar 250 KB em vez de 1 KB em cache quando for uma ocorrncia normal de Sprite (no armazenada em cache).

Evite o zoom em superfcies em cache. Se usar exageradamente cache de bitmaps, consumida uma grande
quantidade de memria (veja observao anterior) se fizer o zoom do contedo.

Use superfcies para ocorrncias de objeto de exibio em grande parte estticas (sem animao). Voc pode
arrastar ou mover a ocorrncia, mas o contedo da ocorrncia no deve ser animado ou mudado muito. A animao ou alterao do contedo tem maior probabilidade de acontecer com uma ocorrncia de MovieClip que contm animao ou uma ocorrncia de Video. Por exemplo, se voc girar ou transformar uma ocorrncia, ela muda entre a superfcie e os dados vetoriais, o que difcil de processar e afeta negativamente o arquivo SWF.

Se misturar superfcies com dados vetoriais, aumenta a quantidade de processamento a ser feita pelo Flash Player
e pelo AIR (e algumas vezes o computador). Agrupe as superfcies o mximo possvel, por exemplo, quando criar aplicativos em janelas.

No armazene em cache objetos cujas imagens grficas sejam alteradas com freqncia. Toda vez que voc
dimensiona, inclina, gira o objeto de exibio, altera a transformao de cor ou do alfa, move objetos de exibio filho ou desenha usando a propridade graphics, o cache de bitmap redesenhado. Se isso acontecer em cada quadro, o tempo de execuo precisa desenhar o objeto em um bitmap e, em seguida, copiar esse bitmap no palco, o que resulta em trabalho extra, quando comparado com o simples desenho no palco do objeto que no est em cache. A escolha em termos de desempenho entre cache e freqncia de atualizao depende da complexidade e do tamanho do objeto de exibio e pode ser determinada somente pelo teste do contedo especfico.

Ativao do armazenamento em cache de bitmaps

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para ativar o armazenamento em cache de bitmaps para um objeto de exibio, defina a propriedade cacheAsBitmap como true:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

178

mySprite.cacheAsBitmap = true;

Depois de definir a propriedade cacheAsBitmap como true, voc deve perceber que o objeto de exibio realiza o encaixe de pixels automaticamente em coordenadas inteiras. Ao testar o arquivo SWF, voc ver que qualquer animao executada em uma imagem vetorial complexa processada muito mais rpido. Uma superfcie (bitmap em cache) no ser criada, mesmo que cacheAsBitmap esteja definido como true, se ocorrer uma ou mais das seguintes situaes:

O bitmap muito maior do que 2880 pixels de altura ou largura. O bitmap no consegue ser alocado (produzindo erro de falta de memria).
Matrizes de transformao de bitmap armazenado em cache Adobe AIR 2.0 e posterior (perfil mvel) Em aplicativos AIR para dispositivos mveis, voc deve definir a propriedade cacheAsBitmapMatrix sempre que definir a propriedade cacheAsBitmap. A definio desta propriedade permite aplicar um intervalo mais amplo de transformaes ao objeto de exibio sem acionamento de uma nvoa renderizao.
mySprite.cacheAsBitmap = true; mySprite.cacheAsBitmapMatrix = new Matrix();

Quando voc define esta matriz adequadamente, pode aplicar a seguinte transformao adicional ao objeto de exibio sem voltar a armazenar o objeto em cache:

Mover ou converter sem encaixe de pixel Girar Dimensionamento Inclinar Alterar o alfa (entre 0% e 100% de transparncia)
Essas transformaes so aplicadas diretamente ao bitmap no cache.

Definio de uma cor de fundo opaca

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc pode definir um plano de fundo opaco para um objeto de exibio. Por exemplo, quando o SWF tem um plano de fundo que contm elementos vetoriais complexos, voc pode definir a propriedade opaqueBackground como uma cor especificada (normalmente a mesma cor do palco). A cor especificada como um nmero (em geral, um valor de cor hexadecimal). O plano de fundo tratado como um bitmap, o que ajuda a otimizar o desempenho. Quando voc define cacheAsBitmap como true e tambm define a propriedade opaqueBackground como uma cor especificada, a propriedade opaqueBackground permite que o bitmap interno seja opaco e renderizado mais rapidamente. Se cacheAsBitmap no for definido como true, a propriedade opaqueBackground adicionar uma forma vetorial quadrada opaca ao plano de fundo do objeto de exibio. Isso no cria um bitmap automaticamente. O exemplo a seguir mostra como definir o plano de fundo de um objeto de exibio para otimizar o desempenho:
myShape.cacheAsBitmap = true; myShape.opaqueBackground = 0xFF0000;

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

179

Nesse caso, a cor de fundo da forma chamada myShape definida como vermelha (0xFF0000). Supondo que a ocorrncia de Shape contm um desenho de um tringulo verde, em um palco com fundo branco, seria mostrado um tringulo verde com vermelho no espao vazio da caixa delimitadora da ocorrncia de Shape (o retngulo que envolve a forma por completo).

Obviamente, isso faria mais sentido se fosse usado com um palco com fundo vermelho slido. Em outro fundo colorido, essa cor seria especificada. Por exemplo, em um SWF com fundo branco, a propriedade opaqueBackground provavelmente seria definida como 0xFFFFFF, ou branco puro.

Aplicao de modos de mesclagem

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os modos de mesclagem envolvem a combinao das cores de uma imagem (a imagem base) com as cores de outra imagem (a imagem de mesclagem) para produzir uma terceira imagem; a imagem resultante aquela realmente exibida na tela. Cada valor de pixel em uma imagem processado com o valor de pixel correspondente da outra imagem para produzir um valor de pixel para a mesma posio no resultado. Todos os objetos de exibio tm uma propriedade blendMode que pode ser definida como um dos seguintes modos de mesclagem. Esses modos so constantes definidas na classe BlendMode. Se preferir, voc pode usar os valores de String (entre parnteses) que so os reais valores das constantes.

BlendMode.ADD ("add"): normalmente usado para criar um efeito animado de dissoluo de iluminao entre

duas imagens.
BlendMode.ALPHA ("alpha"): normalmente usado para aplicar a transparncia do primeiro plano no plano de

fundo. (Sem suporte na renderizao pela GPU.)

BlendMode.DARKEN ("darken"): normalmente usado para sobrepor tipos. (Sem suporte na renderizao pela GPU.) BlendMode.DIFFERENCE ("difference"): normalmente usado para criar cores mais vibrantes. BlendMode.ERASE ("erase"): normalmente usado para cortar (apagar) parte do plano de fundo usando o alfa do

primeiro plano. (Sem suporte na renderizao pela GPU.)

BlendMode.HARDLIGHT ("hardlight"): normalmente usado para criar efeitos de sombra. (Sem suporte na

renderizao pela GPU.)

BlendMode.INVERT ("invert"): usado para inverter o plano de fundo. BlendMode.LAYER ("layer"): usado para forar a criao de um buffer temporrio para pr-composio de um

objeto de exibio especfico. (Sem suporte na renderizao pela GPU.)

BlendMode.LIGHTEN ("lighten"): normalmente usado para sobrepor tipos. (Sem suporte na renderizao pela GPU.) BlendMode.MULTIPLY ("multiply"): normalmente usado para criar sombras e efeitos de profundidade. BlendMode.NORMAL ("normal"): usado para especificar que os valores de pixel da imagem de mesclagem

substituem os da imagem base.

BlendMode.OVERLAY ("overlay"): normalmente usado para criar efeitos de sombra. (Sem suporte na renderizao pela GPU.)

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

180

BlendMode.SCREEN ("screen"): normalmente usado para criar realces e manchas de luz. BlendMode.SHADER ("shader"): usado para especificar que um sombreador Pixel Bender usado para criar um

efeito de mesclagem personalizado. Para obter mais informaes sobre como usar sombreadores, consulte Trabalho com sombreadores Pixel Bender na pgina 293. (Sem suporte na renderizao pela GPU.)

BlendMode.SUBTRACT ("subtract"): normalmente usado para criar um efeito animado de dissoluo de

escurecimento entre duas imagens.

Ajuste das cores de DisplayObject

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc pode usar os mtodos da classe ColorTransform (flash.geom.ColorTransform) para ajustar a cor de um objeto de exibio. Cada objeto de exibio tem uma propriedade transform, que uma ocorrncia da classe Transform, e contm informaes sobre vrias transformaes que so aplicadas no objeto de exibio (como rotao, alteraes na escala ou posio e assim por diante). Alm de informaes sobre transformaes geomtricas, a classe Transform tambm inclui uma propriedade colorTransform, que uma ocorrncia da classe ColorTransform e fornece acesso para fazer ajustes de cor no objeto de exibio. Para acessar as informaes de transformao de cor de um objeto de exibio, voc pode usar um cdigo como esse:
var colorInfo:ColorTransform = myDisplayObject.transform.colorTransform;

Depois de criar uma ocorrncia de ColorTransform, voc pode ler os valores de propriedade para descobrir quais transformaes de cor j foram aplicadas ou definir esses valores para alterar cores no objeto de exibio. Para atualizar o objeto de exibio depois de fazer alteraes, atribua novamente a ocorrncia de ColorTransform propriedade transform.colorTransform.
var colorInfo:ColorTransform = myDisplayObject.transform.colorTransform; // Make some color transformations here. // Commit the change. myDisplayObject.transform.colorTransform = colorInfo;

Definio de valores de cor com cdigo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A propriedade color da classe ColorTransform pode ser usada para atribuir um valor de cor RGB (vermelho, verde e azul) especfico ao objeto de exibio. O exemplo a seguir usa a propriedade color para alterar a cor do objeto de exibio chamado square como azul quando o usurio clicar no boto blueBtn:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

181

// square is a display object on the Stage. // blueBtn, redBtn, greenBtn, and blackBtn are buttons on the Stage. import flash.events.MouseEvent; import flash.geom.ColorTransform; // Get access to the ColorTransform instance associated with square. var colorInfo:ColorTransform = square.transform.colorTransform; // This function is called when blueBtn is clicked. function makeBlue(event:MouseEvent):void { // Set the color of the ColorTransform object. colorInfo.color = 0x003399; // apply the change to the display object square.transform.colorTransform = colorInfo; } blueBtn.addEventListener(MouseEvent.CLICK, makeBlue);

Observe que, ao alterar a cor de um objeto de exibio usando a propriedade color, a cor do objeto inteiro alterada, independentemente de o objeto ter vrias cores anteriormente. Por exemplo, se houver um objeto de exibio que contm um crculo verde com texto preto na parte superior, definir a propriedade color da ocorrncia de ColorTransform associada desse objeto como uma sombra vermelha faz com que o objeto inteiro, crculo e texto, fique vermelho (de modo que o texto no ser mais diferenciado do restante do objeto).

Alterao de efeitos de brilho e cor com cdigo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Digamos que voc tenha um objeto de exibio com vrias cores (por exemplo, uma foto digital) e no queira colorir o objeto inteiro novamente; voc quer apenas ajustar a cor de um objeto de exibio com base nas cores existentes. Nesse cenrio, a classe ColorTransform inclui uma srie de propriedades de multiplicador e deslocamento que podem ser usadas para fazer esse tipo de ajuste. As propriedades de multiplicador, chamadas redMultiplier, greenMultiplier, blueMultiplier e alphaMultiplier, funcionam como filtros fotogrficos coloridos (ou culos de sol coloridos), intensificando ou ofuscando algumas cores no objeto de exibio. As propriedades de deslocamento (redOffset, greenOffset, blueOffset e alphaOffset) podem ser usadas para aumentar a quantidade de uma determinada cor no objeto ou para especificar o valor mnimo que uma cor especfica pode ter. Essas propriedades de multiplicador e deslocamento so idnticas s configuraes de cor avanadas que esto disponveis para smbolos de clipe de filme na ferramenta de criao do Flash quando voc escolhe Avanado no menu pop-up Cor no Inspetor de propriedades. O cdigo a seguir carrega uma imagem JPEG e aplica uma transformao de cor nela, ajustando os canais vermelho e verde medida que o ponteiro do mouse se move ao longo dos eixos x e y. Nesse caso, como nenhum valor de deslocamento foi especificado, o valor de cada canal de cor exibido na tela ser uma porcentagem do valor de cor original na imagem - a maior parte de vermelho ou verde exibida em um pixel a quantidade original de vermelho ou verde nesse pixel.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

182

import import import import import

flash.display.Loader; flash.events.MouseEvent; flash.geom.Transform; flash.geom.ColorTransform; flash.net.URLRequest;

// Load an image onto the Stage. var loader:Loader = new Loader(); var url:URLRequest = new URLRequest("http://www.helpexamples.com/flash/images/image1.jpg"); loader.load(url); this.addChild(loader); // This function is called when the mouse moves over the loaded image. function adjustColor(event:MouseEvent):void { // Access the ColorTransform object for the Loader (containing the image) var colorTransformer:ColorTransform = loader.transform.colorTransform; // Set the red and green multipliers according to the mouse position. // The red value ranges from 0% (no red) when the cursor is at the left // to 100% red (normal image appearance) when the cursor is at the right. // The same applies to the green channel, except it's controlled by the // position of the mouse in the y axis. colorTransformer.redMultiplier = (loader.mouseX / loader.width) * 1; colorTransformer.greenMultiplier = (loader.mouseY / loader.height) * 1; // Apply the changes to the display object. loader.transform.colorTransform = colorTransformer; } loader.addEventListener(MouseEvent.MOUSE_MOVE, adjustColor);

Rotao de objetos
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os objetos de exibio podem ser girados com a propriedade rotation. Voc pode ler esse valor para saber se um objeto foi girado ou, para girar o objeto, defina essa propriedade como um nmero (em graus) que representa o valor de rotao a ser aplicado no objeto. Por exemplo, essa linha do cdigo gira o objeto chamado square 45 graus (1/8 de uma revoluo completa):
square.rotation = 45;

Se preferir, gire o objeto de exibio usando uma matriz de transformao, conforme descrito em Trabalho com geometria na pgina 202.

Desaparecimento de objetos
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc pode controlar a transparncia de um objeto de exibio para deix-lo parcial ou completamente transparente ou alterar a transparncia para realar ou ofuscar o objeto. A propriedade alpha da classe DisplayObject define a transparncia (ou, mais precisamente, a opacidade) de um objeto de exibio. A propriedade alpha pode ser definida como qualquer valor entre 0 e 1, onde 0 completamente transparente e 1 completamente opaco. Por exemplo, essas linhas de cdigo deixam o objeto chamado myBall parcialmente transparente (50%) quando clicado com o mouse:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

183

function fadeBall(event:MouseEvent):void { myBall.alpha = .5; } myBall.addEventListener(MouseEvent.CLICK, fadeBall);

Voc tambm pode alterar a transparncia de um objeto de exibio usando os ajustes de cor disponveis pela classe ColorTransform. Para obter mais informaes, consulte Ajuste das cores de DisplayObject na pgina 180.

Mascaramento de objetos de exibio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc pode usar um objeto de exibio como uma mscara para criar um orifcio por meio do qual o contedo de outro objeto de exibio visualizado.

Definio de uma mscara

Para indicar que um objeto de exibio ser a mscara de outro objeto, defina o objeto de mscara como a propriedade mask do objeto de exibio a ser mascarado:
// Make the object maskSprite be a mask for the object mySprite. mySprite.mask = maskSprite;

O objeto de exibio mascarado revelado em todas as reas opacas (no transparentes) do objeto de exibio que age como a mscara. Por exemplo, o cdigo a seguir cria uma ocorrncia de Shape que contm um quadrado vermelho de 100 x 100 pixels e uma ocorrncia de Sprite que contm um crculo azul com raio de 25 pixels. Assim que clicado, o crculo definido como a mscara do quadrado para que a nica parte exibida do quadrado seja a parte coberta pela parte slida do crculo. Em outras palavras, somente um crculo vermelho ficar visvel.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

184

// This code assumes it's being run within a display object container // such as a MovieClip or Sprite instance. import flash.display.Shape; // Draw a square and add it to the display list. var square:Shape = new Shape(); square.graphics.lineStyle(1, 0x000000); square.graphics.beginFill(0xff0000); square.graphics.drawRect(0, 0, 100, 100); square.graphics.endFill(); this.addChild(square); // Draw a circle and add it to the display list. var circle:Sprite = new Sprite(); circle.graphics.lineStyle(1, 0x000000); circle.graphics.beginFill(0x0000ff); circle.graphics.drawCircle(25, 25, 25); circle.graphics.endFill(); this.addChild(circle); function maskSquare(event:MouseEvent):void { square.mask = circle; circle.removeEventListener(MouseEvent.CLICK, maskSquare); } circle.addEventListener(MouseEvent.CLICK, maskSquare);

O objeto de exibio que atua como mscara pode ser arrastado, animado, redimensionado dinamicamente e pode usar formas separadas em uma nica mscara. O objeto de exibio de mscara no precisa ser necessariamente adicionado lista de exibio. No entanto, se desejar que o objeto de mscara seja dimensionado quando o palco for dimensionado ou se desejar permitir a interao do usurio com a mscara (como as operaes de arrastar e redimensionar controladas pelo usurio), o objeto de mscara deve ser adicionado lista de exibio. O ndice z real (ordem da frente para trs) dos objetos de exibio no importam, desde que o objeto de mscara seja adicionado lista de exibio. O objeto de mscara ser exibido na tela apenas como uma mscara. Se o objeto de mscara for uma ocorrncia de MovieClip com vrios quadros, todos os quadros da linha do tempo desse objeto sero reproduzidos, do mesmo modo como se no estivesse agindo como mscara. Para remover uma mscara, defina a propriedade mask como null:
// remove the mask from mySprite mySprite.mask = null;

Voc no pode usar uma mscara para mascarar outra. A propriedade alpha de um objeto de exibio de mscara no pode ser definida. Somente os preenchimentos so usados em um objeto de exibio usado como mscara; os traados so ignorados.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

185

AIR 2 Se um objeto de exibio com mscara for armazenado em cache pela definio das propriedades cacheAsBitmap e cacheAsBitmapMatrix, a mscara deve ser um filho do objeto de exibio com mscara. Da mesma forma, se o objeto de exibio com mscara for descendente de um continer de objetos de exibio em cache, a mscara e o objeto de exibio devem ser descendentes deste continer. Se o objeto com mscara for descendente de mais de um continer de objetos de exibio em cache, a mscara deve ser descendente do recipiente em cache mais prximo do objeto com mscara na lista de exibio.

Sobre o mascaramento de fontes de dispositivo

Voc pode usar um objeto de exibio para mascarar o texto que est definido em uma fonte de dispositivo. Quando um objeto de exibio usado para mascarar o texto definido em uma fonte de dispositivo, a caixa delimitadora retangular da mscara usada como a forma de mascaramento. Isso significa que, se voc criar uma mscara no retangular de objeto de exibio para o texto da fonte de dispositivo, a mscara exibida no arquivo SWF ter a forma da caixa delimitadora retangular da mscara, no a forma da mscara propriamente dita.

Mascaramento do canal alfa

O mascaramento do canal alfa permitido se a mscara e os objetos de exibio mascarados usarem o cache de bitmaps, conforme mostrado aqui:
// maskShape is a Shape instance which includes a gradient fill. mySprite.cacheAsBitmap = true; maskShape.cacheAsBitmap = true; mySprite.mask = maskShape;

Por exemplo, o mascaramento do canal alfa usa um filtro no objeto de mscara diferente do filtro que aplicado no objeto de exibio mascarado. No exemplo a seguir, um arquivo de imagem externo carregado no palco. Essa imagem (ou, mais precisamente, a ocorrncia de Loader na qual carregada) ser o objeto de exibio mascarado. Um elemento oval de gradiente (centro preto slido que fica transparente nas bordas) desenhado na imagem; esta ser a mscara alfa. Os dois objetos de exibio tm o cache de bitmaps ativado. O elemento oval definido como uma mscara para a imagem e pode ser arrastado.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

186

// This code assumes it's being run within a display object container // such as a MovieClip or Sprite instance. import import import import import flash.display.GradientType; flash.display.Loader; flash.display.Sprite; flash.geom.Matrix; flash.net.URLRequest;

// Load an image and add it to the display list. var loader:Loader = new Loader(); var url:URLRequest = new URLRequest("http://www.helpexamples.com/flash/images/image1.jpg"); loader.load(url); this.addChild(loader); // Create a Sprite. var oval:Sprite = new Sprite(); // Draw a gradient oval. var colors:Array = [0x000000, 0x000000]; var alphas:Array = [1, 0]; var ratios:Array = [0, 255]; var matrix:Matrix = new Matrix(); matrix.createGradientBox(200, 100, 0, -100, -50); oval.graphics.beginGradientFill(GradientType.RADIAL, colors, alphas, ratios, matrix); oval.graphics.drawEllipse(-100, -50, 200, 100); oval.graphics.endFill(); // add the Sprite to the display list this.addChild(oval); // Set cacheAsBitmap = true for both display objects. loader.cacheAsBitmap = true; oval.cacheAsBitmap = true; // Set the oval as the mask for the loader (and its child, the loaded image) loader.mask = oval; // Make the oval draggable. oval.startDrag(true);

Animao de objetos
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Animao o processo de fazer algo se movimentar ou, tambm, de fazer algo mudar com o passar do tempo. A animao com script uma parte fundamental dos jogos de vdeo e normalmente usada para adicionar dicas teis de interao a outros aplicativos.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

187

A idia bsica por trs da animao por script de que uma alterao deve ocorrer e essa alterao precisa ser dividida em incrementos com o passar do tempo. fcil fazer algo se repetir no ActionScript, usando uma instruo de consulta comum. No entanto, uma consulta ser executada em todas as iteraes antes da atualizao da exibio. Para criar animao com script, voc precisa gravar um ActionScript que execute alguma ao repetidas vezes com o passar do tempo e tambm atualize a tela sempre que essa ao for executada. Por exemplo, imagine que voc quer criar uma animao simples, como uma bola que percorre a tela. O ActionScript inclui um mecanismo fcil que permite acompanhar a passagem do tempo e atualizar a tela conforme necessrio, ou seja, voc pode gravar o cdigo que move a bola um pouco por vez at atingir o destino. Aps cada movimentao, a tela atualizada e o usurio pode visualizar o movimento no palco. Do ponto de vista prtico, faz sentido sincronizar a animao com script com a taxa de quadros do arquivo SWF (em outras palavras, fazer uma alterao de animao sempre que um novo quadro for exibido), pois tal procedimento define a freqncia de atualizao de tela do Flash Player ou do AIR. Cada objeto de exibio tem um evento enterFrame que enviado de acordo com a taxa de quadros do arquivo SWF - um evento por quadro. A maioria dos desenvolvedores que cria animaes com script usa o evento enterFrame para criar aes que se repetem com o passar do tempo. Voc pode gravar um cdigo que ouve o evento enterFrame, movendo a bola animada um pouco em cada quadro e, medida que a tela atualizada (cada quadro), a bola seria redesenhada em seu novo local, criando o movimento. Nota: Uma ao que se repete com o passar do tempo tambm pode ser criada com a classe Timer. Uma ocorrncia de Timer aciona uma notificao de evento sempre que um perodo especificado passa. Voc poderia gravar um cdigo que executa a animao manipulando os eventos de tempo da classe Timer, definindo um intervalo de tempo pequeno (alguma frao de um segundo). Para obter mais informaes sobre como usar a classe Timer, consulte Controle de intervalos de tempo na pgina 4. No exemplo a seguir, uma ocorrncia circular de Sprite, chamada circle, criada no palco. Quando o usurio clica no crculo, uma seqncia de animao com script iniciada, fazendo com que o crculo desaparea (a propriedade alpha diminuda) at ficar completamente transparente:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

188

import flash.display.Sprite; import flash.events.Event; import flash.events.MouseEvent; // draw a circle and add it to the display list var circle:Sprite = new Sprite(); circle.graphics.beginFill(0x990000); circle.graphics.drawCircle(50, 50, 50); circle.graphics.endFill(); addChild(circle); // When this animation starts, this function is called every frame. // The change made by this function (updated to the screen every // frame) is what causes the animation to occur. function fadeCircle(event:Event):void { circle.alpha -= .05; if (circle.alpha <= 0) { circle.removeEventListener(Event.ENTER_FRAME, fadeCircle); } } function startAnimation(event:MouseEvent):void { circle.addEventListener(Event.ENTER_FRAME, fadeCircle); } circle.addEventListener(MouseEvent.CLICK, startAnimation);

Quando o usurio clica no crculo, a funo fadeCircle() inscrita como ouvinte do evento enterFrame, indicando que comear a ser chamada uma vez por quadro. Essa funo desbota o crculo alterando sua propriedade alpha para que, uma vez por quadro, o alfa do crculo diminua 0,05 (5%) e a tela seja atualizada. Eventualmente, quando o valor de alpha 0 (crculo completamente transparente), a funo fadeCircle() removida como ouvinte de eventos, encerrando a animao. O mesmo cdigo poderia ser usado, por exemplo, para criar um movimento animado em vez de desbotar o objeto. Substituindo uma propriedade diferente para alpha na funo que um ouvinte de eventos enterFrame, essa propriedade ser animada. Por exemplo, alterar esta linha
circle.alpha -= .05;

para este cdigo

circle.x += 5;

animar a propriedade x, fazendo com que o crculo se mova para a direita no palco. A condio que encerra a animao poderia ser alterada para finalizar a animao (isto , cancelar a inscrio do ouvinte enterFrame) quando a coordenada x desejada for atingida.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

189

Orientao do palco
AIR 2.0 e posterior Normalmente, dispositivos mveis reorientam a interface do usurio para manter a exibio vertical quando o usurio gira o dispositivo. Se voc ativar a orientao automtica em seu aplicativo, o dispositivo manter o visor corretamente orientado, mas cabe a voc se certificar de que a aparncia do contedo esteja OK quando a proporo do palco for alterada. Se voc desativar a auto-orientao, a exibio do dispositivo permanecer fixa, a menos que voc altere a orientao manualmente. Os aplicativos AIR so executados em diversos dispositivos e sistemas operacionais diferentes. O comportamento subjacente da orientao pode variar dependendo do sistema operacional e, at mesmo, dos diferentes dispositivos com o mesmo sistema operacional. Uma simples estratgia de design, que funciona bem em todos os dispositivos e sistemas operacionais, ativar a orientao automtica e ouvir eventos resize do palco para determinar quando preciso atualizar o layout do aplicativo. Como alternativa, se seu aplicativo oferecer suporte somente proporo retrato ou paisagem, voc pode desativar a orientao automtica e definir a proporo com suporte no descritor do aplicativo AIR. Esta estratgia de design proporciona um comportamento consistente e seleciona a melhor orientao para a proporo selecionada. Por exemplo, se voc especificar a proporo de paisagem, a orientao escolhida ser apropriada para dispositivos com teclados slide-out em modo de paisagem.

Obteno da orientao e proporo atuais do palco

A orientao informada em relao posio normal do dispositivo. Na maioria dos dispositivos, h uma posio vertical clara. Essa posio considerada a orientao padro. As outras trs orientaes possveis so: girado para a esquerda, girado para a direita e de ponta cabea. A classe StageOrientation define constantes de string a serem usadas na definio ou comparao de valores de orientao. A classe Stage define duas propriedades que indicam a orientao:

Stage.deviceOrientation Indica a orientao fsica do dispositivo em relao posio padro.

Nota: A propriedade deviceOrientation nem sempre est disponvel quando o aplicativo inicializado ou quando o dispositivo est deitado sobre uma superfcie. Nesses casos, a orientao do dispositivo indicada como desconhecida.

Stage.orientation Indica a orientao do palco em relao posio padro. Quando a orientao automtica
ativada, o palco gira na direo oposta do dispositivo para permanecer vertical. Assim, as posies direita e esquerda indicadas pela propriedade orientation so opostas quelas indicadas pela propriedade deviceOrientation. Por exemplo, quando deviceRotation indica girado para a direita, orientation indica girado para a esquerda. A proporo do palco pode ser derivada pela simples comparao da largura e altura atuais do palco:
var aspect:String = this.stage.stageWidth >= this.stage.stageHeight ? StageAspectRatio.LANDSCAPE : StageAspectRatio.PORTRAIT;

Orientao automtica
Quando a orientao automtica est ativa e um usurio gira o dispositivo, o sistema opercional reorienta toda a interface do usurio, inclusive a barra de tarefas e o seu aplicativo. Como resultado, a proporo do palco se altera de retrato para paisagem ou vice-versa. Quando a proporo alterada, as dimenses do palco tambm so alteradas.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

190

Ative ou desative a orientao automtica em tempo de execuo definido a propriedade autoOrients do palco como true ou false. Tambm possvel definir o valor inicial dessa propriedade no descritor do aplicativo AIR com o elemento <autoOrients>. (Observe que antes do AIR 2.6, autoOrients uma propriedade somente leitura que pode ser definida somente no descritor do aplicativo.) Alteraes das dimenses do palco Quando as dimenses do palco so alteradas, o contedo do palco dimensionado e reposicionado, conforme especificado pelas propriedades scaleMode e align do objeto Stage. Na maioria dos casos, depender do comportamento automtico fornecido pela configurao de scaleMode de Stage no produz bons resultados. Em vez disso, refaa o layout ou redesenhe seus elementos grficos e componentes de modo a oferecer suporte a mais de uma proporo. (Proporcionar lgica de layout flexvel tambm significa que seu aplicativo funcionar melhor em diferentes dispositivos com diferentes tamanhos e propores de tela.) A ilustrao a seguir demonstra os efeitos de diferentes configuraes de scaleMode quando um dispositivo mvel tpico girado:

Rotao da proporo paisagem para retrato

A ilustrao demonstra o comportamento de dimensionamento que ocorre na rotao da proporo paisagem para retrato com diferentes modos de escala. Girar de retrato para paisagem causa um conjunto semelhante de efeitos. Eventos de mudana de orientao O objeto Stage despacha dois tipos de evento que voc pode usar para detectar e reagir a mudanas de orientao. Ambos os eventos resize e orientationChange do palco so despachados quando a orientao automtica ativada. O evento resize o melhor evento a ser usado quando voc est dependendo da orientao automtica para manter o visor na vertical. Quando o palco despachar um evento resize, recrie o layout ou redesenhe seu contedo, conforme necessrio. O evento resize despachado somente quando o modo de escala do palco est definido como noScale. O evento orientationChange tambm pode ser usado para detectar mudanas de orientao. O evento
orientationChange despachado somente quando a orientao automtica est ativada.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

191

Nota: Em algumas plataformas mveis, o palco despacha um evento orientationChanging cancelvel antes de despachar os eventos resize ou orientationChange. Visto que no h suporte para o evento em todas as plataformas, evite depender dele.

Orientao manual
AIR 2.6 e posterior Voc pode controlar a orientao do palco usando o mtodo de Palco setOrientation() ou setAspectRatio(). Definindo a orientao do palco Voc pode definir a orientao do palco no tempo de execuo usando o mtodo setOrientation() do objeto Stage. Use as constantes de sequncias de caracteres definidas pela classe StageOrientation para especificar a orientao desejada:
this.stage.setOrientation( StageOrientation.ROTATED_RIGHT );

Nem todos os dispositivos ou sistemas operacionais suportam todas as orientaes possveis. Por exemplo, o Android 2.2 no suporta a escolha programada da orientao com giro para a esquerda nos dispositivos que tm a orientao de retrato como padro, assim como no suporta de nenhuma forma a orientao de cima para baixo. A propriedade supportedOrientations do palco fornece uma lista de orientaes que podem ser transferidas para o mtodo setOrientation():
var orientations:Vector.<String> = this.stage.supportedOrientations; for each( var orientation:String in orientations ) { trace( orientation ); }

Definindo a proporo do palco Se a proporo do palco for sua preocupao principal, voc poder defini-la como retrato ou paisagem. Voc pode definir a proporo no descritor do aplicativo do AIR ou no tempo de execuo, usando o mtodo setAspectRatio():
this.stage.setAspectRatio( StageAspectRatio.LANDSCAPE );

O tempo de execuo escolhe uma das duas orientaes possveis para a proporo especificada. Essa pode no corresponder orientao do dispositivo atual. A orientao padro escolhida com preferncia para a orientao de cima para baixo. A orientao apropriada para o teclado slide-out escolhida em preferncia orientao oposta. Exemplo: Definio da orientao do palco para corresponder orientao do dispositivo O exemplo a seguir ilustra uma funo que atualiza a orientao do palco para corresponder orientao atual do dispositivo. A propriedade deviceOrientation do palco indica a orientao fsica do dispositivo, mesmo quando a auto-orientao est desativada.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

192

function refreshOrientation( theStage:Stage ):void { switch ( theStage.deviceOrientation ) { case StageOrientation.DEFAULT: theStage.setOrientation( StageOrientation.DEFAULT ); break; case StageOrientation.ROTATED_RIGHT: theStage.setOrientation( StageOrientation.ROTATED_LEFT ); break; case StageOrientation.ROTATED_LEFT: theStage.setOrientation( StageOrientation.ROTATED_RIGHT ); break; case StageOrientation.UPSIDE_DOWN: theStage.setOrientation( StageOrientation.UPSIDE_DOWN ); break; default: //No change } }

A mudana de orientao assncrona. Voc pode ouvir o evento orientationChange despachado pelo palco para detectar a concluso da mudana. Se uma orientao no for suportada num dispositivo, a chamada setOrientation() falhar sem emitir um erro.

Carregamento dinmico do contedo da exibio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc pode carregar qualquer uma dos seguintes ativos de exibio externos em um aplicativo ActionScript 3.0:

Um arquivo SWF criado no ActionScript 3.0 - Esse arquivo pode ser uma classe Sprite, MovieClip ou qualquer
classe que estende Sprite. Nos aplicativos do AIR que rodam no iOS, somente os arquivos SWF que no contm cdigo de byte do ActionScript podem ser carregados. Isso significa que os arquivos SWF que contm dados incorporados, tais como imagens e som, podem ser carregados, mas no os arquivos SWF que contm cdigo executvel.

Um arquivo de imagem - Isso inclui arquivos JPG, PNG e GIF. Um arquivo SWF AVM1 - Arquivo SWF gravado no ActionScript 1.0 ou 2.0. (no suportado em aplicativos mveis
do AIR) Carregue esses ativos usando a classe Loader.

Carregamento de objetos de exibio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os objetos Loader so usados para carregar arquivos SWF e de imagem em um aplicativo. A classe Loader uma subclasse de DisplayObjectContainer. Um objeto Loader pode conter apenas um objeto de exibio filho na lista de exibio, o objeto que representa o arquivo SWF ou de imagem carregado. Quando voc adiciona um objeto Loader lista de exibio, como no cdigo a seguir, tambm pode adicionar o objeto filho carregado lista de exibio aps o carregamento:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

193

var pictLdr:Loader = new Loader(); var pictURL:String = "banana.jpg" var pictURLReq:URLRequest = new URLRequest(pictURL); pictLdr.load(pictURLReq); this.addChild(pictLdr);

Assim que o arquivo SWF ou imagem carregado, voc pode mover o objeto de exibio carregado para outro continer, como o objeto container DisplayObjectContainer neste exemplo:
import flash.display.*; import flash.net.URLRequest; import flash.events.Event; var container:Sprite = new Sprite(); addChild(container); var pictLdr:Loader = new Loader(); var pictURL:String = "banana.jpg" var pictURLReq:URLRequest = new URLRequest(pictURL); pictLdr.load(pictURLReq); pictLdr.contentLoaderInfo.addEventListener(Event.COMPLETE, imgLoaded); function imgLoaded(event:Event):void { container.addChild(pictLdr.content); }

Monitoramento do progresso do carregamento

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Assim que o arquivo comea a ser carregado, um objeto LoaderInfo criado. Um objeto LoaderInfo fornece informaes como o progresso do carregamento, os URLs do carregador e do contedo carregado, o nmero de bytes totais para a mdia e a altura e largura nominais da mdia. O objeto LoaderInfo tambm envia eventos para o monitoramento do progresso do carregamento. O diagrama a seguir mostra os diferentes usos do objeto LoaderInfo - para a ocorrncia da classe principal do arquivo SWF, para um objeto Loader e para um objeto carregado por Loader:
Palco

Objeto LoaderInfo Ocorrncia da classe principal do arquivo SWF

Propriedade loaderInfo

Objeto Loader

Propriedade contentLoaderInfo Objeto LoaderInfo

contedo

Propriedade loaderInfo

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

194

O objeto LoaderInfo pode ser acessado como uma propriedade do objeto Loader e do objeto de exibio carregado. Assim que o carregamento comea, o objeto LoaderInfo pode ser acessado por meio da propriedade contentLoaderInfo do objeto Loader. Quando o carregamento do objeto de exibio termina, o objeto LoaderInfo tambm pode ser acessado como uma propriedade do objeto de exibio carregado pela propriedade loaderInfo. A propriedade loaderInfo do objeto de exibio carregado refere-se ao mesmo objeto LoaderInfo da propriedade contentLoaderInfo do objeto Loader. Em outras palavras, um objeto LoaderInfo compartilhado entre um objeto carregado e o objeto Loader que o carregou (entre o carregador e o carregado). Para acessar as propriedades do contedo carregado, adicione um ouvinte de eventos ao objeto LoaderInfo, assim como no cdigo a seguir:
import flash.display.Loader; import flash.display.Sprite; import flash.events.Event; var ldr:Loader = new Loader(); var urlReq:URLRequest = new URLRequest("Circle.swf"); ldr.load(urlReq); ldr.contentLoaderInfo.addEventListener(Event.COMPLETE, loaded); addChild(ldr); function loaded(event:Event):void { var content:Sprite = event.target.content; content.scaleX = 2; }

Para obter mais informaes, consulte Manipulao de eventos na pgina 118.

Especificao do contexto do carregamento

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Quando voc carrega um arquivo externo no Flash Player ou no AIR com o mtodo load() ou loadBytes() da classe Loader, pode especificar, se desejar, um parmetro context. Este parmetros um objeto LoaderContext. A classe LoaderContext inclui trs propriedades que permitem definir o contexto de como o contedo carregado pode ser usado:

checkPolicyFile: Use essa propriedade apenas ao carregar um arquivo de imagem (no um arquivo SWF). Se

voc definir a propriedade como true, o Loader verificar o servidor de origem para obter um arquivo de poltica (consulteControles de site (arquivos de poltica) na pgina 1037). Isso necessrio apenas para o contedo originado de domnios diferentes dos domnios do arquivo SWF que contm o objeto Loader. Se o servidor conceder permisso ao domnio de Loader, o ActionScript dos arquivos SWF do domnio de Loader poder acessar os dados na imagem carregada; em outras palavras, voc pode usar o comando BitmapData.draw() para acessar os dados na imagem carregada. Observe que um arquivo SWF de outros domnios que no so os do objeto Loader pode chamar Security.allowDomain() para permitir um domnio especfico.

securityDomain: S use essa propriedade ao carregar um arquivo SWF (no uma imagem). Especifique-a para um arquivo SWF de um domnio diferente daquele do arquivo que contm o objeto Loader. Quando essa opo especificada, o Flash Player verifica a existncia de um arquivo de poltica e, se existir algum, os arquivos SWF dos domnios permitidos no arquivo de poltica podero cruzar o script do contedo SWF carregado. Voc pode especificar flash.system.SecurityDomain.currentDomain como este parmetro.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

195

applicationDomain: Use essa propriedade apenas ao carregar um arquivo SWF gravado no ActionScript 3.0 (no em uma imagem ou arquivo SWF gravado no ActionScript 1.0 ou no ActionScript 2.0). Ao carregar o arquivo, voc pode especificar que o arquivo seja includo no mesmo domnio de aplicativo do objeto Loader, definindo o parmetro applicationDomain como flash.system.ApplicationDomain.currentDomain. Colocando o arquivo SWF carregado no mesmo domnio de aplicativo, possvel acessar suas classes diretamente. Isso pode ser til se estiver carregando um arquivo SWF que contm mdia incorporada, que pode ser acessada por meio dos nomes de classe associados. Para obter mais informaes, consulte Trabalhar com domnios de aplicativo na pgina 141.

Veja um exemplo de busca de um arquivo de poltica ao carregar um bitmap de outro domnio:

var context:LoaderContext = new LoaderContext(); context.checkPolicyFile = true; var urlReq:URLRequest = new URLRequest("http://www.[your_domain_here].com/photo11.jpg"); var ldr:Loader = new Loader(); ldr.load(urlReq, context);

Veja um exemplo de busca de um arquivo de poltica ao carregar um SWF de outro domnio para colocar o arquivo na mesma caixa de proteo do objeto Loader. Alm disso, o cdigo adiciona as classes do arquivo SWF carregado ao mesmo domnio de aplicativo do objeto Loader:
var context:LoaderContext = new LoaderContext(); context.securityDomain = SecurityDomain.currentDomain; context.applicationDomain = ApplicationDomain.currentDomain; var urlReq:URLRequest = new URLRequest("http://www.[your_domain_here].com/library.swf"); var ldr:Loader = new Loader(); ldr.load(urlReq, context);

Para obter mais informaes, consulte a classe LoaderContext em Referncia do ActionScript 3.0 para a plataforma Adobe Flash.

Exemplo de objeto de exibio: SpriteArranger

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O aplicativo de amostra SpriteArranger criado com base no aplicativo de exemplo Geometric Shapes descrito separadamente no Aprendizado do ActionScript 3.0. O aplicativo de amostra SpriteArranger ilustra diversos conceitos de manipulao de objetos de exibio:

Extenso de classes de objeto de exibio Adio de objetos lista de exibio Disposio em camadas de objetos de exibio e trabalho com contineres de objeto de exibio Resposta a eventos de objeto de exibio Uso de propriedades e mtodos de objetos de exibio
Para obter os arquivos do aplicativo para este exemplo, consulte www.adobe.com/go/learn_programmingAS3samples_flash_br. Os arquivos do aplicativo SpriteArranger esto localizados na pasta Exemplos/SpriteArranger. O aplicativo consiste nos seguintes arquivos:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

196

Arquivo SpriteArranger.mxml ou SpriteArranger.fla com/example/programmingas3/SpriteArranger/CircleSprite.as

Descrio O arquivo principal do aplicativo no Flash (FLA) ou no Flex (MXML).

Uma classe que define um tipo de objeto Sprite que processa um crculo na tela. Uma classe que define a tela de desenho, que um continer de objeto de exibio que contm objetos GeometricSprite. Uma classe que define um tipo de objeto Sprite que processa um quadrado na tela. Uma classe que define um tipo de objeto Sprite que processa um tringulo na tela. Uma classe que estende o objeto Sprite, usado para definir uma forma na tela. CircleSprite, SquareSprite e TriangleSprite estendem essa classe. A interface bsica que define os mtodos a serem implementados por todas as classes de forma geomtrica. Uma interface que define os mtodos a serem implementados pelas classes de forma geomtrica que tm vrios lados. Um tipo de forma geomtrica que tem lados com o mesmo comprimento posicionados simetricamente ao redor do centro da forma. Um tipo de forma geomtrica que define um crculo. Uma subclasse de RegularPolygon que define um tringulo com todos os lados com o mesmo comprimento. Uma subclasse de RegularPolygon que define um retngulo com os quatro lados com o mesmo comprimento. Uma classe que contm um mtodo de fbrica para criar formas com tamanho e tipo especificados.

com/example/programmingas3/SpriteArranger/DrawingCanvas.as

com/example/programmingas3/SpriteArranger/SquareSprite.as

com/example/programmingas3/SpriteArranger/TriangleSprite.as

com/example/programmingas3/SpriteArranger/GeometricSprite.as

com/example/programmingas3/geometricshapes/IGeometricShape.as

com/example/programmingas3/geometricshapes/IPolygon.as

com/example/programmingas3/geometricshapes/RegularPolygon.as

com/example/programmingas3/geometricshapes/Circle.as

com/example/programmingas3/geometricshapes/EquilateralTriangle.as

com/example/programmingas3/geometricshapes/Square.as

com/example/programmingas3/geometricshapes/GeometricShapeFactory.as

Definio das classes SpriteArranger

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O aplicativo SpriteArranger permite que o usurio adicione vrios objetos de exibio tela de desenho exibida. A classe DrawingCanvas define uma rea de desenho, um tipo de continer de objeto de exibio ao qual o usurio pode adicionar formas na tela. Essas formas na tela so ocorrncias de uma das subclasses de GeometricSprite.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

197

A classe DrawingCanvas No Flex, todos os objetos de exibio filho adicionados a um objeto Container devem ser de uma classe originada da classe mx.core.UIComponent. Esse aplicativo adiciona uma ocorrncia da classe DrawingCanvas como um filho de um objeto mx.containers.VBox, conforme definido no cdigo MXML no arquivo SpriteArranger.mxml. Essa herana definida na declarao da classe DrawingCanvas, do seguinte modo:
public class DrawingCanvas extends UIComponent

A classe UIComponent herdada das classes DisplayObject, DisplayObjectContainer e Sprite e o cdigo na classe DrawingCanvas usa mtodos e propriedades dessas classes. A classe DrawingCanvas estende a classe Sprite e sua herana definida na declarao da classe DrawingCanvas, do seguinte modo:
public class DrawingCanvas extends Sprite

A classe Sprite uma subclasse de DisplayObjectContainer e de DisplayObject, e a classe DrawingCanvas usa mtodos e propriedades dessas classes. O mtodo do construtor DrawingCanvas() configura um objeto de Rectangle, bounds, que a propriedade usada posteriormente no desenho do contorno da tela de desenho. Em seguida, o mtodo initCanvas() chamado do seguinte modo:
this.bounds = new Rectangle(0, 0, w, h); initCanvas(fillColor, lineColor);

Como mostra o exemplo a seguir, o mtodo initCanvas() define vrias propriedades do objeto DrawingCanvas, que foram transmitidas como argumentos para a funo do construtor:
this.lineColor = lineColor; this.fillColor = fillColor; this.width = 500; this.height = 200;

O mtodo initCanvas() chama o mtodo drawBounds(), que desenha a tela de desenho usando a propriedade graphics da classe DrawingCanvas. A propriedade graphics herdada da classe Shape.
this.graphics.clear(); this.graphics.lineStyle(1.0, this.lineColor, 1.0); this.graphics.beginFill(this.fillColor, 1.0); this.graphics.drawRect(bounds.left - 1, bounds.top - 1, bounds.width + 2, bounds.height + 2); this.graphics.endFill();

Os mtodos adicionais a seguir da classe DrawingCanvas so invocados com base nas interaes do usurio com o aplicativo:

Os mtodos addShape() e describeChildren(), que so descritos em Adio de objetos de exibio tela de

desenho na pgina 198

Os mtodos moveToBack(), moveDown(), moveToFront() e moveUp(), que so descritos em Reorganizao da

disposio em camadas do objeto de exibio na pgina 201

O mtodo onMouseUp(), que descrito em Clique e arrasto de objetos de exibio na pgina 200

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

198

A classe GeometricSprite e suas subclasses Cada objeto de exibio que pode ser adicionado tela de desenho pelo usurio uma ocorrncia de uma das seguintes subclasses de GeometricSprite:

CircleSprite SquareSprite TriangleSprite

A classe GeometricSprite estende a classe flash.display.Sprite:
public class GeometricSprite extends Sprite

A classe GeometricSprite inclui diversas propriedades comuns a todos os objetos GeometricSprite. Essas propriedades so definidas na funo do construtor com base nos parmetros transmitidos para a funo. Por exemplo:
this.size = size; this.lineColor = lColor; this.fillColor = fColor;

A propriedade geometricShape da classe GeometricSprite define uma interface IGeometricShape, que define as propriedades matemticas, mas no as visuais, da forma. As classes que implementam a interface IGeometricShape so definidas no aplicativo de amostra GeometricShapes descrito no Aprendizado do ActionScript 3.0. A classe GeometricSprite define o mtodo drawShape(), que refinado ainda mais nas definies de substituio em cada subclasse de GeometricSprite. Para obter mais informaes, consulte a seo "Adio de objetos de exibio tela de desenho", apresentada a seguir. A classe GeometricSprite tambm fornece os seguintes mtodos:

Os mtodos onMouseDown() e onMouseUp(), que so descritos em Clique e arrasto de objetos de exibio na

pgina 200

Os mtodos showSelected() e hideSelected(), que so descritos em Clique e arrasto de objetos de exibio

na pgina 200

Adio de objetos de exibio tela de desenho

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Quando o usurio clica no boto Adicionar forma, o aplicativo chama o mtodo addShape() da classe DrawingCanvas. Esse mtodo percorre um novo GeometricSprite chamando a funo do construtor adequada de uma das subclasses de GeometricSprite, como mostra o exemplo a seguir:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

199

public function addShape(shapeName:String, len:Number):void { var newShape:GeometricSprite; switch (shapeName) { case "Triangle": newShape = new TriangleSprite(len); break; case "Square": newShape = new SquareSprite(len); break; case "Circle": newShape = new CircleSprite(len); break; } newShape.alpha = 0.8; this.addChild(newShape); }

Cada mtodo do construtor chama o mtodo drawShape(), que usa a propriedade graphics da classe (herdada da classe Sprite) para desenhar o grfico vetorial adequado. Por exemplo, o mtodo drawShape() da classe CircleSprite inclui o seguinte cdigo:
this.graphics.clear(); this.graphics.lineStyle(1.0, this.lineColor, 1.0); this.graphics.beginFill(this.fillColor, 1.0); var radius:Number = this.size / 2; this.graphics.drawCircle(radius, radius, radius);

Da segunda ltima linha da funo addShape(), definida a propriedade alpha do objeto de exibio (herdada da classe DisplayObject) para que cada objeto de exibio adicionado tela de desenho seja ligeiramente transparente, deixando o usurio ver os objetos que esto por trs. A linha final do mtodo addChild() adiciona o novo objeto de exibio lista de filhos da ocorrncia da classe DrawingCanvas, que j est na lista de exibio. Desse modo, o novo objeto de exibio aparece no palco. A interface do aplicativo inclui dois campos de texto, selectedSpriteTxt e outputTxt. As propriedades de texto desses campos so atualizados com informaes sobre os objetos GeometricSprite que foram adicionados tela de desenho ou selecionados pelo usurio. A classe GeometricSprite manipula essa tarefa de registro de informaes substituindo o mtodo toString() da seguinte maneira:
public override function toString():String { return this.shapeType + " of size " + this.size + " at " + this.x + ", " + this.y; }

A propriedade shapeType definida como o valor adequado no mtodo do construtor de cada subclasse de GeometricSprite. Por exemplo, o mtodo toString() poderia retornar o seguinte valor para uma ocorrncia de CircleSprite adicionada recentemente ocorrncia de DrawingCanvas:
Circle of size 50 at 0, 0

O mtodo describeChildren() da classe DrawingCanvas percorre a lista de filhos da tela de desenho, usando a propriedade numChildren (herdada da classe DisplayObjectContainer), para definir o limite do loop for. gerada uma string que lista cada filho, do seguinte modo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

200

var desc:String = ""; var child:DisplayObject; for (var i:int=0; i < this.numChildren; i++) { child = this.getChildAt(i); desc += i + ": " + child + '\n'; }

A string resultante usada para definir a propriedade text do campo de texto outputTxt.

Clique e arrasto de objetos de exibio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Quando o usurio clica em uma ocorrncia de GeometricSprite, o aplicativo chama o manipulador de eventos onMouseDown(). Conforme mostrado a seguir, esse manipulador de eventos definido para ouvir eventos de mouse na funo do construtor da classe GeometricSprite:
this.addEventListener(MouseEvent.MOUSE_DOWN, onMouseDown);

O mtodo onMouseDown() chama o mtodo showSelected() do objeto GeometricSprite. Se for a primeira vez que esse mtodo foi chamado para o objeto, o mtodo criar um novo objeto Shape chamado selectionIndicator e usar a propriedade graphics do objeto Shape para desenhar um retngulo de realce vermelho, do seguinte modo:
this.selectionIndicator = new Shape(); this.selectionIndicator.graphics.lineStyle(1.0, 0xFF0000, 1.0); this.selectionIndicator.graphics.drawRect(-1, -1, this.size + 1, this.size + 1); this.addChild(this.selectionIndicator);

Se no for a primeira vez que o mtodo onMouseDown() chamado, o mtodo simplesmente definir a propriedade visible da forma selectionIndicator (herdada da classe DisplayObject), do seguinte modo:
this.selectionIndicator.visible = true;

O mtodo hideSelected() oculta a forma selectionIndicator do objeto selecionado anteriormente definindo a propriedade visible como false. O manipulador de eventos onMouseDown() tambm chama o mtodo startDrag() (herdado da classe Sprite), que inclui o seguinte cdigo:
var boundsRect:Rectangle = this.parent.getRect(this.parent); boundsRect.width -= this.size; boundsRect.height -= this.size; this.startDrag(false, boundsRect);

Isso permite que o usurio arraste o objeto selecionado em torno da tela de desenho, dentro dos limites definidos pelo retngulo boundsRect. Quando o usurio solta o boto do mouse, o evento mouseUp enviado. O mtodo do construtor de DrawingCanvas configura o seguinte ouvinte de eventos:
this.addEventListener(MouseEvent.MOUSE_UP, onMouseUp);

Esse ouvinte de eventos definido para o objeto DrawingCanvas, no para objetos GeometricSprite individuais. Isso ocorre porque quando o objeto GeometricSprite arrastado, pode terminar atrs de outro objeto de exibio (outro objeto GeometricSprite) assim que o mouse solto. O objeto de exibio em primeiro plano receberia o evento de mouse, mas o objeto de exibio que est sendo arrastado pelo usurio no. A adio do ouvinte ao objeto DrawingCanvas garante que o evento seja sempre manipulado.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de exibio

201

O mtodo onMouseUp() chama o mtodo onMouseUp() do objeto GeometricSprite, que, por sua vez, chama o mtodo stopDrag() do objeto GeometricSprite.

Reorganizao da disposio em camadas do objeto de exibio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A interface de usurio do aplicativo inclui os botes Mover para trs, Mover para baixo, Mover para cima e Mover para frente. Quando o usurio clica em um desses botes, o aplicativo chama o mtodo correspondente da classe DrawingCanvas: moveToBack(), moveDown(), moveUp() ou moveToFront(). Por exemplo, o mtodo moveToBack() inclui o seguinte cdigo:
public function moveToBack(shape:GeometricSprite):void { var index:int = this.getChildIndex(shape); if (index > 0) { this.setChildIndex(shape, 0); } }

O mtodo setChildIndex() (herdado da classe DisplayObjectContainer) usado para colocar o objeto de exibio na posio de ndice 0 na lista de filhos da ocorrncia de DrawingCanvas (this). O mtodo moveDown() funciona de modo similar, mas diminui a posio de ndice do objeto de exibio em incrementos de 1 na lista de filhos da ocorrncia de DrawingCanvas:
public function moveDown(shape:GeometricSprite):void { var index:int = this.getChildIndex(shape); if (index > 0) { this.setChildIndex(shape, index - 1); } }

Os mtodos moveUp() e moveToFront() funcionam de modo similar aos mtodos moveToBack() e moveDown().

ltima atualizao em 29/3/2011

202

Captulo 10: Trabalho com geometria

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O pacote flash.geom contm classes que definem objetos geomtricos como pontos, retngulos e matrizes de transformao. Essas classes so usadas para definir as propriedades dos objetos utilizados em outras classes.

Mais tpicos da Ajuda

Pacote flash.geom

Noes bsicas de geometria

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O pacote flash.geom contm classes que definem objetos geomtricos como pontos, retngulos e matrizes de transformao. Essas classes necessariamente no fornecem uma funcionalidade em si, mas so usadas para definir as propriedades dos objetos utilizados em outras classes. Todas as classes de geometria giram em torno da noo de que os locais na tela so representados como um plano bidimensional. A tela tratada como um grfico plano com um eixo horizontal (x) e um vertical (y). Qualquer local (ou ponto) da tela pode ser representado como um par de valores x e y as coordenadas desse local. Cada objeto de exibio, inclusive o palco, tem seu prprio espao de coordenadas. O espao de coordenadas o prprio grfico de um objeto para traar os locais dos objetos de exibio descendentes, desenhos, etc. A origin est na coordenada 0, 0 (onde os eixos x e y se encontram) e est localizada no canto superior esquerdo do objeto de exibio. Embora esse local de origem seja sempre vlido para o palco, no necessariamente vlido para nenhum outro objeto de exibio. Os valores do eixo x aumentam em direo direita e diminuem em direo esquerda. Para os locais esquerda da origem, a coordenada x negativa. Entretanto, ao contrrio do sistema tradicional de coordenadas, os valores de coordenadas do tempo de execuo do Flash no eixo y aumentam quando descem na tela e diminuem quando sobem na tela. Os valores acima da origem tm um valor negativo de coordenada y). Como o canto superior esquerdo do palco a origem do espao de coordenadas, a maioria dos objetos no palco tem uma coordenada x maior que 0 e menor que a largura do palco. E o mesmo objeto tem uma coordenada y maior que 0 e menor que a altura do palco. Voc pode usar ocorrncias da classe Point para representar pontos individuais em um espao de coordenadas. possvel criar uma ocorrncia de Rectangle para representar uma regio retangular em um espao de coordenadas. Para usurios avanados, voc pode usar uma ocorrncia de Matrix para aplicar vrias transformaes ou transformaes complexas em um objeto de exibio. Muitas transformaes simples, como rotao, posio e alteraes de escala, podem ser aplicadas diretamente a um objeto de exibio usando as propriedades desse objeto. Para obter informaes sobre como aplicar transformaes usando propriedades de objeto de exibio, consulte Manipulao de objetos de exibio na pgina 166. Conceitos e termos importantes A lista de referncias a seguir contm termos geomtricos importantes:
Coordenadas cartesianas Coordenadas comumente escritas como um par de nmeros (como 5, 12 ou 17, -23). Os dois

nmeros so as coordenadas x e y, respectivamente.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com geometria

203

Espao de coordenadas O grfico de coordenadas contido em um objeto de exibio, no qual seus elementos-filho so

posicionados.
Origem O ponto em um espao de coordenadas onde o eixo x encontra o eixo y. Esse ponto tem a coordenada 0,0. Ponto Um local isolado em um espao de coordenadas. No sistema de coordenadas bidimensional usado no ActionScript, o local ao longo do eixo x e do eixo y (as coordenadas do ponto) define o ponto. Ponto de registro Em um objeto de exibio, a origem (coordenada 0, 0) de seu espao coordenado. Dimensionamento O tamanho de um objeto em relao ao seu tamanho original. Quando usado como um verbo,

dimensionar um objeto significa alterar seu tamanho, aumentando ou diminuindo o objeto.

Traduzir Alterar as coordenadas de um ponto de um espao de coordenadas para outro. Transformao Ajuste de uma caracterstica visual de um grfico como a rotao do objeto, a alterao da escala, a

inclinao ou distoro da forma ou a alterao da cor.

Eixo X O eixo horizontal no sistema de coordenadas bidimensional usado no ActionScript. Eixo Y O eixo vertical no sistema de coordenadas bidimensional usado no ActionScript.

Uso de objetos Point

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O objeto Point define um par de coordenadas Cartesianas. Ele representa um local em um sistema de coordenadas bidimensional, em que x representa o eixo horizontal e y, o vertical. Para definir um objeto Point, defina as propriedades de x e y da seguinte forma:
import flash.geom.*; var pt1:Point = new Point(10, 20); // x == 10; y == 20 var pt2:Point = new Point(); pt2.x = 10; pt2.y = 20;

Clculo da distncia entre dois pontos

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc pode usar o mtodo distance() da classe Point para calcular a distncia entre dois pontos em um espao de coordenadas. Por exemplo, o cdigo a seguir calcula a distncia entre os pontos de registro de dois objetos de exibio, circle1 e circle2, no mesmo continer de objetos de exibio:
import flash.geom.*; var pt1:Point = new Point(circle1.x, circle1.y); var pt2:Point = new Point(circle2.x, circle2.y); var distance:Number = Point.distance(pt1, pt2);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com geometria

204

Transposio de espaos de coordenadas

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Se dois objetos de exibio estiverem em contineres de objetos de exibio diferentes, talvez estejam em espaos de coordenadas diferentes. Voc pode usar o mtodo localToGlobal() da classe DisplayObject para transpor as coordenadas para o mesmo espao de coordenadas (global) que o Palco. Por exemplo, o cdigo a seguir calcula a distncia entre os pontos de registro de dois objetos de exibio, circle1 e circle2, em contineres de objetos de exibio diferentes:
import flash.geom.*; var pt1:Point = new Point(circle1.x, circle1.y); pt1 = circle1.localToGlobal(pt1); var pt2:Point = new Point(circle2.x, circle2.y); pt2 = circle2.localToGlobal(pt2); var distance:Number = Point.distance(pt1, pt2);

Da mesma forma, para calcular a distncia do ponto de registro de um objeto de exibio chamado target a partir de um ponto especfico no palco, use o mtodo localToGlobal() da classe DisplayObject:
import flash.geom.*; var stageCenter:Point = new Point(); stageCenter.x = this.stage.stageWidth / 2; stageCenter.y = this.stage.stageHeight / 2; var targetCenter:Point = new Point(target.x, target.y); targetCenter = target.localToGlobal(targetCenter); var distance:Number = Point.distance(stageCenter, targetCenter);

Mover um objeto de exibio usando um ngulo e uma distncia especificados

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc pode usar o mtodo polar() da classe Point para mover um objeto de exibio a uma distncia especfica em um ngulo especfico. Por exemplo, o cdigo a seguir move o objeto myDisplayObject 100 pixels em 60:
import flash.geom.*; var distance:Number = 100; var angle:Number = 2 * Math.PI * (90 / 360); var translatePoint:Point = Point.polar(distance, angle); myDisplayObject.x += translatePoint.x; myDisplayObject.y += translatePoint.y;

Outros usos da classe Point

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior possvel usar os objetos Point com os seguintes mtodos e propriedades:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com geometria

205

Classe DisplayObjectContainer

Mtodos ou propriedades
areInaccessibleObjectsUnderPoint()getObject sUnderPoint()

Descrio Usada para retornar uma lista de objetos sob um ponto em um continer de objetos de exibio. Usada para definir o pixel no objeto BitmapData bem como o ponto cuja ocorrncia voc est verificando. Usada para definir as posies de retngulos que definem as operaes.

BitmapData

hitTest()

BitmapData

applyFilter() copyChannel() merge() paletteMap() pixelDissolve() threshold()

Matriz

deltaTransformPoint() transformPoint()

Usada para definir os pontos para os quais voc deseja aplicar uma transformao. Usada para definir essas propriedades.

Retngulo

bottomRight size topLeft

Uso de objetos Rectangle

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O objeto Rectangle define uma rea retangular. Um objeto Rectangle tem uma posio, definida pelas coordenadas x e y de seu canto superior esquerdo, uma propriedade width e uma propriedade height . Voc pode definir essas propriedades para um novo objeto Rectangle chamando a funo de construtor Rectangle() da seguinte forma:
import flash.geom.Rectangle; var rx:Number = 0; var ry:Number = 0; var rwidth:Number = 100; var rheight:Number = 50; var rect1:Rectangle = new Rectangle(rx, ry, rwidth, rheight);

Redimensionamento e reposicionamento de objetos Rectangle

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior H vrias formas de redimensionar e reposicionar objetos Rectangle. Voc pode reposicionar o objeto Rectangle alterando suas propriedades x e y. Essa alterao no afeta a largura ou a altura do objeto Rectangle.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com geometria

206

import flash.geom.Rectangle; var x1:Number = 0; var y1:Number = 0; var width1:Number = 100; var height1:Number = 50; var rect1:Rectangle = new Rectangle(x1, y1, width1, height1); trace(rect1) // (x=0, y=0, w=100, h=50) rect1.x = 20; rect1.y = 30; trace(rect1); // (x=20, y=30, w=100, h=50)

Como mostra o cdigo a seguir, quando voc altera a propriedade left ou top de um objeto Rectangle, o retngulo reposicionado. As propriedades x e y do retngulo correspondem s propriedades left e top, respectivamente. Entretanto, a posio do canto inferior esquerdo do objeto Rectangle no alterada, por isso ele redimensionado.
import flash.geom.Rectangle; var x1:Number = 0; var y1:Number = 0; var width1:Number = 100; var height1:Number = 50; var rect1:Rectangle = new Rectangle(x1, y1, width1, height1); trace(rect1) // (x=0, y=0, w=100, h=50) rect1.left = 20; rect1.top = 30; trace(rect1); // (x=20, y=30, w=80, h=20)

Da mesma forma, como mostra o exemplo, se voc alterar a propriedade bottom ou right de um objeto Rectangle, a posio de seu canto superior esquerdo no alterada. O retngulo realizado corretamente:
import flash.geom.Rectangle; var x1:Number = 0; var y1:Number = 0; var width1:Number = 100; var height1:Number = 50; var rect1:Rectangle = new Rectangle(x1, y1, width1, height1); trace(rect1) // (x=0, y=0, w=100, h=50) rect1.right = 60; trect1.bottom = 20; trace(rect1); // (x=0, y=0, w=60, h=20)

Voc tambm pode reposicionar um objeto Rectangle usando o mtodo offset() da seguinte maneira:
import flash.geom.Rectangle; var x1:Number = 0; var y1:Number = 0; var width1:Number = 100; var height1:Number = 50; var rect1:Rectangle = new Rectangle(x1, y1, width1, height1); trace(rect1) // (x=0, y=0, w=100, h=50) rect1.offset(20, 30); trace(rect1); // (x=20, y=30, w=100, h=50)

O mtodo offsetPt() funciona da mesma forma, exceto que assume um objeto Point como parmetro, em vez dos valores de deslocamento x e y. Voc tambm pode redimensionar um objeto Rectangle usando o mtodo inflate(), que inclui dois parmetros, dx e dy. O parmetro dx representa o nmero de pixels que os lados esquerdo e direito do retngulo se movem em relao ao centro. O parmetro dy representa o nmero de pixels que os lados superior e inferior do retngulo se movem em relao ao centro.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com geometria

207

import flash.geom.Rectangle; var x1:Number = 0; var y1:Number = 0; var width1:Number = 100; var height1:Number = 50; var rect1:Rectangle = new Rectangle(x1, y1, width1, height1); trace(rect1) // (x=0, y=0, w=100, h=50) rect1.inflate(6,4); trace(rect1); // (x=-6, y=-4, w=112, h=58)

O mtodo inflatePt() funciona da mesma forma, exceto que assume um objeto Point como parmetro, em vez dos valores de deslocamento dx e dy.

Localizao de unies e intersees de objetos Rectangle

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc usa o mtodo union() para localizar a regio retangular formada pelos limites de dois retngulos:
import flash.display.*; import flash.geom.Rectangle; var rect1:Rectangle = new Rectangle(0, 0, 100, 100); trace(rect1); // (x=0, y=0, w=100, h=100) var rect2:Rectangle = new Rectangle(120, 60, 100, 100); trace(rect2); // (x=120, y=60, w=100, h=100) trace(rect1.union(rect2)); // (x=0, y=0, w=220, h=160)

Voc usa o mtodo intersection() para localizar a regio retangular formada pela regio sobreposta de dois retngulos:
import flash.display.*; import flash.geom.Rectangle; var rect1:Rectangle = new Rectangle(0, 0, 100, 100); trace(rect1); // (x=0, y=0, w=100, h=100) var rect2:Rectangle = new Rectangle(80, 60, 100, 100); trace(rect2); // (x=120, y=60, w=100, h=100) trace(rect1.intersection(rect2)); // (x=80, y=60, w=20, h=40)

O mtodo intersects() usado para descobrir se h interseo de dois retngulos. O mtodo intersects() tambm pode ser usado para descobrir se um objeto de exibio est em uma determinada regio do Palco. No cdigo de exemplo a seguir, suponha que o espao de coordenadas do continer de objetos de exibio que inclui o objeto circle seja o mesmo do palco. O exemplo mostra como usar o mtodo intersects() para determinar se h interseo de um objeto de exibio, circle, com regies especificadas do Palco, definidas pelos objetos Rectangle target1 e target2:
import flash.display.*; import flash.geom.Rectangle; var circle:Shape = new Shape(); circle.graphics.lineStyle(2, 0xFF0000); circle.graphics.drawCircle(250, 250, 100); addChild(circle); var circleBounds:Rectangle = circle.getBounds(stage); var target1:Rectangle = new Rectangle(0, 0, 100, 100); trace(circleBounds.intersects(target1)); // false var target2:Rectangle = new Rectangle(0, 0, 300, 300); trace(circleBounds.intersects(target2)); // true

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com geometria

208

Da mesma forma, o mtodo intersects() pode ser usado para descobrir se os retngulos delimitadores de dois objetos de exibio se sobrepem. Use o mtodo getRect() da classe DisplayObject para incluir qualquer espao adicional que os traados de um objeto de exibio adicionam a uma regio delimitadora.

Outros usos de objetos Rectangle

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os objetos Rectangle so usados nos seguintes mtodos e propriedades:
Classe BitmapData Mtodos ou propriedades
applyFilter(), colorTransform(), copyChannel(), copyPixels(), draw(), fillRect(), generateFilterRect(), getColorBoundsRect(), getPixels(), merge(), paletteMap(), pixelDissolve(), setPixels() e threshold() getBounds(), getRect(), scrollRect, scale9Grid addPage() startDrag() getCharBoundaries() pixelBounds

Descrio Usada como o tipo para alguns parmetros a fim de definir uma regio do objeto BitmapData.

DisplayObject

Usada como o tipo de dados para a propriedade ou o tipo de dados retornado. Usada para definir o parmetro printArea. Usada para definir o parmetro bounds. Usada como um tipo de valor de retorno. Usada como o tipo de dados.

PrintJob Sprite TextField Transform

Uso de objetos Matrix

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe Matrix representa uma matriz de transformao que determina como o map aponta de um espao de coordenada para outro. possvel realizar vrias transformaes grficas em um objeto de exibio definindo as propriedades de um objeto Matrix, aplicando esse objeto Matrix propriedade matrix de um objeto Transform, e depois aplicando esse objeto Transform como a propriedade transform do objeto de exibio. Essas funes de transformao incluem converso (reposicionamento de x e y), rotao, dimensionamento e inclinao. Embora seja possvel definir uma matriz ajustando diretamente as propriedades (a, b, c, d, tx, ty) de um objeto Matrix, mais fcil usar o mtodo createBox(). Esse mtodo inclui parmetros que permitem definir diretamente os efeitos de dimensionamento, rotao e transposio da matriz resultante. Por exemplo, o cdigo a seguir cria um objeto Matrix que dimension um objeto horizontalmente em 2,0, verticalmente em 3,0, gira-o em 45, movendo-o (transpondo) 10 pixels para a direita e 20 pixels para baixo:
var matrix:Matrix = new Matrix(); var scaleX:Number = 2.0; var scaleY:Number = 3.0; var rotation:Number = 2 * Math.PI * (45 / 360); var tx:Number = 10; var ty:Number = 20; matrix.createBox(scaleX, scaleY, rotation, tx, ty);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com geometria

209

Tambm possvel ajustar os efeitos de dimensionamento, rotao e transposio de um objeto Matrix usando os mtodos scale(), rotate() e translate() . Observe que esses mtodos combinam com os valores do objeto Matrix existente. Por exemplo, o cdigo a seguir define um objeto Matrix que dimensiona um objeto por um fator de 4 e girao 60, desde que os mtodos scale() e rotate() sejam chamados duas vezes:
var matrix:Matrix = new Matrix(); var rotation:Number = 2 * Math.PI * (30 / 360); // 30 var scaleFactor:Number = 2; matrix.scale(scaleFactor, scaleFactor); matrix.rotate(rotation); matrix.scale(scaleX, scaleY); matrix.rotate(rotation); myDisplayObject.transform.matrix = matrix;

Para aplicar uma transformao de inclinao em um objeto Matrix, ajuste sua propriedade b ou c. O ajuste da propriedade b inclina a matriz verticalmente e o ajuste da propriedadec inclina a matriz horizontalmente. O cdigo a seguir inclina o objeto Matrix myMatrix verticalmente por um fator de 2:
var skewMatrix:Matrix = new Matrix(); skewMatrix.b = Math.tan(2); myMatrix.concat(skewMatrix);

Voc pode aplicar uma transformao de Matrix propriedade transform de um objeto de exibio. Por exemplo, o cdigo a seguir aplica uma transformao de matriz em um objeto de exibio chamado myDisplayObject:
var matrix:Matrix = myDisplayObject.transform.matrix; var scaleFactor:Number = 2; var rotation:Number = 2 * Math.PI * (60 / 360); // 60 matrix.scale(scaleFactor, scaleFactor); matrix.rotate(rotation); myDisplayObject.transform.matrix = matrix;

A primeira linha define um objeto Matrix como a matriz de transformao existente usada pelo objeto de exibio myDisplayObject (a propriedade matrix da propriedade transformation do objeto de exibio myDisplayObject). Dessa forma, os mtodos da classe Matrix que voc chama tero um efeito cumulativo na posio, dimenso e rotao existentes do objeto de exibio. Nota: A classe ColorTransform tambm est includa no pacote flash.geometry. Essa classe usada para definir a propriedade colorTransform de um objeto Transform. Como no se aplica a nenhum transformao geomtrica, ela no ser discutida em detalhes aqui. Para obter mais informaes, consulte a classe ColorTransform em Referncia do ActionScript 3.0 para a plataforma Adobe Flash.

Exemplo de geometria: aplicao de uma transformao de matriz em um objeto de exibio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O aplicativo de exemplo DisplayObjectTransformer mostra vrios recursos de uso da classe Matrix para transformar um objeto de exibio, incluindo o seguinte:

Girar o objeto de exibio Dimensionar o objeto de exibio ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com geometria

210

Transpor (reposicionar) o objeto de exibio Inclinar o objeto de exibio

O aplicativo fornece uma interface para ajustar os parmetros de transformao da matriz, como a seguir:

Quando o usurio clica no boto Transform, o aplicativo aplica a transformao apropriada.

O objeto de exibio original e o objeto de exibio com um giro de - 45 e um dimensionamento de 50%

Para obter os arquivos do aplicativo para este exemplo, consulte www.adobe.com/go/learn_programmingAS3samples_flash_br. Os arquivos do aplicativo DisplayObjectTransformer podem ser encontrados na pasta Samples/DisplayObjectTransformer. O aplicativo consiste nos seguintes arquivos:
Arquivo DisplayObjectTransformer.mxml ou DisplayObjectTransformer.fla com/example/programmingas3/geometry/MatrixTransformer.as Uma classe que contm mtodos para aplicar transformaes de matriz. Um diretrio contendo arquivos de imagem de exemplo usados pelo aplicativo. Descrio O arquivo principal do aplicativo no Flash (FLA) ou no Flex (MXML)

img/

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com geometria

211

Definio da classe MatrixTransformer

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe MatrixTransformer inclui mtodos estticos que aplicam transformaes geomtricas de objetos Matrix. O mtodo transform() O mtodo transform() inclui parmetros para cada um dos itens a seguir:

sourceMatrix a matriz de entrada, que o mtodo transforma xScale e yScale o fator de dimensionamento x e y dx e dy os valores de transposio x e y, em pixels rotation o valor de rotao, em graus skew o fator de inclinao, em porcentagem skewType a direo da inclinao "right" ou "left"

O valor de retorno a matriz resultante. O mtodo transform() chama os seguintes mtodos estticos da classe:

skew() scale() translate() rotate()

Cada um retorna a matriz de origem com a transformao aplicada. O mtodo skew() O mtodo skew() inclina a matriz, ajustando as propriedades b e c da matriz. Um parmetro opcional, unit, determina as unidades usadas para definir o ngulo de inclinao e, se necessrio, o mtodo converte o valor angle em radianos:
if (unit == { angle = } if (unit == { angle = } "degrees") Math.PI * 2 * angle / 360; "gradients") Math.PI * 2 * angle / 100;

Um objeto Matrix skewMatrix criado e ajustado para aplicar a transformao de inclinao. Inicialmente, a matriz de identidade, como a seguir:
var skewMatrix:Matrix = new Matrix();

O parmetro skewSide determina o lado para o qual a inclinao aplicada. Se for definida como "right", o seguinte cdigo define a propriedade b da matriz:
skewMatrix.b = Math.tan(angle);

Caso contrrio, o lado inferior inclinado ajustando a propriedade c de Matrix, como a seguir:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com geometria

212

skewMatrix.c = Math.tan(angle);

A inclinao resultante aplicada matriz existente, concatenando as duas matrizes, como mostra o seguinte exemplo:
sourceMatrix.concat(skewMatrix); return sourceMatrix;

O mtodo scale() exemplo a seguir mostra que o mtodo scale() primeiro ajusta o fator de dimensionamento, caso seja fornecido como uma porcentagem e, em seguida, usa o mtodo scale() do objeto da matriz:
if (percent) { xScale = xScale / 100; yScale = yScale / 100; } sourceMatrix.scale(xScale, yScale); return sourceMatrix;

O mtodo translate() O mtodo translate() apenas aplica os fatores de transposio dx e dy chamando o mtodo translate() do objeto da matriz, como a seguir:
sourceMatrix.translate(dx, dy); return sourceMatrix;

O mtodo rotate() O mtodo rotate() converte o fator de rotao de entrada em radianos (se fornecido em graus ou gradientes) e chama o mtodo rotate() do objeto da matriz:
if (unit == "degrees") { angle = Math.PI * 2 * angle / 360; } if (unit == "gradients") { angle = Math.PI * 2 * angle / 100; } sourceMatrix.rotate(angle); return sourceMatrix;

Chamada do mtodo MatrixTransformer.transform() no aplicativo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O aplicativo contm uma interface do usurio para obter os parmetros de transformao do usurio. Ento, ele transmite esses valores, junto com a propriedade matrix da propriedade transform do objeto de exibio, ao mtodo Matrix.transform(), da seguinte maneira:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com geometria

213

tempMatrix = MatrixTransformer.transform(tempMatrix, xScaleSlider.value, yScaleSlider.value, dxSlider.value, dySlider.value, rotationSlider.value, skewSlider.value, skewSide );

O aplicativo aplica o valor de retorno propriedade matrix da propriedade transform do objeto de exibio, acionando a transformao:
img.content.transform.matrix = tempMatrix;

ltima atualizao em 29/3/2011

214

Captulo 11: Uso da API de desenho

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Embora as imagens e a arte final importadas sejam importantes, a funcionalidade conhecida como API de desenho, que permite desenhar linhas e formas no ActionScript, d a voc a liberdade de iniciar um aplicativo com o equivalente computacional de uma tela de desenho em branco, na qual possvel criar as imagens desejadas. A habilidade de criar seus prprios grficos abre muitas possibilidades para seus aplicativos. Com as tcnicas tratadas aqui, voc pode criar um programa de desenho, fazer arte interativa e animada ou criar, em termos programticos, seus prprios elementos da interface do usurio, entre muitas possibilidades.

Mais tpicos da Ajuda

flash.display.Graphics

Noes bsicas da API de desenho

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior API de desenho o nome da funcionalidade incorporada ao ActionScript que permite criar grficos vetoriais (linhas, curvas, formas, preenchimentos e gradientes) e exibi-los na tela usando o ActionScript. A classe flash.display.Graphics oferece esta funcionalidade. possvel desenhar com o ActionScript em qualquer ocorrncia de Shape, Sprite ou MovieClip usando a propriedade graphics definida em cada uma dessas classes. (A propriedade graphics de cada uma dessas classes , na verdade, uma ocorrncia da classe Graphics.) Se voc est apenas comeando a desenhar com cdigo, a classe Graphics inclui diversos mtodos que ajudam a desenhar formas comuns, como crculos, elipses, retngulos e retngulos com cantos arredondados. possvel desenh-las como linhas vazias ou formas preenchidas. Quando voc precisar de funcionalidade mais avanada, a classe Graphics tambm inclui mtodos para desenhar linhas e curvas Bzier quadrticas, que podem ser usadas junto com as funes de trigonometria da classe Math para criar qualquer forma desejada. Os tempos de execuo do Flash (como Flash Player 10 e o Adobe AIR 1.5 e as verses posteriores) adicionam mais uma API de desenho, que permite desenhar formas inteiras de modo programtico usando um nico comando. Depois que voc estiver familiarizado com a classe Graphics e as tarefas includas em Noes bsicas do uso da API de desenho, passe para Uso avanado da API de desenho na pgina 227 para saber mais sobre esses recursos da API de desenho. Conceitos e termos importantes A lista de referncia a seguir contm termos importantes que voc vai encontrar ao usar a API de desenho:
Ponto de ancoragem Uma das duas extremidades de uma curva Bzier quadrtica. Ponto de controle O ponto que define a direo e o grau da curva de uma curva Bzier quadrtica. A linha curva nunca

atinge o ponto de controle, mas a linha faz uma curva como se estivesse sendo desenhada perto do ponto de controle.
Espao de coordenadas O grfico de coordenadas contido em um objeto de exibio, no qual seus elementos-filho so

posicionados.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API de desenho

215

Preencher A parte interna slida de uma forma que tem uma linha preenchida com cor ou uma forma inteira que no tem contorno. Gradiente Cor que consiste em uma transio gradual de uma cor para uma ou mais cores (ao contrrio de uma cor

slida).
Ponto Um local isolado em um espao de coordenadas. No sistema de coordenadas bidimensional usado no ActionScript, um ponto definido por seu local no eixo x e no eixo y (as coordenadas do ponto). Curva Bzier quadrtica Tipo de curva definido por uma frmula matemtica especfica. Neste tipo de curva, a forma de uma curva calculada com base nas posies dos pontos de ancoragem (as extremidades da curva) e em um ponto de controle que define o grau e a direo da curva. Escala O tamanho de um objeto em relao ao seu tamanho original. Quando usado como um verbo, dimensionar um

objeto significa alterar seu tamanho, aumentando ou diminuindo o objeto.

Traado A parte do contorno de uma forma que tem uma linha preenchida com cor ou as linhas de uma forma sem

preenchimento.
Traduzir Alterar as coordenadas de um ponto de um espao de coordenadas para outro. Eixo X O eixo horizontal no sistema de coordenadas bidimensional usado no ActionScript. Eixo Y O eixo vertical no sistema de coordenadas bidimensional usado no ActionScript.

A classe Graphics
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Cada objeto Shape, Sprite e MovieClip tem uma propriedade graphics, que uma ocorrncia da classe Graphics. A classe Graphics inclui propriedades e mtodos para desenhar linhas, preenchimentos e formas. Se voc quiser que o objeto display seja usado apenas como uma tela de desenho para o contedo do desenho, use uma ocorrncia Shape. Uma ocorrncia Shape ser executada de modo melhor do que outros objetos display para desenho, porque ela no tem a sobrecarga da funcionalidade adicional nas classes Sprite e MovieClip. Se quiser um objeto display no qual seja possvel desenhar contedo grfico e no qual outros objetos display estejam contidos, use uma ocorrncia Sprite. Para obter mais informaes sobre a determinao dos objetos display que sero usados para vrias tarefas, consulte Escolha de uma subclasse de DisplayObject na pgina 165.

Desenho de linhas e curvas

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Todos os desenhos feitos com uma ocorrncia Graphics baseiam-se em desenhos bsicos com linhas e curvas. Conseqentemente, todos os desenhos do ActionScript devem ser executados utilizando a mesma srie de etapas:

Definir estilos de linha e preenchimento Definir posio inicial do desenho Desenhar linhas, curvas e formas (opcionalmente movendo o ponto de desenho) Concluir a criao de um preenchimento, se necessrio

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API de desenho

216

Definio de estilos de linha e preenchimento

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para desenhar com a propriedade graphics de uma ocorrncia de Shape, Sprite ou MovieClip, defina primeiro o estilo (tamanho e cor da linha, cor do preenchimento) a ser usado no desenho. Da mesma forma como acontece quando voc usa as ferramentas de desenho do Adobe Flash Professional ou outro aplicativo de desenho, ao usar o ActionScript para desenhar, voc pode desenhar com ou sem traado e com ou sem uma cor de preenchimento. Voc especifica a aparncia do traado utilizando o mtodo lineStyle() ou lineGradientStyle(). Para criar uma linha slida, use o mtodo lineStyle(). Quando voc chamar esse mtodo, os valores mais comuns que voc especificar sero os trs primeiros parmetros: espessura da linha, cor e alfa. Por exemplo, essa linha de cdigo instrui Shape chamada myShape a desenhar linhas com espessura de 2 pixels, vermelhas (0x990000) e 75% opacas:
myShape.graphics.lineStyle(2, 0x990000, .75);

O valor padro para o parmetro alpha 1.0 (100%), ento voc pode deix-lo desativado, se quiser uma linha totalmente opaca. O mtodo lineStyle() tambm aceita dois parmetros adicionais para dica de pixel e modo de escala. Para obter mais informaes sobre o uso desses parmetros, consulte a descrio do mtodo Graphics.lineStyle() na Referncia do ActionScript 3.0 para a plataforma Adobe Flash. Para criar uma linha gradiente, use o mtodo lineGradientStyle(). Esse mtodo descrito em Criao de linhas e preenchimentos gradientes na pgina 219. Se voc quiser criar uma forma preenchida, chame os mtodos beginFill(), beginGradientFill(), beginBitmapFill() ou beginShaderFill() antes de iniciar o desenho. O mais bsico deles, o mtodo beginFill(), aceita dois parmetros: a cor de preenchimento e (opcionalmente) um valor alfa para a cor de preenchimento. Por exemplo, se voc quiser desenhar uma forma com um preenchimento verde slido, utilize o seguinte cdigo (considerando que est desenhando em um objeto chamado myShape):
myShape.graphics.beginFill(0x00FF00);

Chamar qualquer mtodo de preenchimento implicitamente encerra qualquer preenchimento anterior antes de iniciar um novo. Chamar qualquer mtodo que especifique um estilo de traado substitui o traado anterior, mas no altera o preenchimento especificado anteriormente e vice-versa. Depois de especificar as propriedades style e fill da linha, a prxima etapa indicar o ponto de incio para o desenho. A ocorrncia Graphics tem um ponto de desenho, como a ponta de uma caneta em um pedao de papel. Sempre que o ponto de desenho for localizado, esse ser o local em que a prxima ao de desenho ser iniciada. Inicialmente um objeto Graphics comea com seu ponto de desenho no ponto 0, 0 no espao de coordenadas do objeto em que est o desenho. Para iniciar o desenho em um ponto diferente, voc pode primeiro chamar o mtodo moveTo() antes de chamar um dos mtodos de desenho. Isso semelhante a tirar do papel a ponta da caneta e mov-la para uma nova posio. Com o ponto de desenho no local, desenhe usando uma srie de chamadas de mtodos de desenho lineTo() (para linhas retas) e curveTo() (para linhas curvas). Enquanto estiver desenhando, chame o mtodo moveTo() a qualquer momento para mover o ponto de desenho para uma nova posio sem desenhar. Ao desenhar, se voc tiver especificado uma cor de preenchimento, feche o preenchimento chamando o mtodo endFill(). Se voc no desenhou uma forma fechada (em outras palavras, se no momento em que voc chama endFill(), o ponto de desenho no est no ponto inicial da forma), quando chamar o mtodo endFill(), o tempo de execuo do Flash fecha automaticamente a forma desenhando uma linha reta do ponto de desenho atual at o local especificado na chamada mais recente de moveTo(). Se voc iniciou um preenchimento e no chamou endFill(), chamar beginFill() (ou qualquer um dos outros mtodos de preenchimento) fecha o preenchimento atual e inicia um novo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API de desenho

217

Desenho de linhas retas

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Quando voc chama o mtodo lineTo(), o objeto Graphics desenha uma linha reta do ponto de desenho atual at as coordenadas especificadas como os dois parmetros na chamada do mtodo, com o estilo de linha tambm especificado. Por exemplo, essa linha de cdigo coloca o ponto de desenho no ponto 100, 100 e desenha uma linha at o ponto 200, 200:
myShape.graphics.moveTo(100, 100); myShape.graphics.lineTo(200, 200);

O exemplo a seguir desenha tringulos vermelho e verde com uma altura de 100 pixels:
var triangleHeight:uint = 100; var triangle:Shape = new Shape(); // red triangle, starting at point 0, 0 triangle.graphics.beginFill(0xFF0000); triangle.graphics.moveTo(triangleHeight / 2, 0); triangle.graphics.lineTo(triangleHeight, triangleHeight); triangle.graphics.lineTo(0, triangleHeight); triangle.graphics.lineTo(triangleHeight / 2, 0); // green triangle, starting at point 200, 0 triangle.graphics.beginFill(0x00FF00); triangle.graphics.moveTo(200 + triangleHeight / 2, 0); triangle.graphics.lineTo(200 + triangleHeight, triangleHeight); triangle.graphics.lineTo(200, triangleHeight); triangle.graphics.lineTo(200 + triangleHeight / 2, 0); this.addChild(triangle);

Desenho de curvas
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O mtodo curveTo() desenha uma curva Bzier quadrtica. Isso desenha um arco que conecta dois pontos (chamados pontos de ancoragem, enquanto se curva a um terceiro ponto (chamado ponto de controle). O objeto Graphics usa a posio atual do desenho como o primeiro ponto de ancoragem. Quando voc chama o mtodo curveTo(), passa quatro parmetros: as coordenadas x e y do ponto de controle, seguido pelas coordenadas x e y do segundo ponto de ancoragem. Por exemplo, o seguinte cdigo desenha uma curva comeando no ponto 100, 100 e terminando no ponto 200, 200. Como o ponto de controle est no ponto 175, 125, isso cria uma curva que se move para a direita e para baixo:
myShape.graphics.moveTo(100, 100); myShape.graphics.curveTo(175, 125, 200, 200);

O exemplo a seguir desenha objetos circulares vermelho e verde com uma largura e altura de 100 pixels. Observe que, devido natureza da equao de Bzier de segundo grau, esses crculos no so perfeitos.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API de desenho

218

var size:uint = 100; var roundObject:Shape = new Shape(); // red circular shape roundObject.graphics.beginFill(0xFF0000); roundObject.graphics.moveTo(size / 2, 0); roundObject.graphics.curveTo(size, 0, size, size / 2); roundObject.graphics.curveTo(size, size, size / 2, size); roundObject.graphics.curveTo(0, size, 0, size / 2); roundObject.graphics.curveTo(0, 0, size / 2, 0); // green circular shape roundObject.graphics.beginFill(0x00FF00); roundObject.graphics.moveTo(200 + size / 2, 0); roundObject.graphics.curveTo(200 + size, 0, 200 + size, size / 2); roundObject.graphics.curveTo(200 + size, size, 200 + size / 2, size); roundObject.graphics.curveTo(200, size, 200, size / 2); roundObject.graphics.curveTo(200, 0, 200 + size / 2, 0); this.addChild(roundObject);

Desenho de formas utilizando os mtodos incorporados

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para sua convenincia, ao desenhar formas comuns como crculos, elipses, retngulos e retngulos com cantos arredondados, o ActionScript 3.0 tem mtodos que desenham essas formas comuns para voc. Estes so os mtodos drawCircle(), drawEllipse(), drawRect() e drawRoundRect() da classe Graphics. Esses mtodos tambm podem ser utilizados no lugar dos mtodos lineTo() e curveTo(). Observe, entretanto, que voc ainda deve especificar os estilos de linha e preenchimento antes de chamar esses mtodos. O exemplo a seguir recria o exemplo de desenho de quadrados vermelho, verde e azul com largura e altura de 100 pixels. Esse cdigo usa o mtodo drawRect() e, alm disso, especifica que a cor de preenchimento tem um alfa de 50% (0,5):
var squareSize:uint = 100; var square:Shape = new Shape(); square.graphics.beginFill(0xFF0000, 0.5); square.graphics.drawRect(0, 0, squareSize, squareSize); square.graphics.beginFill(0x00FF00, 0.5); square.graphics.drawRect(200, 0, squareSize, squareSize); square.graphics.beginFill(0x0000FF, 0.5); square.graphics.drawRect(400, 0, squareSize, squareSize); square.graphics.endFill(); this.addChild(square);

Em um objeto Sprite ou MovieClip, o contedo de desenho criado com a propriedade graphics sempre aparece atrs de todos os objetos display filhos contidos no objeto. Alm disso, o contedo da propriedade graphics no um objeto display separado; portanto ele no aparece na lista de filhos do objeto Sprite ou MovieClip. Por exemplo, o seguinte objeto Sprite tem um crculo desenhado com sua propriedade graphics e um objeto TextField em sua lista de objetos display filhos:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API de desenho

219

var mySprite:Sprite = new Sprite(); mySprite.graphics.beginFill(0xFFCC00); mySprite.graphics.drawCircle(30, 30, 30); var label:TextField = new TextField(); label.width = 200; label.text = "They call me mellow yellow..."; label.x = 20; label.y = 20; mySprite.addChild(label); this.addChild(mySprite);

Observe que TextField aparece na parte superior do crculo desenhado com o objeto graphics.

Criao de linhas e preenchimentos gradientes

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O objeto graphics tambm pode desenhar traados e preenchimentos com gradientes em vez de cores slidas. Um traado gradiente criado com o mtodo lineGradientStyle() e um preenchimento de gradiente criado com o mtodo beginGradientFill(). Os dois mtodos aceitam os mesmos parmetros. Os primeiros quatro so obrigatrios: tipo, cores, alfas e propores. Os outros quatro so opcionais, mas teis para personalizao avanada.

O primeiro parmetro especifica o tipo de gradiente que est criando. Os valores aceitveis so
GradientType.LINEAR ou GradientType.RADIAL.

O segundo parmetro especifica a matriz dos valores de cor que sero utilizados. Em um gradiente linear, as cores
sero organizadas da esquerda para a direita. Em um gradiente radial, as cores sero organizadas de dentro para fora. A ordem das cores da matriz representa a ordem em que elas sero desenhadas no gradiente.

O terceiro parmetro especifica os valores de transparncia alfa das cores correspondentes no parmetro anterior. O quarto parmetro especifica as propores ou a nfase que cada cor tem no gradiente. A faixa de valores aceitvel
de 0 a 255. Esses valores no representam a largura ou a altura, mas a posio no gradiente; 0 representa o incio do gradiente e 255 representa o final do gradiente. A matriz de propores deve aumentar seqencialmente e tem o mesmo nmero de entradas que as matrizes de cores e alfa especificadas no segundo e no terceiro parmetros. Embora o quinto parmetro, a matriz de transformao, seja opcional, ele normalmente usado porque fornece um modo fcil e eficiente de controlar a aparncia do gradiente. Esse parmetro aceita uma ocorrncia Matrix. O modo mais fcil de criar um objeto Matrix para um gradiente usar o mtodo createGradientBox() da classe Matrix.

Definio de um objeto Matrix para usar com um gradiente

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc usa os mtodos beginGradientFill() e lineGradientStyle() da classe flash.display.Graphics para definir gradientes para usar em formas. Ao definir um gradiente, voc fornece uma matriz como um dos parmetros desses mtodos.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API de desenho

220

A maneira mais fcil de definir a matriz utilizando o mtodo createGradientBox() da classe Matrix, que cria uma matriz utilizada para definir o gradiente. Voc define a escala, a rotao e a posio do gradiente utilizando os parmetros passados para o mtodo createGradientBox(). O mtodo createGradientBox() aceita os seguintes parmetros:

Largura da caixa de gradientes: a largura (em pixels) para a qual o gradiente ser ampliado. Altura da caixa de gradientes: a altura (em pixels) para a qual o gradiente ser ampliado. Rotao da caixa de gradientes: a rotao (em radianos) que ser aplicada ao gradiente. Movimentao horizontal: a distncia (em pixels) que o gradiente se deslocar horizontalmente. Movimentao vertical: a distncia (em pixels) que o gradiente se deslocar verticalmente.
Por exemplo, considere um gradiente com as seguintes caractersticas:

GradientType.LINEAR 255].

Duas cores, verde e azul, com a matriz de propores definidas para [0,
SpreadMethod.PAD InterpolationMethod.LINEAR_RGB

Os seguintes exemplos mostram gradientes nos quais o parmetro rotation do mtodo createGradientBox() diferente conforme indicado, mas todas as configuraes permanecem as mesmas:
width = 100; height = 100; rotation = 0; tx = 0; ty = 0; width = 100; height = 100; rotation = Math.PI/4; // 45 tx = 0; ty = 0; width = 100; height = 100; rotation = Math.PI/2; // 90 tx = 0; ty = 0;

Os seguintes exemplos mostram os efeitos de um gradiente linear verde para azul no qual os parmetros rotation, tx e ty do mtodo createGradientBox() so diferentes conforme indicado, mas todas as outras configuraes permanecem as mesmas:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API de desenho

221

width = 50; height = 100; rotation = 0; tx = 0; ty = 0; width = 50; height = 100; rotation = 0 tx = 50; ty = 0; width = 100; height = 50; rotation = Math.PI/2; // 90 tx = 0; ty = 0; width = 100; height = 50; rotation = Math.PI/2; // 90 tx = 0; ty = 50;

Os parmetros width, height, tx e ty do mtodo createGradientBox() tambm afetam o tamanho e a posio de um preenchimento de gradiente radial, conforme mostram os exemplos a seguir:
width = 50; height = 100; rotation = 0; tx = 25; ty = 0;

O cdigo a seguir produz o ltimo gradiente radial ilustrado:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API de desenho

222

import flash.display.Shape; import flash.display.GradientType; import flash.geom.Matrix; var var var var var var var type:String = GradientType.RADIAL; colors:Array = [0x00FF00, 0x000088]; alphas:Array = [1, 1]; ratios:Array = [0, 255]; spreadMethod:String = SpreadMethod.PAD; interp:String = InterpolationMethod.LINEAR_RGB; focalPtRatio:Number = 0;

var matrix:Matrix = new Matrix(); var boxWidth:Number = 50; var boxHeight:Number = 100; var boxRotation:Number = Math.PI/2; // 90 var tx:Number = 25; var ty:Number = 0; matrix.createGradientBox(boxWidth, boxHeight, boxRotation, tx, ty); var square:Shape = new Shape; square.graphics.beginGradientFill(type, colors, alphas, ratios, matrix, spreadMethod, interp, focalPtRatio); square.graphics.drawRect(0, 0, 100, 100); addChild(square);

Observe que a largura e a altura do preenchimento de gradiente so determinadas pela largura e altura da matriz de gradientes em vez da largura e altura desenhadas utilizando o objeto Graphics. Ao desenhar com objetos Graphics, voc desenha o que existe naquelas coordenadas na matriz de gradiente. Mesmo que voc use um dos mtodos shape de um objeto Graphics como drawRect(), o gradiente no se amplia para o tamanho da forma que desenhada o tamanho do gradiente deve ser especificado na prpria matrix de gradiente. A seguir est uma ilustrao da diferena visual entre as dimenses da matrix de gradiente e das dimenses do prprio desenho.
var myShape:Shape = new Shape(); var gradientBoxMatrix:Matrix = new Matrix(); gradientBoxMatrix.createGradientBox(100, 40, 0, 0, 0); myShape.graphics.beginGradientFill(GradientType.LINEAR, [0xFF0000, 0x00FF00, 0x0000FF], [1, 1, 1], [0, 128, 255], gradientBoxMatrix); myShape.graphics.drawRect(0, 0, 50, 40); myShape.graphics.drawRect(0, 50, 100, 40); myShape.graphics.drawRect(0, 100, 150, 40); myShape.graphics.endFill(); this.addChild(myShape);

Esse cdigo desenha trs gradientes com o mesmo estilo de preenchimento, especificado com uma distribuio igual de vermelho, verde e azul. Os gradientes so desenhados utilizando o mtodo drawRect() com larguras de pixel de 50, 100 e 150 respectivamente. A matriz de gradiente que especificada no mtodo beginGradientFill() criada com uma largura de 100 pixels. Isso significa que o primeiro gradiente engloba apenas meio espectro de gradiente, o segundo engloba todo ele e o terceiro engloba todo ele e tem 50 pixels adicionais de azul estendidos para a direita.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API de desenho

223

O mtodo lineGradientStyle() funciona de modo semelhante a beginGradientFill() exceto pelo fato de que ao definir o gradiente, voc deve especificar a espessura do trao utilizando o mtodo lineStyle() antes do desenho. O cdigo a seguir desenha uma caixa com um traado gradiente vermelho, verde e azul:
var myShape:Shape = new Shape(); var gradientBoxMatrix:Matrix = new Matrix(); gradientBoxMatrix.createGradientBox(200, 40, 0, 0, 0); myShape.graphics.lineStyle(5, 0); myShape.graphics.lineGradientStyle(GradientType.LINEAR, [0xFF0000, 0x00FF00, 0x0000FF], [1, 1, 1], [0, 128, 255], gradientBoxMatrix); myShape.graphics.drawRect(0, 0, 200, 40); this.addChild(myShape);

Para obter mais informaes sobre a classe Matrix, consulte Uso de objetos Matrix na pgina 208.

Uso da classe Math com mtodos de desenho

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O objeto Graphics desenha crculos e quadrados, mas tambm pode desenhar formas mais complexas, especialmente quando os mtodos de desenho so utilizados junto com as propriedades e os mtodos da classe Math. A classe Math contm constantes matemticas comuns, como Math.PI (aproximadamente 3.14159265...), uma constante para proporo de circunferncia de um crculo em relao ao seu dimetro. Ela tambm contm mtodos para funes de trigonometria, incluindo Math.sin(), Math.cos() e Math.tan() entre outros. Desenhar formas utilizando esses mtodos e constantes cria efeitos visuais mais dinmicos, especialmente quando utilizados com repetio ou recurso. Muitos mtodos da classe Math esperam medidas circulares em unidades de radianos em vez de graus. A converso entre esses dois tipos de unidades um uso comum da classe Math:
var degrees = 121; var radians = degrees * Math.PI / 180; trace(radians) // 2.111848394913139

O exemplo a seguir cria uma onda senoidal e uma cossenoidal entre os mtodos Math.sin() e Math.cos() para um determinado valor.
var var var var var var sinWavePosition = 100; cosWavePosition = 200; sinWaveColor:uint = 0xFF0000; cosWaveColor:uint = 0x00FF00; waveMultiplier:Number = 10; waveStretcher:Number = 5;

var i:uint; for(i = 1; i < stage.stageWidth; i++) { var sinPosY:Number = Math.sin(i / waveStretcher) * waveMultiplier; var cosPosY:Number = Math.cos(i / waveStretcher) * waveMultiplier; graphics.beginFill(sinWaveColor); graphics.drawRect(i, sinWavePosition + sinPosY, 2, 2); graphics.beginFill(cosWaveColor); graphics.drawRect(i, cosWavePosition + cosPosY, 2, 2); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API de desenho

224

Animao com a API de desenho

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Uma vantagem da criao de contedo com a API de desenho que voc no est limitado a posicionar o contedo apenas uma vez. O que voc desenha pode ser modificado pela manuteno e modificao das variveis que usa ao desenhar. Voc pode transmitir a animao alterando as variveis e redesenhando, em um perodo de quadros ou com um temporizador. Por exemplo, o cdigo a seguir altera a exibio com cada quadro transmitido (atendendo ao evento Event.ENTER_FRAME), incrementando a contagem de graus atual, direciona o objeto graphics para limpar e redesenhar na posio atualizada.
stage.frameRate = 31; var currentDegrees:Number = 0; var radius:Number = 40; var satelliteRadius:Number = 6; var container:Sprite = new Sprite(); container.x = stage.stageWidth / 2; container.y = stage.stageHeight / 2; addChild(container); var satellite:Shape = new Shape(); container.addChild(satellite); addEventListener(Event.ENTER_FRAME, doEveryFrame); function doEveryFrame(event:Event):void { currentDegrees += 4; var radians:Number = getRadians(currentDegrees); var posX:Number = Math.sin(radians) * radius; var posY:Number = Math.cos(radians) * radius; satellite.graphics.clear(); satellite.graphics.beginFill(0); satellite.graphics.drawCircle(posX, posY, satelliteRadius); } function getRadians(degrees:Number):Number { return degrees * Math.PI / 180; }

Para produzir um resultado significativamente diferente, voc pode modificar as variveis base iniciais no incio do cdigo, currentDegrees, radius esatelliteRadius. Por exemplo, tente reduzir a varivel radius e/ou aumentar a varivel totalSatellites. Esse apenas um exemplo de como a API de desenho pode criar uma exibio visual cuja complexidade oculta a simplicidade de sua criao.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API de desenho

225

Exemplo de API de desenho: gerador visual algortmico

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O exemplo do Gerador visual algortmico desenha dinamicamente no palco vrios "satlites" ou crculos que se movem em uma rbita circular. Entre os recursos explorados esto:

Uso da API de desenho para desenhar uma forma bsica com aparncias dinmicas Conexo da interao do usurio com as propriedades utilizadas em um desenho Transmisso de animao por meio da limpeza do palco em cada quadro e redesenho
O exemplo na subseo anterior animou um satlite solitrio utilizando o evento Event.ENTER_FRAME. Esse exemplo vai alm disso, criando um painel de controle com sries de controles deslizantes que atualizam imediatamente a exibio visual de vrios satlites. Esse exemplo formaliza o cdigo em classes externas e agrupa o cdigo de criao de satlites em um loop, armazenando uma referncia para cada satlite em uma matriz satellites. Para obter os arquivos do aplicativo para este exemplo, consulte www.adobe.com/go/learn_programmingAS3samples_flash_br. Os arquivos do aplicativo podem ser encontrados na pasta Amostras/AlgorithmicVisualGenerator. Essa pasta contm os seguintes arquivos:
Arquivo AlgorithmicVisualGenerator.fla Descrio O arquivo principal do aplicativo no Flash Professional (FLA). A classe que fornece a funcionalidade principal do aplicativo, que inclui desenho de satlites no palco e resposta aos eventos do painel de controle para atualizar as variveis que afetam o desenho dos satlites. A classe que gerencia a interao do usurio com vrios controles deslizantes e eventos de despacho quando eles ocorrem. Uma classe que representa o objeto display que gira em uma rbita ao redor de um ponto central e contm propriedades relacionadas ao estados atual do seu desenho.

com/example/programmingas3/algorithmic/AlgorithmicVisualGenerator.as

com/example/programmingas3/algorithmic/ControlPanel.as

com/example/programmingas3/algorithmic/Satellite.as

Definio de ouvintes
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O aplicativo primeiro cria trs ouvintes. O primeiro atende um evento despachado do painel de controle informando que necessrio recriar os satlites. O segundo atende s alteraes de tamanho do palco do arquivo SWF. O terceiro atende a cada transmisso de quadro no arquivo SWF e para redesenhar utilizando a funo doEveryFrame().

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API de desenho

226

Criao de satlites
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Assim que os ouvintes estiverem definidos, a funobuild() chamada. Essa funo chama primeiro a funo clear(), que esvazia a matriz satellites e apaga qualquer desenho anterior no palco. Isso necessrio pois a funo build() pode ser chamada novamente sempre que o painel de controle envia um evento para isso, como quando as configuraes de cor so alteradas. Nesse caso, os satlites devem ser removidos e recriados. A funo ento cria os satlites, configurando as propriedades iniciais necessrias para a criao, como a varivel
position, que comea em uma posio aleatria na rbita, e a varivel color, que neste exemplo no alterada pois

o satlite foi criado. Como cada satlite criado, uma referncia a ele includa na matriz satellites. Quando a funo doEveryFrame() chamada, ela ser atualizada para todos os satlites nessa matriz.

Atualizao da posio do satlite

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A funo doEveryFrame() o corao do processo de animao do aplicativo. Ela chamada para cada quadro, em uma taxa igual taxa de quadro do arquivo SWF. As pequenas alteraes das variveis do desenho transmitem a aparncia da animao. A funo primeiro apaga todos os desenhos anteriores e redesenha o plano de fundo. Em seguida, ela percorre cada continer de satlite, incrementa a propriedade position de cada satlite e atualiza as propriedades radius e orbitRadius que podem ter sido alteradas na interao do usurio com o painel de controle. Por fim, o satlite atualiza-se para a sua nova posio chamando o mtodo draw() da classe Satellite. Observe que o contador, i, incrementa apenas at a varivel visibleSatellites. Isso porque se o usurio limitar a quantidade de satlites que so exibidos no painel de controle, os satlites restantes no loop no devero ser redesenhados, mas devero ficar ocultos. Isso ocorre em um loop que segue imediatamente o loop responsvel pelo desenho. Quando a funo doEveryFrame() concluda, o nmero de visibleSatellites atualizado na posio na tela.

Resposta interao do usurio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A interao do usurio ocorre por meio do painel de controle, que gerenciado pela classe ControlPanel. Essa classe define um ouvinte junto com os valores individuais mnimo, mximo e padro de cada controle deslizante. medida que o usurio move esses controles, a funo changeSetting() chamada. Essa funo atualiza as propriedades do painel de controle. Se a alterao exigir a criao da exibio, um evento despachado e ento tratado no arquivo principal do aplicativo. medida que as configuraes do painel de controle so alteradas, a funo doEveryFrame() desenha cada satlite com as variveis atualizadas.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API de desenho

227

Personalizao posterior
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Esse exemplo apenas um esquema bsico de como gerar visuais utilizando a API de desenho. Ele usa relativamente poucas linhas de cdigo para criar uma experincia interativa que parece muito complexa. Apesar disso, esse exemplo pode ser estendido com pequenas alteraes Algumas idias:

A funo doEveryFrame() pode incrementar o valor de cor do satlite. A funo doEveryFrame() pode reduzir ou expandir o raio do satlite com o tempo. O raio do satlite no precisa ser circular; ele pode usar a classe Math para se mover de acordo com uma onda
senoidal, por exemplo.

Os satlites podem usar a deteco de pressionamento com outros satlites.

A API de desenho pode ser utilizada como uma alternativa para criar efeitos visuais no ambiente de autoria do Flash, desenhando formas bsicas no tempo de execuo. Mas ela tambm pode ser utilizada para criar efeitos visuais diversos e com escopo diferente que no podem ser criados manualmente. Com a utilizao da API de desenho e um pouco de matemtica, o autor do ActionScript pode dar vida a vrias criaes inesperadas.

Uso avanado da API de desenho

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior O Flash Player 10, o Adobe AIR 1.5 e os tempos de execuo posteriores do Flash suportam um conjunto avanado de recursos de desenho. Os aprimoramentos da API de desenho para esses tempos de execuo expandem os mtodos de desenho de verses anteriores, por isso possvel estabelecer conjuntos de dados para gerar formas, alterar formas em tempo de execuo e criar efeitos tridimensionais. Os aprimoramentos feitos na API de desenho consolidam os mtodos existentes em comandos alternativos. Esses comandos utilizam matrizes de vetor e classes de enumerao para fornecer conjuntos de dados aos mtodos de desenho. O uso de matrizes de vetor permite que formas mais complexas sejam renderizadas rapidamente e que os desenvolvedores alterem os valores de matriz de modo programtico para a renderizao dinmica de formas em tempo de execuo. Os recursos de desenho introduzidos no Flash Player 10 esto descritos nas seguintes sees: Caminhos de desenho na pgina 228, Definio de regras de contorno na pgina 230, Uso de classes de dados grficos na pgina 232 e Sobre o uso de drawTriangles() na pgina 234. As seguintes tarefas so operaes que provavelmente voc executar usando a API de desenho avanada do ActionScript:

Uso de objetos Vector para armazenar dados para mtodos de desenho Definio de caminhos para desenhar formas de modo programtico Definio de regras de contorno para determinar como preencher formas sobrepostas Uso de classes de dados grficos Uso de tringulos e mtodos de desenho para efeitos tridimensionais

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API de desenho

228

Conceitos e termos importantes A lista de referncia a seguir contm termos importantes usados nesta seo:

Vector: uma matriz de valores, todos com o mesmo tipo de dados. Um objeto Vector pode armazenar uma matriz
de valores que os mtodos de desenho usam para construir linhas e formas com um nico comando. Para obter mais informaes sobre objetos Vector, consulte Matrizes indexadas na pgina 27.

Caminho: um caminho formado por um ou mais segmentos retos ou curvos. O incio e o final de cada segmento
so marcados por coordenadas, que funcionam como alfinetes que prendem um esboo. Um caminho pode ser fechado (por exemplo, um crculo) ou aberto, com extremidades distintas (como uma linha ondulada).

Contorno: a direo de um caminho conforme interpretada pelo renderizador, seja positiva (sentido horrio) ou
negativa (sentido anti-horrio).

GraphicsStroke: classe usada para definir o estilo da linha. Embora o termo traado no faa parte dos
aprimoramentos da API de desenho, o uso de uma classe para designar um estilo de linha com sua propriedade de preenchimento faz parte da nova API de desenho. possvel ajustar o estilo de uma linha dinamicamente usando a classe GraphicsStroke.

Objeto Fill: objetos criados usando classes de exibio, como flash.display.GraphicsBitmapFill e

flash.display.GraphicsGradientFill, que so passadas para o comando de desenho Graphics.drawGraphicsData(). Os objetos Fill e os comandos de desenho aprimorados introduzem uma abordagem de programao mais orientada a objetos para replicar Graphics.beginBitmapFill() e Graphics.beginGradientFill().

Caminhos de desenho
Flash Player 10 e posterior, Adobe AIR 1.5 e posterior A seo sobre como desenhar linhas e curvas (consulte Desenho de linhas e curvas na pgina 215) apresentou os comandos usados para desenhar uma nica linha (Graphics.lineTo()) ou curva (Graphics.curveTo()) e mover a linha at outro ponto (Graphics.moveTo()) para obter uma forma. Algumas das melhorias da API de desenho do ActionScript, como Graphics.drawPath() e Graphics.drawTriangles(), utilizam os comandos de desenho existentes como parmetros. Assim, voc pode fornecer uma srie de comandos Graphics.lineTo(), Graphics.curveTo() ou Graphics.moveTo() para o tempo de execuo do Flash executar em uma nica instruo. Dois dos aprimoramentos em APIs de desenho permitem que Graphics.drawPath() e
Graphics.drawTriangles() consolidem comandos existentes:

A classe de enumerao GraphicsPathCommand: a classe GraphicsPathCommand associa vrios comandos de

desenho a valores de constante. Use uma srie desses valores como parmetros para o mtodo
Graphics.drawPath(). Em seguida, com um nico comando, voc pode renderizar a forma inteira ou vrias

formas. Tambm possvel alterar dinamicamente os valores passados para esses mtodos a fim de alterar uma forma existente.

Matrizes de vetor: as matrizes de vetor contm uma srie de valores de um tipo de dados especfico. Assim, voc
pode armazenar um grupo de constantes GraphicsPathCommand em um objeto Vector e uma srie de coordenadas em outro objeto Vector. Graphics.drawPath() ou Graphics.drawTriangles() atribui esses valores juntos para gerar um caminho de desenho ou uma forma.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API de desenho

229

No mais preciso separar comandos para cada segmento de uma forma. Por exemplo, o mtodo Graphics.drawPath() consolida Graphics.moveTo(), Graphics.lineTo() e Graphics.curveTo() em um nico mtodo. Em vez de cada mtodo ser chamado separadamente, eles so abstrados em identificadores numricos, conforme definido na classe GraphicsPathCommand. Uma operao moveTo() representada por um 1, enquanto uma operao lineTo() um 2. Armazene uma matriz desses valores em um objeto Vector.<int> para uso no parmetro commands. Em seguida, crie outra matriz que contenha coordenadas em um objeto Vector.<Number> para o parmetro data. Cada valor GraphicsPathCommand corresponde aos valores de coordenada armazenados no parmetro de dados em que dois nmeros consecutivos definem um local no espao de coordenadas de destino. Nota: Os valores do vetor no so objetos Point; o vetor consiste em uma srie de nmeros em que cada grupo de dois nmeros representa um par de coordenadas x/y. O mtodo Graphics.drawPath() compara cada comando com seus respectivos valores de ponto (uma coleo de dois ou quatro nmeros) para gerar um caminho no objeto Graphics:
package{ import flash.display.*; public class DrawPathExample extends Sprite { public function DrawPathExample(){ var square_commands:Vector.<int> = new Vector.<int>(5,true); square_commands[0] = 1;//moveTo square_commands[1] = 2;//lineTo square_commands[2] = 2; square_commands[3] = 2; square_commands[4] = 2; var square_coord:Vector.<Number> = new Vector.<Number>(10,true); square_coord[0] = 20; //x square_coord[1] = 10; //y square_coord[2] = 50; square_coord[3] = 10; square_coord[4] = 50; square_coord[5] = 40; square_coord[6] = 20; square_coord[7] = 40; square_coord[8] = 20; square_coord[9] = 10; graphics.beginFill(0x442266);//set the color graphics.drawPath(square_commands, square_coord); } } }

No exemplo acima, cada comando e par de coordenadas so designados individualmente para mostrar sua posio na matriz, mas podem ser atribudos em uma nica instruo. O exemplo a seguir desenha a mesma estrela designando os valores para cada matriz em uma instruo push():

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API de desenho

230

package{ import flash.display.*; public class DrawPathExample extends Sprite { public function DrawPathExample(){ var square_commands:Vector.<int> = new Vector.<int>(); square_commands.push(1, 2, 2, 2, 2); var square_coord:Vector.<Number> = new Vector.<Number>(); square_coord.push(20,10, 50,10, 50,40, 20,40, 20,10); graphics.beginFill(0x442266); graphics.drawPath(square_commands, square_coord); } } }

Definio de regras de contorno

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior A API de desenho aprimorada tambm introduz o conceito de "espiral" do caminho: a direo para o caminho. O contorno de um caminho tanto positivo (sentido horrio) quanto negativo (sentido anti-horrio). A ordem em que o renderizador interpreta as coordenadas fornecidas pelo vetor para o parmetro de dados determina o contorno.
A

3 B

1 C

Contorno positivo e negativo A. Setas indicam a direo do desenho B. Rotao positiva (sentido horrio) C. Rotao negativa (sentido anti-horrio)

Alm disso, observe que o mtodo Graphics.drawPath() tem um terceiro parmetro opcional, chamado winding:
drawPath(commands:Vector.<int>, data:Vector.<Number>, winding:String = "evenOdd"):void

Neste contexto, o terceiro parmetro uma string ou uma constante que especifica a regra de contorno ou de preenchimento para interseco de caminhos. (Os valores de constante so definidos na classe GraphicsPathWinding como GraphicsPathWinding.EVEN_ODD ou GraphicsPathWinding.NON_ZERO.) A regra de contorno importante quando ocorre interseco de caminhos. A regra par-mpar a regra de contorno padro, sendo usada pela API de desenho herdada. Par-mpar tambm a regra padro para o mtodo Graphics.drawPath(). Com a regra de contorno par-mpar, qualquer caminho de interseco alterna entre preenchimentos abertos e fechados. Se houver interseco de dois quadrados desenhados com o mesmo preenchimento, a rea em que ocorre a interseco ser preenchida. Geralmente, as reas adjacentes no so ambas preenchidas nem ambas no preenchidas.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API de desenho

231

A regra diferente de zero, por outro lado, depende do contorno (direo do desenho) para determinar se reas definidas por caminhos de interseco so preenchidas. Quando caminhos de contorno opostos se cruzam, a rea definida no preenchida, bem parecido com o que ocorre na regra par-mpar. Para caminhos com o mesmo contorno, a rea que no seria preenchida preenchida:

Regras de contorno para reas de interseco A. Regra de contorno par-mpar B. Regra de contorno diferente de zero

Nomes de regras de contorno

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Os nomes referem-se a uma regra mais especfica que define como esses preenchimentos so gerenciados. Caminhos de rotao positiva recebem um valor de +1; caminhos de rotao negativa recebem um valor de -1. Comeando em um ponto dentro de uma rea fechada de uma forma, desenhe uma linha a partir desse ponto que se estenda indefinidamente. O nmero de vezes que a linha cruza um caminho e os valores combinados desses caminhos so usados para determinar o preenchimento. Para contorno par-mpar, usado o nmero de vezes em que a linha cruza um caminho. Quando a contagem mpar, a rea preenchida. Para contagens pares, a rea no preenchida. Para contorno diferente de zero, so usados os valores atribudos aos caminhos. Quando os valores combinados do caminho no so 0, a rea preenchida. Quando os valores combinados so 0, a rea no preenchida.

Preenchimentos e contagens de regras de contorno A. Regra de contorno par-mpar B. Regra de contorno diferente de zero

Uso de regras de contorno

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Essas regras de preenchimento so complicadas, mas em algumas situaes elas so necessrias. Por exemplo, pense no desenho de uma forma de estrela. Com a regra par-mpar padro, a forma exigiria dez linhas diferentes. Com a regra de contorno diferente de zero, essas dez linhas so reduzidas a cinco. Este o ActionScript de uma estrela com cinco linhas e uma regra de contorno diferente de zero:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API de desenho

232

graphics.beginFill(0x60A0FF); graphics.drawPath( Vector.<int>([1,2,2,2,2]), Vector.<Number>([66,10, 23,127, 122,50, 10,49, 109,127]), GraphicsPathWinding.NON_ZERO);

E esta a forma de estrela:

Uma forma de estrela usando regras de contorno diferente A. 10 linhas pares-mpares B. 5 linhas pares-mpares C. 5 linhas diferentes de zero

E, medida que imagens so animadas ou usadas como texturas em objetos tridimensionais e se sobrepem, as regras de contorno tornam-se mais importantes.

Uso de classes de dados grficos

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior A API de desenho aprimorada introduz uma coleo de classes no pacote flash.display do tipo IGraphicsData (uma interface implementada por cada uma das classes). As classes que implementam a interface IGraphicsData funcionam como contineres de dados para os mtodos da API de desenho. As seguintes classes implementam a interface IGraphicsData:

GraphicsBitmapFill GraphicsEndFill GraphicsGradientFill GraphicsPath GraphicsShaderFill GraphicsSolidFill GraphicsStroke GraphicsTrianglePath

Com elas, possvel armazenar desenhos completos em uma matriz de objeto Vector do tipo IGraphicsData (Vector.<IGraphicsData>) que pode ser reutilizada como fonte de dados para outras ocorrncias da forma ou para armazenar informaes para uso posterior. Observe que existem vrias classes de preenchimento para cada estilo de preenchimento, mas somente uma classe de traado. O ActionScript tem apenas uma classe de traado IGraphicsData, pois a classe de traado usa as classes de preenchimento para definir seu estilo. Assim, cada traado , na verdade, a classe de traado e uma classe de preenchimento. Do contrrio, a API dessas classes de dados grficos espelha os mtodos que elas representam na classe flash.display.Graphics:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API de desenho

233

Mtodo de Graphics beginBitmapFill() beginFill() beginGradientFill() beginShaderFill() lineBitmapStyle() lineGradientStyle() lineShaderStyle() lineStyle() moveTo() lineTo() curveTo() drawPath() drawTriangles()

Classe de dados GraphicsBitmapFill GraphicsSolidFill GraphicsGradientFill GraphicsShaderFill GraphicsStroke + GraphicsBitmapFill GraphicsStroke + GraphicsGradientFill GraphicsStroke + GraphicsShaderFill GraphicsStroke + GraphicsSolidFill GraphicsPath

GraphicsTrianglePath

Alm disso, a classe GraphicsPath tem seus prprios mtodos de utilitrio GraphicsPath.moveTo(), GraphicsPath.lineTo(), GraphicsPath.curveTo(), GraphicsPath.wideLineTo() e GraphicsPath.wideMoveTo() que facilitam a definio desses comandos para uma instncia de GraphicsPath. Esses mtodos de utilitrio facilitam a definio ou a atualizao direta dos comandos e valores de dados. Uma vez que voc tem uma coleo de ocorrncias de IGraphicsData, use o mtodo Graphics.drawGraphicsData() para renderizar os grficos. O mtodo Graphics.drawGraphicsData() executa um vetor de ocorrncias de IGraphicsData atravs da API de desenho em ordem seqencial:
// stroke object var stroke:GraphicsStroke = new GraphicsStroke(3); stroke.joints = JointStyle.MITER; stroke.fill = new GraphicsSolidFill(0x102020);// solid stroke // fill object var fill:GraphicsGradientFill = new GraphicsGradientFill(); fill.colors = [0x0000FF, 0xEEFFEE]; fill.matrix = new Matrix(); fill.matrix.createGradientBox(70,70, Math.PI/2); // path object var path:GraphicsPath = new GraphicsPath(new Vector.<int>(), new Vector.<Number>()); path.commands.push(1,2,2); path.data.push(125,0, 50,100, 175,0); // combine objects for complete drawing var drawing:Vector.<IGraphicsData> = new Vector.<IGraphicsData>(); drawing.push(stroke, fill, path); // draw the drawing graphics.drawGraphicsData(drawing);

Modificando-se um valor no caminho usado pelo desenho do exemplo, possvel redesenhar a forma vrias vezes para uma imagem mais complexa:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API de desenho

234

// draw the drawing multiple times // change one value to modify each variation graphics.drawGraphicsData(drawing); path.data[2] += 200; graphics.drawGraphicsData(drawing); path.data[2] -= 150; graphics.drawGraphicsData(drawing); path.data[2] += 100; graphics.drawGraphicsData(drawing); path.data[2] -= 50;graphicsS.drawGraphicsData(drawing);

Embora objetos IGraphicsData possam definir estilos de preenchimento e de traado, esses estilos no so obrigatrios. Em outras palavras, os mtodos da classe Graphics podem ser usados para definir estilos, enquanto os objetos IGraphicsData podem ser usados para desenhar uma coleo de caminhos salvos ou vice-versa. Nota: Use o mtodo Graphics.clear() para remover um desenho anterior antes de comear um novo, a menos que voc esteja aumentando o desenho original, como visto no exemplo acima. Quando alterar uma nica parte de um caminho ou de uma coleo de objetos IGraphicsData, redesenhe o desenho inteiro para ver as alteraes. Quando so usadas classes de dados grficos, o preenchimento renderizado sempre que trs ou mais pontos so desenhados porque a forma inerentemente fechada nesse ponto. Embora o preenchimento seja fechado, o traado no , e esse comportamento diferente de quando so usados vrios comandos Graphics.lineTo() ou Graphics.moveTo().

Sobre o uso de drawTriangles()

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Outro mtodo avanado introduzido no Flash Player 10 e no Adobe AIR 1.5, Graphics.drawTriangles(), como o mtodo Graphics.drawPath(). O mtodo Graphics.drawTriangles() tambm usa um Vector.<Number> para especificar localizaes de pontos para desenhar um caminho. No entanto, a verdadeira finalidade do mtodo Graphics.drawTriangles() facilitar os efeitos tridimensionais atravs do ActionScript. Para obter informaes sobre como usar Graphics.drawTriangles() para produzir efeitos tridimensionais, consulte Uso de tringulos para obter efeitos 3D na pgina 348.

ltima atualizao em 29/3/2011

235

Captulo 12: Trabalho com bitmaps

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Alm dos recursos de desenho de vetores, o ActionScript 3.0 permite criar imagens de bitmap ou manipular dados em pixels de imagens de bitmap externas carregadas em um arquivo SWF. Com a habilidade de acessar e alterar valores de pixel individuais, voc pode criar seus prprios efeitos de imagem semelhantes a filtros e usar as funes internas de rudo para criar texturas e rudos aleatrios.

Noes bsicas do trabalho com bitmaps

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Quando voc trabalha com imagens digitais, provavelmente encontra dois tipos principais de grficos: bitmap e vetor. Os grficos bitmap, tambm conhecidos como grficos raster, so compostos por pequenos quadrados (pixels) organizados em um formato de grade retangular. Os grficos de vetor so compostos por formas geomtricas geradas matematicamente, como linhas, curvas e polgonos. As imagens de bitmap so definidas pela largura e altura da imagem, medidas em pixels, e pelo nmero de bits contido em cada pixel, que representa o nmero de cores que um pixel pode conter. No caso das imagens de bitmap que utilizam o modelo de cor RGB, os pixels so compostos por trs bytes: vermelho, verde e azul. Cada um desses bytes contm um valor que varia de 0 a 255. Quando os bytes so combinados em pixels, eles produzem uma cor semelhante cor produzida quando um artista mistura cores de pintura. Por exemplo, um pixel que contm valores de byte de vermelho-255, verde-102 e azul-0 produz uma cor laranja vibrante. A qualidade de uma imagem de bitmap determinada pela combinao de resoluo de imagem e o valor de bits da densidade de cor. Resoluo relaciona-se ao nmero de pixels contido dentro de uma imagem. Quanto maior o nmero de pixels, mais alta a resoluo e melhor a imagem aparece. Densidade de cor relaciona-se quantidade de informaes que um pixel pode conter. Por exemplo, uma imagem que tem um valor de densidade de cor de 16 bits por pixel no pode representar o mesmo nmero de cores que uma imagem que tem uma densidade de cor de 48 bits. Conseqentemente, a imagem de 48 bits ter graus de sombreamento mais suaves do que a contraparte de 16 bits. Como os grficos de bitmap dependem da resoluo, eles no so dimensionados muito bem. Isso mais facilmente notado quando imagens de bitmap so aumentadas em tamanho. Aumentar um bitmap normalmente resulta em perda de detalhes e qualidade. Formatos de arquivo bitmap As imagens bitmap so agrupadas em vrios formatos de arquivo comuns. Esses formatos usam tipos diferentes de algoritmos de compactao para reduzir o tamanho do arquivo, bem como otimizar a qualidade da imagem com base no objeto final da imagem. Os formatos de imagem de bitmap suportados pelos tempos de execuo da Adobe so BMP, GIF, JPG, PNG e TIFF. BMP O formato BMP (bit mapped) um formato de imagem padro usado pelo sistema operacional Microsoft Windows. Por no utilizar algoritmos de compactao de nenhum tipo, o tamanho dos arquivos BMP maior.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bitmaps

236

GIF O GIF (Graphics Interchange Format) foi originalmente desenvolvido pela CompuServe em 1987 como uma forma de transmitir imagem com 256 cores (cor de 8 bits). O formato fornece tamanhos pequenos de arquivo e ideal para imagens com base na Web. Devido a esse palete de cores limitado do formato, as imagens GIF no so normalmente para fotografias, que geralmente exigem mais graus de sombreamento e gradientes de cor. As imagens GIF permitem transparncia de bit nico, possibilitando que as cores sejam mapeadas como claras (ou transparentes). Isso resulta na cor de plano de fundo de uma pgina da Web mostrada atravs da imagem onde a transparncia foi mapeada. JPEG Desenvolvido pelo Joint Photographic Experts Group (JPEG), o formato de imagem JPEG (tambm escrito como JPG) usa um algoritmo de compactao com perdas para permitir densidade de cores de 24 bits com tamanho de arquivo pequeno. Compactao com perdas significa que sempre que a imagem salva, ela perde qualidade de dados, mas resulta em um tamanho de arquivo menor. O formato JPEG ideal para fotografias porque ele capaz de exibir milhes de cores. A habilidade de controlar o grau de compactao aplicada a uma imagem permite manipular a qualidade da imagem e o tamanho do arquivo. PNG O formato PNG (Portable Network Graphics) foi produzido como uma alternativa de fonte aberta para o formato de arquivo GIF patenteado. O formato PNG suporta densidade de cores de at 64 bits, permitindo at 16 milhes de cores. Como o PNG relativamente um novo formato, alguns navegadores antigos no suportam arquivos PNG. Diferentemente dos JPGs, os PNGs usam compactao sem perda, o que significa que nenhum dado da imagem perdido quando a imagem salva. Os arquivos PNG tambm suportam transparncia alfa, que permite at 256 nveis de transparncia. TIFF O TIFF (Tagged Image File Format) foi o formato compatvel com vrias plataformas escolhido antes do surgimento do PNG. A desvantagem desse formato que, devido grande variedade de TIFFs, no h um nico leitor que possa manipular cada verso. Alm disso, no h navegadores da Web que suportam esse formato atualmente. Esse formato usa compactao com ou sem perdas, e pode manipular espaos de cor especficos do dispositivo (como CMYK). Bitmaps transparentes e opacos As imagens de bitmap que usam os formatos GIF ou PNG podem ter um byte extra (canal alfa) adicionado a cada pixel. O byte de pixel extra representa o valor da transparncia do pixel. As images GIF permitem transparncia de nico bit, o que significa que voc pode especificar uma nica cor, de um palete de 256 cores, para ser transparente. As imagens PNG, por outro lado, podem ter at 256 nveis de transparncia. Essa funo traz benefcios especialmente quando imagens ou texto devem ficar mesclados nos planos de fundo. O ActionScript 3.0 replica esse byte de pixel de transparncia extra dentro da classe BitmapData. Semelhante ao modelo de transparncia do PNG, o ActionScript oferece at 256 nveis de transparncia. Conceitos e termos importantes A lista a seguir contm termos importantes que voc vai encontrar ao conhecer o grfico de bitmap:
Alfa O nvel de transparncia (ou mais precisamente, de opacidade) em uma cor ou uma imagem. O valor de alfa freqentemente descrito como o valor do canal alfa. Cor ARGB Um esquema de cores em que cada cor de pixel uma mistura de valores das cores vermelho, verde e azul,

e sua transparncia especificada como um valor alfa.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bitmaps

237

Canal de cor Normalmente, as cores so representadas como uma mistura de algumas cores bsicas - geralmente (para grficos de computador) vermelho, verde e azul. Cada cor bsica considerada um canal de cor; as quantidades de cor em cada canal de cor, misturadas, determinam a cor final. Intensidade de cor Tambm conhecido como densidade de bits, refere-se quantidade de memria do computador que est atribuda a cada pixel, que por sua vez determina o nmero de cores possveis que podem ser representadas na imagem. Pixel A menor unidade de informao em uma imagem de bitmap essencialmente um ponto de cor. Resoluo As dimenses em pixel de uma imagem, que determinam o nvel de detalhes granulados contidos na

imagem. A resoluo freqentemente expressa em termos de largura e altura em nmero de pixels.

Cor RGB Um esquema de cores em que cada cor de pixel representada como uma mistura de valores das cores vermelho, verde e azul.

Classes Bitmap e BitmapData

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior As principais classes do ActionScript 3.0 para trabalhar com imagens de bitmpa so a classe Bitmap, que usada para exibir as imagens de bitmap na tela, e a classe BitmapData, usada para acessar e manipular os dados brutos de imagem de um bitmpa.

Mais tpicos da Ajuda

flash.display.Bitmap flash.display.BitmapData

Compreenso da classe Bitmap

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Como uma subclasse da classe DisplayObject, a classe Bitmap a principal classe do ActionScript 3.0 usada para exibir imagens de bitmap. Essas imagens podem ter sido carregadas atravs da classe flash.display.Loader ou criada dinamicamente com o construtor Bitmap(). Durante o carregamento de uma imagem a partir de uma fonte externa, um objeto Bitmap pode usar apenas imagens nos formatos GIF, JPEG ou PNG. Depois de instanciado, a ocorrncia de Bitmap pode ser considerada um wrapper para um objeto BitmapData que precisa ser renderizado no Palco. Como uma ocorrncia de bitmap um objeto de exibio, todos os recursos e funcionalidade dos objetos de exibio tambm podem ser usados para manipular uma ocorrncia de Bitmap. Para obter mais informaes sobre como trabalhar com objetos de exibio, consulte Programao de exibio na pgina 145.

Encaixe e suavizao de pixels

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Alm da funcionalidade comum para todos os objetos de exibio, a classe Bitmap fornece alguns recursos adicionais que so especficos para imagens bitmaps. A propriedade pixelSnapping da classe Bitmap determina se um objeto Bitmap se encaixa ou no no seu pixel mais prximo. Essa propriedade aceita uma das trs constantes definidas na classe PixelSnapping: ALWAYS, AUTO eNEVER.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bitmaps

238

A sintaxe para aplicao de encaixe de pixel como se segue:

myBitmap.pixelSnapping = PixelSnapping.ALWAYS;

Freqentemente, quando imagens de bitmap so escalada, elas ficam borradas e distorcidas. Para ajudar a reduzir essa distoro, use a propriedade smoothing da classe BitmapData. Essa propriedade Boolean, quando definida como true, suaviza os pixels dentro da imagem quando ela escalada. Isso d imagem uma aparncia mais clara e natural.

Compreenso da classe BitmapData

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe BitmapData, que est no pacote flash.display, pode ser comparada a um snapshot fotogrfico de pixels contido em um imagem de bitmap carregada ou criada dinamicamente. Esse snapshot representado por uma matriz de dados de pixel dentro do objeto. A classe BitmapData tambm contm uma srie de mtodos incorporados que so utilizados para a criao e a manipulao de dados de pixel. Para instanciar um objeto BitmapData, use o seguinte cdigo:
var myBitmap:BitmapData = new BitmapData(width:Number, height:Number, transparent:Boolean, fillColor:uinit);

Os parmetros width e height especificam o tamanho do bitmap. No AIR 1.5 e no Flash Player 10, o tamanho mximo de um objeto BitmapData de 8.191 pixels de largura ou de altura, e o nmero total de pixels no pode exceder 16.777.215 pixels. (Dessa forma, caso um objeto BitmapData tenha 8.191 pixels de largura, ele s pode ter 2.048 pixels de altura.) No Flash Player 9 e anteriores e no AIR 1.1 e anteriores, a limitao de 2.880 de altura e de 2.880 pixels de largura. O parmetro transparent especifica se os dados de bitmap incluem um canal alfa (true) ou no (false). O parmetro fillColor um valor de cor de 32 bits que especifica a cor de plano de fundo, bem como o valor de transparncia (se ele tiver sido definido como true). O exemplo a seguir cria um objeto BitmapData com plano de fundo laranja que 50% transparente.
var myBitmap:BitmapData = new BitmapData(150, 150, true, 0x80FF3300);

Para renderizar um objeto BitmapData criado recentemente na tela, atribua-o ou envolva-o em uma ocorrncia de Bitmap. Para fazer isso, voc pode transmitir o objeto BitmapData como um parmetro do construtor de objeto Bitmap ou atribu-lo propriedade bitmapData de uma ocorrncia de Bitmap existente. Voc tambm deve adicionar a ocorrncia de Bitmap lista de exibio chamando os mtodos addChild() ou addChildAt() do continer de objeto de exibio que conter a ocorrncia de Bitmap. Para obter mais informaes sobre como trabalhar com a lista de exibio, consulte Adio de objetos de exibio lista de exibio na pgina 153. O exemplo a seguir cria um objeto BitmapData com preenchimento vermelho e exibe-o em uma ocorrncia de Bitmap.
var myBitmapDataObject:BitmapData = new BitmapData(150, 150, false, 0xFF0000); var myImage:Bitmap = new Bitmap(myBitmapDataObject); addChild(myImage);

Manipulao de pixels
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe BitmapData tambm contm um conjunto de mtodos que permitem manipular valores de dados de pixels.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bitmaps

239

Manipulao de pixels individuais

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Ao alterar a aparncia de uma imagem de bitmap no nvel de pixel, voc primeiro precisa obter os valores de cores dos pixels contidos dentro da rea que deseja manipular. Use o mtodo getPixel() para ler esses valores de pixel. O mtodo getPixel() recupera um valor RGB a partir de um conjunto de coordenadas x, y (pixel) transmitidas como parmetros. Se qualquer um dos pixels que voc deseja manipular incluir informaes sobre transparncia (canal alfa), ser necessrio usar o mtodo getPixel32(). Esse mtodo tambm recupera um valor RGB, mas diferente de getPixel(), o valor retornado por getPixel32() contm dados adicionais que representam o valor do canal alfa (transparncia) do pixel selecionado. Como alternativa, se voc quiser simplesmente alterar a cor ou a transparncia de um pixel contido em um bitmap, poder usar o mtodo setPixel() ou setPixel32(). Para definir uma cor de pixels, transmita simplesmente as coordenadas x, y e o valor da cor para um desses mtodos. O exemplo a seguir usa o mtodo setPixel() para desenhar uma cruz em um plano de fundo BitmapData verde: Ele ento usa getPixel() para recuperar o valor da cor do pixel nas coordenadas 50, 50 e liga o valor retornado.
import flash.display.Bitmap; import flash.display.BitmapData; var myBitmapData:BitmapData = new BitmapData(100, 100, false, 0x009900); for (var i:uint = 0; i < 100; i++) { var red:uint = 0xFF0000; myBitmapData.setPixel(50, i, red); myBitmapData.setPixel(i, 50, red); } var myBitmapImage:Bitmap = new Bitmap(myBitmapData); addChild(myBitmapImage); var pixelValue:uint = myBitmapData.getPixel(50, 50); trace(pixelValue.toString(16));

Se voc quiser ler o valor de um grupo de pixels, use o mtodo getPixels(). Esse mtodo gera uma matriz de bytes a partir de uma regio retangular dos dados de pixels que so transmitidos como um parmetro. Cada um dos elementos da matriz de bytes (em outra palavras, os valores de pixel) so valores de pixel inteiros no assinados de 32 bits e no multiplicados. Inversamente, para alterar (ou definir) o valor de um grupo de pixels, use o mtodo setPixels(). Esse mtodo espera dois parmetros (rect e inputByteArray), que so combinados para resultar em uma regio retangular (rect) dos dados de pixel (inputByteArray). Como os dados so lidos (e gravados) fora de inputByteArray, o mtodo ByteArray.readUnsignedInt() chamado para cada um dos pixels na matriz. Se, por alguma razo, inputByteArray no contiver pelo menos um retangular inteiro de dados de pixel, o mtodo interromper o processamento dos dados da imagem naquele ponto. importante lembrar que, para obter e configurar dados de pixel, a matriz de byte espera valores de pixel vermelho, verde, azul e alfa de 32 bits (ARGB). O exemplo a seguir usa os mtodos getPixels() e setPixels() para copiar um grupo de pixels de um objeto BitmapData para outro:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bitmaps

240

import import import import

flash.display.Bitmap; flash.display.BitmapData; flash.utils.ByteArray; flash.geom.Rectangle;

var bitmapDataObject1:BitmapData = new BitmapData(100, 100, false, 0x006666FF); var bitmapDataObject2:BitmapData = new BitmapData(100, 100, false, 0x00FF0000); var rect:Rectangle = new Rectangle(0, 0, 100, 100); var bytes:ByteArray = bitmapDataObject1.getPixels(rect); bytes.position = 0; bitmapDataObject2.setPixels(rect, bytes); var bitmapImage1:Bitmap = new Bitmap(bitmapDataObject1); addChild(bitmapImage1); var bitmapImage2:Bitmap = new Bitmap(bitmapDataObject2); addChild(bitmapImage2); bitmapImage2.x = 110;

Deteco de coliso de nvel de pixel

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O mtodo BitmapData.hitTest() executa a deteco de coliso no nvel de pixel entre os dados de bitmap e outro objeto ou ponto. O mtodo BitmapData.hitTest() aceita cinco parmetros:

firstPoint (Point): Esse parmetro se refere posio do pixel do canto superior esquerdo do primeiro

BitmapData no qual o teste de ocorrncia est sendo executado.

firstAlphaThreshold (uint): Esse parmetro especifica o valor de canal alfa mais alto que considerado opaco

para esse teste de ocorrncia.

secondObject (Object): Esse parmetro representa a rea de impacto. O objeto secondObject no pode ser um

objeto Rectangle, Point, Bitmap ou BitmapData. Esse objeto representa a rea de ocorrncia na qual a deteco de coliso est sendo executada.

secondBitmapDataPoint (Point): Esse parmetro opcional usado para definir uma localizao de pixel no

segundo objeto BitmapData. Use esse parmetro apenas quando o valor de secondObject for um objeto BitmapData. O padro null.

secondAlphaThreshold (uint): Esse parmetro opcional representa o valor de canal alfa mais alto que considerado opaco no segundo objeto BitmapData. O valor padro 1. Use esse parmetro apenas quando o valor de secondObject for um objeto BitmapData e quando ambos os objetos BitmapData forem transparentes.

Ao executar a deteco de coliso em imagens opacas, lembre-se de que o ActionScript trata a imagem como se ela fosse um retngulo totalmente opaco (ou caixa delimitadora). Como alternativa, ao executar teste de ocorrncia em nvel de pixel em imagens transparentes, ambas as imagens devem ser transparentes. Alm disso, o ActionScript usa os parmetros de limitao de alfa para determinar em qual ponto os pixels so alterados de transparente para opaco. O exemplo a seguir cria trs imagens de bitmap e verifica se h coliso de pixel utilizando dois diferentes pontos de coliso (um retorna false e outro true):

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bitmaps

241

import flash.display.Bitmap; import flash.display.BitmapData; import flash.geom.Point; var bmd1:BitmapData = new BitmapData(100, 100, false, 0x000000FF); var bmd2:BitmapData = new BitmapData(20, 20, false, 0x00FF3300); var bm1:Bitmap = new Bitmap(bmd1); this.addChild(bm1); // Create a red square. var redSquare1:Bitmap = new Bitmap(bmd2); this.addChild(redSquare1); redSquare1.x = 0; // Create a second red square. var redSquare2:Bitmap = new Bitmap(bmd2); this.addChild(redSquare2); redSquare2.x = 150; redSquare2.y = 150; // Define the var pt1:Point // Define the var pt2:Point // Define the var pt3:Point point = new point = new point = new at the top-left corner of the bitmap. Point(0, 0); at the center of redSquare1. Point(20, 20); at the center of redSquare2. Point(160, 160);

trace(bmd1.hitTest(pt1, 0xFF, pt2)); // true trace(bmd1.hitTest(pt1, 0xFF, pt3)); // false

Cpia de dados de bitmap

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para copiar dados de bitmap de uma imagem para outra, voc pode usar vrios mtodos: clone(), copyPixels(), copyChannel() edraw(). Como o nome sugere, o mtodo clone() permite clonar, ou obter uma amostra, dos dados de bitmap de um objeto BitmapData para outro. Quando chamado, o mtodo retorna um novo objeto BitmapData que um clone exato da ocorrncia original do qual foi copiado. O exemplo a seguir clona uma cpia de um quadrado (pai) laranja e coloca o clone ao lado do quadrado pai original:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bitmaps

242

import flash.display.Bitmap; import flash.display.BitmapData; var myParentSquareBitmap:BitmapData = new BitmapData(100, 100, false, 0x00ff3300); var myClonedChild:BitmapData = myParentSquareBitmap.clone(); var myParentSquareContainer:Bitmap = new Bitmap(myParentSquareBitmap); this.addChild(myParentSquareContainer); var myClonedChildContainer:Bitmap = new Bitmap(myClonedChild); this.addChild(myClonedChildContainer); myClonedChildContainer.x = 110;

O mtodo copyPixels() um modo fcil e rpido de copiar pixels de um objeto BitmapData para outro. O mtodo obtm um snapshot retangular (definido pelo parmetro sourceRect) da imagem de origem e a copia para outra rea retangular (de tamanho igual). O local do retngulo "colado" recentemente definido dentro do parmetro destPoint. O mtodo copyChannel() fornece amostras de um valor de canal de cor predefinido (alfa, vermelho, verde ou azul) de um objeto BitmapData de origem e o copia para um canal de um objeto BitmapData de destino. Chamar esse mtodo no afeta os outros canais no objeto BitmapData de destino. O mtodo draw() desenha, ou processa, o contedo grfico de um sprite de origem, clipe de filme ou outro objeto de exibio em um novo bitmap. Usando matrix, colorTransform, blendMode e os parmetros de destinoclipRect, voc pode modificar a forma na qual o novo bitmap renderizado. Esse mtodo usa o processador de vetor no Flash Player e no AIR para gerar os dados. Quando voc chama draw(), transmite o objeto de origem (sprite, clipe de filme ou outro objeto de exibio) como o primeiro parmetro, como demonstrado aqui:
myBitmap.draw(movieClip);

Se o objeto de origem teve qualquer transformao (cor, matriz etc.) aplicada a ele depois que ele foi originalmente carregado, essas transformaes no sero copiadas para o novo objeto. Se voc quiser copiar as transformaes para o novo bitmap, ser necessrio copiar o valor da propriedade transform do objeto original para a propriedade transform do objeto Bitmap que usa o novo objeto BitmapData.

Texturas com funes de rudo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para modificar a aparncia de um bitmap, voc pode aplicar um efeito de rudo nele, usando o mtodo noise() ou os mtodos perlinNoise(). Um efeito de rudo pode ser comparado a um esttico que aparece em uma tela de televiso no sintonizada. Para aplicar um efeito de rudo a um bitmap, use o mtodo noise(). Esse mtodo aplica um valor de cor aleatrio para pixels dentro de uma rea especificada de uma imagem de bitmap. Esse mtodo aceita cinco parmetros:

randomSeed (int): O nmero base aleatrio que determina o padro. Apesar do nome, esse nmero cria realmente

os mesmos resultados se o mesmo nmero transmitido. Para obter um resultado aleatrio verdadeiro, use o mtodo Math.random() para transmitir um nmero aleatrio para esse parmetro.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bitmaps

243

low (uint): Esse parmetro se refere ao valor mais baixo a ser gerado para cada pixel (0 a 255). O valor padro 0. A configurao desse valor mais baixo resulta em um padro de rudo mais escuro, enquanto a configurao de um valor mais alto resulta em um padro mais claro. high (uint): Esse parmetro se refere ao valor mais alto a ser gerado para cada pixel (0 a 255). O valor padro 255.

A configurao desse valor mais baixo resulta em um padro de rudo mais escuro, enquanto a configurao de um valor mais alto resulta em um padro mais claro.

channelOptions (uint): Esse parmetro especifica a qual canal de cores do objeto Bitmap o padro de rudo ser aplicado. O nmero pode ser uma combinao de qualquer um dos quatro valores ARGB do canal de cores. O valor padro 7. grayScale (Boolean): Quando definido para true, esse parmetro aplica o valor randomSeed aos pixels de bitmap,

eliminando efetivamente todas as cores da imagem. O canal alfa no afetado por esse parmetro. O valor padro false. O exemplo a seguir cria uma imagem de bitmap e aplica um padro de rudo azul a ela:
import flash.display.Bitmap; import flash.display.BitmapData; var myBitmap:BitmapData = new BitmapData(250, 250,false, 0xff000000); myBitmap.noise(500, 0, 255, BitmapDataChannel.BLUE,false); var image:Bitmap = new Bitmap(myBitmap); addChild(image);

Se voc quiser criar uma textura com a aparncia mais orgnica, use o mtodo perlinNoise() . O mtodo perlinNoise() produz texturas orgnicas realistas que so ideais para fumaa, nuvens, gua, fogo ou at mesmo exploses. Como isso gerado por um algoritmo, o mtodo perlinNoise() usa menos memria do que as texturas com base em bitmap. Entretanto, ele pode ainda ter um impacto no uso do processador, tornando o contedo mais lento e fazendo com que a tela seja redesenhada mais lentamente do que a taxa de quadro, especialmente em computadores mais antigos. Isso deve-se principalmente aos clculos de ponto de flutuao que precisam ocorrer para processar os algoritmos de rudo perlin. O mtodo aceita nove parmetros (os primeiro seis so obrigatrio):

baseX (Number): Determina o valor de x (tamanho) dos padres criados. baseY (Number): Determina o valor de y (tamanho) dos padres criados. numOctaves (uint): Nmero de oitavas ou funes de rudo individuais a serem combinadas para criar esse rudo.

Nmeros maiores de oitavas criam imagens com mais detalhes, mas tambm exigem mais tempo de processamento.

randomSeed (int): O nmero base aleatrio funciona exatamente da mesma forma que na funo noise(). Para obter um resultado aleatrio verdadeiro, use o mtodo Math.random() para transmitir um nmero aleatrio para esse parmetro. stitch (Boolean): Se definido para true, esse mtodo tentar suavizar as bordas de transio da imagem para criar

texturas contnuas para colocao lado a lado como um preenchimento de bitmap.

fractalNoise (Boolean): Esse parmetro relaciona as bordas de gradientes sendo geradas pelo mtodo. Se definido para true, o mtodo gerar rudo fractal que suaviza as bordas do efeito. Se definido como false, ocorre turbulncia. Uma imagem com turbulncia tem descontinuidades visveis no gradiente que podem fazer com que ela aproxime melhor os efeitos visuais mais ntidos, como chamas e ondas do mar.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bitmaps

244

channelOptions (uint): O parmetro channelOptions funciona exatamente da mesma forma que no mtodo noise(). Ele especifica a qual canal de cores (do bitmap) o padro de rudo ser aplicado. O nmero pode ser uma

combinao de qualquer um dos quatro valores ARGB do canal de cores. O valor padro 7.

grayScale (Boolean): O parmetro grayScale funciona exatamente da mesma forma que no mtodo noise().

Quando definido como true, esse parmetro aplica o valor randomSeed aos pixels de bitmap, eliminando todas as cores da imagem de modo eficaz. O valor padro false.

deslocamentos (Matriz): Uma matriz de pontos que corresponde a deslocamentos x e y para cada oitava. Ao

manipular os valores de deslocamento, voc pode rolar suavemente as camadas de uma imagem. Cada ponto na matriz de deslocamento afeta uma funo de rudo de oitava especfica. O valor padro null. O exemplo a seguir cria um objeto BitmapData de 150 x 150 pixels que chama o mtodo perlinNoise() para gerar um efeito de nuvem em verde e azul:
import flash.display.Bitmap; import flash.display.BitmapData; var myBitmapDataObject:BitmapData = new BitmapData(150, 150, false, 0x00FF0000); var seed:Number = Math.floor(Math.random() * 100); var channels:uint = BitmapDataChannel.GREEN | BitmapDataChannel.BLUE myBitmapDataObject.perlinNoise(100, 80, 6, seed, false, true, channels, false, null); var myBitmap:Bitmap = new Bitmap(myBitmapDataObject); addChild(myBitmap);

Rolagem de bitmaps
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Imagine que voc criou um aplicativo de mapeamento de ruas em que sempre que o usurio move o mapa voc precisa atualizar a visualizao (mesmo que o mapa tenha sido movido apenas alguns pixels). Uma forma de criar essa funcionalidade seria reprocessar uma nova imagem contendo a visualizao atualizada do mapa sempre que o usurio move o mapa. Como alternativa, voc pode criar uma nica imagem grande e usar o mtodo scroll(). O mtodo scroll() copia um bitmap na tela e o cola em um local de deslocamento especificado por parmetros (x, y). Se acontecer de uma parte do bitmap ficar fora do palco, o efeito resultante indicar que a imagem foi deslocada. Quando combinado com uma funo de temporizador (ou um evento enterFrame), voc poder fazer com a imagem parea ser animada ou estar em rolagem. O exemplo a seguir pega o exemplo de rudo perlin anterior e gera uma imagem de bitmap maior (trs quartos dela so renderizados fora do palco). O mtodo scroll() ento aplicado junto com um ouvinte do evento enterFrame que desloca a imagem por um pixel na direo diagonal para baixo. Esse mtodo chamado sempre que o quadro inserido e, conseqentemente, as partes da imagem fora da tela so renderizadas no Palco medida que usamos a rolagem na imagem.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bitmaps

245

import flash.display.Bitmap; import flash.display.BitmapData; var myBitmapDataObject:BitmapData = new BitmapData(1000, 1000, false, 0x00FF0000); var seed:Number = Math.floor(Math.random() * 100); var channels:uint = BitmapDataChannel.GREEN | BitmapDataChannel.BLUE; myBitmapDataObject.perlinNoise(100, 80, 6, seed, false, true, channels, false, null); var myBitmap:Bitmap = new Bitmap(myBitmapDataObject); myBitmap.x = -750; myBitmap.y = -750; addChild(myBitmap); addEventListener(Event.ENTER_FRAME, scrollBitmap); function scrollBitmap(event:Event):void { myBitmapDataObject.scroll(1, 1); }

Benefcios do mapeamento mip

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Mapas MIP (tambm conhecido como mipmaps), so bitmaps agrupados e associados a uma textura para aumentar a qualidade e o desempenho da renderizao no tempo de execuo. O Flash Player 9.115.0 e verses posteriores e o AIR implementam essa tecnologia (o processo chamado mamepaminto Mip), por meio da criao de verses otimizadas de escala varivel de cada bitmap (comeando em 50%). Os mapas MIP so criados para os seguintes tipos de bitmaps:

um bitmap (arquivos JPEG, GIF ou PNG) exibido com a classe Loader do ActionScript 3.0 um bitmap na biblioteca de um documento Flash Professional um objeto BitmapData um bitmap exibido com a funo loadMovie() do ActionScript 2.0
Os mapas MIP no so aplicados a objetos filtrados nem a clipes de filme em cache de bitmap. Entretanto, os mapas MIP so aplicados se voc tiver transformaes de bitmap em um objeto de exibio filtrado, mesmo se o bitmap estiver dentro de contedo mascarado. Os mapeamentos mip ocorre automaticamente, mas voc pode seguir algumas orientaes para se certificar de que suas imagens usem essa otimizao:

Para reproduo de vdeo, defina a propriedade smoothing como true para o objeto Video (consulte a classe
Video).

Para bitmaps, a propriedade smoothing no tem que ser definida como true, mas os aprimoramentos de qualidade
so mais visveis quando os bitmaps usam suavizao.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bitmaps

246

Use tamanhos de bitmap que so divisveis por 4 ou 8 para imagens bidimensionais (como 640 x 128, que pode ser
reduzida como se segue: 320 x 64 > 160 x 32 > 80 x 16 > 40 x 8 > 20 x 4 > 10 x 2 > 5 x 1) e 2^n para texturas tridimensionais. Os mapas MIP so gerados a partir de bitmaps que tm largura e altura que so 2^n (como 256 x 256, 512 x 512, 1024 x 1024). O mapeamento mip no ocorre para contedo de bitmap com uma largura ou altura estranhas.

Exemplo de bitmap: lua giratria animada

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O exemplo de lua giratria animada demonstra tcnicas para trabalhar com objetos Bitmap e dados de imagem de bitmap (objetos BitmapData). O exemplo cria uma animao de uma lua giratria e esfrica utilizando uma imagem plana da superfcie da lua como os dados de imagem no processados. As tcnicas a seguir so demonstradas:

Carregamento de uma imagem externa e acesso aos seus dados de imagem no processados Criao de animao por meio de cpia repetida de pixels de diferentes partes de uma imagem de origem Criao de uma imagem de bitmap pela definio de valores de pixel
Para obter os arquivos do aplicativo para este exemplo, consulte www.adobe.com/go/learn_programmingAS3samples_flash_br. Os arquivos de aplicativo da lua giratrio animada podem ser encontrados na pasta Samples/SpinningMoon. O aplicativo consiste nos seguintes arquivos:
Arquivo SpinningMoon.mxml ou SpinningMoon.fla com/example/programmingas3/moon/MoonSphere.as A classe que executa a funcionalidade de carregamento, exibio e animao da lua. O arquivo de imagem que contm uma fotografia da superfcie da lua, que carregado e utilizado para criar a lua giratrio e animada. Descrio O arquivo principal do aplicativo no Flex (MXML) ou Flash (FLA).

moonMap.png

Carregamento de uma imagem externa como dados de bitmap

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A primeira tarefa principal que essa amostra executa o carregamento de um arquivo de imagem externa, que uma fotografia da superfcie da lua. A operao de carregamento manipulada por dois mtodos na classe MoonSphere: o construtor MoonSphere(), em que o processo de carregamento iniciado, e o mtodo imageLoadComplete(), que chamado quando a imagem externa est totalmente carregada. O carregamento de uma imagem externa semelhante ao carregamento de um SWF externo; ambos utilizam uma ocorrncia da classe flash.display.Loader para executar essa operao. O cdigo real no mtodo MoonSphere() que inicia o carregamento de uma imagem o seguinte:
var imageLoader:Loader = new Loader(); imageLoader.contentLoaderInfo.addEventListener(Event.COMPLETE, imageLoadComplete); imageLoader.load(new URLRequest("moonMap.png"));

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bitmaps

247

A primeira linha declara que a ocorrncia de Loader chamada imageLoader. A terceira linha inicia realmente o processo de carregamento chamando o mtodo load() do objeto Loader, transmitindo uma ocorrncia de URLRequest que representa a URL da imagem a ser carregada. A segunda linha configura o ouvinte do evento que ser acionado quando a imagem for totalmente carregada. Observe que o mtodo addEventListener() no chamado na prpria ocorrncia de Loader; em vez disso, ele chamado na propriedade contentLoaderInfo do objeto Loader. A prpria ocorrncia de Loader no despacha eventos relacionados ao contedo sendo carregado. A propriedade contentLoaderInfo, entretanto, contm uma referncia ao objeto LoaderInfo que associado ao contedo sendo carregado no objeto Loader (a imagem externa nesse caso). Aquele objeto LoaderInfo fornece vrios eventos relacionados ao progresso e concluso do carregamento de contedo externo, incluindo o evento complete (Event.COMPLETE) que acionar uma chamada para o mtodo imageLoadComplete() quando a imagem for totalmente carregada. Embora o incio do carregamento da imagem externa seja uma parte importante do processo, igualmente importante saber o que fazer quando o carregamento for concludo. Como mostrado no cdigo acima, a funo imageLoadComplete() chamada quando a imagem carregada. Aquela funo faz vrias atividades com os dados de imagem carregados, descritas nas sees subsequentes. Contudo, para usar os dados da imagem, necessrio acessar aqueles dados. Quando o objeto Loader for utilizado para carregar uma imagem externa, a imagem carregada torna-se uma ocorrncia de bitmap que anexada a um objeto de exibio filho do objeto Loader. Nesse caso, a ocorrncia de Loader est disponvel para o mtodo do ouvinte do evento como parte do objeto de evento que transmitido para o mtodo como um parmetro. As primeiras linhas do mtodo imageLoadComplete() so como se segue:
private function imageLoadComplete(event:Event):void { textureMap = event.target.content.bitmapData; ... }

Observe que o parmetro do objeto de evento chamado event, e uma ocorrncia da classe Event. Cada ocorrncia da classe Event tem uma propriedade target, que se refere ao objeto que est acionando o evento (nesse caso, a ocorrncia de LoaderInfo na qual o mtodo addEventListener() foi chamado, conforme descrito anteriormente). O objeto LoaderInfo, por sua vez, tem uma propriedade content que (uma vez concludo o processo de carregamento) contm a ocorrncia de Bitmap com a imagem de bitmap carregada. Se voc quiser exibir a imagem diretamente na tela, poder anexar essa ocorrncia de Bitmap (event.target.content) a um continer do objeto de exibio. (Voc tambm pode anexar o objeto Loader a um continer do objeto de exibio). Entretanto, nessa amostra, o contedo carregado utilizado como uma origem dos dados da imagem no processados que esto sendo exibidos na tela. Consequentemente, a primeira linha do mtodo imageLoadComplete() l a propriedade bitmapData da ocorrncia de Bitmap carregada (event.target.content.bitmapData) e a armazena na varivel de ocorrncia chamada textureMap, que usada como uma origem de dados de imagem para criar a animao da lua giratria. Isso descrito a seguir.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bitmaps

248

Criao da animao pela cpia de pixels

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Uma definio bsica da animao a iluso de movimentao, ou alterao, criada pela alterao de uma imagem ao longo do tempo. Nessa amostra, o objetivo criar a iluso de uma lua esfrica girando ao redor de seu eixo vertical. Contudo, para o propsito de animao, voc pode ignorar o aspecto de distoro esfrica da amostra. Considere a imagem real que est carregada e usada como a origem dos dados da imagem de lua:

Como voc pode ver, a imagem no uma nem vrias esferas; ela uma fotografia retangular da superfcie da lua. Como a foto foi tirada exatamente na linha do equador da lua, as partes da imagem prximas parte superior e inferior da imagem so expandidas e distorcidas. Para remover a distoro da imagem e deix-la com uma aparncia esfrica, utilizaremos um filtro de mapa de deslocamento, como descrito posteriormente. Entretanto, como essa imagem de origem um retngulo, para criar a iluso de que a esfera est girando, o cdigo simplesmente precisa deslizar a foto da superfcie da lua horizontalmente. Observe que a imagem realmente contm duas cpias da fotografia da superfcie da lua prximas uma da outra. Essa imagem a imagem de origem da qual os dados de imagem foram copiados repetidas vezes para criar a aparncia de movimento. Tendo duas cpias da imagem prximas uma da outra, um efeito de rolagem contnuo e ininterrupto pode ser criado com mais facilidade. Vamos avanar no processo de animao etapa por etapa para ver como ele funciona. O processo realmente envolve dois objetos separados do ActionScript. Primeiro, existe a imagem de origem carregada, que no cdigo representada pela ocorrncia de BitmapData chamada textureMap. Como descrito anteriormente, textureMap preenchido com os dados de imagem assim que a imagem externa carregada, utilizando este cdigo:
textureMap = event.target.content.bitmapData;

O contedo de textureMap a imagem da lua em retngulo. Alm disso, para criar a rotao animada, o cdigo usa uma ocorrncia de Bitmap chamada sphere, que o objeto de exibio real que mostra a imagem da lua na tela. Como textureMap, o objeto sphere criado e preenchido com seus dados de imagem iniciais no mtodo imageLoadComplete(), utilizando o seguinte cdigo:
sphere = new Bitmap(); sphere.bitmapData = new BitmapData(textureMap.width / 2, textureMap.height); sphere.bitmapData.copyPixels(textureMap, new Rectangle(0, 0, sphere.width, sphere.height), new Point(0, 0));

Como mostra o cdigo, sphere instanciado. Sua propriedade bitmapData (os dados de imagem no processados que so exibidos por sphere) criada com a mesma altura e metade da largura de textureMap. Em outras palavras, o contedo de sphere ser o tamanho de uma foto da lua (desde que a imagem textureMap contenha duas fotos da lua lado a lado). Em seguida, a propriedade bitmapData preenchida com dados de imagem utilizando o mtodo copyPixels(). Os parmetros na chamada do mtodo copyPixels() indicam vrias coisas:

O primeiro parmetro indica que os dados da imagem so copiados de textureMap. ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bitmaps

249

O segundo parmetro, uma nova ocorrncia de Rectangle, especifica de qual parte de textureMap o snapshot da
imagem deve ser tirado; nesse caso, o snapshot um retngulo que comea no canto superior esquerdo de textureMap (indicado pelos dois primeiros parmetros Rectangle(): 0, 0) e a largura e a altura do snapshot do retngulo corresponde s propriedades width e height desphere.

O terceiro parmetro, uma nova ocorrncia de Point com os valores x e y de 0, define o destino dos dados de pixel
nesse caso, o canto superior esquerdo (0, 0) de sphere.bitmapData. Representado visualmente, o cdigo copia os pixels de textureMap contornados na imagem a seguir e os cola em sphere. Em outras palavras, o contedo de BitmapData desphere a parte de textureMap em destaque aqui:

Lembre-se, contudo, de que esse apenas o estado inicial de sphere o contedo da primeira imagem que copiada na sphere. Com a imagem de origem carregada e sphere criada, a tarefa final executada pelo mtodo imageLoadComplete() a configurao da animao. A animao orientada pela ocorrncia de Timer chamada rotationTimer, que criada e iniciada pelo seguinte cdigo:
var rotationTimer:Timer = new Timer(15); rotationTimer.addEventListener(TimerEvent.TIMER, rotateMoon); rotationTimer.start();

O cdigo cria primeiro a ocorrncia de Timer chamada rotationTimer; o parmetro transmitido para o construtor Timer() indica que rotationTimer deve acionar seu evento timer a cada 15 milissegundos. Em seguida, o mtodo addEventListener() chamado, especificando que, quando o evento timer (TimerEvent.TIMER) ocorre, o mtodo rotateMoon() chamado. Por fim, o temporizado realmente iniciado chamando seu mtodo start(). Devido ao modo com rotationTimer est definido, aproximadamente a cada 15 milissegundos, o Flash Player chama o mtodo rotateMoon() na classe MoonSphere, que onde a animao da lua acontece. O cdigo-fonte do mtodo rotateMoon() o seguinte:
private function rotateMoon(event:TimerEvent):void { sourceX += 1; if (sourceX > textureMap.width / 2) { sourceX = 0; } sphere.Data.copyPixels(textureMap, new Rectangle(sourceX, 0, sphere.width, sphere.height), new Point(0, 0)); event.updateAfterEvent(); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bitmaps

250

O cdigo faz trs coisas:

1 O valor da varivel sourceX (inicialmente definido como 0) incrementado em 1.
sourceX += 1;

Como voc ver, sourceX usado para determinar o local em textureMap do qual os pixels sero copiados para sphere; portanto esse cdigo tem o efeito de mover o retngulo um pixel para a direita em textureMap. Voltando representao visual, depois de vrios ciclos de animao, o retngulo de origem ter se movido vrios pixels para a direita, como se segue:

Depois de vrios outros ciclos, o retngulo ter se movido para mais longe:

Esse deslocamento gradual, uniforme no local do qual os pixels so copiados a chave da animao. Movendo lenta e continuamente o local de origem para a direita, a imagem que exibida na tela em sphere parece deslizar continuamente para a esquerda. Essa a razo pela qual a imagem de origem (textureMap) precisa ter duas cpias da foto da superfcie da lua. Como o retngulo se move continuamente para a direita, a maioria das vezes ele no est sobre uma nica foto da lua, mas sobrepe as duas fotos da lua.
2 Com o retngulo de origem movendo-se lentamente para a direita, h um problema. Finalmente, o retngulo

atingir a borda direita de textureMap e ficar sem os pixels da foto da lua para copiar na sphere:

As linhas de cdigo a seguir solucionam esse problema:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bitmaps

251

if (sourceX >= textureMap.width / 2) { sourceX = 0; }

O cdigo verifica se sourceX (a borda esquerda do retngulo) atingiu o meio de textureMap. Em caso afirmativo, ele redefine sourceX para 0, movendo-o para a borda esquerda de textureMap e iniciando o ciclo novamente:

3 Com o valor sourceX apropriado calculado, a etapa final na criao da animao copiar realmente os pixels do

novo retngulo de origem para sphere. O cdigo que faz isso muito semelhante ao cdigo que inicialmente preenche sphere (descrito anteriormente); a nica diferena que nesse caso, na chamada do construtor new Rectangle(), a borda esquerda do retngulo colocada em sourceX:
sphere.bitmapData.copyPixels(textureMap, new Rectangle(sourceX, 0, sphere.width, sphere.height), new Point(0, 0));

Lembre-se de que esse cdigo chamada repetidamente a cada 15 milissegundos. Como o local do retngulo de origem deslocado de forma contnua, e os pixels so copiados em sphere, a aparncia na tela a de que a imagem da foto da lua representada por sphere desliza continuamente. Em outras palavras, a lua parece girar continuamente.

Criao da aparncia esfrica

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A lua, claro, uma esfera e no um retngulo. Conseqentemente, a mostra precisa pegar a foto da superfcie da lua retangular, medida que animada continuamente, e convert-la em uma esfera. Isso envolve duas etapas separadas: uma mscara usada para ocultar todo o contedo exceto uma regio circular da foto da superfcie da lua, e um filtro de mapa de deslocamento usado para distorcer a aparncia da foto da lua para que ela parea tridimensional. Primeiro, uma mscara no formato de crculo usada para ocultar todo o contedo do objeto MoonSphere exceto a esfera criada pelo filtro. O cdigo a seguir cria a mscara como uma ocorrncia de Shape e a aplica como a mscara da ocorrncia MoonSphere:
moonMask = new Shape(); moonMask.graphics.beginFill(0); moonMask.graphics.drawCircle(0, 0, radius); this.addChild(moonMask); this.mask = moonMask;

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bitmaps

252

Observe que, como MoonSphere um objeto de exibio (ele baseado na classe Sprite), a mscara pode ser aplicada diretamente ocorrncia de MoonSphere usando sua propriedade mask herdada.

Ocultar simplesmente partes da foto utilizando uma mscara em forma de crculo no suficiente para criar um efeito de esfera giratria realista. Devido forma como a foto da superfcie da lua foi tirada, suas dimenses no so proporcionais; as partes da imagem que esto mais prximas parte superior ou inferior da imagem so mais distorcidas e expandidas em comparao com as partes na linha do equador. Para distorcer a aparncia da foto da lua e torn-la tridimensional, usaremos um filtro de mapa de deslocamento. Um filtro de mapa de deslocamento um tipo de filtro utilizado para distorcer uma imagem. Nesse caso, a foto da lua ser "distorcida" para torn-la mais realista, comprimindo a parte superior e inferior da imagem horizontalmente, enquanto deixa o meio inalterado. Considerando que o filtro funciona em uma parte em formato de quadrado da foto, comprimir a parte superior e a inferior, mas no o meio, transformar o quadrado em um crculo. Um efeito colateral da animao dessa imagem distorcida que o meio da imagem parece mover-se para mais longe em distncia real de pixels do que as reas prximas parte superior e inferior, o que cria a iluso de que o crculo realmente um objeto tridimensional (uma esfera). O cdigo a seguir usado para criar o filtro do mapa de deslocamento chamado displaceFilter:
var displaceFilter:DisplacementMapFilter; displaceFilter = new DisplacementMapFilter(fisheyeLens, new Point(radius, 0), BitmapDataChannel.RED, BitmapDataChannel.GREEN, radius, 0);

Esse primeiro parmetro, fisheyeLens, conhecido como a imagem de mapa; nesse caso, um objeto BitmapData que criado de modo programtico. A criao daquela imagem descrita na seo Criao de uma imagem de bitmap pela definio de valores de pixel na pgina 253. Os outros parmetros descrevem a posio na imagem filtrada na qual o filtro deve ser aplicado, os canais de cor que sero utilizados para controlar o efeito do deslocamento e at qual extenso eles afetaro o deslocamento. Depois que o filtro de mapa de deslocamento criado, ele aplicado a sphere, ainda dentro do mtodo imageLoadComplete():
sphere.filters = [displaceFilter];

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bitmaps

253

A imagem final, com a mscara e o filtro de mapa de deslocamento aplicados, se parece com:

Com cada ciclo de animao da lua giratria, o contedo de BitmapData da esfera sobregravado por um novo snapshot dos dados da imagem de origem. Contudo, o filtro no precisa ser reaplicado sempre. Isso porque o filtro aplicado ocorrncia de Bitmap (o objeto de exibio) em vez de aos dados do bitmap (as informaes em pixels no processadas). Lembre-se, a ocorrncia do Bitmap no so os dados reais de bitmap; ela uma objeto de exibio que mostra os dados de bitmap na tela. Para usar uma analogia, uma ocorrncia de Bitmap como o projeto de slides que usado para exibir slides fotogrficos em uma tela; um objeto BitmapData como o slide de fotografia real que pode ser apresentando por de um projetor de slide. Um filtro pode ser aplicado diretamente a um objeto BitmapData, que seria comparvel a desenhar diretamente no slide fotogrfico para alterar a imagem. Um filtro tambm pode ser aplicado a qualquer objeto de exibio, inclusive uma ocorrncia de Bitmap; isso seria como colocar um filtro na frente das lentes do projetor de slides para distorcer a sada mostrada na tela (sem alterar o slide original). Como os dados de bitmap no processados esto acessveis por meio da propriedade bitmapData da ocorrncia de Bitmap, o filtro pode ter sido aplicado diretamente nos dados de bitmap no processados. Entretanto, nesse caso, faz sentido aplicar o filtro ao objeto de exibio Bitmap em vez dos dados de bitmap. Para obter informaes detalhadas sobre o uso de filtro de mapas de deslocamento no ActionScript, consulte Filtro de objetos de exibio na pgina 259.

Criao de uma imagem de bitmap pela definio de valores de pixel

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Um importante aspecto de um filtro de mapa de deslocamento que ele realmente envolve duas imagens. Uma imagem, a imagem de origem, a imagem que ser realmente alterada pelo filtro. Nessa amostra, a imagem de origem a ocorrncia de Bitmap chamada sphere. A outra imagem usada pelo filtro conhecida como a imagem de mapa. A imagem do mapa no realmente exibida na ela. Em vez disso, a cor de cada um de seus pixels usada como uma entrada para a funo de deslocamento a cor do pixel em uma determinada coordenada x, y na imagem de mapa determina quanto de deslocamento (deslocamento fsico na posio) aplicado ao pixel naquelas coordenadas x, y na imagem de origem.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bitmaps

254

Conseqentemente, para usar o filtro de mapa de deslocamento para criar um efeito de esfera, a amostra precisa de imagem de mapa apropriada aquela que tem um plano de fundo cinza e um crculo que preenchido com um gradiente de uma nica cor (vermelho) indo horizontalmente de escuro para claro, como mostrado aqui:

Como somente uma imagem e um filtro de mapa so utilizados nesta amostra, a imagem do mapa criada apenas uma vez, no mtodo imageLoadComplete() (em outras palavras, quando a imagem externa acabar de ser carregada. A imagem do mapa, chamada fisheyeLens, criada chamando o mtodo createFisheyeMap() da classe MoonSphere:
var fisheyeLens:BitmapData = createFisheyeMap(radius);

Dentro do mtodo createFisheyeMap(), a imagem de mapa desenhada um pixel por vez utilizando o mtodo setPixel() da classe BitmapData. O cdigo completo para o mtodo createFisheyeMap() listado aqui, seguido por uma discusso etapa por etapa de como ele funciona:
private function createFisheyeMap(radius:int):BitmapData { var diameter:int = 2 * radius; var result:BitmapData = new BitmapData(diameter, diameter, false, 0x808080); // Loop through the pixels in the image one by one for (var i:int = 0; i < diameter; i++) { for (var j:int = 0; j < diameter; j++) { // Calculate the x and y distances of this pixel from // the center of the circle (as a percentage of the radius). var pctX:Number = (i - radius) / radius; var pctY:Number = (j - radius) / radius; // Calculate the linear distance of this pixel from // the center of the circle (as a percentage of the radius). var pctDistance:Number = Math.sqrt(pctX * pctX + pctY * pctY); // If the current pixel is inside the circle,

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bitmaps

255

// set its color. if (pctDistance < 1) { // Calculate the appropriate color depending on the // distance of this pixel from the center of the circle. var red:int; var green:int; var blue:int; var rgb:uint; red = 128 * (1 + 0.75 * pctX * pctX * pctX / (1 - pctY * pctY)); green = 0; blue = 0; rgb = (red << 16 | green << 8 | blue); // Set the pixel to the calculated color. result.setPixel(i, j, rgb); } } } return result; }

Primeiro, quando o mtodo chamado, ele recebe um parmetro, radius, indicando o raio da imagem em forma de crculo a ser criado. Em seguida, o cdigo cria o objeto BitmapData no qual o crculo ser desenhado. Aquele objeto, chamado result, por fim transmitido de volta como o valor de retorno do mtodo. Como mostrado no snippet de cdigo a seguir, a ocorrncia de BitmapData de result criada com a largura e a altura to grandes quando o dimetro do crculo, sem transparncia (false para o terceiro parmetro), e preenchida com a cor 0x808080 (cinza mdio):
var result:BitmapData = new BitmapData(diameter, diameter, false, 0x808080);

Em seguida, o cdigo usa loops para iterar cada pixel da imagem. O loop externo engloba cada coluna da imagem da esquerda para a direita (utilizando a varivel i para representar a posio horizontal do pixel atualmente sendo manipulado), enquanto o loop interno engloba cada pixel da coluna atual de cima para baixo (com a varivel j representando a posio vertical de pixels atual). O cdigo para os loops (com o contedo do loop interno omitido) mostrado aqui:
for (var i:int = 0; i < diameter; i++) { for (var j:int = 0; j < diameter; j++) { ... } }

medida que o loop engloba os pixels um a um, em cada pixel um valor (o valor de cor daquele pixel na imagem de mapa) calculado. Esse processo envolve quatro etapas:
1 O cdigo calcula a distncia do pixel atual do centro do crculo ao longo do eixo x (i - radius). Esse valor

dividido pelo raio para torn-lo um percentual de raio em vez de uma distncia absoluta ((i - radius) /
radius). Esse valor de percentual armazenado em uma varivel chamada pctX, e o valor equivalente para o eixo

y calculado e armazenado na varivel pctY, como mostra este cdigo:

var pctX:Number = (i - radius) / radius; var pctY:Number = (j - radius) / radius;

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bitmaps

256

2 Usando uma frmula trigonomtrica padro, o Teorema de Pitgoras, a distncia linear entre o cento do crculo e

o ponto atual calculado de pctX e pctY. Esse valor armazenado em uma varivel chamada pctDistance, como mostrado aqui:
var pctDistance:Number = Math.sqrt(pctX * pctX + pctY * pctY);

3 Em seguida, o cdigo verifica se o percentual de distncia menor do que 1 (significando 100% do raio, ou em

outras palavras, se o pixel sendo considerado est dentro do raio do crculo). Se o pixel estiver dentro do crculo, ele recebe um valor de cor calculado (omitido aqui, mas descrito na etapa 4); em caso negativo, nada mais acontece com aquele pixel; sua cor deixada como o padro de cinza mdio:
if (pctDistance < 1) { ... }

4 Para aqueles pixels que estiverem dentro do crculo, um valor de cor calculado para o pixel. A cor final ser uma

sombra de vermelho variando de preto (0% de vermelho) na borda esquerda do crculo at vermelho vivo (100%) na borda direita do crculo. O valor da cor inicialmente calculado em trs partes (vermelho, verde e azul), como mostrado aqui:BitmapData
red = 128 * (1 + 0.75 * pctX * pctX * pctX / (1 - pctY * pctY)); green = 0; blue = 0;

Observe que apenas a parte vermelha da cor (a varivel red) tem realmente um valor. Os valores de verde e azul (as variveis green e blue) so mostrados aqui para fins de explicao, mas podem ser omitidos. Como o propsito desse mtodo criar um crculo que contenha um gradiente vermelho, nenhum valor de verde ou azul necessrio. Depois que os trs valores de cores individuais estiverem determinados, eles sero combinados em um nico valor de cor inteiro utilizando um algoritmo de deslocamento de bits padro, mostrado neste cdigo:
rgb = (red << 16 | green << 8 | blue);

Finalmente, com o valor de cor calculado, aquele valor atribudo ao pixel atual utilizando o mtodo setPixel() do objeto result BitmapData, mostrado aqui:
result.setPixel(i, j, rgb);

Decodificao assncrona de imagens de bitmap

Flash Player 10.2 e posterior, Adobe AIR 2.6 e posterior Quando voc trabalha com imagens de bitmap, pode decodificar e carregar assincronamente as imagens de bitmap a fim de aprimorar o desempenho percebido de seu aplicativo. A decodificao assncrona de uma imagem de bitmap, em muitos casos pode durar o mesmo tempo que a decodificao sncrona da imagem. No entanto, a imagem de bitmap decodificada em um encadeamento separado antes que o objeto Loader associado envie o evento COMPLETE. Assim, possvel decodificar assincronamente imagens maiores depois de carreg-las. A classe ImageDecodingPolicy no pacote flash.system permite especificar o esquema de carregamento de bitmap. O esquema de carregamento padro sncrono.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bitmaps

257

Poltica de decodificao de bitmap

Esquema de carregamento de bitmap Sncrono

Descrio

ImageDecodingPolicy.ON_DEMAND

As imagens carregadas so decodificadas quando os dados da imagem so acessados. Use esta poltica para decodificar imagens menores. Voc tambm pode usar esta poltica quando seu aplicativo no depender de efeitos e transies complexas.

ImageDecodingPolicy.ON_LOAD

Assncrono

As imagens carregadas so decodificadas no carregamento, antes que o evento COMPLETE seja despachado. Ideal para imagens maiores (maiores que 10 MP). Quando estiver desenvolvendo aplicativos mveis baseados no AIR com transies de pgina, use esta poltica de carregamento de bitmap para aumentar o desempenho percebido de seu aplicativo.

Nota: Se o arquivo carregado for uma imagem de bitmap e a poltica de decodificao usada for ON_LOAD, a imagem ser decodificada de modo assncrono antes de o evento COMPLETEser despachado. O cdigo a seguir mostra o uso da classe ImageDecodingPolicy:
var loaderContext:LoaderContext = new LoaderContext(); loaderContext.imageDecodingPolicy = ImageDecodingPolicy.ON_LOAD var loader:Loader = new Loader(); loader.load(new URLRequest("http://www.adobe.com/myimage.png"), loaderContext);

Voc ainda pode usar a decodificao ON_DEMAND com os mtodos Loader.load() e Loader.loadBytes(). No entanto, todos os outros mtodos que obtm um objeto LoaderContext como argumento ignoram qualquer valor de ImageDecodingPolicy passado. O exemplo a seguir mostra a diferena entre a decodificao sncrona e assncrona de uma imagem de bitmap:
package { import import import import import import

flash.display.Loader; flash.display.Sprite; flash.events.Event; flash.net.URLRequest; flash.system.ImageDecodingPolicy; flash.system.LoaderContext;

public class AsyncTest extends Sprite { private var loaderContext:LoaderContext; private var loader:Loader; private var urlRequest:URLRequest; public function AsyncTest() { //Load the image synchronously loaderContext = new LoaderContext(); //Default behavior. loaderContext.imageDecodingPolicy = ImageDecodingPolicy.ON_DEMAND; loader = new Loader();

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bitmaps

258

loadImageSync(); //Load the image asynchronously loaderContext = new LoaderContext(); loaderContext.imageDecodingPolicy = ImageDecodingPolicy.ON_LOAD; loader = new Loader(); loadImageASync(); } private function loadImageASync():void{ trace("Loading image asynchronously..."); urlRequest = new URLRequest("http://www.adobe.com/myimage.png"); urlRequest.useCache = false; loader.load(urlRequest, loaderContext); loader.contentLoaderInfo.addEventListener (Event.COMPLETE, onAsyncLoadComplete); } private function onAsyncLoadComplete(event:Event):void{ trace("Async. Image Load Complete"); } private function loadImageSync():void{ trace("Loading image synchronously..."); urlRequest = new URLRequest("http://www.adobe.com/myimage.png"); urlRequest.useCache = false; loader.load(urlRequest, loaderContext); loader.contentLoaderInfo.addEventListener (Event.COMPLETE, onSyncLoadComplete); } private function onSyncLoadComplete(event:Event):void{ trace("Sync. Image Load Complete"); } } }

ltima atualizao em 29/3/2011

259

Captulo 13: Filtro de objetos de exibio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Historicamente, o aplicativo de efeitos de filtro s imagens de bitmap so o domnio dos softwares especializados de edio de imagem, como o Adobe Photoshop e o Adobe Fireworks. O ActionScript 3.0 inclui o pacote flash.filters, que contm uma srie de classes de filtro de efeito de bitmap. Esses efeitos permitem que os desenvolvedores apliquem filtros, em termos programticos, aos bitmaps e exibam objetos e com isso obtenham muitos dos mesmos efeitos que esto disponveis nos aplicativos de manipulao grfica.

Noes bsicas sobre filtragem de objetos de exibio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Uma das formas de acrescentar polons a um aplicativo acrescentar efeitos grficos simples. Voc pode acrescentar um efeito de sombra por trs de uma foto para criar a iluso de 3D, ou um brilho ao redor de um boto para mostrar que ele est ativo. O ActionScript 3.0 inclui dez filtros que podem ser aplicados em qualquer objeto de exibio ou em uma ocorrncia de BitmapData. Os filtros incorporados variam do bsico, como filtros de sombra e brilho, ao complexo, como o filtro de mapa de mesclagem e o filtro de convoluo. Nota: Alm dos filtros incorporados, voc tambm pode programar filtros e efeitos personalizados usando o Pixel Bender. Consulte Trabalho com sombreadores Pixel Bender na pgina 293. Conceitos e termos importantes A lista de referncia a seguir contm termos importantes que voc pode encontrar ao criar filtros:
Bisel Uma borda criada por pixels de iluminao nos dois lados e pixels de escurecimento nos dois lados opostos. Esse

efeito cria a aparncia de uma borda tridimensional. O efeito geralmente utilizado para botes erguidos ou recuados e imagens grficas semelhantes.
Convoluo Distoro de pixels em uma imagem por meio da combinao do valor de cada pixel com os valores de

alguns ou todos os pixels ao redor, usando diversas propores.

Deslocamento Mudana ou movimentao de pixels em uma imagem para uma nova posio. Matriz Uma grade de nmeros usada para realizar alguns clculos matemticos aplicando os nmeros da grade em diversos valores e combinando os resultados.

Mais tpicos da Ajuda

Pacote flash.filters flash.display.DisplayObject.filters flash.display.BitmapData.applyFilter()

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

260

Criao e aplicao de filtros

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os filtros permitem aplicar diversos efeitos em objetos de exibio e bitmap, variando desde sombras projetadas at bisis e desfoques. Cada filtro definido como uma classe, de modo que a aplicao de filtros envolve a criao de ocorrncias de objetos de filtro, o que equivale a criar qualquer outro objeto. Depois de criar uma ocorrncia de um objeto de filtro, possvel aplic-la com facilidade em um objeto de exibio usando a propriedade filters do objeto ou, no caso de um objeto BitmapData, usando o mtodo applyFilter().

Criao de um filtro
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para criar um objeto de filtro, basta chamar o mtodo de construtor da classe de filtro selecionada. Por exemplo, para criar um objeto DropShadowFilter, use o seguinte cdigo:
import flash.filters.DropShadowFilter; var myFilter:DropShadowFilter = new DropShadowFilter();

Embora no seja mostrado aqui, o construtor DropShadowFilter() (como todos os construtores de classes de filtro) aceita vrios parmetros opcionais que podem ser usados para personalizar a aparncia do efeito do filtro.

Aplicao de um filtro
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Depois de criar um objeto de filtro, voc pode aplic-lo em um objeto de exibio ou em um objeto BitmapData; o modo de aplicao do filtro depende do objeto no qual ele ser aplicado. Aplicao de um filtro em um objeto de exibio Use a propriedade filters para aplicar efeitos de filtro em um objeto de exibio. A propriedade filters de um objeto de exibio uma ocorrncia de Array, cujos elementos so objetos de filtro aplicados no objeto de exibio. Para aplicar um nico filtro em um objeto de exibio, crie a ocorrncia de filtro, adicione-a a uma ocorrncia de Array e atribua esse objeto Array propriedade filters do objeto de exibio:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

261

import flash.display.Bitmap; import flash.display.BitmapData; import flash.filters.DropShadowFilter; // Create a bitmapData object and render it to screen var myBitmapData:BitmapData = new BitmapData(100,100,false,0xFFFF3300); var myDisplayObject:Bitmap = new Bitmap(myBitmapData); addChild(myDisplayObject); // Create a DropShadowFilter instance. var dropShadow:DropShadowFilter = new DropShadowFilter(); // Create the filters array, adding the filter to the array by passing it as // a parameter to the Array() constructor. var filtersArray:Array = new Array(dropShadow); // Assign the filters array to the display object to apply the filter. myDisplayObject.filters = filtersArray;

Se desejar atribuir vrios filtros ao objeto, basta adicionar todos os filtros ocorrncia de Array antes de atribu-la propriedade filters. Para adicionar vrios objetos a uma matriz, transmita-os como parmetros para o construtor. Por exemplo, esse cdigo aplica um filtro de bisel e um filtro de brilho ao objeto de exibio criado anteriormente:
import flash.filters.BevelFilter; import flash.filters.GlowFilter; // Create the filters and add them to an array. var bevel:BevelFilter = new BevelFilter(); var glow:GlowFilter = new GlowFilter(); var filtersArray:Array = new Array(bevel, glow); // Assign the filters array to the display object to apply the filter. myDisplayObject.filters = filtersArray;

Ao criar a matriz que contm os filtros, voc pode usar o construtor new Array() (conforme mostrado nos exemplos anteriores) ou a sintaxe do literal de matriz, colocando os filtros entre colchetes ([]). Por exemplo, esta linha de cdigo:
var filters:Array = new Array(dropShadow, blur);

faz a mesma coisa que esta linha de cdigo:

var filters:Array = [dropShadow, blur];

Se vrios filtros forem aplicados em objetos de exibio, a aplicao ser feita de modo cumulativo e seqencial. Por exemplo, se uma matriz de filtros tiver dois elementos, um filtro de bisel adicionado primeiro e um filtro de sombra projetada adicionado depois, o filtro de sombra projetada ser aplicado no filtro de bisel e no objeto de exibio. Isso ocorre devido posio do filtro de sombra projetada em segundo lugar na matriz de filtros. Se desejar aplicar filtros de modo no cumulativo, voc deve aplicar cada filtro em uma nova cpia do objeto de exibio. Se estiver atribuindo apenas um ou alguns filtros a um objeto de exibio, crie a ocorrncia do filtro e atribua-a ao objeto em uma nica instruo. Por exemplo, a linha de cdigo a seguir aplica um filtro de desfoque em um objeto de exibio chamado myDisplayObject:
myDisplayObject.filters = [new BlurFilter()];

O cdigo anterior cria uma ocorrncia de Array usando a sintaxe do literal de matriz (entre colchetes), cria uma ocorrncia de BlurFilter como um elemento da matriz e atribui a essa matriz a propriedade filters do objeto de exibio chamado myDisplayObject.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

262

Remoo de filtros de um objeto de exibio A remoo de todos os filtros de um objeto de exibio to simples quanto atribuir um valor nulo propriedade filters:
myDisplayObject.filters = null;

Se tiver aplicado vrios filtros em um objeto e desejar remover apenas um dos filtros, realize as etapas para alterar a matriz da propriedade filters. Para obter mais informaes, consulte Possveis problemas resultantes do trabalho com filtros na pgina 262. Aplicao de um filtro em um objeto BitmapData A aplicao de um filtro em um objeto BitmapData requer o uso do mtodo applyFilter() do objeto BitmapData:
var rect:Rectangle = new Rectangle(); var origin:Point = new Point(); myBitmapData.applyFilter(sourceBitmapData, rect, origin, new BlurFilter());

O mtodo applyFilter() aplica um filtro em um objeto BitmapData de origem, produzindo uma nova imagem filtrada. Esse mtodo no modifica a imagem de origem inicial; em vez disso, o resultado da aplicao do filtro na imagem de origem armazenado na ocorrncia de BitmapData na qual o mtodo applyFilter() chamado.

Como funcionam os filtros

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A filtragem de objetos de exibio funciona armazenando uma cpia do objeto original em cache como um bitmap transparente. Assim que um filtro aplicado em um objeto de exibio, o tempo de execuo armazena o objeto em cache como um bitmap enquanto o objeto tiver uma lista de filtros vlida. O bitmap de origem usado como imagem original para todos os efeitos de filtro aplicados posteriormente. Cada objeto de exibio geralmente contm dois bitmaps: um com o objeto original de exibio de origem e outro para a imagem final, aps a filtragem. A imagem final usada no momento da renderizao. Desde que o objeto de exibio no seja alterado, a imagem final no precisa de atualizao.

Possveis problemas resultantes do trabalho com filtros

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Existem vrias fontes de possveis problemas que devem ser consideradas ao trabalhar com filtros. Cache de bitmaps e filtros Para aplicar um filtro em um objeto de exibio, o cache de bitmaps deve ser ativado para esse objeto. Quando voc aplica um filtro a um objeto de exibio cuja propriedade cacheAsBitmap est definida como false, a propriedade cacheAsBitmap do objeto automaticamente definida como true. Se mais tarde voc remover todos os filtros do objeto de exibio, a propriedade cacheAsBitmap definida para o ltimo valor em que estava.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

263

Alterao de filtros em tempo de execuo Se um objeto de exibio j tiver um ou mais filtros aplicados, no ser possvel alterar o conjunto de filtros adicionando mais filtros ou removendo filtros da matriz da propriedade filters. Em vez disso, para adicionar ou alterar o conjunto de filtros aplicados, faa as alteraes em uma matriz separada e, em seguida, atribua essa matriz propriedade filters do objeto de exibio para que os filters sejam aplicados no objeto. A maneira mais simples de fazer isso ler a matriz da propriedade filters em uma varivel Array e fazer as modificaes nessa matriz temporria. Depois, atribua essa matriz novamente propriedade filters do objeto de exibio. Em casos mais complexos, talvez seja necessrio manter uma matriz de filtros principal separada. Faa as alteraes nessa matriz de filtros principal e atribua-a novamente propriedade filters do objeto de exibio depois de cada alterao. Adio de mais um filtro O cdigo a seguir demonstra o processo de adio de mais um filtro a um objeto de exibio que j tem um ou mais filtros aplicados. Inicialmente, um filtro de brilho aplicado no objeto de exibio chamado myDisplayObject; posteriormente, quando o objeto de exibio clicado, a funo addFilters() chamada. Nesta funo, dois filtros adicionais so aplicados em myDisplayObject:
import flash.events.MouseEvent; import flash.filters.*; myDisplayObject.filters = [new GlowFilter()]; function addFilters(event:MouseEvent):void { // Make a copy of the filters array. var filtersCopy:Array = myDisplayObject.filters; // Make desired changes to the filters (in this case, adding filters). filtersCopy.push(new BlurFilter()); filtersCopy.push(new DropShadowFilter()); // Apply the changes by reassigning the array to the filters property. myDisplayObject.filters = filtersCopy; } myDisplayObject.addEventListener(MouseEvent.CLICK, addFilters);

Remoo de um filtro do conjunto de filtros Se um objeto de exibio tiver vrios filtros aplicados e voc desejar remover um dos filtros enquanto os outros continuam a ser aplicados no objeto, copie os filtros em uma matriz separada, remova o filtro indesejado dessa matriz e atribua a matriz temporria novamente propriedade filters do objeto de exibio. Vrias maneiras de remover um ou mais elementos de qualquer matriz esto descritas em Recuperao de valores e remoo de elementos de matriz na pgina 32. O mais fcil remover o filtro de nvel superior do objeto (o ltimo filtro aplicado no objeto). Use o mtodo pop() da classe Array para remover o filtro da matriz:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

264

// Example of removing the top-most filter from a display object // named "filteredObject". var tempFilters:Array = filteredObject.filters; // Remove the last element from the Array (the top-most filter). tempFilters.pop(); // Apply the new set of filters to the display object. filteredObject.filters = tempFilters;

Similarmente, para remover o filtro de nvel inferior (o primeiro aplicado no objeto), use o mesmo cdigo, usando o mtodo shift() da matriz Array em vez do mtodo pop(). Para remover um filtro do meio de uma matriz de filtros (supondo que a matriz tem mais de dois filtros), use o mtodo splice(). Voc deve saber o ndice (a posio na matriz) do filtro que deseja remover. Por exemplo, o cdigo a seguir remove o segundo filtro (no ndice 1) de um objeto de exibio:
// Example of removing a filter from the middle of a stack of filters // applied to a display object named "filteredObject". var tempFilters:Array = filteredObject.filters; // Remove the second filter from the array. It's the item at index 1 // because Array indexes start from 0. // The first "1" indicates the index of the filter to remove; the // second "1" indicates how many elements to remove. tempFilters.splice(1, 1); // Apply the new set of filters to the display object. filteredObject.filters = tempFilters;

Determinao do ndice de um filtro Voc precisa saber qual filtro deve ser removido da matriz para determinar o ndice do filtro. Voc deve saber (em virtude da designao do aplicativo) ou calcular o ndice do filtro a ser removido. A melhor maneira designar o aplicativo de modo que o filtro a ser removido sempre fique na mesma posio no conjunto de filtros. Por exemplo, se houver apenas um objeto de exibio com um filtro de convoluo e um filtro de sombra projetada aplicados (nessa ordem) e voc desejar remover o filtro de sombra projetada, mas manter o outro, o filtro estar em uma posio conhecida (o filtro de nvel superior) para que voc saiba com antecedncia qual mtodo Array deve ser usado (neste caso, Array.pop() para remover o filtro de sombra projetada). Se o filtro que deseja remover for sempre do mesmo tipo, mas no estiver necessariamente na mesma posio do conjunto de filtros todas as vezes, verifique o tipo de dados de cada filtro da matriz para determinar qual deve ser removido. Por exemplo, o cdigo a seguir determina qual o filtro de brilho em um conjunto de filtros e remove esse filtro do conjunto.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

265

// Example of removing a glow filter from a set of filters, where the //filter you want to remove is the only GlowFilter instance applied // to the filtered object. var tempFilters:Array = filteredObject.filters; // Loop through the filters to find the index of the GlowFilter instance. var glowIndex:int; var numFilters:int = tempFilters.length; for (var i:int = 0; i < numFilters; i++) { if (tempFilters[i] is GlowFilter) { glowIndex = i; break; } } // Remove the glow filter from the array. tempFilters.splice(glowIndex, 1); // Apply the new set of filters to the display object. filteredObject.filters = tempFilters;

Em um caso mais complexo, como se o filtro a ser removido for selecionado em tempo de execuo, o melhor manter uma cpia separada permanente da matriz de filtros que serve como a lista principal de filtros. Sempre que voc alterar o conjunto de filtros, altere a lista principal e aplique essa matriz de filtros como a propriedade filters do objeto de exibio. Por exemplo, na listagem de cdigo a seguir, vrios filtros de convoluo so aplicados em um objeto de exibio para criar efeitos visuais diferentes e, posteriormente, um desses filtros removido enquanto os outros so mantidos. Neste caso, o cdigo mantm uma cpia principal da matriz de filtros, bem como uma referncia ao filtro a ser removido. Localizar e remover o filtro especfico similar abordagem anterior, mas, em vez de criar uma cpia temporria da matriz de filtros, a cpia principal manipulada e aplicada no objeto de exibio.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

266

// // // //

Example of removing a filter from a set of filters, where there may be more than one of that type of filter applied to the filtered object, and you only want to remove one.

// A master list of filters is stored in a separate, // persistent Array variable. var masterFilterList:Array; // At some point, you store a reference to the filter you // want to remove. var filterToRemove:ConvolutionFilter; // ... assume the filters have been added to masterFilterList, // which is then assigned as the filteredObject.filters: filteredObject.filters = masterFilterList; // ... later, when it's time to remove the filter, this code gets called: // Loop through the filters to find the index of masterFilterList. var removeIndex:int = -1; var numFilters:int = masterFilterList.length; for (var i:int = 0; i < numFilters; i++) { if (masterFilterList[i] == filterToRemove) { removeIndex = i; break; } } if (removeIndex >= 0) { // Remove the filter from the array. masterFilterList.splice(removeIndex, 1); // Apply the new set of filters to the display object. filteredObject.filters = masterFilterList; }

Nesta abordagem (quando estiver comparando uma referncia de filtro armazenada com os itens da matriz de filtros para determinar qual filtro deve ser removido), voc deve manter uma cpia separada da matriz de filtros - o cdigo no funcionar se a referncia de filtro armazenada for comparada com os elementos de uma matriz temporria copiada da propriedade filters do objeto de exibio. Isso ocorre porque internamente, quando uma matriz atribuda propriedade filters, o tempo de execuo faz uma cpia de cada objeto de filtro na matriz. Essas cpias (no os objetos originais) so aplicadas no objeto de exibio e, quando a propriedade filters lida em uma matriz temporria, a matriz temporria contm referncias aos objetos de filtro copiados, em vez de referncias aos objetos de filtro originais. Conseqentemente, se no exemplo anterior voc tentar determinar o ndice de filterToRemove comparando-o com os filtros de uma matriz temporria, nenhuma correspondncia ser encontrada.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

267

Transformaes de objeto e filtros Nenhuma regio filtrada (uma sombra projetada, por exemplo) fora do retngulo delimitador do objeto de exibio considerada como parte da superfcie para fins de deteco de ocorrncias (determinar se uma ocorrncia se sobrepe ou faz interseo com outra). Como os mtodos de deteco de ocorrncias da classe DisplayObject so baseados em vetores, no possvel detectar ocorrncias no resultado de bitmap. Por exemplo, se um filtro de bisel for aplicado em uma ocorrncia de boto, a deteco de ocorrncias no estar disponvel na parte do bisel da ocorrncia. Os filtros no permitem dimensionar, girar e inclinar objetos; se o objeto de exibio filtrado for dimensionado (se scaleX e scaleY no forem 100%), o efeito de filtro no ser dimensionado com a ocorrncia. Isso significa que a forma original da ocorrncia girada, dimensionada ou inclinada; no entanto, o filtro no girado, dimensionado ou inclinado com a ocorrncia. Voc pode animar uma ocorrncia com um filtro para criar efeitos realistas ou aninhar ocorrncias e usar a classe BitmapData para animar os filtros e atingir esse efeito. Objetos de bitmap e filtros Quando algum filtro aplicado em um objeto BitmapData, a propriedade cacheAsBitmap definida automaticamente como true. Desse modo, o filtro realmente aplicado na cpia do objeto, no no original. Em seguida, essa cpia colocada na exibio principal (no objeto original) o mais perto possvel do pixel mais prximo. Se os limites do bitmap original forem alterados, o bitmap de cpia filtrado ser recriado a partir do original, em vez de ser esticado ou distorcido. Se voc apagar todos os filtros de um objeto de exibio, a propriedade cacheAsBitmap ser redefinida como o valor original antes do filtro ser aplicado.

Filtros de exibio disponveis

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O ActionScript 3.0 inclui dez classes de filtro que podem ser aplicadas em objetos de exibio e em objetos BitmapData:

Filtro de bisel (classe BevelFilter) Filtro de desfoque (classe BlurFilter) Filtro de sombra projetada (classe DropShadowFilter) Filtro de brilho (classe GlowFilter) Filtro de bisel de gradiente (classe GradientBevelFilter) Filtro de brilho de gradiente (classe GradientGlowFilter) Filtro de matriz de cor (classe ColorMatrixFilter) Filtro de convoluo (classe ConvolutionFilter) Filtro de mapa de deslocamento (classe DisplacementMapFilter) Filtro de sombreador (classe ShaderFilter)
Os seis primeiros filtros so simples e podem ser usados para criar um efeito especfico, com alguns recursos de personalizao disponveis. Esses seis filtros podem ser aplicados usando o ActionScript e tambm a objetos no Flash Professional usando o painel Filtros. Consequentemente, mesmo que os filtros sejam aplicados com ActionScript, se voc tiver o Flash Professional, poder usar a interface visual para experimentar rapidamente filtros e configuraes diferentes para saber como criar o efeito desejado.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

268

Os quatro ltimos filtros esto disponveis somente no ActionScript. Esses filtros (matriz de cor, convoluo, mapa de deslocamento e sombreador) so muito mais flexveis nos tipos de efeitos que podem criar. Em vez de serem otimizados para um nico efeito, eles fornecem poder e flexibilidade. Por exemplo, selecionando valores diferentes para sua matriz, o filtro de convoluo pode ser usado para criar efeitos como desfoque, entalhe, nitidez, localizao de bordas de cor, transformaes e muito mais. Cada filtro, simples ou complexo, pode ser personalizado com suas propriedades. Geralmente, existem duas opes para configurar propriedades de filtro. Todos os filtros permitem definir as propriedades por meio da transmisso de valores de parmetro ao construtor do objeto de filtro. Se preferir, independentemente de configurar as propriedades de filtro transmitindo parmetros, voc pode ajustar os filtros posteriormente definindo valores para as propriedades do objeto de filtro. A maioria das listagens de cdigo de exemplo define as propriedades diretamente para facilitar o acompanhamento do exemplo. Entretanto, voc normalmente atinge o mesmo resultado em menos linhas de cdigo passando os valores como parmetros no construtor de objeto de filtro. Para obter mais detalhes sobre os princpios de cada filtro, suas propriedades e seus parmetros de construo, consulte Referncia do ActionScript 3.0 para a plataforma Adobe Flash.

Filtro de bisel
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe BevelFilter permite a adio de uma borda 3D chanfrada ao objeto filtrado. Esse filtro deixa os cantos ou bordas pontudos do objeto talhados ou chanfrados. As propriedades da classe BevelFilter permitem personalizar a aparncia do bisel. possvel definir cores de realce e sombra, desfoques de borda chanfrada, ngulos de bisel e colocao da borda chanfrada; voc pode inclusive criar um efeito vazado. O exemplo a seguir carrega uma imagem externa e aplica um filtro de bisel nela.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

269

import import import import import

flash.display.*; flash.filters.BevelFilter; flash.filters.BitmapFilterQuality; flash.filters.BitmapFilterType; flash.net.URLRequest;

// Load an image onto the Stage. var imageLoader:Loader = new Loader(); var url:String = "http://www.helpexamples.com/flash/images/image3.jpg"; var urlReq:URLRequest = new URLRequest(url); imageLoader.load(urlReq); addChild(imageLoader); // Create the bevel filter and set filter properties. var bevel:BevelFilter = new BevelFilter(); bevel.distance = 5; bevel.angle = 45; bevel.highlightColor = 0xFFFF00; bevel.highlightAlpha = 0.8; bevel.shadowColor = 0x666666; bevel.shadowAlpha = 0.8; bevel.blurX = 5; bevel.blurY = 5; bevel.strength = 5; bevel.quality = BitmapFilterQuality.HIGH; bevel.type = BitmapFilterType.INNER; bevel.knockout = false; // Apply filter to the image. imageLoader.filters = [bevel];

Filtro de desfoque
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe BlurFilter mancha ou desfoca objetos de exibio e seu respectivo contedo. Os efeitos de desfoque so teis para dar a impresso de que um objeto est fora de foco ou para simular um deslocamento rpido, como em um desfoque de movimento. Defina a propriedade quality do filtro de desfoque como muito baixa para simular um efeito de lente ligeiramente fora do foco. Definir a propriedade quality como alta resulta em um efeito de desfoque suave similar a um desfoque de Gauss. O exemplo a seguir cria um objeto circular usando o mtodo drawCircle() da classe Graphics e aplica um filtro de desfoque nele:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

270

import flash.display.Sprite; import flash.filters.BitmapFilterQuality; import flash.filters.BlurFilter; // Draw a circle. var redDotCutout:Sprite = new Sprite(); redDotCutout.graphics.lineStyle(); redDotCutout.graphics.beginFill(0xFF0000); redDotCutout.graphics.drawCircle(145, 90, 25); redDotCutout.graphics.endFill(); // Add the circle to the display list. addChild(redDotCutout); // Apply the blur filter to the rectangle. var blur:BlurFilter = new BlurFilter(); blur.blurX = 10; blur.blurY = 10; blur.quality = BitmapFilterQuality.MEDIUM; redDotCutout.filters = [blur];

Filtro de sombra projetada

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior As sombras projetadas do a impresso de que existe uma fonte de luz separada situada acima do objeto de destino. A posio e a intensidade dessa fonte de luz podem ser modificadas para produzir diversos efeitos de sombra projetada diferentes. A classe DropShadowFilter usa um algoritmo similar ao do filtro de desfoque. A principal diferena que o filtro de sombra projetada tem mais propriedades que podem ser modificadas para simular outros atributos de fonte de luz (como alfa, cor, deslocamento e brilho). O filtro de sombra projetada tambm permite aplicar opes de transformao personalizadas no estilo da sombra projetada, incluindo a sombra interna ou externa e o modo vazado (tambm conhecido como recorte). O cdigo a seguir cria uma caixa quadrada e aplica um filtro de sombra projetada nela:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

271

import flash.display.Sprite; import flash.filters.DropShadowFilter; // Draw a box. var boxShadow:Sprite = new Sprite(); boxShadow.graphics.lineStyle(1); boxShadow.graphics.beginFill(0xFF3300); boxShadow.graphics.drawRect(0, 0, 100, 100); boxShadow.graphics.endFill(); addChild(boxShadow); // Apply the drop shadow filter to the box. var shadow:DropShadowFilter = new DropShadowFilter(); shadow.distance = 10; shadow.angle = 25; // You can also set other properties, such as the shadow color, // alpha, amount of blur, strength, quality, and options for // inner shadows and knockout effects. boxShadow.filters = [shadow];

Filtro de brilho
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe GlowFilter aplica um efeito de iluminao aos objetos de exibio, como se o objeto fosse iluminado por baixo, criando um leve brilho. Assim como o filtro de sombra projetada, o filtro de brilho inclui propriedades para modificar a distncia, o ngulo e a cor da fonte de luz para produzir efeitos variados. O GlowFilter tambm tem vrias opes para modificar o estilo do brilho, incluindo o brilho interno ou externo e o modo vazado. O cdigo a seguir cria uma transversal usando a classe Sprite e aplica um filtro de brilho nela:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

272

import flash.display.Sprite; import flash.filters.BitmapFilterQuality; import flash.filters.GlowFilter; // Create a cross graphic. var crossGraphic:Sprite = new Sprite(); crossGraphic.graphics.lineStyle(); crossGraphic.graphics.beginFill(0xCCCC00); crossGraphic.graphics.drawRect(60, 90, 100, 20); crossGraphic.graphics.drawRect(100, 50, 20, 100); crossGraphic.graphics.endFill(); addChild(crossGraphic); // Apply the glow filter to the cross shape. var glow:GlowFilter = new GlowFilter(); glow.color = 0x009922; glow.alpha = 1; glow.blurX = 25; glow.blurY = 25; glow.quality = BitmapFilterQuality.MEDIUM; crossGraphic.filters = [glow];

Filtro de bisel de gradiente

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe GradientBevelFilter permite a aplicao de um efeito de bisel aprimorado em objetos de exibio ou objetos BitmapData. Usar uma cor de gradiente no bisel melhora muito a profundidade espacial do bisel, dando s bordas uma aparncia 3D mais realista. O cdigo a seguir cria um objeto retangular usando o mtodo drawRect() da classe Shape e aplica um filtro de bisel de gradiente nele.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

273

import flash.display.Shape; import flash.filters.BitmapFilterQuality; import flash.filters.GradientBevelFilter; // Draw a rectangle. var box:Shape = new Shape(); box.graphics.lineStyle(); box.graphics.beginFill(0xFEFE78); box.graphics.drawRect(100, 50, 90, 200); box.graphics.endFill(); // Apply a gradient bevel to the rectangle. var gradientBevel:GradientBevelFilter = new GradientBevelFilter(); gradientBevel.distance = 8; gradientBevel.angle = 225; // opposite of 45 degrees gradientBevel.colors = [0xFFFFCC, 0xFEFE78, 0x8F8E01]; gradientBevel.alphas = [1, 0, 1]; gradientBevel.ratios = [0, 128, 255]; gradientBevel.blurX = 8; gradientBevel.blurY = 8; gradientBevel.quality = BitmapFilterQuality.HIGH; // Other properties let you set the filter strength and set options // for inner bevel and knockout effects. box.filters = [gradientBevel]; // Add the graphic to the display list. addChild(box);

Filtro de brilho de gradiente

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe GradientGlowFilter permite a aplicao de um efeito de brilho aprimorado em objetos de exibio ou objetos BitmapData. Os efeitos permitem que voc tenha mais controle sobre o brilho e produza um efeito mais realista. Alm disso, o filtro de brilho de gradiente permite aplicar um brilho gradiente nas bordas interna, externa ou superior de um objeto. O exemplo a seguir desenha um crculo no palco e aplica um filtro de brilho de gradiente a ele. medida que voc move o mouse mais para a direita e para baixo, a quantidade de desfoque aumenta nas direes horizontal e vertical, respectivamente. Alm disso, sempre que voc clicar no palco, a intensidade do desfoque aumentar.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

274

import import import import

flash.events.MouseEvent; flash.filters.BitmapFilterQuality; flash.filters.BitmapFilterType; flash.filters.GradientGlowFilter;

// Create a new Shape instance. var shape:Shape = new Shape(); // Draw the shape. shape.graphics.beginFill(0xFF0000, 100); shape.graphics.moveTo(0, 0); shape.graphics.lineTo(100, 0); shape.graphics.lineTo(100, 100); shape.graphics.lineTo(0, 100); shape.graphics.lineTo(0, 0); shape.graphics.endFill(); // Position the shape on the Stage. addChild(shape); shape.x = 100; shape.y = 100; // Define a gradient glow. var gradientGlow:GradientGlowFilter = new GradientGlowFilter(); gradientGlow.distance = 0; gradientGlow.angle = 45; gradientGlow.colors = [0x000000, 0xFF0000]; gradientGlow.alphas = [0, 1]; gradientGlow.ratios = [0, 255]; gradientGlow.blurX = 10; gradientGlow.blurY = 10; gradientGlow.strength = 2; gradientGlow.quality = BitmapFilterQuality.HIGH; gradientGlow.type = BitmapFilterType.OUTER; // Define functions to listen for two events. function onClick(event:MouseEvent):void { gradientGlow.strength++; shape.filters = [gradientGlow]; } function onMouseMove(event:MouseEvent):void { gradientGlow.blurX = (stage.mouseX / stage.stageWidth) * 255; gradientGlow.blurY = (stage.mouseY / stage.stageHeight) * 255; shape.filters = [gradientGlow]; } stage.addEventListener(MouseEvent.CLICK, onClick); stage.addEventListener(MouseEvent.MOUSE_MOVE, onMouseMove);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

275

Exemplo: combinao de filtros bsicos

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O cdigo a seguir usa vrios filtros bsicos, combinados com um cronmetro, para criar aes repetidas e simular um farol animado.
import import import import import import import import var var var var var var var var var var var var flash.display.Shape; flash.events.TimerEvent; flash.filters.BitmapFilterQuality; flash.filters.BitmapFilterType; flash.filters.DropShadowFilter; flash.filters.GlowFilter; flash.filters.GradientBevelFilter; flash.utils.Timer;

count:Number = 1; distance:Number = 8; angleInDegrees:Number = 225; // opposite of 45 degrees colors:Array = [0xFFFFCC, 0xFEFE78, 0x8F8E01]; alphas:Array = [1, 0, 1]; ratios:Array = [0, 128, 255]; blurX:Number = 8; blurY:Number = 8; strength:Number = 1; quality:Number = BitmapFilterQuality.HIGH; type:String = BitmapFilterType.INNER; knockout:Boolean = false;

// Draw the rectangle background for the traffic light. var box:Shape = new Shape(); box.graphics.lineStyle(); box.graphics.beginFill(0xFEFE78); box.graphics.drawRect(100, 50, 90, 200); box.graphics.endFill(); // Draw the 3 circles for the three lights. var stopLight:Shape = new Shape(); stopLight.graphics.lineStyle(); stopLight.graphics.beginFill(0xFF0000); stopLight.graphics.drawCircle(145,90,25); stopLight.graphics.endFill(); var cautionLight:Shape = new Shape(); cautionLight.graphics.lineStyle(); cautionLight.graphics.beginFill(0xFF9900); cautionLight.graphics.drawCircle(145,150,25); cautionLight.graphics.endFill(); var goLight:Shape = new Shape(); goLight.graphics.lineStyle(); goLight.graphics.beginFill(0x00CC00); goLight.graphics.drawCircle(145,210,25); goLight.graphics.endFill(); // Add the graphics to the display list. addChild(box);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

276

addChild(stopLight); addChild(cautionLight); addChild(goLight); // Apply a gradient bevel to the traffic light rectangle. var gradientBevel:GradientBevelFilter = new GradientBevelFilter(distance, angleInDegrees, colors, alphas, ratios, blurX, blurY, strength, quality, type, knockout); box.filters = [gradientBevel]; // Create the inner shadow (for lights when off) and glow // (for lights when on). var innerShadow:DropShadowFilter = new DropShadowFilter(5, 45, 0, 0.5, 3, 3, 1, 1, true, false); var redGlow:GlowFilter = new GlowFilter(0xFF0000, 1, 30, 30, 1, 1, false, false); var yellowGlow:GlowFilter = new GlowFilter(0xFF9900, 1, 30, 30, 1, 1, false, false); var greenGlow:GlowFilter = new GlowFilter(0x00CC00, 1, 30, 30, 1, 1, false, false); // Set the starting state of the lights (green on, red/yellow off). stopLight.filters = [innerShadow]; cautionLight.filters = [innerShadow]; goLight.filters = [greenGlow]; // Swap the filters based on the count value. function trafficControl(event:TimerEvent):void { if (count == 4) { count = 1; } switch (count) { case 1: stopLight.filters = [innerShadow]; cautionLight.filters = [yellowGlow]; goLight.filters = [innerShadow]; break; case 2: stopLight.filters = [redGlow]; cautionLight.filters = [innerShadow]; goLight.filters = [innerShadow]; break; case 3: stopLight.filters = [innerShadow]; cautionLight.filters = [innerShadow]; goLight.filters = [greenGlow]; break; } count++; } // Create a timer to swap the filters at a 3 second interval. var timer:Timer = new Timer(3000, 9); timer.addEventListener(TimerEvent.TIMER, trafficControl); timer.start();

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

277

Filtro de matriz de cor

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe ColorMatrixFilter usada para manipular a cor e os valores alfa do objeto filtrado. Isso permite criar alteraes de saturao, rotao de matizes (alterando uma paleta de uma gama de cores para outra), alteraes de luminncia para alfa e outros efeitos de manipulao de cor usando valores de um canal de cor e possivelmente aplicando-os em outros canais. Conceitualmente, o filtro percorre cada pixel da imagem de origem e separa-os nos componentes vermelho, verde, azul e alfa. Em seguida, os valores fornecidos na matriz de cor so multiplicados por cada um desses valores, somando os resultados para determinar o valor de cor resultante que ser exibido na tela para o pixel em questo. A propriedade matrix do filtro uma matriz de 20 nmeros usada no clculo da cor final. Para obter detalhes do algoritmo especfico utilizado para calcular os valores de cor, consulte a entrada que descreve a propriedade matrixda classe ColorMatrixFilter em Referncia do ActionScript 3.0 para a plataforma Adobe Flash. Outras informaes e exemplos do filtro de matriz de cor esto disponveis no artigo Uso de matrizes para transformaes, ajustes de cor e efeitos de convoluo no Flash no site do Centro de desenvolvedores da Adobe.

Filtro de convoluo
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe ConvolutionFilter pode ser usada para aplicar diversas transformaes de imagem em objetos BitmapData e objetos de exibio, como desfoque, deteco de borda, nitidez, entalhe e bisel. Conceitualmente, o filtro de convoluo percorre cada pixel da imagem de origem e determina a cor final desse pixel usando o valor do pixel e dos pixels ao redor. Uma matriz, especificada como uma matriz de valores numricos, indica at que ponto o valor de cada pixel ao redor afeta o valor resultante final. Considere o tipo de matriz utilizado com mais freqncia, que uma matriz 3 x 3. A matriz inclui nove valores:
N N N N P N N N N

Quando o filtro de convoluo aplicado a um certo pixel, considerado o valor de cor do pixel propriamente dito (P no exemplo), bem como os valores dos pixels ao redor (N no exemplo). No entanto, definindo valores na matriz, voc especifica a prioridade de determinados pixels na imagem resultante. Por exemplo, a matriz a seguir, que tem um filtro de convoluo aplicado, deixar uma imagem exatamente como era:
0 0 0 0 1 0 0 0 0

A imagem no alterada porque o valor do pixel original tem uma intensidade relativa igual a 1 para determinar a cor final do pixel, enquanto os valores dos pixels ao redor tm a intensidade relativa igual a 0 - suas cores no afetam a imagem final. Similarmente, essa matriz far com que os pixels de uma imagem mudem um pixel para a esquerda:
0 0 0 0 0 0 0 1 0

Observe que, nesse caso, o pixel propriamente dito no afeta o valor final do pixel exibido nesse local na imagem final; apenas o valor do pixel direita usado para determinar o valor resultante do pixel.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

278

No ActionScript, voc cria a matriz como uma combinao de uma ocorrncia de Array que contm os valores e as duas propriedades que especificam o nmero de linhas e colunas da matriz. O exemplo a seguir carrega uma imagem e, quando o carregamento termina, aplica um filtro de convoluo na imagem usando a matriz da listagem anterior:
// Load an image onto the Stage. var loader:Loader = new Loader(); var url:URLRequest = new URLRequest("http://www.helpexamples.com/flash/images/image1.jpg"); loader.load(url); this.addChild(loader); function applyFilter(event:MouseEvent):void { // Create the convolution matrix. var matrix:Array = [0, 0, 0, 0, 0, 1, 0, 0, 0]; var convolution:ConvolutionFilter = new ConvolutionFilter(); convolution.matrixX = 3; convolution.matrixY = 3; convolution.matrix = matrix; convolution.divisor = 1; loader.filters = [convolution]; } loader.addEventListener(MouseEvent.CLICK, applyFilter);

O que no fica bvio nesse cdigo o efeito do uso de valores diferentes de 1 ou 0 na matriz. Por exemplo, a mesma matriz, com o nmero 8 em vez de 1 na posio direita, executa a mesma ao (movimentando os pixels para a esquerda). Alm disso, ela afeta as cores da imagem, deixando-as oito vezes mais brilhantes. Isso ocorre porque os valores finais de cor do pixel so calculados pela multiplicao dos valores da matriz pelas cores do pixel original, pela soma dos valores e pela diviso pelo valor da propriedade divisor do filtro. Observe que, no cdigo de exemplo, a propriedade divisor definida como 1. Como regra geral, se desejar que o brilho das cores permanea quase igual ao brilho da imagem original, o divisor deve ser igual soma dos valores da matriz. Desse modo, se uma matriz tiver a soma de seus valores igual a 8 e o divisor igual a 1, a imagem resultante ser aproximadamente 8 vezes mais brilhante do que a imagem original. Embora o efeito nessa matriz no seja muito notvel, outros valores de matriz podem ser usados para criar diversos efeitos. Veja alguns conjuntos padro de valores de matriz para diferentes efeitos usando uma matriz 3 x 3:

Desfoque bsico (divisor 5):

0 1 0 1 1 1 0 1 0

Nitidez (divisor 1):

0, -1, 0 -1, 5, -1 0, -1, 0

Deteco de borda (divisor 1):

0, -1, 0 -1, 4, -1 0, -1, 0

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

279

Efeito de entalhe (divisor 1):

-2, -1, 0 -1, 1, 1 0, 1, 2

Observe que na maioria desses efeitos o divisor igual a 1. Isso ocorre porque a adio de valores de matriz negativos a valores de matriz positivos resulta em 1 (ou 0 no caso da deteco de borda, mas o valor da propriedade divisor no pode ser 0).

Filtro de mapa de deslocamento

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe DisplacementMapFilter usa valores de pixel de um objeto BitmapData (conhecido como a imagem do mapa de deslocamento) para realizar um efeito de deslocamento em um novo objeto. A imagem do mapa de deslocamento normalmente diferente do objeto de exibio ou da ocorrncia de BitmapData real no qual o filtro est sendo aplicado. Um efeito de deslocamento envolve a movimentao de pixels nas imagem filtrada - em outras palavras, desloc-los do local original para alguma posio. Esse filtro pode ser usado para criar um efeito alterado, distorcido ou matizado. O local e a quantidade de deslocamento aplicados em um determinado pixel so especificados pelo valor de cor da imagem do mapa de deslocamento. Ao trabalhar com o filtro, alm de especificar a imagem do mapa, voc especifica os seguintes valores para controlar como o deslocamento calculado a partir da imagem do mapa:

Ponto do mapa: o local da imagem filtrada na qual o canto superior esquerdo do filtra de deslocamento ser
aplicado. Use esse ponto apenas se desejar aplicar o filtro em parte de uma imagem.

Componente X: canal de cor da imagem do mapa que afeta a posio x dos pixels. Componente Y: canal de cor da imagem do mapa que afeta a posio y dos pixels. Escala X: um valor de multiplicador que especifica a intensidade do deslocamento do eixo x. Escala Y: um valor de multiplicador que especifica a intensidade do deslocamento do eixo y. Modo de filtro: determina o que fazer em qualquer espao vazio criado pelos pixels que esto sendo alterados. As
opes, definidas como constantes na classe DisplacementMapFilterMode, devem exibir os pixels originais (modo de filtro IGNORE), colocar os pixels em torno do outro lado da imagem (modo de filtro WRAP, que o padro), usar o pixel alterado mais prximo (modo de filtro CLAMP) ou preencher os espaos com uma cor (modo de filtro COLOR). Para entender o funcionamento do filtro do mapa de deslocamento, considere um exemplo simples. No cdigo a seguir, uma imagem carregada e, em seguida, centralizada no palco. Um filtro de mapa de deslocamento aplicado, fazendo com que os pixels da imagem inteira mudem horizontalmente para a esquerda.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

280

import import import import import import

flash.display.BitmapData; flash.display.Loader; flash.events.MouseEvent; flash.filters.DisplacementMapFilter; flash.geom.Point; flash.net.URLRequest;

// Load an image onto the Stage. var loader:Loader = new Loader(); var url:URLRequest = new URLRequest("http://www.helpexamples.com/flash/images/image3.jpg"); loader.load(url); this.addChild(loader); var mapImage:BitmapData; var displacementMap:DisplacementMapFilter; // This function is called when the image finishes loading. function setupStage(event:Event):void { // Center the loaded image on the Stage. loader.x = (stage.stageWidth - loader.width) / 2; loader.y = (stage.stageHeight - loader.height) / 2; // Create the displacement map image. mapImage = new BitmapData(loader.width, loader.height, false, 0xFF0000); // Create the displacement filter. displacementMap = new DisplacementMapFilter(); displacementMap.mapBitmap = mapImage; displacementMap.mapPoint = new Point(0, 0); displacementMap.componentX = BitmapDataChannel.RED; displacementMap.scaleX = 250; loader.filters = [displacementMap]; } loader.contentLoaderInfo.addEventListener(Event.COMPLETE, setupStage);

As propriedades usadas para definir o deslocamento so as seguintes:

Bitmap de mapa: o bitmap de deslocamento uma nova ocorrncia de BitmapData criada pelo cdigo. Suas
dimenses coincidem com as dimenses da imagem carregada (de modo que o deslocamento aplicado na imagem inteira). Ela preenchida com pixels vermelhos slidos.

Ponto do mapa: esse valor definido como o ponto 0, 0 - mais uma vez, o deslocamento ser aplicado na imagem
inteira.

Componente X: esse valor definido como a constante BitmapDataChannel.RED, o que significa que o valor
vermelho do bitmap de mapa determinar o deslocamento dos pixels (o quanto se movimentam) ao longo do eixo x.

Escala X: esse valor definido como 250. O valor total de deslocamento (a partir da imagem do mapa que est
completamente vermelha) desloca a imagem apenas um pouco (aproximadamente metade de um pixel), de modo que, se esse valor fosse definido como 1, a imagem seria movida apenas 0,5 pixel na horizontal. Se esse valor for definido como 250, a imagem ser deslocada aproximadamente 125 pixels.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

281

Essas configuraes fazem com que os pixels da imagem filtrada sejam deslocados 250 pixels para a esquerda. A direo (esquerda ou direita) e o valor do deslocamento baseiam-se no valor de cor dos pixels da imagem do mapa. Conceitualmente, o filtro percorre cada pixel da imagem filtrada (pelo menos os pixels da regio onde o filtro aplicado que, nesse caso, so todos os pixels) e faz o seguinte com cada pixel:
1 Localiza o pixel correspondente na imagem do mapa. Por exemplo, quando o filtro calcula o valor de deslocamento

para o pixel no canto superior esquerdo da imagem filtrada, ser observado o pixel no canto superior esquerdo da imagem do mapa.
2 Determina o valor do canal de cor especificado no pixel do mapa. Nesse caso, o canal de cor do componente x o

canal vermelho, de modo que o filtro observa qual o valor do canal vermelho da imagem do mapa no pixel em questo. Como a imagem do mapa vermelho slido, o canal vermelho do pixel 0xFF ou 255. Esse valor usado como valor de deslocamento.
3 Compara o valor de deslocamento com o valor "central" (127, que o valor mdio entre 0 e 255). Se o valor de

deslocamento for inferior ao valor mdio, o pixel ser deslocado em uma direo positiva (para a direita no deslocamento x; para baixo no deslocamento y). Por outro lado, se o valor de deslocamento for maior do que o valor mdio (como neste exemplo), o pixel ser deslocado em uma direo negativa (para a esquerda no deslocamento x; para cima no deslocamento y). Para ser mais preciso, o filtro subtrai o valor de deslocamento de 127 e o resultado (positivo ou negativo) o valor relativo do deslocamento que aplicado.
4 Finalmente, ele determina o valor real de deslocamento definindo qual porcentagem de deslocamento completo

representado pelo valor de deslocamento relativo. Nesse caso, vermelho total indica 100% de deslocamento. Essa porcentagem multiplicada pelo valor da escala x ou y para determinar o nmero de pixels do deslocamento que ser aplicado. Neste exemplo, 100% vezes um multiplicador igual a 250 determina o valor de deslocamento aproximadamente 125 pixels para a esquerda. Como nenhum valor foi especificado para o componente e a escala y, os padres (que no provocam nenhum deslocamento) foram usados; por esse motivo que a imagem no alterada na vertical. A configurao padro do modo de filtro, WRAP, usada no exemplo, de modo que os pixels se movem para a esquerda e o espao vazio direita preenchido pelos pixels que se deslocaram da margem esquerda da imagem. Voc pode experimentar esse valor para ver os diferentes efeitos. Por exemplo, se voc adicionar a linha a seguir parte do cdigo onde as propriedades de deslocamento esto sendo definidas (antes da linha loader.filters = [displacementMap]), a imagem parecer ter sido manchada ao longo do palco:
displacementMap.mode = DisplacementMapFilterMode.CLAMP;

Em exemplos mais complexos, a listagem a seguir usa um filtro de mapa de deslocamento para criar um efeito de lupa em uma imagem:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

282

import import import import import import import import import import import import

flash.display.Bitmap; flash.display.BitmapData; flash.display.BitmapDataChannel; flash.display.GradientType; flash.display.Loader; flash.display.Shape; flash.events.MouseEvent; flash.filters.DisplacementMapFilter; flash.filters.DisplacementMapFilterMode; flash.geom.Matrix; flash.geom.Point; flash.net.URLRequest;

// Create the gradient circles that will together form the // displacement map image var radius:uint = 50; var type:String = GradientType.LINEAR; var redColors:Array = [0xFF0000, 0x000000]; var blueColors:Array = [0x0000FF, 0x000000]; var alphas:Array = [1, 1]; var ratios:Array = [0, 255]; var xMatrix:Matrix = new Matrix(); xMatrix.createGradientBox(radius * 2, radius * 2); var yMatrix:Matrix = new Matrix(); yMatrix.createGradientBox(radius * 2, radius * 2, Math.PI / 2); var xCircle:Shape = new Shape(); xCircle.graphics.lineStyle(0, 0, 0); xCircle.graphics.beginGradientFill(type, redColors, alphas, ratios, xMatrix); xCircle.graphics.drawCircle(radius, radius, radius); var yCircle:Shape = new Shape(); yCircle.graphics.lineStyle(0, 0, 0); yCircle.graphics.beginGradientFill(type, blueColors, alphas, ratios, yMatrix); yCircle.graphics.drawCircle(radius, radius, radius); // Position the circles at the bottom of the screen, for reference. this.addChild(xCircle); xCircle.y = stage.stageHeight - xCircle.height; this.addChild(yCircle); yCircle.y = stage.stageHeight - yCircle.height; yCircle.x = 200; // Load an image onto the Stage. var loader:Loader = new Loader(); var url:URLRequest = new URLRequest("http://www.helpexamples.com/flash/images/image1.jpg"); loader.load(url); this.addChild(loader); // Create the map image by combining the two gradient circles. var map:BitmapData = new BitmapData(xCircle.width, xCircle.height, false, 0x7F7F7F); map.draw(xCircle); var yMap:BitmapData = new BitmapData(yCircle.width, yCircle.height, false, 0x7F7F7F); yMap.draw(yCircle); map.copyChannel(yMap, yMap.rect, new Point(0, 0), BitmapDataChannel.BLUE, BitmapDataChannel.BLUE);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

283

yMap.dispose(); // Display the map image on the Stage, for reference. var mapBitmap:Bitmap = new Bitmap(map); this.addChild(mapBitmap); mapBitmap.x = 400; mapBitmap.y = stage.stageHeight - mapBitmap.height; // This function creates the displacement map filter at the mouse location. function magnify():void { // Position the filter. var filterX:Number = (loader.mouseX) - (map.width / 2); var filterY:Number = (loader.mouseY) - (map.height / 2); var pt:Point = new Point(filterX, filterY); var xyFilter:DisplacementMapFilter = new DisplacementMapFilter(); xyFilter.mapBitmap = map; xyFilter.mapPoint = pt; // The red in the map image will control x displacement. xyFilter.componentX = BitmapDataChannel.RED; // The blue in the map image will control y displacement. xyFilter.componentY = BitmapDataChannel.BLUE; xyFilter.scaleX = 35; xyFilter.scaleY = 35; xyFilter.mode = DisplacementMapFilterMode.IGNORE; loader.filters = [xyFilter]; } // This function is called when the mouse moves. If the mouse is // over the loaded image, it applies the filter. function moveMagnifier(event:MouseEvent):void { if (loader.hitTestPoint(loader.mouseX, loader.mouseY)) { magnify(); } } loader.addEventListener(MouseEvent.MOUSE_MOVE, moveMagnifier);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

284

Primeiro, o cdigo gera dois crculos de gradiente, que so combinados para formar a imagem do mapa de deslocamento. O crculo vermelho cria o deslocamento do eixo x (xyFilter.componentX = BitmapDataChannel.RED) e o crculo azul cria o deslocamento do eixo y (xyFilter.componentY = BitmapDataChannel.BLUE). Para ajudar voc a entender como se parece a imagem do mapa de deslocamento, o cdigo adiciona os crculos originais, bem como o crculo combinado que serve como a imagem do mapa, parte inferior da tela.

Em seguida, o cdigo carrega uma imagem e, medida que o mouse se move, aplica o filtro de deslocamento na parte da imagem que est embaixo do mouse. Os crculos de gradiente usados como a imagem do mapa de deslocamento fazem com que a regio deslocada se distancie do ponteiro. Observe que as regies de cinza da imagem do mapa no provocam nenhum deslocamento. A cor de cinza 0x7F7F7F. Os canais azul e vermelho dessa sombra de cinza correspondem exatamente sombra central desses canais de cor, de modo que no h nenhum deslocamento em uma rea de cinza da imagem do mapa. Do mesmo modo, no h nenhum deslocamento no centro do crculo. Embora a cor no seja cinza, os canais azul e vermelho dessa cor so idnticos aos canais azul e vermelho do cinza mdio e, como azul e vermelho so as cores que provocam o deslocamento, no ocorre nenhum deslocamento aqui.

Filtro de sombreador
Flash Player 10 e posterior, Adobe AIR 1.5 e posterior A classe ShaderFilter permite o uso de um efeito de filtro personalizado definido como um sombreador Pixel Bender. Como gravado como um sombreador Pixel Bender, o efeito de filtro pode ser completamente personalizado. O contedo filtrado transmitido para o sombreador como uma entrada de imagem e o resultado da operao de shader se transforma no resultado de filtro. Nota: O filtro Sombreador est disponvel no ActionScript a partir do Flash Player 10 e do Adobe AIR 1.5. Para aplicar um filtro de sombreador em um objeto, crie uma ocorrncia de Shader que representa o sombreador Pixel Bender utilizado. Para obter informaes sobre o procedimento de criao de uma ocorrncia de Shader e sobre como especificar a imagem de entrada e valores de parmetro, consulte Trabalho com sombreadores Pixel Bender na pgina 293. Ao usar um sombreador como filtro, tenha em mente trs coisas importantes:

O sombreador deve ser definido para aceitar pelo menos uma imagem de entrada.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

285

O objeto filtrado (o objeto de exibio ou o objeto BitmapData no qual o filtro aplicado) transmitido para o
sombreador como o primeiro valor da imagem de entrada. Devido a isso, no especifique manualmente um valor para a primeira entrada de imagem.

Se o sombreador definir mais de uma imagem de entrada, as entradas adicionais devero ser especificadas
manualmente (isto , ser necessrio definir a propriedade input de todas as ocorrncias de ShaderInput que pertencem ocorrncia de Shader). Assim que um objeto Shader tiver sido definido para o sombreador, crie uma ocorrncia de ShaderFilter. Este o objeto de filtro real usado como qualquer outro filtro. Para criar um ShaderFilter que usa um objeto Shader, chame o construtor ShaderFilter() e transmita o objeto Shader como um argumento, como mostra esta listagem:
var myFilter:ShaderFilter = new ShaderFilter(myShader);

Para obter um exemplo completo de como utilizar um filtro de sombreador, consulte Uso de um sombreador como filtro na pgina 311.

Exemplo de filtragem de objetos de exibio: bancada do filtro

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O Filter Workbench fornece uma interface de usurio para aplicar filtros diferentes em imagens e outros contedos visuais e para visualizar o cdigo resultante que pode ser usado para gerar o mesmo efeito no ActionScript. Alm de fornecer uma ferramenta para experimentar filtros, esse aplicativo demonstra as seguintes tcnicas:

Criao de ocorrncias de vrios filtros Aplicao de vrios filtros em um objeto de exibio

Para obter os arquivos do aplicativo para este exemplo, consulte www.adobe.com/go/learn_programmingAS3samples_flash_br. Os arquivos do aplicativo Filter Workbench esto localizados na pasta Amostras/FilterWorkbench. O aplicativo consiste nos seguintes arquivos:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

286

Arquivo com/example/programmingas3/filterWorkbench/FilterWorkbenchController.as

Descrio Classe que fornece a principal funcionalidade do aplicativo, incluindo a alternncia do contedo para os filtros aplicados e a aplicao de filtros no contedo. Interface que define mtodos comuns que so implementados por cada classe padro de filtro. Essa interface define a funcionalidade comum que a classe FilterWorkbenchController usa para interagir com classes individuais de filtro padro. Conjunto de classes, cada uma delas implementa a interface IFilterFactory. Cada uma dessas classes permite criar e definir valores para um nico tipo de filtro. Os painis de propriedade de filtro do aplicativo usam essas classes padro para criar ocorrncias de filtros especficos, que a classe FilterWorkbenchController recupera e aplica no contedo da imagem.

com/example/programmingas3/filterWorkbench/IFilterFactory.as

Na pasta com/example/programmingas3/filterWorkbench/: BevelFactory.as BlurFactory.as ColorMatrixFactory.as ConvolutionFactory.as DropShadowFactory.as GlowFactory.as GradientBevelFactory.as GradientGlowFactory.as com/example/programmingas3/filterWorkbench/IFilterPanel.as

Interface que define mtodos comuns implementados pelas classes que definem os painis da interface de usurio usados para manipular valores de filtro no aplicativo. Classe de utilitrio que inclui um mtodo para converter um valor de cor numrico em um formato de string hexadecimal Classe que serve como objeto de valor, combinando em um nico objeto os trs valores (cor, alfa e proporo) associados a cada cor em GradientBevelFilter e GradientGlowFilter

com/example/programmingas3/filterWorkbench/ColorStringFormatter.as

com/example/programmingas3/filterWorkbench/GradientColor.as

Interface de usurio (Flex) FilterWorkbench.mxml O arquivo principal que define a interface de usurio do aplicativo. Classe que gera a funcionalidade da interface de usurio do aplicativo principal; essa classe usada como a classe code-behind do arquivo MXML do aplicativo. Conjunto de componentes MXML que gera a funcionalidade de cada painel usado para definir opes para um nico filtro.

flexapp/FilterWorkbench.as

Na pasta flexapp/filterPanels: BevelPanel.mxml BlurPanel.mxml ColorMatrixPanel.mxml ConvolutionPanel.mxml DropShadowPanel.mxml GlowPanel.mxml GradientBevelPanel.mxml GradientGlowPanel.mxml

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

287

Arquivo flexapp/ImageContainer.as

Descrio Um objeto de exibio que serve como continer da imagem carregada na tela Renderizador de clula personalizado usado para alterar a cor de fundo de uma clula no componente DataGrid Controle personalizado que define uma caixa combinada que pode ser usada na configurao de qualidade de diversos painis de filtro. Controle personalizado que define uma caixa combinada que pode ser usada na configurao de tipo de diversos painis de filtro.

flexapp/controls/BGColorCellRenderer.as

flexapp/controls/QualityComboBox.as

flexapp/controls/TypeComboBox.as

Interface de usurio (Flash) FilterWorkbench.fla O arquivo principal que define a interface de usurio do aplicativo. Classe que gera a funcionalidade da interface de usurio do aplicativo principal; essa classe usada como a classe document do arquivo FLA do aplicativo. Conjunto de classes que geram a funcionalidade de cada painel usado para definir opes para um nico filtro. Para cada classe, tambm existe um smbolo MovieClip associado na biblioteca do arquivo FLA do aplicativo principal, cujo nome corresponde ao nome da classe (por exemplo, o smbolo BlurPanel est vinculado classe definida em BlurPanel.as). Os componentes que fazem parte da interface de usurio so posicionados e nomeados nesses smbolos.

flashapp/FilterWorkbench.as

Na pasta flashapp/filterPanels: BevelPanel.as BlurPanel.as ColorMatrixPanel.as ConvolutionPanel.as DropShadowPanel.as GlowPanel.as GradientBevelPanel.as GradientGlowPanel.as flashapp/ImageContainer.as

Um objeto de exibio que serve como continer da imagem carregada na tela Renderizador de clula personalizado usado para alterar a cor de fundo de uma clula no componente DataGrid Renderizador de clula personalizado usado para incluir um componente de boto em uma clula no componente DataGrid

flashapp/BGColorCellRenderer.as

flashapp/ButtonCellRenderer.as

Contedo da imagem filtrada com/example/programmingas3/filterWorkbench/ImageType.as Essa classe serve como um objeto de valor que contm o tipo e a URL de um nico arquivo de imagem no qual o aplicativo pode carregar e aplicar filtros. A classe tambm inclui um conjunto de constantes que representam os arquivos de imagem reais disponveis. Imagens e outros contedos visuais nos quais os filtros so aplicados no aplicativo.

images/sampleAnimation.swf, images/sampleImage1.jpg, images/sampleImage2.jpg

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

288

Como experimentar filtros do ActionScript

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O aplicativo Filter Workbench foi desenvolvido para ajudar voc a experimentar os diversos efeitos de filtro e gerar o cdigo do ActionScript relevante para esse efeito. O aplicativo permite selecionar entre trs arquivos diferentes que possuem contedo visual, incluindo imagens de bitmap e uma animao criada no Flash, alm de permitir aplicar oito filtros diferentes do ActionScript na imagem selecionada, individualmente ou em combinao com outros filtros. O aplicativo inclui estes filtros:

Bisel (flash.filters.BevelFilter) Desfoque (flash.filters.BlurFilter) Matrix de cor (flash.filters.ColorMatrixFilter) Convoluo (flash.filters.ConvolutionFilter) Sombra projetada (flash.filters.DropShadowFilter) Brilho (flash.filters.GlowFilter) Bisel de gradiente (flash.filters.GradientBevelFilter) Brilho de gradiente (flash.filters.GradientGlowFilter)
Depois que o usurio seleciona uma imagem e um filtro a ser aplicado nessa imagem, o aplicativo exibe um painel com controles para definir as propriedades especficas do filtro selecionado. Por exemplo, a imagem a seguir mostra o aplicativo com o filtro de bisel selecionado:

medida que o usurio ajusta as propriedades de filtro, a visualizao atualizada em tempo real. O usurio tambm pode aplicar vrios filtros personalizando um filtro, clicando no boto Apply filter and add another, personalizando outro filtro, clicando no boto Apply filter and add another e assim por diante.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

289

Existem alguns recursos e limitaes nos painis de filtro do aplicativo:

O filtro de matriz de cor inclui um conjunto de controles para manipular diretamente propriedades comuns de
imagem, como brilho, contrastes, saturao e matiz. Alm disso, possvel especificar valores personalizados de matriz de cor.

O filtro de convoluo, que est disponvel somente no ActionScript, inclui no conjunto de valores de matriz de
convoluo usados normalmente ou valores personalizados podem ser especificados. No entanto, enquanto a classe ConvolutionFilter aceita qualquer tamanho de matriz, o aplicativo Filter Workbench usa uma matriz 3 x 3 fixa, o tamanho de filtro usado com mais freqncia.

Os filtros de mapa de deslocamento e de sombreador, disponveis somente no ActionScript, no esto presentes no

aplicativo Filter Workbench.

Criao de ocorrncias de filtro

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O aplicativo Filter Workbench inclui um conjunto de classes, uma para cada filtro disponvel, que so usadas por painis individuais para criar os filtros. Quando o usurio seleciona um filtro, o cdigo do ActionScript associado ao painel de filtro cria uma ocorrncia da classe de filtro de fbrica apropriada. Essas classes so conhecidas como classes de fbrica porque sua finalidade criar ocorrncias de outros objetos, assim como uma fbrica real cria produtos individuais. Sempre que o usurio altera um valor de propriedade no painel, o cdigo do painel chama o mtodo adequado na classe de fbrica. Cada classe de fbrica inclui mtodos especficos usados pelo painel para criar a ocorrncia de filtro adequada. Por exemplo, se o usurio selecionar o filtro de desfoque, o aplicativo criar uma ocorrncia de BlurFactory. A classe BlurFactory inclui um mtodo modifyFilter() que aceita trs parmetros: blurX, blurY e quality, que so usados em conjunto para criar a ocorrncia de BlurFilter desejada:
private var _filter:BlurFilter; public function modifyFilter(blurX:Number = 4, blurY:Number = 4, quality:int = 1):void { _filter = new BlurFilter(blurX, blurY, quality); dispatchEvent(new Event(Event.CHANGE)); }

Por outro lado, se o usurio selecionar o filtro de convoluo, esse filtro dar uma flexibilidade muito maior e, conseqentemente, ter um conjunto maior de propriedades para controlar. Na classe ConvolutionFactory, o cdigo a seguir chamado quando o usurio seleciona um valor diferente no painel de filtro:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

290

private var _filter:ConvolutionFilter; public function modifyFilter(matrixX:Number = 0, matrixY:Number = 0, matrix:Array = null, divisor:Number = 1.0, bias:Number = 0.0, preserveAlpha:Boolean = true, clamp:Boolean = true, color:uint = 0, alpha:Number = 0.0):void { _filter = new ConvolutionFilter(matrixX, matrixY, matrix, divisor, bias, preserveAlpha, clamp, color, alpha); dispatchEvent(new Event(Event.CHANGE)); }

Observe que, em cada caso, quando os valores de filtro so alterados, o objeto de fbrica envia um evento Event.CHANGE para notificar os ouvintes que os valores do filtro foram alterados. A classe FilterWorkbenchController, que realmente aplica os filtros no contedo filtrado, ouve esse evento para recuperar uma nova cpia do filtro e reaplic-lo no contedo filtrado quando necessrio. A classe FilterWorkbenchController no precisa conhecer os detalhes especficos de cada classe de fbrica de filtro ela s precisa saber que o filtro foi alterado e acessar uma cpia do filtro. Para dar suporte a isso, o aplicativo inclui uma interface, IFilterFactory, que define o comportamento que uma classe de fbrica de filtro precisa fornecer para que a ocorrncia de FilterWorkbenchController do aplicativo possa fazer seu trabalho. A classe IFilterFactory define o mtodo getFilter() que usado na classe FilterWorkbenchController:
function getFilter():BitmapFilter;

Observe que a definio do mtodo da interface getFilter() especifica o retorno de uma ocorrncia de BitmapFilter, em vez de um tipo especfico de filtro. A classe BitmapFilter no define um tipo especfico de filtro. Em vez disso, BitmapFilter a classe bsica a partir da qual todas as classes de filtro so criadas. Cada classe de fbrica de filtro define uma implementao especfica do mtodo getFilter() que retorna uma referncia ao objeto de filtro criado. Por exemplo, veja uma verso abreviada do cdigo-fonte da classe ConvolutionFactory:
public class ConvolutionFactory extends EventDispatcher implements IFilterFactory { // ------- Private vars ------private var _filter:ConvolutionFilter; ... // ------- IFilterFactory implementation ------public function getFilter():BitmapFilter { return _filter; } ... }

Na implementao da classe ConvolutionFactory do mtodo getFilter(), retornada uma ocorrncia de ConvolutionFilter, embora nenhum objeto que chame getFilter() saiba necessariamente disso - de acordo com a definio do mtodo getFilter() seguida por ConvolutionFactory, qualquer ocorrncia de BitmapFilter deve ser retornada, a qual pode ser uma ocorrncia de qualquer classe de filtro do ActionScript.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

291

Aplicao de filtros em objetos de exibio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Conforme explicado antes, o aplicativo Filter Workbench usa uma ocorrncia da classe FilterWorkbenchController (a partir daqui mencionada como ocorrncia do controlador), que realmente aplica os filtros no objeto visual selecionado. Antes de aplicar um filtro, a ocorrncia do controlador precisa saber em qual imagem ou contedo visual o filtro deve ser aplicado. Quando o usurio seleciona uma imagem, o aplicativo chama o mtodo setFilterTarget() na classe FilterWorkbenchController, transmitindo uma das constantes definidas na classe ImageType:
public function setFilterTarget(targetType:ImageType):void { ... _loader = new Loader(); ... _loader.contentLoaderInfo.addEventListener(Event.COMPLETE, targetLoadComplete); ... }

Usando essas informaes, a ocorrncia do controlador carrega o arquivo designado, armazenando-o em uma varivel da ocorrncia chamada _currentTarget assim que o carregamento termina:
private var _currentTarget:DisplayObject; private function targetLoadComplete(event:Event):void { ... _currentTarget = _loader.content; ... }

Quando o usurio seleciona um filtro, o aplicativo chama o mtodo setFilter() da ocorrncia do controlador, dando ao controlador uma referncia ao objeto de fbrica de filtro relevante, armazenado em uma varivel da ocorrncia chamada _filterFactory.
private var _filterFactory:IFilterFactory; public function setFilter(factory:IFilterFactory):void { ... _filterFactory = factory; _filterFactory.addEventListener(Event.CHANGE, filterChange); }

Observe que, conforme descrito anteriormente, a ocorrncia do controlador no sabe o tipo de dados especfico da ocorrncia de fbrica de filtro fornecida; ela s sabe que o objeto implementa a ocorrncia de IFilterFactory, indicando que tem um mtodo getFilter() e envia um evento change (Event.CHANGE) quando o filtro alterado. Quando o usurio altera as propriedades no painel do filtro, a ocorrncia do controlador descobre que o filtro foi alterado por meio do evento change da fbrica de filtro, que chama o mtodo filterChange() da ocorrncia do controlador. Esse mtodo, por sua vez, chama o mtodo applyTemporaryFilter():

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Filtro de objetos de exibio

292

private function filterChange(event:Event):void { applyTemporaryFilter(); } private function applyTemporaryFilter():void { var currentFilter:BitmapFilter = _filterFactory.getFilter(); // Add the current filter to the set temporarily _currentFilters.push(currentFilter); // Refresh the filter set of the filter target _currentTarget.filters = _currentFilters; // Remove the current filter from the set // (This doesn't remove it from the filter target, since // the target uses a copy of the filters array internally.) _currentFilters.pop(); }

A aplicao do filtro no objeto de exibio ocorre no mtodo applyTemporaryFilter(). Primeiro, o controlador recupera uma referncia ao objeto de filtro chamando o mtodo getFilter() da fbrica de filtro.
var currentFilter:BitmapFilter = _filterFactory.getFilter();

A ocorrncia do controlador tem uma varivel da ocorrncia de Array chamada _currentFilters, na qual so armazenados todos os filtros que foram aplicados no objeto de exibio. A prxima etapa adicionar o filtro recm atualizado a essa matriz:
_currentFilters.push(currentFilter);

Em seguida, o cdigo atribui a matriz dos filtros propriedade filters do objeto de exibio, que realmente aplica os filtros na imagem:
_currentTarget.filters = _currentFilters;

Finalmente, como esse filtro adicionado recentemente ainda o filtro de trabalho, ele no deve ser aplicado permanentemente no objeto de exibio e, por isso, removido da matriz _currentFilters:
_currentFilters.pop();

A remoo desse filtro da matriz no afeta o objeto de exibio filtrado porque um objeto de exibio cria uma cpia da matriz de filtros quando esta atribuda propriedade filters e usa essa matriz interna em vez da original. Desse modo, todas as alteraes feitas na matriz dos filtros no afetam o objeto de exibio at que a matriz seja novamente atribuda propriedade filters do objeto de exibio.

ltima atualizao em 29/3/2011

293

Captulo 14: Trabalho com sombreadores Pixel Bender

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior O Adobe Pixel Bender Toolkit permite que os desenvolvedores gravem sombreadores para criar efeitos grficos e executar outro processamento de imagem e dados. O cdigo de bytes do Pixel Bender pode ser executado no ActionScript para aplicar o efeito aos dados da imagem ou ao contedo visual. O uso de sombreadores Pixel Bender no ActionScript fornece a capacidade de criar efeitos visuais personalizados e de executar processamento de dados alm dos recursos internos do ActionScript. Nota: O suporte para Pixel Bender foi disponibilizado a partir do Flash Player 10 e do Adobe AIR 1.5. Mesclagens, filtros e preenchimentos do Pixel Bender no contam com suporte quando a renderizao feita pela GPU.

Mais tpicos da Ajuda

Centro de tecnologia do Adobe Pixel Bender Guia do desenvolvedor do Pixel Bender Referncia do Pixel Bender flash.display.Shader flash.filters.ShaderFilter Introduo ao Pixel Bender para Flash Introduo ao Pixel Bender para Flex

Noes bsicas de sombreadores Pixel Bender

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior O Adobe Pixel Bender uma linguagem de programao utilizada para criar ou manipular contedo de imagem. Usando o Pixel Bender, voc criar um kernel, tambm conhecido como sombreador. O sombreador define uma nica funo executada individualmente em cada pixel de uma imagem. O resultado de cada chamada funo a cor gerada nessa coordenada de pixel da imagem. possvel especificar valores de imagens e parmetros de entrada para personalizar a operao. Em uma nica execuo de um sombreador, os valores de entrada e parmetro so constantes. A nica coisa varivel a coordenada do pixel cuja cor o resultado da chamada funo. Quando possvel, a funo de sombreador chamada para vrias coordenadas de pixel de sada em paralelo. Isso melhora o desempenho do sombreador e pode oferecer processamento de alto desempenho. No ActionScript, trs tipos de efeitos podem ser facilmente criados com um sombreador:

preenchimento de desenho modo de mesclagem filtro

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sombreadores Pixel Bender

294

Tambm possvel executar um sombreador no modo autnomo. No modo autnomo, o resultado de um sombreador acessado diretamente, sem a necessidade de especificar previamente seu uso pretendido. possvel acessar o resultado como dados de imagem ou como dados binrios ou numricos. No necessrio que os dados sejam dados de imagem. Dessa forma, voc pode atribuir a um sombreador um conjunto de dados como entrada. O sombreador processa os dados, e voc pode acessar o resultado retornado por ele. O suporte para Pixel Bender foi disponibilizado a partir do Flash Player 10 e do Adobe AIR 1.5. Mesclagens, filtros e preenchimentos do Pixel Bender no contam com suporte quando a renderizao feita pela GPU. Em dispositivos mveis, os sombreadores Pixel Bender so executados com renderizao pela CPU. No entanto, o desempenho no do mesmo nvel de um computador desktop. Muitos programas sombreadores podem executar somente alguns quadros por segundo. Conceitos e termos importantes A lista de referncia a seguir contm termos importantes que voc vai encontrar ao criar e usar os sombreadores do Pixel Bender:
Kernel No Pixel Bender, um kernel o mesmo que um sombreador. Usando o Pixel Bender, seu cdigo define um kernel, que por sua vez define uma nica funo que executada individualmente em cada pixel de uma imagem. Cdigo de bytes do Pixel Bender Um kernel do Pixel Bender transformado em cdigo de bytes do Pixel Bender. O

cdigo de bytes acessado e executado no tempo de execuo.

Linguagem Pixel Bender A linguagem de programao usada para criar um kernel do Pixel Bender. Toolkit do Pixel Bender O aplicativo usado para criar um arquivo de cdigo de bytes do Pixel Bender com base no cdigo-fonte do Pixel Bender. O kit de ferramentas permite programar, testar e compilar o cdigo-fonte do Pixel Bender. Shader Neste documento, um sombreador um conjunto de funcionalidades criado na linguagem Pixel Bender. O

cdigo de um sombreador cria um efeito visual ou executa um clculo. Em qualquer um dos casos, o sombreador retorna um conjunto de dados (normalmente, os pixels de uma imagem). O sombreador realiza a mesma operao em cada ponto de dados, com a nica diferena sendo as coordenadas do pixel de sada. O sombreador no escrito em ActionScript. Ele criado na linguagem Pixel Bender e compilado no cdigo de bytes do Pixel Bender. Ele pode ser incorporado a um arquivo SWF em tempo de compilao ou carregado como arquivo externo em tempo de execuo. Nos dois casos, ele acessado no ActionScript atravs da criao de um objeto Shader e da vinculao deste ao cdigo de bytes do sombreador.
Entrada do sombreador Uma entrada complexa, geralmente dados de imagem de bitmap, fornecida para um

sombreador para uso em seus clculos. Para cada varivel de entrada definida em um sombreador, usado um nico valor (isto , uma nica imagem ou um conjunto de dados binrios) para a execuo inteira do sombreador.
Parmetro de sombreador Um nico valor (ou conjunto limitado de valores) que fornecido para um sombreador us-lo em seus clculos. Cada valor de parmetro definido para uma nica execuo do sombreador, e o mesmo valor usado durante toda a execuo.

Teste por meio dos exemplos de cdigo Talvez voc queira testar as listagens do cdigo de exemplo que so fornecidas. Testar o cdigo envolve execut-lo e ver os resultados no SWF que criado. Todos os exemplos criam contedo usando a API de desenho que utiliza ou modificada pelo efeito de sombreador.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sombreadores Pixel Bender

295

A maioria das listagens de cdigo de exemplo tm duas partes. Uma parte o cdigo-fonte do Pixel Bender referente ao sombreador usado no exemplo. Primeiro voc deve usar o Pixel Bender Toolkit para compilar o cdigo-fonte em um arquivo de cdigo de bytes do Pixel Bender. Siga estas etapas para criar o arquivo de cdigo de bytes do Pixel Bender:
1 Abra o Adobe Pixel Bender Toolkit. Se necessrio, no menu Criar, escolha Ativar avisos e erros do Flash Player. 2 Copie a listagem de cdigo do Pixel Bender e cole-a no painel do editor de cdigo do Pixel Bender Toolkit. 3 No menu Arquivo, escolha Exportar filtro de kernel do Flash Player. 4 Salve o arquivo do cdigo de bytes do Pixel Bender no mesmo diretrio que o documento do Flash. O nome do

arquivo deve ser igual ao nome especificado na descrio do exemplo. A parte do ActionScript de cada exemplo escrita como arquivo de classe. Execute as etapas a seguir par testar o exemplo no Flash Professional:
1 Crie um documento do Flash vazio e salve-o no seu computador. 2 Crie e salve um novo arquivo do ActionScript no mesmo diretrio do documento Flash. O nome do arquivo deve

corresponder ao nome da classe na listagem de cdigo. Por exemplo, se a listagem de cdigo define uma classe chamada MyApplication, use o nome MyApplication.as para salvar o arquivo do ActionScript.
3 Copie a listagem de cdigo no arquivo do ActionScript e salve o arquivo. 4 No documento Flash, clique em uma parte em branco do Palco ou espao de trabalho para ativar o Inspetor de

propriedades do documento.
5 No Inspetor de propriedades, no campo Classe do documento, digite o nome da classe ActionScript que voc

copiou do texto.
6 Execute o programa usando Controlar > Testar filme

Voc ver os resultados do exemplo na janela de visualizao. As tcnicas para testar listas de cdigo de exemplo so explicadas em mais detalhes em Como Usar Exemplos do ActionScript na pgina 1085.

Carregamento ou incorporao de um sombreador

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior A primeira etapa do uso de um sombreador Pixel Bender no ActionScript obter acesso ao sombreador no seu cdigo ActionScript. Como um sombreador criado usando o Adobe Pixel Bender Toolkit e gravado na linguagem Pixel Bender, ele no pode ser acessado diretamente no ActionScript. Em vez disso, crie uma ocorrncia da classe Shader que represente o sombreador Pixel Bender para o ActionScript. O objeto Shader permite localizar informaes sobre o sombreador, como por exemplo, se ele espera parmetros ou valores da imagem de entrada. Voc passa o objeto Shader para outros objetos para realmente usar o sombreador. Por exemplo, para usar o sombreador como um filtro, voc atribui o objeto Shader propriedade shader de um objeto ShaderFilter. Como alternativa, para usar o sombreador como um preenchimento de desenho, voc passa o objeto Shader como um argumento para o mtodo Graphics.beginShaderFill().

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sombreadores Pixel Bender

296

Seu cdigo ActionScript pode acessar um sombreador criado pelo Adobe Pixel Bender Toolkit (um arquivo .pbj) de duas maneiras:

Carregado em tempo de execuo: o arquivo sombreador pode ser carregado como um ativo externo usando um
objeto URLLoader. Essa tcnica semelhante ao carregamento de um ativo externo, como um arquivo de texto. O exemplo a seguir demonstra o carregamento de um arquivo de cdigo de bytes do sombreador em tempo de execuo e sua vinculao com uma ocorrncia de Shader:
var loader:URLLoader = new URLLoader(); loader.dataFormat = URLLoaderDataFormat.BINARY; loader.addEventListener(Event.COMPLETE, onLoadComplete); loader.load(new URLRequest("myShader.pbj")); var shader:Shader; function onLoadComplete(event:Event):void { // Create a new shader and set the loaded data as its bytecode shader = new Shader(); shader.byteCode = loader.data; // You can also pass the bytecode to the Shader() constructor like this: // shader = new Shader(loader.data); // do something with the shader }

Incorporado no arquivo SWF: o arquivo sombreador pode ser incorporado no arquivo SWF em tempo de
compilao usando a tag de metadados [Embed]. A tag de metadados [Embed] fica disponvel somente se voc usar o SDK do Flex para compilar o arquivo SWF. O parmetro source da tag [Embed] aponta para o arquivo sombreador, e seu parmetro mimeType o "application/octet-stream", como neste exemplo:
[Embed(source="myShader.pbj", mimeType="application/octet-stream")] var MyShaderClass:Class; // ... // create a shader and set the embedded shader as its bytecode var shader:Shader = new Shader(); shader.byteCode = new MyShaderClass(); // You can also pass the bytecode to the Shader() constructor like this: // var shader:Shader = new Shader(new MyShaderClass()); // do something with the shader

Nos dois casos, voc vincula o cdigo de bytes brutos do sombreador (a propriedade URLLoader.data ou uma ocorrncia da classe de dados [Embed]) com a ocorrncia de Shader. Como demonstram os exemplos anteriores, voc pode atribuir o cdigo de bytes ocorrncia de Shader de duas maneiras. Voc pode passar o cdigo de bytes do sombreador como um argumento para o construtor Shader(). Voc tambm pode defini-lo como a propriedade byteCode da ocorrncia de Shader. Depois que um sombreador Pixel Bender foi criado e vinculado com um objeto Shader, voc pode us-lo para criar efeitos de vrias maneiras. Pode us-lo como um filtro, um modo de mesclagem, um preenchimento bitmap ou para processamento autnomo de bitmap ou de outros dados. Voc tambm pode usar a propriedade data do objeto Shader para acessar os metadados de sombreador, especificar imagens de entrada e definir valores de parmetros.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sombreadores Pixel Bender

297

Acesso aos metadados de sombreador

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Ao criar um kernel de sombreador Pixel Bender, o autor pode especificar metadados sobre o sombreador no cdigo fonte Pixel Bender. Ao usar um sombreador no ActionScript, voc pode examin-lo e extrair seus metadados. Ao criar uma ocorrncia de Shader e vincul-la a um sombreador Pixel Bender, um objeto ShaderData que contm dados sobre o sombreador criado e armazenado na propriedade data do objeto Shader. A classe ShaderData no define nenhuma propriedade prpria. No entanto, em tempo de execuo uma propriedade adicionada dinamicamente ao objeto ShaderData para cada valor de metadados definido no cdigo fonte do sombreador. O nome fornecido a cada propriedade igual ao nome especificado nos metadados. Por exemplo, suponha que o cdigo fonte de um sombreador Pixel Bender inclua a seguinte definio de metadados:
namespace : "Adobe::Example"; vendor : "Bob Jones"; version : 1; description : "Creates a version of the specified image with the specified brightness.";

O objeto ShaderData criado para esse sombreador criado com as seguintes propriedades e valores:

namespace (String): "Adobe::Example" vendor (String): "Bob Jones" version (String): "1" description (String): "Cria uma verso da imagem especificada com o brilho especificado"

Como as propriedades de metadados so adicionadas dinamicamente ao objeto ShaderData, voc pode usar um loop for..in para examinar o objeto ShaderData. Usando essa tcnica possvel descobrir se o sombreador tem algum metadado e quais so os seus valores. Alm das propriedades de metadados, um objeto ShaderData pode ter propriedades que representam entradas e parmetros definidos no sombreador. Ao usar um loop for..in para examinar um objeto ShaderData, verifique o tipo de dados de cada propriedade para determinar se a propriedade uma entrada (uma ocorrncia de ShaderInput), um parmetro (uma ocorrncia de ShaderParameter) ou um valor de metadados (uma ocorrncia de String). O exemplo a seguir mostra como usar um loop for..in para examinar as propriedades dinmicas da propriedade data de um sombreador. Cada valor de metadados adicionado a uma ocorrncia de Vector denominada metadata. Observe que este exemplo pressupe que uma ocorrncia de Shader denominada myShader j foi criada:
var shaderData:ShaderData = myShader.data; var metadata:Vector.<String> = new Vector.<String>(); for (var prop:String in shaderData) { if (!(shaderData[prop] is ShaderInput) && !(shaderData[prop] is ShaderParameter)) { metadata[metadata.length] = shaderData[prop]; } } // do something with the metadata

Para obter uma verso desse exemplo que tambm extrai entradas e parmetros de sombreador, consulte Identificao de entradas e parmetros de sombreador na pgina 298. Para obter mais informaes sobre propriedades de entrada e parmetro, consulte Especificao de valores de entrada e de parmetro de sombreador na pgina 298.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sombreadores Pixel Bender

298

Especificao de valores de entrada e de parmetro de sombreador

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Muitos sombreadores Pixel Bender so definidos para usar uma ou mais imagens de entrada que so usadas no processamento do sombreador. Por exemplo, comum um sombreador aceitar uma imagem de origem e produzi-la com um efeito especfico aplicado a ela. Dependendo de como o sombreador usado, o valor de entrada pode ser especificado automaticamente ou voc pode precisar fornecer um valor explicitamente. De modo semelhante, muitos sombreadores especificam parmetros que so usados para personalizar a sada do sombreador. Voc tambm deve definir explicitamente um valor para cada parmetro antes de usar o sombreador. Voc usa a propriedade data do objeto Shader para definir entradas e parmetros do sombreador e para determinar se um sombreador especfico espera entradas ou parmetros. A propriedade data uma ocorrncia de ShaderData.

Identificao de entradas e parmetros de sombreador

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior A primeira etapa da especificao de valores de entrada e de parmetro de sombreador descobrir se o sombreador especfico que voc est usando espera qualquer imagem ou parmetro de entrada. Cada ocorrncia de Shader tem uma propriedade data que contm um objeto ShaderData. Se o sombreador definir quaisquer entradas ou parmetros, eles sero acessados como propriedades desse objeto ShaderData. Os nomes de propriedades correspondem aos nomes especificados para as entradas e parmetros no cdigo fonte do sombreador. Por exemplo, se um sombreador definir uma entrada denominada src, o objeto ShaderData ter uma propriedade denominada src que representa essa entrada. Cada propriedade que representa uma entrada uma ocorrncia de ShaderInput, e cada propriedade que representa um parmetro uma ocorrncia de ShaderParameter. O ideal que o autor do sombreador fornea documentao do sombreador, indicando quais valores de imagens de entrada e de parmetros o sombreador espera, o que eles representam, os valores apropriados, e assim por diante. No entanto, se o sombreador no estiver documentado (e voc no tiver seu cdigo fonte), voc poder inspecionar os dados do sombreador para identificar as entradas e parmetros. As propriedades que representam entradas e parmetros so adicionadas dinamicamente ao objeto ShaderData. Conseqentemente, voc pode usar um loop for..in para examinar o objeto ShaderData para descobrir se o sombreador associado define quaisquer entradas ou parmetros. Conforme descrito em Acesso aos metadados de sombreador na pgina 297, qualquer valor de metadados definido para um sombreador tambm acessado como uma propriedade dinmica adicionada propriedade Shader.data. Ao usar essa tcnica para identificar entradas e parmetros de sombreador, verifique o tipo de dados das propriedades dinmicas. Se uma propriedade for uma ocorrncia de ShaderInput, ela representar uma entrada. Se ela for uma ocorrncia de ShaderParameter, ela representar um parmetro. Caso contrrio, ela ser um valor de metadados. O exemplo a seguir mostra como usar um loop for..in para examinar as propriedades dinmicas da propriedade data de um sombreador. Cada entrada (objeto ShaderInput) adicionada a uma ocorrncia de Vector denominada inputs. Cada parmetro (objeto ShaderParameter) adicionado a uma ocorrncia de Vector denominada parameters. Finalmente, quaisquer propriedades de metadados so adicionadas a uma ocorrncia de Vector denominada metadata. Observe que este exemplo pressupe que uma ocorrncia de Shader denominada myShader j foi criada:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sombreadores Pixel Bender

299

var var var var

shaderData:ShaderData = myShader.data; inputs:Vector.<ShaderInput> = new Vector.<ShaderInput>(); parameters:Vector.<ShaderParameter> = new Vector.<ShaderParameter>(); metadata:Vector.<String> = new Vector.<String>();

for (var prop:String in shaderData) { if (shaderData[prop] is ShaderInput) { inputs[inputs.length] = shaderData[prop]; } else if (shaderData[prop] is ShaderParameter) { parameters[parameters.length] = shaderData[prop]; } else { metadata[metadata.length] = shaderData[prop]; } } // do something with the inputs or properties

Especificao de valores de entrada de sombreador

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Muitos sombreadores esperam uma ou mais imagens de entrada que so usadas no processamento do sombreador. No entanto, em muitos casos, uma entrada especificada automaticamente quando o objeto Shader usado. Por exemplo, suponha que um sombreador exija uma entrada e seja usado como um filtro. Quando o filtro aplicado a um objeto de exibio ou a um objeto BitmapData, esse objeto definido automaticamente como a entrada. Nesse caso voc no define explicitamente um valor de entrada. No entanto, em alguns casos, especialmente se um sombreador definir vrias entradas, voc definir explicitamente um valor para uma entrada. Cada entrada definida em um sombreador representada no ActionScript por um objeto ShaderInput. O objeto ShaderInput uma propriedade da ocorrncia de ShaderData na propriedade data do objeto Shader, conforme descrito em Identificao de entradas e parmetros de sombreador na pgina 298. Por exemplo, suponha que um sombreador defina uma entrada denominada src e que o sombreador esteja vinculado a um objeto Shader denominado myShader. Nesse caso, voc acessa o objeto ShaderInput que corresponde entrada src usando o seguinte identificador:
myShader.data.src

Cada objeto ShaderInput tem uma propriedade input usada para definir o valor da entrada. Voc define a propriedade input como uma ocorrncia de BitmapData para especificar dados da imagem. Tambm pode definir a propriedade input como uma ocorrncia de BitmapData ou Vector.<Nmero> para especificar dados binrios ou numricos. Para obter detalhes e restries sobre o uso de uma ocorrncia de BitmapData ou Vector.Para instncia <Number> como entrada, consulte a lista ShaderInput.input em Referncia do ActionScript 3.0 para a plataforma Adobe Flash.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sombreadores Pixel Bender

300

Alm da propriedade input, um objeto ShaderInput tem propriedades que podem ser usadas para determinar qual tipo de imagem a entrada espera. Essas propriedades incluem as propriedades width, height e channels. Cada objeto ShaderInput tambm tem uma propriedade index que til para determinar se um valor explcito deve ser fornecido para a entrada. Se um sombreador esperar mais entradas do que o nmero definido automaticamente, defina valores para essas entradas. Para obter detalhes sobre as diferentes maneiras de uso de um sombreador, e se os valores de entrada so definidos automaticamente, consulte Uso de um sombreador na pgina 303.

Especificao de valores de parmetros de sombreador

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Alguns sombreadores definem valores de parmetros que o sombreador usa para criar seu resultado. Por exemplo, um sombreador que altera o brilho de uma imagem pode especificar um parmetro de brilho que determina o quanto a operao afeta o brilho. Um nico parmetro definido em um sombreador pode esperar um nico valor ou vrios valores, de acordo com a definio do parmetro no sombreador. Cada parmetro definido em um sombreador representado no ActionScript por um objeto ShaderParameter. O objeto ShaderParameter uma propriedade da ocorrncia de ShaderData na propriedade de dados do objeto Shader, conforme descrito em Identificao de entradas e parmetros de sombreador na pgina 298. Por exemplo, suponha que um sombreador defina um parmetro denominado brightness e que o sombreador esteja representado por um objeto Shader denominado myShader. Nesse caso, voc acessa o ShaderParameter que corresponde ao parmetro brightness usando o seguinte identificador:
myShader.data.brightness

Para definir um ou mais valores para o parmetro, crie uma matriz do ActionScript que contenha o valor ou valores e atribua essa matriz propriedade value do objeto ShaderParameter. A propriedade value definida como uma ocorrncia de Array porque possvel que um nico parmetro do sombreador exija vrios valores. Mesmo que o parmetro do sombreador espere um nico valor, voc deve delimitar o valor em um objeto Array para atribu-lo propriedade ShaderParameter.value. A listagem a seguir demonstra como definir um nico valor como a propriedade value:
myShader.data.brightness.value = [75];

Se o cdigo-fonte de Pixel Bender do sombreador definir um valor padro para o parmetro, uma matriz que contm o valor ou valores padro ser criada e atribuda propriedade value do objeto ShaderParameter quando o objeto Shader for criado. Depois que a matriz for atribuda propriedade value (inclusive se ela for a matriz padro), o valor do parmetro poder ser alterado com a alterao do valor do elemento de matriz. Voc no precisa criar uma nova matriz e atribu-la propriedade value. O exemplo a seguir demonstra a configurao de um valor do parmetro do sombreador no ActionScript. Neste exemplo o sombreador define um parmetro denominado color. O parmetro color declarado como uma varivel float4 no cdigo-fonte do Pixel Bender, o que significa que ela uma matriz de quatro nmeros de ponto flutuante. No exemplo, o valor do parmetro color alterado continuamente e, cada vez que ele alterado, o sombreador usado para desenhar um retngulo colorido na tela. O resultado uma alterao de cor animada. Nota: O cdigo para este exemplo foi escrito por Ryan Taylor. Obrigado por compartilhar este exemplo, Ryan. Para ver o portflio de Ryan e ler seus artigos, acesse www.boostworthy.com/. O cdigo ActionScript est centralizado em torno de trs mtodos:

init(): no mtodo init(), o cdigo carrega o arquivo de cdigo de bytes do Pixel Bender que contm o

sombreador. Quando o arquivo carregado, o mtodo onLoadComplete() chamado.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sombreadores Pixel Bender

301

onLoadComplete(): no mtodo onLoadComplete(), o cdigo cria o objeto Shader chamado shader. Ele tambm

cria uma ocorrncia de Sprite chamada texture. No mtodo renderShader(), o cdigo desenha o resultado do sombreador em texture uma vez por quadro.

onEnterFrame(): o mtodo onEnterFrame() chamado uma vez por quadro, o que cria o efeito de animao.

Nesse mtodo, o cdigo define o valor do parmetro do sombreador como a nova cor e, em seguida, chama o mtodo renderShader() para desenhar o resultado do sombreador como um retngulo.

renderShader(): no mtodo renderShader(), o cdigo chama o mtodo Graphics.beginShaderFill() para

especificar um preenchimento do sombreador. Em seguida, ele desenha um retngulo cujo preenchimento definido pela sada do sombreador (a cor gerada). Para obter mais informaes sobre como usar um sombreador desta maneira, consulte Uso de um sombreador como um preenchimento de desenho na pgina 304. Veja abaixo o cdigo ActionScript para este exemplo. Use esta classe com a classe de aplicativo principal em um projeto somente ActionScript no Flash Builder ou como a classe do documento para o arquivo FLA no Flash Professional:
package { import import import import import import

flash.display.Shader; flash.display.Sprite; flash.events.Event; flash.net.URLLoader; flash.net.URLLoaderDataFormat; flash.net.URLRequest;

public class ColorFilterExample extends Sprite { private const DELTA_OFFSET:Number = Math.PI * 0.5; private var loader:URLLoader; private var shader:Shader; private var texture:Sprite; private var delta:Number = 0; public function ColorFilterExample() { init(); } private function init():void { loader = new URLLoader(); loader.dataFormat = URLLoaderDataFormat.BINARY; loader.addEventListener(Event.COMPLETE, onLoadComplete); loader.load(new URLRequest("ColorFilter.pbj")); } private function onLoadComplete(event:Event):void { shader = new Shader(loader.data); texture = new Sprite(); addChild(texture); addEventListener(Event.ENTER_FRAME, onEnterFrame); } private function onEnterFrame(event:Event):void

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sombreadores Pixel Bender

302

{ shader.data.color.value[0] = 0.5 + Math.cos(delta - DELTA_OFFSET) * 0.5; shader.data.color.value[1] = 0.5 + Math.cos(delta) * 0.5; shader.data.color.value[2] = 0.5 + Math.cos(delta + DELTA_OFFSET) * 0.5; // The alpha channel value (index 3) is set to 1 by the kernel's default // value. This value doesn't need to change. delta += 0.1; renderShader(); } private function renderShader():void { texture:graphics.clear(); texture.graphics.beginShaderFill(shader); texture.graphics.drawRect(0, 0, stage.stageWidth, stage.stageHeight); texture.graphics.endFill(); } } }

Este o cdigo-fonte para o kernel de sombreador ColorFilter, usado para criar o arquivo de cdigo de bytes do Pixel Bender ColorFilter.pbj:
<languageVersion : 1.0;> kernel ColorFilter < namespace : "boostworthy::Example"; vendor : "Ryan Taylor"; version : 1; description : "Creates an image where every pixel has the specified color value."; > { output pixel4 result; parameter float4 color < minValue:float4(0, 0, 0, 0); maxValue:float4(1, 1, 1, 1); defaultValue:float4(0, 0, 0, 1); >; void evaluatePixel() { result = color; } }

Se voc estiver usando um sombreador cujos parmetros no esto documentados, poder calcular quantos elementos de qual tipo devem ser includos na matriz, marcando a propriedade type do objeto ShaderParameter. A propriedade type indica o tipo de dado do parmetro, conforme definido no prprio sombreador. Para obter uma lista de nmeros e tipos de elementos esperados por cada tipo de parmetro, consulte a listagem da propriedade ShaderParameter.value na Referncia do ActionScript 3.0.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sombreadores Pixel Bender

303

Cada objeto ShaderParameter tambm tem uma propriedade index que indica onde o parmetro se ajusta na ordem dos parmetros do sombreador. Alm dessas propriedades, um objeto ShaderParameter pode ter propriedades adicionais que contm valores de metadados fornecidos pelo autor do sombreador. Por exemplo, o autor pode especificar valores de metadados, como valores mnimos, mximos e padro para um parmetro. Todos os valores de metadados especificados pelo autor so adicionados ao objeto ShaderParameter como propriedades dinmicas. Para examinar essas propriedades, use um loop for..in para executar um loop nas propriedades dinmicas do objeto ShaderParameter para identificar seus metadados. O exemplo a seguir mostra como usar um loop for..in para identificar metadados de um objeto ShaderParameter. Cada valor de metadados adicionado a uma ocorrncia de Vector denominada metadata. Observe que este exemplo pressupe que uma ocorrncia de Shader denominada myShader j foi criada, e que conhecida como tendo um parmetro denominado brightness:
var brightness:ShaderParameter = myShader.data.brightness; var metadata:Vector.<String> = new Vector.<String>(); for (var prop:String in brightness) { if (brightness[prop] is String) { metadata[metadata.length] = brightness[prop]; } } // do something with the metadata

Uso de um sombreador
Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Depois que o sombreador Pixel Bender est disponvel no ActionScript como um objeto Shader, ele pode ser usado de vrias maneiras:

Preenchimento de desenho do sombreador: O sombreador define a parte de preenchimento de uma forma

desenhada usando a API de desenho

Modo de mesclagem: O sombreador define a mesclagem entre dois objetos de exibio sobrepostos Filtro: O sombreador define um filtro que modifica a aparncia do contedo visual Processamento autnomo do sombreador: O processamento do sombreador executado sem especificar o uso
pretendido da sada. Como opo, o sombreador pode ser executado no plano de fundo, com o resultado disponvel quando o processamento concludo. Essa tcnica pode ser usada para gerar dados de bitmap e tambm para processar dados no visuais.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sombreadores Pixel Bender

304

Uso de um sombreador como um preenchimento de desenho

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Ao usar um sombreador para criar um preenchimento de desenho, voc deve utilizar os mtodos de API de desenho para criar uma forma vetorial. A sada do sombreador usada para preencher a forma, da mesma maneira que se pode usar qualquer imagem de bitmap como preenchimento de bitmap com a API de desenho. Para criar um preenchimento de sombreador, no ponto do cdigo em que voc deseja comear a desenhar a forma, chame o mtodo beginShaderFill() do objeto Graphics. Passe o objeto Shader como o primeiro argumento do mtodo beginShaderFill(), conforme mostrado nesta listagem:
var canvas:Sprite = new Sprite(); canvas.graphics.beginShaderFill(myShader); canvas.graphics.drawRect(10, 10, 150, 150); canvas.graphics.endFill(); // add canvas to the display list to see the result

Quando voc usa um sombreador como preenchimento de desenho, deve definir quaisquer valores de imagem de entrada e valores de parmetro exigidos pelo sombreador. O exemplo a seguir demonstra o uso de um sombreador como preenchimento de desenho. Neste exemplo, o sombreador cria um gradiente de trs pontas. Esse gradiente tem trs cores, cada uma na ponta de um tringulo, com uma mesclagem de gradiente entre elas. Alm disso, as cores se revezam para criar um efeito animado de cores girando.

Nota: O cdigo deste exemplo foi escrito por Petri Leskinen. Obrigado por compartilhar este exemplo, Petri. Para ver mais exemplos e tutoriais de Petri, acesse http://pixelero.wordpress.com/. O cdigo ActionScript est baseado em trs mtodos:

init(): o mtodo init() chamado quando o aplicativo carregado. Neste mtodo, o cdigo define os valores

iniciais dos objetos Point que representam as pontas do tringulo. O cdigo tambm cria uma ocorrncia de Sprite chamada canvas. Posteriormente, no mtodo updateShaderFill(), o cdigo desenha o resultado do sombreador em canvas uma vez por quadro. Por ltimo, o cdigo carrega o arquivo de cdigo de bytes do sombreador.

onLoadComplete(): no mtodo onLoadComplete(), o cdigo cria o objeto Shader chamado shader. Ele tambm

define os valores de parmetro iniciais. Para terminar, o cdigo adiciona o mtodo updateShaderFill() como um ouvinte do evento enterFrame, o que significa que ele chamado uma vez por quadro para criar um efeito de animao.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sombreadores Pixel Bender

305

updateShaderFill(): o mtodo updateShaderFill() chamado uma vez por quadro, o que cria o efeito de animao. Neste mtodo, o cdigo calcula e define os valores dos parmetros do sombreador. O cdigo ento chama o mtodo beginShaderFill() para criar um preenchimento de sombreador e chama outros mtodos de API de desenho para desenhar o resultado do sombreador em um tringulo.

Veja abaixo o cdigo ActionScript para este exemplo. Use esta classe com a classe de aplicativo principal em um projeto somente ActionScript no Flash Builder ou como a classe do documento para um arquivo FLA no Flash Professional:
package { import import import import import import import

flash.display.Shader; flash.display.Sprite; flash.events.Event; flash.geom.Point; flash.net.URLLoader; flash.net.URLLoaderDataFormat; flash.net.URLRequest;

public class ThreePointGradient extends Sprite { private var canvas:Sprite; private var shader:Shader; private var loader:URLLoader; private var topMiddle:Point; private var bottomLeft:Point; private var bottomRight:Point; private var colorAngle:Number = 0.0; private const d120:Number = 120 / 180 * Math.PI; // 120 degrees in radians

public function ThreePointGradient() { init(); } private function init():void { canvas = new Sprite(); addChild(canvas); var size:int = 400; topMiddle = new Point(size / 2, 10); bottomLeft = new Point(0, size - 10); bottomRight = new Point(size, size - 10); loader = new URLLoader(); loader.dataFormat = URLLoaderDataFormat.BINARY; loader.addEventListener(Event.COMPLETE, onLoadComplete); loader.load(new URLRequest("ThreePointGradient.pbj")); } private function onLoadComplete(event:Event):void { shader = new Shader(loader.data);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sombreadores Pixel Bender

306

shader.data.point1.value = [topMiddle.x, topMiddle.y]; shader.data.point2.value = [bottomLeft.x, bottomLeft.y]; shader.data.point3.value = [bottomRight.x, bottomRight.y]; addEventListener(Event.ENTER_FRAME, updateShaderFill); } private function updateShaderFill(event:Event):void { colorAngle += .06; var c1:Number = 1 / 3 + 2 / 3 * Math.cos(colorAngle); var c2:Number = 1 / 3 + 2 / 3 * Math.cos(colorAngle + d120); var c3:Number = 1 / 3 + 2 / 3 * Math.cos(colorAngle - d120); shader.data.color1.value = [c1, c2, c3, 1.0]; shader.data.color2.value = [c3, c1, c2, 1.0]; shader.data.color3.value = [c2, c3, c1, 1.0]; canvas.graphics.clear(); canvas.graphics.beginShaderFill(shader); canvas.graphics.moveTo(topMiddle.x, topMiddle.y); canvas.graphics.lineTo(bottomLeft.x, bottomLeft.y); canvas.graphics.lineTo(bottomRight.x, bottomLeft.y); canvas.graphics.endFill(); } } }

Este o cdigo-fonte do ncleo de sombreador ThreePointGradient, usado para criar o arquivo de cdigo de bytes do Pixel Bender ThreePointGradient.pbj:
<languageVersion : 1.0;> kernel ThreePointGradient < namespace : "Petri Leskinen::Example"; vendor : "Petri Leskinen"; version : 1; description : "Creates a gradient fill using three specified points and colors."; > { parameter float2 point1 // coordinates of the first point < minValue:float2(0, 0); maxValue:float2(4000, 4000); defaultValue:float2(0, 0); >; parameter float4 color1 // color at the first point, opaque red by default < defaultValue:float4(1.0, 0.0, 0.0, 1.0); >; parameter float2 point2 // coordinates of the second point <

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sombreadores Pixel Bender

307

minValue:float2(0, 0); maxValue:float2(4000, 4000); defaultValue:float2(0, 500); >; parameter float4 color2 // color at the second point, opaque green by default < defaultValue:float4(0.0, 1.0, 0.0, 1.0); >; parameter float2 point3 // coordinates of the third point < minValue:float2(0, 0); maxValue:float2(4000, 4000); defaultValue:float2(0, 500); >; parameter float4 color3 // color at the third point, opaque blue by default < defaultValue:float4(0.0, 0.0, 1.0, 1.0); >; output pixel4 dst; void evaluatePixel() { float2 d2 = point2 - point1; float2 d3 = point3 - point1; // transformation to a new coordinate system // transforms point 1 to origin, point2 to (1, 0), and point3 to (0, 1) float2x2 mtrx = float2x2(d3.y, -d2.y, -d3.x, d2.x) / (d2.x * d3.y - d3.x * d2.y); float2 pNew = mtrx * (outCoord() - point1); // repeat the edge colors on the outside pNew.xy = clamp(pNew.xy, 0.0, 1.0); // set the range to 0.0 ... 1.0 // interpolating the output color or alpha value dst = mix(mix(color1, color2, pNew.x), color3, pNew.y); } }

Nota: Se voc usar um preenchimento por sombreamento ao renderizar com a unidade de processamento grfico (GPU), a rea preenchida assumir a cor ciano. Para obter mais informaes sobre como desenhar formas usando a API de desenho, consulte Uso da API de desenho na pgina 214.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sombreadores Pixel Bender

308

Uso de um sombreador como modo de mesclagem

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior O uso de um sombreador como modo de mesclagem parecido com o uso de outros modos de mesclagem. O sombreador define a aparncia resultante da mesclagem visual de dois objetos de exibio. Para usar um sombreador como modo de mesclagem, atribua o objeto Shader propriedade blendShader do objeto de exibio em primeiro plano. A atribuio de um valor diferente de null propriedade blendShader automaticamente define a propriedade blendMode do objeto de exibio como BlendMode.SHADER. A listagem a seguir demonstra o uso de um sombreador como modo de mesclagem. Observe que este exemplo pressupe a existncia de um objeto de exibio chamado foreground contido no mesmo pai na lista de exibio que outro contedo de exibio, com foreground se sobrepondo ao outro contedo:
foreground.blendShader = myShader;

Quando voc usa um sombreador como modo de mesclagem, ele deve ser definido com pelo menos duas entradas. Como mostra o exemplo, voc no define os valores de entrada no cdigo. Em vez disso, as duas imagens mescladas so usadas automaticamente como entradas do sombreador. A imagem em primeiro plano definida como a segunda imagem. (Este o objeto de exibio ao qual o modo de mesclagem aplicado.) Uma imagem em segundo plano criada colocando-se a composio de todos os pixels atrs da caixa delimitadora da imagem em primeiro plano. Essa imagem em segundo plano definida como a primeira imagem de entrada. Se usar um sombreador que espera mais de duas entradas, especifique um valor para qualquer entrada alm das duas primeiras. O exemplo a seguir demonstra o uso de um sombreador como modo de mesclagem. Este exemplo utiliza um modo de mesclagem de clareamento baseado na luminosidade. O resultado da mesclagem que o valor de pixel mais claro de qualquer um dos objetos mesclados se torna o pixel que exibido. Nota: O cdigo deste exemplo foi escrito por Mario Klingemann. Obrigado por compartilhar este exemplo, Mario. Para conhecer mais sobre o trabalho de Mario e ler seus artigos, acesse www.quasimondo.com/. O cdigo ActionScript importante est nestes dois mtodos:

init(): o mtodo init() chamado quando o aplicativo carregado. Neste mtodo, o cdigo carrega o arquivo

de cdigo de bytes do sombreador.

onLoadComplete(): no mtodo onLoadComplete(), o cdigo cria o objeto Shader chamado shader. Em seguida, ele desenha trs objetos. O primeiro, backdrop, um plano de fundo cinza escuro atrs de objetos mesclados. O segundo, backgroundShape, uma elipse gradiente verde. O terceiro objeto, foregroundShape, uma elipse gradiente cor de laranja.

A elipse foregroundShape o objeto de primeiro plano da mesclagem. A imagem de fundo da mesclagem formada pela parte de backdrop e pela parte de backgroundShape que so sobrepostas pela caixa delimitadora do objeto foregroundShape. O objeto foregroundShape o objeto mais frente na lista de exibio. Ele se sobrepe parcialmente a backgroundShape e completamente a backdrop. Por causa dessa sobreposio, sem um modo de mesclagem aplicado, a elipse laranja (foregroundShape) exibida por completo e parte da elipse verde (backgroundShape) ocultada por ela:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sombreadores Pixel Bender

309

No entanto, com o modo de mesclagem aplicado, a parte mais brilhante da elipse verde transparece porque mais clara do que a parte de foregroundShape que se sobrepe a ela:

Veja abaixo o cdigo ActionScript para este exemplo. Use esta classe com a classe de aplicativo principal em um projeto somente ActionScript no Flash Builder ou como a classe do documento para o arquivo FLA no Flash Professional:
package { import import import import import import import import import import import

flash.display.BlendMode; flash.display.GradientType; flash.display.Graphics; flash.display.Shader; flash.display.Shape; flash.display.Sprite; flash.events.Event; flash.geom.Matrix; flash.net.URLLoader; flash.net.URLLoaderDataFormat; flash.net.URLRequest;

public class LumaLighten extends Sprite { private var shader:Shader; private var loader:URLLoader; public function LumaLighten() { init(); } private function init():void { loader = new URLLoader(); loader.dataFormat = URLLoaderDataFormat.BINARY; loader.addEventListener(Event.COMPLETE, onLoadComplete); loader.load(new URLRequest("LumaLighten.pbj")); }

private function onLoadComplete(event:Event):void { shader = new Shader(loader.data); var backdrop:Shape = new Shape(); var g0:Graphics = backdrop.graphics; g0.beginFill(0x303030);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sombreadores Pixel Bender

310

g0.drawRect(0, 0, 400, 200); g0.endFill(); addChild(backdrop); var backgroundShape:Shape = new Shape(); var g1:Graphics = backgroundShape.graphics; var c1:Array = [0x336600, 0x80ff00]; var a1:Array = [255, 255]; var r1:Array = [100, 255]; var m1:Matrix = new Matrix(); m1.createGradientBox(300, 200); g1.beginGradientFill(GradientType.LINEAR, c1, a1, r1, m1); g1.drawEllipse(0, 0, 300, 200); g1.endFill(); addChild(backgroundShape); var foregroundShape:Shape = new Shape(); var g2:Graphics = foregroundShape.graphics; var c2:Array = [0xff8000, 0x663300]; var a2:Array = [255, 255]; var r2:Array = [100, 255]; var m2:Matrix = new Matrix(); m2.createGradientBox(300, 200); g2.beginGradientFill(GradientType.LINEAR, c2, a2, r2, m2); g2.drawEllipse(100, 0, 300, 200); g2.endFill(); addChild(foregroundShape); foregroundShape.blendShader = shader; foregroundShape.blendMode = BlendMode.SHADER; } } }

Este o cdigo-fonte para o kernel de sombreador LumaLighten, usado para criar o arquivo de cdigo de bytes do Pixel Bender LumaLighten.pbj:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sombreadores Pixel Bender

311

<languageVersion : 1.0;> kernel LumaLighten < namespace : "com.quasimondo.blendModes"; vendor : "Quasimondo.com"; version : 1; description : "Luminance based lighten blend mode"; > { input image4 background; input image4 foreground; output pixel4 dst; const float3 LUMA = float3(0.212671, 0.715160, 0.072169); void evaluatePixel() { float4 a = sampleNearest(foreground, outCoord()); float4 b = sampleNearest(background, outCoord()); float luma_a = a.r * LUMA.r + a.g * LUMA.g + a.b * LUMA.b; float luma_b = b.r * LUMA.r + b.g * LUMA.g + b.b * LUMA.b; dst = luma_a > luma_b ? a : b; } }

Para obter mais informaes sobre como usar modos de mesclagem, consulte Aplicao de modos de mesclagem na pgina 179. Nota: Quando um programa Pixel Bender shader executado como mescla no Flash Player ou no AIR, as funes de amostragem e outCoord() comportam-se de forma diferente de outros contextos. Em uma mescla, a funo de amostragem sempre retornar o pixel atual avaliado pelo shader. Por exemplo, no possvel adicionar um deslocamento em outCoord() para criar uma amostra do pixel vizinho. Da mesma forma, se voc utilizar a funooutCoord() fora de uma funo de amostragem, as coordenadas sero avaliadas em 0. No possvel, por exemplo, utilizar a posio de um pixel para influenciar como as imagens mescladas sero combinadas.

Uso de um sombreador como filtro

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Usar um sombreador como filtro parecido com usar qualquer um dos outros filtros do ActionScript. Quando voc utiliza um sombreador como filtro, a imagem filtrada (um objeto de exibio ou objeto BitmapData) passada para ele. O sombreador usa a imagem de entrada para criar a sada do filtro, que geralmente uma verso modificada da imagem original. Se o objeto filtrado um objeto de exibio, a sada do sombreador exibida na tela no lugar do objeto de exibio filtrado. Se o objeto filtrado um objeto BitmapData, a sada do sombreador torna-se o contedo do objeto BitmapData cujo mtodo applyFilter() chamado. Para usar um sombreador como filtro, primeiro voc deve criar o objeto Shader conforme descrito em Carregamento ou incorporao de um sombreador na pgina 295. Em seguida, crie um objeto ShaderFilter vinculado ao objeto Shader. O objeto ShaderFilter o filtro aplicado ao objeto filtrado. Voc deve aplic-lo a um objeto da mesma maneira que aplica qualquer filtro. Passe-o para a propriedade filters de um objeto de exibio ou chame o mtodo applyFilter() em um objeto BitmapData. Por exemplo, o cdigo a seguir cria um objeto ShaderFilter e aplica o filtro a um objeto de exibio chamado homeButton.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sombreadores Pixel Bender

312

var myFilter:ShaderFilter = new ShaderFilter(myShader); homeButton.filters = [myFilter];

Quando voc usa um sombreador como filtro, o filtro deve ser definido com pelo menos uma entrada. Como mostra o exemplo, voc no define o valor de entrada no cdigo. Em vez disso, o objeto de exibio filtrado ou o objeto BitmapData definido como a imagem de entrada. Se usar um sombreador que espera mais de uma entrada, especifique um valor para qualquer entrada alm da primeira. Em alguns casos, um filtro altera as dimenses da imagem original. Por exemplo, um tpico efeito de sombra adiciona pixels extra contendo a sombra que acrescentada imagem. Quando usar um sombreador que altera as dimenses da imagem, defina as propriedades leftExtension, rightExtension, topExtension e bottomExtension para indicar em quanto voc deseja que o tamanho da imagem seja alterado. O exemplo a seguir demonstra o uso de um sombreador como filtro. O filtro deste exemplo inverte os valores de canal de vermelho, verde e azul de uma imagem. O resultado a verso negativa da imagem. Nota: O sombreador usado neste exemplo o kernel do Pixel Bender invertRGB.pbk fornecido com o Pixel Bender Toolkit. possvel carregar o cdigo-fonte do kernel a partir do diretrio de instalao do Pixel Bender Toolkit. Compile o cdigo-fonte e salve o arquivo de cdigo de bytes no mesmo diretrio do cdigo-fonte. O cdigo ActionScript importante est nestes dois mtodos:

init(): o mtodo init() chamado quando o aplicativo carregado. Neste mtodo, o cdigo carrega o arquivo

de cdigo de bytes do sombreador.

onLoadComplete(): no mtodo onLoadComplete(), o cdigo cria o objeto Shader chamado shader. Em seguida, ele cria e desenha o contedo de um objeto chamado target. O objeto target um retngulo preenchido com uma cor gradiente linear que vermelha esquerda, verde e amarela no meio e azul claro direita. O objeto no filtrado semelhante a este:

Com o filtro aplicado, as cores so invertidas, e o retngulo fica parecido com o seguinte:

O sombreador usado neste exemplo o kernel do Pixel Bender de exemplo invertRGB.pbk fornecido com o Pixel Bender Toolkit. O cdigo-fonte est disponvel no arquivo invertRGB.pbk localizado no diretrio de instalao do Pixel Bender Toolkit. Compile o cdigo-fonte e salve o arquivo de cdigo de bytes com o nome invertRGB.pbj no mesmo diretrio que o seu cdigo-fonte do ActionScript.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sombreadores Pixel Bender

313

Veja abaixo o cdigo ActionScript para este exemplo. Use esta classe com a classe de aplicativo principal em um projeto somente ActionScript no Flash Builder ou como a classe do documento para o arquivo FLA no Flash Professional:
package { import import import import import import import import import import import

flash.display.GradientType; flash.display.Graphics; flash.display.Shader; flash.display.Shape; flash.display.Sprite; flash.filters.ShaderFilter; flash.events.Event; flash.geom.Matrix; flash.net.URLLoader; flash.net.URLLoaderDataFormat; flash.net.URLRequest;

public class InvertRGB extends Sprite { private var shader:Shader; private var loader:URLLoader; public function InvertRGB() { init(); } private function init():void { loader = new URLLoader(); loader.dataFormat = URLLoaderDataFormat.BINARY; loader.addEventListener(Event.COMPLETE, onLoadComplete); loader.load(new URLRequest("invertRGB.pbj")); }

private function onLoadComplete(event:Event):void {

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sombreadores Pixel Bender

314

shader = new Shader(loader.data); var target:Shape = new Shape(); addChild(target); var g:Graphics = target.graphics; var c:Array = [0x990000, 0x445500, 0x007799]; var a:Array = [255, 255, 255]; var r:Array = [0, 127, 255]; var m:Matrix = new Matrix(); m.createGradientBox(w, h); g.beginGradientFill(GradientType.LINEAR, c, a, r, m); g.drawRect(10, 10, w, h); g.endFill(); var invertFilter:ShaderFilter = new ShaderFilter(shader); target.filters = [invertFilter]; } } }

Para obter mais informaes sobre como aplicar filtros, consulte Criao e aplicao de filtros na pgina 260.

Uso de um sombreador no modo autnomo

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Quando voc usa um sombreador no modo autnomo, o processamento do sombreador executado independentemente do modo como voc pretende usar a sada. Voc especifica o sombreador a ser executado, define valores de entrada e de parmetro e designa um objeto em que so colocados os dados resultantes. Voc pode usar um sombreador no modo autnomo por dois motivos:

Processamento de dados no de imagem: no modo autnomo, voc pode optar por passar dados binrios ou
numricos arbitrrios para o sombreador em vez de dados de imagem de bitmap. Voc pode determinar que o resultado do sombreador seja retornado como dados binrios ou numricos alm dos dados de imagem de bitmap.

Processamento em segundo plano: Quando voc executa um sombreador no modo autnomo, por padro ele
executado de maneira assncrona. Isso significa que o sombreador executado em segundo plano enquanto o aplicativo continua a executar, e o cdigo recebe uma notificao quando o processamento do sombreador concludo. Voc pode usar um sombreador que demora bastante tempo para ser executado e no congela a interface de usurio do aplicativo ou outro processamento enquanto o sombreador est em execuo. Use um objeto ShaderJob para executar um sombreador no modo autnomo. Primeiro voc deve criar o objeto ShaderJob e vincul-lo ao objeto Shader que representa o sombreador a ser executado:
var job:ShaderJob = new ShaderJob(myShader);

Em seguida, defina quaisquer valores de entrada ou de parmetro esperados pelo sombreador. Se estiver executando o sombreador em segundo plano, voc tambm dever registrar um ouvinte para o evento complete do objeto ShaderJob. O ouvinte ser chamado quando o sombreador concluir seu trabalho:
function completeHandler(event:ShaderEvent):void { // do something with the shader result } job.addEventListener(ShaderEvent.COMPLETE, completeHandler);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com sombreadores Pixel Bender

315

Em seguida, crie um objeto no qual o resultado da operao do sombreador ser gravado quando a operao for concluda. Atribua esse objeto propriedade target do objeto ShaderJob:
var jobResult:BitmapData = new BitmapData(100, 75); job.target = jobResult;

Atribua uma ocorrncia de BitmapData propriedade target, caso voc esteja usando ShaderJob para executar o processamento da imagem. Se estiver processando dados binrios ou numricos, atribua um objeto ByteArray ou uma ocorrncia de Vector.<Number> propriedade target. Nesse caso, voc deve definir as propriedades width e height do objeto ShaderJob para especificar o volume de dados a ser gerado para o objeto target. Nota: possvel definir as propriedades shader, target, width e height do objeto ShaderJob em uma nica etapa passando argumentos para o construtor ShaderJob(), da seguinte forma:var job:ShaderJob = new
ShaderJob(myShader, myTarget, myWidth, myHeight);

Quando estiver pronto para executar o sombreador, chame o mtodo start() do objeto ShaderJob:
job.start();

Por padro, chamar start() faz com que ShaderJob seja executado de maneira assncrona. Nesse caso, a execuo do programa prossegue imediatamente com a prxima linha de cdigo, em vez de esperar a concluso do sombreador. Quando a operao do sombreador concluda, o objeto ShaderJob chama seus ouvintes de evento complete, notificando-os sobre o trmino da execuo. Nesse momento (isto , no corpo do ouvinte de evento complete), o objeto target contm o resultado da operao do sombreador. Nota: Em vez de usar o objeto da propriedade target, voc pode recuperar o resultado do sombreador diretamente do objeto do evento que passado para o mtodo do ouvinte. O objeto de evento uma ocorrncia de ShaderEvent. O objeto ShaderEvent tem trs propriedades que podem ser usadas para acessar o resultado, dependendo do tipo de dados do objeto definido como a propriedade target: ShaderEvent.bitmapData, ShaderEvent.byteArray e ShaderEvent.vector. Se preferir, voc pode passar um argumento true para o mtodo start(). Nesse caso, a operao do sombreador ser executada de maneira sncrona. Todo o cdigo (inclusive a interao com a interface de usurio e quaisquer outros eventos) pausado enquanto o sombreador executado. Quando o sombreador concludo, o objeto target contm o resultado do sombreador e o programa prossegue com a prxima linha de cdigo.
job.start(true);

ltima atualizao em 29/3/2011

316

Captulo 15: Trabalho com clipes de filme

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe MovieClip a classe principal para smbolos de animao e clipe de vdeo que voc cria no seu ambiente de desenvolvimento do Adobe Flash. Ela possui todos os comportamentos e funcionalidades dos objetos de exibio, mas com propriedades e mtodos adicionais para controlar sua linha de tempo.

Noes bsicas de clipes de filme

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os clipes de filme so elementos essenciais para quem cria contedo animado com a ferramenta de autoria do Flash e deseja controlar esse contedo com o ActionScript. Sempre que voc cria um smbolo de clipe de filme no Flash, o Flash adiciona o smbolo biblioteca desse documento Flash. Por padro, esse smbolo se torna uma ocorrncia da Classe MovieClip e, como tal, tem as propriedades e mtodos da classe MovieClip. Quando uma ocorrncia de um smbolo de clipe de filme colocada no Palco, o clipe de filme avana automaticamente na linha de tempo (se tiver mais de um quadro), a menos que a reproduo seja alterada usando o ActionScript. essa linha de tempo que distingue a classe MovieClip, permitindo que voc crie a animao por meio de interpolaes de movimento ou forma com a ferramenta de autoria do Flash. Entretanto, com um objeto de exibio que uma ocorrncia da classe Sprite, voc pode criar a animao apenas alterando os valores do objeto de modo programtico. Nas verses anteriores do ActionScript, a classe MovieClip era a base para todas as ocorrncias no Palco. No ActionScript 3.0, um clipe de filme apenas um dos muitos objetos que podem aparecer na tela. Se uma linha de tempo no for necessria para a funo de um objeto de exibio, o uso da classe Shape ou Sprite no lugar da classe MovieClip poder melhorar o desempenho de renderizao. Para obter informaes sobre a escolha do objeto de exibio apropriado para uma tarefa, consulte Escolha de uma subclasse de DisplayObject na pgina 165. Conceitos e termos importantes A lista de referncia a seguir contm termos importantes relacionados aos clipes de filme:
SWF AVM1 Um arquivo SWF criado usando o ActionScript 1.0 ou o ActionScript 2.0, normalmente destinado

executado no Flash Player 8 ou anterior.

SWF AVM2 Um arquivo SWF criado usando o ActionScript 3.0 para Adobe Flash Player 9 ou posterior ou Adobe AIR. SWF externo Um arquivo SWF que criado separadamente do arquivo SWF de projeto e serve para ser carregado no arquivo SWF de projeto e reproduzido nesse arquivo SWF. Quadro A menor diviso de tempo na linha de tempo. Assim como em um fotograma de filme de cinema, cada quadro

como um instantneo da animao no tempo e, quando os quadros so reproduzidos rapidamente em seqncia, o efeito da animao criado.
Linha do tempo A representao metafrica da srie de quadros forma a seqncia de animao de um clipe de filme. A linha de tempo de um objeto MovieClip equivalente da ferramenta de autoria do Flash. Indicador de reproduo Um marcador identificando o local (quadro) na linha de tempo que est sendo exibido em

um determinado momento.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com clipes de filme

317

Trabalho com objetos MovieClip

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Ao publicar um arquivo SWF, o Flash converte todas as ocorrncias do smbolo de clipe de filme no Palco para objetos MovieClip. Para disponibilizar um smbolo de clipe de filme para o ActionScript, d a ele um nome de ocorrncia no campo Nome da ocorrncia do Inspetor de propriedades. Quando um arquivo SWF criado, o Flash gera o cdigo que cria a ocorrncia de MovieClip no Palco e declara uma varivel usando o nome da ocorrncia. Se voc nomeou clipes de filme que esto aninhados em outros clipes de filme nomeados, esses clipes de filme filho sero tratados como propriedades do clipe de filme pai (voc pode acessar o clipe de filme filho usando a sintaxe de pontos). Por exemplo, se um clipe de filme com o nome de ocorrncia childClip estiver aninhado em outro clipe com o nome de ocorrncia parentClip, voc poder reproduzir a animao de linha de tempo do clipe filho chamando este cdigo:
parentClip.childClip.play();

Nota: : Ocorrncias-filho inseridas no Palco, na ferramenta de autoria do Flash, no podem ser acessadas pelo cdigo a partir do construtor de uma ocorrncia-pai, j que no foram criadas nesse ponto da execuo do cdigo. Antes de acessar o filho, o pai deve, em vez disso, criar a ocorrncia-filho por cdigo ou atrasar o acesso a uma funo de retorno de chamada que ouve o filho de modo a despachar seu evento Event.ADDED_TO_STAGE. Embora alguns mtodos e propriedades herdados da classe MovieClip do ActionScript 2.0 permaneam os mesmos, outros foram alterados. Todas as propriedades prefixadas com um sublinhado foram renomeadas. Por exemplo, as propriedades _width e _height agora so acessadas como width e height, enquanto que _xscale e _yscale agora so acessadas como scaleX e scaleY. Consulte uma lista completa das propriedades e dos mtodos da classe MovieClip em Referncia do ActionScript 3.0 para a plataforma Adobe Flash .

Controle de reproduo de clipe de filme

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O Flash usa a metfora de uma linha de tempo para transmitir uma animao ou uma alterao de estado. Qualquer elemento visual que empregue uma linha de tempo deve ser um objeto MovieClip ou uma extenso da classe MovieClip. Embora o ActionScript possa instruir qualquer clipe de filme a parar, reproduzir ou ir para outro ponto na linha de tempo, ele no pode ser usado para criar dinamicamente uma linha de tempo ou adicionar contedo a quadros especficos; isso s possvel usando a ferramenta de autoria do Flash. Ao ser reproduzido, o MovieClip avana na linha de tempo em uma velocidade controlada pela velocidade de projeo do arquivo SWF. Se desejar, voc pode substituir essa configurao definindo a propriedade Stage.frameRate no ActionScript.

Reproduzir clipes de filme e parar a reproduo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os mtodos play() e stop() permitem o controle bsico de um clipe de filme na linha de tempo. Por exemplo, suponha que voc tenha um smbolo de clipe de filme no Palco que contm uma animao de uma bicicleta se movendo pela tela, com o nome de ocorrncia definido como bicycle. Se o seguinte cdigo for anexado a um quadrochave na linha de tempo principal,
bicycle.stop();

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com clipes de filme

318

a bicicleta no se mover (a animao no ser reproduzida). O movimento da bicicleta pode comear por meio de outra interao do usurio. Por exemplo, se voc tivesse um boto chamado startButton, o seguinte cdigo em um quadro-chave na linha de tempo principal faria a animao ser reproduzida com um clique no boto:
// This function will be called when the button is clicked. It causes the // bicycle animation to play. function playAnimation(event:MouseEvent):void { bicycle.play(); } // Register the function as a listener with the button. startButton.addEventListener(MouseEvent.CLICK, playAnimation);

Avanar e retroceder
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os mtodos play() e stop() no so a nica forma de controlar a reproduo em um clipe de filme. Voc tambm pode mover o indicador de reproduo para frente ou para trs na linha de tempo manualmente, usando os mtodos nextFrame() e prevFrame(). Quando qualquer um desses mtodos chamado, a reproduo pra e move o indicador de reproduo um quadro para frente ou para trs, respectivamente. Usar o mtodo play() como chamar nextFrame() sempre que o evento enterFrame do objeto do clipe de filme disparado. Com essas linhas, voc pode fazer a reproduo do clipe de filme bicycle retroceder, criando um ouvinte de eventos para o evento enterFrame e instruindo bicycle a ir para o quadro anterior na funo do ouvinte, desta forma:
// This function is called when the enterFrame event is triggered, meaning // it's called once per frame. function everyFrame(event:Event):void { if (bicycle.currentFrame == 1) { bicycle.gotoAndStop(bicycle.totalFrames); } else { bicycle.prevFrame(); } } bicycle.addEventListener(Event.ENTER_FRAME, everyFrame);

Na reproduo normal, se um clipe de filme tiver mais de um quadro, ele far loop indefinidamente ao ser reproduzido, ou seja, ele retornar ao Quadro 1 quando ultrapassar o quadro final. Ao usar prevFrame() ou nextFrame(), esse comportamento no acontece automaticamente (chamar prevFrame() quando o indicador de reproduo est no Quadro 1 no o move para o ltimo quadro). A condio if no exemplo anterior verifica se o indicador de reproduo retrocedeu para o primeiro quadro e o define frente de seu quadro final, criando assim um loop contnuo do clipe de filme cuja reproduo retrocede.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com clipes de filme

319

Salto para um quadro diferente e uso de rtulos de quadro

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O envio de um clipe de filme para um novo quadro simples. A chamada de gotoAndPlay() ou gotoAndStop() far o clipe de filme saltar para o nmero de quadro especificado como parmetro. Se preferir, voc pode transmitir uma seqncia de caracteres que corresponda ao nome de um rtulo de quadro. possvel atribuir um rtulo a qualquer quadro na linha de tempo. Para fazer isso, selecione um quadro na linha de tempo e digite um nome no campo Rtulo do quadro no Inspetor de propriedades. As vantagens de usar rtulos de quadro em vez de nmeros ficam mais evidentes ao criar um clipe de filme complexo. Quando o nmero de quadros, camadas e interpolaes em uma animao for grande, considere a rotulagem de quadros importantes com descries explicativas que representem mudanas de comportamento no clipe de filme (por exemplo, "off", "walking", "running"). Isso melhora a confiabilidade do cdigo e tambm fornece flexibilidade, j que as chamadas do ActionScript que vo para um quadro rotulado so ponteiros para uma nica referncia, o rtulo, em vez de um nmero de quadro especfico. Se mais tarde voc decidir mover um segmento especfico da animao para um quadro diferente, no ser necessrio alterar o cdigo do ActionScript contanto que mantenha o mesmo rtulo para os quadros no novo local. Para representar os rtulos de quadro no cdigo, o ActionScript 3.0 inclui a classe FrameLabel. Cada ocorrncia dessa classe representa um nico rtulo de quadro e tem uma propriedade name representando o nome do rtulo de quadro conforme especificado no Inspetor de propriedades e uma propriedadeframe representando o nmero do quadro com rtulo colocado na linha de tempo. Para obter acesso s ocorrncias de FrameLabel associadas a uma ocorrncia de clipe de filme, a classe MovieClip inclui duas propriedades que retornam objetos FrameLabel diretamente. A propriedade currentLabels retorna uma matriz que consiste em todos os objetos FrameLabel na linha de tempo inteira de um clipe de filme. A propriedade currentLabel retorna uma seqncia de caracteres contendo o nome do rtulo de quadro encontrado mais recentemente na linha de tempo. Suponha que voc crie um clipe de filme chamado robot e rotulou os diversos estados dessa animao. Voc pode configurar uma condio que verifica a propriedade currentLabel para acessar o estado atual de robot, como no seguinte cdigo:
if (robot.currentLabel == "walking") { // do something }

Trabalho com cenas

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior No ambiente de autoria do Flash, voc pode usar cenas para demarcar uma srie de linhas de tempo pelas quais um arquivo SWF pode avanar. Com o uso do segundo parmetro dos mtodos gotoAndPlay() ou gotoAndStop(), possvel especificar uma cena qual enviar o indicador de reproduo. Todos os arquivos FLA comeam apenas com a cena inicial, mas voc pode criar novas cenas. O uso de cenas nem sempre a melhor abordagem porque as cenas apresentam vrias desvantagens. Um documento Flash contendo vrias cenas pode ser difcil de manter, principalmente em ambientes de vrios autores. Vrias cenas tambm podem ser ineficientes em largura de banda, porque o processo de publicao mescla todas as cenas em uma nica linha de tempo. Isso provoca um download progressivo de todas as cenas, mesmo que elas nunca sejam reproduzidas. Por esses motivos, o uso de vrias cenas, muitas vezes, no recomendado para organizar vrias animaes longas baseadas na linha de tempo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com clipes de filme

320

A propriedade scenes da classe MovieClip uma matriz de objetos Scene que representa todas as cenas no arquivo SWF. A propriedade currentScene retorna um objeto Scene que representa a cena que est em execuo no momento. A classe Scene possui vrias propriedades que fornecem informaes sobre uma cena. A propriedade labels retorna uma matriz de objetos FrameLabel representando os rtulos de quadro dessa cena. A propriedade name retorna o nome da cena como uma seqncia de caracteres. A propriedade numFrames retorna um int representando o nmero total de quadro na cena.

Criao de objetos MovieClip com o ActionScript

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Uma maneira de adicionar contedo tela no Flash arrastando ativos da biblioteca para o Palco, mas esse no o nico fluxo de trabalho. Para projetos complexos, os desenvolvedores experientes em geral preferem criar clipes de filme de modo programtico. Essa abordagem apresenta vrias vantagens: facilidade de reutilizao de cdigo, velocidade de tempo de compilao mais rpida e modificaes mais sofisticadas que esto disponveis apenas para o ActionScript. A API da lista de exibio do ActionScript 3.0 simplifica o processo de criar dinamicamente os objetos MovieClip. A capacidade de instanciar uma ocorrncia de MovieClip diretamente, separada do processo de adicion-la lista de exibio, fornece flexibilidade e simplicidade sem sacrificar o controle. No ActionScript 3.0, quando voc cria uma ocorrncia de clipe de filme (ou qualquer outro objeto de exibio) de modo programtico, ela s aparece na tela quando adicionada lista de exibio, chamando addChild() ou o mtodo addChildAt() em um continer de objetos de exibio. Isso permite criar um clipe de filme, definir suas propriedades e at chamar mtodos antes que ele seja renderizado na tela. Para obter informaes sobre como trabalhar com a lista de exibio, consulte Trabalho com contineres de objeto de exibio na pgina 153.

Exportao de smbolos da biblioteca para o ActionScript

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Por padro, as ocorrncias de smbolos de clipe de filme em uma biblioteca de documentos Flash no podem ser criadas dinamicamente (ou seja, usando apenas o ActionScript). Isso porque cada smbolo que exportado para ser usado no ActionScript aumenta o tamanho do arquivo SWF, e talvez no haja a inteno de usar alguns smbolos no palco. Por isso, para que um smbolo se torne disponvel, necessrio especificar que ele seja exportado para o ActionScript. Para exportar um smbolo para o ActionScript: 1 Selecione o smbolo no painel Biblioteca e abra a caixa de dilogo Propriedades do smbolo.
2 Se necessrio, ative as Configuraes avanadas. 3 Na seo de ligao, marque a caixa de seleo Exportar para ActionScript.

Isso ativar os campos Classe e Classe base.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com clipes de filme

321

Por padro, o campo Classe preenchido com o nome do smbolo, com os espaos removidos (por exemplo, um smbolo chamado "Tree House" se tornaria "TreeHouse"). Para especificar que o smbolo use uma classe personalizada para seu comportamento, digite o nome completo da classe incluindo seu pacote neste campo. Se pretende criar ocorrncias do smbolo no ActionScript, mas no precisa adicionar nenhum comportamento adicional, voc pode deixar o nome da classe como est. O valor da Classe base assume flash.display.MovieClip como padro. Se quiser estender a funcionalidade do smbolo para outra classe personalizada, voc poder especificar o nome dessa classe, contanto que ela estenda a classe Sprite (ou MovieClip).
4 Pressione o boto OK para salvar as alteraes.

Neste ponto, se o Flash no puder encontrar um arquivo ActionScript externo com uma definio para a classe especificada (por exemplo, se no for preciso adicionar outro comportamento ao smbolo), ser exibido um aviso: No foi possvel localizar uma definio para esta classe no caminho de classe. Portanto, uma definio ser automaticamente gerada no arquivo SWF aps a exportao.. Desconsidere esse aviso se o smbolo da biblioteca no exigir funcionalidade exclusiva alm daquela da classe MovieClip. Se voc no fornecer uma classe para o smbolo, o Flash criar uma para ele equivalente a esta:
package { import flash.display.MovieClip; public class ExampleMovieClip extends MovieClip { public function ExampleMovieClip() { } } }

Se quiser adicionar outra funcionalidade ActionScript ao smbolo, adicione as propriedades e mtodos adequados estrutura de cdigo abaixo. Por exemplo, suponha que voc tenha um smbolo de clipe de filme contendo um crculo com 50 pixels de largura e 50 de altura, e o smbolo seja especificado para ser exportado para o ActionScript com uma classe chamada Circle. O cdigo a seguir, quando colocado em um arquivo Circle.as, estende a classe MovieClip e fornece ao smbolo os mtodos adicionais getArea() e getCircumference():

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com clipes de filme

322

package { import flash.display.MovieClip; public class Circle extends MovieClip { public function Circle() { } public function getArea():Number { // The formula is Pi times the radius squared. return Math.PI * Math.pow((width / 2), 2); } public function getCircumference():Number { // The formula is Pi times the diameter. return Math.PI * width; } } }

O seguinte cdigo, colocado em um quadro-chave no Quadro 1 do documento Flash, criar uma ocorrncia do smbolo e a exibir na tela:
var c:Circle = new Circle(); addChild(c); trace(c.width); trace(c.height); trace(c.getArea()); trace(c.getCircumference());

Esse cdigo demonstra a instanciao baseada no ActionScript como uma alternativa para arrastar ativos individuais ao Palco. Isso cria um crculo com todas as propriedades de um clipe de filme e com os mtodos personalizados definidos na classe Circle. Este exemplo bem bsico; o smbolo da biblioteca pode especificar um nmero qualquer de propriedades e mtodos em sua classe. A instanciao baseada no ActionScript muito eficiente, porque permite criar dinamicamente grandes quantidades de ocorrncias, um trabalho que seria cansativo se feito manualmente. Ela tambm flexvel, porque voc pode personalizar as propriedades de cada ocorrncia na sua criao. Para ter uma idia dessas duas vantagens, use um loop para criar dinamicamente vrias ocorrncias de Circle. Com o smbolo e a classe Circle descritos anteriormente na sua biblioteca de documentos Flash, coloque o seguinte cdigo em um quadro-chave do Quadro 1:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com clipes de filme

323

import flash.geom.ColorTransform; var totalCircles:uint = 10; var i:uint; for (i = 0; i < totalCircles; i++) { // Create a new Circle instance. var c:Circle = new Circle(); // Place the new Circle at an x coordinate that will space the circles // evenly across the Stage. c.x = (stage.stageWidth / totalCircles) * i; // Place the Circle instance at the vertical center of the Stage. c.y = stage.stageHeight / 2; // Change the Circle instance to a random color c.transform.colorTransform = getRandomColor(); // Add the Circle instance to the current timeline. addChild(c); } function getRandomColor():ColorTransform { // Generate random values for the red, green, and blue color channels. var red:Number = (Math.random() * 512) - 255; var green:Number = (Math.random() * 512) - 255; var blue:Number = (Math.random() * 512) - 255; // Create and return a ColorTransform object with the random colors. return new ColorTransform(1, 1, 1, 1, red, green, blue, 0); }

Isso demonstra como voc pode criar e personalizar vrias ocorrncias de um smbolo com rapidez usando cdigo. Cada ocorrncia posicionada com base na contagem atual dentro do loop e recebe uma cor aleatria definindo sua propriedade transform (que Circle herda ao estender a classe MovieClip).

Carregamento de um arquivo SWF externo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior No ActionScript 3.0, os arquivos SWF so carregados usando a classe Loader. Para carregar um arquivo SWF externo, o ActionScript precisa fazer quatro coisas:
1 Criar um novo objeto URLRequest com a url do arquivo. 2 Criar um novo objeto Loader. 3 Chamar o mtodo load() do objeto Loader, transmitindo a ocorrncia de URLRequest como um parmetro. 4 Chame o mtodo addChild() em um continer de objetos de exibio (como a linha de tempo principal de um

documento Flash) para adicionar a ocorrncia de Loader lista de exibio. Por fim, o cdigo fica semelhante a este:
var request:URLRequest = new URLRequest("http://www.[yourdomain].com/externalSwf.swf"); var loader:Loader = new Loader() loader.load(request); addChild(loader);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com clipes de filme

324

Esse mesmo cdigo pode ser usado para carregar um arquivo de imagem externo, como uma imagem JPEG, GIF ou PNG, especificando a url do arquivo de imagem em vez da url de um arquivo SWF. Um arquivo SWF, diferentemente de um arquivo de imagem, pode conter o ActionScript. Por isso, embora o processo de carregar um arquivo SWF seja idntico ao de carregar uma imagem, no carregamento de um arquivo SWF externo, o arquivo SWF que faz o carregamento e o arquivo SWF que carregado residem na mesma caixa de proteo caso o Flash Player ou o AIR executem o SWF e voc pretenda usar o ActionScript para se comunicar de alguma forma com arquivo SWF. Alm disso, se o arquivo SWF contiver classes que compartilhem o mesmo namespace das classes no arquivo SWF de carregamento, talvez seja necessrio criar um novo domnio de aplicativo para o arquivo SWF carregado a fim de evitar conflitos de namespace. Para obter mais informas sobre segurana e consideraes sobre domnio de aplictivo, consulte Trabalhar com domnios de aplicativo na pgina 141 e Carregamento de contedo na pgina 1045. Quando carregado com xito, o arquivo SWF externo pode ser acessado por meio da propriedade Loader.content. Se for publicado no ActionScript 3.0, o arquivo SWF externo ser um clipe de filme ou uma entidade grfica, dependendo da classe que ele estender.

Consideraes sobre o carregamento de um arquivo SWF antigo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Se o arquivo SWF externo for publicado com uma verso mais antiga do ActionScript, h importantes limitaes a serem consideradas. Diferentemente de um arquivo SWF do ActionScript 3.0 que executado com AVM2 (ActionScript Virtual Machine 2), um arquivo SWF publicado para o ActionScript 1.0 ou no 2.0 executado com AVM1 (ActionScript Virtual Machine 1). H diferenas importantes ao carregar um arquivo SWF do ActionScript 1.0 ou 2.0 em um arquivo SWF do ActionScript 3.0 (em comparao com o carregamento de um arquivo SWF do ActionScript 3.0). O Flash Player fornece compatibilidade total com contedo publicado em verses anteriores. Qualquer contedo que executado em verses anteriores do Flash Player pode ser reproduzido nas verses do Flash Player que suportam o ActionScript 3.0. No entanto, so aplicadas as seguintes limitaes:

O cdigo do ActionScript 3.0 pode carregar um arquivo SWF escrito no ActionScript 1.0 ou 2.0. Quando um
arquivo SWF do ActionScript 1.0 or 2.0 carregado com sucesso, o objeto carregado (a propriedade Loader.content) um objeto AVM1Movie. Uma ocorrncia de AVM1Movie no igual a uma ocorrncia de MovieClip. um objeto de exibio, mas, diferentemente de um clipe de filme, no inclui mtodos ou propriedades relacionadas linha de tempo. O arquivo SWF AVM2 pai no pode acessar as propriedades, mtodos ou objetos do objeto AVM1Movie carregado.

Os arquivos SWF escritos no ActionScript 1.0 ou 2.0 no podem carregar arquivos SWF escritos no ActionScript
3.0. Isso significa que os arquivos SWF criados no Flash 8 ou no Flex Builder 1.5 ou verses anteriores no podem carregar arquivos SWF do ActionScript 3.0. A nica exceo a essa regra que um arquivo SWF do ActionScript 2.0 pode ser substitudo por um arquivo SWF do ActionScript 3.0, contanto que no tenha carregado nada antes em qualquer um de seus nveis. Um arquivo SWF do ActionScript 2.0 pode fazer isso por meio de uma chamada a loadMovieNum(), transmitindo um valor de 0 ao parmetro level.

Em geral, os arquivos SWF escritos no ActionScript 1.0 ou 2.0 devem ser migrados para trabalhar com os arquivos
SWF escritos no ActionScript 3.0. Por exemplo, suponhamos que voc criou um player de mdia usando o ActionScript 2.0. Ele carrega vrios contedos que tambm foram criados usando o ActionScript 2.0. Se voc criar um novo contedo no ActionScript 3.0, no poder carreg-lo no player de mdia. Ser necessrio migrar o player de vdeo para o ActionScript 3.0. Se, no entanto, voc criar um player de mdia no ActionScript 3.0, ele poder executar carregamentos simples do seu contedo do ActionScript 2.0.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com clipes de filme

325

As tabelas a seguir resumem as limitaes das verses anteriores do Flash Player em relao ao carregamento de contedo mais novo e execuo de cdigo, bem como as limitaes de cross-scripting entre arquivos SWF escritos em verses diferentes do ActionScript.
Funcionalidade com suporte Pode carregar SWFs publicados para Contm este AVM Executa SWFs gravados no ActionScript Flash Player 7 7 e anterior AVM1 1.0 e 2.0 Flash Player 8 8 e anterior AVM1 1.0 e 2.0 Flash Player 9 e 10 9 (ou 10) e anterior AVM1 e AVM2 1.0, 2.0 e 3.0

Na tabela a seguir, "Funcionalidade com suporte" refere-se ao contedo executado no Flash Player 9 ou posterior. O contedo executado no Flash Player 8 ou anterior s pode ser carregar, exibir, executar e cruzar scripts no ActionScript 1.0 e 2.0.
Funcionalidade com suporte Contedo criado no ActionScript 1.0 e 2.0 Contedo criado no ActionScript 3.0 ActionScript 1.0, 2.0 e 3.0

Pode carregar contedo e executar cdigo no ActionScript 1.0 e 2.0 apenas contedo criado no Pode cruzar contedo de script criado no

ActionScript 1.0 e 2.0 apenas (ActionScript 3.0 ActionScript 1.0 e 2.0 at LocalConnection. at LocalConnection) ActionScript 3.0

Exemplo de clipe de filme: RuntimeAssetsExplorer

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A funcionalidade Exportar para ActionScript pode ser especialmente vantajosa para bibliotecas que podem ser teis em mais de um projeto. Se o Flash Player ou o AIR executar um arquivo SWF, os smbolos exportados para o ActionScript ficaro disponveis para qualquer arquivo SWF dentro da mesma caixa de proteo de segurana que o SWF que o carregar. Dessa forma, um nico documento Flash pode gerar um arquivo SWF exclusivamente designado para manter ativos grficos. Essa tcnica especialmente til para projetos grandes nos quais os designers que lidam com ativos visuais podem trabalhar em paralelo com os desenvolvedores que criam um arquivo SWF "empacotador" que carrega o arquivo SWF de ativos grficos em tempo de execuo. Voc pode usar esse mtodo para manter uma srie de arquivos de verso nos quais os ativos grficos no dependem do progresso do desenvolvimento de programao. O aplicativo RuntimeAssetsExplorer carrega qualquer arquivo SWF que for uma subclasse de RuntimeAsset e permite navegar pelos ativos disponveis desse arquivo SWF. O exemplo ilustra o seguinte:

Carregamento de um arquivo SWF externo usando Loader.load() Criao dinmica de um smbolo de biblioteca exportado para o ActionScript Controle do ActionScript de reproduo de MovieClip
Antes de comear, observe que cada arquivo SWF a ser executado no Flash Player deve estar localizado na mesma caixa de proteo de segurana. Para obter mais informaes, consulte Caixas de proteo de segurana na pgina 1029. Para obter os arquivos de aplicativos dessa amostra, efetue o download de Amostras do Flash Professional. Os arquivos de aplicativo RuntimeAssetsExplorer podem ser encontrados na pasta Samples/RuntimeAssetsExplorer. O aplicativo consiste nos seguintes arquivos:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com clipes de filme

326

Arquivo RuntimeAssetsExample.mxml ou RuntimeAssetsExample.fla RuntimeAssetsExample.as GeometricAssets.as

Descrio A interface do usurio do aplicativo para Flex (MXML) ou Flash (FLA).

Classe de documento para o aplicativo Flash (FLA). Uma classe de exemplo que implementa a interface RuntimeAsset. Um arquivo FLA vinculado classe GeometricAssets (a classe de documento do FLA) contendo smbolos que so exportados para o ActionScript. Uma interface que define os mtodos necessrios esperados de todos os arquivos SWF de ativos de tempo de execuo que sero carregados no continer do explorador. A classe do smbolo de biblioteca na forma de uma caixa de rotao. A classe do smbolo de biblioteca na forma de uma estrela de rotao.

GeometricAssets.fla

com/example/programmingas3/runtimeassetexplorer/RuntimeLibrary.as

com/example/programmingas3/runtimeassetexplorer/AnimatingBox.as

com/example/programmingas3/runtimeassetexplorer/AnimatingStar.as

Estabelecimento de uma interface de biblioteca de tempo de execuo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para que o explorador interaja adequadamente com uma biblioteca SWF, a estrutura das bibliotecas de ativos de tempo de execuo deve ser formalizada. Faremos isso criando uma interface, que semelhante a uma classe pois trata-se de um projeto de mtodos que demarca uma estrutura esperada, mas, diferentemente de uma classe, no inclui nenhum corpo de mtodo. A interface fornece um meio de comunicao ente a biblioteca de tempo de execuo e o explorador. Cada SWF de ativos de tempo de execuo que for carregado em nosso navegador implementar essa interface. Para obter informaes sobre interfaces e como elas podem ser teis, consulte Interfaces em Aprendizado do ActionScript 3.0. A interface RuntimeLibrary ser bem simples: precisamos apenas de uma funo que fornea ao explorador uma matriz de caminhos de classe para os smbolos a serem exportados e disponibilizados na biblioteca de tempo de execuo. Para esse fim, a interface possui um nico mtodo: getAssets().
package com.example.programmingas3.runtimeassetexplorer { public interface RuntimeLibrary { function getAssets():Array; } }

Criao do arquivo SWF da biblioteca de ativos

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Ao definir a interface RuntimeLibrary, possvel criar vrios arquivos SWF de biblioteca de ativos que podem ser carregados em outro arquivo SWF. A criao de uma biblioteca SWF individual de ativos envolve quatro tarefas:

Criao de uma classe para o arquivo SWF da biblioteca de ativos

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com clipes de filme

327

Criao de classes para ativos individuais contidos na biblioteca Criao dos ativos grficos em si Associao de elementos grficos a classes e publicao do SWF da biblioteca
Criao de uma classe para implementar a interface RuntimeLibrary Em seguida, criaremos a classe GeometricAssets que implementar a interface RuntimeLibrary. Ela ser a classe de documento do FLA. O cdigo para essa classe muito semelhante interface RuntimeLibrary; a diferena entre eles que, na definio da classe, o mtodo getAssets() possui um corpo de mtodo.
package { import flash.display.Sprite; import com.example.programmingas3.runtimeassetexplorer.RuntimeLibrary; public class GeometricAssets extends Sprite implements RuntimeLibrary { public function GeometricAssets() { } public function getAssets():Array { return [ "com.example.programmingas3.runtimeassetexplorer.AnimatingBox", "com.example.programmingas3.runtimeassetexplorer.AnimatingStar" ]; } } }

Se fssemos criar uma segunda biblioteca de tempo de execuo, criaramos outro FLA com base em outra classe (por exemplo, AnimationAssets) que fornece sua prpria implementao de getAssets(). Criao de classes para cada ativo MovieClip Para este exemplo, iremos apenas estender a classe MovieClip sem adicionar nenhuma funcionalidade aos ativos personalizados. O seguinte cdigo para AnimatingStar anlogo ao de AnimatingBox:
package com.example.programmingas3.runtimeassetexplorer { import flash.display.MovieClip; public class AnimatingStar extends MovieClip { public function AnimatingStar() { } } }

Publicao da biblioteca Agora, iremos conectar os ativos baseados no MovieClip nova classe, criando um novo FLA e inserindo GeometricAssets no campo Classe do documento do Inspetor de propriedades. Para fins deste exemplo, criaremos duas formas bsicas que suam uma interpolao de linha de tempo para fazer uma rotao no sentido horrio em 360 quadros. Os smbolos animatingBox e animatingStar so definidos para Exportar para ActionScript e o campo Classe definido com os respectivos caminhos de classe especificados na implementao de getAssets(). A classe base padro de flash.display.MovieClip permanece, pois desejamos subclassificar os mtodos MovieClip padro.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com clipes de filme

328

Depois de definir as configuraes de exportao do smbolo, publique o FLA. Agora, sua primeira biblioteca de tempo de execuo est pronta. Se esse arquivo SWF fosse carregado em outro arquivo SWF AVM2, os smbolos AnimatingBox e AnimatingStar ficariam disponveis para o arquivo SWF.

Carregamento da biblioteca em outro arquivo SWF

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A ltima questo funcional a ser resolvida a interface do usurio para o explorador de ativos. Neste exemplo, o caminho para a biblioteca de tempo de execuo codificado como uma varivel chamada ASSETS_PATH. Se preferir, voc pode usar a classe FileReference, por exemplo, para criar uma interface que navegue para um arquivo SWF especfico do seu disco rgido. Quando a biblioteca de tempo de execuo carregada com xito, o Flash Player chama o mtodo
runtimeAssetsLoadComplete(): private function runtimeAssetsLoadComplete(event:Event):void { var rl:* = event.target.content; var assetList:Array = rl.getAssets(); populateDropdown(assetList); stage.frameRate = 60; }

Nesse mtodo, a varivel rl representa o arquivo SWF carregado. O cdigo chama o mtodo getAssets() do arquivo SWF carregado, obtendo uma lista de ativos que esto disponveis e os usa para preencher um componente ComboBox com uma lista de ativos disponveis, chamando o mtodo populateDropDown(). Esse mtodo por sua vez armazena o caminho de classe completo de cada ativo. Ao ser clicado, o boto Adicionar da interface do usurio dispara o mtodo addAsset():
private { var var var ... } function addAsset():void className:String = assetNameCbo.selectedItem.data; AssetClass:Class = getDefinitionByName(className) as Class; mc:MovieClip = new AssetClass();

que obtm o caminho de classe do ativo atualmente selecionado no ComboBox (assetNameCbo.selectedItem.data) e usa a funo getDefinitionByName() (do pacote flash.utils) para obter uma referncia real para a classe do ativo a fim de criar uma nova ocorrncia desse ativo.

ltima atualizao em 29/3/2011

329

Captulo 16: Trabalho com cinemtica inversa

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior, requer Flash CS4 ou posterior A IK (Cinemtica inversa) uma tima tcnica de criao de movimentos realistas. A IK permite a criao de movimentos coordenados dentro de uma cadeia de trechos conectados conhecida como armadura IK, para que as partes apresentem movimentos sincronizados realistas. As partes da armadura so os bones e as junes. Dado o ponto final da armadura, a IK calcula os ngulos das junes que devem alcanar esse ponto. Fazer os clculos de tais ngulos manualmente seria desafiador. O mrito desse recurso que voc pode criar armaduras interativamente usando o Adobe Flash Professional. Em seguida, s anim-las usando o ActionScript. O mecanismo IK includo com o Flash Professional realiza os clculos para descrever o movimento da armadura. possvel limitar o movimento a determinados parmetros contidos em seu cdigo ActionScript. Uma novidade do Flash Professional CS5 da verso IK o conceito de bone spring, normalmente associado com aplicativos de animao de ponta. Utilizado com o Physics Engine, este recursos permite configurar movimentos realsticos. Este efeito visvel no tempo de execuo e durante a autoria. Para criar armaduras de cinemtica inversa, preciso ter a licena do Flash Professional.

Mais tpicos da Ajuda

Pacote fl.ik

Noes bsicas de cinemtica inversa

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior, requer Flash CS4 ou posterior A IK permite a criao de animaes realistas por meio da juno de partes que se movimentam entre si. Por exemplo, com o uso da IK voc pode mover uma perna para uma determinada posio ao articular o movimento de suas respectivas junes para alcanar a posio desejada. A IK usa uma estrutura de bones encadeados em uma estrutura chamada armadura IK. O pacote fl.ik ajuda a criar animaes que remetem a movimentos naturais. Ele permite que voc anime vrias armaduras IK diretamente sem precisar saber muito sobre o funcionamento dos algoritmos IK. Crie a armadura IK com seus respectivos bones e junes auxiliares no Flash Professional. Em seguida, acesse as classes IK para anim-las no tempo de execuo. Consulte a seo Uso de cinemtica inversa em Uso do Flash Professional para obter instrues detalhadas sobre como criar uma armadura IK. Conceitos e termos importantes A lista de referncia a seguir contm termos importantes que so relevantes a este recurso:
Armadura Cadeia cinemtica, formada por bones e junes, utilizada em animaes computadorizadas para simular movimentos reais.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com cinemtica inversa

330

Bone um segmento rgido de uma armadura, que corresponde a um dos ossos de um esqueleto. Cinemtica inversa (IK) Processo de determinao dos parmetros de um objeto com junes flexveis, que pode ser

uma cadeia cinemtica ou uma armadura.

Juno Local em que ocorre a unio de dois bones, construda para permitir o movimento dos bones, que corresponde a uma articulao de um ser vivo. Physics Engine Um pacote de algoritmos de Fsica usados para criar aes realistas em animaes. Spring A qualidade de um osso que se move e reage quando o osso ascendente movimentado e, depois, diminui gradualmente ao longo do tempo.

Viso geral da animao de armaduras IK

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior, requer Flash CS4 ou posterior Aps criar uma armadura IK no Flash Professional, use as classes fl.ik para restringir seus movimentos, rastrear seus eventos e anim-la no tempo de execuo. A figura a seguir apresenta um clipe de filme chamado Roda. O eixo uma ocorrncia de uma IKArmature chamada
Eixo. A classe IKMover move a armadura de modo sincronizado com a rotao da roda. O IKBone, ikBone2, da

armadura anexado roda, como juno de sua parte inferior.

A

A. Roda B. Eixo C. ikBone2

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com cinemtica inversa

331

No tempo de execuo, a roda gira em associao com a interpolao de movimento __motion_Wheel discutida em Descrio da animao. Um objeto IKMover inicia e controla o movimento do eixo. A figura a seguir exibe dois instantneos da armadura do eixo fixos roda em diferentes quadros durante o movimento de rotao.

No tempo de execuo, o ActionScript a seguir:

Obtm informaes sobre a armadura e seus componentes Cria ocorrncia de um objeto IKMover Move o eixo de acordo com a rotao da roda
import fl.ik.* var var var var tree:IKArmature = IKManager.getArmatureByName("Axle"); bone:IKBone = tree.getBoneByName("ikBone2"); endEffector:IKJoint = bone.tailJoint; pos:Point = endEffector.position;

var ik:IKMover = new IKMover(endEffector, pos); ik.limitByDistance = true; ik.distanceLimit = 0.1; ik.limitByIteration = true; ik.iterationLimit = 10; Wheel.addEventListener(Event.ENTER_FRAME, frameFunc); function frameFunc(event:Event) { if (Wheel != null) { var mat:Matrix = Wheel.transform.matrix; var pt = new Point(90, 0); pt = mat.transformPoint(pt); ik.moveTo(pt); } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com cinemtica inversa

332

As classes IK usadas para mover o eixo so:

IKArmature: descreve a armadura, uma estrutura em rvore formada por bones e junes, que deve ser criada no
Flash Professional

IKManager: classe de continer para todas as armaduras IK do documento, que deve ser criada no Flash
Professional

IKBone: um segmento de uma armadura IK IKJoint: uma conexo entre dois bones IK IKMover: inicia e controla o movimento IK das armaduras
Veja descries completas e detalhadas dessas classes no pacote ik.

Obteno de informaes sobre uma armadura IK

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior, requer Flash CS4 ou posterior Primeiro, declare variveis para a armadura, para o bone e para a juno que une as partes que deseja movimentar. O cdigo a seguir usa o mtodo getArmatureByName() da classe IKManager para atribuir o valor da armadura Eixo varivel tree da IKArmature. A armadura Axle foi criada anteriormente no Flash Professional.
var tree:IKArmature = IKManager.getArmatureByName("Axle");

De modo semelhante, o cdigo a seguir usa o mtodo getBoneByName() da classe IKArmature para atribuir a varivel IKBone ao valor do bone ikBone2.
var bone:IKBone = tree.getBoneByName("ikBone2");

A juno da parte inferior do bone ikBone2 a parte da armadura que a conecta roda. A linha a seguir declara a varivel endEffector e atribui a ela a propriedade tailjoint do bone ikBone2:
var endEffector:IKJoint = home.tailjoint;

A varivel pos um ponto que armazena a posio correta da juno endEffector.

var pos:Point = endEffector.position;

Nesse exemplo, pos a posio da juno na extremidade do eixo conectada roda. O valor original dessa varivel obtida a partir da propriedade position do IKJoint.

Ocorrncia de IKMover e limitao de seu movimento

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior, requer Flash CS4 ou posterior Uma ocorrncia da classe IKMover movimenta o eixo. A linha a seguir cria ocorrncia do objeto ik do IKMover, transmitindo ao seu construtor o elemento a ser movimentado e o ponto de incio do movimento:
var ik:IKMover = new IKMover(endEffector, pos);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com cinemtica inversa

333

As propriedades da classe IKMover permitem a limitao do movimento de uma armadura. possvel limitar o movimento, tendo como base a distncia, as iteraes e o tempo de durao do movimento. Os pares de propriedades a seguir reforam esses limites. Os pares consistem em um valor booleano que indica se o movimento limitado, alm de um inteiro que especifica o limite:
Propriedade Boolean
limitByDistance:Boolean

Propriedade Integer
distanceLimit:int

Limite definido Define a distncia mxima em pixels que o mecanismo IK se desloca para cada iterao. Define o nmero mximo de iteraes que o mecanismo IK executa para cada movimento. Define o tempo mximo em milissegundos designado para que o mecanismo IK execute o movimento.

limitByIteration:Boolean

iterationLimit:int

limitByTime:Boolean

timeLimit:int

Por padro, todos os valores booleanos so definidos como false, assim o movimento no limitado a menos que voc defina explicitamente um valor booleano como true. Para forar um limite, defina a propriedade apropriada true e depois especifique um valor para a propriedade Integer correspondente. Se voc definir o limite para um valor sem configurar sua propriedade Boolean correspondente, o limite ser ignorado. Nesse caso, o mecanismo IK continua a movimentao do objeto at outro limite ou at que a posio de destino do IKMover seja alcanada. No exemplo a seguir, a distncia mxima do movimento da armadura est definido como 0,1 pixels por iterao. O nmero mximo de iteraes para cada movimento est definido como dez.
ik.limitByDistance = true; ik.distanceLimit = 0.1; ik.limitByIteration = true; ik.iterationLimit = 10;

Movimentao de uma armadura IK

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior, requer Flash CS4 ou posterior O IKMover movimenta o eixo interno do ouvinte de eventos para a roda. Em cada evento enterFrame da roda, uma nova posio de destino para a armadura calculada. Usando seu mtodo moveTo() , o IKMover movimenta a juno da parte inferior para sua respectiva posio de destino ou o mais prximo possvel, dentro dos limites definidos pelas suas propriedades limitByDistance, limitByIteration e limitByTime.
Wheel.addEventListener(Event.ENTER_FRAME, frameFunc); function frameFunc(event:Event) { if (Wheel != null) { var mat:Matrix = Wheel.transform.matrix; var pt = new Point(90,0); pt = mat.transformPoint(pt); ik.moveTo(pt); } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com cinemtica inversa

334

Utilizando suspenses
O Flash Player 10 e superior, Adobe AIR 1.5 e superior, requerem o Flash CS5 ou superior A cinemtica invertida o Flash Professional CS5 fornece suporte a bone spring. O bone spring pode ser configurado durante a autoria e seus atributos podem ser adicionados ou modificados em tempo de execuo. Elasticidade (spring) uma propriedade de um osso e de suas articulaes. Ele possui dois atributos: IKJoint.springStrength, que define a quantidade de spring e IKJoint.springDamping, que adiciona resistncia ao valor de fora e altera a taxa de decaimento do spring. A fora do spring um valor percentual de padro 0 (totalmente rgido) at 100 (muito solto e controlado por propriedades fsicas). Ossos com elasticidade reagem ao movimento de suas articulaes. Se nenhuma outra translao (rotao, x, ou y) estiver ativada, as configuraes de elasticidade no tero nenhum efeito. O amortecimento de spring um valor percentual de padro 0 (nenhuma resistncia) at 100 (muito reduzido). O amortecimento altera o tempo entre o movimento inicial o osso e o retorno posio de descanso. Verifique se os springs esto habilitados para um objeto IKArmature verificando a propriedade IKArmature.springsEnabled . As outras propriedades e os outros mtodos da elasticidade pertencem a cada objeto IKJoint individualmente. Uma junta pode ser habilitada para rotao angular e transporte entre os eixo x e y. Voc pode posicionar um ngulo de spring de junta com IKJoint.setSpringAngle e uma posio de junta de spring transportvel com IKJoint.setSpringPt. Este exemplo seleciona um osso pelo nome e identifica sua tailJoint. O cdigo testa a armadura ascendente para saber se as elasticidades esto ativadas e, em seguida, define as propriedades de elasticidade da articulao.
var arm:IKArmature = IKManager.getArmatureAt(0); var bone:IKBone = arm.getBoneByName("c"); var joint:IKJoint = bone.tailJoint; if (arm.springsEnabled) { joint.springStrength = 50; //medium spring strength joint.springDamping = 10; //light damping resistance if (joint.hasSpringAngle) { joint.setSpringAngle(30); //set angle for rotational spring } }

Uso de eventos IK
Flash Player 10 e posterior, Adobe AIR 1.5 e posterior, requer Flash CS4 ou posterior A classe IKEvent permite a criao de um objeto de evento que contm informaes sobre eventos IK. As informaes IKEvent descrevem o movimento que foi interrompido porque o tempo especificado, a distncia ou o limite de iterao foi excedido. O cdigo a seguir mostra um ouvinte de eventos e um manipulador para rastreamento de eventos de limite de tempo. Esse manipulador de eventos indica o tempo, a distncia, a contagem de iteraes e as propriedades de junes de um evento que dispara quando o limite de tempo do IKMover excedido.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com cinemtica inversa

335

var ikmover:IKMover = new IKMover(endjoint, pos); ikMover.limitByTime = true; ikMover.timeLimit = 1000; ikmover.addEventListener(IKEvent.TIME_LIMIT, timeLimitFunction); function timeLimitFunction(evt:IKEvent):void { trace("timeLimit hit"); trace("time is " + evt.time); trace("distance is " + evt.distance); trace("iterationCount is " + evt.iterationCount); trace("IKJoint is " + evt.joint.name); }

ltima atualizao em 29/3/2011

336

Captulo 17: Trabalho em 3D (trs dimenses)

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior

Noes bsicas de 3D
Flash Player 10 e posterior, Adobe AIR 1.5 e posterior A principal diferena entre um objeto bidimensional (2D) e um objeto tridimensional (3D) projetados em uma tela bidimensional a adio de uma terceira dimenso ao objeto. A terceira dimenso permite que o objeto se aproxime ou se afaste do ponto de viso do usurio. Quando voc define explicitamente a propriedade z de um objeto de exibio com um valor numrico, o objeto automaticamente cria uma matriz de transformao 3D. possvel alterar essa matriz para modificar as configuraes de transformao 3D do objeto. Alm disso, a rotao 3D diferente da rotao 2D. Em 2D, o eixo de rotao est sempre perpendicular ao plano x/y - em outras palavras, ele est no eixo z. Em 3D, o eixo de rotao pode estar em torno de qualquer um dos eixos x, y ou z. Definir as propriedades de rotao e dimensionamento de um objeto de exibio permite que ele se mova no espao 3D. Conceitos e termos importantes A lista de referncia a seguir contm termos importantes que voc vai encontrar ao conhecer o grfico de programao em trs dimenses:
Perspectiva Em um plano 2D, a representao de linhas paralelas como convergentes em um ponto de fuga para dar

a iluso de profundidade e distncia.

Projeo A produo de uma imagem 2D de um objeto de dimenses maiores; a projeo 3D mapeia pontos 3D para

um plano 2D.
Rotao Alterar a orientao (e, muitas vezes, a posio) de um objeto movendo cada ponto includo nele em movimento circular. Transformao Alterar pontos 3D ou conjuntos de pontos por translao, rotao, escala, inclinao ou uma

combinao destas aes.

Translao Alterar a posio de um objeto movendo cada ponto includo nele da mesma forma e na mesma direo. Ponto de fuga Ponto em que linhas paralelas recuadas parecem se encontrar quando representadas em perspectiva

linear.
Vetor Um vetor 3D representa um ponto ou um local no espao tridimensional com as coordenadas cartesianas x, y e z. Vrtice Um ponto de canto. Malha com textura Qualquer ponto que define um objeto no espao 3D.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho em 3D (trs dimenses)

337

Mapeamento UV Uma forma de aplicar textura ou bitmap a uma superfcie 3D. O mapeamento UV atribui valores a coordenadas de uma imagem como porcentagens dos eixos horizontal (U) e vertical (V). valor T O fator de dimensionamento para determinar o tamanho de um objeto 3D medida que ele se aproxima, ou

se afasta, do ponto de viso atual.

Remoo Renderizao, ou no, de superfcies com contorno especfico. O uso da remoo pode ocultar superfcies

que no esto visveis para o ponto de viso atual.

Noes bsicas sobre os recursos 3D do Flash Player e o runtime do AIR

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Nas verses do Flash Player anteriores ao Flash Player 10 e nas verses do Adobe AIR anteriores ao Adobe AIR 1.5, os objetos de exibio tm duas propriedades, x e y, para posicion-los em um plano 2D. A partir do Flash Player 10 e do Adobe AIR 1.5, todo objeto de exibio do ActionScript tem uma propriedade z que permite posicion-lo ao longo do eixo z, normalmente usado para indicar profundidade ou distncia. O Flash Player 10 e o Adobe AIR 1.5 introduziram o suporte para efeitos 3D. No entanto, os objetos de exibio so inerentemente planos. Cada objeto de exibio, como MovieClip ou Sprite, basicamente renderiza-se em duas dimenses em um nico plano. Os recursos 3D permitem colocar, movimentar, girar e transformar todos esses objetos planos em tridimensionais. Eles tambm permitem gerenciar pontos 3D e convert-los em coordenadas x, y 2D para que voc possa projetar objetos 3D em uma exibio 2D. possvel simular muitos tipos de experincias 3D usando esses recursos. O sistema de coordenadas 3D usado pelo ActionScript difere do de outros sistemas. Quando so usadas coordenadas 2D no ActionScript, o valor de x aumenta medida que voc vai para a direita no eixo x, e o valor de y aumenta conforme voc percorre o eixo y. O sistema de coordenadas 3D retm essas convenes e adiciona um eixo z cujo valor aumenta medida que voc se afasta do ponto de viso.
A

(0,0,0)
C B

As direes positivas dos eixos x, y e z no sistema de coordenadas 3D do ActionScript. A. Eixo +Z B. Origem C. Eixo +X D. Eixo +Y

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho em 3D (trs dimenses)

338

Nota: O Flash Player e o AIR sempre representam 3D em camadas. Isso significa que, se o objeto A est na frente do objeto B na lista de exibio, o Flash Player ou o AIR sempre renderiza A na frente de B, independentemente dos valores do eixo z dos dois objetos. Para resolver este conflito entre a ordem na lista de exibio e a ordem no eixo z, use o mtodo transform.getRelativeMatrix3D() para salvar e reordenar as camadas de objetos de exibio 3D. Para obter mais informaes, consulte Uso de objetos Matrix3D para reordenar a exibio na pgina 347. As seguintes classes do ActionScript do suporte aos novos recursos relacionados a 3D:
1 A classe flash.display.DisplayObject contm a propriedade z e novas propriedades de rotao e dimensionamento

para manipular objetos de exibio no espao 3D. O mtodo DisplayObject.local3DToGlobal() oferece uma maneira simples de projetar geometria 3D em um plano 2D.
2 A classe flash.geom.Vector3D pode ser usada como estrutura de dados para gerenciar pontos 3D. Ela tambm

oferece suporte para matemtica de vetores.

3 A classe flash.geom.Matrix3D d suporte a transformaes complexas de geometria 3D, como rotao,

dimensionamento e translao.
4 A classe flash.geom.PerspectiveProjection controla os parmetros para mapear geometria 3D em uma exibio 2D.

Existem duas abordagens distintas para simular imagens 3D no ActionScript:

1 Organizar e animar objetos planos no espao 3D. Esta abordagem envolve animar objetos de exibio usando as

propriedades x, y e z de objetos de exibio ou definir propriedades de rotao e dimensionamento utilizando a classe DisplayObject. possvel obter movimentos mais complexos usando o objeto DisplayObject.transform.matrix3D. O objeto DisplayObject.transform.perspectiveProjection personaliza a forma como os objetos de exibio so desenhados em perspectiva 3D. Use esta abordagem quando quiser animar objetos 3D formados principalmente por planos. Exemplos desta abordagem incluem galerias de imagens 3D ou objetos de animao 2D organizados no espao 3D.
2 Gerar tringulos 2D a partir de geometria 3D e renderiz-los com texturas. Para usar esta abordagem, primeiro voc

deve definir e gerenciar dados sobre objetos 3D e, em seguida, converter esses dados em tringulos 2D para fins de renderizao. possvel mapear texturas de bitmap para esses tringulos, e depois eles so desenhados em um objeto grfico atravs do mtodo Graphics.drawTriangles(). Exemplos desta abordagem incluem carregar dados de modelo 3D a partir de um arquivo e renderizar o modelo na tela ou gerar e desenhar um terreno 3D como malhas de tringulo.

Criao e movimentao de objetos 3D

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Para converter um objeto de exibio 2D em um objeto de exibio 3D, voc pode definir explicitamente a propriedade z correspondente com um valor numrico. Quando voc atribui um valor para a propriedade z, criado um novo objeto Transform para o objeto de exibio. Definir as propriedades DisplayObject.rotationX ou DisplayObject.rotationY tambm cria um novo objeto Transform. O objeto Transform contm uma propriedade Matrix3D que determina como o objeto de exibio representado no espao 3D. O seguinte cdigo define as coordenadas para um objeto de exibio chamado leaf (folha):
leaf.x = 100; leaf.y = 50; leaf.z = -30;

Voc pode ver estes valores, bem como as propriedades derivadas deles, na propriedade matrix3D do objeto Transform da folha:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho em 3D (trs dimenses)

339

var leafMatrix:Matrix3D

= leaf.transform.matrix3D;

trace(leafMatrix.position.x); trace(leafMatrix.position.y); trace(leafMatrix.position.z); trace(leafMatrix.position.length); trace(leafMatrix.position.lengthSquared);

Para obter informaes sobre as propriedades do objeto Transform, consulte a classe Transform. Para obter informaes sobre as propriedades do objeto Matrix3D, consulte a classe Matrix3D.

Movimentao de um objeto no espao 3D

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior possvel movimentar um objeto no espao 3D alterando os valores de suas propriedades x, y ou z. Quando voc altera o valor da propriedade z, o objeto parece aproximar-se ou afastar-se do visualizador. O cdigo a seguir movimenta duas elipses para frente e para trs ao longo dos eixos z alterando o valor das respectivas propriedades z em resposta a um evento. ellipse2 movimenta-se mais rpido do que ellipse1: sua propriedade z aumentada por um mltiplo de 20 em cada evento Frame, enquanto a propriedade z de ellipse1 aumentada por um mltiplo de 10:
var depth:int = 1000; function ellipse1FrameHandler(e:Event):void { ellipse1Back = setDepth(e, ellipse1Back); e.currentTarget.z += ellipse1Back * 10; } function ellipse2FrameHandler(e:Event):void { ellipse2Back = setDepth(e, ellipse1Back); e.currentTarget.z += ellipse1Back * 20; } function setDepth(e:Event, d:int):int { if(e.currentTarget.z > depth) { e.currentTarget.z = depth; d = -1; } else if (e.currentTarget.z < 0) { e.currentTarget.z = 0; d = 1; } }

Rotao de um objeto no espao 3D

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior possvel girar um objeto de trs formas diferentes, dependendo de como voc definir as propriedades de rotao do objeto: rotationX, rotationY e rotationZ.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho em 3D (trs dimenses)

340

A figura abaixo mostra dois quadrados que no so girados:

A prxima figura mostra os dois quadrados quando voc incrementa a propriedade rotationY do continer dos quadrados para gir-los no eixo y. Girar o continer, ou o objeto de exibio pai, dos dois quadrados gira ambos os quadrados:
container.rotationY += 10;

A prxima figura mostra o que acontece quando voc define a propriedade rotationX do continer dos quadrados. Isso gira os quadrados no eixo x.

A prxima figura mostra o que acontece quando voc incrementa a propriedade rotationZ do continer dos quadrados. Isso gira os quadrados no eixo z.

Um objeto de exibio pode, ao mesmo tempo, se movimentar e girar no espao 3D.

Projeo de objetos 3D em uma exibio 2D

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior A classe PerspectiveProjection do pacote flash.geom oferece uma maneira simples de aplicar perspectiva rudimentar quando voc movimenta objetos de exibio pelo espao 3D.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho em 3D (trs dimenses)

341

Caso voc no crie uma projeo em perspectiva para o espao 3D explicitamente, o mecanismo 3D usar um objeto PerspectiveProjection padro que existe na raiz e propagado para todos os seus filhos. As trs propriedades que definem como um objeto PerspectiveProjection exibe o espao 3D so:

fieldOfView projectionCenter focalLength

Modificar o valor de fieldOfView modifica automaticamente o valor de focalLength e vice-versa, uma vez que elas so interdependentes. A frmula usada para calcular a propriedade focalLength considerando-se o valor de fieldOfView a seguinte:
focalLength = stageWidth/2 * (cos(fieldOfView/2) / sin(fieldOfView/2)

Normalmente voc modificaria a propriedade fieldOfView de maneira explcita.

Campo de viso
Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Manipulando a propriedade fieldOfView da classe PerspectiveProjection, possvel fazer com que um objeto de exibio 3D que est se aproximando do visualizador parea maior e com que um objeto que est se afastando do visualizador parea menor. A propriedade fieldOfView especifica um ngulo entre 0 e 180 graus que determina a intensidade da projeo em perspectiva. Quanto maior o valor, mais intensa a distoro aplicada a um objeto de exibio que se movimenta em seu eixo z. Um valor baixo de fieldOfView resulta em um dimensionamento muito pequeno e faz com que os objetos paream se movimentar apenas um pouco para trs no espao. Um valor alto de fieldOfView gera mais distoro e o aspecto de maior movimento. O valor mximo de 179,9999... graus resulta em um efeito extremo da lente de olho de peixe. O valor mximo de fieldOfView 179,9999... e o mnimo 0,00001... 0 e 180 exatos so valores invlidos.

Centro da projeo
Flash Player 10 e posterior, Adobe AIR 1.5 e posterior A propriedade projectionCenter representa o ponto de fuga na projeo em perspectiva. Ela aplicada como um deslocamento at o ponto de registro padro (0,0) no canto superior esquerdo do palco. Conforme um objeto parece se afastar do visualizador, ele se movimenta em direo ao ponto de fuga e, por fim, desaparece. Imagine um corredor infinitamente longo. Quando voc olha para o final dele, as extremidades das paredes se convergem em um ponto de fuga no final do corredor. Se o ponto de fuga est no centro do palco, o corredor desaparece em direo a um ponto no centro. O valor padro da propriedade projectionCenter o centro do palco. Se, por exemplo, voc quiser que os elementos apaream no lado esquerdo do palco e que uma rea 3D aparea no lado direito, defina projectionCenter como um ponto no lado direito do palco para torn-lo o ponto de fuga da sua rea de exibio 3D.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho em 3D (trs dimenses)

342

Distncia focal
Flash Player 10 e posterior, Adobe AIR 1.5 e posterior A propriedade focalLength representa a distncia entre a origem do ponto de viso (0,0,0) e a localizao do objeto de exibio em seu eixo z. Uma distncia focal longa como uma teleobjetiva com uma visualizao limitada e distncias reduzidas entre objetos. Uma distncia focal curta como uma lente com grande abertura angular, com a qual voc tem uma visualizao ampla com muita distoro. Uma distncia focal mdia assemelha-se ao que os olhos humanos vem. Normalmente, a propriedade focalLength recalculada dinamicamente durante a transformao de perspectiva medida que o objeto de exibio se movimenta, mas possvel defini-la de forma explcita.

Valores padro da projeo em perspectiva

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior O objeto PerspectiveProjection padro criado na raiz tem os seguintes valores:

fieldOfView: 55 perspectiveCenter: stagewidth/2, stageHeight/2 focalLength: stageWidth/ 2 * ( cos(fieldOfView/2) / sin(fieldOfView/2) )

Esses so os valores que sero utilizados se voc no criar seu prprio objeto PerspectiveProjection. possvel instanciar seu prprio objeto PerspectiveProjection com a inteno de voc mesmo modificar projectionCenter e fieldOfView. Nesse caso, os valores padro do objeto recm-criado so os seguintes, de acordo com um tamanho de palco padro de 500 por 500:

fieldOfView: 55 perspectiveCenter: 250,250 focalLength: 480.24554443359375

Exemplo: Projeo em perspectiva

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior O exemplo a seguir demonstra o uso da projeo em perspectiva para criar o espao 3D. Ele mostra como voc pode modificar o ponto de fuga e alterar a projeo em perspectiva do espao atravs da propriedade projectionCenter. Essa modificao fora o reclculo das propriedades focalLength e fieldOfView com a distoro concomitante do espao 3D. Este exemplo:
1 Cria uma entidade grfica chamada center, como um crculo com cruzes 2 Atribui as coordenadas da entidade grfica center propriedade projectionCenter da

propriedadeperspectiveProjection da propriedade transform da raiz

3 Adiciona ouvintes de eventos para eventos de mouse que chamam manipuladores que modificam a propriedade
projectionCenter para que ela siga a localizao do objeto center

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho em 3D (trs dimenses)

343

4 Cria quatro caixas com o estilo acordeo que formam as paredes do espao em perspectiva

Quando voc testar este exemplo, ProjectionDragger.swf, arraste o crculo para diferentes locais. O ponto de fuga segue o crculo, parando no lugar em que voc solt-lo. Observe as caixas que circundam o espao se alongam e se tornam distorcidas quando voc afasta o centro de projeo do centro do palco. Para obter os arquivos de aplicativo deste exemplo, consulte www.adobe.com/go/learn_programmingAS3samples_flash_br. Os arquivos do aplicativo ProjectionDragger esto na pasta Samples/ProjectionDragger.
package { import flash.display.Sprite; import flash.display.Shape; import flash.geom.Point; import flash.events.*; public class ProjectionDragger extends Sprite { private var center : Sprite; private var boxPanel:Shape; private var inDrag:Boolean = false; public function ProjectionDragger():void { createBoxes(); createCenter(); } public function createCenter():void { var centerRadius:int = 20; center = new Sprite(); // circle center.graphics.lineStyle(1, 0x000099); center.graphics.beginFill(0xCCCCCC, 0.5); center.graphics.drawCircle(0, 0, centerRadius); center.graphics.endFill(); // cross hairs center.graphics.moveTo(0, centerRadius); center.graphics.lineTo(0, -centerRadius); center.graphics.moveTo(centerRadius, 0); center.graphics.lineTo(-centerRadius, 0); center.x = 175; center.y = 175; center.z = 0; this.addChild(center); center.addEventListener(MouseEvent.MOUSE_DOWN, startDragProjectionCenter); center.addEventListener(MouseEvent.MOUSE_UP, stopDragProjectionCenter); center.addEventListener( MouseEvent.MOUSE_MOVE, doDragProjectionCenter); root.transform.perspectiveProjection.projectionCenter = new Point(center.x, center.y); } public function createBoxes():void { // createBoxPanel();

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho em 3D (trs dimenses)

344

var var var var

boxWidth:int = 50; boxHeight:int = 50; numLayers:int = 12; depthPerLayer:int = 50;

boxHeight, boxHeight, boxHeight, boxHeight, }

// var boxVec:Vector.<Shape> = new Vector.<Shape>(numLayers); for (var i:int = 0; i < numLayers; i++) { this.addChild(createBox(150, 50, (numLayers - i) * depthPerLayer, boxWidth, 0xCCCCFF)); this.addChild(createBox(50, 150, (numLayers - i) * depthPerLayer, boxWidth, 0xFFCCCC)); this.addChild(createBox(250, 150, (numLayers - i) * depthPerLayer, boxWidth, 0xCCFFCC)); this.addChild(createBox(150, 250, (numLayers - i) * depthPerLayer, boxWidth, 0xDDDDDD)); }

public function createBox(xPos:int = 0, yPos:int = 0, zPos:int = 100, w:int = 50, h:int = 50, color:int = 0xDDDDDD):Shape { var box:Shape = new Shape(); box.graphics.lineStyle(2, 0x666666); box.graphics.beginFill(color, 1.0); box.graphics.drawRect(0, 0, w, h); box.graphics.endFill(); box.x = xPos; box.y = yPos; box.z = zPos; return box; } public function startDragProjectionCenter(e:Event) { center.startDrag(); inDrag = true; } public function doDragProjectionCenter(e:Event) { if (inDrag) { root.transform.perspectiveProjection.projectionCenter = new Point(center.x, center.y); } } public function stopDragProjectionCenter(e:Event) { center.stopDrag(); root.transform.perspectiveProjection.projectionCenter = new Point(center.x, center.y); inDrag = false; } } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho em 3D (trs dimenses)

345

Para projeo em perspectiva mais complexa, use a classe Matrix3D.

Execuo de transformaes 3D complexas

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior A classe Matrix3D permite transformar pontos 3D dentro de um espao de coordenadas ou mapear pontos 3D de um espao de coordenadas para outro. Voc no precisa conhecer a matemtica de matrizes para usar a classe Matrix3D. A maior parte das operaes de transformao comuns pode ser feita usando-se os mtodos da classe. Voc no precisa se preocupar em definir ou calcular explicitamente os valores de cada elemento da matriz. Depois de definir a propriedade z de um objeto de exibio como um valor numrico, voc pode recuperar a matriz de transformao dele usando a propriedade Matrix3D do objeto Transform do objeto de exibio:
var leafMatrix:Matrix3D = this.transform.matrix3D;

Voc pode usar os mtodos do objeto Matrix3D para executar translao, rotao, dimensionamento e projeo em perspectiva no objeto de exibio. Use a classe Vector3D com suas propriedades x, y e z para gerenciar pontos 3D. Ela tambm pode representar um vetor espacial na fsica, que tem uma direo e uma magnitude. Os mtodos da classe Vector3D permitem executar clculos comuns com vetores espaciais, como clculos de adio, produto escalar e produto complementar. Nota: A classe Vector3D no est relacionada classe Vector do ActionScript. A classe Vector3D contm propriedades e mtodos para definir e manipular pontos 3D, enquanto a classe Vector oferece suporte a matrizes de objetos com tipo.

Criao de objetos Matrix3D

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior H trs maneiras de criar ou recuperar objetos Matrix3D:
1 Use o mtodo do construtor Matrix3D() para instanciar uma nova matriz. O construtor Matrix3D() toma um

objeto Vector que contm 16 valores numricos e coloca cada valor em uma clula da matriz. Por exemplo:
var rotateMatrix:Matrix3D = new Matrix3D(1,0,0,1, 0,1,0,1, 0,0,1,1, 0,0,0,1);

2 Defina o valor da propriedade z de um objeto de exibio. Em seguida, recupere a matriz de transformao da

propriedade transform.matrix3D desse objeto.

3 Recupere o objeto Matrix3D que controla a exibio de objetos 3D no palco obtendo o valor da propriedade
perspectiveProjection.matrix3D do objeto de exibio raiz.

Aplicao de vrias transformaes 3D

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior possvel aplicar muitas transformaes 3D de uma s vez usando um objeto Matrix3D. Por exemplo, para girar, dimensionar e, depois, movimentar um cubo, voc pode aplicar trs transformaes separadas a cada ponta do cubo. No entanto, muito mais eficiente pr-calcular vrias transformaes em um objeto Matrix3D e, em seguida, executar uma transformao de matriz em cada uma das pontas.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho em 3D (trs dimenses)

346

Nota: A ordem em que as transformaes de matriz so aplicadas importante. Os clculos de matriz no so comutativos. Por exemplo, o resultado de aplicar uma rotao seguida de uma translao diferente do resultado de aplicar a mesma translao seguida da mesma rotao. O exemplo a seguir mostra duas maneiras de executar vrias transformaes 3D.
package { import import import import flash.display.Sprite; flash.display.Shape; flash.display.Graphics; flash.geom.*;

public class Matrix3DTransformsExample extends Sprite { private var rect1:Shape; private var rect2:Shape; public function Matrix3DTransformsExample():void { var pp:PerspectiveProjection = this.transform.perspectiveProjection; pp.projectionCenter = new Point(275,200); this.transform.perspectiveProjection = pp; rect1 = new Shape(); rect1.x = -70; rect1.y = -40; rect1.z = 0; rect1.graphics.beginFill(0xFF8800); rect1.graphics.drawRect(0,0,50,80); rect1.graphics.endFill(); addChild(rect1); rect2 = new Shape(); rect2.x = 20; rect2.y = -40; rect2.z = 0; rect2.graphics.beginFill(0xFF0088); rect2.graphics.drawRect(0,0,50,80); rect2.graphics.endFill(); addChild(rect2);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho em 3D (trs dimenses)

347

doTransforms(); } private function doTransforms():void { rect1.rotationX = 15; rect1.scaleX = 1.2; rect1.x += 100; rect1.y += 50; rect1.rotationZ = 10; var matrix:Matrix3D = rect2.transform.matrix3D; matrix.appendRotation(15, Vector3D.X_AXIS); matrix.appendScale(1.2, 1, 1); matrix.appendTranslation(100, 50, 0); matrix.appendRotation(10, Vector3D.Z_AXIS); rect2.transform.matrix3D = matrix; } } }

No mtodo doTransforms(), o primeiro bloco de cdigo usa as propriedades DisplayObject para alterar a rotao, o dimensionamento e a posio de uma forma de retngulo. O segundo bloco de cdigo usa os mtodos da classe Matrix3D para fazer as mesmas transformaes. A principal vantagem de usar os mtodos Matrix3D que todos os clculos so realizados primeiro na matriz. Em seguida, eles so aplicados ao objeto de exibio apenas uma vez, quando sua propriedade transform.matrix3D definida. Configurar propriedades DisplayObject torna a leitura do cdigo-fonte um pouco mais simples. Todavia, sempre que definida uma propriedade de rotao ou dimensionamento, ela gera vrios clculos e altera diversas propriedades do objeto de exibio. Se o seu cdigo aplicar as mesmas transformaes complexas a objetos de exibio mais de uma vez, salve o objeto Matrix3D como uma varivel e, em seguida, aplique-o de novo repetidas vezes.

Uso de objetos Matrix3D para reordenar a exibio

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Conforme mencionado anteriormente, a ordem em camadas dos objetos de exibio na lista de exibio determina a ordem em camadas da exibio, independentemente dos eixos x relacionados. Se a sua animao transforma as propriedades de objetos de exibio em uma ordem diferente da ordem da lista de exibio, o visualizador poder ver os objetos de exibio em uma disposio em camadas que no corresponde disposio em camadas no eixo z. Por isso, um objeto que deve parecer mais distante do visualizador pode aparecer na frente de um objeto que est mais perto do visualizador. Para assegurar que a disposio em camadas dos objetos de exibio 3D corresponda s profundidades relativas dos objetos, use uma abordagem como a seguinte:
1 Use o mtodo getRelativeMatrix3D() do objeto Transform para obter os eixos z relacionados dos objetos de

exibio 3D filho.
2 Use o mtodo removeChild() para remover os objetos da lista de exibio. 3 Classifique os objetos de exibio com base nos valores do eixo z relacionado. 4 Use o mtodo addChild() para adicionar os filhos de volta lista de exibio na ordem inversa.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho em 3D (trs dimenses)

348

Essa reordenao assegura que seus objetos sero exibidos de acordo com os eixos z relacionados. O cdigo a seguir fora a exibio correta das seis faces de uma caixa 3D. Ele reordena as faces da caixa depois que rotaes foram aplicadas a ela:
public var faces:Array; . . . public function ReorderChildren() { for(var ind:uint = 0; ind < 6; ind++) { faces[ind].z = faces[ind].child.transform.getRelativeMatrix3D(root).position.z; this.removeChild(faces[ind].child); } faces.sortOn("z", Array.NUMERIC | Array.DESCENDING); for (ind = 0; ind < 6; ind++) { this.addChild(faces[ind].child); } }

Para obter os arquivos de aplicativo deste exemplo, consulte www.adobe.com/go/learn_programmingAS3samples_flash_br. Os arquivos do aplicativo esto na pasta Samples/ReorderByZ.

Uso de tringulos para obter efeitos 3D

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior No ActionScript, voc executa transformaes de bitmap usando o mtodo Graphics.drawTriangles(), pois os modelos 3D so representados por um conjunto de tringulos no espao. (Contudo, o Flash Player e o AIR no do suporte a um buffer de profundidade, por isso os objetos de exibio so inerentemente planos, ou 2D. Isto descrito em Noes bsicas sobre os recursos 3D do Flash Player e o runtime do AIR na pgina 337.) O mtodo Graphics.drawTriangles() parecido com o mtodo Graphics.drawPath() no sentido de que usa um conjunto de coordenadas para desenhar um caminho de tringulo. Para se familiarizar com o uso de Graphics.drawPath(), consulte Caminhos de desenho na pgina 228. O mtodo Graphics.drawTriangles() usa um Vector.<Number> para especificar as localizaes das pontas para o caminho do tringulo:
drawTriangles(vertices:Vector.<Number>, indices:Vector.<int> = null, uvtData:Vector.<Number> = null, culling:String = "none"):void

O primeiro parmetro de drawTriangles() o nico necessrio: o parmetro vertices. Este parmetro um vetor de nmeros que define as coordenadas atravs das quais os seus tringulos so desenhados. Cada trs conjuntos de coordenadas (seis nmeros) representa um caminho de tringulo. Sem o parmetro indices, o comprimento do vetor deve sempre ser um fator de seis, uma vez que cada tringulo requer trs pares de coordenadas (trs conjuntos de dois valores x/y). Por exemplo:
graphics.beginFill(0xFF8000); graphics.drawTriangles( Vector.<Number>([ 10,10, 100,10, 10,100, 110,10, 110,100, 20,100]));

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho em 3D (trs dimenses)

349

Nenhum desses tringulos compartilham pontas, mas, se compartilhassem, o segundo parmetro de drawTriangles(), indices, poderia ser usado para reutilizar valores do vetor vertices para mais de um tringulo. Quando usar o parmetro indices, importante que voc saiba que os valores de indices so ndices de pontos e no ndices relacionados diretamente aos elementos de matriz vertices. Em outras palavras, um ndice no vetor vertices conforme definido por indices , na verdade, o ndice real dividido por 2. Para a terceira ponta de um vetor vertices, por exemplo, use um valor de 2 para indices, mesmo que o primeiro valor numrico dessa ponta comece no ndice de vetor de 4. Por exemplo, mescle dois tringulos para que compartilhem a aresta diagonal usando o parmetro indices:
graphics.beginFill(0xFF8000); graphics.drawTriangles( Vector.<Number>([10,10, 100,10, 10,100, 100,100]), Vector.<int>([0,1,2, 1,3,2]));

Observe que, apesar de agora ter sido desenhado um quadrado usando-se dois tringulos, somente quatro pontas foram especificadas no vetor vertices. Usando indices, as duas pontas compartilhadas pelos dois tringulos so reutilizadas para cada tringulo. Isso diminui a contagem geral de vrtices de 6 (12 nmeros) para 4 (8 nmeros):

Um quadrado desenhado com dois tringulos usando o parmetro vertices

Esta tcnica torna-se til com malhas de tringulos maiores, onde a maioria das pontas so compartilhadas por vrios tringulos. Todos os preenchimentos podem ser aplicados a tringulos. Os preenchimentos so aplicados malha de tringulos resultante, assim como ocorre com qualquer outra forma.

Transformao de bitmaps
Flash Player 10 e posterior, Adobe AIR 1.5 e posterior As transformaes de bitmap do a iluso de perspectiva ou "textura" em um objeto tridimensional. Especificamente, voc pode distorcer um bitmap em direo a um ponto de fuga de modo que a imagem parea diminuir medida que se aproxima do ponto de fuga. Se preferir, voc pode usar um bitmap bidimensional para criar uma superfcie para um objeto tridimensional, dando a iluso de textura ou wrapping nesse objeto 3D.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho em 3D (trs dimenses)

350

Uma superfcie bidimensional usando um ponto de fuga e um objeto tridimensional delimitado com um bitmap.

Mapeamento UV
Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Depois que comear a trabalhar com texturas, voc desejar usar o parmetro uvtData de drawTriangles(). Esse parmetro permite configurar o mapeamento UV para preenchimentos de bitmap. O mapeamento UV um mtodo de aplicar textura a objetos. Ele se baseia em dois valores: um valor horizontal U (x) e um valor vertical V (y). Em vez de serem baseados em valores de pixel, eles so baseados em porcentagens. 0 U e 0 V o canto superior esquerdo de uma imagem, e 1 U e 1 V o canto inferior direito:

As localizaes UV 0 e 1 em uma imagem de bitmap

Os vetores de um tringulo podem receber coordenadas UV para se associarem s respectivas localizaes em uma imagem:

As coordenadas UV de uma rea triangular de uma imagem de bitmap

Os valores UV permanecem consistentes com as pontas do tringulo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho em 3D (trs dimenses)

351

Os vrtices do tringulo so movimentados e o bitmap distorcido para manter iguais os valores UV de uma ponta individual

Conforme transformaes 3D do ActionScript so aplicadas ao tringulo associado ao bitmap, a imagem do bitmap aplicada ao tringulo com base nos valores UV. Portanto, em vez de usar clculos de matriz, defina ou ajuste os valores UV para criar um efeito tridimensional. O mtodo Graphics.drawTriangles() tambm aceita uma informao opcional para transformaes tridimensionais: o valor T. O valor T em uvtData representa a perspectiva 3D ou, mais especificamente, o fator de escala do vrtice associado. O mapeamento UVT adiciona correo de perspectiva ao mapeamento UV. Por exemplo, se um objeto estiver posicionado no espao 3D longe do ponto de viso, de modo que parea ter 50% de seu tamanho original, o valor T desse objeto ser 0,5. Uma vez que tringulos so desenhados para representar objetos no espao 3D, sua localizao no eixo z determina seus valores T. A equao que determina o valor T a seguinte:
T = focalLength/(focalLength + z);

Nesta equao, focalLength representa uma distncia focal ou uma localizao "na tela" calculada, que determina o grau da perspectiva observado na exibio.
A B C

A distncia focal e o valor z A. ponto de viso B. tela C. Objeto 3D D. valor de focalLength E. valor z

O valor de T usado para dimensionar formas bsicas para fazer com que paream mais distantes. Normalmente o valor usado para converter pontos 3D em pontos 2D. No caso de dados UVT, tambm usado para dimensionar um bitmap entre as pontas de um tringulo com perspectiva. Quando voc define valores UVT, o valor T segue diretamente os valores UV definidos para um vrtice. Com a incluso de T, cada trs valores no parmetro uvtData (U, V e T) correspondem a cada dois valores no parmetro vertices (x e y). Com valores UV apenas, uvtData.length == vertices.length. Com a incluso de um valor T, uvtData.length = 1,5*vertices.length. O exemplo a seguir mostra um plano sendo girado no espao 3D usando dados UVT. Este exemplo usa uma imagem chamada ocean.jpg e uma classe auxiliar (ImageLoader) para carregar a imagem de maneira que ela possa ser atribuda ao objeto BitmapData.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho em 3D (trs dimenses)

352

Este o cdigo-fonte da classe ImageLoader (salve-o em um arquivo chamado ImageLoader.as):

package { import flash.display.* import flash.events.*; import flash.net.URLRequest; public class ImageLoader extends Sprite { public var url:String; public var bitmap:Bitmap; public function ImageLoader(loc:String = null) { if (loc != null){ url = loc; loadImage(); } } public function loadImage():void{ if (url != null){ var loader:Loader = new Loader(); loader.contentLoaderInfo.addEventListener(Event.COMPLETE, onComplete); loader.contentLoaderInfo.addEventListener(IOErrorEvent.IO_ERROR, onIoError); var req:URLRequest = new URLRequest(url); loader.load(req); } } private function onComplete(event:Event):void { var loader:Loader = Loader(event.target.loader); var info:LoaderInfo = LoaderInfo(loader.contentLoaderInfo); this.bitmap = info.content as Bitmap; this.dispatchEvent(new Event(Event.COMPLETE)); } private function onIoError(event:IOErrorEvent):void { trace("onIoError: " + event); } } }

E este o ActionScript que usa tringulos, mapeamento UV e valores T para fazer com que a imagem parea estar diminuindo medida que se aproxima de um ponto de fuga e girando. Salve este cdigo em um arquivo denominado Spinning3dOcean.as:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho em 3D (trs dimenses)

353

package { import flash.display.* import flash.events.*; import flash.utils.getTimer; public class Spinning3dOcean extends Sprite { // plane vertex coordinates (and t values) var x1:Number = -100,y1:Number = -100,z1:Number = 0,t1:Number = 0; var x2:Number = 100,y2:Number = -100,z2:Number = 0,t2:Number = 0; var x3:Number = 100,y3:Number = 100,z3:Number = 0,t3:Number = 0; var x4:Number = -100,y4:Number = 100,z4:Number = 0,t4:Number = 0; var focalLength:Number = 200; // 2 triangles for 1 plane, indices will always be the same var indices:Vector.<int>; var container:Sprite; var bitmapData:BitmapData; // texture var imageLoader:ImageLoader; public function Spinning3dOcean():void { indices = new Vector.<int>(); indices.push(0,1,3, 1,2,3); container = new Sprite(); // container to draw triangles in container.x = 200; container.y = 200; addChild(container); imageLoader = new ImageLoader("ocean.jpg"); imageLoader.addEventListener(Event.COMPLETE, onImageLoaded); } function onImageLoaded(event:Event):void { bitmapData = imageLoader.bitmap.bitmapData; // animate every frame addEventListener(Event.ENTER_FRAME, rotatePlane); } function rotatePlane(event:Event):void { // rotate vertices over time var ticker = getTimer()/400; z2 = z3 = -(z1 = z4 = 100*Math.sin(ticker)); x2 = x3 = -(x1 = x4 = 100*Math.cos(ticker)); // calculate t values

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho em 3D (trs dimenses)

354

t1 t2 t3 t4

= = = =

focalLength/(focalLength focalLength/(focalLength focalLength/(focalLength focalLength/(focalLength

+ + + +

z1); z2); z3); z4);

// determine triangle vertices based on t values var vertices:Vector.<Number> = new Vector.<Number>(); vertices.push(x1*t1,y1*t1, x2*t2,y2*t2, x3*t3,y3*t3, x4*t4,y4*t4); // set T values allowing perspective to change // as each vertex moves around in z space var uvtData:Vector.<Number> = new Vector.<Number>(); uvtData.push(0,0,t1, 1,0,t2, 1,1,t3, 0,1,t4); // draw container.graphics.clear(); container.graphics.beginBitmapFill(bitmapData); container.graphics.drawTriangles(vertices, indices, uvtData); } } }

Para testar este exemplo, salve esses dois arquivos de classe no mesmo diretrio de uma imagem chamada ocean.jpg. Voc pode ver como o bitmap original transformado para dar a impresso de que ele est desaparecendo conforme aumenta a distncia e girando no espao 3D.

Remoo
Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Remoo o processo que determina quais superfcies de um objeto tridimensional o renderizador no deve renderizar pelo fato de estarem ocultas do ponto de viso atual. No espao 3D, a superfcie na parte de trs de um objeto tridimensional fica oculta do ponto de viso:
A B

A parte de trs de um objeto 3D fica oculta do ponto de viso. A. ponto de viso B. objeto 3D C. a parte de trs de um objeto tridimensional

Inerentemente, todos os tringulos sempre so renderizados, seja qual for o tamanho, a forma ou a posio. A remoo assegura que o Flash Player ou o AIR renderize o objeto 3D corretamente. Alm disso, para ganhar tempo nos ciclos de renderizao, s vezes voc deseja que alguns tringulos sejam ignorados pelo renderizador. Pense em um cubo girando no espao. Em um determinado momento, voc no ver mais do que trs lados desse cubo, uma vez que os lados que no aparecem na exibio estariam voltados para a outra direo no outro lado do cubo. Como esses lados no sero vistos, o renderizados no deve desenh-los. Sem a remoo, o Flash Player ou o AIR renderiza os lados da frente e de trs.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho em 3D (trs dimenses)

355

Um cubo tem lados que no ficam visveis no ponto de viso atual

Por isso, o mtodo Graphics.drawTriangles() tem um quarto parmetro para estabelecer um valor de remoo:
public function drawTriangles(vertices:Vector.<Number>, indices:Vector.<int> = null, uvtData:Vector.<Number> = null, culling:String = "none"):void

O parmetro de remoo um valor da classe de enumerao TriangleCulling: TriangleCulling.NONE, TriangleCulling.POSITIVE e TriangleCulling.NEGATIVE. Esses valores dependem da direo do caminho do tringulo que define a superfcie do objeto. A API do ActionScript para determinar a remoo pressupe que todos os tringulos voltados para fora de uma forma 3D sejam desenhados com a mesma direo de caminho. Uma vez que uma face do tringulo virada, a direo do caminho tambm muda. Nesse ponto, o tringulo pode ser removido (excludo da renderizao). Portanto, um valor POSITIVE deTriangleCulling remove tringulos com direo de caminho positiva (no sentido horrio). Um valor NEGATIVE de TriangleCulling remove tringulos com uma direo de caminho negativa (no sentido anti-horrio). No caso de um cubo, enquanto as superfcies voltadas para frente tm uma direo de caminho positiva, as superfcies traseiras tm uma direo de caminho negativa:

Um cubo aberto para mostrar a direo do caminho. Quando o cubo est fechado, a direo do caminho da parte traseira invertida.

Para ver como funciona a remoo, comece com o exemplo anterior de Mapeamento UV na pgina 350, defina o parmetro de remoo do mtodo drawTriangles() como TriangleCulling.NEGATIVE:
container.graphics.drawTriangles(vertices, indices, uvtData, TriangleCulling.NEGATIVE);

Observe que o lado de trs da imagem no renderizado porque o objeto gira.

ltima atualizao em 29/3/2011

356

Captulo 18: Princpios bsicos do trabalho com texto

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para exibir texto na tela do Adobe Flash Player ou Adobe AIR, use uma instncia da classe TextField ou use as classes Flash Text Engine. Essas classes permitem a criao, exibio e formatao de texto. Como alternativa, possvel usar a Text Layout Framework (TLF) - uma biblioteca de componentes que se baseia nas classes Flash Text Engine, porm projetada para simplificar sua utilizao. possvel estabelecer contedo especfico para campos de texto ou designar a origem do texto e definir sua aparncia. Tambm possvel responder aos eventos do usurio assim que ele insira texto ou clique em um link de hipertexto. A classe TextField e as classes Flash Text Engine lhe permitem exibir e gerenciar o texto no Flash Player e no AIR. Voc pode usar a classe TextField para criar objetos de texto para exibio e insero. TextField fornece os princpios para outros componentes baseados em texto, como TextArea e TextInput. possvel usar a classe TextFormat para definir a formatao dos caracteres e pargrafos dos objetos TextField e aplicar CSS (folhas de estilos em cascata) usando a propriedade Textfield.styeSheet e a classe StyleSheet. possvel designar texto formatado em HTML, que pode conter mdia incorporada (clipes de filme, arquivos SWF, arquivos GIF, arquivos PNG e arquivos JPEG), diretamente para um campo de texto. O Flash Text Engine, disponvel a partir do Flash Player 10 e do Adobe AIR 1.5, apresenta suporte em baixo nvel para o controle sofisticado de mtricas de texto, formatao e texto bidirecional. Oferece tambm fluxo de texto aprimorado e suporte avanado a idioma. Embora voc possa usar o Flash Text Engine para criar e gerenciar os elementos de texto, ele foi projetado principalmente como base para criar componentes de tratamento de texto e exige maior conhecimento de programao. A Text Layout Framework, que inclui um componente de tratamento de texto baseado no Flash Text Engine, fornece uma forma facilitada de usar os recursos avanados do novo mecanismo de texto. A Text Layout Framework uma biblioteca extensvel totalmente integrada ao ActionScript 3.0. possvel usar o componente TLF existente ou usar a estrutura para construir seu prprio componente de texto. Para obter mais informaes sobre esses tpicos, consulte:

Uso da classe TextField na pgina 358 Uso do Flash Text Engine na pgina 383 Uso da Text Layout Framework na pgina 413
Conceitos e termos importantes A lista de referncia a seguir contm termos importantes envolvidos com o tratamento de texto:
Folhas de estilos em cascata Uma sintaxe padro para especificao de estilos e formatao de contedo estruturado

no formato XML (ou HTML).

Fonte do dispositivo Uma fonte instalada na mquina do usurio. Campo de texto dinmico Um campo de texto cujos contedos possam ser alterados pelo ActionScript, mas no pela

entrada do usurio.
Fonte incorporada Uma fonte que tem seus dados de estrutura de tpicos de caracteres armazenados no arquivo SWF

do aplicativo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Princpios bsicos do trabalho com texto

357

Texto HTML Contedo em texto inserido em um campo de texto usando o ActionScript que inclui tags de formatao

HTML junto com o contedo de texto real.

Campo de texto de entrada Um campo de texto cujo contedo pode ser alterado pela entrada do usurio ou pelo

ActionScript.
Kerning Um ajuste de espao entre pares de caracteres a fim de tornar o espaamento em palavras mais proporcional

e o texto mais fcil de ler.

Campo de texto esttico Um campo de texto criado na ferramenta de autoria, cujo contedo no pode ser alterado quando o arquivo SWF est em execuo. Mtricas das linhas de texto Medies do tamanho de vrias partes de texto em um campo de texto, por exemplo, a linha de base do texto, a altura do topo dos caracteres, o tamanho dos descendentes (a parte de algumas letras minsculas que se estendem abaixo da linha de base) e assim por diante. Tracking Um ajuste de espao entre grupos de letras ou blocos de texto para aumentar ou diminuir a densidade e

tornar o texto mais legvel.

ltima atualizao em 29/3/2011

358

Captulo 19: Uso da classe TextField

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc pode usar uma ocorrncia da classe TextField para exibir texto ou criar um campo de entrada de texto na tela no Adobe Flash Player ou no Adobe AIR. A classe TextField o ponto de partida para outros componentes com base em texto, como os componentes TextArea ou TextInput. O contedo do campo de texto pode ser pr-especificado no arquivo SWF, carregado de um arquivo de texto, ou banco de dados, ou inserido por um usurio que interaja com o seu aplicativo. Em um campo de texto, o texto pode aparecer como contedo HTML renderizado, com imagens incorporadas em tal HTML. Depois de criar uma instncia de um campo de texto, possvel usar as classes flash.text como TextFormat e StyleSheet, para controlar a aparncia do texto. O pacote flash.text contm quase todas as classes relacionadas criao, ao gerenciamento e formatao de texto no ActionScript. possvel formatar texto definindo a formatao com um objeto TextFormat e atribuir esse objeto no campo de texto. Se o campo de texto contiver texto HTML, ser possvel aplicar um objeto StyleSheet ao campo de texto para atribuir estilos a partes especficas do contedo do campo de texto. Os objetos TextFormat ou StyleSheet contm propriedades que definem a aparncia do texto, como cor, tamanho e peso. O objeto TextFormat designa as propriedades a todo o contedo dentro de um campo de texto para um intervalo de texto. Por exemplo, no mesmo campo, o texto de uma sentena pode estar em vermelho e negrito, e o da sentena seguinte em azul e itlico. Alm das classes no pacote flash.text, possvel usar a classe flash.events.TextEvent para responder s aes do usurio relacionadas ao texto.

Mais tpicos da Ajuda

Atribuio de formatos de texto na pgina 366 Exibio de texto HTML na pgina 360 Aplicao de folhas de estilos em cascata na pgina 366

Exibio de texto
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Embora as ferramentas de autoria como o Adobe Flash Builder e o Flash Professional apresentem vrias opes de exibio de texto, incluindo componentes relacionados a texto ou ferramentas de texto, o modo mais simples de exibir texto de modo programtico por meio de um campo de texto.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da classe TextField

359

Tipos de texto
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O tipo de texto dentro de um campo caracterizado por sua fonte:

Texto dinmico
O texto dinmico inclui contedo carregado de uma fonte externa, por exemplo, um arquivo de texto, um arquivo XML ou mesmo um servio da Web remoto.

Texto de entrada
Texto de entrada qualquer texto inserido por um usurio ou texto dinmico que um usurio possa editar. possvel configurar uma folha de estilos para formatar texto de entrada ou usar a classe flash.text.TextFormat para atribuir propriedades ao campo de texto do contedo de entrada. Para obter mais informaes, consulte Captura de entrada de texto na pgina 364.

Texto esttico
O texto esttico criado apenas atravs do Flash Professional. No possvel criar uma instncia de texto esttico usando o ActionScript 3.0. No entanto, possvel usar classes ActionScript como StaticText e TextSnapshot para manipular uma instncia de texto esttica. Para obter mais informaes, consulte Trabalho com texto esttico na pgina 372

Modificao de contedos de campo de texto

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc pode definir texto dinmico atribuindo uma sequncia de caracteres propriedade flash.text.TextField.text. Voc designa uma sequncia de caracteres diretamente propriedade, como segue:
myTextField.text = "Hello World";

Tambm possvel designar propriedade text um valor de uma varivel definida no script, como no exemplo a seguir:
package { import flash.display.Sprite; import flash.text.*; public class TextWithImage extends Sprite { private var myTextBox:TextField = new TextField(); private var myText:String = "Hello World"; public function TextWithImage() { addChild(myTextBox); myTextBox.text = myText; } } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da classe TextField

360

Como alternativa, voc pode designar propriedade text um valor de uma varivel remota. Voc tem trs opes para carregar valores de texto de fontes remotas:

As classes flash.net.URLLoader e flash.net.URLRequest carregam as variveis do texto da posio local para uma
remota.

O atributo FlashVars est incorporado na pgina HTML que hospeda o arquivo SWF e pode conter valores das
variveis de texto.

A classe flash.net.SharedObject gerencia armazenamento persistente de valores. Para obter mais informaes,
consulte Armazenamento de dados locais na pgina 687.

Exibio de texto HTML

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe flash.text.TextField tem uma propriedade htmlText que pode ser usada para identificar a sequncia de texto medida que ela contm tags HTML para formatao de contedo. Como no exemplo a seguir, atribua um valor de sequncia de caracteres propriedade htmlText (no propriedade text) do Flash Player ou AIR para renderizar o texto como HTML:
var myText:String = "<p>This is <b>some</b> content to <i>render</i> as <u>HTML</u> text.</p>"; myTextBox.htmlText = myText;

O Flash Player e o AIR do suporte a um subconjunto de tags HTML e s entidades da propriedade htmlText. A descrio da propriedade flash.text.TextField.htmlText na Referncia do ActionScript 3.0 apresenta informaes detalhadas sobre as tags e entidades HTML com suporte. Assim que projetar o contedo usando a propriedade htmlText, voc poder usar as folhas de estilos ou a tag textformat para gerenciar a formatao do contedo. Para obter mais informaes, consulte Formatao de texto na pgina 366.

Uso de imagens em campos de texto

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Outra vantagem de exibir o contedo como texto HTML a incluso de imagens no campo de texto. possvel fazer referncia a uma imagem, local ou remota, usando a tag img e fazer com que ela aparea dentro do campo de texto associado. O exemplo a seguir cria um campo de texto denominado myTextBox e inclui a imagem JPG de um olho, armazenada no mesmo diretrio que o arquivo SWF, dentro do texto exibido:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da classe TextField

361

package { import flash.display.Sprite; import flash.text.*; public class TextWithImage extends Sprite { private var myTextBox:TextField; private var myText:String = "<p>This is <b>some</b> content to <i>test</i> and <i>see</i></p><p><img src='eye.jpg' width='20' height='20'></p><p>what can be rendered.</p><p>You should see an eye image and some <u>HTML</u> text.</p>"; public function TextWithImage() { myTextBox.width = 200; myTextBox.height = 200; myTextBox.multiline = true; myTextBox.wordWrap = true; myTextBox.border = true; addChild(myTextBox); myTextBox.htmlText = myText; } } }

A tag img suporta arquivos JPEG, GIF, PNG e SWF.

Rolagem de texto em um campo de texto

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior possvel que, em muitos casos, o texto seja maior que o campo de exibio. Ou talvez um campo de entrada permita que um usurio insira mais texto do que possa ser exibido de uma nica vez. Nesses casos, use as propriedades da classe flash.text.TextField relativas rolagem para gerenciar contedos extensos, quer na vertical quanto na horizontal. Essas propriedades incluem TextField.scrollV, TextField.scrollH, maxScrollV e maxScrollH. Use essas propriedades para responder a eventos, como um clique de mouse ou um pressionamento de tecla. O exemplo a seguir cria um campo de texto que um tamanho definido e contm mais texto do que o campo pode exibir de uma nica vez. O texto rola verticalmente medida que o usurio clica no campo de texto.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da classe TextField

362

package { import flash.display.Sprite; import flash.text.*; import flash.events.MouseEvent; public class TextScrollExample extends Sprite { private var myTextBox:TextField = new TextField(); private var myText:String = "Hello world and welcome to the show. It's really nice to meet you. Take your coat off and stay a while. OK, show is over. Hope you had fun. You can go home now. Don't forget to tip your waiter. There are mints in the bowl by the door. Thank you. Please come again."; public function TextScrollExample() { myTextBox.text = myText; myTextBox.width = 200; myTextBox.height = 50; myTextBox.multiline = true; myTextBox.wordWrap = true; myTextBox.background = true; myTextBox.border = true; var format:TextFormat = new TextFormat(); format.font = "Verdana"; format.color = 0xFF0000; format.size = 10; myTextBox.defaultTextFormat = format; addChild(myTextBox); myTextBox.addEventListener(MouseEvent.MOUSE_DOWN, mouseDownScroll); } public function mouseDownScroll(event:MouseEvent):void { myTextBox.scrollV++; } } }

Seleo e manipulao de texto

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior possvel selecionar texto dinmico ou de entrada. Como as propriedades e mtodos de seleo de texto da classe TextField usam posies de indexao para definir o intervalo do texto a ser manipulado, possvel selecionar programaticamente o texto dinmico ou de entrada mesmo quando o contedo desconhecido. Nota: No Flash Professional, se voc escolher a opo selecionvel em um campo de texto esttico, o campo de texto a ser exportado e colocado na lista de exibio ser um campo de texto regular, dinmico.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da classe TextField

363

Seleo de texto
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A propriedade flash.text.TextField.selectable true por padro e possvel selecionar texto programaticamente usando o mtodo setSelection(). Por exemplo, possvel definir um texto especfico dentro de um campo de texto para ser selecionado quando o usurio clicar no campo de texto:
var myTextField:TextField = new TextField(); myTextField.text = "No matter where you click on this text field the TEXT IN ALL CAPS is selected."; myTextField.autoSize = TextFieldAutoSize.LEFT; addChild(myTextField); addEventListener(MouseEvent.CLICK, selectText); function selectText(event:MouseEvent):void { myTextField.setSelection(49, 65); }

De modo similar, para que o texto dentro de um campo de texto seja selecionado assim que o texto for inicialmente exibido, crie uma funo do manipulador de eventos que seja chamada quando o campo de texto for adicionado lista de exibio.

Captura de texto selecionado pelo usurio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior As propriedades selectionBeginIndex e selectionEndIndex de TextField (que so somente leitura e, portanto, no podem ser definidas para selecionar texto de modo programtico) podem ser usadas para capturar qualquer coisa que o usurio tenha selecionado atualmente. Adicionalmente, os campos de texto de entrada podem usar a propriedade caretIndex. Por exemplo, o cdigo a seguir controla os valores dos ndices do texto selecionado pelo usurio:
var myTextField:TextField = new TextField(); myTextField.text = "Please select the TEXT IN ALL CAPS to see the index values for the first and last letters."; myTextField.autoSize = TextFieldAutoSize.LEFT; addChild(myTextField); addEventListener(MouseEvent.MOUSE_UP, selectText); function selectText(event:MouseEvent):void { trace("First letter index position: " + myTextField.selectionBeginIndex); trace("Last letter index position: " + myTextField.selectionEndIndex); }

possvel aplicar uma coleo das propriedades do objeto TextFormat para a seleo a fim de alterar a aparncia do texto. Para obter mais informaes sobre a aplicao de uma coleo de propriedades TextFormat para o texto selecionado, consulte Formatao de intervalos de texto dentro de um campo de texto na pgina 369.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da classe TextField

364

Captura de entrada de texto

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Por padro, a propriedade type de um campo de texto est definida como dynamic. Se voc definir a propriedade type como input usando a classe TextFieldType, poder colecionar a entrada do usurio e salvar o valor para uso em outras partes do aplicativo. Os campos de texto de entrada so teis para formulrios e quaisquer aplicativos que desejem que o usurio defina um valor de texto a ser utilizado em outro lugar no programa. Por exemplo, o cdigo a seguir cria um campo de texto de entrada denominado myTextBox. Assim que o usurio inserir texto no campo, o evento textInput ser acionado. Um manipulador de eventos denominado textInputCapture capturar a sequncia de caracteres de texto inserida e a designar para uma varivel. O Flash Player ou AIR exibir o novo texto em outro campo de texto, denominado myOutputBox.
package { import import import import

flash.display.Sprite; flash.display.Stage; flash.text.*; flash.events.*; Sprite new TextField(); = new TextField(); your text here.";

public class CaptureUserInput extends { private var myTextBox:TextField = private var myOutputBox:TextField private var myText:String = "Type public function CaptureUserInput() { captureText(); }

public function captureText():void { myTextBox.type = TextFieldType.INPUT; myTextBox.background = true; addChild(myTextBox);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da classe TextField

365

myTextBox.text = myText; myTextBox.addEventListener(TextEvent.TEXT_INPUT, textInputCapture); } public function textInputCapture(event:TextEvent):void { var str:String = myTextBox.text; createOutputBox(str); } public function createOutputBox(str:String):void { myOutputBox.background = true; myOutputBox.x = 200; addChild(myOutputBox); myOutputBox.text = str; } } }

Restrio de entrada de texto

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Como campos de texto de entrada so usados frequentemente para formulrios ou caixas de dilogos nos aplicativos, talvez voc queira limitar os tipos de caracteres que um usurio pode inserir em um campo de texto ou mant-lo oculto - por exemplo, no caso de uma senha. A classe flash.text.TextField tem as propriedades displayAsPassword e restrict que podem ser definidas para controlar a entrada do usurio. A propriedade displayAsPassword simplesmente oculta o texto (exibindo-o como uma srie de asteriscos) medida que o usurio o digita. Quando displayAsPassword est definido como true, os comandos Recortar e Copiar, e seus respectivos atalhos no teclado, no funcionam. Como mostrado no exemplo a seguir, designe a propriedade displayAsPassword exatamente como faria com outras propriedades, como background e color:
myTextBox.type = TextFieldType.INPUT; myTextBox.background = true; myTextBox.displayAsPassword = true; addChild(myTextBox);

A propriedade restrict um pouco mais complicada visto que voc precisa especificar que caracteres o usurio tem permisso para digitar em um campo de texto de entrada. As entradas admissveis so letras e nmeros especficos ou intervalos de letras, nmeros e caracteres. O cdigo a seguir permite que o usurio insira letras maisculas apenas (e no nmeros ou caracteres especiais) no campo de texto:
myTextBox.restrict = "A-Z";

O ActionScript 3.0 usa hfens para definir intervalos e circunflexos para definir caracteres excludos. Para obter mais informaes sobre a como definir o que est restrito em um campo de texto de entrada, consulte a entrada da propriedade flash.text.TextField.restrict na Referncia do ActionScript 3.0.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da classe TextField

366

Formatao de texto
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc tem vrias opes para formatar programaticamente a exibio do texto. possvel definir propriedades diretamente na instncia do TextField por exemplo, as propriedades TextFIeld.thickness, TextField.textColor e TextField.textHeight.Ou voc pode designar o contedo do campo de texto usando a propriedade htmlText e lanar mo das tags HTML com suporte, por exemplo b, i e u. No entanto, tambm possvel aplicar objetos TextFormat para os campos de texto que contm texto sem formatao ou objetos StyleSheet para os campos de texto que contm a propriedade htmlText. O uso dos objetos TextFormat e StyleSheet fornece a maioria do controle e consistncia sobre a aparncia do texto em todo o aplicativo. possvel definir um objeto TextFormat ou StyleSheet e aplic-lo a vrios ou a todos os campos de texto no seu aplicativo.

Atribuio de formatos de texto

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior possvel usar a classe TextFormat para definir um nmero diferente de propriedade de exibio de texto e aplic-las todo o contedo de um objeto TextField ou a um intervalo de texto. O exemplo a seguir aplica um objeto de TextFormat a um objeto TextField inteiro e aplica um segundo Objeto TextFormat a um intervalo de texto dentro desse objeto TextField.
var tf:TextField = new TextField(); tf.text = "Hello Hello"; var format1:TextFormat = new TextFormat(); format1.color = 0xFF0000; var format2:TextFormat = new TextFormat(); format2.font = "Courier"; tf.setTextFormat(format1); var startRange:uint = 6; tf.setTextFormat(format2, startRange); addChild(tf);

O mtodo TextField.setTextFormat() afeta apenas o texto que j est exibido no campo de texto. Se o contedo em TextField mudar, talvez seja necessrio que o aplicativo chame o mtodo TextField.setTextFormat() novamente para reaplicar a formatao. Ainda possvel definir a propriedade defaultTextFormat de TextField para especificar o formato a ser usado para o texto inserido pelo usurio.

Aplicao de folhas de estilos em cascata

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os campos de texto contm texto sem formatao ou formatado em HTML. O texto sem formatao est armazenado na propriedade text da instncia e o texto HTML est armazenado na propriedadehtmlText. possvel usar declaraes de estilo CSS para definir estilos de texto que voc possa aplicar a diferentes campos de texto. As declaraes de estilo CSS podem ser criadas no seu cdigo de aplicativo ou carregada em um tempo de execuo a partir de um arquivo CSS externo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da classe TextField

367

A classe flash.text.StyleSheet manipula os estilos das CSS. A classe StyleSheet reconhece um conjunto limitado de propriedades das CSS. Para obter uma lista detalhada das propriedades de estilo que a classe StyleSheet suporta, consulte a entrada flash.textStylesheet na Referncia do ActionScript 3.0. Como o exemplo a seguir mostra, possvel criar as CSS em seu cdigo e aplicar esses estilos ao texto HTML usando um objeto StyleSheet:
var style:StyleSheet = new StyleSheet(); var styleObj:Object = new Object(); styleObj.fontSize = "bold"; styleObj.color = "#FF0000"; style.setStyle(".darkRed", styleObj); var tf:TextField = new TextField(); tf.styleSheet = style; tf.htmlText = "<span class = 'darkRed'>Red</span> apple"; addChild(tf);

Depois de criar um objeto StyleSheet, o cdigo de exemplo cria um objeto simples para manter um conjunto de propriedades de declarao de estilos. Em seguida, ele chama o mtodo StyleSheet.setStyle()que adiciona o novo estilo folha de estilos com o nome .darkred. Depois, ele aplica a formatao da folha de estilos atribuindo o objeto StyleSheet propriedade styleSheet do TextField. Para que os estilos das CSS tenham efeito, a folha de estilos deve ser aplicada ao objeto TextField antes que a propriedade htmlText seja definida. Por design, um campo de texto com uma folha de estilos no editvel. Se tiver um campo de texto de entrada e atribuir uma folha de estilos a ele, o campo de texto apresentar as propriedades da folha de estilos, mas o campo texto no permitir que usurios insiram o novo texto nele. Alm disso, no ser possvel usar as APIs do ActionScript abaixo em um campo de texto caso uma folha de estilos esteja atribuda:

O mtodo TextField.replaceText() O mtodo TextField.replaceSelectedText() A propriedade TextField.defaultTextFormat O mtodo TextField.setTextFormat()

Se um campo de texto tiver uma folha de estilos atribuda a ele, no entanto, posteriormente, a propriedade TextField.styleSheet for definida como null, o contedo das propriedades TextField.text e TextField.htmlText adicionaro tags e atributos ao contedo para incorporar a formatao da folha de estilos anteriormente atribuda. A fim de preservar a propriedade htmlText original, salve-a em uma varivel antes de definir a folha de estilos como null.

Carregamento de um arquivo CSS externo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A abordagem das CSS para formatao ser mais eficaz quando for possvel carregar as informaes das CSS desde um arquivo externo no tempo de execuo. Quando os dados das CSS forem externos ao prprio aplicativo, ser possvel alterar o estilo visual do texto no aplicativo sem ter de alterar o cdigo de origem do ActionScript 3.0. Depois da implementao do aplicativo, possvel alterar um arquivo CSS externo para alterar a aparncia do aplicativo, sem ter de reimplementar o arquivo SWF do aplicativo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da classe TextField

368

O mtodo StyleSheet.parseCSS() converte uma sequncia de caracteres que contm dados CSS em declaraes de estilo no objeto StyleSheet. O exemplo a seguir mostra como ler um arquivo CSS externo e aplicar suas declaraes de estilo a um objeto TextField. Em primeiro lugar, este o contedo do arquivo CSS a ser carregado, denominado exemplo.css:
p { font-family: Times New Roman, Times, _serif; font-size: 14; } h1 { font-family: Arial, Helvetica, _sans; font-size: 20; font-weight: bold; } .bluetext { color: #0000CC; }

Ao lado, est o cdigo do ActionScript para uma classe que carrega o arquivo example.css e aplica os estilos ao contedo TextField.
package { import import import import import import import

flash.display.Sprite; flash.events.Event; flash.net.URLLoader; flash.net.URLRequest; flash.text.StyleSheet; flash.text.TextField; flash.text.TextFieldAutoSize;

public class CSSFormattingExample extends Sprite { var loader:URLLoader; var field:TextField; var exampleText:String = "<h1>This is a headline</h1>" + "<p>This is a line of text. <span class='bluetext'>" + "This line of text is colored blue.</span></p>"; public function CSSFormattingExample():void { field = new TextField(); field.width = 300;

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da classe TextField

369

field.autoSize = TextFieldAutoSize.LEFT; field.wordWrap = true; addChild(field); var req:URLRequest = new URLRequest("example.css"); loader = new URLLoader(); loader.addEventListener(Event.COMPLETE, onCSSFileLoaded); loader.load(req); } public function onCSSFileLoaded(event:Event):void { var sheet:StyleSheet = new StyleSheet(); sheet.parseCSS(loader.data); field.styleSheet = sheet; field.htmlText = exampleText; } } }

Quando os dados das CSS forem carregados, o mtodo onCSSFileLoaded() ser executado e chamar o mtodo StyleSheet.parseCSS() para transferir as declaraes de estilos para o objeto StyleSheet.

Formatao de intervalos de texto dentro de um campo de texto

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Um mtodo til da classe flash.text.TextField o mtodo setTextFormat() Com setTextFormat(), possvel atribuir propriedades especficas ao contedo de parte de um campo de texto para responder entrada do usurio, por exemplo, formulrios que precisem lembrar usurios que determinadas entradas so necessrias ou alterar a nfase de uma subseo de uma passagem de texto em um campo quando um usurio seleciona partes do texto. O exemplo a seguir usa TextField.setTextFormat() em um cadeia de caracteres para alterar a aparncia de parte do contedo do myTextField quando o usurio clica no campo de texto:
var myTextField:TextField = new TextField(); myTextField.text = "No matter where you click on this text field the TEXT IN ALL CAPS changes format."; myTextField.autoSize = TextFieldAutoSize.LEFT; addChild(myTextField); addEventListener(MouseEvent.CLICK, changeText); var myformat:TextFormat = new TextFormat(); myformat.color = 0xFF0000; myformat.size = 18; myformat.underline = true; function changeText(event:MouseEvent):void { myTextField.setTextFormat(myformat, 49, 65); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da classe TextField

370

Renderizao avanada de texto

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O ActionScript 3.0 apresenta uma variedade de classes no pacote flash.text para controlar as propriedades do texto exibido, incluindo fontes incorporadas, configuraes de suavizao de serrilhado, controle de canal alfa e outras configuraes especficas. A Referncia do ActionScript 3.0 apresenta descries detalhadas das classes e propriedades, incluindo as classes CSMSettings, Font e TextRenderer.

Uso de fontes incorporadas

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Quando voc especificar uma fonte especfica para um TextField no aplicativo, o Flash Player ou AIR procurar uma fonte de dispositivo (uma fonte que reside no computador do usurio) com o mesmo nome. Se essa fonte no for localizada no sistema ou se o usurio tiver uma verso ligeiramente diferente de uma fonte com esse nome, a aparncia da exibio do texto poder ser bem diferente do que se pretende. Para ter certeza de que o usurio ver exatamente a fonte correta, incorpore a fonte no arquivo SWF do aplicativo. As fontes incorporadas tm um nmero de benefcios:

Os caracteres de fonte incorporada tm suavizao de serrilhado, o que faz com que as bordas sejam exibidas com
mais suavidade, especialmente em um texto maior.

possvel girar texto que use fontes incorporadas. Texto com fonte incorporada pode ser transparente ou semitransparente. possvel usar o estilo CSS kerning com fontes incorporadas.
A maior limitao ao uso de fontes incorporadas que elas aumentam o tamanho do arquivo ou do download do aplicativo. O mtodo exato a ser usado para incorporar um arquivo fonte no arquivo SWF do aplicativo varia de acordo com o ambiente de desenvolvimento. Depois de incorporar uma fonte, possvel verificar se um TextField utilizar a fonte incorporada correta:

Defina a propriedade embedFonts do TextField como true. Crie um objeto TextFormat, defina a propriedade fontFamily como o nome da fonte incorporada e aplique o
objeto TextFormat ao TextField. Quando voc especificar uma fonte incorporada, a propriedade fontFamily dever conter apenas um nico nome, e no poder usar uma lista delimitada por vrgulas de vrios nomes de fonte.

Se estiver usando os estilos CSS para definir fontes para os TextFields ou componentes, defina a propriedade das
CSS font-family para o nome da fonte incorporada. A propriedade font-family dever conter um nico nome, no uma lista de nomes, se voc desejar especificar uma fonte incorporada. Incorporao de uma fonte no Flash O Flash Professional permite que voc incorpore qualquer fonte que possua ao sistema, incluindo as fontes True Type e Postscript Tipo 1. possvel incorporar fontes em um aplicativo de muitos modos, incluindo:

Configurando as propriedades da fonte e do estilo de um TextField no Palco e clicando na caixa de seleo Fontes
incorporadas

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da classe TextField

371

Criando e fazendo referncia a um smbolo de fonte Criando e usando uma biblioteca compartilhada de tempo de execuo que contm smbolos de fonte incorporada
Para obter detalhes adicionais sobre como incorporar fontes em aplicativos, consulte "Fontes incorporadas para campos de texto dinmicos ou de entrada" em Uso do Flash. Incorporao de uma fonte no Flex possvel incorporar fontes em um aplicativo Flex de muitos modos, incluindo:

Usar a tag de metadados [Embed] em um script Usar a declarao de estilo @font-face Estabelea uma classe para a fonte e utilize a tag [Embed] para integr-la.
Apenas fontes True Type podem ser diretamente incorporadas em um aplicativo Flex. Para fontes em outros formatos (como Postscript Tipo 1), possvel incorpor-las, primeiro, em um arquivo SWF e, depois, usando o Flash Professional, usar tal arquivo no seu aplicativo Flex. Para obter detalhes sobre como usar fontes incorporadas dos arquivos SWF no Flex, consulte "Incorporao de fontes de arquivos SWF" em Uso do Flex 4.

Mais tpicos da Ajuda

Peter deHaan: Embedding fonts (Incorporao de Fontes) Divillysausages.com: AS3 Font embedding masterclass (Masterclass de Incorporao de Fontes do AS3)

Controle de nitidez, espessura e suavizao de serrilhado

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Por padro, o Flash Player ou AIR determina as configuraes dos controles de exibio de texto como nitidez, espessura e suavizao de serrilhado medida que o texto redimensionado, muda de cor ou exibido em diversos fundos. Em alguns casos (por exemplo, quando se tem um texto muito pequeno, muito grande ou uma diversidade de fundos exclusivos), talvez voc queira manter controle sobre essas configuraes. possvel substituir as configuraes do Flash Player ou AIR usando a classe flash.text.TextRenderer e suas classes associadas, como a classe CSMSettings. Essas classes concedem controle preciso sobre a renderizao da qualidade do texto incorporado. Para obter informaes adicionais sobre fontes incorporadas, consulte Uso de fontes incorporadas na pgina 370 Nota: A propriedade flash.text.TextField.antiAliasType deve ter o valor AntiAliasType.ADVANCED para configurar a nitidez, espessura ou propriedade gridFitType, ou usar o mtodo TextRenderer.setAdvancedAntiAliasingTable(). O exemplo a seguir aplica-se s propriedades e formatao da CSM (modulao de traado contnuo) personalizadas para o texto exibido usando uma fonte incorporada denominada myFont. Quando o usurio clicar no texto exibido, o Flash Player ou o Adobe AIR aplicar as configuraes personalizadas.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da classe TextField

372

var format:TextFormat = new TextFormat(); format.color = 0x336699; format.size = 48; format.font = "myFont"; var myText:TextField = new TextField(); myText.embedFonts = true; myText.autoSize = TextFieldAutoSize.LEFT; myText.antiAliasType = AntiAliasType.ADVANCED; myText.defaultTextFormat = format; myText.selectable = false; myText.mouseEnabled = true; myText.text = "Hello World"; addChild(myText); myText.addEventListener(MouseEvent.CLICK, clickHandler); function clickHandler(event:Event):void { var myAntiAliasSettings = new CSMSettings(48, 0.8, -0.8); var myAliasTable:Array = new Array(myAntiAliasSettings); TextRenderer.setAdvancedAntiAliasingTable("myFont", FontStyle.ITALIC, TextColorType.DARK_COLOR, myAliasTable); }

Trabalho com texto esttico

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O texto esttico s criado no Flash Professional. No possvel instanciar programaticamente texto esttico usando ActionScript. O texto esttico til quando o texto pequeno e no pode ser alterado (como o texto dinmico pode). Pense no texto esttico como a um elemento grfico (por exemplo, um crculo ou quadrado) desenhado no Palco, no Flash Professional. Embora o texto esttico seja mais limitado que o texto dinmico, o ActionScript 3.0 permite que voc leia os valores da propriedade do texto esttico usando a classe StaticText. possvel tambm usar a classe TextSnapshot para ler outros tipos de valores alm do texto esttico.

Acesso aos campos de texto esttico com a classe StaticText

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Normalmente, possvel usar a classe flash.text.StaticText no painel Aes do Flash Professional para interagir com uma instncia de texto esttica posicionada no Palco. Tambm possvel trabalhar nos arquivos do ActionScript que interagem com um arquivo SWF que contm texto esttico. Em qualquer caso, possvel instanciar uma instncia de texto esttico de modo programtico. O texto esttico criado no Flash Professional. Para criar uma referncia a um campo de texto esttico existente, faa uma iterao nos itens na lista de exibio e atribua um varivel. Por exemplo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da classe TextField

373

for (var i = 0; i < this.numChildren; i++) { var displayitem:DisplayObject = this.getChildAt(i); if (displayitem instanceof StaticText) { trace("a static text field is item " + i + " on the display list"); var myFieldLabel:StaticText = StaticText(displayitem); trace("and contains the text: " + myFieldLabel.text); } }

Depois de fazer referncia a um campo de texto esttico, possvel usar as propriedades desse campo no ActionScript 3.0. O cdigo a seguir est anexado a um quadro na Linha de tempo e parte da premissa de que uma varivel denominada myFieldLabel foi atribuda a uma referncia a texto esttico. Um campo de texto dinmico, denominado myField, est posicionado em relao aos valores x e y de myFieldLabel e exibe o valor de myFieldLabel novamente.
var myField:TextField = new TextField(); addChild(myField); myField.x = myFieldLabel.x; myField.y = myFieldLabel.y + 20; myField.autoSize = TextFieldAutoSize.LEFT; myField.text = "and " + myFieldLabel.text

Uso da classe TextSnapshot

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Se desejar trabalhar programaticamente com uma instncia de texto esttica existente, poder usar a classe flash.text.TextSnapshot para trabalhar com a propriedade textSnapshot de um flash.display.DisplayObjectContainer. Em outras palavras, voc cria uma instncia do TextSnapshot da propriedade DisplayObjectContainer.textSnapshot possvel aplicar mtodos a essa instncia para recuperar valores ou selecionar partes do texto esttico. Por exemplo, coloque um campo de texto esttico que contm o texto "Exemplo de TextSnapshot" no Palco. Adicione o ActionScript a seguir ao Quadro 1 da Linha de tempo:
var mySnap:TextSnapshot = this.textSnapshot; var count:Number = mySnap.charCount; mySnap.setSelected(0, 4, true); mySnap.setSelected(1, 2, false); var myText:String = mySnap.getSelectedText(false); trace(myText);

A classe TextSnapshot ser til para obter texto dentre os campos de texto esttico em um arquivo SWF carregado, caso voc queira usar o texto como um valor em outra parte de um aplicativo.

Exemplo de TextField: formatao de texto estilo jornal

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O exemplo Layout de notcias formata o texto para uma aparncia similar a uma matria de jornal impresso. O texto de entrada pode conter um ttulo, um subttulo e o corpo da matria. Com determinada largura e altura de exibio, o exemplo de Layout de notcias formata o ttulo e o subttulo de modo a ocupar toda a extenso da rea de exibio. O texto da matria distribudo em duas ou mais colunas.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da classe TextField

374

Este exemplo ilustra as seguintes tcnicas de programao do ActionScript:

Extenso da classe TextField Carregamento e aplicao de um arquivo CSS externo Converso de estilos CSS em objetos TextFormat Uso da classe TextLineMetrics para obter informaes sobre o tamanho de exibio de texto
Para obter os arquivos do aplicativo deste exemplo, consulte www.adobe.com/go/learn_programmingAS3samples_flash_br. Os arquivos do aplicativo Layout de notcias podem ser encontrados na pasta Samples/NewsLayout. O aplicativo consiste nos seguintes arquivos:
Arquivo NewsLayout.mxml ou NewsLayout.fla com/example/programmingas3/ne wslayout/StoryLayoutComponent.a s com/example/programmingas3/ne wslayout/StoryLayout.as com/example/programmingas3/ne wslayout/FormattedTextField.as com/example/programmingas3/ne wslayout/HeadlineTextField.as com/example/programmingas3/ne wslayout/MultiColumnTextField.as story.css Uma classe UIComponent do Flex que substitui a instncia do StoryLayout. Descrio A interface do usurio do aplicativo para Flex (MXML) ou Flash (FLA).

A principal classe do ActionScript que organiza todos os componentes de uma matria jornalstica para exibio. Uma subclasse da classe TextField que gerencia seus prprio TextFormat.

Uma subclasse da classe FormattedTextField que ajusta os tamanhos das fontes de modo a se ajustarem largura desejada. Uma classe ActionScript que divide texto em duas ou mais colunas.

Um arquivo CSS que define estilos de texto para o layout.

Leitura do arquivo CSS externo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O aplicativo Layout de notcias inicia pela leitura do texto da matria de um arquivo XML local. Em seguida, ele l um arquivo CSS externo que fornece as informaes de formatao para o ttulo, subttulo e texto principal. O arquivo CSS define trs estilos, um estilo de pargrafo padro para a matria, e os estilos h1 e h2 para ttulo e subttulo respectivamente.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da classe TextField

375

p { font-family: Georgia, "Times New Roman", Times, _serif; font-size: 12; leading: 2; text-align: justify; indent: 24; } h1 { font-family: Verdana, Arial, Helvetica, _sans; font-size: 20; font-weight: bold; color: #000099; text-align: left; } h2 { font-family: Verdana, Arial, Helvetica, _sans; font-size: 16; font-weight: normal; text-align: left; }

A tcnica usada par ler o arquivo CSS externo a mesma descrita em Carregamento de um arquivo CSS externo na pgina 367 Quando o arquivo CSS for carregado, o aplicativo executar o mtodo onCSSFileLoaded(), como mostrado abaixo.
public function onCSSFileLoaded(event:Event):void { this.sheet = new StyleSheet(); this.sheet.parseCSS(loader.data); h1Format = getTextStyle("h1", this.sheet); if (h1Format == null) { h1Format = getDefaultHeadFormat(); } h2Format = getTextStyle("h2", this.sheet); if (h2Format == null) { h2Format = getDefaultHeadFormat(); h2Format.size = 16; } pFormat = getTextStyle("p", this.sheet); if (pFormat == null) { pFormat = getDefaultTextFormat(); pFormat.size = 12; } displayText(); }

O mtodo onCSSFileLoaded() cria um objeto StyleSheet e o utiliza para analisar os dados das CSS de entrada. O principal texto da matria exibida em um objeto MultiColumnTextField, que pode usar um objeto StyleSheet diretamente. No entanto, os campos do ttulo usam a classe HeadlineTextField, que usam um objeto TextFormat para formatao.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da classe TextField

376

O mtodo onCSSFileLoaded() chama o mtodo getTextStyle() duas vezes para converter uma declarao de estilo CSS em um objeto TextFormat a ser utilizado com cada um dos dois objetos TextField do ttulo.
public function getTextStyle(styleName:String, ss:StyleSheet):TextFormat { var format:TextFormat = null; var style:Object = ss.getStyle(styleName); if (style != null) { var colorStr:String = style.color; if (colorStr != null && colorStr.indexOf("#") == 0) { style.color = colorStr.substr(1); } format = new TextFormat(style.fontFamily, style.fontSize, style.color, (style.fontWeight == "bold"), (style.fontStyle == "italic"), (style.textDecoration == "underline"), style.url, style.target, style.textAlign, style.marginLeft, style.marginRight, style.indent, style.leading); if (style.hasOwnProperty("letterSpacing")) { format.letterSpacing = style.letterSpacing; } } return format; }

Os nomes das propriedades e o significado dos valores das propriedades so diferentes entre as declaraes de estilo CSS e os objetos TextFormat. O mtodo getTextStyle() converte os valores das propriedades das CSS nos valores esperados pelo objeto TextFormat.

Organizao dos elementos da matria na pgina

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe StoryLayout formata e dispe o ttulo, o subttulo e os campos de texto principais em uma organizao com estilo de jornal. O mtodo displayText() cria inicialmente e posiciona os diversos campos.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da classe TextField

377

public function displayText():void { headlineTxt = new HeadlineTextField(h1Format); headlineTxt.wordWrap = true; headlineTxt.x = this.paddingLeft; headlineTxt.y = this.paddingTop; headlineTxt.width = this.preferredWidth; this.addChild(headlineTxt); headlineTxt.fitText(this.headline, 1, true); subtitleTxt = new HeadlineTextField(h2Format); subtitleTxt.wordWrap = true; subtitleTxt.x = this.paddingLeft; subtitleTxt.y = headlineTxt.y + headlineTxt.height; subtitleTxt.width = this.preferredWidth; this.addChild(subtitleTxt); subtitleTxt.fitText(this.subtitle, 2, false); storyTxt = new MultiColumnText(this.numColumns, 20, this.preferredWidth, 400, true, this.pFormat); storyTxt.x = this.paddingLeft; storyTxt.y = subtitleTxt.y + subtitleTxt.height + 10; this.addChild(storyTxt); storyTxt.text = this.content; ...

Cada campo posicionado abaixo do campo anterior definindo sua propriedade y de modo a igualar a propriedade y do campo anterior mais sua altura. Esse clculo dinmico de posicionamento necessrio porque os objetos HeadlineTextField e MultiColumnTextField podem alterar sua altura de modo a se adequarem ao contedo.

Alterao do tamanho da fonte para ajustar o tamanho do campo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Dada a largura em pixels e o nmero mximo de linhas, o HeadlineTextField altera o tamanho da fonte de modo a ajustar o texto ao campo. Se o texto for curto, o tamanho da fonte ser grande, criando um ttulo estilo tablide. Se o texto for longo, o tamanho da fonte ser menor. O mtodo HeadlineTextField.fitText() mostrado abaixo faz com que o dimensionamento de fonte funcione:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da classe TextField

378

public function fitText(msg:String, maxLines:uint = 1, toUpper:Boolean = false, targetWidth:Number = -1):uint { this.text = toUpper ? msg.toUpperCase() : msg; if (targetWidth == -1) { targetWidth = this.width; } var pixelsPerChar:Number = targetWidth / msg.length; var pointSize:Number = Math.min(MAX_POINT_SIZE, Math.round(pixelsPerChar * 1.8 * maxLines)); if (pointSize < 6) { // the point size is too small return pointSize; } this.changeSize(pointSize); if (this.numLines > maxLines) { return shrinkText(--pointSize, maxLines); } else { return growText(pointSize, maxLines); } } public function growText(pointSize:Number, maxLines:uint = 1):Number { if (pointSize >= MAX_POINT_SIZE) { return pointSize; } this.changeSize(pointSize + 1); if (this.numLines > maxLines) { // set it back to the last size this.changeSize(pointSize); return pointSize; } else { return growText(pointSize + 1, maxLines); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da classe TextField

379

} public function shrinkText(pointSize:Number, maxLines:uint=1):Number { if (pointSize <= MIN_POINT_SIZE) { return pointSize; } this.changeSize(pointSize); if (this.numLines > maxLines) { return shrinkText(pointSize - 1, maxLines); } else { return pointSize; } }

O mtodo HeadlineTextField.fitText() usa uma tcnica recursiva simples para dimensionar a fonte. Em primeiro lugar, ele advinha um nmero mdio de pixels por caractere no texto e, ento, calcula um tamanho de ponto inicial. Em seguida, altera o tamanho da fonte e verifica se o texto tem quebra de palavras para criar mais do que o nmero mximo de linhas de texto. Se houver linhas em excesso, ele chamar o mtodo shrinkText() para diminuir o tamanho da fonte e tentar novamente. Se no houver linhas em excesso, ele chamar o mtodo growText() para aumentar o tamanho da fonte e tentar novamente. O processo parar no ponto em que incrementar o tamanho da fonte em mais um criar linhas em excesso.

Diviso de texto em vrias colunas

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe MultiColumnTextField expande o texto entre vrios objetos TextField que so organizados, por sua vez, como colunas de jornal. O construtor MultiColumnTextField() cria, primeiro, uma matriz de objetos TextFields, uma para cada coluna, conforme mostrado aqui:
for (var i:int = 0; i < cols; i++) { var field:TextField = new TextField(); field.multiline = true; field.autoSize = TextFieldAutoSize.NONE; field.wordWrap = true; field.width = this.colWidth; field.setTextFormat(this.format); this.fieldArray.push(field); this.addChild(field); }

Cada objeto TextField adicionado matriz e lista de exibio com o mtodo addChild(). Sempre que a propriedade text ou styleSheet do StoryLayout muda, ele chama o mtodo layoutColumns() para re-exibir o texto. O mtodo layoutColumns() chama o mtodo getOptimalHeight() para calcular a altura em pixels correta necessria para ajustar todo o texto a determinada largura de layout.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da classe TextField

380

public function getOptimalHeight(str:String):int { if (field.text == "" || field.text == null) { return this.preferredHeight; } else { this.linesPerCol = Math.ceil(field.numLines / this.numColumns); var metrics:TextLineMetrics = field.getLineMetrics(0); this.lineHeight = metrics.height; var prefHeight:int = linesPerCol * this.lineHeight; return prefHeight + 4; } }

Em primeiro lugar, o mtodo getOptimalHeight() calcula a largura de cada coluna. Em seguida, define a largura e a propriedade htmlText do primeiro objeto TextField na matriz. O mtodo getOptimalHeight() usa esse primeiro objeto TextField para descobrir o nmero total de linhas com quebra de palavras no texto e, com base nesse nmero, identifica quantas linhas deve haver em cada coluna. Em seguida, ele chama o mtodo TextField.getLineMetrics() para recuperar um objeto TextLineMetrics contendo detalhes sobre o tamanho do texto na primeira linha. A propriedade TextLineMetrics.height representa a altura completa de uma linha de texto, em pixels, incluindo ascendente, descendente e entrelinha. A altura ideal do objeto MultiColumnTextField a altura da linha multiplicada pelo nmero de linhas por coluna, mais 4 para computar a borda de dois pixels em cima e embaixo de um objeto TextField. Este o cdigo do mtodo layoutColumns() completo:
public function layoutColumns():void { if (this._text == "" || this._text == null) { return; } var field:TextField = fieldArray[0] as TextField; field.text = this._text; field.setTextFormat(this.format); this.preferredHeight = this.getOptimalHeight(field); var remainder:String = this._text; var fieldText:String = ""; var lastLineEndedPara:Boolean = true; var indent:Number = this.format.indent as Number; for (var i:int = 0; i < fieldArray.length; i++) { field = this.fieldArray[i] as TextField; field.height = this.preferredHeight; field.text = remainder; field.setTextFormat(this.format);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da classe TextField

381

var lineLen:int; if (indent > 0 && !lastLineEndedPara && field.numLines > 0) { lineLen = field.getLineLength(0); if (lineLen > 0) { field.setTextFormat(this.firstLineFormat, 0, lineLen); } } field.x = i * (colWidth + gutter); field.y = 0; remainder = ""; fieldText = ""; var linesRemaining:int = field.numLines; var linesVisible:int = Math.min(this.linesPerCol, linesRemaining); for (var j:int = 0; j < linesRemaining; j++) { if (j < linesVisible) { fieldText += field.getLineText(j); } else { remainder +=field.getLineText(j); } } field.text = fieldText; field.setTextFormat(this.format); if (indent > 0 && !lastLineEndedPara) { lineLen = field.getLineLength(0); if (lineLen > 0) { field.setTextFormat(this.firstLineFormat, 0, lineLen); } } var lastLine:String = field.getLineText(field.numLines - 1); var lastCharCode:Number = lastLine.charCodeAt(lastLine.length - 1);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da classe TextField

382

if (lastCharCode == 10 || lastCharCode == 13) { lastLineEndedPara = true; } else { lastLineEndedPara = false; } if ((this.format.align == TextFormatAlign.JUSTIFY) && (i < fieldArray.length - 1)) { if (!lastLineEndedPara) { justifyLastLine(field, lastLine); } } } }

Depois da propriedade preferredHeight ter sido definida pela chamada do mtodo getOptimalHeight(), o mtodo layoutColumns() ser iterado por meio dos objetos TextField definindo a altura de cada objeto para o valor preferredHeight. O mtodo layoutColumns() distribui apenas linhas suficientes de texto para cada campo de modo que no ocorra rolamento em nenhum campo individual e o texto em cada campo sucessivo inicie onde termina o texto no campo anterior. Se o estilo de alinhamento de texto for definido como justificar, o mtodo justifyLastLine() ser chamado para justificar a linha final do texto em um campo. Caso contrrio, a ltima linha ser tratada como uma linha de fim de pargrafo e no justificada.

ltima atualizao em 29/3/2011

383

Captulo 20: Uso do Flash Text Engine

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior O Adobe Flash Text Engine (FTE), disponvel a partir do Flash Player 10 e do Adobe AIR1.5, fornece um suporte de baixo nvel para o controle sofisticado de mtricas de texto, formatao e texto bidirecional. Oferece fluxo de texto aprimorado e suporte avanado a idioma. Embora possa ser usado para criar e gerenciar elementos de texto simples, o FTE foi desenvolvido principalmente como uma base para os desenvolvedores criarem componentes de tratamento de texto. Assim, o Flash Text Engine presume um nvel mais avanado de especializao em programao. Para exibir elementos de texto simples, consulte Uso da classe TextField na pgina 358. A Text Layout Framework, que inclui um componente de tratamento de texto baseado na FTE, fornece uma forma mais fcil de usar seus recursos avanados. A Text Layout Framework uma biblioteca extensvel totalmente integrada ao ActionScript 3.0. possvel usar o componente TLF existente ou usar a estrutura para construir seu prprio componente de texto. Para obter mais informaes, consulte Uso da Text Layout Framework na pgina 413.

Mais tpicos da Ajuda

pacote flash.text.engine

Criao e exibio de texto

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Essas classes que compe o Flash Text Engine permitem a criao, formatao e controle de texto. As classes a seguir so blocos de construo bsicos para criao e exibio de texto com o Flash Text Engine:

TextElement/GraphicElement/GroupElement - contm o contedo de uma instncia do TextBlock ElementFormat - especifica os atributos de formatao do contedo de uma instncia do TextBlock TextBlock - a fbrica para construo de um pargrafo de texto TextLine - uma linha de texto criada a partir do TextBlock
Para exibir texto, crie um objeto TextElement de um String usando um objeto ElementFormat para especificar as caracterstics de formatao. Atribua o TextElement propriedade content de um objeto TextBlock. Crie as linhas de texto da exibio chamando o mtodo TextBlock.createTextLine(). O mtodo createTextLine() retorna um objeto TextLine que contm tantas strings quantas vo se ajustar na largura especificada. Chame o mtodo repetidamente at que toda a string tenha sido formatada em linhas. Quando no houver mais linhas para criar, propriedade textLineCreationResult do objeto TextBlock atribudo o valor: TextLineCreationResult.COMPLETE. Para mostrar as linhas, acrescente-as lista de exibio (com os valores apropriados da posio x e y). O cdigo a seguir, por exemplo, usa as classes FTE para exibir "Hello World!". This is Flash Text Engine!" (Ol a todos, esse o Flash Text Engine), usando o formato e os valores de fonte padro. Neste exemplo simples, criada apenas uma linha de texto.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

384

package { import flash.text.engine.*; import flash.display.Sprite; public class HelloWorldExample extends Sprite { public function HelloWorldExample() { var str = "Hello World! This is Flash Text Engine!"; var format:ElementFormat = new ElementFormat(); var textElement:TextElement = new TextElement(str, format); var textBlock:TextBlock = new TextBlock(); textBlock.content = textElement; var textLine1:TextLine = textBlock.createTextLine(null, 300); addChild(textLine1); textLine1.x = 30; textLine1.y = 30; } } }

Os parmetros para createTextLine() especificam a linha a partir de qual inicia a nova linha e a largura da linha em pixels. A linha a partir da qual se inicia a nova linha , normalmente, a linha anterior, contudo, no caso da primeira linha, ela null.

Adio dos objetos GraphicElement e GroupElement

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior possvel atribuir um objeto GraphicElement para um objeto TextBlock a fim de exibir uma imagem ou um elemento grfico. Simplesmente, crie uma instncia da classe GraphicElement de um grfico ou de uma imagem e atribua a instncia para a propriedade TextBlock.content. Crie a linha de texto chamando TextBlock.createTextline() como voc faz normalmente. O exemplo a seguir cria duas linhas de texto, uma com um objeto GraphicElement e outra com um objeto TextElement.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

385

package { import import import import

flash.text.engine.*; flash.display.Sprite; flash.display.Shape; flash.display.Graphics;

public class GraphicElementExample extends Sprite { public function GraphicElementExample() { var str:String = "Beware of Dog!"; var triangle:Shape = new Shape(); triangle.graphics.beginFill(0xFF0000, 1); triangle.graphics.lineStyle(3); triangle.graphics.moveTo(30, 0); triangle.graphics.lineTo(60, 50); triangle.graphics.lineTo(0, 50); triangle.graphics.lineTo(30, 0); triangle.graphics.endFill(); var format:ElementFormat = new ElementFormat(); format.fontSize = 20; var graphicElement:GraphicElement = new GraphicElement(triangle, triangle.width, triangle.height, format); var textBlock:TextBlock = new TextBlock(); textBlock.content = graphicElement; var textLine1:TextLine = textBlock.createTextLine(null, triangle.width); textLine1.x = 50; textLine1.y = 110; addChild(textLine1); var textElement:TextElement = new TextElement(str, format); textBlock.content = textElement; var textLine2 = textBlock.createTextLine(null, 300); addChild(textLine2); textLine2.x = textLine1.x - 30; textLine2.y = textLine1.y + 15; } } }

Voc pode criar um objeto GroupElement para criar um grupo de objetos TextElement, GraphicElement, e outros objetos GroupElement. Um GroupElement pode ser atribudo propriedade content de um objeto TextBlock. O parmetro para o construtor GroupElement() um Vetor, que aponta para os elementos de texto, grficos e de grupo que formam o grupo. O exemplo a seguir agrupa dois elementos grficos e um elemento de texto e os designa como unidade para um bloco de texto.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

386

package { import import import import

flash.text.engine.*; flash.display.Sprite; flash.display.Shape; flash.display.Graphics;

public class GroupElementExample extends Sprite { public function GroupElementExample() { var str:String = "Beware of Alligators!"; var triangle1:Shape = new Shape(); triangle1.graphics.beginFill(0xFF0000, 1); triangle1.graphics.lineStyle(3); triangle1.graphics.moveTo(30, 0); triangle1.graphics.lineTo(60, 50); triangle1.graphics.lineTo(0, 50); triangle1.graphics.lineTo(30, 0); triangle1.graphics.endFill(); var triangle2:Shape = new Shape(); triangle2.graphics.beginFill(0xFF0000, 1); triangle2.graphics.lineStyle(3); triangle2.graphics.moveTo(30, 0); triangle2.graphics.lineTo(60, 50); triangle2.graphics.lineTo(0, 50); triangle2.graphics.lineTo(30, 0); triangle2.graphics.endFill(); var format:ElementFormat = new ElementFormat(); format.fontSize = 20; var graphicElement1:GraphicElement = new GraphicElement(triangle1, triangle1.width, triangle1.height, format); var textElement:TextElement = new TextElement(str, format); var graphicElement2:GraphicElement = new GraphicElement(triangle2, triangle2.width, triangle2.height, format); var groupVector:Vector.<ContentElement> = new Vector.<ContentElement>(); groupVector.push(graphicElement1, textElement, graphicElement2); var groupElement = new GroupElement(groupVector); var textBlock:TextBlock = new TextBlock(); textBlock.content = groupElement; var textLine:TextLine = textBlock.createTextLine(null, 800); addChild(textLine); textLine.x = 100; textLine.y = 200; } } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

387

Substituio de texto
Flash Player 10 e posterior, Adobe AIR 1.5 e posterior possvel substituir texto em uma ocorrncia de TextBlock chamando TextElement.replaceText() para substituir o texto no TextElement que voc atribuiu propriedade TextBlock.content. O exemplo a seguir usa replaceText() para primeiro inserir texto no incio da linha, depois anexar texto ao final da linha e por fim substituir texto no meio da linha.
package { import flash.text.engine.*; import flash.display.Sprite; public class ReplaceTextExample extends Sprite { public function ReplaceTextExample() { var str:String = "Lorem ipsum dolor sit amet"; var fontDescription:FontDescription = new FontDescription("Arial"); var format:ElementFormat = new ElementFormat(fontDescription); format.fontSize = 14; var textElement:TextElement = new TextElement(str, format); var textBlock:TextBlock = new TextBlock(); textBlock.content = textElement; createLine(textBlock, 10); textElement.replaceText(0, 0, "A text fragment: "); createLine(textBlock, 30); textElement.replaceText(43, 43, "..."); createLine(textBlock, 50); textElement.replaceText(23, 28, "(ipsum)"); createLine(textBlock, 70); } function createLine(textBlock:TextBlock, y:Number):void { var textLine:TextLine = textBlock.createTextLine(null, 300); textLine.x = 10; textLine.y = y; addChild(textLine); } } }

O mtodo replaceText() substitui o texto especificado pelos parmetros beginIndex e endIndex pelo texto especificado pelo parmetro newText. Se os valores dos parmetros beginIndex e endIndex forem idnticos, replaceText() inserir o texto especificado nesse local. Caso contrrio, ele substituir pelo novo texto os caracteres especificados por beginIndex e endIndex.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

388

Manipulao de eventos no FTE

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior possvel adicionar ouvintes de eventos a uma instncia do TextLine assim como a outros objetos de exibio. Por exemplo, possvel detectar quando um usurio passa o mouse sobre uma linha de texto ou um usurio clica na linha. O exemplo a seguir detecta ambos os eventos. Quando o usurio passar o mouse sobre a linha, o cursor mudar para um cursor de boto, e quando ele clicar na linha, a cor do cursor mudar.
package { import import import import import

flash.text.engine.*; flash.ui.Mouse; flash.display.Sprite flash.events.MouseEvent; flash.events.EventDispatcher;

public class EventHandlerExample extends Sprite { var textBlock:TextBlock = new TextBlock(); public function EventHandlerExample():void { var str:String = "I'll change color if you click me."; var fontDescription:FontDescription = new FontDescription("Arial"); var format:ElementFormat = new ElementFormat(fontDescription, 18); var textElement = new TextElement(str, format); textBlock.content = textElement; createLine(textBlock); } private function createLine(textBlock:TextBlock):void { var textLine:TextLine = textBlock.createTextLine(null, 500); textLine.x = 30; textLine.y = 30; addChild(textLine); textLine.addEventListener("mouseOut", mouseOutHandler); textLine.addEventListener("mouseOver", mouseOverHandler); textLine.addEventListener("click", clickHandler); } private function mouseOverHandler(event:MouseEvent):void { Mouse.cursor = "button"; } private function mouseOutHandler(event:MouseEvent):void { Mouse.cursor = "arrow"; } function clickHandler(event:MouseEvent):void { if(textBlock.firstLine) removeChild(textBlock.firstLine);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

389

var newFormat:ElementFormat = textBlock.content.elementFormat.clone(); switch(newFormat.color) { case 0x000000: newFormat.color = 0xFF0000; break; case 0xFF0000: newFormat.color = 0x00FF00; break; case 0x00FF00: newFormat.color = 0x0000FF; break; case 0x0000FF: newFormat.color = 0x000000; break; } textBlock.content.elementFormat = newFormat; createLine(textBlock); } } }

Espelhamento de eventos
Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Tambm possvel espelhar os eventos em um bloco de texto ou em uma parte de um bloco de texto para um dispatcher de eventos. Em primeiro lugar, crie uma instncia do EventDispatcher e a atribua propriedade eventMirror de uma instncia do TextElement. Se o bloco for composto de um nico elemento de texto, o mecanismo espelhar eventos para todo o bloco de texto. Se o texto for composto de vrios elementos de texto, o mecanismo espelhar eventos apenas para as instncias do TextElement que tenham a propriedade eventMirror definida. O texto no exemplo a seguir composto por trs elementos: a palavra "Click" (Clique), a palavra "here" (aqui) e a sequncia de caracteres "to see me in italic" (para me ver em itlico). O exemplo designa um dispatcher de eventos ao segundo elemento de texto, a palavra "here" e adiciona um ouvinte de eventos, o mtodo clickHandler(). O mtodo clickHandler() altera o texto para itlico. Ele substitui tambm o contedo do terceiro elemento para rezar "Click here to see me in normal font!" (Clique aqui para me ver em fonte normal!)

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

390

package { import import import import import

flash.text.engine.*; flash.ui.Mouse; flash.display.Sprite; flash.events.MouseEvent; flash.events.EventDispatcher;

public class EventMirrorExample extends Sprite { var fontDescription:FontDescription = new FontDescription("Helvetica", "bold"); var format:ElementFormat = new ElementFormat(fontDescription, 18); var textElement1 = new TextElement("Click ", format); var textElement2 = new TextElement("here ", format); var textElement3 = new TextElement("to see me in italic! ", format); var textBlock:TextBlock = new TextBlock(); public function EventMirrorExample() { var myEvent:EventDispatcher = new EventDispatcher(); myEvent.addEventListener("click", clickHandler); myEvent.addEventListener("mouseOut", mouseOutHandler); myEvent.addEventListener("mouseOver", mouseOverHandler); textElement2.eventMirror=myEvent; var groupVector:Vector.<ContentElement> = new Vector.<ContentElement>; groupVector.push(textElement1, textElement2, textElement3); var groupElement:GroupElement = new GroupElement(groupVector); textBlock.content = groupElement; createLines(textBlock); } private function clickHandler(event:MouseEvent):void { var newFont:FontDescription = new FontDescription(); newFont.fontWeight = "bold"; var newFormat:ElementFormat = new ElementFormat(); newFormat.fontSize = 18; if(textElement3.text == "to see me in italic! ") { newFont.fontPosture = FontPosture.ITALIC; textElement3.replaceText(0,21, "to see me in normal font! "); } else { newFont.fontPosture = FontPosture.NORMAL; textElement3.replaceText(0, 26, "to see me in italic! "); } newFormat.fontDescription = newFont; textElement1.elementFormat = newFormat; textElement2.elementFormat = newFormat; textElement3.elementFormat = newFormat; createLines(textBlock); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

391

private function mouseOverHandler(event:MouseEvent):void { Mouse.cursor = "button"; } private function mouseOutHandler(event:MouseEvent):void { Mouse.cursor = "arrow"; } private function createLines(textBlock:TextBlock):void { if(textBlock.firstLine) removeChild (textBlock.firstLine); var textLine:TextLine = textBlock.createTextLine (null, 300); textLine.x = 15; textLine.y = 20; addChild (textLine); } } }

As funes mouseOverHandler() e mouseOutHandler() muda o cursor para um cursor de boto quando ele est passando sobre a palavra "here" e o retorna para uma seta quando no est.

Formatao de texto
Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Um objeto TextBlock uma fbrica para criao de linhas de texto. O contedo de um TextBlock designado pelo objeto TextElement. Um objeto ElementFormat manipula a formatao do texto. A classe ElementFormat define propriedades como alinhamento da linha de base, ajuste de espao, tracking, rotao de texto, alm de tamanho, cor e caixa de fonte. Tambm inclui uma FontDescription, abordada em detalhes em Trabalho com fontes na pgina 395.

Uso do objeto ElementFormat

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior O construtor do objeto ElementFormat adota qualquer item de uma lista longa de parmetros opcionais, incluindo uma FontDescription. Tambm possvel definir essas propriedades fora do construtor. O exemplo a seguir mostra o relacionamento de vrios objetos na definio e exibio de uma linha de texto simples.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

392

package { import flash.display.Sprite; import flash.text.*; public class ElementFormatExample extends Sprite { private var tb:TextBlock = new TextBlock(); private var te:TextElement; private var ef:ElementFormat; private var fd:FontDescription = new FontDescription(); private var str:String; private var tl:TextLine; public function ElementFormatExample() { fd.fontName = "Garamond"; ef = new ElementFormat(fd); ef.fontSize = 30; ef.color = 0xFF0000; str = "This is flash text"; te = new TextElement(str, ef); tb.content = te; tl = tb.createTextLine(null,600); addChild(tl); } } }

Cor e transparncia (alfa) da fonte

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior A propriedade color do objeto ElementFormat define a cor da fonte. O valor um inteiro que representa os componentes RGB da cor, por exemplo, 0xFF0000 para vermelho e 0x00FF00 para verde. O padro preto (0x000000). A propriedade alpha define o valor da transferncia alfa para um elemento (TextElement e GraphicElement). Os valores podem variar de 0 (totalmente transparente) a 1 (totalmente opaco, que a definio padro). Elementos com alpha igual a 0 so invisveis, porm ativos. Esse valor multiplicado por quaisquer valores alfa herdados, tornando o elemento mais transparente.
var ef:ElementFormat = new ElementFormat(); ef.alpha = 0.8; ef.color = 0x999999;

Alinhamento e deslocamento de linha de base

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior A fonte e o tamanho do texto maior em uma linha determina sua linha de base dominante. possvel substituir esses valores definindo TextBlock.baselineFontDescription e TextBlock.baselineFontSize. possvel alinhar a linha de base dominante com uma das diversas linhas de base dentro do texto. Essas linhas de base incluem as linhas ascendente e descendente ou as partes superior, inferior e central do ideograma.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

393

A. Ascendente B. Linha de base C. Descendente D. Altura do x

No objeto ElementFormat, trs propriedades determinam as caractersticas da linha de base e do alinhamento. A propriedade alignmentBaseline define a linha de base principal de um TextElement ou GraphicElement. Essa linha de base a linha "de encaixe" do elemento, e a base de linha dominante de todo o texto se alinha em relao sua posio. A propriedade dominantBaseline especifica quais linhas de base do elemento usar, o que determina a posio vertical do elemento na linha. O valor padro TextBaseline.ROMAN, mas tambm pode ser definido de modo que IDEOGRAPHIC_TOP ou IDEOGRAPHIC_BOTTOM seja a linha de base dominante. A propriedade baselineShift move a linha de base por um nmero de pixels definidos no eixo y. No texto normal (no girado), um valor positivo move a linha de base para baixo e um valor negativo, para cima.

Caixa tipogrfica
Flash Player 10 e posterior, Adobe AIR 1.5 e posterior A propriedade TypographicCase de ElementFormat especifica a caixa de texto como maiscula, minscula ou versalete.
var ef_Upper:ElementFormat = new ElementFormat(); ef_Upper.typographicCase = TypographicCase.UPPERCASE; var ef_SmallCaps:ElementFormat = new ElementFormat(); ef_SmallCaps.typographicCase = TypographicCase.SMALL_CAPS;

Giro de texto
Flash Player 10 e posterior, Adobe AIR 1.5 e posterior possvel girar um bloco de texto ou os glifos dentro de um segmento de texto em incrementos de 90. A classe TextRotation define as seguintes constantes para definir o giro de bloco de texto e glifo:
Constante AUTO Valor auto Descrio Especifica um giro de 90 no sentido anti-horrio. Usada, normalmente, com a fonte asitica vertical para girar apenas glifos que exigem rotao. No especifica nenhuma rotao. Especifica um giro de 180. Especifica um giro de 270. Especifica um giro de 90 no sentido horrio.

ROTATE_0 ROTATE_180 ROTATE_270 ROTATE_90

rotate_0 rotate_180 rotate_270 rotate_90

Para girar as linhas de texto em um bloco de texto, defina a propriedade TextBlock.lineRotation antes de chamar o mtodo TextBlock.createTextLine() para criar a linha de texto.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

394

Para girar os glifos em um bloco de texto ou segmento, defina a propriedade ElementFormat.textRotation como o nmero de graus que o glifo deve ser girado. Um glifo a forma que compe um caractere ou uma parte de um caractere composto de vrios glifos. A letra "a" e o ponto em um "i", por exemplo, so glifos. O giro dos glifos importante em alguns idiomas asiticos em qual se quer girar as linhas para vertical, sem girar os caracteres dentro das linhas. Para obter mais informaes sobre o giro de texto asitico, consulte Justificao de texto do leste asitico na pgina 399. Este um exemplo de giro de um bloco de texto e dos glifos internos, que pode ser aplicativo a um texto asitico. O exemplo tambm usa uma fonte japonesa:
package { import flash.display.Sprite; import flash.text.*; public class RotationExample extends Sprite { private var tb:TextBlock = new TextBlock(); private var te:TextElement; private var ef:ElementFormat; private var fd:FontDescription = new FontDescription(); private var str:String; private var tl:TextLine; public function RotationExample() { fd.fontName = "MS Mincho"; ef = new ElementFormat(fd); ef.textRotation = TextRotation.AUTO; str = "This is rotated Japanese text"; te = new TextElement(str, ef); tb.lineRotation = TextRotation.ROTATE_90; tb.content = te; tl = tb.createTextLine(null,600); addChild(tl); } } }

Bloqueio e clonagem de ElementFormat

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Quando um objeto ElementFormat for atribudo a qualquer tipo de ContentElement, sua propriedade locked ser automaticamente definida como true. A tentativa para modificar um objeto ElementFormat bloqueado emite um IllegalOperationError. A prtica recomendada definir completamente tal objeto antes de atribu-lo a uma instncia do TextElement. Para modificar uma instncia do ElementFormat existente, primeiro verifique sua propriedade locked. Se estiver definida como true, use o mtodoclone() para criar uma cpia desbloqueada do objeto. As propriedades desse objeto desbloqueado podem ser alteradas e possvel atribu-lo instncia do TextElement. Quaisquer linhas criadas a partir de ento tero a nova formatao. As linhas desse mesmo objeto criadas anteriormente, e usando o formato antigo, permanecero inalteradas.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

395

package { import flash.display.Sprite; import flash.text.*; public class ElementFormatCloneExample extends Sprite { private var tb:TextBlock = new TextBlock(); private var te:TextElement; private var ef1:ElementFormat; private var ef2:ElementFormat; private var fd:FontDescription = new FontDescription(); public function ElementFormatCloneExample() { fd.fontName = "Garamond"; ef1 = new ElementFormat(fd); ef1.fontSize = 24; var str:String = "This is flash text"; te = new TextElement(str, ef); tb.content = te; var tx1:TextLine = tb.createTextLine(null,600); addChild(tx1); ef2 = (ef1.locked) ? ef1.clone() : ef1; ef2.fontSize = 32; tb.content.elementFormat = ef2; var tx2:TextLine = tb.createTextLine(null,600); addChild(tx2); } } }

Trabalho com fontes

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior O objeto FontDescription usado em conjunto com ElementFormat para identificar uma face de fonte e definir algumas de suas caractersticas. Essas caractersticas incluem o nome da fonte, peso, postura, renderizao e como localizar a fonte (de dispositivo versus incorporada). Nota: O FTE no oferece suporte a fontes de Tipo 1 ou fontes de bitmap, como Tipo 3, ATC, sfnt-wrapped CID ou Naked CID.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

396

Definio das caractersticas da fonte (objeto FontDescription)

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior A propriedade fontName do objeto FontDescription pode ser um nome individual ou uma lista separada por vrgulas de nomes. Por exemplo, em uma lista como Arial, Helvetica, _sans, o mecanismo de texto procura, primeiro, Arial, em seguida, Helvetica e, finalmente, _sans se no for possvel localizar as duas primeiras fontes. O conjunto de nomes de fontes inclui trs nomes de fontes de dispositivo genricos _sans, _serif e _typewriter. Eles mapeiam a fontes de dispositivos especficos, dependendo do sistema de reproduo. prtica recomendada especificar o nome padro, por exemplo, os especificados em todas as descries de fontes que usam fontes de dispositivo. Se nenhum fontName for especificado, _serif ser usado como padro. A propriedade fontPosture pode ser definida como padro (FontPosture.NORMAL) ou como itlico (FontPosture.ITALIC). A propriedade fontWeight pode ser definida como padro (FontWeight.NORMAL) ou como negrito (FontWeight.BOLD).
var fd1:FontDescription = new FontDescription(); fd1.fontName = "Arial, Helvetica, _sans"; fd1.fontPosture = FontPosture.NORMAL; fd1.fontWeight = FontWeight.BOLD;

Fontes incorporadas versus de dispositivo

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior A propriedade fontLookup do objeto FontDescription especifica se o mecanismo de texto procura uma fonte de dispositivo ou fonte incorporada para renderizar o texto. Se uma fonte de dispositivo (FontLookup.DEVICE) for especificada, o tempo de execuo procurar a fonte no sistema de reproduo. A especificao de uma fonte incorporada (FontLookup.EMBEDDED_CFF) faz com que o tempo de execuo procure uma fonte incorporada com o nome especificado no arquivo SWF. Somente fontes CFF (Formato compacto de fonte) funcionam com essa configurao. Se a fonte especificada no for localizada, uma fonte do dispositivo de fallback ser usada. As fontes de dispositivo resultam em um tamanho de arquivo SWF menor. As fontes incorporadas concedem maior fidelidade entre plataformas.
var fd1:FontDescription = new FontDescription(); fd1.fontLookup = FontLookup.EMBEDDED_CFF; fd1.fontName = "Garamond, _serif";

Modo de renderizao e instruo

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior A renderizao de CFF (Formato compacto de fonte) est disponvel a partir do Flash Player 10 e do Adobe AIR 1.5. Esse tipo de renderizao de fonte torna o texto mais legvel e permite maior qualidade de exibio para fontes em tamanhos menores. Essa configurao aplica-se apenas a fontes incorporadas. FontDescription a definio padro dessa definio (RenderingMode.CFF) para a propriedade renderingMode . possvel definir essa propriedade como RenderingMode.NORMAL a fim de corresponder o tipo de renderizao usado pelo Flash Player 7 ou verses anteriores. Quando a renderizao de CFF for selecionada, uma segunda propriedade, cffHinting, controlar como as hastes horizontais se ajustam grade de subpixels. O valor padro, CFFHinting.HORIZONTAL_STEM, usa instruo de CFF. Definir essa propriedade como CFFHinting.NONE remove a instruo, que apropriada para animao ou para tamanhos de fontes maiores.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

397

var fd1:FontDescription = new FontDescription(); fd1.renderingMode = RenderingMode.CFF; fd1.cffHinting = CFFHinting.HORIZONTAL_STEM;

Bloqueio e clonagem de FontDescription

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Quando um objeto FontDescription estiver atribudo a um ElementFormat, sua propriedade locked ser automaticamente definida como true. A tentativa para modificar um objeto FontDescription bloqueado emitiu um IllegalOperationError. A prtica recomendada definir completamente tal objeto antes de atribu-lo a uma instncia do ElementFormat. Para modificar uma instncia da FontDescription existente, primeiro verifique sua propriedade locked. Se estiver definida como true, use o mtodoclone() para criar uma cpia desbloqueada do objeto. As propriedades desse objeto desbloqueado podem ser alteradas e possvel atribu-lo instncia do ElementFormat. Quaisquer linhas criadas a partir desse TextElement tero a nova formatao. As linhas desse mesmo objeto criadas anteriormente permanecero inalteradas.
package { import flash.display.Sprite; import flash.text.*; public class FontDescriptionCloneExample extends Sprite { private var tb:TextBlock = new TextBlock(); private var te:TextElement; private var ef1:ElementFormat; private var ef2:ElementFormat; private var fd1:FontDescription = new FontDescription(); private var fd2:FontDescription; public function FontDescriptionCloneExample() { fd1.fontName = "Garamond"; ef1 = new ElementFormat(fd); var str:String = "This is flash text"; te = new TextElement(str, ef); tb.content = te; var tx1:TextLine = tb.createTextLine(null,600); addChild(tx1); fd2 = (fd1.locked) ? fd1.clone() : fd1; fd2.fontName = "Arial"; ef2 = (ef1.locked) ? ef1.clone() : ef1; ef2.fontDescription = fd2; tb.content.elementFormat = ef2; var tx2:TextLine = tb.createTextLine(null,600); addChild(tx2); } } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

398

Controle de texto
Flash Player 10 e posterior, Adobe AIR 1.5 e posterior O FTE proporcional um novo conjunto de controles de formatao de texto para manipular a justificao e o espaamento de caracteres (kerning e tracking). H tambm propriedades para controlar o modo como as linhas so quebradas e para definir as paradas de tabulao dentro das linhas.

Justificao do texto
Flash Player 10 e posterior, Adobe AIR 1.5 e posterior A justificao de texto deixa todas as linhas em um pargrafo com o mesmo comprimento ajustando o espaamento entre palavras e, algumas vezes, entre letras. O efeito alinhar texto em ambos os lados, ao passo que o espaamento entre palavras e letras varia. As colunas de texto nos jornais e revistas so frequentemente justificadas. A propriedade lineJustfication, na classe SpaceJustifier, permite o controle da justificao das linhas em um bloco de texto. A classe LineJustification define as constantes que podem ser usadas para especificar uma opo de justificao: ALL_BUT_LAST justifica tudo, menos a ltima linha do texto; ALL_INCLUDING_LAST justifica todo o texto, inclusive a ltima linha; UNJUSTIFIED, que o padro, deixa o texto sem justificao. Para justificar o texto, defina a propriedade lineJustification para uma instncia da classe SpaceJustifier e atribua essa instncia propriedade textJustifier de uma instncia do TextBlock. O exemplo a seguir cria um pargrafo em que todas as linhas do texto, menos a ltima, esto justificadas.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

399

package { import flash.text.engine.*; import flash.display.Sprite; public class JustifyExample extends Sprite { public function JustifyExample() { var str:String = "Lorem ipsum dolor sit amet, consectetur adipisicing elit, " + "sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut " + "enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut " + "aliquip ex ea commodo consequat."; var format:ElementFormat = new ElementFormat(); var textElement:TextElement=new TextElement(str,format); var spaceJustifier:SpaceJustifier=new SpaceJustifier("en",LineJustification.ALL_BUT_LAST); var textBlock:TextBlock = new TextBlock(); textBlock.content=textElement; textBlock.textJustifier=spaceJustifier; createLines(textBlock); } private function createLines(textBlock:TextBlock):void { var yPos=20; var textLine:TextLine=textBlock.createTextLine(null,150); while (textLine) { addChild(textLine); textLine.x=15; yPos+=textLine.textHeight+2; textLine.y=yPos; textLine=textBlock.createTextLine(textLine,150); } } } }

Para variar o espaamento entre letras e palavras, defina a propriedade SpaceJustifier.letterspacing como true. A ativao do espaamento entre letras reduz a ocorrncia de lacunas de m aparncia entre as palavras, o que pode ocorrer algumas vezes com a justificao simples.

Justificao de texto do leste asitico

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior A justificao de texto do leste asitico exige consideraes adicionais. Ele pode ser escrito do alto para baixo e alguns caracteres, conhecidos como kinsoku, no podem aparecer no incio ou no fim de uma linha. A classe JustificationStyle define as seguintes constantes, que especificam as opes de manipulao desses caracteres. PRIORITIZE_LEAST_ADJUSTMENT baseia a justificao na expanso ou compresso da linha, dependendo do que produz o resultado mais desejvel. PUSH_IN_KINSOKU basear a justificao na compresso do kinsoku no final da linha ou na sua expanso, caso no haja nenhum kinsoku ou se o espao no for suficiente.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

400

PUSH_OUT_ONLY baseia a justificao na expanso da linha. Para criar um bloco de texto asitico vertical, defina a

propriedade TextBlock.lineRotation para TextRotation.ROTATE_90 e defina a propriedade

ElementFormat.textRotation para TextRotation.AUTO, que o padro. A definio da propriedade textRotation para AUTO faz com que os glifos no texto permaneam na vertical em vez de virarem lateralmente quando a linha girada. A configurao AUTO gira glifos, apenas de largura e amplitude completas, 90 no sentido antihorrio, conforme determinado pelas propriedades do Unicode do glifo. O exemplo a seguir exibe um bloco vertical de texto japons e o justifica usando a opo PUSH_IN_KINSOKU. package { import import import import

flash.text.engine.*; flash.display.Stage; flash.display.Sprite; flash.system.Capabilities;

public class EastAsianJustifyExample extends Sprite { public function EastAsianJustifyExample() { var Japanese_txt:String = String.fromCharCode( 0x5185, 0x95A3, 0x5E9C, 0x304C, 0x300C, 0x653F, 0x5E9C, 0x30A4, 0x30F3, 0x30BF, 0x30FC, 0x30CD, 0x30C3, 0x30C8, 0x30C6, 0x30EC, 0x30D3, 0x300D, 0x306E, 0x52D5, 0x753B, 0x914D, 0x4FE1, 0x5411, 0x3051, 0x306B, 0x30A2, 0x30C9, 0x30D3, 0x30B7, 0x30B9, 0x30C6, 0x30E0, 0x30BA, 0x793E, 0x306E) var textBlock:TextBlock = new TextBlock(); var font:FontDescription = new FontDescription(); var format:ElementFormat = new ElementFormat(); format.fontSize = 12; format.color = 0xCC0000; format.textRotation = TextRotation.AUTO; textBlock.baselineZero = TextBaseline.IDEOGRAPHIC_CENTER; var eastAsianJustifier:EastAsianJustifier = new EastAsianJustifier("ja", LineJustification.ALL_BUT_LAST); eastAsianJustifier.justificationStyle = JustificationStyle.PUSH_IN_KINSOKU; textBlock.textJustifier = eastAsianJustifier; textBlock.lineRotation = TextRotation.ROTATE_90; var linePosition:Number = this.stage.stageWidth - 75; if (Capabilities.os.search("Mac OS") > -1) // set fontName: Kozuka Mincho Pro R

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

401

font.fontName = String.fromCharCode(0x5C0F, 0x585A, 0x660E, 0x671D) + " Pro R"; else font.fontName = "Kozuka Mincho Pro R"; textBlock.content = new TextElement(Japanese_txt, format); var previousLine:TextLine = null; while (true) { var textLine:TextLine = textBlock.createTextLine(previousLine, 200); if (textLine == null) break; textLine.y = 20; textLine.x = linePosition; linePosition -= 25; addChild(textLine); previousLine = textLine; } } } }

Kerning e tracking
Flash Player 10 e posterior, Adobe AIR 1.5 e posterior O kerning e o tracking afetam a distncia entre os pares adjacentes de caracteres em um bloco de texto. O kerning controla como os pares de caracteres "se ajustam" entre si, por exemplo, os pares "WA" ou "Va". O kerning est definido no objeto ElementFormat. Est ativado por padro (Kerning.ON) e pode ser definido como OFF ou AUTO; nesse caso, o kerning ser aplicado entre os caracteres apenas se no forem Kanji, Hiragana ou Katakana. O tracking adiciona ou subtrai um conjunto de nmeros de pixels entre todos os caracteres em um bloco de texto e definido tambm no objeto ElementFormat. Trabalha com ambas as fontes, incorporadas e de dispositivo. O FTE suporta duas propriedades de tracking: trackingLeft, que adiciona/subtrai pixels do lado esquerdo de um caractere, e trackingRight, que adiciona/subtrai do lado direito. Se o kerning estiver sendo usado, o valor de tracking ser adicionado ou subtrado dos valores do kerning de cada par de caracteres.
A

VAY VAY VAY

VAY VAY VY A

A. Kerning.OFF B. TrackingRight=5, Kerning.OFF C. TrackingRight=-5, Kerning.OFF D. Kerning.ON E. TrackingRight=-5, Kerning.ON F. TrackingRight=-5, Kerning.ON

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

402

var ef1:ElementFormat = new ElementFormat(); ef1.kerning = Kerning.OFF; var ef2:ElementFormat = new ElementFormat(); ef2.kerning = Kerning.ON; ef2.trackingLeft = 0.8; ef2.trackingRight = 0.8; var ef3:ElementFormat = new ElementFormat(); ef3.trackingRight = -0.2;

Quebras de linhas para texto disposto

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior A propriedade breakOpportunity do objeto ElementFormat determina que caracteres podem ser usado para quebra de linha quando o texto est disposto em vrias linhas. O padro, BreakOpportunity.AUTO, usa as propriedades padro do Unicode, como a quebra entre palavras ou nos hfens. O uso de BreakOpportunity.ALL permite que qualquer caractere seja tratado como uma oportunidade de quebra de linha, o que til para a criao de efeitos como texto ao longo de um caminho.
var ef:ElementFormat = new ElementFormat(); ef.breakOpportunity = BreakOpportunity.ALL;

Paradas de tabulao
Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Para definir as paradas de tabulao em um bloco de texto, defina as paradas de tabulao criando instncias da classe TabStop. Os parmetros para o construtor TabStop() especifica como o texto se alinha parada de tabulao. Esses parmetros especificam a posio da parada de tabulao e, no caso do alinhamento decimal, o valor em que alinhar, expresso como uma sequncia de caracteres. Normalmente, esse valor um ponto decimal, mas tambm pode ser uma vrgula, um cifro ou o smbolo do Yen ou Euro, por exemplo. A linha de cdigo a seguir cria uma parada de tabulao denominada tab1.
var tab1:TabStop = new TabStop(TabAlignment.DECIMAL, 50, ".");

Depois da criao das paradas de tabulao para um bloco de texto, atribua-as propriedade tabStops de uma instncia do TextBlock. Como a propriedade tabStops requer um Vetor, crie primeiro o Vetor e, depois, adicione as paradas de tabulao a ele. O Vetor permite que voc designe um conjunto de paradas de tabulao ao bloco de texto. O exemplo a seguir cria uma instncia do Vector<TabStop> e inclui um conjunto de objetos TabStop nele. Em seguida, ele atribui as paradas de tabulao propriedade tabStops de uma instncia do TextBlock.
var tabStops:Vector.<TabStop> = new Vector.<TabStop>(); tabStops.push(tab1, tab2, tab3, tab4); textBlock.tabStops = tabStops

Para obter mais informaes sobre Vetores, consulte Trabalho com matrizes na pgina 25. O exemplo a seguir mostra o efeito de cada opo de alinhamento TabStop.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

403

package { import flash.text.engine.*; import flash.display.Sprite; public class TabStopExample extends Sprite { public function TabStopExample() { var format:ElementFormat = new ElementFormat(); format.fontDescription = new FontDescription("Arial"); format.fontSize = 16; var tabStops:Vector.<TabStop> = new Vector.<TabStop>(); tabStops.push( new TabStop(TabAlignment.START, 20), new TabStop(TabAlignment.CENTER, 140), new TabStop(TabAlignment.DECIMAL, 260, "."), new TabStop(TabAlignment.END, 380)); var textBlock:TextBlock = new TextBlock(); textBlock.content = new TextElement( "\tt1\tt2\tt3\tt4\n" + "\tThis line aligns on 1st tab\n" + "\t\t\t\tThis is the end\n" + "\tThe following fragment centers on the 2nd tab:\t\t\n" + "\t\tit's on me\t\t\n" + "\tThe following amounts align on the decimal point:\n" + "\t\t\t45.00\t\n" + "\t\t\t75,320.00\t\n" + "\t\t\t6,950.00\t\n" + "\t\t\t7.01\t\n", format); textBlock.tabStops = tabStops; var yPosition:Number = 60; var previousTextLine:TextLine = null; var textLine:TextLine; var i:int; for (i = 0; i < 10; i++) { textLine = textBlock.createTextLine(previousTextLine, 1000, 0); textLine.x = 20; textLine.y = yPosition; addChild(textLine); yPosition += 25; previousTextLine = textLine; } } } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

404

Exemplo de Flash Text Engine: layout das notcias

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Este exemplo de programao mostra o Flash Text Engine em uso organizando uma pgina simples de jornal. A pgina inclui um ttulo grande, um subttulo e uma seo de corpo com vrias colunas. Em primeiro lugar, crie um arquivo FLA e acrescente o cdigo a seguir ao quadro #2 da camada padro:
import com.example.programmingas3.newslayout.StoryLayout ; // frame sc ript - create a 3-columned arti cle layout var story:StoryLayout = new StoryLayout(720, 500, 3, 10); story.x = 20; story.y = 80; addChild(story); stop();

StoryLayout.as o script do controlador desse exemplo. Ele define o contedo, l as informaes de estilo de uma folha de estilos e atribui tais estilos aos objetos ElementFormat. Em seguida, cria o ttulo, subttulo e elementos de texto de vrias colunas.
package com.example.programmingas3.newslayout { import flash.display.Sprite; import flash.text.StyleSheet; import flash.text.engine.*; import import import import import flash.events.Event; flash.net.URLRequest; flash.net.URLLoader; flash.display.Sprite; flash.display.Graphics;

public class StoryLayout extends Sprite { public var headlineTxt:HeadlineTextField; public var subtitleTxt:HeadlineTextField; public var storyTxt:MultiColumnText; public var sheet:StyleSheet; public var h1_ElFormat:ElementFormat; public var h2_ElFormat:ElementFormat; public var p_ElFormat:ElementFormat; private var loader:URLLoader; public public public public var var var var paddingLeft:Number; paddingRight:Number; paddingTop:Number; paddingBottom:Number;

public var preferredWidth:Number; public var preferredHeight:Number; public var numColumns:int; public var bgColor:Number = 0xFFFFFF;

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

405

public var headline:String = "News Layout Example"; public var subtitle:String = "This example formats text like a newspaper page using the Flash Text Engine API. "; public var rawTestData:String = "From the part Mr. Burke took in the American Revolution, it was natural that I should consider him a friend to mankind; and as our acquaintance commenced on that ground, it would have been more agreeable to me to have had cause to continue in that opinion than to change it. " + "At the time Mr. Burke made his violent speech last winter in the English Parliament against the French Revolution and the National Assembly, I was in Paris, and had written to him but a short time before to inform him how prosperously matters were going on. Soon after this I saw his advertisement of the Pamphlet he intended to publish: As the attack was to be made in a language but little studied, and less understood in France, and as everything suffers by translation, I promised some of the friends of the Revolution in that country that whenever Mr. Burke's Pamphlet came forth, I would answer it. This appeared to me the more necessary to be done, when I saw the flagrant misrepresentations which Mr. Burke's Pamphlet contains; and that while it is an outrageous abuse on the French Revolution, and the principles of Liberty, it is an imposition on the rest of the world. " + "I am the more astonished and disappointed at this conduct in Mr. Burke, as (from the circumstances I am going to mention) I had formed other expectations. " + "I had seen enough of the miseries of war, to wish it might never more have existence in the world, and that some other mode might be found out to settle the differences that should occasionally arise in the neighbourhood of nations. This certainly might be done if Courts were disposed to set honesty about it, or if countries were enlightened enough not to be made the dupes of Courts. The people of America had been bred up in the same prejudices against France, which at that time characterised the people of England; but experience and an acquaintance with the French Nation have most effectually shown to the Americans the falsehood of those prejudices; and I do not believe that a more cordial and confidential intercourse exists between any two countries than between America and France. "; public function StoryLayout(w:int = 400, h:int = 200, cols:int = 3, padding:int = 10):void { this.preferredWidth = w; this.preferredHeight = h; this.numColumns = cols; this.paddingLeft = padding; this.paddingRight = padding; this.paddingTop = padding; this.paddingBottom = padding; var req:URLRequest = new URLRequest("story.css"); loader = new URLLoader(); loader.addEventListener(Event.COMPLETE, onCSSFileLoaded); loader.load(req); } public function onCSSFileLoaded(event:Event):void { this.sheet = new StyleSheet(); this.sheet.parseCSS(loader.data); // convert headline styles to ElementFormat objects h1_ElFormat = getElFormat("h1", this.sheet);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

406

h1_ElFormat.typographicCase = TypographicCase.UPPERCASE; h2_ElFormat = getElFormat("h2", this.sheet); p_ElFormat = getElFormat("p", this.sheet); displayText(); } public function drawBackground():void { var h:Number = this.storyTxt.y + this.storyTxt.height + this.paddingTop + this.paddingBottom; var g:Graphics = this.graphics; g.beginFill(this.bgColor); g.drawRect(0, 0, this.width + this.paddingRight + this.paddingLeft, h); g.endFill(); } /** * Reads a set of style properties for a named style and then creates * a TextFormat object that uses the same properties. */ public function getElFormat(styleName:String, ss:StyleSheet):ElementFormat { var style:Object = ss.getStyle(styleName); if (style != null) { var colorStr:String = style.color; if (colorStr != null && colorStr.indexOf("#") == 0) { style.color = colorStr.substr(1); } var fd:FontDescription = new FontDescription( style.fontFamily, style.fontWeight, FontPosture.NORMAL, FontLookup.DEVICE, RenderingMode.NORMAL, CFFHinting.NONE); var format:ElementFormat = new ElementFormat(fd, style.fontSize, style.color, 1, TextRotation.AUTO, TextBaseline.ROMAN, TextBaseline.USE_DOMINANT_BASELINE, 0.0, Kerning.ON, 0.0, 0.0, "en", BreakOpportunity.AUTO, DigitCase.DEFAULT, DigitWidth.DEFAULT, LigatureLevel.NONE, TypographicCase.DEFAULT); if (style.hasOwnProperty("letterSpacing")) {

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

407

format.trackingRight = style.letterSpacing; } } return format; } public function displayText():void { headlineTxt = new HeadlineTextField(h1_ElFormat,headline,this.preferredWidth); headlineTxt.x = this.paddingLeft; headlineTxt.y = 40 + this.paddingTop; headlineTxt.fitText(1); this.addChild(headlineTxt); subtitleTxt = new HeadlineTextField(h2_ElFormat,subtitle,this.preferredWidth); subtitleTxt.x = this.paddingLeft; subtitleTxt.y = headlineTxt.y + headlineTxt.height; subtitleTxt.fitText(2); this.addChild(subtitleTxt); storyTxt = new MultiColumnText(rawTestData, this.numColumns, 20, this.preferredWidth, this.preferredHeight, p_ElFormat); storyTxt.x = this.paddingLeft; storyTxt.y = subtitleTxt.y + subtitleTxt.height + 10; this.addChild(storyTxt); drawBackground(); } } }

FormattedTextBlock.as usado como uma classe base para criao de blocos de texto. Inclui tambm funes utilitrias para alterao do tamanho e caixa da fonte.
package com.example.programmingas3.newslayout { import flash.text.engine.*; import flash.display.Sprite; public class FormattedTextBlock extends Sprite { public var tb:TextBlock; private var te:TextElement; private var ef1:ElementFormat; private var textWidth:int; public var totalTextLines:int; public var blockText:String; public var leading:Number = 1.25; public var preferredWidth:Number = 720; public var preferredHeight:Number = 100; public function FormattedTextBlock(ef:ElementFormat,txt:String, colW:int = 0) { this.textWidth = (colW==0) ? preferredWidth : colW; blockText = txt; ef1 = ef; tb = new TextBlock();

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

408

tb.textJustifier = new SpaceJustifier("en",LineJustification.UNJUSTIFIED,false); te = new TextElement(blockText,this.ef1); tb.content = te; this.breakLines(); } private function breakLines() { var textLine:TextLine = null; var y:Number = 0; var lineNum:int = 0; while (textLine = tb.createTextLine(textLine,this.textWidth,0,true)) { textLine.x = 0; textLine.y = y; y += this.leading*textLine.height; this.addChild(textLine); } for (var i:int = 0; i < this.numChildren; i++) { TextLine(this.getChildAt(i)).validity = TextLineValidity.STATIC; } this.totalTextLines = this.numChildren; } private function rebreakLines() { this.clearLines(); this.breakLines(); } private function clearLines() { while(this.numChildren) { this.removeChildAt(0); } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

409

public function changeSize(size:uint=12):void { if (size > 5) { var ef2:ElementFormat = ef1.clone(); ef2.fontSize = size; te.elementFormat = ef2; this.rebreakLines(); } } public function changeCase(newCase:String = "default"):void { var ef2:ElementFormat = ef1.clone(); ef2.typographicCase = newCase; te.elementFormat = ef2; } } }

HeadlineTextBlock.as estende a classe FormattedTextBlock e usado para criao de ttulos. Inclui uma funo para ajuste de texto dentro do espao definido na pgina.
package com.example.programmingas3.newslayout { import flash.text.engine.*; public class HeadlineTextField extends FormattedTextBlock { public static var MIN_POINT_SIZE:uint = 6; public static var MAX_POINT_SIZE:uint = 128; public function HeadlineTextField(te:ElementFormat,txt:String,colW:int = 0) { super(te,txt); } public function fitText(maxLines:uint = 1, targetWidth:Number = -1):uint { if (targetWidth == -1) { targetWidth = this.width; } var pixelsPerChar:Number = targetWidth / this.blockText.length; var pointSize:Number = Math.min(MAX_POINT_SIZE, Math.round(pixelsPerChar * 1.8 * maxLines)); if (pointSize < 6) { // the point size is too small return pointSize; } this.changeSize(pointSize); if (this.totalTextLines > maxLines)

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

410

{ return shrinkText(--pointSize, maxLines); } else { return growText(pointSize, maxLines); } } public function growText(pointSize:Number, maxLines:uint = 1):Number { if (pointSize >= MAX_POINT_SIZE) { return pointSize; } this.changeSize(pointSize + 1); if (this.totalTextLines > maxLines) { // set it back to the last size this.changeSize(pointSize); return pointSize; } else { return growText(pointSize + 1, maxLines); } } public function shrinkText(pointSize:Number, maxLines:uint=1):Number { if (pointSize <= MIN_POINT_SIZE) { return pointSize; } this.changeSize(pointSize); if (this.totalTextLines > maxLines) { return shrinkText(pointSize - 1, maxLines); } else { return pointSize; } } } }

MultiColumnText.as manipula a formatao de texto dentro de um design de vrias colunas. Demonstra o uso flexvel de um objeto TextBlock como uma fbrica para criao, formatao e posicionamento de linhas de texto.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

411

package com.example.programmingas3.newslayout { import flash.display.Sprite; import flash.text.engine.*; public class MultiColumnText extends Sprite { private var tb:TextBlock; private var te:TextElement; private var numColumns:uint = 2; private var gutter:uint = 10; private var leading:Number = 1.25; private var preferredWidth:Number = 400; private var preferredHeight:Number = 100; private var colWidth:int = 200; public function MultiColumnText(txt:String = "",cols:uint = 2, gutter:uint = 10, w:Number = 400, h:Number = 100, ef:ElementFormat = null):void { this.numColumns = Math.max(1, cols); this.gutter = Math.max(1, gutter); this.preferredWidth = w; this.preferredHeight = h; this.setColumnWidth(); var field:FormattedTextBlock = new FormattedTextBlock(ef,txt,this.colWidth); var totLines:int = field.totalTextLines; field = null; var linesPerCol:int = Math.ceil(totLines/cols); tb = new TextBlock(); te = new TextElement(txt,ef); tb.content = te; var textLine:TextLine = null; var x:Number = 0; var y:Number = 0; var i:int = 0; var j:int = 0; while (textLine = tb.createTextLine(textLine,this.colWidth,0,true)) { textLine.x = Math.floor(i/(linesPerCol+1))*(this.colWidth+this.gutter); textLine.y = y; y += this.leading*textLine.height;

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso do Flash Text Engine

412

j++; if(j>linesPerCol) { y = 0; j = 0; } i++; this.addChild(textLine); } } private function setColumnWidth():void { this.colWidth = Math.floor( (this.preferredWidth ((this.numColumns - 1) * this.gutter)) / this.numColumns); } } }

ltima atualizao em 29/3/2011

413

Captulo 21: Uso da Text Layout Framework

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior

Viso geral do Text Layout Framework

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior A Text Layout Framework (TLF) uma biblioteca ActionScript extensvel. A TLF construda sobre o mecanismo de texto no Adobe Flash Player 10 e no Adobe AIR 1.5. A TLF oferece recursos tipogrficos e de layout de texto avanados para proporcionar uma tipografia inovadora na Web. A estrutura pode ser usada com o Adobe Flex ou com o Adobe Flash Professional. Os desenvolvedores podem usar ou estender componentes existentes ou podem usar a estrutura para criar seus prprios componentes de texto. A TLF inclui os seguintes recursos:

Texto bidirecional, texto vertical e mais de 30 scripts de escrita, inclusive rabe, hebraico, chins, japons, coreano,
tailands, laosiano, vietnamita, entre outros

Seleo, edio e fluxo de texto em vrias colunas e contineres vinculados Texto vertical, Tate-Chu-Yoko (horizontal em texto vertical) e justificador para tipografia do leste asitico Controles tipogrficos avanados, inclusive kerning, ligaturas, caso tipogrfico, tipo de caixa de dgito, largura de
dgito e hfens facultativos

Recortar, copiar, colar, desfazer e gestos padro do teclado e do mouse para edio APIs avanadas do desenvolvedor para manipular contedo de texto, layout e marcao e criar componentes de
texto personalizados

Suporte robusto de lista com marcadores personalizados e formatos de numerao Imagens alinhadas e regras de posicionamento
A TLF uma biblioteca do ActionScript 3.0 construda com base no Flash Text Engine (FTE), lanado no Flash Player 10. O FTE pode ser acessado por meio do pacote flash.text.engine que parte da API (Interface de programao de aplicativo) do Flash Player 10. A API do Flash Player, no entanto, fornece bastante acesso de baixo nvel ao mecanismo de texto, o que significa que algumas tarefas podem exigir uma quantidade relativamente grande de cdigo. A TLF encapsula o cdigo de baixo nvel em APIs mais simples. A TLF tambm oferece uma arquitetura conceitual que organiza os elementos bsicos definidos pelo FTE em um sistema mais fcil de usar. Diferentemente do FTE, a TLF no incorporada ao Flash Player. Em vez disso, trata-se de uma biblioteca de componentes independente escrita inteiramente no ActionScript 3.0. Como a estrutura extensvel, ela pode ser personalizada para ambientes especficos. Tanto o Flash Professional quanto o Flex SDK incluem componentes baseados na estrutura da TLF.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da Text Layout Framework

414

Mais tpicos da Ajuda

"Fluxo" do aplicativo de marcao TLF

Suporte a script complexo

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior A TLF oferece suporte a script complexo. O suporte a script complexo inclui a capacidade de exibir e editar scripts da direita para a esquerda. A TLF tambm oferece a capacidade de exibir e editar uma mistura de scripts da esquerda para a direita e da direita para a esquerda, como rabe e hebraico. A estrutura oferece suporte no apenas para o layout de texto vertical para chins, japons e coreano, como tambm para tate-chuu-yoko (elementos TCY). Os elementos TCY so blocos de texto horizontal integrados em sries verticais de texto. H suporte para os seguintes scripts:

Latim (ingls, espanhol, francs, vietnamita e assim por diante) Grego, cirlico, armnio, georgiano e etope rabe e hebraico Ideogramas Han e Kana (chins, japons e coreano) e Hangul Johab (coreano) Tailands, laosiano e khmer Devanagari, Bengali, Gurmukhi, Malaio, Tlego, Tmil, Gujarati, Oriya, Kannada e Tibetano Tifinagh, Yi, Cherokee, Silbico canadense, Deseret, Shaviano, Vai, Tagalo, Hanunoo, Buhid e Tagbanwa

Uso da Text Layout Framework no Flash Professional e no Flex

Voc pode usar as classes TLF diretamente para criar componentes personalizados no Flash. Alm disso, o Flash Professional CS5 fornece uma nova classe, fl.text.TLFTextField, que encapsula a funcionalidade da TLF. Use a classe TLFTextField para criar campos de texto no ActionScript que usam os recursos de exibio de texto avanados da TLF. Crie um objeto de TLFTextField do mesmo modo que voc cria um campo de texto com a classe TextField. Em seguida, use a propriedade textFlow para atribuir a formatao avanada das classes TLF. Voc tambm pode usar o Flash Professional para criar a ocorrncia de TLFTextField no palco usando a ferramenta de texto. Em seguida, pode usar o ActionScript para controlar a formatao e o layout do contedo do campo de texto usando classes da TLF. Para obter mais informaes, consulte TLFTextField na Referncia do ActionScript 3.0 para a plataforma Adobe Flash. Se estiver trabalhando no Flex, use as classes da TLF. Para obter mais informaes, consulte Uso da Text Layout Framework na pgina 414.

Uso da Text Layout Framework

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Se estiver trabalhando no Flex ou estiver criando componentes de texto personalizados, use as classes da TLF. A TLF uma biblioteca do ActionScript 3.0 contida inteiramente na biblioteca textLayout.swc. A biblioteca TLF contm quase cem classes e interfaces do ActionScript 3.0 organizadas em dez pacotes. Esses pacotes so subpacotes do pacote flashx.textLayout.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da Text Layout Framework

415

Classes da Text Layout Framework

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior As classes da TLF podem ser agrupadas em trs categorias:

Estrutura de dados e formatao de classes Classes de renderizao Classes de interao com o usurio

Estrutura de dados e formatao de classes

Os seguintes pacotes contm as estruturas de dados e as classes de formatao da TLF:

flashx.textLayout.elements flashx.textLayout.formats flashx.textLayout.conversion

A estrutura de dados principal da TLF a hierarquia de fluxo de texto, definida no pacote de elementos. Dentro dessa estrutura, possvel atribuir estilos e atributos a execues de texto com o pacote de formatos. Voc tambm pode controlar como o texto importado para a estrutura de cados, e dela exportado, com o pacote de converso.

Classes de renderizao
Os seguintes pacotes contm as classes de renderizao da TLF:

flashx.textLayout.factory flashx.textLayout.container flashx.textLayout.compose

As classes nestes pacotes facilitam a renderizao de texto para exibio pelo Flash Player. O pacote da fbrica fornece um modo simples para exibir texto esttico. O pacote do continer inclui classes e interfaces que definem contineres de exibio de texto dinmico. O pacote composto define tcnicas para posicionamento e exibio de texto dinmico nos contineres.

Classes de interao com o usurio

Os seguintes pacotes contm as classes de interao com o usurio da TLF:

flashx.textLayout.edit flashx.textLayout.operations flashx.textLayout.events

Os pacotes de edio e operaes definem classes que podem ser usadas para permitir a edio do texto armazenado nas estruturas de dados. O pacote de eventos contm classes para tratamento de eventos.

Etapas gerais para criao de texto com a Text Layout Framework

As seguintes etapas descrevem o processo geral para criao de texto com o Text Layout Format:
1 Importe texto formatado para as estruturas de dados da TLF. Para obter mais informaes, consulte Estruturao

de texto com a TLF na pgina 419 e Formatao de texto com a TLF na pgina 423.
2 Crie um ou mais contineres de objeto de exibio vinculados para o texto. Para obter mais informaes, consulte

Gerenciamento de contineres de texto com a TLF na pgina 425.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da Text Layout Framework

416

3 Associe o texto nas estruturas de dados aos contineres e defina opes de edio e rolagem. Para obter mais

informaes, consulte Ativao da seleo de texto, edio e recurso desfazer com a TLF na pgina 426.
4 Crie um manipulador de evento para fazer o refluxo do texto em resposta a eventos de redimensionamento (ou

outros). Para obter mais informaes, consulte Tratamento de eventos com a TLF na pgina 426.

Exemplo da Text Layout Framework: layout das notcias

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior O exemplo a seguir demonstra o uso da TLF para fazer o layout de uma simples pgina de jornal. A pgina inclui um ttulo grande, um subttulo e uma seo de corpo com vrias colunas:
package { import import import import import import import import import import import

flash.display.Sprite; flash.display.StageAlign; flash.display.StageScaleMode; flash.events.Event; flash.geom.Rectangle; flashx.textLayout.compose.StandardFlowComposer; flashx.textLayout.container.ContainerController; flashx.textLayout.container.ScrollPolicy; flashx.textLayout.conversion.TextConverter; flashx.textLayout.elements.TextFlow; flashx.textLayout.formats.TextLayoutFormat;

public class TLFNewsLayout extends Sprite { private var hTextFlow:TextFlow; private var headContainer:Sprite; private var headlineController:ContainerController; private var hContainerFormat:TextLayoutFormat; private private private private var var var var bTextFlow:TextFlow; bodyTextContainer:Sprite; bodyController:ContainerController; bodyTextContainerFormat:TextLayoutFormat;

private const headlineMarkup:String = "<flow:TextFlow xmlns:flow='http://ns.adobe.com/textLayout/2008'><flow:p textAlign='center'><flow:span fontFamily='Helvetica' fontSize='18'>TLF News Layout Example</flow:span><flow:br/><flow:span fontFamily='Helvetica' fontSize='14'>This example formats text like a newspaper page with a headline, a subtitle, and multiple columns</flow:span></flow:p></flow:TextFlow>"; private const bodyMarkup:String = "<flow:TextFlow xmlns:flow='http://ns.adobe.com/textLayout/2008' fontSize='12' textIndent='10' marginBottom='15' paddingTop='4' paddingLeft='4'><flow:p marginBottom='inherit'><flow:span>There are many </flow:span><flow:span fontStyle='italic'>such</flow:span><flow:span> lime-kilns in that tract of country, for the purpose of burning the white marble which composes a large part of the substance of the hills. Some of them, built years ago, and long deserted, with weeds growing in the vacant round of the interior, which is open to the sky, and grass and wild-flowers rooting themselves into the chinks of the stones, look already like relics of antiquity, and may yet be overspread with the lichens of centuries to come. Others, where the lime-burner still feeds his daily and nightlong fire, afford points of interest to the wanderer among the hills, who seats

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da Text Layout Framework

417

himself on a log of wood or a fragment of marble, to hold a chat with the solitary man. It is a lonesome, and, when the character is inclined to thought, may be an intensely thoughtful occupation; as it proved in the case of Ethan Brand, who had mused to such strange purpose, in days gone by, while the fire in this very kiln was burning.</flow:span></flow:p><flow:p marginBottom='inherit'><flow:span>The man who now watched the fire was of a different order, and troubled himself with no thoughts save the very few that were requisite to his business. At frequent intervals, he flung back the clashing weight of the iron door, and, turning his face from the insufferable glare, thrust in huge logs of oak, or stirred the immense brands with a long pole. Within the furnace were seen the curling and riotous flames, and the burning marble, almost molten with the intensity of heat; while without, the reflection of the fire quivered on the dark intricacy of the surrounding forest, and showed in the foreground a bright and ruddy little picture of the hut, the spring beside its door, the athletic and coal-begrimed figure of the lime-burner, and the half-frightened child, shrinking into the protection of his father's shadow. And when again the iron door was closed, then reappeared the tender light of the halffull moon, which vainly strove to trace out the indistinct shapes of the neighboring mountains; and, in the upper sky, there was a flitting congregation of clouds, still faintly tinged with the rosy sunset, though thus far down into the valley the sunshine had vanished long and long ago.</flow:span></flow:p></flow:TextFlow>"; public function TLFNewsLayout() { //wait for stage to exist addEventListener(Event.ADDED_TO_STAGE, onAddedToStage); } private function onAddedToStage(evtObj:Event):void { removeEventListener(Event.ADDED_TO_STAGE, onAddedToStage); stage.scaleMode = StageScaleMode.NO_SCALE; stage.align = StageAlign.TOP_LEFT; // Headline text flow and flow composer hTextFlow = TextConverter.importToFlow(headlineMarkup, TextConverter.TEXT_LAYOUT_FORMAT); // initialize the headline container and controller objects headContainer = new Sprite(); headlineController = new ContainerController(headContainer); headlineController.verticalScrollPolicy = ScrollPolicy.OFF; hContainerFormat = new TextLayoutFormat(); hContainerFormat.paddingTop = 4; hContainerFormat.paddingRight = 4; hContainerFormat.paddingBottom = 4; hContainerFormat.paddingLeft = 4; headlineController.format = hContainerFormat; hTextFlow.flowComposer.addController(headlineController); addChild(headContainer); stage.addEventListener(flash.events.Event.RESIZE, resizeHandler); // Body text TextFlow and flow composer bTextFlow = TextConverter.importToFlow(bodyMarkup, TextConverter.TEXT_LAYOUT_FORMAT); // The body text container is below, and has three columns bodyTextContainer = new Sprite(); bodyController = new ContainerController(bodyTextContainer);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da Text Layout Framework

418

bodyTextContainerFormat = new TextLayoutFormat(); bodyTextContainerFormat.columnCount = 3; bodyTextContainerFormat.columnGap = 30; bodyController.format = bodyTextContainerFormat; bTextFlow.flowComposer.addController(bodyController); addChild(bodyTextContainer); resizeHandler(null); } private function resizeHandler(event:Event):void { const verticalGap:Number = 25; const stagePadding:Number = 16; var stageWidth:Number = stage.stageWidth - stagePadding; var stageHeight:Number = stage.stageHeight - stagePadding; var headlineWidth:Number = stageWidth; var headlineContainerHeight:Number = stageHeight; // Initial compose to get height of headline after resize headlineController.setCompositionSize(headlineWidth, headlineContainerHeight); hTextFlow.flowComposer.compose(); var rect:Rectangle = headlineController.getContentBounds(); headlineContainerHeight = rect.height; // Resize and place headline text container // Call setCompositionSize() again with updated headline height headlineController.setCompositionSize(headlineWidth, headlineContainerHeight ); headlineController.container.x = stagePadding / 2; headlineController.container.y = stagePadding / 2; hTextFlow.flowComposer.updateAllControllers(); // Resize and place body text container var bodyContainerHeight:Number = (stageHeight - verticalGap headlineContainerHeight); bodyController.format = bodyTextContainerFormat; bodyController.setCompositionSize(stageWidth, bodyContainerHeight ); bodyController.container.x = (stagePadding/2); bodyController.container.y = (stagePadding/2) + headlineContainerHeight + verticalGap; bTextFlow.flowComposer.updateAllControllers(); } } }

A classe TLFNewsLayout usa dois contineres de texto. Um continer exibe um ttulo e subttulo e o outro exibe o texto do corpo em trs colunas. Por uma questo de simplicidade, o texto codificado no exemplo como texto de marcao TLF. A varivel headlineMarkup contm o ttulo e o subttulo, e a varivel bodyMarkup contm o corpo do texto. Para obter mais informaes sobre a marcao da TLF, consulte Estruturao de texto com a TLF na pgina 419. Aps alguma inicializao, a funo onAddedToStage() importa o texto do ttulo para o objeto TextFlow, que a principal estrutura de dados da TLF:
hTextFlow = TextConverter.importToFlow(headlineMarkup, TextConverter.TEXT_LAYOUT_FORMAT);

Em seguida, um objeto Sprite criado para o continer e um controlador criado e associado ao continer:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da Text Layout Framework

419

headContainer = new Sprite(); headlineController = new ContainerController(headContainer);

O controlador inicializado para definir formatao e rolagem, entre outras opes. O controlador contm geometria que define os limites do continer no qual o texto flui. Um objeto TextLayoutFormat contm as opes de formatao:
hContainerFormat = new TextLayoutFormat();

O controlador atribudo ao compositor de fluxo e a funo adiciona o continer lista de exibio. A composio e a exibio reais dos contineres so adiados para o mtodo resizeHandler(). A mesma seqncia de etapas executada para inicializar o objeto TextFlow do corpo. O mtodo resizeHandler() mede o espao disponvel para renderizar os contineres e dimension-los de acordo. Uma chamada ao mtodo compose() permite calcular a altura adequada do continer de ttulo. O mtodo resizeHandler() pode ento colocar e exibir o continer de ttulo com o mtodo updateAllControllers(). Por fim, o mtodo resizeHandler() usa o tamanho do continer de ttulo para determinar a colocao do continer de texto do corpo.

Estruturao de texto com a TLF

A TLF usa uma rvore hierrquica para representar o texto. Cada n na rvore a instncia de uma classe definida no pacote de elementos. Por exemplo, o n raiz da rvore sempre uma instncia da classe TextFlow. A classe TextFlow representa uma matria inteira de texto. Uma histria uma coleo de texto e outros elementos tratada como uma unidade nica, ou fluxo. Um nico artigo histria pode exigir mais do que uma coluna ou continer de texto para ser exibida. Alm do n raiz, os elementos remanescentes baseiam-se livremente nos elementos XHTML. O diagrama a seguir mostra a hierarquia da estrutura:

Hierarquia de TextFlow

Marcao da Text Layout Framework

Compreender a estrutura da TLF tambm til ao lidar com a marcao TLF. A marcao TLF uma representao de texto que faz parte da TLF. Embora a estrutura tambm ofera suporte a outros formatos XML, a marcao TLF exclusiva pelo fato de se basear especificamente na estrutura da hierarquia TextFlow. Se voc exportar o XML de um TextFlow usando esse formato de markup, o XML ser exportado com essa hierarquia intacta.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da Text Layout Framework

420

A marcao TLF oferece a representao da mais alta fidelidade em uma hierarquia TextFlow. A linguagem da marcao fornece tags para cada um dos elementos bsicos da hierarquia TextFlow, alm de fornecer atributos para todas as propriedades de formatao disponveis na classe TextLayoutFormat. A tabela a seguir contm as tags que podem ser usadas na TLF Markup.
Elemento textflow div Descrio O elemento raiz da marcao. Uma diviso em um TextFlow. Pode conter um grupo de pargrafos. Um pargrafo. Filhos div, p div, list, p Classe TextFlow DivElement

a, tcy, span, img, tab, br, ParagraphElement g tcy, span, img, tab, br, g a, span, img, tab, br, g LinkElement TCYElement

a tcy

Um link. Uma srie de texto horizontal (usada em um TextFlow vertical). Uma srie de texto em um pargrafo. Uma imagem em um pargrafo. Um caractere de tabulao. Uma caractere de quebra. Usado para terminar uma linha em um pargrafo. O texto continua na prxima linha, mas permanece no mesmo pargrafo. Define os atributos de formatao usados para links no estado normal. Define os atributos de formatao usados para links no estado ativo, quando o mouse est sobre um link. Define os atributos de formatao usados para links no estado suspenso, quando o mouse est dentro dos limites (rolando sobre) de um link. Um elemento de item da lista. Deve estar dentro de um elemento da lista. Uma lista. As listas podem ser aninhadas, ou colocadas adjacentes entre si. Diferentes esquemas de rotulagem ou de numerao podem ser aplicados aos itens da lista.

span img tab br

SpanElement InlineGraphicElement TabElement BreakElement

linkNormalFormat

TextLayoutFormat

TextLayoutFormat

linkActiveFormat

TextLayoutFormat

TextLayoutFormat

linkHoverFormat

TextLayoutFormat

TextLayoutFormat

li

div, li, list, p

ListItemElement

list

div, li, list, p

ListElement

Um elemento do grupo. Usado para agrupar a, tcy, span, img, tab, br, SubParagraphGroupE elementos em um pargrafo. Permite aninhar g lement elementos abaixo do nvel de pargrafo.

Mais tpicos da Ajuda

Markup de listas TLF 2.0 TLF 2.0 SubParagraphGroupElements e typeName

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da Text Layout Framework

421

Usando listas enumeradas e com marcadores

possvel usar as classes ListElement e ListItemElement para incluir listas com marcadores nos controles do seu texto. As listas com marcadores podem ser aninhadas e personalizadas para usar marcadores (ou sinalizadores) diferentes e numerao automtica, assim como numerao por destaque. Para criar listas de seus fluxos de texto, use a tag <list>. Use tags <li> dentro da tag <list> para cada item de lista na lista. possvel personalizar a aparncia dos marcadores usando a classe ListMarkerFormat. O exemplo a seguir cria listas simples:
<flow:list paddingRight="24" paddingLeft="24"> <flow:li>Item 1</flow:li> <flow:li>Item 2</flow:li> <flow:li>Item 3</flow:li> </flow:list>

possvel aninhar listas dentro de outras, como mostra o exemplo a seguir:

<flow:list paddingRight="24" paddingLeft="24"> <flow:li>Item 1</flow:li> <flow:list paddingRight="24" paddingLeft="24"> <flow:li>Item 1a</flow:li> <flow:li>Item 1b</flow:li> <flow:li>Item 1c</flow:li> </flow:list> <flow:li>Item 2</flow:li> <flow:li>Item 3</flow:li> </flow:list>

Para personalizar o tipo de marcador na lista, use a propriedade listStyleType do ListElement. Esta propriedade pode ser qualquer valor definido pela classe ListStyleType (como check, circle, decimal e box). O exemplo a seguir cria listas com vrios tipos de marcadores e um incremento de contador personalizado:
<flow:list paddingRight="24" paddingLeft="24" listStyleType="upperAlpha"> <flow:li>upperAlpha item</flow:li> <flow:li>another</flow:li> </flow:list> <flow:list paddingRight="24" paddingLeft="24" listStyleType="lowerAlpha"> <flow:li>lowerAlpha item</flow:li> <flow:li>another</flow:li> </flow:list> <flow:list paddingRight="24" paddingLeft="24" listStyleType="upperRoman"> <flow:li>upperRoman item</flow:li> <flow:li>another</flow:li> </flow:list> <flow:list paddingRight="24" paddingLeft="24" listStyleType="lowerRoman"> <flow:listMarkerFormat> <!-- Increments the list by 2s rather than 1s. --> <flow:ListMarkerFormat counterIncrement="ordered 2"/> </flow:listMarkerFormat> <flow:li>lowerRoman item</flow:li> <flow:li>another</flow:li> </flow:list>

Use a classe ListMarkerFormat para definir o contador. Alm de definir o incremento de um contador, tambm possvel personaliz-lo, redefinindo-o com a propriedade counterReset. possvel ainda personalizar a aparncia dos marcadores em sua lista usando as propriedades beforeContent e afterContent do ListMarkerFormat. Estas propriedades se aplicam ao contedo que aparece antes e depois do contedo do marcador. O exemplo a seguir adiciona a seqncia de caracteres XX antes do marcador, e a YY antes:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da Text Layout Framework

422

<flow:list listStyleType="upperRoman" paddingLeft="36" paddingRight="24"> <flow:listMarkerFormat> <flow:ListMarkerFormat fontSize="16" beforeContent="XX" afterContent="YY" counterIncrement="ordered -1"/> </flow:listMarkerFormat> <flow:li>Item 1</flow:li> <flow:li>Item 2</flow:li> <flow:li>Item 3</flow:li> </flow:list>

A propriedade content em si pode definir mais personalizaes do formato do marcador. O exemplo a seguir exibe um marcador ordenado de numeral romano maisculo:
<flow:list listStyleType="disc" paddingLeft="96" paddingRight="24"> <flow:listMarkerFormat> <flow:ListMarkerFormat fontSize="16" beforeContent="Section " content="counters(ordered,&quot;*&quot;,upperRoman)" afterContent=": "/> </flow:listMarkerFormat> <flow:li>Item 1</li> <flow:li>Item 2</li> <flow:li>Item 3</li> </flow:list>

Como mostra o exemplo anterior, a propriedade content tambm pode inserir um sufixo: uma seqncia de caracteres que aparece depois do marcador, mas antes do afterContent. Para inserir esta seqncia de caracteres ao fornecer o contedo XML para o fluxo, envolva a seqncia de caracteres nas entidades HTML &quote; em vez de aspas ("<string>").

Mais tpicos da Ajuda

Markup de listas TLF 2.0

Usando deslocamento no TLF

Cada FlowElement compatvel com propriedades de deslocamento que voc usa para controlar a posio da rea do contedo de cada elemento, e o espao entre as reas do contedo. A largura total de um elemento a soma da largura do seu contedo, mais as propriedades paddingLeft e paddingRight. A altura total de um elemento a soma da altura do seu contedo, mais as propriedades paddingTop e paddingBottom. O deslocamento o espao entre a borda e o contedo. As propriedades de deslocamento so paddingBottom, paddingTop, paddingLeft e paddingRight. possvel aplicar pads ao objeto TestFlow e aos seguintes elementos subordinados (filhos):

div img li lista p

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da Text Layout Framework

423

As propriedades de deslocamento no podem ser aplicadas aos elementos de distncia. O exemplo a seguir define as propriedades de deslocamento no TextFlow:
<flow:TextFlow version="2.0.0" xmlns:flow="http://ns.adobe.com/textLayout/2008" fontSize="14" textIndent="15" paddingTop="4" paddingLeft="4" fontFamily="Times New Roman">

Os valores vlidos para as propriedades de panorama so um nmero ( em pixels), auto, ou herdado. O valor padro "auto", o que significa que calculado automaticamente e definido para 0, para todos os elementos, exceto o ListElement. Para ListElements, auto 0 exceto no lado de incio da lista, onde o valor da propriedade listAutoPadding usado. O valor padro de listAutoPadding 40, o que d lista um recuo padro. As propriedades de deslocamento no so herdadas por padro. Os valores auto e inherit so constantes definidas pela classe FormatValue. As propriedades de deslocamento podem ser valores negativos.

Mais tpicos da Ajuda

Alteraes de deslocamento em TLF 2.0

Formatao de texto com a TLF

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior O pacote flashx.textLayout.formats contm interfaces e classes que permitem atribuir formatos a qualquer FlowElement na rvore da hierarquia de fluxo de texto. H dois modos para aplicao da formatao. Voc pode atribuir um formato especfico individualmente ou atribuir um grupo de formatos simultaneamente com um objeto de formatao especial. A interface ITextLayoutFormat contm todos os formatos que podem ser aplicados a um FlowElement. Alguns formatos se aplicam a um pargrafo ou continer de texto inteiro, mas no se aplicam a caracteres individuais. Por exemplo, formatos como justificao e paradas de tabulao se aplicam a todos os pargrafos, mas no so aplicveis a caracteres individuais.

Atribuio de formatos a um FlowElement com propriedades

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Voc pode definir formatos individuais em FlowElement atravs de atribuio de propriedade. A classe FlowElement implementa a interface ITextLayoutFormat, de modo que qualquer subclasse da classe FlowElement tambm deve implementar essa interface. Por exemplo, o cdigo a seguir mostra como atribuir formatos individuais a uma ocorrncia de ParagraphElement:
var p:ParagraphElement = new ParagraphElement(); p.fontSize = 18; p.fontFamily = "Arial";

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da Text Layout Framework

424

Atribuio de formatos a um FlowElement com a classe TextLayoutFormat

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior possvel aplicar formatos a um FlowElement com a classe TextLayoutFormat. Utilize esta classe para criar um objeto de formatao especial que contm todos os valores e formato que desejar. Isso viabilizar a designao desse objeto propriedade format de qualquer objeto FlowElement. Tanto TextLayoutFormat quanto FlowElement implementam a interface ITextLayoutFormat. Essa organizao garante que as duas classes contenham as mesmas propriedades de formato. Para obter mais informaes, consulte TextLayoutFormat na Referncia do ActionScript 3.0 para a plataforma Adobe Flash.

Herana de formato
Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Formatos so herdados atravs da hierarquia de fluxo de texto. Se voc designar uma instncia de TextLayoutFormat a uma instncia do FlowElement com filhos, a estrutura iniciar um processo denominado cascade. Durante uma cascata, a estrutura examina recursivamente cada n na hierarquia que herda do seu FlowElement. Ento, ela determina se deve atribuir os valores herdados para cada propriedade de formatao. As seguintes regras se aplicam rplica em cascata:
1 Os valores da propriedade so herdados apenas de um ancestral imediato (algumas vezes, denominado o pai). 2 Os valores da propriedade sero herdados apenas se uma propriedade no tiver ainda nenhum valor (ou seja, o

valor estiver undefined).

3 Alguns atributos no herdaro valores indefinidos, a no ser que o valor do atributo esteja definido como "inherit"

ou como a constante flashx.textLayout.formats.FormatValue.INHERIT. Por exemplo, se voc definir o valor fontSize no nvel do TextFlow, a configurao se aplicar a todos os elementos no TextFlow. Em outras palavra, os valores replicam a hierarquia de fluxo de texto em cascata. Ser possvel, no entanto, substituir o valor em determinado elemento designando-lhe diretamente um novo valor. Como contraexemplo, se voc definir o valor backgroundColor para o nvel do TextFlow, os filhos do TextFlow no herdam esse valor. A propriedade backgroundColor aquela que no herda de seu pai durante uma cascata. possvel sobrescrever esse comportamento definido propriedade backgroundColor em cada filho para flashx.textLayout.formats.FormatValue.INHERIT. Para obter mais informaes, consulte TextLayoutFormat na Referncia do ActionScript 3.0 para a plataforma Adobe Flash.

Importao e exportao de texto com a TLF

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior A classe TextConverter no flashx.textLayout.conversion.* o pacote permite importar e exportar texto do TLF. Use essa classe se planeja carregar texto no tempo de execuo em vez de compilar o texto no arquivo SWF. Voc tambm pode usar essa classe para exportar o texto, que fica armazenado em uma ocorrncia de TextFlow em um objeto String ou XML.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da Text Layout Framework

425

Tanto a importao quanto a exportao so procedimentos simples. Voc chama o mtodo export() ou importToFlow(), ambos partes da classe TextConverter. Ambos os mtodos so estticos, o que significa que voc chama os mtodos na classe TextConverter em vez de uma instncia da classe. As classes no pacote flashx.textLayout.conversion oferecem considervel flexibilidade por permitir a opo de armazenar o texto. Por exemplo, se voc armazenar seu texto em um banco de dados, poder importar o texto para a estrutura para fins de exibio. Em seguida, voc pode usar as classes no pacote flashx.textLayout.edit para alterar o texto e exportar o texto alterado de volta para o banco de dados. Para obter mais informaes, consulte flashx.textLayout.conversion na Referncia do ActionScript 3.0 para a plataforma Adobe Flash.

Gerenciamento de contineres de texto com a TLF

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Depois que o texto armazenado nas estruturas de dados da TLF, o Flash Player pode exibi-lo. O texto armazenado na hierarquia de fluxo precisa ser convertido em um formato que o Flash Player possa exibir. O TLF oferece duas maneiras de criar objetos de exibio a partir de um fluxo. A primeira, a abordagem mais simples, adequada para exibio de texto esttico. A segunda, a abordagem mais complicada, permite criar texto dinmico que pode ser selecionado e editado. Em ambos os casos, o texto finalmente convertido em instncias da classe TextLine, que faz parte do pacote flash.text.engine.* no Flash Player 10.

Criao de texto esttico

A abordagem simples utiliza a classe TextFlowTextLineFactory, que pode ser encontrada no pacote flashx.textLayout.factory. A vantagem dessa abordagem, alm da sua simplicidade, que ela tem uma superfcie de memria menor em relao abordagem do FlowComposer. Essa abordagem aconselhvel para o texto esttico que o usurio no precisa editar, selecionar ou rolar. Para obter mais informaes, consulte TextFlowTextLineFactory na Referncia do ActionScript 3.0 para a plataforma Adobe Flash.

Criao de texto dinmico e de contineres

Use um compositor de fluxo se desejar ter mais controle sobre a exibio do texto do que quando fornecido pelo TextFlowTextLineFactory. Por exemplo, com um compositor de fluxo, os usurios podem selecionar e editar o texto. Para obter mais informaes, consulte Ativao da seleo de texto, edio e recurso desfazer com a TLF na pgina 426. Um compositor de fluxo uma ocorrncia da classe StandardFlowComposer no pacote flashx.textLayout.compose. Um compositor de fluxo gerencia a converso do TextFlow em ocorrncias de TextLine, bem como o posicionamento dessas ocorrncias de TextLine em um ou mais contineres.
TextFlow IFlowComposer ContainerController Stage Sprite TextLine
Um IFlowComposer tem zero ou mais ContainerControllers

TextLine

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da Text Layout Framework

426

Cada instncia do TextFlow tem um objeto correspondente que implementa a interface IFlowComposer. Esse objeto IFlowComposer acessvel por meio da propriedade TextFlow.flowComposer. Voc chama mtodos definidos pela interface IFlowComposer usando esta propriedade. Estes mtodos permitem associar o texto a um ou mais contineres e preparar o texto para exibio em um continer. Um continer uma instncia da classe Sprite, a qual, por sua vez, uma subclasse da classe DisplayObjectContainer. Ambas essas classes so parte da API da lista de exibio do Flash Player. Um continer uma forma mais avanada do retngulo delimitador usado na classe TextLineFactory. Como o retngulo delimitador, um continer define a rea em que as instncias do TextLine aparecero. Diferentemente de um retngulo delimitador, um continer te um objeto controlador correspondente. O controlador gerencia a rolagem, composio, vinculao, formatao e tratamento de eventos de um continer ou conjunto de contineres. Cada continer tem um objeto controlador correspondente, que uma ocorrncia da classe ContainerController no pacote flashx.textLayout.container. Para exibir texto, crie um objeto controlador para gerenciar o continer e associ-lo ao compositor de texto. Depois de associar o continer, componha o texto antes que ele possa ser exibido. Da mesma forma, os contineres tm dois estados: composio e exibio. A composio o processo de converso de texto da hierarquia de fluxo de texto nas instncias do TextLine e o clculo de se essas instncias se ajustaro ao continer. A exibio o processo de atualizao da lista de exibio do Flash Player. Para obter mais informaes, consulte IFlowComposer, StandardFlowComposer e ContainerController na Referncia do ActionScript 3.0 para a plataforma Adobe Flash.

Ativao da seleo de texto, edio e recurso desfazer com a TLF

Flash Player 9.0 e posterior, Adobe AIR 1.0 e posterior A capacidade de selecionar ou editar texto controlada no nvel do fluxo de texto. Todas as instncias da classe TextFlow tem um gerenciador de interao associado. Voc pode acessar o gerenciador de interao de um objeto TextFlow atravs da propriedade TextFlow.interactionManager do objeto. Para ativar a seleo de texto, designe uma instncia da classe SelectionManager propriedade interactionManager. Para ativar a seleo e edio de texto, designe uma instncia da classe EditManager em vez de uma instncia da classe SelectionManager. Para ativar as operaes de desfazer, crie uma instncia da classe UndoManager e inclua-a como argumento ao chamar o construtor para EditManager. A classe UndoManager mantm um histrico das atividades de edio mais recentes do usurio e que o usurio desfaa ou refaa edies especficas. As trs classes fazem parte do pacote de edio. Para obter mais informaes, consulte SelectionManager, EditManager e UndoManager na Referncia do ActionScript 3.0 para a plataforma Adobe Flash.

Tratamento de eventos com a TLF

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Objetos TextFlow despacham eventos em muitas circunstncias, que incluem:

Quando o texto ou o layout so alterados Antes do incio e aps o fim de uma operao Quando o status de um objeto FlowElement alterado ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da Text Layout Framework

427

Quando uma operao de composio concluda

Para obter mais informaes, consulte flashx.textLayout.events na Referncia do ActionScript 3.0 para a plataforma Adobe Flash.

Mais tpicos da Ajuda

Eventos TLF FlowElement, LinkElement e EventMirrors

Posicionamento de imagens dentro do texto

Para posicionar InlineGraphicElement dentro do texto, use as seguintes propriedades:

propriedade float da classe InlineGraphicElement propriedade clearFloats da FlowElement

A propriedade float controla o posicionamento do grfico e o texto em torno deste. A propriedade clearFloats controla o posicionamento dos elementos do pargrafo em relao ao float. Para controlar a localizao de uma imagem dentro de um elemento de texto, use a propriedade float. O exemplo a seguir adiciona uma imagem a um pargrafo e a alinha esquerda para que o texto seja disposto em torno da direita:
<flow:p paragraphSpaceAfter="15" >Images in a flow are a good thing. For example, here is a float. It should show on the left: <flow:img float="left" height="50" width="19" source="../assets/bulldog.jpg"></flow:img> Don't you agree? Another sentence here. Another sentence here. Another sentence here. Another sentence here. Another sentence here. Another sentence here. Another sentence here. Another sentence here.</flow:p>

Os valores vlidos para a propriedade float so left, right, start, end e none. A classe Float define estas constantes. O valor padro "none". A propriedade clearFloats til nos casos em que voc deseja ajustar a posio inicial dos pargrafos subseqentes, que normalmente envolve a imagem. Por exemplo, suponha que voc tenha uma imagem que maior do que o primeiro pargrafo. Para ter certeza que o segundo pargrafo inicia depois da imagem, defina a propriedade clearFloats. O exemplo a seguir usa uma imagem mais alta do que o texto no primeiro pargrafo. Para fazer o segundo pargrafo iniciar aps a imagem do bloco de texto, este exemplo define a propriedade clearFloats no segundo pargrafo para "end".
<flow:p paragraphSpaceAfter="15" >Here is another float, it should show up on the right: <flow:img float="right" height="50" elementHeight="200" width="19" source="../assets/bulldog.jpg"></flow:img>We'll add another paragraph that should clear past it.</flow:p><flow:p clearFloats="end" >This should appear after the previous float on the right.</flow:p>

Os valores vlidos para a propriedade clearFloats so left, right, end, start, none e both. A classe ClearFloats define estas constantes. Tambm possvel definir a propriedade clearFloats para inherit, que uma constante definida pela classe FormatValue. O valor padro "none".

Mais tpicos da Ajuda

TLF Floats

ltima atualizao em 29/3/2011

428

Captulo 22: Trabalho com som

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O ActionScript foi desenvolvido para aplicativos interativos de imerso, e um dos elementos muitas vezes negligenciado nesses aplicativos o som. possvel adicionar efeitos de som a um video game, feedback de udio para a interface do usurio de um aplicativo ou mesmo criar um programa que analisa arquivos MP3 carregados pela Internet, com som na base do aplicativo. Voc pode carregar os arquivos de udio externos e trabalhar com o udio que est incorporado em um SWF. Voc poder controlar o udio, criar representaes visuais das informaes de som e capturar som de um microfone do usurio.

Mais tpicos da Ajuda

pacote flash.media flash.events.SampleDataEvent

Noes bsicas do trabalho com som

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os computadores podem capturar e codificar udio digital, que a representao das informaes de som no computador, bem como armazen-lo e recuper-lo para reproduo pelos alto-falantes. possvel reproduzir som usando o Adobe Flash Player ou Adobe AIR e o ActionScript. Quando dados de som so convertidos em formato digital, eles tm vrias caractersticas, como o volume e se o som estreo ou mono. Quando voc reproduz um som no ActionScript, tambm pode ajustar essas caractersticas; por exemplo, voc pode aumentar o som ou fazer parecer que ele est vindo de uma certa direo. Para controlar um som no ActionScript, voc precisa ter as informaes do som carregadas no Flash Player ou no AIR. H cinco maneiras de inserir dados de udio no Flash Player ou AIR para que voc possa trabalhar com eles no ActionScript.

Carregue um arquivo de som externo, como um arquivo mp3 no SWF. Incorpore as informaes de som diretamente no arquivo SWF durante sua criao. Capture udio de um microfone conectado ao computador do usurio. Faa o fluxo de udio a partir de um servidor. Gere e reproduza udio dinamicamente.
Quando voc carrega dados de som a partir de um arquivo de som externo, pode comear a reproduzir o incio do arquivo enquanto o restante dos dados ainda esto sendo carregados. Embora existam vrios formatos de arquivo de som usados para codificar udio digital, o ActionScript 3.0, o Flash Player e o AIR do suporte a arquivos de som armazenados no formato mp3. Eles no podem carregar ou reproduzir arquivos de som diretamente em outros formatos, como WAV ou AIFF.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

429

Enquanto estiver trabalhando com som no ActionScript, provavelmente voc desejar trabalhar com vrias classes do pacote flash.media. A classe Sound a classe que voc usa para obter acesso a informaes de udio carregando um arquivo de som ou atribuindo uma funo a um evento que tira amostras de dados de som e, em seguida, inicia a reproduo. Depois que voc comea a reproduzir um som, o Flash Player e o AIR lhe do acesso a um objeto SoundChannel. Como um arquivo de udio carregado s pode ser um dos vrios sons que voc reproduz no computador de um usurio, cada som especfico reproduzido usa seu prprio objeto SoundChannel; a sada combinada de todos os objetos SoundChannel misturados na verdade consiste no que reproduzido pelos altofalantes do computador. Use esta ocorrncia de SoundChannel para controlar as propriedades do som e interromper a reproduo. Por ltimo, se voc deseja controlar o udio combinado, a classe SoundMixer lhe d controle sobre a sada combinada. Tambm possvel usar vrias outras classes para executar tarefas mais especficas quando voc estiver trabalhando com som no ActionScript; para obter mais informaes sobre todas as classes relacionadas a som, consulte Compreenso da arquitetura do som na pgina 429. Conceitos e termos importantes A lista de referncia a seguir contm termos importantes que voc poder encontrar:
Amplitude A distncia de um ponto na forma de onda de som a partir da linha zero ou de equilbrio. Taxa de bits A quantidade de dados que codificada ou transmitida em fluxo para cada segundo de um arquivo de som. No caso de arquivos mp3, a taxa de bits normalmente informada em milhares de bits por segundo (kbps). Uma taxa de bits mais alta geralmente significa uma onda de som de melhor qualidade. Armazenamento em buffer O recebimento e o armazenamento de dados de som antes de eles serem reproduzidos. mp3 MPEG-1 Audio Layer 3, ou mp3, um formato popular de compactao de som. Panormica O posicionamento de um sinal de udio entre os canais esquerdo e direito em um campo de som estreo. Pico O ponto mais alto em uma forma de onda. Taxa de amostragem Define o nmero de amostras por segundo extradas de um sinal de udio analgico para criar

um sinal digital. A taxa de amostragem de udio de um CD padro de 44,1 kHz ou 44.100 amostras por segundo.
Streaming O processo de reproduzir as partes iniciais de um arquivo de som ou de vdeo enquanto as partes finais

ainda esto sendo carregadas de um servidor.

Volume O volume de um som. Forma de onda A forma de um grfico das variadas amplitudes de um sinal de som ao longo do tempo.

Compreenso da arquitetura do som

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Seus aplicativos podem carregar dados de som de cinco origens principais:

Arquivos de som externos carregados em tempo de execuo Recursos de som incorporados no arquivo SWF do aplicativo Dados de som de um microfone conectado ao sistema do usurio Dados de som transmitidos de um servidor de mdia remoto, como o Flash Media Server Dados de som gerados dinamicamente por meio do uso do manipulador de eventos sampleData

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

430

Dados de som podem ser carregados completamente antes de o som ser reproduzido ou podem ser transmitidos em fluxo, o que significa que o som reproduzido enquanto ainda est sendo carregado. As classes de som do ActionScript 3.0 do suporte a arquivos de som armazenados no formato mp3. Elas no podem carregar ou reproduzir arquivos de som diretamente em outros formatos, como WAV ou AIFF. No entanto, a partir do Flash Player 9.0.115.0, possvel carregar e reproduzir arquivos de udio AAC usando a classe NetStream. Esta tcnica a mesma utilizada para carregar e reproduzir contedo de vdeo. Para obter mais informaes sobre ela, consulte Trabalho com vdeo na pgina 462. Com o Adobe Flash Professional, possvel importar arquivos de som WAV ou AIFF e incorpor-los aos arquivos SWF do aplicativo no formato mp3. A ferramenta de autoria do Flash tambm permite compactar arquivos de som incorporados para reduzir o tamanho do arquivo, embora essa reduo de tamanho represente perda da qualidade do som. Para obter mais informaes, consulte Importao de sons em Uso do Flash. A arquitetura de som do ActionScript 3.0 usa as seguintes classes no pacote flash.media.
Classe flash.media.Sound Descrio A classe Sound manipula o carregamento do som, gerencia propriedades bsicas de som e inicia uma reproduo de som. Quando um aplicativo reproduz um objeto Sound, um novo objeto SoundChannel criado para controlar a reproduo. O objeto SoundChannel controla o volume dos canais de reproduo direito e esquerdo do som. Cada som reproduzido tem seu prprio objeto SoundChannel. A classe SoundLoaderContext especifica o nmero de segundos de buffer a ser usado ao carregar um som e se o Flash Player ou o AIR deve procurar um arquivo de poltica no servidor quando carregar um arquivo. Um objeto SoundLoaderContext usado como um parmetro para o mtodo Sound.load(). A classe SoundMixer controla as propriedades de reproduo e de segurana relativas a todos os sons em um aplicativo. Em vigor, vrios canais de som so misturados por meio de um objeto SoundMixer comum, portanto valores de propriedades no objeto SoundMixer afetaro todos os objetos SoundChannel em execuo no momento. A classe SoundTransform contm valores que controlam o volume e o panorama do som. Um objeto SoundTransform pode ser aplicado a um objeto SoundChannel individual, ao objeto SoundMixer global ou a um objeto Microphone, entre outros. Um objeto ID3Info contm propriedades que representam informaes de metadados ID3 que normalmente so armazenados em arquivos de som mp3. A classe Microphone representa um microfone ou outro dispositivo de entrada de som conectado ao computador do usurio. A entrada de udio de um microfone pode ser roteada para alto-falantes locais ou enviada a um servidor remoto. O objeto Microphone controla o ganho, a taxa de amostragem e outras caractersticas de seu prprio fluxo de som.

flash.media.SoundChannel

flash.media.SoundLoaderContext

flash.media.SoundMixer

flash.media.SoundTransform

flash.media.ID3Info

flash.media.Microphone

Cada som carregado e reproduzido precisa de sua prpria ocorrncia das classes Sound e SoundChannel. A sada das vrias ocorrncias de SoundChannel ento misturada pela classe global SoundMixer durante a reproduo. As classes Sound, SoundChannel e SoundMixer no so usadas para dados de som obtidos de um microfone ou de um servidor de fluxo de mdia, como o Flash Media Server.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

431

Carregamento de arquivos de som externos

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Cada ocorrncia da classe Sound existe para carregar e disparar a reproduo de um recurso de som especfico. Um aplicativo no pode reutilizar um objeto Sound para carregar mais de um som. Para carregar um novo recurso de som, ele deve criar um novo objeto Sound. Se estiver carregando um arquivo de som pequeno, como um som de clique a ser conectado a um boto, o aplicativo poder criar um novo Sound e fazer com que ele carregue automaticamente o arquivo de som, conforme mostrado a seguir:
var req:URLRequest = new URLRequest("click.mp3"); var s:Sound = new Sound(req);

O construtor Sound() aceita um objeto URLRequest como seu primeiro parmetro. Quando um valor fornecido ao parmetro URLRequest, o novo objeto Sound comea a carregar o recurso de som especificado automaticamente. Em todos, menos nos casos mais simples, o aplicativo deve verificar se ocorrem erros durante o carregamento do som. Por exemplo, se o som de clique for razoavelmente grande, ele talvez no esteja completamente carregado quando o usurio clicar no boto que dispara o som. A tentativa de reproduzir um som no carregado pode provocar um erro em tempo de execuo. mais seguro aguardar que o carregamento do som seja concludo antes de permitir que os usurios executem aes que podem iniciar a reproduo de sons. Um objeto Sound despacha vrios eventos diferentes durante o processo de carregamento do som. O aplicativo pode ouvir esses eventos para controlar o progresso de carregamento e verificar se o som foi completamente carregado antes da reproduo. A tabela a seguir lista os eventos que podem ser despachados por um objeto Sound.
Evento abertura (Event.OPEN) progresso (ProgressEvent.PROGRESS) id3 (Event.ID3) concludo (Event.COMPLETE) ioError (IOErrorEvent.IO_ERROR) Descrio Despachado imediatamente antes do incio da operao de carregamento do som. Despachado periodicamente durante o processo de carregamento do som quando os dados so recebidos do arquivo ou do fluxo. Despachado quando dados ID3 esto disponveis para um som mp3. Despachado quando todos os dados do recurso de som foram carregados. Despachado quando um arquivo de som no pode ser localizado ou quando o processo de carregamento interrompido antes dos dados serem recebidos.

O cdigo a seguir ilustra como reproduzir um som aps a concluso do carregamento:

import flash.events.Event; import flash.media.Sound; import flash.net.URLRequest; var s:Sound = new Sound(); s.addEventListener(Event.COMPLETE, onSoundLoaded); var req:URLRequest = new URLRequest("bigSound.mp3"); s.load(req); function onSoundLoaded(event:Event):void { var localSound:Sound = event.target as Sound; localSound.play(); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

432

Primeiro, o cdigo de amostra cria um novo objeto Sound sem dar a ele um valor inicial para o parmetro URLRequest. Em seguida, ele ouve o evento Event.COMPLETE do objeto Sound, o que faz com que o mtodo onSoundLoaded() seja executado quando todos os dados do som esto carregados. Em seguida, ele chama o mtodo Sound.load() com um novo valor de URLRequest para o arquivo de som. O mtodo onSoundLoaded() executado quando o carregamento do som concludo. A propriedade target do objeto Event uma referncia ao objeto Sound. A chamada do mtodo play() do objeto Sound inicia a reproduo do som.

Monitoramento do processo de carregamento do som

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Arquivos de som podem ser muito grandes e levar muito tempo para serem carregados. Embora o Flash Player e o AIR permitam que o aplicativo reproduza sons mesmo antes de eles serem completamente carregados, talvez voc queira dar ao usurio uma indicao da quantidade de dados de som carregada e da quantidade de som que j foi reproduzida. A classe Sound despacha dois eventos que facilitam relativamente a exibio do progresso de carregamento de um som: ProgressEvent.PROGRESS e Event.COMPLETE. O exemplo a seguir mostra como usar esses eventos para exibir informaes de progresso sobre o som que est sendo carregado:
import import import import flash.events.Event; flash.events.ProgressEvent; flash.media.Sound; flash.net.URLRequest;

var s:Sound = new Sound(); s.addEventListener(ProgressEvent.PROGRESS, onLoadProgress); s.addEventListener(Event.COMPLETE, onLoadComplete); s.addEventListener(IOErrorEvent.IO_ERROR, onIOError); var req:URLRequest = new URLRequest("bigSound.mp3"); s.load(req); function onLoadProgress(event:ProgressEvent):void { var loadedPct:uint = Math.round(100 * (event.bytesLoaded / event.bytesTotal)); trace("The sound is " + loadedPct + "% loaded."); } function onLoadComplete(event:Event):void { var localSound:Sound = event.target as Sound; localSound.play(); } function onIOError(event:IOErrorEvent) { trace("The sound could not be loaded: " + event.text); }

Esse cdigo primeiro cria um objeto Sound e, em seguida, adiciona ouvintes para esse objeto para os eventos ProgressEvent.PROGRESS e Event.COMPLETE. Aps o mtodo Sound.load() ter sido chamado e os primeiros dados terem sido recebidos do arquivo de som, ocorre um evento ProgressEvent.PROGRESS que dispara o mtodo onSoundLoadProgress().

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

433

A porcentagem dos dados de som que foi carregada igual ao valor da propriedade bytesLoaded do objeto gressEvent dividido pelo valor da propriedade bytesTotal. As mesmas propriedades bytesLoaded e bytesTotal esto disponveis no objeto Sound tambm. O exemplo acima simplesmente mostra mensagens sobre o progresso do carregamento do som, mas possvel usar facilmente os valores de bytesLoaded e bytesTotal para atualizar os componentes da barra de progresso, como os provenientes da estrutura do Adobe Flex ou da ferramenta de autoria do Adobe Flash. Esse exemplo tambm mostra como um aplicativo pode reconhecer e responder a um erro ao carregar arquivos de som. Por exemplo, se um arquivo de som com o nome fornecido no puder ser localizado, um evento Event.IO_ERROR ser despachado pelo objeto Sound. No cdigo anterior, o mtodo onIOError() executa e exibe uma breve mensagem de erro quando ocorre um erro.

Trabalho com sons incorporados

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O uso de sons incorporados, em vez do carregamento de som de um arquivo externo, mais til para pequenos sons que so usados como indicadores dentro da interface do usurio do aplicativo, como sons que so reproduzidos quando botes so clicados. Quando um arquivo de som incorporado no aplicativo, o tamanho do arquivo SWF resultante aumenta pelo tamanho do arquivo de som. Em outras palavras, a incorporao de arquivos de som grandes no aplicativo pode aumentar o tamanho do arquivo SWF para um tamanho indesejado. O mtodo exato a ser usado para incorporar um arquivo de som no arquivo SWF do aplicativo varia de acordo com o ambiente de desenvolvimento.

Uso de um arquivo de som incorporado no Flash

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A ferramenta de autoria do Flash permite importar sons de vrios formatos e armazen-los como smbolos na Biblioteca. Em seguida, possvel atribu-los a quadros na linha do tempo ou a quadros de um estado de boto, uslos com Comportamentos ou us-los diretamente no cdigo do ActionScript. Esta seo descreve como usar sons incorporados no cdigo ActionScript com a ferramenta de autoria do Flash. Para obter informaes sobre as outras maneiras de usar sons incorporados no Flash, consulte Importao de sons em Uso do Flash. Para incorporar um arquivo de som usando a Ferramenta de autoria do Flash: 1 Selecione Arquivo > Importar > Importar para biblioteca e, em seguida, selecione e importe um arquivo de som.
2 Clique com o boto direito do mouse no nome do arquivo importado no painel Biblioteca e selecione Propriedades.

Clique na caixa de seleo Exportar para ActionScript.

3 No campo Classe, digite um nome a ser usado ao fazer referncia a esse som incorporado no ActionScript. Por

padro, ele usar o nome do arquivo de som nesse campo. Se o nome do arquivo incluir um ponto, como no nome DrumSound.mp3, voc dever alter-lo para algo como DrumSound. O ActionScript no permite um caractere ponto em um nome de classe. O campo Classe base ainda deve mostrar flash.media.Sound.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

434

4 Clique em OK. Talvez voc veja uma caixa de dilogo informando que uma definio dessa classe no pde ser

localizada no caminho de classe. Clique em OK e continue. Se voc inseriu um nome de classe que no corresponde ao nome de qualquer uma das classes no caminho de classe do aplicativo, uma nova classe que herda da classe flash.media.Sound ser gerada automaticamente para voc.
5 Para usar o som incorporado, voc faz referncia ao nome da classe para aquele som no ActionScript. Por exemplo,

o cdigo a seguir comea criando uma nova ocorrncia da classe DrumSound gerada automaticamente:
var drum:DrumSound = new DrumSound(); var channel:SoundChannel = drum.play();

DrumSound uma subclasse da classe flash.media.Sound portanto ela herda os mtodos e as propriedades da classe Sound, incluindo o mtodo play() conforme mostrado acima.

Uso de um arquivo de som incorporado no Flex

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Existem vrias maneiras de incorporar recursos de som em um aplicativo Flex, incluindo:

Usar a tag de metadados [Embed] em um script. Usar a diretiva @Embed no MXML para atribuir um recurso incorporado como uma propriedade de um
componente, como Button ou SoundEffect.

Usar a diretiva @Embed dentro de um arquivo CSS.

Esta seo descreve a primeira opo: como incorporar sons no cdigo ActionScript dentro de um aplicativo Flex usando a tag de metadados [Embed]. Para incorporar um ativo no cdigo ActionScript, use a tag de metadados [Embed]. Coloque o arquivo de som na pasta de origem principal ou em outra pasta que esteja no caminho de criao do projeto. Quando o compilador do encontra uma tag de metadados Embed, ele cria a classe de ativos incorporada para voc. possvel acessar a classe por meio de uma varivel de tipo de dados Class que pode ser declarada imediatamente aps a tag de metadados [Embed]. O cdigo a seguir incorpora um som denominado smallSound.mp3 e usa uma varivel denominada soundClass para armazenar uma referncia classe de ativos incorporada associada quele som. Em seguida, o cdigo cria uma ocorrncia da classe de ativos incorporada, projeta-a como uma ocorrncia da classe Sound e chama o mtodo play() naquela ocorrncia:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

435

package { import flash.display.Sprite; import flash.media.Sound; import flash.media.SoundChannel; public class EmbeddedSoundExample extends Sprite { [Embed(source="smallSound.mp3")] public var soundClass:Class; public function EmbeddedSoundExample() { var smallSound:Sound = new soundClass() as Sound; smallSound.play(); } } }

Para usar o som incorporado para definir uma propriedade de um componente Flex, ele deve ser projetado como uma ocorrncia da classe mx.core.SoundAsset em vez de uma ocorrncia da classe Sound. Para obter um exemplo semelhante que usa a classe SoundAsset, consulte "Classes de ativos incorporadas" em Aprendendo o ActionScript 3.0.

Trabalho com arquivos de fluxo de som

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A reproduo de um arquivo de som ou de vdeo enquanto seus dados ainda esto sendo carregados conhecida como streaming. Arquivos de som externos que so carregados de um servidor remoto normalmente so transmitidos em fluxo para que o usurio no precise aguardar at que todos os dados do som sejam carregados para ouvir o som. A propriedade SoundMixer.bufferTime representa o nmero de milissegundos de dados de som que o Flash Player ou o AIR deve coletar antes de permitir a reproduo do som. Em outras palavras, se a propriedade bufferTime estiver definida como 5000, o Flash Player ou o AIR carregaro pelo menos 5000 milissegundos de dados do arquivo de som antes de iniciar a reproduo do som. O valor padro SoundMixer.bufferTime 1000. O aplicativo pode substituir o valor global SoundMixer.bufferTime de um som individual especificando explicitamente um novo valor de bufferTime ao carregar o som. Para substituir o tempo de buffer padro, primeiro crie uma nova ocorrncia da classe SoundLoaderContext, defina sua propriedade bufferTime e, em seguida, passe-a como um parmetro para o mtodo Sound.load(), conforme mostrado a seguir:
import flash.media.Sound; import flash.media.SoundLoaderContext; import flash.net.URLRequest; var s:Sound = new Sound(); var req:URLRequest = new URLRequest("bigSound.mp3"); var context:SoundLoaderContext = new SoundLoaderContext(8000, true); s.load(req, context); s.play();

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

436

Conforme a reproduo continua, o Flash Player e o AIR tentam manter o buffer de som do mesmo tamanho ou maior. Se os dados do som forem carregados mais rapidamente do que a velocidade de reproduo, a reproduo continuar sem interrupo. No entanto, se a taxa de carregamento de dados for reduzida devido a limitaes da rede, o indicador de reproduo poder atingir o final do buffer de som. Nesse caso, a reproduo ser suspensa, embora ela seja reiniciada automaticamente quando mais dados de som forem carregados. Para descobrir se a reproduo est suspensa porque o Flash Player ou o AIR esto aguardando o carregamento dos dados, use a propriedade Sound.isBuffering.

Trabalho com udio gerado dinamicamente

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Nota: A capacidade de gerar udio dinamicamente est disponvel a partir do Flash Player 10 e do Adobe AIR 1.5. Em vez de carregar ou transmitir em fluxo um som existente, possvel gerar dados de udio dinamicamente. Voc pode gerar dados de udio quando estiver atribuindo um ouvinte de eventos ao evento sampleData de um objeto Sound. (O evento sampleData definido na classe SampleDataEvent do pacote flash.events.) Neste ambiente, o objeto Sound no carrega dados de som de um arquivo. Em vez disso, ele funciona como um soquete para dados de som que esto sendo transmitidos em fluxo atravs do uso da funo que voc atribui a esse evento. Quando voc adiciona um ouvinte de eventos sampleData a um objeto Sound, o objeto periodicamente solicita dados para adicion-los ao buffer de som. Esse buffer contm dados para o objeto Sound reproduzir. Quando voc chama o mtodo play() do objeto Sound, ele despacha o evento sampleData ao solicitar novos dados de som. (Isto s se aplica quando o objeto Sound no carregou dados mp3 de um arquivo.) O objeto SampleDataEvent inclui uma propriedade data. No ouvinte de eventos, voc grava objetos ByteArray neste objeto data. As matrizes de bytes gravadas neste objeto somam-se aos dados de som em buffer reproduzidos pelo objeto Sound. A matriz de bytes no buffer um fluxo de valores de ponto flutuante que variam de -1 a 1. Cada valor de ponto flutuante representa a amplitude de um canal (esquerdo ou direito) de uma amostra de som. A amostragem do som ocorre a 44.100 amostras por segundo. Cada amostra contm um canal esquerdo e direito, intercalados como dados de ponto flutuante na matriz de bytes. Na funo do manipulador, use o mtodo ByteArray.writeFloat() para gravar na propriedade data do evento
sampleData. Por exemplo, o seguinte cdigo gera uma onda senoidal: var mySound:Sound = new Sound(); mySound.addEventListener(SampleDataEvent.SAMPLE_DATA, sineWaveGenerator); mySound.play(); function sineWaveGenerator(event:SampleDataEvent):void { for (var i:int = 0; i < 8192; i++) { var n:Number = Math.sin((i + event.position) / Math.PI / 4); event.data.writeFloat(n); event.data.writeFloat(n); } }

Quando voc chama Sound.play(), o aplicativo comea a chamar seu manipulador de eventos, solicitando dados de amostra de som. O aplicativo continua enviando eventos medida que o som reproduzido, at voc parar de fornecer dados ou chamar SoundChannel.stop().

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

437

A latncia do evento varia de uma plataforma para outra e pode mudar em verses futuras do Flash Player e do AIR. No dependa de uma latncia especfica; em vez disso, voc deve calcul-la. Para fazer esse clculo, use a seguinte frmula:
(SampleDataEvent.position / 44.1) - SoundChannelObject.position

Fornea de 2048 a 8192 amostras para a propriedade data do objeto SampleDataEvent (para cada chamada ao ouvinte de eventos). Para obter o melhor desempenho, fornea o mximo possvel de amostras (at 8192). Quanto menos amostras forem fornecidas, maior ser a probabilidade de ocorrerem cliques e estalos durante a reproduo. Esse comportamento pode diferir em vrias plataformas e pode ocorrer em diversas situaes; por exemplo, no redimensionamento do navegador. O cdigo que funciona em uma plataforma quando voc fornece apenas 2048 amostras pode no funcionar to bem quando executado em outra plataforma. Se precisar da menor latncia possvel, pense na possibilidade de tornar o volume de dados selecionvel pelo usurio. Se voc fornecer menos de 2048 amostras (por chamada ao ouvinte de eventos sampleData), o aplicativo ser interrompido depois de reproduzir as amostras restantes. Em seguida, o objeto SoundChannel despacha um evento SoundComplete.

Modificao do som de dados mp3

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Use o mtodo Sound.extract() para extrair dados de um objeto Sound. Voc pode usar (e modificar) esses dados para grav-los no fluxo dinmico de outro objeto Sound para fins de reproduo. Por exemplo, o cdigo a seguir usa os bytes de um arquivo MP3 carregado e os passa usando uma funo de filtro, upOctave():

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

438

var mySound:Sound = new Sound(); var sourceSnd:Sound = new Sound(); var urlReq:URLRequest = new URLRequest("test.mp3"); sourceSnd.load(urlReq); sourceSnd.addEventListener(Event.COMPLETE, loaded); function loaded(event:Event):void { mySound.addEventListener(SampleDataEvent.SAMPLE_DATA, processSound); mySound.play(); } function processSound(event:SampleDataEvent):void { var bytes:ByteArray = new ByteArray(); sourceSnd.extract(bytes, 8192); event.data.writeBytes(upOctave(bytes)); } function upOctave(bytes:ByteArray):ByteArray { var returnBytes:ByteArray = new ByteArray(); bytes.position = 0; while(bytes.bytesAvailable > 0) { returnBytes.writeFloat(bytes.readFloat()); returnBytes.writeFloat(bytes.readFloat()); if (bytes.bytesAvailable > 0) { bytes.position += 8; } } return returnBytes; }

Limitaes quanto aos sons gerados

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior Quando voc usa um ouvinte de eventos sampleData com um objeto Sound, os outros nicos mtodos Sound ativados so Sound.extract() e Sound.play(). Chamar qualquer outro mtodo ou propriedade resultar em uma exceo. Todos os mtodos e propriedades do objeto SoundChannel continuam ativados.

Reproduo de sons
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A reproduo de um som carregado pode ser to simples quanto chamar o mtodo Sound.play() para um objeto Sound, da seguinte maneira:
var snd:Sound = new Sound(new URLRequest("smallSound.mp3")); snd.play();

Ao reproduzir sons usando o ActionScript 3.0, possvel executar as seguintes operaes:

Reproduzir um som a partir de uma posio inicial especfica.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

439

Pausar um som e reiniciar a reproduo a partir da mesma posio mais tarde. Saber exatamente quando a reproduo de um som concluda. Rastrear o progresso da reproduo de um som. Alterar o volume ou a panormica enquanto o som reproduzido.
Para executar essas operaes durante a reproduo, use as classes SoundChannel, SoundMixer e SoundTransform. A classe SoundChannel controle a reproduo de um nico som. A propriedade SoundChannel.position pode ser considerada como um indicador de reproduo, indicando o ponto atual nos dados do som que est sendo reproduzido. Quando um aplicativo chama o mtodo Sound.play(), uma nova ocorrncia da classe SoundChannel criada para controlar a reproduo. O aplicativo pode reproduzir um som a partir de uma posio inicial especfica passando aquela posio, em termos de milissegundos, como o parmetro startTime do mtodo Sound.play(). Ele tambm pode especificar o nmero de vezes para repetio do som em sucesso rpida passando um valor numrico no parmetro loops do mtodo Sound.play(). Quando o mtodo Sound.play() chamado com um parmetro startTime e um parmetro loops, o som reproduzido repetidamente a partir do mesmo ponto inicial, conforme mostrado no cdigo a seguir:
var snd:Sound = new Sound(new URLRequest("repeatingSound.mp3")); snd.play(1000, 3);

Neste exemplo, o som reproduzido a partir de um ponto um segundo aps o incio do som, trs vezes em sucesso.

Pausa e reincio de um som

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Se o aplicativo reproduzir sons longos, como canes ou podcasts, talvez voc queira permitir que os usurios pausem e reiniciem a reproduo desses sons. Um som no pode ser pausado literalmente durante a reproduo no ActionScript. Ele pode apenas ser interrompido. No entanto um som pode ser reproduzido a partir de um ponto qualquer. possvel registrar a posio do som na hora em que foi interrompido e, em seguida, reproduzir o som mais tarde a partir daquela posio. Por exemplo, suponha que o cdigo carrega e reproduz um arquivo de som como este:
var snd:Sound = new Sound(new URLRequest("bigSound.mp3")); var channel:SoundChannel = snd.play();

Enquanto o som reproduzido, a propriedade SoundChannel.position indica o ponto no arquivo de som que est em reproduo no momento. O aplicativo pode armazenar o valor da posio antes de interromper a reproduo do som, da seguinte maneira:
var pausePosition:int = channel.position; channel.stop();

Para reiniciar a reproduo do som, passe o valor da posio armazenado anteriormente para reiniciar o som a partir do mesmo ponto em que foi interrompido anteriormente.
channel = snd.play(pausePosition);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

440

Monitoramento da reproduo
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O aplicativo talvez queira saber quando a reproduo de um som interrompida para que possa iniciar a reproduo de outro som ou limpar alguns recursos usados durante a reproduo anterior. A classe SoundChannel despacha um evento Event.SOUND_COMPLETE quando a reproduo do som concluda. O aplicativo pode ouvir esse evento e tomar a ao apropriada, conforme mostrado a seguir:
import flash.events.Event; import flash.media.Sound; import flash.net.URLRequest; var snd:Sound = new Sound(); var req:URLRequest = new URLRequest("smallSound.mp3"); snd.load(req); var channel:SoundChannel = snd.play(); channel.addEventListener(Event.SOUND_COMPLETE, onPlaybackComplete); public function onPlaybackComplete(event:Event) { trace("The sound has finished playing."); }

A classe SoundChannel no despacha eventos de progresso durante a reproduo. Para relatar o progresso da reproduo, o aplicativo pode configurar seu prprio mecanismo de controle de tempo e rastrear a posio do indicador de reproduo do som. Para calcular qual porcentagem de um som foi reproduzida, possvel dividir o valor da propriedade SoundChannel.position pelo comprimento dos dados do som que est sendo reproduzido:
var playbackPercent:uint = 100 * (channel.position / snd.length);

No entanto esse cdigo relatar porcentagens exatas da reproduo apenas se os dados do som foram carregados completamente antes do incio da reproduo. A propriedade Sound.length mostra o tamanho dos dados do som que esto sendo carregados no momento, no o tamanho eventual do arquivo de som inteiro. Para rastrear o progresso da reproduo de um fluxo de som que ainda est sendo carregado, o aplicativo deve estimar o tamanho eventual do arquivo de som inteiro e usar esse valor em seus clculos. possvel estimar o comprimento eventual dos dados do som usando as propriedades bytesLoaded e bytesTotal do objeto Sound, da seguinte maneira:
var estimatedLength:int = Math.ceil(snd.length / (snd.bytesLoaded / snd.bytesTotal)); var playbackPercent:uint = 100 * (channel.position / estimatedLength);

O cdigo a seguir carrega um arquivo de som maior e usa o evento Event.ENTER_FRAME como seu mecanismo de controle de tempo para mostrar o progresso da reproduo. Ele relata periodicamente a porcentagem de reproduo que calculada como o valor da posio inicial dividido pelo comprimento total dos dados do som:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

441

import flash.events.Event; import flash.media.Sound; import flash.net.URLRequest; var snd:Sound = new Sound(); var req:URLRequest = new URLRequest("http://av.adobe.com/podcast/csbu_dev_podcast_epi_2.mp3"); snd.load(req); var channel:SoundChannel; channel = snd.play(); addEventListener(Event.ENTER_FRAME, onEnterFrame); channel.addEventListener(Event.SOUND_COMPLETE, onPlaybackComplete); function onEnterFrame(event:Event):void { var estimatedLength:int = Math.ceil(snd.length / (snd.bytesLoaded / snd.bytesTotal)); var playbackPercent:uint = Math.round(100 * (channel.position / estimatedLength)); trace("Sound playback is " + playbackPercent + "% complete."); } function onPlaybackComplete(event:Event) { trace("The sound has finished playing."); removeEventListener(Event.ENTER_FRAME, onEnterFrame); }

Aps o incio do carregamento dos dados do som, esse cdigo chama o mtodo snd.play() e armazena o objeto SoundChannel resultante na varivel channel. Em seguida, ele adiciona um ouvinte de eventos ao aplicativo principal para o evento Event.ENTER_FRAME e outro ouvinte de eventos ao objeto SoundChannel para o evento Event.SOUND_COMPLETE que ocorre quando a reproduo concluda. A cada vez que o aplicativo atinge um novo quadro em sua animao, o mtodo onEnterFrame() chamado. O mtodo onEnterFrame() estima o comprimento total do arquivo de som com base na quantidade de dados que j foi carregada e, em seguida, calcula e exibe a porcentagem de reproduo atual. Quando todo o som foi reproduzido, o mtodo onPlaybackComplete() executado, removendo o ouvinte do evento
Event.ENTER_FRAME de forma que ele no tente exibir atualizaes do progresso aps a concluso da reproduo.

O evento Event.ENTER_FRAME pode ser despachado muitas vezes por segundo. Em alguns casos, no conveniente exibir o progresso da reproduo com tanta freqncia. Nesses casos, o aplicativo pode configurar seu prprio mecanismo de controle do tempo usando a classe flash.util.Timer. Consulte Trabalho com datas e horas na pgina 1.

Interrupo de fluxos de som

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior H uma peculiaridade no processo de reproduo de sons que esto sendo transmitidos em fluxo, isto , sons que ainda esto sendo carregados enquanto esto sendo reproduzidos. Quando o aplicativo chama o mtodo SoundChannel.stop() em uma ocorrncia de SoundChannel que est reproduzindo um fluxo de som, a reproduo do som pra em um quadro e, em seguida, no prximo quadro, ela reinicia a partir do incio do som. Isso ocorre porque o processo de carregamento do som ainda est em execuo. Para interromper o carregamento e a reproduo de um fluxo de som, chame a o mtodo Sound.close().

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

442

Consideraes sobre segurana ao carregar e reproduzir sons

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A capacidade do aplicativo de acessar dados de som podem ser limitadas de acordo com o modelo de segurana do Flash Player ou do AIR. Cada som est sujeito a restries de duas caixas de proteo de segurana, a caixa de proteo do prprio contedo (a caixa de proteo do contedo) e a caixa de proteo do aplicativo ou do objeto que carrega e reproduz o som (a caixa de proteo do proprietrio). Para contedo de aplicativo AIR na caixa de proteo do aplicativo, todos os sons, inclusive aqueles carregados de outros domnios, so acessveis ao contedo na caixa de proteo de segurana do aplicativo. No entanto contedo em outras caixas de proteo de segurana observam as mesmas regras que o contedo em execuo no Flash Player. Para obter mais informaes sobre o modelo de segurana do Flash Player em geral e sobre a definio de caixas de proteo, consulte Segurana na pgina 1027. A caixa de proteo do contedo controla se dados de som detalhados podem ser extrados do som usando a propriedade id3 ou o mtodo SoundMixer.computeSpectrum(). Ele no restringe o carregamento ou a reproduo do prprio arquivo de som. O domnio de origem do arquivo de som define as limitaes de segurana da caixa de proteo do contedo. Geralmente, se um arquivo de som est localizado no mesmo domnio ou pasta que o arquivo SWF do aplicativo ou do objeto que o carrega, o aplicativo ou o objeto ter acesso total quele arquivo de som. Se o som for proveniente de um domnio diferente do domnio do aplicativo, ele ainda poder ser trazido para a caixa de proteo do contedo usando um arquivo de poltica. O aplicativo pode passar um objeto SoundLoaderContext com uma propriedade checkPolicyFile como parmetro para o mtodo Sound.load(). A configurao da propriedade checkPolicyFile como true instrui o Flash Player ou o AIR a procurar um arquivo de poltica no servidor onde o som carregado. Se existir um arquivo de poltica e ele conceder acesso ao domnio do arquivo SWF que est sendo carregado, o arquivo SWF poder carregar o arquivo de som, acessar a propriedade id3 do objeto Sound e chamar o mtodo SoundMixer.computeSpectrum() de sons carregados. A caixa de proteo do proprietrio controla a reproduo local dos sons. O aplicativo ou o objeto que inicia a reproduo de um som define a caixa de proteo do proprietrio. O mtodo SoundMixer.stopAll() silencia os sons em todos os objetos SoundChannel que esto sendo reproduzidos no momento, desde que atendam aos seguintes critrios:

Os sons foram iniciados por objetos dentro da mesma caixa de proteo do proprietrio. Os sons so provenientes de uma origem com um arquivo de poltica que concede acesso ao domnio do aplicativo
ou objeto que chama o mtodo SoundMixer.stopAll(). Contudo, em um aplicativo AIR, o contedo na caixa de proteo de segurana do aplicativo (contedo instalado com o aplicativo AIR) no restringido por essas limitaes de segurana. Para descobrir se o mtodo SoundMixer.stopAll() realmente interromper todas os sons em reproduo, o aplicativo pode chamar o mtodo SoundMixer.areSoundsInaccessible(). Se esse mtodo retornar um valor de true, alguns dos sons que esto sendo reproduzidos estaro fora do controle da caixa de proteo do proprietrio atual e no sero interrompidos pelo mtodo SoundMixer.stopAll(). O mtodo SoundMixer.stopAll() tambm interrompe a continuao do indicador da reproduo para todos os sons que foram carregados de arquivos externos. No entanto sons que foram incorporados em arquivos FLA e anexados a quadros na linha do tempo usando a ferramenta de autoria do Flash talvez iniciem a reproduo novamente se a animao mover para um novo quadro.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

443

Controle do volume e do panorama do som

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Um objeto SoundChannel individual controla os canais estreos esquerdo e direito para um som. Se um som mp3 for um som monofnico, os canais estreos esquerdo e direito do objeto SoundChannel contero formas de onda idnticas. possvel descobrir a amplitude de cada canal estreo do som que est sendo reproduzido usando as propriedades leftPeak e rightPeak do objeto SoundChannel. Essas propriedades mostram a amplitude de pico da prpria forma de onda do som. Elas no representam o volume de reproduo real. O volume de reproduo real uma funo da amplitude da onda do som e dos valores de volume definidos no objeto SoundChannel e na classe SoundMixer. A propriedade pan de um objeto SoundChannel pode ser usada para especificar um nvel diferente de volume para cada um dos canais esquerdo e direito durante a reproduo. A propriedade pan pode ter um valor variando de -1 a 1, em que -1 significa que o canal esquerdo reproduz no volume mximo enquanto o canal direito est silencioso e 1 significa que o canal direito reproduz no volume mximo enquanto o canal esquerdo est silencioso. Valores numricos entre -1 e 1 definem valores proporcionais para os valores dos canais esquerdo e direito e um valor igual a 0 significa que os dois canais so reproduzidos em um nvel equilibrado de nvel de volume mdio. O cdigo de exemplo a seguir cria um objeto SoundTransform com um valor de volume de 0,6 e um valor de pan de -1 (volume mximo no canal esquerdo e nenhum volume no canal direito). Ele passa o objeto SoundTransform como um parmetro para o mtodo play() que aplica esse objeto SoundTransform ao novo objeto SoundChannel que criado para controlar a reproduo.
var snd:Sound = new Sound(new URLRequest("bigSound.mp3")); var trans:SoundTransform = new SoundTransform(0.6, -1); var channel:SoundChannel = snd.play(0, 1, trans);

possvel alterar o volume e a panormica enquanto um som est sendo reproduzido definindo as propriedades pan ou volume de um objeto SoundTransform e aplicando esse objeto como a propriedade soundTransform de um objeto SoundChannel. Tambm possvel definir os valores globais de volume e de pan para todos os sons de uma vez usando a propriedade
soundTransform da classe SoundMixer, conforme mostrado no exemplo a seguir: SoundMixer.soundTransform = new SoundTransform(1, -1);

Tambm possvel usar um objeto SoundTransform para definir os valores de volume e panormica para um objeto Microphone (consulte Captura de entrada do som na pgina 449) e para objetos Sprite e SimpleButton. O exemplo a seguir alterna a panormica do som do canal esquerdo para o canal direito e vice-versa enquanto o som reproduzido.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

444

import import import import import

flash.events.Event; flash.media.Sound; flash.media.SoundChannel; flash.media.SoundMixer; flash.net.URLRequest;

var snd:Sound = new Sound(); var req:URLRequest = new URLRequest("bigSound.mp3"); snd.load(req); var panCounter:Number = 0; var trans:SoundTransform; trans = new SoundTransform(1, 0); var channel:SoundChannel = snd.play(0, 1, trans); channel.addEventListener(Event.SOUND_COMPLETE, onPlaybackComplete); addEventListener(Event.ENTER_FRAME, onEnterFrame); function onEnterFrame(event:Event):void { trans.pan = Math.sin(panCounter); channel.soundTransform = trans; // or SoundMixer.soundTransform = trans; panCounter += 0.05; } function onPlaybackComplete(event:Event):void { removeEventListener(Event.ENTER_FRAME, onEnterFrame); }

Esse cdigo iniciado carregando um arquivo de som e criando um novo objeto SoundTransform com o volume definido como 1 (volume total) e panormica definida como 0 (equilibrada igualmente entre a esquerda e a direita). Em seguida, ele chama o mtodo snd.play(), passando o objeto SoundTransform como um parmetro. Enquanto o som reproduzido, o mtodo onEnterFrame() executado repetidamente. O mtodo onEnterFrame() usa a funo Math.sin() para gerar um valor entre -1 e 1, uma faixa que corresponde aos valores aceitveis da propriedade SoundTransform.pan. A propriedade pan do objeto SoundTransform definida como o novo valor e, em seguida, a propriedade soundTransform do canal definida para usar o objeto SoundTransform alterado. Para executar esse exemplo, substitua o nome do arquivo bigSound.mp3 pelo nome de um arquivo mp3 local. Em seguida, execute o exemplo. Voc deve ouvir o volume do canal esquerdo se tornando mais alto enquanto o volume do canal direito se torna mais suave e vice-versa. Nesse exemplo, o mesmo efeito pode ser obtido definindo a propriedade soundTransform da classe SoundMixer. No entanto isso afetar a panormica de todos os sons que esto sendo reproduzidos no momento, no apenas o nico som que est sendo reproduzido pelo objeto SoundChannel.

Trabalho com metadados de som

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Arquivos de som que usam o formato mp3 podem conter dados adicionais sobre o som na forma de tags ID3.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

445

Nem todo arquivo mp3 contm metadados ID3. Quando um objeto Sound carrega um arquivo de som mp3, ele despachar um evento Event.ID3 se o arquivo de som contiver metadados ID3. Para evitar erros em tempo de execuo, o aplicativo deve aguardar at receber o evento Event.ID3 antes de acessar a propriedade Sound.id3 de um som carregado. O cdigo a seguir mostra como reconhecer quando os metadados ID3 de um arquivo de som foram carregados:
import flash.events.Event; import flash.media.ID3Info; import flash.media.Sound; var s:Sound = new Sound(); s.addEventListener(Event.ID3, onID3InfoReceived); s.load("mySound.mp3"); function onID3InfoReceived(event:Event) { var id3:ID3Info = event.target.id3; trace("Received ID3 Info:"); for (var propName:String in id3) { trace(propName + " = " + id3[propName]); } }

Esse cdigo comea criando um objeto Sound e indicando que ele oua o evento Event.ID3. Quando os metadados ID3 do arquivo de som so carregados, o mtodo onID3InfoReceived() chamado. O destino do objeto Event que passado para o mtodo onID3InfoReceived() o objeto Sound original, portanto o mtodo obtm a propriedade id3 do objeto Sound e percorre todas as suas propriedades nomeadas para rastrear seus valores.

Acesso a dados de som brutos

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O mtodo SoundMixer.computeSpectrum() permite que um aplicativo leia os dados de som brutos para a forma de onda que est sendo reproduzida no momento. Se mais de um objeto SoundChannel estiver sendo reproduzido, o mtodo SoundMixer.computeSpectrum() mostrar os dados de som combinados de cada objeto SoundChannel misturado. Os dados de som so retornados como um objeto ByteArray que contm 512 bytes de dados, cada um deles contendo um valor de ponto flutuante entre -1 e 1. Esses valores representam a amplitude dos pontos na forma de onda do som que est sendo reproduzido. Os valores so entregues em dois grupos de 256, o primeiro grupo do canal estreo esquerdo e o segundo grupo do canal estreo direito. O mtodo SoundMixer.computeSpectrum() retornar os dados do espectro da freqncia em vez dos dados da forma de onda se o parmetro FFTMode estiver definido como true. O espectro da freqncia mostra a amplitude organizada pela freqncia do som, da freqncia mais baixa para a mais alta. Uma FFT (Transformao rpida de Fourier) usada para converter os dados da forma de onda nos dados do espectro da freqncia. Os valores do espectro da freqncia resultantes variam de 0 a aproximadamente 1,414 (a raiz quadrada de 2).

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

446

O diagrama a seguir compara os dados retornados do mtodo computeSpectrum() quando o parmetro FFTMode est definido como true e quando est definido como false. O som cujos dados foram usados para esse diagrama contm um som grave alto no canal esquerdo e um som de toque de tambor no canal direito.
Canal esquerdo Canal direito

Canal esquerdo

Canal direito

Valores retornados pelo mtodo SoundMixer.computeSpectrum() A. fftMode=true B. fftMode=false

O mtodo computeSpectrum() tambm pode retornar dados que foram amostrados novamente em uma taxa de bits mais baixa. Geralmente, isso resulta em dados de forma de onda mais suaves ou em dados de freqncia em detrimento de detalhes. O parmetro stretchFactor controla a taxa na qual os dados do mtodo computeSpectrum() so amostrados. Quando o parmetro stretchFactor est definido como 0, o padro, os dados do som so amostrados a uma taxa de 44,1 kHz. A taxa dividida em dois em cada valor sucessivo do parmetro stretchFactor, portanto um valor de 1 especifica uma taxa de 22,05 kHz, um valor de 2 especifica uma taxa de 11,025 kHz e assim por diante. O mtodo computeSpectrum() ainda retorna 256 bytes por canal estreo quando um valor de stretchFactor mais alto usado. O mtodo SoundMixer.computeSpectrum() tem algumas limitaes:

Como os dados do som de um microfone ou de fluxos RTMP no passam pelo objeto global SoundMixer, o mtodo
SoundMixer.computeSpectrum() no retorna dados dessas origens.

Se um ou mais dos sons que esto sendo reproduzidos de origens externas caixa de proteo do contedo atual,
restries de segurana faro com que o mtodo SoundMixer.computeSpectrum() emita um erro. Para obter mais detalhes sobre limitaes de segurana do mtodo SoundMixer.computeSpectrum() consulte Consideraes sobre segurana ao carregar e reproduzir sons na pgina 442 eAcesso mdia carregada como dados na pgina 1052. Contudo, em um aplicativo AIR, o contedo na caixa de proteo de segurana do aplicativo (contedo instalado com o aplicativo AIR) no restringido por essas limitaes de segurana.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

447

Criao de um nico visualizador de som

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O exemplo a seguir usa o mtodo SoundMixer.computeSpectrum() para mostrar um grfico da forma de onda do som que animado com cada quadro:
import import import import import import flash.display.Graphics; flash.events.Event; flash.media.Sound; flash.media.SoundChannel; flash.media.SoundMixer; flash.net.URLRequest;

const PLOT_HEIGHT:int = 200; const CHANNEL_LENGTH:int = 256; var snd:Sound = new Sound(); var req:URLRequest = new URLRequest("bigSound.mp3"); snd.load(req); var channel:SoundChannel; channel = snd.play(); addEventListener(Event.ENTER_FRAME, onEnterFrame); snd.addEventListener(Event.SOUND_COMPLETE, onPlaybackComplete); var bytes:ByteArray = new ByteArray(); function onEnterFrame(event:Event):void { SoundMixer.computeSpectrum(bytes, false, 0); var g:Graphics = this.graphics; g.clear(); g.lineStyle(0, 0x6600CC); g.beginFill(0x6600CC); g.moveTo(0, PLOT_HEIGHT); var n:Number = 0; // left channel for (var i:int = 0; i < CHANNEL_LENGTH; i++) { n = (bytes.readFloat() * PLOT_HEIGHT); g.lineTo(i * 2, PLOT_HEIGHT - n); } g.lineTo(CHANNEL_LENGTH * 2, PLOT_HEIGHT);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

448

g.endFill(); // right channel g.lineStyle(0, 0xCC0066); g.beginFill(0xCC0066, 0.5); g.moveTo(CHANNEL_LENGTH * 2, PLOT_HEIGHT); for (i = CHANNEL_LENGTH; i > 0; i--) { n = (bytes.readFloat() * PLOT_HEIGHT); g.lineTo(i * 2, PLOT_HEIGHT - n); } g.lineTo(0, PLOT_HEIGHT); g.endFill(); } function onPlaybackComplete(event:Event) { removeEventListener(Event.ENTER_FRAME, onEnterFrame); }

Esse exemplo primeiro carrega e reproduz um arquivo de som e, em seguida, ouve o evento Event.ENTER_FRAME que disparar o mtodo onEnterFrame() enquanto o som reproduzido. O mtodo onEnterFrame() iniciado chamando o mtodo SoundMixer.computeSpectrum() que armazena dos dados da onda do som no objeto ByteArray de bytes. A forma de onda do som plotada usando a API de desenho do vetor. Um loop for percorre os primeiros 256 valores de dados que representam o canal estreo esquerdo e desenha uma linha de cada ponto at o prximo usando o mtodo Graphics.lineTo(). Um segundo loop for percorre o prximo conjunto de 256 valores, plotando-os na ordem reversa desta vez, da direita para a esquerda. Os desenhos da forma de onda resultantes podem produzir um efeito interessante de imagem espelhada, conforme mostrado na imagem a seguir.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

449

Captura de entrada do som

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe Microphone permite que o aplicativo se conecte a um microfone ou a outro dispositivo de entrada de som no sistema do usurio e transmita o udio de entrada para os alto-falantes daquele sistema ou envie os dados de udio a um servidor remoto, como o Flash Media Server. Voc pode acessar os dados de udio brutos a partir do microfone e grav-los ou process-los. Tambm pode enviar o udio diretamente para os alto-falantes do sistema ou enviar dados de udio compactados para um servidor remoto. possvel usar o codec Speex ou Nellymoser para os dados enviados a um servidor remoto. (O suporte para o codec Speex foi disponibilizado a partir do Flash Player 10 e do Adobe AIR 1.5.)

Mais tpicos da Ajuda

Michael Chaize: AIR, Android e o Microfone Christophe Coenraets: notas de voz para o Android

Acesso a um microfone
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe Microphone no tem um mtodo construtor. Em vez disso, voc usa o mtodo esttico Microphone.getMicrophone() para obter uma nova ocorrncia de Microphone, conforme mostrado a seguir:
var mic:Microphone = Microphone.getMicrophone();

A chamada do mtodo Microphone.getMicrophone() sem um parmetro retorna o primeiro dispositivo de entrada de som descoberto no sistema do usurio. Um sistema pode ter mais de um dispositivo de entrada de som conectado a ele. O aplicativo pode usar a propriedade Microphone.names para obter uma matriz dos nomes de todos os dispositivos de entrada de som disponveis. Em seguida, ele pode chamar o mtodo Microphone.getMicrophone() com um parmetro index que corresponde ao valor de ndice de um nome de dispositivo na matriz. Um sistema talvez no tenha um microfone ou outro dispositivo de entrada de som conectado a ele. possvel usar a propriedade Microphone.names ou o mtodo Microphone.getMicrophone() para verificar se o usurio tem um dispositivo de entrada de som instalado. Se o usurio no tiver um dispositivo de entrada de som instalado, a matriz names ter um comprimento de zero e o mtodo getMicrophone() retornar um valor null. Quando o aplicativo chama o mtodo Microphone.getMicrophone(), o Flash Player exibe a caixa de dilogo Configuraes do Flash Player que solicita que o usurio permita ou negue acesso do Flash Player cmara e ao microfone no sistema. Depois que o usurio clicar no boto Permitir ou Negar neste dilogo, um StatusEvent ser despachado. A propriedade code dessa ocorrncia de StatusEvent indica se o acesso ao microfone foi permitido ou negado, conforme mostrado neste exemplo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

450

import flash.media.Microphone; var mic:Microphone = Microphone.getMicrophone(); mic.addEventListener(StatusEvent.STATUS, this.onMicStatus); function onMicStatus(event:StatusEvent):void { if (event.code == "Microphone.Unmuted") { trace("Microphone access was allowed."); } else if (event.code == "Microphone.Muted") { trace("Microphone access was denied."); } }

A propriedade StatusEvent.code conter Microphone.Unmuted, se o acesso for permitido, ou Microphone.Muted, se o acesso for negado. A propriedade Microphone.muted definida como true ou false quando o usurio permite ou nega acesso ao microfone, respectivamente. No entanto, a propriedade muted no definida na ocorrncia de Microphone at que StatusEvent tenha sido despachado, de modo que seu aplicativo tambm deve esperar at o evento StatusEvent.STATUS ser despachado antes de verificar a propriedade Microphone.muted. Para que o Flash Player exiba a caixa de dilogo de configuraes, a janela de aplicativo precisa ser grande o suficiente para exibi-la (pelo menos 215 x 138 pixels). Caso contrrio, o acesso negado automaticamente. O contedo em execuo na caixa de proteo do aplicativo AIR no precisa da permisso do usurio para acessar o microfone. Assim, eventos de status para ligar e desligar o som do microfone nunca so despachados. O contedo em execuo no AIR fora da caixa de proteo do aplicativo requer a permisso do usurio, de modo que esses eventos de status podem ser despachados.

Roteamento de udio do microfone para alto-falantes locais

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A entrada de udio de um microfone pode ser roteada para os alto-falantes do sistema local chamando o mtodo Microphone.setLoopback() com um valor de parmetro de true. Quando o som de um microfone local roteado para alto-falantes locais, h um risco de criar um loop de feedback de udio, o que pode provocar sons estridentes e danificar o hardware de som. A chamada do mtodo Microphone.setUseEchoSuppression() com um valor de parmetro true reduz, mas no elimina completamente, o risco de ocorrncia de feedback de udio. A Adobe recomenda sempre chamar Microphone.setUseEchoSuppression(true) antes de chamar Microphone.setLoopback(true), a menos que voc tenha certeza de que o usurio esteja reproduzindo o som usando fones de ouvido ou outra coisa que no seja um alto-falante. O cdigo a seguir mostra como rotear o udio de um microfone local para os alto-falantes do sistema local:
var mic:Microphone = Microphone.getMicrophone(); mic.setUseEchoSuppression(true); mic.setLoopBack(true);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

451

Alterao do udio do microfone

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O aplicativo pode alterar os dados de udio de um microfone de duas maneiras. Primeiro, ele pode alterar o ganho do som de entrada, o que efetivamente multiplica os valores de entrada por um valor especificado para criar um som mais baixo ou mais silencioso. A propriedade Microphone.gain aceita valores numricos entre 0 e 100 inclusive. Um valor de 50 funciona como um multiplicador de um e especifica o volume normal. Um valor de zero funciona como um multiplicador de zero e silencia efetivamente o udio de entrada. Valores acima de 50 especificam um volume mais alto do que o normal. O aplicativo tambm pode alterar a taxa de amostragem do udio de entrada. Taxas de amostragem mais altas aumentam a qualidade do som, mas elas tambm criam fluxos de dados mais densos que usam mais recursos para transmisso e armazenamento. A propriedade Microphone.rate representa a taxa de amostragem de udio medida em quilohertz (kHz). A taxa de amostragem padro de 8 kHz. possvel definir a propriedade Microphone.rate como um valor mais alto do que 8 kHz se o microfone oferecer suporte taxa mais alta. Por exemplo, configurar a propriedade Microphone.rate com um valor de 11 define a taxa de amostragem como 11 kHz. Configur-la como 22 define a taxa de amostragem como 22 kHz e assim por diante. As taxas de amostra disponveis dependem do codec selecionado. Quando voc usa o codec Nellymoser, pode especificar 5, 8, 11, 16, 22 e 44 kHz como taxa de amostra. Quando voc usa o codec Speex (disponvel a partir do Flash Player 10 e do Adobe AIR 1.5), s pode usar 16 kHz.

Deteco de atividade do microfone

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para conservar a largura de banda e os recursos de processamento, o Flash Player tenta detectar quando nenhum som est sendo transmitido por um microfone. Quando o nvel de atividade do microfone permanece abaixo do limite do nvel de silncio por um certo perodo, o Flash Player pra de transmitir a entrada de udio e despacha um simples ActivityEvent. Se voc usar o codec Speex (disponvel no Flash Player 10 ou em verses posteriores e no Adobe AIR 1.5 ou em verses posteriores), defina o nvel de silncio como 0 para assegurar que o aplicativo transmitir dados de udio continuamente. A deteco da atividade de voz do Speex automaticamente reduz a largura de banda. Nota: Um objeto Microphone despacha eventos Activity somente quando o aplicativo estiver monitorando o microfone. Assim, se voc no chamar setLoopBack( true ), adicione um ouvinte para eventos de amostra de dados, ou anexe o microfone a um objeto NetStream e, em seguida, nenhum evento activity ser despachado. Trs propriedades da classe Microphone monitoram e controlam a deteco de atividade:

A propriedade somente leitura activityLevel indica a quantidade de som que o microfone est detectando em
uma escala de 0 a 100.

A propriedade silenceLevel especifica a quantidade de som necessria para ativar o microfone e despachar um
evento ActivityEvent.ACTIVITY. A propriedade silenceLevel tambm usa uma escala de 0 a 100, e o valor padro 10.

A propriedade silenceTimeout descreve o nmero de milissegundos que o nvel de atividade deve permanecer
abaixo do nvel de silncio, at que um evento ActivityEvent.ACTIVITY seja despachado para indicar que o microfone est silencioso. O valor padro de silenceTimeout 2000. As propriedades Microphone.silenceLevel e Microphone.silenceTimeout so somente leitura, mas seus valores podem ser alterados usando o mtodo Microphone.setSilenceLevel().

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

452

Em alguns casos, o processo de ativao do microfone quando nova atividade detectada pode provocar um pequeno atraso. Manter o microfone ativo durante todo o tempo pode remover esses atrasos na ativao. O aplicativo pode chamar o mtodo Microphone.setSilenceLevel() com o parmetro silenceLevel definido como zero para indicar ao Flash Player para manter o microfone ativo e continuar a coletar dados de udio, mesmo quando nenhum som est sendo detectado. De modo oposto, a configurao do parmetro silenceLevel como 100 impede que o microfone seja ativado de qualquer modo. O exemplo a seguir exibe informaes sobre o microfone e relata eventos de atividade e eventos de status despachados por um objeto Microphone:
import flash.events.ActivityEvent; import flash.events.StatusEvent; import flash.media.Microphone; var deviceArray:Array = Microphone.names; trace("Available sound input devices:"); for (var i:int = 0; i < deviceArray.length; i++) { trace(" " + deviceArray[i]); } var mic:Microphone = Microphone.getMicrophone(); mic.gain = 60; mic.rate = 11; mic.setUseEchoSuppression(true); mic.setLoopBack(true); mic.setSilenceLevel(5, 1000); mic.addEventListener(ActivityEvent.ACTIVITY, this.onMicActivity); mic.addEventListener(StatusEvent.STATUS, this.onMicStatus); var micDetails:String = "Sound input device name: " + mic.name + '\n'; micDetails += "Gain: " + mic.gain + '\n'; micDetails += "Rate: " + mic.rate + " kHz" + '\n'; micDetails += "Muted: " + mic.muted + '\n'; micDetails += "Silence level: " + mic.silenceLevel + '\n'; micDetails += "Silence timeout: " + mic.silenceTimeout + '\n'; micDetails += "Echo suppression: " + mic.useEchoSuppression + '\n'; trace(micDetails); function onMicActivity(event:ActivityEvent):void { trace("activating=" + event.activating + ", activityLevel=" + mic.activityLevel); } function onMicStatus(event:StatusEvent):void { trace("status: level=" + event.level + ", code=" + event.code); }

Ao executar o exemplo acima, fale ou faa rudos no microfone do sistema e observe as instrues de rastreamento resultantes serem exibidas em um console ou janela de depurao.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

453

Envio e recebimento de udio de um servidor de mdia

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Recursos adicionais de udio tambm esto disponveis ao usar o ActionScript com um servidor de mdia de fluxo contnuo, como o Flash Media Server. Em particular, seu aplicativo pode conectar um objeto Microphone a um objeto NetStream e transmitir dados diretamente do microfone do usurio para o servidor. Os dados de udio tambm podem ser transmitidos do servidor para um aplicativo e reproduzidos como parte de um MovieClip ou usando um objeto Video. O suporte para o codec Speex foi disponibilizado a partir do Flash Player 10 e do Adobe AIR 1.5. Para definir o codec usado para udio compactado enviado ao servidor de mdia, defina a propriedade codec do objeto Microphone. Esta propriedade pode ter dois valores, que so enumerados na classe SoundCodec. Definir a propriedade do codec como SoundCodec.SPEEX seleciona o codec Speex para compactao de udio. Definir a propriedade como SoundCodec.NELLYMOSER (o padro) seleciona o codec Nellymoser para compactao de udio. Para obter mais informaes, consulte a documentao on-line do Flash Media Server em www.adobe.com/go/learn_fms_docs_br.

Captura dos dados de som do microfone

Flash Player 10.1 e posterior, Adobe AIR 2 e posterior No Flash Player 10.1 e no AIR 2 ou posteriores, voc pode capturar os dados de um microfone, como uma matriz de bytes dos valores de ponto flutuantes. Cada valor representa uma amostragem dos dados de udio monofnicos. Para obter dados de microfone, defina um ouvinte de evento para o evento sampleData do objeto Microphone. O objeto Microphone despacha os eventos sampleData periodicamente medida que o buffer do microfone preenchido com amostragens de som. O objeto SampleDataEvent tem uma propriedade data que uma matriz de bytes das amostragens de som. As amostras so representadas como valores de ponto flutuantes, cada uma representando uma amostragem de som monofnico. O cdigo a seguir captura os dados de som do microfone em um objeto ByteArray chamado soundBytes:
var mic:Microphone = Microphone.getMicrophone(); mic.setSilenceLevel(0, DELAY_LENGTH); mic.addEventListener(SampleDataEvent.SAMPLE_DATA, micSampleDataHandler); function micSampleDataHandler(event:SampleDataEvent):void { while(event.data.bytesAvailable) { var sample:Number = event.data.readFloat(); soundBytes.writeFloat(sample); } }

Voc pode reutilizar os bytes de amostra como udio de reproduo para um objeto Sound. Se fizer isso, defina a propriedade rate do objeto Microphone como 44, que a taxa de amostragem usada pelos objetos Sound. (Voc tambm pode converter as amostragens de microfone capturadas a uma taxa inferior a 44 kHz que exigida pelo objeto Sound.) Alm disso, tenha em mente que o objeto Microphone captura as as amostragens monofnicas, ao passo que o objeto Sound usa som estreo. Por isso, escreva cada um dos bytes capturados pelo objeto Microphone no objeto Sound duas vezes. O exemplo a seguir captura quatro segundos de dados do microfone e o reproduz novamente usando um objeto Sound:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

454

const DELAY_LENGTH:int = 4000; var mic:Microphone = Microphone.getMicrophone(); mic.setSilenceLevel(0, DELAY_LENGTH); mic.gain = 100; mic.rate = 44; mic.addEventListener(SampleDataEvent.SAMPLE_DATA, micSampleDataHandler); var timer:Timer = new Timer(DELAY_LENGTH); timer.addEventListener(TimerEvent.TIMER, timerHandler); timer.start(); function micSampleDataHandler(event:SampleDataEvent):void { while(event.data.bytesAvailable) { var sample:Number = event.data.readFloat(); soundBytes.writeFloat(sample); } } var sound:Sound = new Sound(); var channel:SoundChannel; function timerHandler(event:TimerEvent):void { mic.removeEventListener(SampleDataEvent.SAMPLE_DATA, micSampleDataHandler); timer.stop(); soundBytes.position = 0; sound.addEventListener(SampleDataEvent.SAMPLE_DATA, playbackSampleHandler); channel.addEventListener( Event.SOUND_COMPLETE, playbackComplete ); channel = sound.play(); } function playbackSampleHandler(event:SampleDataEvent):void { for (var i:int = 0; i < 8192 && soundBytes.bytesAvailable > 0; i++) { trace(sample); var sample:Number = soundBytes.readFloat(); event.data.writeFloat(sample); event.data.writeFloat(sample); } } function playbackComplete( event:Event ):void { trace( "Playback finished."); }

Para obter mais informaes sobre os sons de reproduo dos dados de amostragem do som, consulte Trabalho com udio gerado dinamicamente na pgina 436.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

455

Exemplo de som: Podcast Player

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Um podcast um arquivo de som distribudo pela Internet sob demanda ou por assinatura. Podcasts normalmente so publicados como parte de uma srie, o que tambm chamado de canal de podcast. Como episdios de podcast podem durar de um minuto a muitas horas, eles normalmente so transmitidos enquanto esto sendo carregados. Episdios de podcast, que tambm so chamados de itens, normalmente so entregues no formato de arquivo mp3. Os podcasts de vdeo tambm so populares, mas esse aplicativo de amostra reproduz apenas podcasts de udio que usam arquivos mp3. Este exemplo no de um aplicativo agregador de podcast completo. Por exemplo, ele no gerencia assinaturas para podcasts especficos ou lembra quais podcasts foram ouvidos pelo usurio na prxima vez que o aplicativo executado. Ele pode funcionar como um ponto de partida para um agregador de podcast mais completo. Este exemplo de Podcast Player ilustra as seguintes tcnicas de programao do ActionScript:

Leitura de um RSS feed externo e anlise de seu contedo XML Criao de uma classe SoundFacade para simplificar o carregamento e a reproduo de arquivos de som. Exibio do progresso da reproduo do som. Pausa e reincio da reproduo do som.
Para obter os arquivos de aplicativo deste exemplo, consulte www.adobe.com/go/learn_programmingAS3samples_flash_br. Os arquivos do aplicativo Podcast Player podem ser encontrados na pasta Amostras/PodcastPlayer. O aplicativo consiste nos seguintes arquivos:
Arquivo PodcastPlayer.mxml ou PodcastPlayer.fla comp/example/progra Classe Document que contm a lgica da interface de usurio do player de podcast (somente no Flash). mmingas3/podcastplay er/PodcastPlayer.as SoundPlayer.mxml Um componente MXML que exibe botes de reproduo e barras de progresso e controla a reproduo de som, apenas para Flex. Estilos da interface de usurio do aplicativo (somente no Flex). cones para aplicar estilo aos botes (somente no Flex). Descrio A interface do usurio do aplicativo para Flex (MXML) ou Flash (FLA).

main.css images/

comp/example/progra Classe do smbolo de clipe de filme SoundPlayer que contm a lgica da interface de usurio do player de som mmingas3/podcastplay (somente no Flash). er/SoundPlayer.as comp/example/progra Renderizador de clulas personalizado para exibir um boto Reproduzir em uma clula de grade de dados mmingas3/podcastplay (somente no Flash). er/PlayButtonRenderer. as com/example/program Uma classe base que fornece propriedades e mtodos comuns para as classes RSSChannel e RSSItem. mingas3/podcastplayer /RSSBase.as

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

456

Arquivo

Descrio

com/example/program Uma classe ActionScript que mantm dados sobre um canal RSS. mingas3/podcastplayer /RSSChannel.as com/example/program Uma classe ActionScript que mantm dados sobre um item RSS. mingas3/podcastplayer /RSSItem.as com/example/program A classe principal do ActionScript para o aplicativo. Ela encapsula os mtodos e eventos da classe Sound e da classe mingas3/podcastplayer SoundChannel e adiciona suporte para pausar e reiniciar a reproduo. /SoundFacade.as com/example/program Uma classe ActionScript que recupera dados de uma URL remota. mingas3/podcastplayer /URLService.as playerconfig.xml Um arquivo XML que contm uma lista de RSS feeds que representam canais de podcast.

comp/example/progra Classe usada para facilitar a formatao de dados (somente no Flash). mmingas3/utils/DateUt il.as

Leitura de dados RSS para um canal de podcast

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O aplicativo Podcast Player comea lendo informaes sobre vrios canais de podcast e seus episdios: 1. Primeiro, o aplicativo l um arquivo de configurao XML que contm uma lista de canais de podcast e exibe a lista de canais para o usurio. 2. Quando o usurio seleciona um dos canais de podcast, ele l o RSS feed do canal e exibe uma lista de episdios de canal. Este exemplo usa a classe do utilitrio URLLoader para recuperar dados com base em texto de um local remoto ou de um arquivo local. O Podcast Player primeiro cria um objeto URLLoader para obter uma lista de RSS feeds em formato XML do arquivo playerconfig.xml. Em seguida, quando o usurio seleciona um feed especfico da lista, um novo objeto URLLoader criado para ler os dados RSS daquela URL do feed.

Simplificao do carregamento e da reproduo de som usando a classe SoundFacade

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A arquitetura de som do ActionScript 3.0 poderosa, mas complexa. Aplicativos que precisam apenas de recursos bsicos de carregamento e reproduo de som podem usar uma classe que oculte um pouco da complexidade fornecendo um conjunto mais simples de chamadas e eventos de mtodos. No mundo de padres de design de software, essa classe chamada de facade. A classe SoundFacade apresenta uma nica interface para executar as seguintes tarefas:

Carregamento de arquivos de som usando um objeto Sound, um objeto SoundLoaderContext e uma classe
SoundMixer.

Reproduo de arquivos de som usando os objetos Sound e SoundChannel. Despacho de eventos de progresso da reproduo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

457

Pausa e reincio da reproduo do som usando os objetos Sound e SoundChannel.

A classe SoundFacade tenta oferecer mais da funcionalidade das classes de som do ActionScript com menos complexidade. O cdigo a seguir mostra a declarao da classe, as propriedades da classe e o mtodo construtor SoundFacade():
public class SoundFacade extends EventDispatcher { public var s:Sound; public var sc:SoundChannel; public var url:String; public var bufferTime:int = 1000; public public public public public public var var var var var var isLoaded:Boolean = false; isReadyToPlay:Boolean = false; isPlaying:Boolean = false; isStreaming:Boolean = true; autoLoad:Boolean = true; autoPlay:Boolean = true;

public var pausePosition:int = 0; public static const PLAY_PROGRESS:String = "playProgress"; public var progressInterval:int = 1000; public var playTimer:Timer; public function SoundFacade(soundUrl:String, autoLoad:Boolean = true, autoPlay:Boolean = true, streaming:Boolean = true, bufferTime:int = -1):void { this.url = soundUrl; // Sets Boolean values that determine the behavior of this object this.autoLoad = autoLoad; this.autoPlay = autoPlay; this.isStreaming = streaming; // Defaults to the global bufferTime value if (bufferTime < 0) { bufferTime = SoundMixer.bufferTime; } // Keeps buffer time reasonable, between 0 and 30 seconds this.bufferTime = Math.min(Math.max(0, bufferTime), 30000); if (autoLoad) { load(); } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

458

A classe SoundFacade estende a classe EventDispatcher para poder despachar seus prprios eventos. O cdigo da classe primeiro declara propriedades de um objeto Sound e de um objeto SoundChannel. A classe tambm armazena o valor da URL do arquivo de som e uma propriedade bufferTime a ser usada ao transmitir o som em fluxo. Alm disso, ele aceita alguns valores de parmetros booleanos que afetam o comportamento do carregamento e da reproduo:

O parmetro autoLoad indica ao objeto que o carregamento do som deve iniciar assim que esse objeto criado. O parmetro autoPlay indica que a reproduo do som deve iniciar assim que dados de som suficientes estiverem
carregados. Se esse for um fluxo de som, a reproduo ser iniciada assim que dados suficientes, conforme especificado pela propriedade bufferTime, estiverem carregados.

O parmetro streaming indica que a reproduo desse arquivo pode ser iniciada antes do carregamento ser
concludo. O parmetro bufferTime padronizado como um valor de -1. Se o mtodo construtor detectar um valor negativo no parmetro bufferTime, ele definir a propriedade bufferTime como o valor de SoundMixer.bufferTime. Isso permite que o aplicativo seja padronizado para o valor global SoundMixer.bufferTime conforme desejado. Se o parmetro autoLoad for definido como true, o mtodo construtor chamar imediatamente o mtodo load() seguinte para iniciar o carregamento do arquivo de som:
public function load():void { if (this.isPlaying) { this.stop(); this.s.close(); } this.isLoaded = false; this.s = new Sound(); this.s.addEventListener(ProgressEvent.PROGRESS, onLoadProgress); this.s.addEventListener(Event.OPEN, onLoadOpen); this.s.addEventListener(Event.COMPLETE, onLoadComplete); this.s.addEventListener(Event.ID3, onID3); this.s.addEventListener(IOErrorEvent.IO_ERROR, onIOError); this.s.addEventListener(SecurityErrorEvent.SECURITY_ERROR, onIOError); var req:URLRequest = new URLRequest(this.url); var context:SoundLoaderContext = new SoundLoaderContext(this.bufferTime, true); this.s.load(req, context); }

O mtodo load() cria um novo objeto Sound e adiciona ouvintes para todos os eventos de som importantes. Em seguida, ele indica ao objeto Sound para carregar o arquivo de som usando um objeto SoundLoaderContext para passar o valor de bufferTime. Como a propriedade url pode ser alterada, uma ocorrncia de SoundFacade pode ser usada para reproduzir arquivos de som diferentes em sucesso: simplesmente altere a propriedade url e chame o mtodo load() e o novo arquivo de som ser carregado. Os trs mtodos ouvintes de eventos a seguir mostram como o objeto SoundFacade rastreia o progresso do carregamento e decide quando iniciar a reproduo do som:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

459

public function onLoadOpen(event:Event):void { if (this.isStreaming) { this.isReadyToPlay = true; if (autoPlay) { this.play(); } } this.dispatchEvent(event.clone()); } public function onLoadProgress(event:ProgressEvent):void { this.dispatchEvent(event.clone()); } public function onLoadComplete(event:Event):void { this.isReadyToPlay = true; this.isLoaded = true; this.dispatchEvent(evt.clone()); if (autoPlay && !isPlaying) { play(); } }

O mtodo onLoadOpen() executado quando o carregamento do som iniciado. Se o som puder ser reproduzido em modo de streaming, o mtodo onLoadComplete() definir o sinalizador isReadyToPlay como true imediatamente. O sinalizador isReadyToPlay determina se o aplicativo pode iniciar a reproduo do som, talvez em resposta a uma ao do usurio, como um clique em um boto de reproduo. A classe SoundChannel gerencia o buffer de dados de som, portanto no h necessidade de verificar explicitamente se dados suficientes foram carregados antes de chamar o mtodo play(). O mtodo onLoadProgress() executado periodicamente durante o processo de carregamento. Ele simplesmente despacha um clone de seu objeto ProgressEvent para uso pelo cdigo que usa esse objeto SoundFacade. Quando os dados do som estiverem totalmente carregados, o mtodo onLoadComplete() executado, chamando o mtodo play() para sons que no sejam de fluxo, se necessrio. O prprio mtodo play() mostrado a seguir.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

460

public function play(pos:int = 0):void { if (!this.isPlaying) { if (this.isReadyToPlay) { this.sc = this.s.play(pos); this.sc.addEventListener(Event.SOUND_COMPLETE, onPlayComplete); this.isPlaying = true; this.playTimer = new Timer(this.progressInterval); this.playTimer.addEventListener(TimerEvent.TIMER, onPlayTimer); this.playTimer.start(); } } }

O mtodo play() chamar o mtodo Sound.play() se o som estiver pronto para execuo. O objeto SoundChannel resultante armazenado na propriedade sc. Em seguida, o mtodo play() cria um objeto Timer que ser utilizado para despachar eventos de progresso da reproduo em intervalos regulares.

Exibio do progresso da reproduo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A criao de um objeto Timer para acionar o monitoramento da reproduo uma operao complexa que voc deve codificar apenas uma vez. O encapsulamento dessa lgica de Timer em uma classe reutilizvel, como a classe SoundFacade, permite que os aplicativos ouam alguns tipos de eventos de progresso quando um som est sendo carregado e quando ele est sendo reproduzido. O objeto Timer criado pelo mtodo SoundFacade.play() despacha uma ocorrncia de TimerEvent a cada segundo. O mtodo onPlayTimer() a seguir executado sempre que um novo TimerEvent recebido:
public function onPlayTimer(event:TimerEvent):void { var estimatedLength:int = Math.ceil(this.s.length / (this.s.bytesLoaded / this.s.bytesTotal)); var progEvent:ProgressEvent = new ProgressEvent(PLAY_PROGRESS, false, false, this.sc.position, estimatedLength); this.dispatchEvent(progEvent); }

O mtodo onPlayTimer() implementa a tcnica de estimativa de tamanho descrita na seo Monitoramento da reproduo na pgina 440. Em seguida, ele cria uma nova ocorrncia de ProgressEvent com um tipo de evento de SoundFacade.PLAY_PROGRESS, com a propriedade bytesLoaded definida como a posio atual do objeto SoundChannel e a propriedade bytesTotal definida como o comprimento estimado dos dados do som.

Pausa e reincio da reproduo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O mtodo SoundFacade.play() mostrado anteriormente aceita um parmetro pos correspondente a uma posio inicial nos dados de som. Se o valor pos for zero, a reproduo do som ser executada do incio. O mtodo SoundFacade.stop() tambm aceita um parmetro pos conforme mostrado aqui:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com som

461

public function stop(pos:int = 0):void { if (this.isPlaying) { this.pausePosition = pos; this.sc.stop(); this.playTimer.stop(); this.isPlaying = false; } }

Sempre que o mtodo SoundFacade.stop() chamado, ele define a propriedade pausePosition de forma que o aplicativo saiba onde posicionar o indicador de reproduo se o usurio desejar retomar a reproduo do mesmo som. Os mtodos SoundFacade.pause() e SoundFacade.resume() mostrados a seguir chamam os mtodos SoundFacade.stop() e SoundFacade.play() respectivamente, passando um valor de parmetro pos a cada vez.
public function pause():void { stop(this.sc.position); } public function resume():void { play(this.pausePosition); }

O mtodo pause() passa o valor atual de SoundChannel.position para o mtodo play() que armazena o valor na propriedade pausePosition. O mtodo resume()inicia a reproduo do mesmo som novamente usando o valor de pausePosition como o ponto de incio.

Extenso do exemplo do Podcast Player

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Este exemplo apresenta um Podcast Player reduzido ao essencial que demonstra o uso da classe SoundFacade reutilizvel. possvel adicionar outros recursos para aprimorar a utilidade deste aplicativo, incluindo o seguinte:

Armazenar a lista de feeds e informaes de uso sobre cada episdio em uma ocorrncia de SharedObject que pode
ser usada na prxima vez que o usurio executar o aplicativo.

Permitir que o usurio adicione seus prprios RSS feeds lista de canais de podcast. Memorizar a posio do indicador de reproduo quando o usurio interromper ou sair de um episdio, para que
ele possa ser reiniciado daquele ponto na prxima vez que o usurio executar o aplicativo.

Baixar arquivos mp3 de episdios para ouvir offline, quando o usurio no estiver conectado Internet. Adicionar recursos de assinatura que verificam periodicamente novos episdios em um canal de podcast e atualizar
a lista de episdios automaticamente.

Adicionar funcionalidade de pesquisa e de procura de podcast usando uma API de um servio de host de podcast,
como o Odeo.com.

ltima atualizao em 29/3/2011

462

Captulo 23: Trabalho com vdeo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os vdeos criados com o Adobe Flash so uma das tecnologias de destaque na Internet. No entanto, a apresentao tradicional do vdeo, em uma tela retangular com uma barra de progresso e botes de controle na parte inferior, apenas um dos usos possveis do vdeo. Por meio do ActionScript, voc tem acesso e controle ajustados sobre o carregamento, a apresentao e a reproduo de vdeos.

Noes bsicas sobre vdeo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Um recurso importante do Adobe Flash Player e do Adobe AIR a capacidade de exibir e manipular informaes de vdeo com o ActionScript, da mesma forma que voc pode manipular outros contedos visuais, como imagens, animao, texto e assim por diante. Ao criar um arquivo FLV (Flash Video) no Adobe Flash CS4 Professional, voc tem a opo de selecionar uma capa que inclui controles de reproduo comuns. Todavia, no h motivo para se limitar s opes disponveis. Usando o ActionScript, voc tem controle ajustado sobre o carregamento, a exibio e a reproduo de vdeo, o que significa que possvel criar sua prpria capa de player de vdeo ou usar o vdeo de qualquer maneira menos tradicional que voc queira. O trabalho com vdeo no ActionScript envolve o trabalho com uma combinao de vrias classes:

Classe Video: a caixa clssica de contedo de vdeo no Palco uma ocorrncia da classe Video. A classe Video um
objeto de exibio, por isso pode ser manipulada com as mesmas tcnicas aplicveis a outros objetos de exibio, como posicionamento, aplicao de transformaes, aplicao de filtros e modos de mesclagem, entre outras.

Classe StageVideo: normalmente, a classe Video usa decodificao e renderizao por software. Quando a
acelerao por hardware da GPU est disponvel em um dispositivo, seu aplicativo pode aproveitar melhor a renderizao por hardware alternando para a classe StageVideo. A API StageVideo inclui um conjunto de eventos que indica ao cdigo para quando alternar entre os objetos StageVideo e Video. O vdeo Stage impe algumas restries de menor importncia sobre a reproduo de vdeo. Se seu aplicativo aceita essas limitaes, implemente a API do StageVideo. Consulte Orientaes e limitaes na pgina 501.

Classe NetStream: quando voc est carregando um arquivo de vdeo a ser controlado pelo ActionScript, uma
instncia de NetStream representa a origem do contedo do vdeo neste caso, um fluxo de dados de vdeo. O uso de uma instncia de NetStream tambm inclui o uso de um objeto NetConnection, que a conexo com o arquivo de vdeo como o tnel pelo qual carregado o contedo do vdeo.

Classe Camera: quando voc est trabalhando com dados de vdeo de uma cmera conectada ao computador do
usurio, uma instncia de Camera representa a origem do contedo do vdeo a cmera do usurio e os dados de vdeo disponibilizados por ela. Quando voc carrega vdeo externo, pode carregar o arquivo de um servidor Web padro para download progressivo ou trabalhar com vdeo de fluxo contnuo entregue por um servidor especializado, como o Flash Media Server da Adobe.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

463

Conceitos e termos importantes Ponto de sinalizao Um marcador que pode ser colocado em um momento especfico de um arquivo de vdeo, por exemplo, para funcionar como um marcador que localiza esse ponto no tempo ou para fornecer dados adicionais associados ao momento em questo.
Codificao O processo de pegar dados de vdeo em um formato e convert-los em outro formato de dados de vdeo;

por exemplo, voc pode pegar um vdeo de uma origem de alta resoluo e convert-lo em um formato adequado para disponibilizao na Internet.
Quadro Um nico segmento de informaes de vdeo; cada quadro como uma imagem esttica que representa um

instantneo de um momento. A execuo de quadros em seqncia em alta velocidade cria a iluso de movimento.
Quadro principal Um quadro de vdeo que contm todas as informaes do quadro. Outros quadros que vm aps um

quadro-chave contm apenas informaes sobre no qu eles so diferentes do quadro-chave, e no todas as informaes do quadro inteiro.
Metadados Informaes sobre um arquivo de vdeo que so incorporadas a ele e recuperadas quando o vdeo

carregado.
Download progressivo Quando um arquivo de vdeo disponibilizado de um servidor Web padro, os dados de vdeo

so carregados por meio de download progressivo, o que significa que as informaes sobre o vdeo so carregadas em seqncia. Isso tem a vantagem de que a reproduo do vdeo pode comear antes de terminar o download do arquivo inteiro; no entanto, o download progressivo impede de voc avanar para uma parte do vdeo que ainda no foi carregada.
Streaming Como alternativa ao download progressivo, pode-se usar um servidor de vdeo especial para disponibilizar

vdeo pela Internet usando uma tcnica conhecida como streaming (tambm chamada de true streaming). Com o streaming, o computador do visualizador nunca baixa todo o vdeo de uma s vez. Para agilizar os tempos de download, em qualquer momento o computador s precisa de uma parte de todas as informaes do vdeo. Como um servidor especial controla a entrega do contedo do vdeo, qualquer parte do vdeo pode ser acessada a qualquer momento, e no necessrio aguardar o trmino do download para acess-lo.

Noes bsicas sobre formatos de vdeo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Alm do formato de vdeo Adobe FLV, o Flash Player e o Adobe AIR do suporte a vdeo e udio codificados em H.264 e HE-AAC a partir de formatos de arquivo com o padro MPEG-4. Esses formatos transmitem vdeos de alta qualidade com taxas de bits mais baixas. Os desenvolvedores podem utilizar ferramentas padro do setor, como o Adobe Premiere Pro e o Adobe After Effects, para criar e disponibilizar contedos em vdeo interessantes.
Tipo Vdeo Vdeo Vdeo udio Formato H.264 Sorenson Spark ON2 VP6 AAC+ / HE-AAC / AAC v1 / AAC v2 Recipiente MPEG-4: MP4, M4V, F4V, 3GPP Arquivo FLV Arquivo FLV MPEG-4:MP4, M4V, F4V, 3GPP

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

464

Tipo udio udio udio

Formato Mp3 Nellymoser Speex

Recipiente Mp3 Arquivo FLV Arquivo FLV

Mais tpicos da Ajuda

Flash Media Server: codecs com suporte Adobe HTTP Dynamic Streaming

Codificao de vdeo para dispositivos mveis

O AIR no Android pode decodificar uma grande variedade de vdeos H.264. Entretanto, somente um pequeno subconjunto de vdeos H.264 adequado para reproduo suave em telefones celulares. Isso acontece porque muitos celulares so restringidos em termos de poder de processamento. O Adobe Flash Player para celulares pode decodificar vdeos H.264 usando a acelerao de hardware incorporada. Essa decodificao assegura melhor qualidade com consumo mais baixo de energia. O padro H.264 oferece suporte a vrias tcnicas de codificao. Somente dispositivos sofisticados reproduzem vdeo suavemente com perfis e nveis complexos. No entanto, a maioria dos dispositivos pode reproduzir vdeo codificado no perfil de linha e base. Em dispositivos mveis, a acelerao por hardware est disponvel para um subconjunto dessas tcnicas. Os parmetros de perfil e de nvel definem esse subconjunto de tcnicas de codificao e as configuraes usadas pelo codificador. Para os desenvolvedores, isso significa codificar o vdeo na resoluo selecionada, que reproduzida satisfatoriamente na maioria dos dispositivos. Embora as resolues que se beneficiam da acelerao por hardware variem de acordo com o dispositivo, a maioria dos dispositivos oferece suporte s resolues padro a seguir.
Proporo 4:3 16:9 Resolues recomendadas 640 480 640 360 512 384 512 x 288 480 360 480 272

Nota: O Flash Player oferece suporte a cada nvel e perfil do padro H.264. Acatar estas recomendaes garante a acelerao por hardware e uma melhor experincia do usurio na maioria dos dispositivos. Estas recomendaes no so obrigatrias. Para obter uma discusso detalhada e as configuraes de codificao no Adobe Media Encoder CS5, consulte Recomendaes para codificao de vdeo H.264 para Flash Player 10.1 em dispositivos mveis (http://www.adobe.com/devnet/devices/articles/mobile_video_encoding.html). Nota: No iOS, somente o vdeo codificado com os codecs Sorenson Spark e On2 VP6 podem ser reproduzidos usando a classe Video. Voc tambm pode reproduzir vdeo codificado H.264 no reprodutor de vdeo do dispositivo ativando o URL para o vdeo, usando a funo flash.net.navigateToURL(). Voc tambm pode reproduzir vdeo H.264 usando a marcao <video> em uma pgina html exibida num objeto StageWebView.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

465

Compatibilidade do Flash Player e do AIR com arquivos de vdeo codificados

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O Flash Player 7 oferece suporte a arquivos FLV codificados com o codec de vdeo Sorenson Spark. O Flash Player 8 d suporte a arquivos FLV codificados com o codificador Sorenson Spark ou On2 VP6 no Flash Professional 8. O codec de vdeo On2 VP6 oferece suporte a um canal alfa. O Flash Player 9.0.115.0 e verses posteriores do suporte a arquivos derivados do formato de recipiente MPEG-4 padro. Esses arquivos incluem F4V, MP4, M4A, MOV, MP4V, 3GP e 3G2, se contm vdeo H.264 ou udio codificado em HE-AAC v2 ou ambos. O H.264 oferece vdeo de qualidade superior com taxas de bits inferiores se comparadas com o mesmo perfil de codificao no Sorenson ou On2. O HE-AAC v2 uma extenso do AAC, um formato de udio padro definido no padro de vdeo MPEG-4. O HE-AAC v2 usa as tcnicas SBR (Spectral Band Replication) e PS (Parametric Stereo) para aumentar a eficincia da codificao em taxas de bits baixas. A tabela a seguir lista os codecs suportados. Ela tambm mostra o formato de arquivo SWF correspondente e as verses do Flash Player e do AIR necessrias para reproduzi-los:
Codec Verso do formato de arquivo SWF (verso de publicao mais antiga suportada) 6 6 Flash Player e AIR (verso mais antiga necessria para reproduo)

Sorenson Spark On2 VP6

Flash Player 6, Flash Lite 3 Flash Player 8, Flash Lite 3. Apenas o Flash Player 8 e verses posteriores oferecem suporte publicao e reproduo de vdeo On2 VP6.

H.264 (MPEG-4 Parte 10) ADPCM Mp3 AAC (MPEG-4 Parte 3) Speex (udio) Nellymoser

9 6 6 9 10 6

Flash Player 9 Update 3, AIR 1.0 Flash Player 6, Flash Lite 3 Flash Player 6, Flash Lite 3 Flash Player 9 Update 3, AIR 1.0 Flash Player 10, AIR 1.5 Flash Player 6

Noes bsicas sobre os formatos de arquivo de vdeo Adobe F4V e FLV

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A Adobe oferece os formatos de arquivo de vdeo F4V e FLV para transmitir contedo para o Flash Player e o AIR. Para ver uma descrio completa desses formatos de arquivo de vdeo, consulte www.adobe.com/go/video_file_format_br.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

466

O formato de arquivo de vdeo F4V

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A partir da atualizao 3 do Flash Player (9.0.115.0) e do AIR 1.0, o Flash Player e o AIR do suporte ao formato de vdeo Adobe F4V, que baseado no formato ISO MP4. Subconjuntos do formato do suporte a diferentes recursos. O Flash Player espera que um arquivo F4V vlido comece com uma das seguintes caixas de nvel superior:

ftyp
A caixa ftyp identifica os recursos para os quais um programa deve oferecer suporte para executar um determinado formato de arquivo.

moov
A caixa moov o cabealho de um arquivo F4V. Ela contm uma ou mais outras caixas que, por sua vez, contm outras caixas que definem a estrutura dos dados F4V. Um arquivo F4V deve conter somente uma caixa moov.

mdat
Uma caixa mdat contm a carga de dados do arquivo F4V. Um arquivo FV contm apenas uma caixa mdat. Tambm deve haver uma caixa moov no arquivo porque a caixa mdat no pode ser compreendida por si s. Os arquivos F4V do suporte a inteiros multibyte na ordem de bytes big-endian, pela qual o byte mais importante ocorre primeiro, no endereo mais baixo.

O formato de arquivo de vdeo FLV

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O formato de arquivo Adobe FLV contm dados de udio e vdeo codificados para entrega pelo Flash Player. possvel usar um codificador, como o Adobe Media Encoder ou o Sorenson Squeeze, para converter um arquivo de vdeo do QuickTime ou do Windows Media em um arquivo FLV. Nota: Voc pode criar arquivos FLV importando vdeo para o Flash e o exportando como um arquivo FLV. Voc pode usar o plug-in de exportao de FLV para exportar arquivos FLV de aplicativos de edio de vdeos suportados. Para carregar arquivos FLV de um servidor Web, registre a extenso do nome de arquivo e o tipo MIME no servidor Web. Consulte a documentao do seu servidor Web. O tipo MIME de arquivos FLV video/x-flv. Para obter mais informaes, consulte Sobre a configurao de arquivos FLV para hospedagem em um servidor na pgina 492. Para obter mais informaes sobre arquivos FLV, consulte Tpicos avanados sobre arquivos de vdeo na pgina 491.

Vdeo externo versus incorporado

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O uso de arquivos de vdeo externos oferece determinados recursos que no esto disponveis quando voc usa vdeo importado:

Clipes de vdeo mais longos podem ser usados no seu aplicativo sem diminuir a velocidade da reproduo.
Arquivos de vdeo externos usam a memria cache, o que significa que arquivos grandes so armazenados em pequenas partes e acessados dinamicamente. Por esse motivo, os arquivos F4V e FLV externos exigem menos memria do que os arquivos de vdeo incorporados.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

467

Um arquivo de vdeo externo pode ter uma taxa de quadros diferente do que o arquivo SWF no qual ele
reproduzido. Por exemplo, voc pode definir a taxa de quadros do arquivo SWF como 30 quadros por segundo (fps) e a taxa de quadros de vdeo como 21 fps. Esta configurao lhe d mais controle sobre o vdeo do que o vdeo incorporado e assegura a reproduo contnua. Ela tambm permite reproduzir arquivos de vdeo com taxas de quadro diferentes sem precisar alterar o contedo do arquivo SWF existente.

Com arquivos de vdeo externos, a reproduo do contedo SWF no interrompida enquanto o arquivo de vdeo
est sendo carregado. s vezes, os arquivos de vdeo importados podem interromper a reproduo de documentos para executar certas funes, como acessar uma unidade de CD-ROM. Os arquivos de vdeo podem executar funes independentemente do contedo SWF sem interromper a reproduo.

mais fcil legendar o contedo em vdeo com arquivos FLV externos porque voc pode acessar os metadados do
vdeo usando manipuladores de eventos.

Noes bsicas sobre a classe Video

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe Video permite exibir vdeo de fluxo contnuo ao vivo em um aplicativo sem incorpor-lo ao seu arquivo SWF. possvel capturar e reproduzir vdeo ao vivo usando o mtodo Camera.getCamera(). Voc tambm pode usar a classe Video para reproduzir arquivos de vdeo por HTTP ou a partir do sistema de arquivos local. H vrias maneiras diferentes de usar a classe Video em seus projetos:

Carregue um arquivo de vdeo dinamicamente usando as classes NetConnection e NetStream e exiba o vdeo em
um objeto Video.

Capture a entrada da cmera do usurio. Para mais informaes, consulte Trabalhando com cmeras na
pgina 508.

Use o componente FLVPlayback. Use o controle VideoDisplay.

Nota: As ocorrncias de um objeto Video no Palco so ocorrncias da classe Video. Embora a classe Video esteja no pacote flash.media, ela herda da classe flash.display.DisplayObject. Portanto, toda a funcionalidade do objeto de exibio, como transformaes de matriz e filtros, tambm se aplica a ocorrncias de Video. Para obter mais informaes, consulte Manipulao de objetos de exibio na pgina 166, Trabalho com geometria na pgina 202 e Filtro de objetos de exibio na pgina 259.

Carregamento de arquivos de vdeo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O processo de carregar vdeos usando as classes NetStream e NetConnection inclui vrias etapas:
1 Crie um objeto NetConnection. Se voc estiver se conectando a um arquivo de vdeo local ou a um arquivo que no

est usando um servidor, como o Flash Media Server 2 da Adobe, passe null para o mtodo connect() para reproduzir arquivos de vdeo de um endereo HTTP ou de uma unidade local. Se voc estiver se conectando a um servidor, defina o parmetro como o URI do aplicativo que contm o arquivo de vdeo no servidor.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

468

var nc:NetConnection = new NetConnection(); nc.connect(null);

2 Crie um objeto NetStream que use um objeto NetConnection como parmetro e especifique o arquivo de vdeo que

voc deseja carregar. O seguinte snippet conecta um objeto NetStream ocorrncia especificada de NetConnection e carrega um arquivo de vdeo chamado video.mp4 no mesmo diretrio do arquivo SWF:
var ns:NetStream = new NetStream(nc); ns.addEventListener(AsyncErrorEvent.ASYNC_ERROR, asyncErrorHandler); ns.play("video.mp4"); function asyncErrorHandler(event:AsyncErrorEvent):void { // ignore error }

3 Crie um novo objeto Video e anexe o objeto NetStream criado anteriormente usando o mtodo
attachNetStream() da classe Video. Em seguida, adicione o objeto de vdeo lista de exibio usando o mtodo addChild(), como visto neste snippet: var vid:Video = new Video(); vid.attachNetStream(ns); addChild(vid);

medida que o Flash Player executa esse cdigo, ele tenta carregar o arquivo de vdeo video.mp4 do mesmo diretrio em que est o seu arquivo SWF.

Mais tpicos da Ajuda

Flex: controle Spark VideoPlayer spark.components.VideoDisplay

Controle da reproduo de vdeo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe NetStream oferece quatro principais mtodos para controlar a reproduo de vdeos:
pause(): pausa a reproduo de um vdeo em fluxo contnuo. Se o vdeo j estiver pausado, chamar este mtodo no

ter efeito.
resume(): reinicia a reproduo de um vdeo em fluxo contnuo que foi suspenso. Se o vdeo j estiver em reproduo,

chamar este mtodo no ter efeito.

seek(): busca o quadro-chave mais prximo do local especificado (um deslocamento, em segundos, a partir do incio do fluxo). togglePause(): pausa ou reinicia a reproduo de um fluxo contnuo.

Nota: No h um mtodo stop(). Para interromper um fluxo, voc deve pausar a reproduo e fazer a busca at o incio do fluxo de vdeo. Nota: O mtodo play() no reinicia a reproduo; ele usado para carregar arquivos de vdeo. O exemplo a seguir demonstra como controlar um vdeo usando vrios botes diferentes. Para executar o exemplo, crie um novo documento e adicione quatro ocorrncias de boto ao seu espao de trabalho (pauseBtn, playBtn, stopBtn e togglePauseBtn):

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

469

var nc:NetConnection = new NetConnection(); nc.connect(null); var ns:NetStream = new NetStream(nc); ns.addEventListener(AsyncErrorEvent.ASYNC_ERROR, asyncErrorHandler); ns.play("video.flv"); function asyncErrorHandler(event:AsyncErrorEvent):void { // ignore error } var vid:Video = new Video(); vid.attachNetStream(ns); addChild(vid); pauseBtn.addEventListener(MouseEvent.CLICK, pauseHandler); playBtn.addEventListener(MouseEvent.CLICK, playHandler); stopBtn.addEventListener(MouseEvent.CLICK, stopHandler); togglePauseBtn.addEventListener(MouseEvent.CLICK, togglePauseHandler); function pauseHandler(event:MouseEvent):void { ns.pause(); } function playHandler(event:MouseEvent):void { ns.resume(); } function stopHandler(event:MouseEvent):void { // Pause the stream and move the playhead back to // the beginning of the stream. ns.pause(); ns.seek(0); } function togglePauseHandler(event:MouseEvent):void { ns.togglePause(); }

Quando voc clica na ocorrncia do boto pauseBtn durante a reproduo do vdeo, o arquivo de vdeo pausado. Se o vdeo j estiver pausado, clicar neste boto no ter efeito. Clicar na ocorrncia do boto playBtn reinicia a reproduo do vdeo se a reproduo foi pausada anteriormente; caso contrrio, o boto no ter efeito se o vdeo j estiver sendo reproduzido.

Deteco do final de um fluxo de vdeo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para monitorar o comeo ou o final de um fluxo de vdeo, voc precisa adicionar um ouvinte de eventos ocorrncia de NetStream para monitorar o evento netStatus. O seguinte cdigo demonstra como monitorar os diversos cdigos durante a reproduo do vdeo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

470

ns.addEventListener(NetStatusEvent.NET_STATUS, statusHandler); function statusHandler(event:NetStatusEvent):void { trace(event.info.code) }

O cdigo anterior gera a seguinte sada:

NetStream.Play.Start NetStream.Buffer.Empty NetStream.Buffer.Full NetStream.Buffer.Empty NetStream.Buffer.Full NetStream.Buffer.Empty NetStream.Buffer.Full NetStream.Buffer.Flush NetStream.Play.Stop NetStream.Buffer.Empty NetStream.Buffer.Flush

Os dois cdigos que voc deseja monitorar especificamente so NetStream.Play.Start e NetStream.Play.Stop, que sinalizam o incio e o fim da reproduo do vdeo. O seguinte snippet usa uma instruo de opo para filtrar esses dois cdigos e rastrear uma mensagem:
function statusHandler(event:NetStatusEvent):void { switch (event.info.code) { case "NetStream.Play.Start": trace("Start [" + ns.time.toFixed(3) + " seconds]"); break; case "NetStream.Play.Stop": trace("Stop [" + ns.time.toFixed(3) + " seconds]"); break; } }

Ao monitorar o evento netStatus (NetStatusEvent.NET_STATUS), voc pode criar um player de vdeo que carregue o prximo vdeo de uma lista de exibio depois que a reproduo do vdeo atual for concluda.

Reproduo de vdeo no modo de tela cheia

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O Flash Player e o AIR permitem criar um aplicativo em tela cheia para a reproduo de vdeos e do suporte ao dimensionamento de vdeo em tela cheia. Para contedo do AIR em execuo em modo de tela cheia na rea de trabalho, o protetor de tela do sistema e as opes de economia de energia ficam desativados durante a reproduo at que a entrada de vdeo pare ou que o usurio saia do modo de tela cheia. Para obter detalhes sobre como usar o modo de tela cheia, consulte Trabalho com o modo de tela cheia na pgina 161.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

471

Ativao do modo de tela cheia do Flash Player em um navegador Para que voc possa implementar o modo de tela cheia do Flash Player em um navegador, ative-o atravs do modelo Publish do seu aplicativo. Os modelos que permitem o modo de tela cheia incluem as tags <object> e <embed> que contm um parmetro allowFullScreen. O exemplo a seguir mostra o parmetro allowFullScreen em uma tag <embed>.
<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" id="fullScreen" width="100%" height="100%" codebase="http://fpdownload.macromedia.com/get/flashplayer/current/swflash.cab"> ... <param name="allowFullScreen" value="true" /> <embed src="fullScreen.swf" allowFullScreen="true" quality="high" bgcolor="#869ca7" width="100%" height="100%" name="fullScreen" align="middle" play="true" loop="false" quality="high" allowScriptAccess="sameDomain" type="application/x-shockwave-flash" pluginspage="http://www.adobe.com/go/getflashplayer"> </embed> ... </object>

No Flash, selecione Arquivo -> Configuraes de publicao e, na aba HTML da caixa de dilogo Configuraes de publicao, selecione o modelo Somente Flash - Permitir tela cheia. No Flex, verifique se o modelo HTML inclui as tags <object> e <embed> que do suporte a tela cheia. Inicializao do modo de tela cheia Para contedo Flash Player executado em um navegador, voc inicia o modo de tela cheia para vdeo em resposta a um clique do mouse ou a um pressionamento de tecla. Por exemplo, voc pode iniciar o modo de tela cheia quando o usurio clica em um boto chamado Tela cheia ou seleciona um comando Tela cheia em um menu de contexto. Para responder ao usurio, adicione um ouvinte de eventos ao objeto no qual ocorre a ao. O seguinte cdigo adiciona um ouvinte de eventos a um boto no qual o usurio clica para entrar no modo de tela cheia:
var fullScreenButton:Button = new Button(); fullScreenButton.label = "Full Screen"; addChild(fullScreenButton); fullScreenButton.addEventListener(MouseEvent.CLICK, fullScreenButtonHandler); function fullScreenButtonHandler(event:MouseEvent) { stage.displayState = StageDisplayState.FULL_SCREEN; }

O cdigo inicia o modo de tela cheia definindo a propriedade Stage.displayState como StageDisplayState.FULL_SCREEN. Este cdigo dimensiona todo o palco em tela cheia, sendo que o vdeo dimensionado proporcionalmente ao espao que ocupa no palco. A propriedade fullScreenSourceRect permite especificar uma determinada rea do palco a ser dimensionada para tela cheia. Primeiro, defina o retngulo que voc deseja dimensionar para tela cheia. Depois, atribua-o propriedade Stage.fullScreenSourceRect. Esta verso da funo fullScreenButtonHandler() adiciona duas linhas a mais de cdigo que dimensionam somente o vdeo para tela cheia.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

472

private function fullScreenButtonHandler(event:MouseEvent) { var screenRectangle:Rectangle = new Rectangle(video.x, video.y, video.width, video.height); stage.fullScreenSourceRect = screenRectangle; stage.displayState = StageDisplayState.FULL_SCREEN; }

Embora este exemplo chame um manipulador de eventos em resposta a um clique do mouse, a tcnica de entrar no modo de tela cheia a mesma para o Flash Player e o AIR. Defina o retngulo que voc deseja dimensionar e configure a propriedade Stage.displayState. Para obter mais informaes, consulte Referncia do ActionScript 3.0 para a plataforma Adobe Flash. O exemplo completo, mostrado a seguir, adiciona um cdigo que cria a conexo e o objeto NetStream para o vdeo e comea a reproduzi-lo.
package { import import import import import import import import import

flash.net.NetConnection; flash.net.NetStream; flash.media.Video; flash.display.StageDisplayState; fl.controls.Button; flash.display.Sprite; flash.events.MouseEvent; flash.events.FullScreenEvent; flash.geom.Rectangle;

public class FullScreenVideoExample extends Sprite { var fullScreenButton:Button = new Button(); var video:Video = new Video(); public function FullScreenVideoExample() { var videoConnection:NetConnection = new NetConnection(); videoConnection.connect(null); var videoStream:NetStream = new NetStream(videoConnection); videoStream.client = this; addChild(video); video.attachNetStream(videoStream); videoStream.play("http://www.helpexamples.com/flash/video/water.flv"); fullScreenButton.x = 100;

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

473

fullScreenButton.y = 270; fullScreenButton.label = "Full Screen"; addChild(fullScreenButton); fullScreenButton.addEventListener(MouseEvent.CLICK, fullScreenButtonHandler); } private function fullScreenButtonHandler(event:MouseEvent) { var screenRectangle:Rectangle = new Rectangle(video.x, video.y, video.width, video.height); stage.fullScreenSourceRect = screenRectangle; stage.displayState = StageDisplayState.FULL_SCREEN; } public function onMetaData(infoObject:Object):void { // stub for callback function } } }

A funo onMetaData() uma funo de retorno de chamada que manipula os metadados do vdeo, se houver. Uma funo de retorno de chamada a funo que o tempo de execuo chama em resposta a algum tipo de ocorrncia ou evento. Neste exemplo, a funo onMetaData() um stub que atende ao requisito de fornecer a funo. Para obter mais informaes, consulte Criao de mtodos de retorno de chamada para metadados e pontos de sinalizao na pgina 475 Sada do modo de tela cheia Um usurio pode sair do modo de tela cheia usando um dos atalhos de teclado, como a tecla Escape. Voc pode encerrar o modo de tela cheia no ActionScript definindo a propriedade Stage.displayState como StageDisplayState.NORMAL. O cdigo do exemplo a seguir finaliza o modo de tela cheia quando ocorre o evento NetStream.Play.Stop netStatus.
videoStream.addEventListener(NetStatusEvent.NET_STATUS, netStatusHandler); private function netStatusHandler(event:NetStatusEvent) { if(event.info.code == "NetStream.Play.Stop") stage.displayState = StageDisplayState.NORMAL; }

Acelerao de hardware em tela cheia Quando voc dimensiona novamente a rea retangular do palco para o modo de tela cheia, o Flash Player ou o AIR usa acelerao por hardware caso ela esteja disponvel e ativada. O tempo de execuo usa o adaptador de vdeo do computador para acelerar o dimensionamento do vdeo ou de uma parte do palco para o tamanho de tela cheia. Nestas circunstncias, os aplicativos Flash Player muitas vezes podem aproveitar a mudana para a classe StageVideo da classe Video. Para obter mais informaes sobre acelerao de hardware no modo de tela cheia, consulte Trabalho com o modo de tela cheia na pgina 161. Para mais informaes sobre StageVideo, consulte Utilizando a classe StageVideo para renderizao acelerada por hardware na pgina 499.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

474

Arquivos de vdeo em fluxo contnuo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para reproduzir arquivos em fluxo contnuo no Flash Media Server, voc pode usar as classes NetConnection e NetStream para se conectar a uma ocorrncia do servidor remoto e reproduzir um fluxo especificado. Para especificar um servidor RTMP (Real-Time Messaging Protocol), passe a URL RTMP desejada, como rtmp://localhost/appName/appInstance, para o mtodo NetConnection.connect() em vez de passar null. Para reproduzir um determinado fluxo ao vivo ou gravado do Flash Media Server, passe um nome de identificao referente aos dados ao vivo publicados por NetStream.publish() ou um nome de arquivo gravado para reproduo ao mtodo NetStream.play().

Envio de vdeo para um servidor

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Se voc deseja criar aplicativos mais complexos que envolvam objetos de vdeo ou cmera, o Flash Media Server oferece uma combinao de recursos de fluxo de mdia e um ambiente de desenvolvimento para criar e disponibilizar aplicativos de mdia para um grande pblico. Esta combinao permite que os desenvolvedores criem aplicativos como Vdeo sob Demanda, transmisses ao vivo de eventos pela Web e streaming Mp3, alm de publicao de vdeos em blogs, envio de vdeos via mensagens instantneas e ambientes de bate-papo com recursos multimdia. Para obter mais informaes, consulte a documentao on-line do Flash Media Server em www.adobe.com/go/learn_fms_docs_br.

Noes bsicas sobre pontos de sinalizao

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior possvel incorporar pontos de sinalizao a um arquivo de vdeo Adobe F4V ou FLV durante a codificao. Historicamente, os pontos de sinalizao eram incorporados a filmes para dar ao projetista um sinal visual que indicava que o rolo de filme estava perto do fim. Nos formatos de vdeo Adobe F4V e FLV, um ponto de sinalizao permite que voc d incio a uma ou mais aes no aplicativo quando ele ocorrer no fluxo de vdeo. Voc pode usar vrios tipos diferentes de pontos de sinalizao com vdeos criados no Flash. Voc pode usar o ActionScript para interagir com pontos de sinalizao que incorpora a um arquivo de vdeo ao cri-lo.

Pontos de sinalizao de navegao: incorpore pontos de sinalizao de navegao ao pacote de metadados e fluxo
de vdeo quando codificar o arquivo de vdeo. Use pontos de sinalizao de navegao para que os usurios possam fazer a busca at uma determinada parte de um arquivo.

Pontos de sinalizao de evento: incorpore pontos de sinalizao de evento ao pacote de metadados e fluxo de vdeo
quando codificar o arquivo de vdeo. Voc pode criar um cdigo para manipular os eventos que so acionados em pontos especficos durante a reproduo do vdeo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

475

Pontos de sinalizao do ActionScript: os pontos de sinalizao do ActionScript s esto disponveis para o

componente FLVPlayback do Flash. Eles so pontos de sinalizao externos criados e acessados com cdigo ActionScript. Voc pode criar um cdigo para acionar esses pontos de sinalizao em relao reproduo do vdeo. Eles so menos precisos do que os pontos de sinalizao incorporados (at um dcimo de segundo), porque o player de vdeo os rastreia separadamente. Se voc pretende criar um aplicativo em que os usurios podero navegar at um ponto de sinalizao, deve criar e incorporar pontos de sinalizao quando codificar o arquivo em vez de usar pontos de sinalizao do ActionScript. Voc deve incorporar os pontos de sinalizao ao arquivo FLV porque eles so mais precisos. Os pontos de sinalizao de navegao criam um quadro-chave no local especificado do ponto de sinalizao, por isso voc pode usar um cdigo para deslocar o indicador de reproduo de um player de vdeo at esse local. possvel definir pontos especficos em um arquivo de vdeo no qual voc deseja que os usurios faam uma busca. Por exemplo, o seu vdeo pode ter vrios captulos ou segmentos, e voc pode control-lo incorporando pontos de sinalizao de navegao ao arquivo de vdeo. Para obter mais informaes sobre como codificar arquivos de vdeo Adobe com pontos de sinalizao, consulte Incorporao de pontos de sinalizao em Uso do Flash. possvel acessar parmetros de ponto de sinalizao criando cdigo ActionScript. Os parmetros de ponto de sinalizao fazem parte do objeto de evento recebido pelo manipulador de retorno de chamada. Para iniciar certas aes no seu cdigo quando um arquivo FLV atingir um ponto de sinalizao especfico, use o manipulador de eventos NetStream.onCuePoint. Para sincronizar uma ao para um ponto de sinalizao em um arquivo de vdeo F4V, recupere os dados do ponto de sinalizao usando as funes de retorno de chamada onMetaData() ou onXMPData() e acione o ponto de sinalizao usando a classe Timer do ActionScript 3.0. Para obter mais informaes sobre pontos de sinalizao F4V, consulte Uso de onXMPData() na pgina 487. Para obter mais informaes sobre como manipular pontos de sinalizao e metadados, consulte Criao de mtodos de retorno de chamada para metadados e pontos de sinalizao na pgina 475.

Criao de mtodos de retorno de chamada para metadados e pontos de sinalizao

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior possvel iniciar aes no seu aplicativo quando metadados especficos so recebidos pelo player ou quando se atingem determinados pontos de sinalizao. Quando esses eventos ocorrem, voc deve usar mtodos de retorno de chamada especficos como manipuladores de eventos. A classe NetStream especifica os seguintes eventos de metadados, que podem ocorrer durante a reproduo: onCuePoint (somente em arquivos FLV), onImageData, onMetaData, onPlayStatus, onTextData e onXMPData. Voc deve criar mtodos de retorno de chamada para esses manipuladores, ou o tempo de execuo do Flash poder gerar erros. Por exemplo, o cdigo a seguir reproduz um arquivo FLV chamado video.flv na mesma pasta em que reside o arquivo SWF:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

476

var nc:NetConnection = new NetConnection(); nc.connect(null); var ns:NetStream = new NetStream(nc); ns.addEventListener(AsyncErrorEvent.ASYNC_ERROR, asyncErrorHandler); ns.play("video.flv"); function asyncErrorHandler(event:AsyncErrorEvent):void { trace(event.text); } var vid:Video = new Video(); vid.attachNetStream(ns); addChild(vid);

O cdigo anterior carrega um arquivo de vdeo local chamado video.flv e monitora o evento asyncError (AsyncErrorEvent.ASYNC_ERROR) a ser despachado. Esse evento despachado quando o cdigo assncrono nativo gera uma exceo. Nesse caso, ele despachado quando o arquivo de vdeo contm informaes de metadados ou de ponto de sinalizao e os ouvintes apropriados no foram definidos. O cdigo anterior manipula o evento asyncError e ignora o erro se voc no est interessado nas informaes de metadados ou de ponto de sinalizao do arquivo de vdeo. Se voc tivesse um arquivo FLV com metadados e vrios pontos de sinalizao, a funo trace() exibiria as seguintes mensagens de erro:
Error Error Error Error #2095: #2095: #2095: #2095: flash.net.NetStream flash.net.NetStream flash.net.NetStream flash.net.NetStream was was was was unable unable unable unable to to to to invoke invoke invoke invoke callback callback callback callback onMetaData. onCuePoint. onCuePoint. onCuePoint.

Os erros ocorrem porque o objeto NetStream no conseguiu encontrar um mtodo de retorno de chamada onMetaData ou onCuePoint. Existem diversas maneiras de definir esses mtodos de retorno de chamada nos seus aplicativos.

Mais tpicos da Ajuda

Flash Media Server: tratamento de metadados em fluxos

Definir a propriedade client do objeto NetStream como Object

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Ao definir a propriedade client como Object ou uma subclasse de NetStream, voc pode redirecionar os mtodos de retorno de chamada onMetaData e onCuePoint ou ignor-los completamente. O exemplo a seguir demonstra como usar um Object vazio para ignorar os mtodos de retorno de chamada sem monitorar o evento asyncError:
var nc:NetConnection = new NetConnection(); nc.connect(null); var customClient:Object = new Object(); var ns:NetStream = new NetStream(nc); ns.client = customClient; ns.play("video.flv"); var vid:Video = new Video(); vid.attachNetStream(ns); addChild(vid);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

477

Para monitorar os mtodos de retorno de chamada onMetaData ou onCuePoint, seria preciso definir mtodos para manipular esses mtodos de retorno de chamada, conforme mostrado no seguinte snippet:
var customClient:Object = new Object(); customClient.onMetaData = metaDataHandler; function metaDataHandler(infoObject:Object):void { trace("metadata"); }

O cdigo anterior monitora o mtodo de retorno de chamada onMetaData e chama o mtodo metaDataHandler(), que rastreia uma string. Se o tempo de execuo do Flash encontrasse um ponto de sinalizao, nenhum erro seria gerado, mesmo que no tenha sido definido um mtodo de retorno de chamada onCuePoint.

Criar uma classe personalizada e definir mtodos para manipular os mtodos de retorno de chamada
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O seguinte cdigo define a propriedade client do objeto NetStream como uma classe personalizada, CustomClient, que define manipuladores para os mtodos de retorno de chamada:
var nc:NetConnection = new NetConnection(); nc.connect(null); var ns:NetStream = new NetStream(nc); ns.client = new CustomClient(); ns.play("video.flv"); var vid:Video = new Video(); vid.attachNetStream(ns); addChild(vid);

Esta a classe CustomClient:

package { public class CustomClient { public function onMetaData(infoObject:Object):void { trace("metadata"); } } }

A classe CustomClient define um manipulador para o manipulador de retorno de chamada onMetaData. Se fosse encontrado um ponto de sinalizao e o manipulador de retorno de chamada onCuePoint fosse chamado, seria despachado um evento asyncError (AsyncErrorEvent.ASYNC_ERROR) informando que flash.net.NetStream no pde chamar o manipulador de retorno de chamada onCuePoint. Para evitar esse erro, seria necessrio definir um mtodo de retorno de chamada onCuePoint na classe CustomClient ou definir um manipulador de eventos para o evento asyncError.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

478

Estender a classe NetStream e adicionar mtodos para manipular os mtodos de retorno de chamada
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O cdigo abaixo cria uma ocorrncia da classe CustomNetStream, que definida em uma listagem de cdigo mais adiante:
var ns:CustomNetStream = new CustomNetStream(); ns.play("video.flv"); var vid:Video = new Video(); vid.attachNetStream(ns); addChild(vid);

A seguinte listagem de cdigo define a classe CustomNetStream que estende a classe NetStream, manipula a criao do objeto NetConnection necessrio e manipula os mtodos de manipulador de retorno de chamada onMetaData e onCuePoint:
package { import flash.net.NetConnection; import flash.net.NetStream; public class CustomNetStream extends NetStream { private var nc:NetConnection; public function CustomNetStream() { nc = new NetConnection(); nc.connect(null); super(nc); } public function onMetaData(infoObject:Object):void { trace("metadata"); } public function onCuePoint(infoObject:Object):void { trace("cue point"); } } }

Para renomear os mtodos onMetaData() e onCuePoint() na classe CustomNetStream, use o seguinte cdigo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

479

package { import flash.net.NetConnection; import flash.net.NetStream; public class CustomNetStream extends NetStream { private var nc:NetConnection; public var onMetaData:Function; public var onCuePoint:Function; public function CustomNetStream() { onMetaData = metaDataHandler; onCuePoint = cuePointHandler; nc = new NetConnection(); nc.connect(null); super(nc); } private function metaDataHandler(infoObject:Object):void { trace("metadata"); } private function cuePointHandler(infoObject:Object):void { trace("cue point"); } } }

Estender a classe NetStream e torn-la dinmica

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior possvel estender a classe NetStream e tornar a subclasse dinmica para que os manipuladores de retorno de chamada onCuePoint e onMetaData possam ser adicionados dinamicamente. Isso demonstrado na listagem a seguir:
var ns:DynamicCustomNetStream = new DynamicCustomNetStream(); ns.play("video.flv"); var vid:Video = new Video(); vid.attachNetStream(ns); addChild(vid);

Esta a classe DynamicCustomNetStream:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

480

package { import flash.net.NetConnection; import flash.net.NetStream; public dynamic class DynamicCustomNetStream extends NetStream { private var nc:NetConnection; public function DynamicCustomNetStream() { nc = new NetConnection(); nc.connect(null); super(nc); } } }

Mesmo sem manipuladores para os manipuladores de retorno de chamada onMetaData e onCuePoint, no so gerados erros porque a classe DynamicCustomNetStream dinmica. Para definir mtodos para os manipuladores de retorno de chamada onMetaData e onCuePoint, use o seguinte cdigo:
var ns:DynamicCustomNetStream = new DynamicCustomNetStream(); ns.onMetaData = metaDataHandler; ns.onCuePoint = cuePointHandler; ns.play("http://www.helpexamples.com/flash/video/cuepoints.flv"); var vid:Video = new Video(); vid.attachNetStream(ns); addChild(vid); function metaDataHandler(infoObject:Object):void { trace("metadata"); } function cuePointHandler(infoObject:Object):void { trace("cue point"); }

Definir a propriedade client do objeto NetStream como this

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Quando se define a propriedade client como this, o aplicativo procura os mtodos onMetaData() e onCuePoint() no escopo atual. Este exemplo demonstra isso:
var nc:NetConnection = new NetConnection(); nc.connect(null); var ns:NetStream = new NetStream(nc); ns.client = this; ns.play("video.flv"); var vid:Video = new Video(); vid.attachNetStream(ns); addChild(vid);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

481

Se os manipuladores de retorno de chamada onMetaData ou onCuePoint so chamados e no existem mtodos para manipular o retorno de chamada, nenhum erro gerado. Para manipular esses manipuladores de retorno de chamada, crie um mtodo onMetaData() e onCuePoint() no seu cdigo, como visto no snippet abaixo:
function onMetaData(infoObject:Object):void { trace("metadata"); } function onCuePoint(infoObject:Object):void { trace("cue point"); }

Uso de pontos de sinalizao e metadados

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Use os mtodos de retorno de chamada NetStream para capturar e processar eventos de metadados e de ponto de sinalizao durante a reproduo do vdeo.

Uso de pontos de sinalizao

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A tabela a seguir descreve os mtodos de retorno de chamada que voc pode usar para capturar pontos de sinalizao F4V e FLV no Flash Player e no AIR.
Tempo de execuo Flash Player 9/AIR1.0 F4V FLV OnCuePoint OnMetaData Flash Player 10 OnMetaData OnXMPData OnCuePoint OnMetaData OnXMPData

O exemplo a seguir usa um loop for..in simples para se repetir em cada uma das propriedades do parmetro infoObject que a funo onCuePoint() recebe. Ele chama a funo trace() para exibir uma mensagem quando recebe dados de ponto de sinalizao:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

482

var nc:NetConnection = new NetConnection(); nc.connect(null); var ns:NetStream = new NetStream(nc); ns.client = this; ns.play("video.flv"); var vid:Video = new Video(); vid.attachNetStream(ns); addChild(vid); function onCuePoint(infoObject:Object):void { var key:String; for (key in infoObject) { trace(key + ": " + infoObject[key]); } }

Aparece a seguinte sada:

parameters: name: point1 time: 0.418 type: navigation

Este cdigo usa uma das vrias tcnicas para definir o objeto no qual executado o mtodo de retorno de chamada. Voc pode usar outras tcnicas; para obter mais informaes, consulte Criao de mtodos de retorno de chamada para metadados e pontos de sinalizao na pgina 475.

Uso de metadados de vdeo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior possvel usar as funes OnMetaData() e OnXMPData() para acessar as informaes de metadados do arquivo de vdeo, inclusive pontos de sinalizao.

Uso de OnMetaData()
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os metadados incluem informaes sobre o arquivo de vdeo, como durao, largura, altura e taxa de quadros. As informaes dos metadados que so adicionadas ao arquivo de vdeo dependem do software utilizado para codificar o arquivo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

483

var nc:NetConnection = new NetConnection(); nc.connect(null); var ns:NetStream = new NetStream(nc); ns.client = this; ns.play("video.flv"); var vid:Video = new Video(); vid.attachNetStream(ns); addChild(vid); function onMetaData(infoObject:Object):void { var key:String; for (key in infoObject) { trace(key + ": " + infoObject[key]); } }

O cdigo anterior gera uma sada parecida com esta:

width: 320 audiodelay: 0.038 canSeekToEnd: true height: 213 cuePoints: ,, audiodatarate: 96 duration: 16.334 videodatarate: 400 framerate: 15 videocodecid: 4 audiocodecid: 2

Se o seu vdeo no tem udio, as informaes de metadados relacionadas a udio (como audiodatarate) retornam undefined, pois nenhuma informao de udio adicionada aos metadados durante a codificao. No cdigo anterior, as informaes de ponto de sinalizao no eram exibidas. Para exibir os metadados de ponto de sinalizao, use esta funo, que exibe os itens recursivamente em um Object:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

484

function traceObject(obj:Object, indent:uint = 0):void { var indentString:String = ""; var i:uint; var prop:String; var val:*; for (i = 0; i < indent; i++) { indentString += "\t"; } for (prop in obj) { val = obj[prop]; if (typeof(val) == "object") { trace(indentString + " " + prop + ": [Object]"); traceObject(val, indent + 1); } else { trace(indentString + " " + prop + ": " + val); } } }

O uso do snippet de cdigo anterior para rastrear o parmetro infoObject no mtodo onMetaData() gera a seguinte sada:
width: 320 audiodatarate: 96 audiocodecid: 2 videocodecid: 4 videodatarate: 400 canSeekToEnd: true duration: 16.334 audiodelay: 0.038 height: 213 framerate: 15 cuePoints: [Object] 0: [Object] parameters: [Object] lights: beginning name: point1 time: 0.418 type: navigation 1: [Object] parameters: [Object] lights: middle name: point2 time: 7.748 type: navigation 2: [Object] parameters: [Object] lights: end name: point3 time: 16.02 type: navigation

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

485

O exemplo a seguir exibe os metadados de um vdeo MP4. Ele pressupe que existe um objeto TextArea chamado metaDataOut, no qual grava os metadados.
package { import import import import import import import import

flash.net.NetConnection; flash.net.NetStream; flash.events.NetStatusEvent; flash.media.Video; flash.display.StageDisplayState; flash.display.Loader; flash.display.Sprite; flash.events.MouseEvent;

public class onMetaDataExample extends Sprite { var video:Video = new Video(); public function onMetaDataExample():void { var videoConnection:NetConnection = new NetConnection(); videoConnection.connect(null); var videoStream:NetStream = new NetStream(videoConnection); videoStream.client = this; addChild(video); video.x = 185; video.y = 5; video.attachNetStream(videoStream); videoStream.play("video.mp4"); videoStream.addEventListener(NetStatusEvent.NET_STATUS, netStatusHandler); } public function onMetaData(infoObject:Object):void { for(var propName:String in infoObject) { metaDataOut.appendText(propName + "=" + infoObject[propName] + "\n"); } } private function netStatusHandler(event:NetStatusEvent):void { if(event.info.code == "NetStream.Play.Stop") stage.displayState = StageDisplayState.NORMAL; } } }

A funo onMetaData() gerou a seguinte sada para esse vdeo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

486

moovposition=731965 height=352 avclevel=21 videocodecid=avc1 duration=2.36 width=704 videoframerate=25 avcprofile=88 trackinfo=[object Object]

Uso do objeto de informao A tabela a seguir mostra os possveis valores para os metadados de vdeo que so passados funo de retorno de chamada onMetaData() no Object por eles recebido:
Parmetro aacaot avclevel avcprofile audiocodecid Descrio Tipo de objeto de udio AAC; so suportados os valores 0, 1 ou 2. Nmero de nvel AVC IDC, como 10, 11, 20, 21 e assim por diante. Nmero de perfil AVC, como 55, 77, 100 e assim por diante. String que indica o codec de udio (tcnica de codificao/decodificao) que foi usado; por exemplo .Mp3 ou mp4a Nmero que indica a taxa de codificao de udio, em KB por segundo. Nmero que indica em que tempo do arquivo FLV est "time 0" do arquivo FLV original. O contedo do vdeo precisa ter um pequeno atraso para que o udio seja sincronizado corretamente. Um valor booleano que true se o arquivo FLV est codificado com um quadro-chave no ltimo quadro, o que permite fazer a busca at o final de um arquivo de vdeo com download progressivo. falso se o arquivo FLV no est codificado com um quadro-chave no ltimo quadro. Uma matriz de objetos, uma para cada ponto de sinalizao incorporado no arquivo FLV. O valor indefinido se o arquivo FLV no contiver pontos de sinalizao. Cada objeto tem as seguintes propriedades:

audiodatarate audiodelay

canSeekToEnd

cuePoints

duration framerate height seekpoints

type: string que especifica o tipo do ponto de sinalizao como "navegao" ou "evento". name: string que o nome do ponto de sinalizao. time: nmero que a hora do ponto de sinalizao em segundos, com uma preciso de trs casas decimais (milsimos de segundo). parameters: objeto opcional que tem pares de nome/valor que o usurio designa ao criar os pontos de

sinalizao. Um nmero que representa a durao do arquivo de vdeo em segundos. Um nmero que representa a taxa de quadros do arquivo FLV. Um nmero que representa a altura do arquivo FLV em pixels. Uma matriz que lista os quadros-chave disponveis como carimbos de data/hora em milsimos de segundo. Opcional. Uma matriz de pares chave/valor que representam as informaes no ncleo ilst, que o equivalente de tags ID3 para arquivos MP4. O iTunes usa essas tags. Pode ser usado para exibir arte-final, se disponvel. Objeto que fornece informaes sobre todas as faixas do arquivo MP4, inclusive o ID de descrio da amostra. Uma string que representa a verso de codec que foi usada para codificar o vdeo. - por exemplo, avc1 ou VP6F

tags

trackinfo videocodecid

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

487

Parmetro videodatarate videoframerate width

Descrio Um nmero que representa a taxa de dados do vdeo do arquivo FLV. Taxa de quadros do vdeo MP4. Um nmero que representa a largura do arquivo FLV em pixels.

A tabela a seguir mostra os valores possveis para o parmetro videocodecid:

videocodecid 2 3 4 5 Nome do codec Sorenson H.263 Vdeo de tela (somente SWF verso 7 e posteriores) VP6 (somente SWF verso 8 e posteriores) Vdeo VP6 com canal alfa (somente SWF verso 8 e posteriores)

A tabela a seguir mostra os valores possveis para o parmetro audiocodecid:

audiocodecid 0 1 2 4 5 6 10 11 Nome do codec no compactado ADPCM Mp3 Nellymoser @ 16 kHz mono Nellymoser, 8 kHz mono Nellymoser AAC Speex

Uso de onXMPData()
Flash Player 10 e posterior, Adobe AIR 1.5 e posterior A funo de retorno de chamada onXMPData() recebe informaes especficas da plataforma XMP (Extensible Metadata Platform) da Adobe que so incorporadas ao arquivo de vdeo Adobe F4V ou FLV. Os metadados XMP incluem pontos de sinalizao e outros metadados de vdeo. O suporte para metadados XMP foi introduzido com o Flash Player 10 e o Adobe AIR 1.5 e suportado pelas verses subseqentes. Este exemplo processa dados de ponto de sinalizao nos metadados XMP:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

488

package { import import import import

flash.display.*; flash.net.*; flash.events.NetStatusEvent; flash.media.Video;

public class onXMPDataExample extends Sprite { public function onXMPDataExample():void { var videoConnection:NetConnection = new NetConnection(); videoConnection.connect(null); var videoStream:NetStream = new NetStream(videoConnection); videoStream.client = this; var video:Video = new Video(); addChild(video); video.attachNetStream(videoStream); videoStream.play("video.f4v"); } public function onMetaData(info:Object):void { trace("onMetaData fired"); } public function onXMPData(infoObject:Object):void { trace("onXMPData Fired\n"); //trace("raw XMP =\n"); //trace(infoObject.data); var cuePoints:Array = new Array(); var cuePoint:Object; var strFrameRate:String; var nTracksFrameRate:Number; var strTracks:String = ""; var onXMPXML = new XML(infoObject.data); // Set up namespaces to make referencing easier var xmpDM:Namespace = new Namespace("http://ns.adobe.com/xmp/1.0/DynamicMedia/"); var rdf:Namespace = new Namespace("http://www.w3.org/1999/02/22-rdf-syntax-ns#"); for each (var it:XML in onXMPXML..xmpDM::Tracks) {

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

489

var strTrackName:String = it.rdf::Bag.rdf::li.rdf::Description.@xmpDM::trackName; var strFrameRateXML:String = it.rdf::Bag.rdf::li.rdf::Description.@xmpDM::frameRate; strFrameRate = strFrameRateXML.substr(1,strFrameRateXML.length); nTracksFrameRate = Number(strFrameRate); strTracks += it; } var onXMPTracksXML:XML = new XML(strTracks); var strCuepoints:String = ""; for each (var item:XML in onXMPTracksXML..xmpDM::markers) { strCuepoints += item; } trace(strCuepoints); } } }

No caso de um arquivo de vdeo curto chamado startrekintro.f4v, este exemplo produz as linhas de rastreamento a seguir. As linhas mostram os dados de ponto de sinalizao referentes a pontos de sinalizao de navegao e de eventos nos metadados XMP:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

490

onMetaData fired onXMPData Fired <xmpDM:markers xmlns:xmp="http://ns.adobe.com/xap/1.0/" xmlns:xmpDM="http://ns.adobe.com/xmp/1.0/DynamicMedia/" xmlns:stDim="http://ns.adobe.com/xap/1.0/sType/Dimensions#" xmlns:xmpMM="http://ns.adobe.com/xap/1.0/mm/" xmlns:stEvt="http://ns.adobe.com/xap/1.0/sType/ResourceEvent#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdfsyntax-ns#" xmlns:x="adobe:ns:meta/"> <rdf:Seq> <rdf:li> <rdf:Description xmpDM:startTime="7695905817600" xmpDM:name="Title1" xmpDM:type="FLVCuePoint" xmpDM:cuePointType="Navigation"> <xmpDM:cuePointParams> <rdf:Seq> <rdf:li xmpDM:key="Title" xmpDM:value="Star Trek"/> <rdf:li xmpDM:key="Color" xmpDM:value="Blue"/> </rdf:Seq> </xmpDM:cuePointParams> </rdf:Description> </rdf:li> <rdf:li> <rdf:Description xmpDM:startTime="10289459980800" xmpDM:name="Title2" xmpDM:type="FLVCuePoint" xmpDM:cuePointType="Event"> <xmpDM:cuePointParams> <rdf:Seq> <rdf:li xmpDM:key="William Shatner" xmpDM:value="First Star"/> <rdf:li xmpDM:key="Color" xmpDM:value="Light Blue"/> </rdf:Seq> </xmpDM:cuePointParams> </rdf:Description> </rdf:li> </rdf:Seq> </xmpDM:markers> onMetaData fired

Nota: Nos dados XMP, o tempo armazenado como Tiques DVA e no como segundos. Para calcular o tempo do ponto de sinalizao, divida a hora inicial pela taxa de quadros. Por exemplo, a hora inicial de 7695905817600 dividida por uma taxa de quadros de 254016000000 igual a 30:30. Para ver os metadados XMP brutos completos, que incluem a taxa de quadros, remova os identificadores de comentrio (//s) que precedem a segunda e a terceira instrues trace() no incio da funo onXMPData(). Para obter mais informaes sobre a XMP, consulte:

partners.adobe.com/public/developer/xmp/topic.html www.adobe.com/devnet/xmp/

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

491

Uso de metadados de imagem

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O evento onImageData envia dados de imagem como uma matriz de bytes por um canal de dados AMF0. Os dados podem estar nos formatos JPEG, PNG ou GIF. Defina um mtodo de retorno de chamada onImageData() para processar essas informaes, da mesma forma que voc definiria mtodos de retorno de chamada para onCuePoint e onMetaData. Este exemplo acessa e exibe dados de imagem usando um mtodo de retorno de chamada onImageData():
public function onImageData(imageData:Object):void { // display track number trace(imageData.trackid); var loader:Loader = new Loader(); //imageData.data is a ByteArray object loader.loadBytes(imageData.data); addChild(loader); }

Uso de metadados de texto

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O evento onTextData envia dados de texto por meio de um canal de dados AMF0. Os dados de texto esto no formato UTF-8 e contm informaes adicionais sobre formatao com base na especificao de texto com tempo 3GP. Essa especificao define um formato de legenda padronizado. Defina um mtodo de retorno de chamada onTextData() para processar essas informaes, da mesma forma que voc definiria mtodos de retorno de chamada para onCuePoint ou onMetaData. No prximo exemplo, o mtodo onTextData() exibe o nmero de identificao da faixa e o texto da faixa correspondente.
public function onTextData(textData:Object):void { // display the track number trace(textData.trackid); // displays the text, which can be a null string, indicating old text // that should be erased trace(textData.text); }

Tpicos avanados sobre arquivos de vdeo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os tpicos a seguir abordam algumas questes especiais sobre o trabalho com arquivos FLV.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

492

Sobre a configurao de arquivos FLV para hospedagem em um servidor

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Quando voc trabalha com arquivos FLV, pode ser necessrio configurar o servidor para trabalhar com o formato de arquivo FLV. MIME (Multipurpose Internet Mail Extensions) uma especificao de dados padronizada que permite enviar arquivos no-ASCII por conexes de Internet. Navegadores da Web e clientes de e-mail so configurados para interpretar inmeros tipos MIME de maneira que possam enviar e receber vdeo, udio, grficos e texto formatado. Para carregar arquivos FLV de um servidor Web, talvez voc precise registrar a extenso de arquivo e o tipo MIME no servidor Web; para isso, consulte a documentao do servidor Web. O tipo MIME de arquivos FLV video/x-flv. As informaes completas sobre o tipo de arquivo FLV so as seguintes:

Tipo MIME: video/x-flv Extenso de arquivo: .flv Parmetros necessrios: nenhum Parmetros opcionais: nenhum Consideraes de codificao: os arquivos FLV so binrios; alguns aplicativos podem exigir que o subtipo
application/octet-stream seja definido

Problemas de segurana: nenhum Especificao publicada: www.adobe.com/go/video_file_format_br

A Microsoft mudou a forma de tratamento de fluxos de mdia no servidor Web Microsoft Internet Information Services (IIS) 6.0 em relao a verses anteriores. As verses anteriores do IIS no exigem modificaes para transmitir vdeo Flash em fluxo. No IIS 6.0, o servidor Web padro fornecido com o Windows 2003, o servidor requer um tipo MIME para reconhecer que os arquivos FLV so fluxo de mdia. Quando arquivos SWF que transmitem arquivos FLV externos em fluxo contnuo so colocados no Microsoft Windows Server 2003 e visualizados em um navegador, o arquivo SWF reproduzido corretamente, mas o vdeo FLV no transmitido em fluxo contnuo. Este problema afeta todos os arquivos FLV colocados no Windows Server 2003, inclusive os arquivos criados com verses anteriores da Ferramenta de autoria do Flash e com o Macromedia Flash Video Kit para Dreamweaver MX 2004 da Adobe. Esses arquivos funcionaro corretamente se voc test-los em outros sistemas operacionais. Para obter informaes sobre como configurar o Microsoft Windows 2003 e o Microsoft IIS Server 6.0 para transmisso de vdeos FLV em fluxo contnuo, consulte www.adobe.com/go/tn_19439_br.

Sobre direcionamento de arquivos FLV locais no Macintosh

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Se voc tentar reproduzir um arquivo FLV local de uma unidade que no do sistema em um computador com o Apple Macintosh usando um caminho que contm uma barra relativa (/), o vdeo no ser reproduzido. Unidades que no so do sistema incluem mas no se limitam a CD-ROMs, discos rgidos particionados, mdia de armazenamento removveis e dispositivos de armazenamento conectados. Nota: O motivo desta falha uma limitao do sistema operacional e no do Flash Player ou do AIR. Para que um arquivo FLV seja reproduzido de uma unidade que no do sistema em um Macintosh, faa referncia a ela com um caminho absoluto usando uma notao baseada em dois pontos (:) em vez de barra (/). A lista a seguir mostra a diferena entre os dois tipos de notao:

Notao baseada em barra: myDrive/myFolder/myFLV.flv

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

493

Notao baseada em dois pontos: (Mac OS) myDrive:myFolder:myFLV.flv

Exemplo de vdeo: jukebox de vdeo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O exemplo a seguir cria uma jukebox de vdeo simples que carrega uma lista de vdeos dinamicamente para reproduo em seqncia. Isso permite que voc crie um aplicativo com o qual um usurio pode navegar por uma srie de tutoriais em vdeo ou talvez especificar quais anncios devem ser reproduzidos antes de reproduzir o vdeo solicitado pelo usurio. Este exemplo mostra os seguintes recursos do ActionScript 3.0:

Atualizao de um indicador de reproduo com base no progresso da reproduo de um arquivo de vdeo Monitoramento e anlise dos metadados de um arquivo de vdeo Manipulao de cdigos especficos em um fluxo de rede Carregamento, reproduo, pausa e interrupo de um FLV carregado dinamicamente Redimensionamento de um objeto de vdeo na lista de exibio com base nos metadados do fluxo de rede
Para obter os arquivos de aplicativo deste exemplo, consulte www.adobe.com/go/learn_programmingAS3samples_flash_br. Os arquivos do aplicativo Jukebox de vdeo podem ser encontrados na pasta Samples/VideoJukebox. O aplicativo consiste nos seguintes arquivos:
Arquivo VideoJukebox.fla ou VideoJukebox.mxml VideoJukebox.as playlist.xml A classe que fornece a funcionalidade principal do aplicativo. Um arquivo que lista quais arquivos de vdeo sero carregados na jukebox de vdeo. Descrio O arquivo principal do aplicativo para Flex (MXML) ou Flash (FLA).

Carregamento de um arquivo externo de lista de reproduo de vdeo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O arquivo externo playlist.xml especifica os vdeos que devem ser carregados e a ordem em que sero reproduzidos. Para carregar o arquivo XML, voc precisa usar um objeto URLLoader e um objeto URLRequest, como visto neste cdigo:
uldr = new URLLoader(); uldr.addEventListener(Event.COMPLETE, xmlCompleteHandler); uldr.load(new URLRequest(PLAYLIST_XML_URL));

Este cdigo colocado no construtor da classe VideoJukebox para que o arquivo seja carregado antes da execuo de qualquer outro cdigo. Assim que termina o carregamento do arquivo XML, chamado o mtodo xmlCompleteHandler(), que analisa o arquivo externo em um objeto XML, como visto neste cdigo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

494

private function xmlCompleteHandler(event:Event):void { playlist = XML(event.target.data); videosXML = playlist.video; main(); }

O objeto XML playlist contm o XML bruto do arquivo externo, enquanto o XML do vdeo um objeto XMLList que contm apenas os ns de vdeo. Um arquivo playlist.xml de exemplo pode ser visto no seguinte snippet:
<videos> <video url="video/caption_video.flv" /> <video url="video/cuepoints.flv" /> <video url="video/water.flv" /> </videos>

Para finalizar, o mtodo xmlCompleteHandler() chama o mtodo main(), que configura as vrias ocorrncias de componente na lista de exibio, bem como os objetos NetConnection e NetStream que so usados para carregar os arquivos FLV externos.

Criao da interface de usurio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para criar a interface de usurio, voc precisa arrastar cinco ocorrncias de Button at a lista de exibio e dar a elas os seguintes nomes de ocorrncia: playButton, pauseButton, stopButton, backButton e forwardButton. Para cada uma dessas ocorrncias de Button, voc ter de atribuir um manipulador para o evento click, como visto no seguinte snippet:
playButton.addEventListener(MouseEvent.CLICK, buttonClickHandler); pauseButton.addEventListener(MouseEvent.CLICK, buttonClickHandler); stopButton.addEventListener(MouseEvent.CLICK, buttonClickHandler); backButton.addEventListener(MouseEvent.CLICK, buttonClickHandler); forwardButton.addEventListener(MouseEvent.CLICK, buttonClickHandler);

O mtodo buttonClickHandler() usa uma instruo de opo para determinar qual ocorrncia de Button foi clicada, como visto neste cdigo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

495

private function buttonClickHandler(event:MouseEvent):void { switch (event.currentTarget) { case playButton: ns.resume(); break; case pauseButton: ns.togglePause(); break; case stopButton: ns.pause(); ns.seek(0); break; case backButton: playPreviousVideo(); break; case forwardButton: playNextVideo(); break; } }

Em seguida, adicione uma ocorrncia de Slider lista de exibio e d a ela um nome de ocorrncia de volumeSlider. O seguinte cdigo define a propriedade liveDragging da ocorrncia de Slider como true e um ouvinte de eventos para o evento change da ocorrncia de Slider:
volumeSlider.value = volumeTransform.volume; volumeSlider.minimum = 0; volumeSlider.maximum = 1; volumeSlider.snapInterval = 0.1; volumeSlider.tickInterval = volumeSlider.snapInterval; volumeSlider.liveDragging = true; volumeSlider.addEventListener(SliderEvent.CHANGE, volumeChangeHandler);

Adicione uma ocorrncia de ProgressBar lista de exibio e d a ela um nome de ocorrncia de positionBar. Defina a propriedade mode como manual, conforme visto no seguinte snippet:
positionBar.mode = ProgressBarMode.MANUAL;

Para terminar, adicione uma ocorrncia de Label lista de exibio e d a ela um nome de ocorrncia de positionLabel. O valor dessa ocorrncia de Label ser definido pela ocorrncia de Timer.

Monitoramento dos metadados de um objeto de vdeo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Quando o Flash Player encontra metadados de cada um dos vdeos carregados, o manipulador de retorno de chamada onMetaData() chamado na propriedade client do objeto NetStream. O seguinte cdigo inicializa um Object e configura o manipulador de retorno de chamada especificado:
client = new Object(); client.onMetaData = metadataHandler;

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

496

O mtodo metadataHandler() copia seus dados para a propriedade meta definida anteriormente no cdigo. Isso permite que voc acesse os metadados do vdeo atual a qualquer momento em todo o aplicativo. Em seguida, o objeto de vdeo no Palco redimensionado para corresponder s dimenses retornadas nos metadados. Por ltimo, a ocorrncia da barra de progresso positionBar movida e redimensionada com base no tamanho do vdeo que est sendo reproduzido. O seguinte cdigo contm o mtodo metadataHandler() inteiro:
private function metadataHandler(metadataObj:Object):void { meta = metadataObj; vid.width = meta.width; vid.height = meta.height; positionBar.move(vid.x, vid.y + vid.height); positionBar.width = vid.width; }

Carregamento dinmico de um vdeo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para carregar cada um dos vdeos dinamicamente, o aplicativo usa um objeto NetConnection e NetStream. O cdigo a seguir cria um objeto NetConnection e passa null para o mtodo connect(). Especificando null, o Flash Player se conecta a um vdeo do servidor local em vez de se conectar a um servidor, como o Flash Media Server. O seguinte cdigo cria ocorrncias de NetConnection e de NetStream, define um ouvinte de eventos para o evento netStatus e atribui Object client propriedade client:
nc = new NetConnection(); nc.connect(null); ns = new NetStream(nc); ns.addEventListener(NetStatusEvent.NET_STATUS, netStatusHandler); ns.client = client;

O mtodo netStatusHandler() chamado sempre que o status do vdeo alterado. Isso inclui as ocasies em que a reproduo de um vdeo iniciada ou interrompida, quando o vdeo armazenado em buffer ou quando um fluxo de vdeo no encontrado. O seguinte cdigo lista o evento netStatusHandler():

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

497

private function netStatusHandler(event:NetStatusEvent):void { try { switch (event.info.code) { case "NetStream.Play.Start": t.start(); break; case "NetStream.Play.StreamNotFound": case "NetStream.Play.Stop": t.stop(); playNextVideo(); break; } } catch (error:TypeError) { // Ignore any errors. } }

O cdigo anterior avalia a propriedade de cdigo do objeto de informaes e filtra se o cdigo NetStream.Play.Start, NetStream.Play.StreamNotFound ou NetStream.Play.Stop. Todos os demais cdigos sero ignorados. Se o fluxo de rede estiver iniciando, o cdigo iniciar a ocorrncia de Timer que atualiza o indicador de reproduo. Se o fluxo de rede no for encontrado ou se for interrompido, a ocorrncia de Timer ser interrompida e o aplicativo tentar reproduzir o prximo vdeo da lista de reproduo. Sempre que Timer executado, a ocorrncia da barra de progresso positionBar atualiza sua posio atual chamando o mtodo setProgress() da classe ProgressBar, e a ocorrncia de Label positionLabel atualizada com o tempo decorrido e o total de tempo do vdeo atual.
private function timerHandler(event:TimerEvent):void { try { positionBar.setProgress(ns.time, meta.duration); positionLabel.text = ns.time.toFixed(1) + " of " meta.duration.toFixed(1) + " seconds"; } catch (error:Error) { // Ignore this error. } }

Controle do volume do vdeo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior possvel controlar o volume do vdeo carregado dinamicamente definindo a propriedade soundTransform no objeto NetStream. O aplicativo de jukebox de vdeo permite modificar o nvel de volume alterando o valor da ocorrncia de Slider volumeSlider. Este cdigo mostra como alterar o nvel de volume atribuindo o valor do componente Slider a um objeto SoundTransform, que definido com a propriedade soundTransform no objeto NetStream:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

498

private function volumeChangeHandler(event:SliderEvent):void { volumeTransform.volume = event.value; ns.soundTransform = volumeTransform; }

Controle da reproduo de vdeo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O restante do aplicativo controla a reproduo de vdeos quando o vdeo chega ao final do fluxo ou quando o usurio acessa o vdeo anterior ou o prximo. O seguinte mtodo recupera a URL do vdeo no objeto XMLList relativo ao ndice que est selecionado:
private function getVideo():String { return videosXML[idx].@url; }

O mtodo playVideo() chama o mtodo play() no objeto NetStream para carregar o vdeo que est selecionado:
private function playVideo():void { var url:String = getVideo(); ns.play(url); }

O mtodo playPreviousVideo() reduz o ndice de vdeos atual, chama o mtodo playVideo() para carregar o novo arquivo de vdeo e define a barra de progresso como visvel:
private function playPreviousVideo():void { if (idx > 0) { idx--; playVideo(); positionBar.visible = true; } }

O ltimo mtodo, playNextVideo(), aumenta o ndice de vdeos e chama o mtodo playVideo(). Se o vdeo atual o ltimo da lista de reproduo, o mtodo clear() chamado no objeto Video, e a propriedade visible da ocorrncia da barra de progresso definida como false:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

499

private function playNextVideo():void { if (idx < (videosXML.length() - 1)) { idx++; playVideo(); positionBar.visible = true; } else { idx++; vid.clear(); positionBar.visible = false; } }

Utilizando a classe StageVideo para renderizao acelerada por hardware

Flash Player 10.2 e posterior, Adobe AIR for TV 2.5 e posterior Flash Player otimiza o desempenho de vdeo utilizando a acelerao por hardware para decodificao de H.264. possvel melhorar ainda mais o desempenho utilizando a API StageVideo. Stage Video permite que sua aplicao aproveite a renderizao acelerada por hardware. Tempos de execuo compatveis com a API StageVideo incluem:

Flash Player 10.2 e posterior Adobe AIR 2.5 for TV e posterior

O Adobe AIR for TV 2.5 e o Adobe Flash Player Beta for Google TV oferecem suporte ao vdeo do palco por meio de um subconjunto da API completa. Nessas plataformas aplicam-se diferenas de configurao e restries adicionais. Para obter instrues sobre o uso do vdeo do palco nessas plataformas, consulte Entrega de vdeo e contedo para a plataforma Flash na TV. O cdigo-fonte disponvel para download e detalhes adicionais do recurso de vdeo do palco esto disponveis em Introduo ao Stage Video. Para um tutorial rpido de incio do StageVideo, consulte Trabalhando com o Stage Video.

Sobre acelerao por hardware usando StageVideo

A classe Video normalmente usa renderizao por software. A renderizao por software ocorre na CPU do dispositivo e pode consumir uma parcela significativa dos recursos do sistema. Em dispositivos que oferecem acelerao da GPU (por hardware), voc pode usar um objeto flash.media.StageVideo para renderizar vdeo diretamente no hardware do dispositivo. A renderizao direta libera a CPU para realizar outras tarefas enquanto a GPU renderiza o vdeo. A renderizao acelerada por hardware aumenta os benefcios de desempenho da decodificao acelerada por hardware. Atualmente poucos dispositivos oferecem acelerao completa de GPU. Contudo, o vdeo do palco permite aos aplicativos aproveitar ao mximo qualquer acelerao por hardware disponvel.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

500

A classe StageVideo no torna a classe Video obsoleta. Funcionando juntas, essas duas classes proporcionam a experincia de exibio de vdeo otimizada permitida pelos recursos do dispositivo a qualquer momento especfico. Seu aplicativo aproveita a acelerao de hardware ouvindo os eventos apropriados e alternando entre StageVideo e Video, conforme necessrio. A classe StageVideo impe certas restries sobre o uso de vdeo. Antes de implementar StageVideo, reveja as orientaes e verifique se sua aplicao pode aceit-lo. Se voc aceitar as restries, use a classe StageVideo sempre que o Flash Player detectar que a renderizao acelerada por hardware est disponvel. Consulte Orientaes e limitaes na pgina 501.

Planos paralelos: lista de exibio do Flash e Stage Video

Com o modelo de vdeo do palco, o Flash Player pode separar o vdeo da lista de exibio. O Flash Player divide o visor composto entre dois planos ordenados Z:
Plano do vdeo do palco O plano do vdeo do palco fica em segundo plano. Ele exibe somente vdeo acelerado por hardware. Devido a esse design, esse plano no fica disponvel se a acelerao por hardware no for compatvel ou no estiver disponvel no dispositivo. No ActionScript, objetos StageVideo manipulam vdeos reproduzidos no plano de vdeo do palco. Plano de lista de exibio Flash As entidades da lista de exibio Flash so compostas em um plano na frente do plano do vdeo do palco. As entidades da lista de exibio incluem qualquer coisa que o tempo de execuo renderizar, inclusive controles de reproduo. Quando a acelerao de hardware no est disponvel, vdeos podem ser reproduzidos somente nesse plano, usando o objeto da classe Video. O vdeo do palco sempre exibido atrs dos grficos da lista de exibio Flash.

do no Pla

lco pa do eo vd o1

U) GP la pe do era el (ac s ro ut os O c fi gr Flash em U) CP te en m (so

e Vd

1 les tro on C

s2 ole r 2 nt eo Co sh Vd Fla o ibi ex de ta Lis

Planos de exibio de vdeo

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

501

O objeto StageVideo exibido em uma regio no rotacionada e retangular da tela alinhada com a janela. Voc no pode estender em camadas objetos atrs do plano de vdeo do palco. Contudo, possvel usar o plano de lista de exibio do Flash para criar camadas com outros grficos sobre o objeto de vdeo do palco. O vdeo do palco executado simultaneamente com a lista de exibio do Assim, voc pode usar os dois mecanismos juntos para criar um efeito visual unificado que usa dois planos discretos. Por exemplo, pode usar o plano frontal para os controles de reproduo que operam no vdeo do palco em execuo em segundo plano.

Vdeo do palco e codec H.264

Em aplicativos Flash Player, a implementao da acelerao por hardware de vdeo envolve duas etapas:
1 Codificao do vdeo como H.264 2 Implementao da API StageVideo

Para melhores resultados, realize as duas etapas. O codec H.264 permite que voc aproveite a acelerao por hardware no dispositivo de destino, a partir da decodificao de vdeo para a renderizao. O vdeo do palco elimina a releitura de GPU para GPU. Em outras palavras, a GPU no envia frames decodificados de volta para a CPU para composio com objetos da lista de exibio. Em vez disso, a GPU imprime diretamente na tela frames decodificados e renderizados, trs dos objetos da lista de exibio. Esta tcnica reduz o uso de memria e CPU e tambm proporciona uma melhor fidelidade de pixel.

Mais tpicos da Ajuda

Noes bsicas sobre formatos de vdeo na pgina 463

Orientaes e limitaes
Quando o vdeo executado no modo de tela cheia, o vdeo do palco est sempre disponvel se o dispositivo for compatvel com acelerao por hardware. O Flash Player, no entanto, tambm executado dentro de um navegador. No contexto de navegador, a configurao wmode afeta a disponibilidade do vdeo do palco. Tente usar sempre wmode="direct" se desejar usar o vdeo do palco. O vdeo do palco no compatvel com outras configuraes wmode quando o modo de tela cheia no usado. Essa restrio significa que, no tempo de execuo, o vdeo do palco pode vacilar de maneira imprevisvel entre estar ou no disponvel. Por exemplo, se o usurio sair do modo de tela cheia enquanto o vdeo estiver em execuo, o contexto de vdeo inverter para o navegador. Se o parmetro wmode do navegador no for definido como "direct", o vdeo do palco pode ficar indisponvel subitamente. O Flash Player comunica alteraes de contexto de reproduo para aplicativos atravs de um conjunto de eventos. Se voc implementar a API StageVideo, mantenha um objeto de vdeo como backup quando o vdeo do palco ficar indisponvel. Por causa dessa relao direta com o hardware, o vdeo do palco restringe alguns recursos de vdeo. O vdeo do palco refora as seguintes restries:

Para cada arquivo SWF, o Flash Player limita a quatro o nmero de objetos StageVideo que podem exibir vdeo
simultaneamente. Entretanto, o limite real pode ser mais baixo, dependendo dos recursos de hardware no dispositivo. Em dispositivos AIR for TV e para a maioria dos dispositivos mveis, apenas um objeto StageVideo pode exibir vdeo de cada vez.

A temporizao do vdeo no sincronizada com a temporizao do contedo exibido pelo tempo de execuo. A rea de exibio de vdeo pode ser somente um retngulo. No possvel usar reas de exibio mais avanadas,
como formas elpticas ou irregulares.

No possvel girar o vdeo. No possvel armazenar o vdeo no cache de bitmap nem usar um objeto BitmapData para acess-lo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

502

No possvel aplicar filtros ao vdeo. No possvel aplicar transformaes de cores ao vdeo. No possvel aplicar um valor alfa ao vdeo. Os modos de combinao que voc aplica a objetos no plano da lista de exibio no se aplicam ao vdeo do palco. possvel posicionar o vdeo somente em limites de pixel cheios. Embora a renderizao da GPU seja a melhor disponvel para o hardware de dispositivo especfico, ela no 100%
idntica em termos de pixel em todos os dispositivos. Ligeiras variaes ocorrem devido a diferenas de driver e de plataforma.

Alguns dispositivos no oferecem suporte a todos os espaos de cor necessrios. Por exemplo, alguns dispositivos
no oferecem suporte a BT.709, o padro H.264. Nesses casos, voc pode usar o BT.601 para acelerar a exibio.

No possvel usar o vdeo do palco com configuraes WMODE, como normal, opaque ou transparent. O vdeo
do palco oferece suporte apenas a WMODE=direct quando no est no modo de tela cheia. O WMODE no tem nenhum efeito no Safari 4 ou superior, no IE 9 ou superior, nem no AIR for TV. Na maioria dos casos, essas limitaes no afetam aplicativos de player de vdeo. Se puder aceitar estas limitaes, use o vdeo do palco sempre que possvel.

Mais tpicos da Ajuda

Trabalho com o modo de tela cheia na pgina 161

Uso das APIs StageVideo

O vdeo do palco um mecanismo no tempo de execuo que melhora a reproduo do vdeo e o desempenho do dispositivo. O tempo de execuo cria e mantm esse mecanismo. Como desenvolvedor, sua funo configurar seu aplicativo de modo a aproveit-lo. Para usar o vdeo do palco, implemente uma estrutura de manipuladores de eventos que detecte quando o vdeo do palco est ou no disponvel. Quando voc receber uma notificao de que o vdeo do palco est disponvel, recupere um objeto StageVideo da propriedade Stage.stageVideos. O tempo de execuo preenche esse objeto Vector com um ou mais objetos StageVideo. Em seguida, voc pode usar um dos objetos StageVideo fornecidos, em vez de um objeto Video, para exibir o fluxo de vdeo. No Flash Player, quando receber uma notificao de que o vdeo do palco no est mais disponvel, alterne seu fluxo de vdeo de volta para um objeto Video. Esta etapa no se aplica aos aplicativos AIR 2.5 for TV. Nota: No possvel criar objetos StageVideo.

Propriedade Stage.stageVideos
A propriedade Stage.stageVideos um objeto Vector que proporciona acesso a ocorrncias de StageVideo. Esse vetor pode conter at quatro objetos StageVideo, dependendo do hardware e dos recursos do sistema. Os dispositivos AIR for TV so limitados a uma nica instncia StageVideo. Dispositivos mveis podem estar limitados a um ou nenhum. Quando o vdeo do palco no est diponvel, este vetor no contm nenhum objeto. Para evitar erros no tempo de execuo, certifique-se de acessar membros desse vetor somente quando o evento StageVideoAvailability mais recente indicar a disponibilidade do vdeo do palco.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

503

Eventos StageVideo
A estrutura da API StageVideo fornece os seguintes eventos:
StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY (Sem suporte para AIR 2.5 for TV) Enviado quando a

propriedade Stage.stageVideos alterada. A propriedade StageVideoAvailabilityEvent.availability indica se AVAILABLE (disponvel) ou UNAVAILABLE (no disponvel). Use este evento para determinar se a propriedade stageVideos contm algum objeto StageVideo, em vez de verificar diretamente o comprimento do vetor Stage.stageVideos.
StageVideoEvent.RENDER_STATE Enviado quando um objeto NetStream tiver sido anexado a um objeto StageVideo

e estiver em reproduo. Indica o tipo de decodificao em uso atualmente: hardware, software ou indisponvel (nada exibido). O destino do evento contm as propriedades videoWidth e videoHeightque so seguras para serem usadas para redimensionar a janela de exibio de vdeo. Importante: As coordenadas obtidas a partir do objeto de destino StageVideo usam as coordenadas Stage visto que no fazem parte da lista de exibio padro.
VideoEvent.RENDER_STATE (Sem suporte em AIR 2.5 for TV) Enviado quando um objeto Video est em uso. Indica se a decodificao acelerada por hardware ou software est em uso. Se este evento indicar a decodificao acelerada por hardware, alterne para um objeto StageVideo, se possvel. O destino do evento Video contm as propriedades videoWidth e videoHeightque so seguras para serem usadas para redimensionar a janela de exibio de vdeo.

Fluxo de trabalho para implementar o recurso StageVideo

Siga estas etapas de nvel superior para implementar o recurso StageVideo:
1 Escute o evento StageVideoAvailabilityEvent. STAGE_VIDEO_AVAILABILITY para descobrir quando
o vetor Stage.stageVideos foi alterado. Consulte Utilizando o evento StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY na pgina 504. (No suportado pelo AIR 2.5 para televiso.)

2 Se o evento StageVideoAvailabilityEvent. STAGE_VIDEO_AVAILABILITY informar que o vdeo de palco est

disponvel, use o objeto Vector Stage.stageVideos do manipulador de eventos para acessar um objeto StageVideo. No AIR 2.5 para televiso, acesse Stage.stageVideos depois que o primeiro quadro SWF for renderizado.
3 Anexe um objeto NetStream usando StageVideo.attachNetStream(). 4 Reproduza o vdeo usando NetStream.play(). 5 Escute o evento StageVideoEvent.RENDER_STATE no objeto StageVideo para determinar o status da reproduo

do vdeo. O recebimento deste evento tambm indica que as propriedades de largura e de altura do vdeo foram inicializadas ou alteradas. Consulte Utilizando os eventos StageVideoEvent.RENDER_STATE e VideoEvent.RENDER_STATE na pgina 506.
6 Escute o evento VideoEvent. RENDER_STATE no objeto Video. Este evento fornece os mesmos status que
StageVideoEvent. RENDER_STATE; portanto, voc tambm pode us-lo para determinar se a acelerao de GPU est disponvel. O recebimento deste evento tambm indica que as propriedades de

largura e de altura do vdeo foram inicializadas ou alteradas. (No suportado pelo AIR 2.5 para televiso.) Consulte Utilizando os eventos StageVideoEvent.RENDER_STATE e VideoEvent.RENDER_STATE na pgina 506.

Inicializando os ouvintes de evento do StageVideo

Configure seus ouvintes StageVideoAvailabilityEvent e VideoEvent durante a inicializao do aplicativo. Por exemplo, voc pode inicializar esses ouvintes no manipulador de eventos flash.events.Event.ADDED_TO_STAGE. Este evento garante que seu aplicativo fique visvel no palco:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

504

public class SimpleStageVideo extends Sprite private var nc:NetConnection; private var ns:NetStream; public function SimpleStageVideo() { // Constructor for SimpleStageVideo class // Make sure the app is visible and stage available addEventListener(Event.ADDED_TO_STAGE, onAddedToStage); } private function onAddedToStage(event:Event):void { //... // Connections nc = new NetConnection(); nc.connect(null); ns = new NetStream(nc); ns.addEventListener(NetStatusEvent.NET_STATUS, onNetStatus); ns.client = this; // Screen video = new Video(); video.smoothing = true; // Video Events // the StageVideoEvent.STAGE_VIDEO_STATE informs you whether // StageVideo is available stage.addEventListener(StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY, onStageVideoState); // in case of fallback to Video, listen to the VideoEvent.RENDER_STATE // event to handle resize properly and know about the acceleration mode running video.addEventListener(VideoEvent.RENDER_STATE, videoStateChange); //... }

Utilizando o evento StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY

No manipulador StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY, decida se deve usar um objeto Video ou StageVideo, com base na disponibilidade de StageVideo. Se a propriedade StageVideoAvailabilityEvent.availability estiver definida como StageVideoAvailability.AVAILABLE, use StageVideo. Nesse caso, voc pode contar com o vetor Stage.stageVideos para conter um ou mais objetos StageVideo. Obtenha um objeto StageVideo da propriedade Stage.stageVideos e anexe o objeto NetStream para esse. Porque os objetos StageVideo sempre aparecem no fundo, remova o objeto Video existente (sempre em primeiro plano). Aproveite este manipulador do evento para adicionar um ouvinte para o evento StageVideoEvent.RENDER_STATE. Se a propriedade StageVideoAvailabilityEvent.availability estiver definida como StageVideoAvailability.UNAVAILABLE, no use o StageVideo nem acesse o vetor Stage.stageVideos. Neste caso, anexe o objeto NetStream para um objeto de Video. Finalmente, adicione o objeto StageVideo ou Video ao palco e chame NetStream.play(). O cdigo a seguir mostra como manipular o evento
StageVideoAvailabilityEvent.STAGE_VIDEO_AVAILABILITY:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

505

private var sv:StageVideo; private var video:Video; private function onStageVideoState(event:StageVideoAvailabilityEvent):void { // Detect if StageVideo is available and decide what to do in toggleStageVideo toggleStageVideo(event.availability == StageVideoAvailability.AVAILABLE); } private function toggleStageVideo(on:Boolean):void { // To choose StageVideo attach the NetStream to StageVideo if (on) { stageVideoInUse = true; if ( sv == null ) { sv = stage.stageVideos[0]; sv.addEventListener(StageVideoEvent.RENDER_STATE, stageVideoStateChange); sv.attachNetStream(ns); } if (classicVideoInUse) { // If you use StageVideo, remove from the display list the // Video object to avoid covering the StageVideo object // (which is always in the background) stage.removeChild ( video ); classicVideoInUse = false; } } else { // Otherwise attach it to a Video object if (stageVideoInUse) stageVideoInUse = false; classicVideoInUse = true; video.attachNetStream(ns); stage.addChildAt(video, 0); } if ( !played ) { played = true; ns.play(FILE_NAME); } }

Importante: A primeira vez que um aplicativo acessa o elemento do vetor em Stage.stageVideos[0], o retngulo padro configurado para 0,0,0,0, e as propriedades pan e zoom usam os valores padro. Sempre definir esses valores para suas configuraes de preferncia. possvel usar as propriedades videoWidth e videoHeight do destino dos eventos StageVideoEvent.RENDER_STATE ou VideoEvent.RENDER_STATE para calcular as dimenses da janela de exibio de vdeo. Baixe todo o cdigo-fonte deste exemplo de aplicativo de Introduo ao vdeo do palco.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

506

Utilizando os eventos StageVideoEvent.RENDER_STATE e VideoEvent.RENDER_STATE

Os objetos StageVideo e Video enviam eventos que informam aos aplicativos quando o ambiente de renderizao alterado. Estes eventos so StageVideoEvent.RENDER_STATE e VideoEvent.RENDER_STATE. Um objeto StageVideo ou Vdeo envia um evento de estado renderizado quando um objeto NetStream anexado e comea a ser reproduzido. Tambm envia esse evento quando o ambiente de renderizao alterado; por exemplo, quando a janela de exibio de vdeo redimensionada. Use essas notificaes para redefinir sua janela de exibio para os valores videoHeight e videoWidth atuais do objeto de destino do evento. Os estados renderizados informados incluem:

RENDER_STATUS_UNAVAILABLE RENDER_STATUS_SOFTWARE RENDER_STATUS_ACCELERATED

Estados renderizados indicam quando a decodificao acelerada por hardware est em uso, independentemente da classe que esteja atualmente reproduzindo o vdeo. Marque a propriedade StageVideoEvent.status para saber se a decodificao necessria est disponvel. Se essa propriedade estiver definida como "indisponvel", o objeto StageVideo no pode reproduzir o vdeo. Este estado exige que voc coloque imediatamente de novo o objeto NetStream para um objeto Video. Outros estados informam para seu aplicativo as condies de renderizao atuais. A tabela a seguir descreve as implicaes de todos os valores do estado de renderizao para objetos StageVideoEvent e VideoEvent em Flash Player:
VideoStatus.ACCELERATED StageVideoEvent A renderizao e a decodificao ocorrem no hardware. (Melhor desempenho.) VideoEvent Renderizao em software, decodificao em hardware. (Desempenho aceitvel apenas em um sistema moderno de desktop. Desempenho degradado em tela cheia.) VideoStatus.SOFTWARE VideoStatus.UNAVAILABLE

Renderizao em hardware, No esto disponveis recursos decodificao em software. da GPU para renderizar o vdeo, (Desempenho aceitvel.) e nada exibido. Retroceder para um objeto Video. Renderizao em software, decodificao em software. (Pior em termos de desempenho de caixa. Desempenho degradado em tela cheia) (N/D)

Nota: O AIR 2.5 for TV no define a classe VideoStatus e no decodifica H.264 em software. Consulte classe StageVideoEvent em Referncia ActionScript 3 para obter detalhes sobre implementao de evento AIR 2.5 for TV.

Espaos de cor
O vdeo do palco usa recursos de hardware subjacentes para oferecer suporte a espaos de cor. O contedo SWF pode fornecer metadados que indicam seu espao de cor preferencial. No entanto, o hardware grfico do dispositivo determina se o espao de cor pode ser usado. Um dispositivo pode oferecer suporte a vrios espaos de cor, enquanto outros no oferecem a nenhum. Se o hardware no oferecer suporte ao espao de cor necessrio, o Flash Player tenta localizar a correspondncia mais prxima entre os espaos de cor com suporte. Para consultar a quais espaos de cor o hardware oferece suporte, use a propriedade StageVideo.colorSpaces. Essa propriedade retorna a lista de espaos de cor com suporte em um vetor String:
var colorSpace:Vector.<String> = stageVideo.colorSpaces();

Para saber qual espao de cor o vdeo em reproduo no momento est usando, verifique a propriedade StageVideoEvent.colorSpace. Verifique essa propriedade em seu manipulador de eventos quanto ao evento StageVideoEvent.RENDER_STATE:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com vdeo

507

var currColorSpace:String; //StageVideoEvent.RENDER_STATE event handler private function stageVideoRenderState(event:Object):void { //... currColorSpace = (event as StageVideoEvent).colorSpace; //... }

Se o Flash Player no encontrar um substituto para o espao de cor incompatvel, o vdeo do palco usar o espao de cor padro BT.601. Por exemplo, fluxos de vdeo com codificao H.264 normalmente usam o espao de cor BT.709. Se o hardware do dispositivo no oferecer suporte a BT.709, a propriedade colorSpace retornar "BT601". O valor "unknown" de StageVideoEvent.colorSpace indica que o hardware no oferece nenhum modo de consultar o espao de cor. Nota: No AIR 2.5 for TV, StageVideo no oferece suporte a espaos de cor. A propriedade StageVideoEvent.colorSpace nessa plataforma retorna BT709 para indicar renderizao por hardware ou BT601 para indicar renderizao por software. Se seu aplicativo considerar o espao de cor atual inaceitvel, voc pode optar por alternar de um objeto StageVideo para um objeto Video. A classe Video oferece suporte a todos os espaos de cor por meio da composio do software.

ltima atualizao em 29/3/2011

508

Captulo 24: Trabalhando com cmeras

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Uma cmera conectada ao computador de um usurio pode funcionar como fonte de dados de vdeo, que voc pode exibir e manipular usando o ActionScript. A classe Camera o mecanismo criado no ActionScript para trabalhar com um computador ou dispositivo de cmera. Nos dispositivos mveis, voc tambm pode usar a classe CameraUI. A classe CameraUI ativa um aplicativo de cmera para permitir que o usurio capture uma tomada de imagem ou de vdeo. Quando o usurio terminar, seu aplicativo poder acessar a imagem ou o vdeo por meio de um objeto MediaPromise.

Mais tpicos da Ajuda

Christian Cantrell: How to use CameraUI in a Cross-platform Way (Como Usar a Interface do Usurio da Cmara em Vrias Plataformas) Michal CHAIZE: Android, AIR and the Camera (Android, AIR e a Cmara)

Noes bsicas sobre a classe Camera

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O objeto Camera permite que voc se conecte cmera local do usurio e transmita o vdeo localmente (para o usurio) ou remotamente para um servidor (como o Flash Media Server). Usando a classe Camera, possvel acessar os seguintes tipos de informaes sobre a cmera do usurio:

Quais cmeras instaladas no computador ou dispositivo do usurio esto disponveis. Se h uma cmera instalada Se o Flash Player tem acesso cmera do usurio ou no Qual cmera est ativa A largura e a altura do vdeo que est sendo capturado
A classe Camera inclui vrios mtodos e propriedades teis para trabalhar com objetos Camera. Por exemplo, a propriedade esttica Camera.names contm uma matriz de nomes de cmeras que esto instaladas no computador do usurio. Voc tambm pode usar a propriedade name para exibir o nome da cmera que est ativa. Nota: Ao transmitir fluxo de vdeo da cmera pela rede, trate sempre das interrupes da rede. Interrupes de rede podem ocorrer por muitos motivos, especialmente em dispositivos mveis.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalhando com cmeras

509

Exibio do contedo da cmera na tela

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A conexo a uma cmera pode exigir menos cdigo do que usar as classes NetConnection e NetStream para carregar um vdeo. A classe Camera tambm pode rapidamente se tornar complicada porque, com o Flash Player, voc precisa da permisso do usurio para se conectar cmera dele antes de acess-la. Este cdigo demonstra como usar a classe Camera para se conectar cmera local de um usurio:
var cam:Camera = Camera.getCamera(); var vid:Video = new Video(); vid.attachCamera(cam); addChild(vid);

Nota: A classe Camera no tem um mtodo construtor. Para criar uma nova ocorrncia de Camera, use o mtodo esttico Camera.getCamera().

Desenvolvimento do aplicativo de cmera

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Ao criar um aplicativo que se conecta cmera de um usurio, considere os seguintes aspectos no seu cdigo:

Verifique se o usurio tem uma cmera instalada. Trate o caso em que no h nenhuma cmera disponvel. Somente no Flash Player, verifique se o usurio permitiu acesso cmera explicitamente. Por motivo de segurana,
o player exibe a caixa de dilogo Configuraes do Flash Player, onde o usurio pode conceder ou negar acesso sua cmera. Isso impede que o Flash Player se conecte cmera de um usurio e transmita um fluxo de vdeo sem a devida permisso. Se um usurio clicar em permitir, o aplicativo poder se conectar cmera. Se ele clicar em negar, o aplicativo no conseguir ter acesso cmera do usurio. Seus aplicativos sempre devem manipular os dois casos normalmente.

Somente para o AIR, verifique se a classe Camera conta com o suporte dos perfis de dispositivo compatveis com
seu aplicativo.

A classe Camera no conta com suporte em navegadores mveis. A classe Camera no conta com suporte em aplicativos AIR mveis que usam o modo de renderizao pela GPU. No iOS, somente uma cmera pode ficar ativa de cada vez. No Android, somente a cmera traseira pode ser acessada.

Mais tpicos da Ajuda

Christophe Coenraets: jogo da velha em vdeo com vrios usurios Mark Doherty: applicativo Android Radar (fonte)

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalhando com cmeras

510

Conexo cmera de um usurio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A primeira etapa para se conectar cmera de um usurio criar uma nova ocorrncia de Camera criando uma varivel do tipo Camera e a inicializando com o valor de retorno do mtodo esttico Camera.getCamera(). A prxima etapa criar um novo objeto de vdeo e conectar o objeto Camera a ele. A terceira etapa adicionar o objeto de vdeo lista de exibio. Voc precisa executar as etapas 2 e 3 porque a classe Camera no estende a classe DisplayObject, por isso no possvel adicion-la diretamente lista de exibio. Para exibir o vdeo capturado da cmera, crie um novo objeto de vdeo e chame o mtodo attachCamera(). O seguinte cdigo mostra estas trs etapas:
var cam:Camera = Camera.getCamera(); var vid:Video = new Video(); vid.attachCamera(cam); addChild(vid);

Observe que, se o usurio no tiver uma cmera instalada, o aplicativo no exibir nada. Na prtica, voc precisa executar outras etapas que envolvem o seu aplicativo. Para obter mais informaes, consulte Verificao da instalao das cmeras na pgina 510 e Deteco de permisses de acesso cmera na pgina 511.

Mais tpicos da Ajuda

Lee Brimelow: como acessar a cmera em dispositivos Android

Verificao da instalao das cmeras

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Antes de tentar usar qualquer um dos mtodos ou propriedades em uma ocorrncia de Camera, recomendvel verificar se o usurio tem uma cmera instalada. H duas maneiras de fazer essa verificao:

Verifique a propriedade esttica Camera.names que contm uma matriz de nomes de cmeras que esto
disponveis. Normalmente, essa matriz ter no mximo uma string, porque provvel que a maioria dos usurios no tenha mais de uma cmera instalada. Este cdigo demonstra como verificar a propriedade Camera.names para saber se o usurio tem alguma cmera disponvel:
if (Camera.names.length > 0) { trace("User has at least one camera installed."); var cam:Camera = Camera.getCamera(); // Get default camera. } else { trace("User has no cameras installed."); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalhando com cmeras

511

Verifique o valor de retorno do mtodo esttico Camera.getCamera(). Se no houver nenhuma cmera disponvel
ou instalada, o mtodo retornar null; caso contrrio, ele retornar uma referncia a um objeto Camera. Este cdigo demonstra como verificar o mtodo Camera.getCamera() para saber se o usurio tem alguma cmera disponvel:
var cam:Camera = Camera.getCamera(); if (cam == null) { trace("User has no cameras installed."); } else { trace("User has at least 1 camera installed."); }

Como a classe Camera no estende a classe DisplayObject, no pode ser adicionada diretamente lista de exibio usando o mtodo addChild(). Para exibir o vdeo capturado da cmera, preciso criar um novo objeto Video e chamar o mtodo attachCamera() na ocorrncia de Video. Este snippet mostra como conectar a cmera, se disponvel; se no houver uma cmera, o aplicativo no exibir nada:
var cam:Camera = Camera.getCamera(); if (cam != null) { var vid:Video = new Video(); vid.attachCamera(cam); addChild(vid); }

Cmeras de dispositivos mveis A classe Camera no suportada no tempo de execuo do Flash Player em navegadores mveis. Nos aplicativos AIR em dispositivos mveis voc pode acessar a cmera ou cmeras no dispositivo. No iOS, voc pode usar tanto a cmera frontal quanto a traseira, mas somente uma sada de cmera pode ser exibida em um determinado momento. (Conectar uma segunda cmera desconecta a primeira.) A cmera frontal espelhada horizontalmente. No Android, somente a cmera traseira pode ser acessada.

Deteco de permisses de acesso cmera

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Na caixa de proteo do aplicativo AIR, o aplicativo pode acessar qualquer cmera sem a permisso do usurio. No Android, no entanto, um aplicativo deve especificar a permisso CAMERA do Android no descritor do aplicativo. Para que o Flash Player possa exibir a sada de uma cmera, o usurio deve permitir o acesso do Flash Player cmera explicitamente. Quando o mtodo attachCamera() chamado, o Flash Player exibe a caixa de dilogo Configuraes do Flash Player, que pede para o usurio conceder ou negar acesso cmera e ao microfone para o Flash Player. Se o usurio clicar no boto Permitir, o Flash Player exibir a sada da cmera na ocorrncia de Video no Palco. Se o usurio clicar no boto Negar, o Flash Player no conseguir se conectar cmera, e o objeto Video no exibir nada. Para detectar se o usurio concedeu acesso cmera para o Flash Player, voc pode monitorar o evento status da cmera (StatusEvent.STATUS), como visto neste cdigo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalhando com cmeras

512

var cam:Camera = Camera.getCamera(); if (cam != null) { cam.addEventListener(StatusEvent.STATUS, statusHandler); var vid:Video = new Video(); vid.attachCamera(cam); addChild(vid); } function statusHandler(event:StatusEvent):void { // This event gets dispatched when the user clicks the "Allow" or "Deny" // button in the Flash Player Settings dialog box. trace(event.code); // "Camera.Muted" or "Camera.Unmuted" }

A funo statusHandler() chamada assim que o usurio clica em Permitir ou Negar. Voc pode detectar em qual boto o usurio clicou usando um destes dois mtodos:

O parmetro event da funo statusHandler() contm uma propriedade de cdigo que inclui a string
Camera.Muted ou Camera.Unmuted. Se o valor Camera.Muted, isso significa que o usurio clicou no boto Negar e o Flash Player no pode acessar a cmera. Este snippet mostra um exemplo disso:
function statusHandler(event:StatusEvent):void { switch (event.code) { case "Camera.Muted": trace("User clicked Deny."); break; case "Camera.Unmuted": trace("User clicked Accept."); break; } }

A classe Camera contm uma propriedade somente leitura chamada muted que especifica se o usurio negou acesso
cmera (true) ou se permitiu acesso a ela (false) no painel Privacidade do Flash Player. Este snippet mostra um exemplo disso:
function statusHandler(event:StatusEvent):void { if (cam.muted) { trace("User clicked Deny."); } else { trace("User clicked Accept."); } }

Verificando o eventos de status a ser despachado, voc pode criar um cdigo que lide com a aceitao ou a negao do acesso cmera pelo usurio e fazer as devidas excluses. Por exemplo, se o usurio clicar no boto Negar, voc poder exibir uma mensagem informando que ele deve clicar em Permitir se deseja participar de um bate-papo com vdeo, ou voc poder verificar se o objeto Video da lista de exibio foi excludo para liberar recursos do sistema. No AIR, um objeto Camera no despacha eventos de status, visto que a permisso para usar a cmera no dinmica.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalhando com cmeras

513

Maximizando a qualidade de vdeo da cmera

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Por padro, as novas ocorrncias da classe Video tm 320 pixels de largura por 240 pixels de altura. Para maximizar a qualidade dos vdeos, sempre verifique se o objeto de vdeo tem as mesmas dimenses do vdeo retornado pelo objeto de cmera. Para obter a largura e a altura do objeto de cmera, use as propriedades width e height da classe Camera; em seguida, voc pode definir as propriedades width e height do objeto de vdeo de modo que correspondam s dimenses dos objetos de cmera, ou pode passar a largura e a altura da cmera para o mtodo construtor da classe Video, como visto neste snippet:
var cam:Camera = Camera.getCamera(); if (cam != null) { var vid:Video = new Video(cam.width, cam.height); vid.attachCamera(cam); addChild(vid); }

Uma vez que o mtodo getCamera() retorna uma referncia a um objeto de cmera (ou null se no houver cmeras disponveis), voc poder acessar os mtodos e as propriedades da cmera mesmo que o usurio negue acesso a ela. Isso permite que voc defina o tamanho da ocorrncia de vdeo usando a altura e a largura nativas da cmera.
var vid:Video; var cam:Camera = Camera.getCamera(); if (cam == null) { trace("Unable to locate available cameras."); } else { trace("Found camera: " + cam.name); cam.addEventListener(StatusEvent.STATUS, statusHandler); vid = new Video(); vid.attachCamera(cam); } function statusHandler(event:StatusEvent):void { if (cam.muted) { trace("Unable to connect to active camera."); } else { // Resize Video object to match camera settings and // add the video to the display list. vid.width = cam.width; vid.height = cam.height; addChild(vid); } // Remove the status event listener. cam.removeEventListener(StatusEvent.STATUS, statusHandler); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalhando com cmeras

514

Para obter informaes sobre o modo de tela cheia, consulte a seo Modo de tela cheia em Configurao de propriedades do palco na pgina 159.

Monitorando o status da cmera

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe Camera contm vrias propriedades que permitem monitorar o status atual do objeto Camera. Por exemplo, este cdigo exibe diversas propriedades da cmera usando um objeto Timer e uma ocorrncia de campo de texto na lista de exibio:
var vid:Video; var cam:Camera = Camera.getCamera(); var tf:TextField = new TextField(); tf.x = 300; tf.autoSize = TextFieldAutoSize.LEFT; addChild(tf); if (cam != null) { cam.addEventListener(StatusEvent.STATUS, statusHandler); vid = new Video(); vid.attachCamera(cam); } function statusHandler(event:StatusEvent):void { if (!cam.muted) { vid.width = cam.width; vid.height = cam.height; addChild(vid); t.start(); } cam.removeEventListener(StatusEvent.STATUS, statusHandler); } var t:Timer = new Timer(100); t.addEventListener(TimerEvent.TIMER, timerHandler); function timerHandler(event:TimerEvent):void { tf.text = ""; tf.appendText("activityLevel: " + cam.activityLevel + "\n"); tf.appendText("bandwidth: " + cam.bandwidth + "\n"); tf.appendText("currentFPS: " + cam.currentFPS + "\n"); tf.appendText("fps: " + cam.fps + "\n"); tf.appendText("keyFrameInterval: " + cam.keyFrameInterval + "\n"); tf.appendText("loopback: " + cam.loopback + "\n"); tf.appendText("motionLevel: " + cam.motionLevel + "\n"); tf.appendText("motionTimeout: " + cam.motionTimeout + "\n"); tf.appendText("quality: " + cam.quality + "\n"); }

A cada 1/10 de segundo (100 milissegundos) o evento timer do objeto Timer despachado, e a funo timerHandler() atualiza o campo de texto na lista de exibio.

ltima atualizao em 29/3/2011

515

Captulo 25: Uso de gerenciamento de direitos digitais

Flash Player 10.1 e posterior, Adobe AIR 1.5 e posterior Adobe Flash Access uma soluo de proteo de contedo. Permite que proprietrios de contedo, distribuidores e anunciantes possuam novas fontes de renda ao fornecer acesso direto a contedo premium. Provedores utilizam o Flash Access para criptografar contedo, criar polticas e conservar licenas. O Adobe Flash Player e o Adobe AIR incorporam uma biblioteca DRM, o mdulo Flash Access. Este mdulo permite que o tempo de execuo se comunique com o servidor de licena do Flash Access e reproduza o contedo protegido. O tempo de execuo completa o ciclo de vida do contedo protegido pelo Flash Access e distribudos pelo Flash Media Server. Com o Flash Access, provedores de contedo podem fornecer contedo gratuito e premium. Por exemplo, um consumidor deseja ver um programa de televiso sem anncios. O consumidor se registra e paga ao provedor de contedo. O Consumidor pode ento inserir suas credenciais de usurio para ganhar acesso e reproduzir o programas sem os anncios. Em outro exemplo, um consumidor deseja ver contedo offline enquanto viaja sem acesso a Internet. O fluxo de trabalho offline suportado em aplicativos AIR. Depois de se registrar e pagar ao provedor pelo contedo, o usurio pode acessar e baixar o contedo e o aplicativo AIR associado do website do provedor. Utilizando o aplicativo AIR, o usurio pode ver o contedo offline durante o perodo permitido. O contedo no pode ser compartilhado com outros usurios. O Flash Access tambm suporta acesso annimo, que no requer autenticao do usurio. Por exemplo, um provedor pode utilizar acesso annimo para distribuir contedo com anncios. O acesso annimo tambm permite que um provedor possua acesso livre ao contedo atual por um nmero especfico de dias. O provedor de contedo tambm pode especificar e restringir o tipo e a verso do player necessrio para seu contedo. Quando um usurio tenta reproduzir contedo protegido no Flash Player ou no Adobe AIR, seu aplicativo deve chamar as APIs de DRM. As APIs de DRM iniciam o fluxo de trabalho para reproduo de contedo protegido. O tempo de execuo, faz contato com o servidor de licenas atravs de mdulo do Flash Access. O servidor de licenas autentica o usurio, caso necessrio, e fornece um voucher (licena) para permitir a reproduo de contedo protegido. O tempo de execuo recebe a licena e descriptografa o contedo para reproduo. A descrio de como habilitar seu aplicativo para reproduo de contedo protegido est aqui. No necessrio entender como criptografar contedo ou manter polticas utilizando o Flash Access. No entanto, pressupe-se que voc est se comunicando como o servido de licenas do Flash Access para autenticar o usurio e recuperar a licena. Tambm pressupes-se que voc esta projetando um aplicativo para reproduzir especificamente contedo protegido pelo Flash Access. Para uma viso geral do Flash Access, incluindo a criao de polticas, consulte a documentao includa com o Flash Access.

Mais tpicos da Ajuda

Pacote flash.net.drm flash.net.NetConnection flash.net.NetStream

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de gerenciamento de direitos digitais

516

Entendendo o fluxo de trabalho de contedo protegido.

Flash Player 10.1 e posterior, Adobe AIR 2.0 e posterior O fluxo de trabalho de alto nvel a seguir mostra como um aplicativo pode recuperar e reproduzir contedo protegido. O fluxo de trabalho assume que o aplicativo projetado para reproduzir especificamente contedo protegido pelo Flash Access:
1

Obtenha os metadados do contedo.

2 Trata das atualizaes do Flash Player, se necessrio. 3 Verifique se uma licena est disponvel localmente. Se sim, carregue-o e siga para o passo 7. Se no, v para o passo 4. 4 Verifique se a autenticao necessria. Se no, v para o passo 7. 5 Caso a autenticao seja necessria, obtenha as credenciais de autenticao para o usurio e passe-as para o servidor

de licenas.
6 Uma vez que a autenticao acontea, baixe a licena do servidor. 7 Reproduza o contedo.

Se no tiver ocorrido nenhum erro e o usurio foi autorizado com xito a exibir o contedo, o objeto NetStream enviar um objeto DRMStatusEvent. O aplicativo inicia a reproduo. O objeto DRMStatusEvent guarda as informaes de voucher relacionadas, que identificam a poltica e as permisses do usurio. Por exemplo, ele possui informaes sobre se o contedo pode ser disponibilizado offline ou quando a licena expira. O aplicativo pode usar esses dados para informar ao usurio sobre o status de sua poltica. Por exemplo, o aplicativo pode exibir o nmero de dias restantes que o usurio possui para exibir o contedo em uma barra de status. (Apenas no AIR) Se o usurio pode acessar contedo offline, o voucher armazenado e o contedo criptografado baixado para a mquina do usurio. O contedo disponibilizado pela durao definida no perodo de concesso offline. A propriedade detail no evento contm "DRM.voucherObtained". O aplicativo decide onde armazenar o contedo localmente para que ele esteja disponvel off-line. Voc tambm pode pr-carregar vouchers usando a classe DRMManager. Todos os erros relacionados ao DRM resultam em no envio de um objeto de evento DRMErrorEvent pelo aplicativo ou em um objeto DRMAuthenticationErrorEvent do AIR. responsabilidade do aplicativo tratar diretamente de todos os outros eventos de erro. Estes eventos incluem casos nos quais o usurio insere credenciais vlidas, mas o voucher que protege o contedo criptografado restringe o acesso ao contedo. Por exemplo, um usurio autenticado no pode acessar o contedo se os direitos no estiverem pagos. Este caso tambm pode ocorrer quando dois integrantes registrados do mesmo provedor tentar compartilhar contedo adquirido somente por um deles. O aplicativo deve informar o usurio sobre o erro e fornecer uma sugesto alternativa. Uma sugesto alternativa comum so as instrues sobre como registrar e pagar por direitos de visualizao.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de gerenciamento de direitos digitais

517

Fluxo de trabalho detalhado

Flash Player 10.1 e posterior, AIR 2.0 e posterior Este fluxo de trabalho fornece uma viso mais detalhada do fluxo de trabalho do contedo protegido. Este fluxo de trabalho descreve as APIs especificas utilizadas para reproduzir contedo protegido pelo Flash Access.
1 Utilizando um objeto URLLoader, carregue os bytes do arquivo de metadados do contedo protegido. Defina este

objeto para uma varivel como metadata_bytes. Todo o contedo controlado pelo Flash Access possui metadados do Flash Access. Quando o contedo empacotado, estes metadados podem ser salvos como um arquivo metadados separado (.metadata) junto com o contedo. Para obter mais informaes, consulte a documentao do Flash Access.
2 Crie uma ocorrncia de DRMContentData. Coloque este cdigo em um bloco try-catch:
new DRMContentData(metadata_bytes)

onde metadata_bytes o objeto URLLoader obtido no passo 1.

3 (Apenas para o Flash Player) O tempo de execuo faz uma verificao sobre o mdulo do Flash Access. Caso no

seja encontrado, um IllegalOperationError com cdigo de erro 3344 emitido. Para tratar desse erro, faa o download do mdulo Flash Access utilizando o SystemUpdater API. Depois que o mdulo for baixado, os objeto SystemUpdater envia um evento COMPLETE. Inclua um ouvinte de eventos para este evento que volta para o passo 2 quando este evento enviado. O cdigo a seguir demonstra as etapas:
flash.system.SystemUpdater.addEventListener(Event.COMPLETE, updateCompleteHandler); flash.system.SystemUpdater.update(flash.system.SystemUpdaterType.DRM) private function updateCompleteHandler (event:Event):void { /*redo step 2*/ drmContentData = new DRMContentData(metadata_bytes); }

Se o prprio player precisa ser atualizado, um evento de status enviado. Para mais informaes sobre como manipular este evento, veja Procurando um evento de atualizao na pgina 530. Nota: Nos aplicativos AIR, o instalador AIR manipula a atualizao do mdulo do Flash Access e de atualizaes do tempo de execuo necessrias.
4 Crie ouvintes para ouvir os eventos DRMStatusEvent e DRMErrorEvent enviados do objeto DRMManager:
DRMManager.addEventListener(DRMStatusEvent.DRM_STATUS, onDRMStatus); DRMManager.addEventListener(DRMErrorEvent.DRM_ERROR, onDRMError);

No ouvinte DRMStatusEvent, verifique se o voucher vlido (no null). No ouvinte DRMErrorEvent, manipule DRMErrorEvents. Veja Uso da classe DRMStatusEvent na pgina 523 e Uso da classe DRMErrorEvent na pgina 527.
5 Carregue o voucher (licena) necessrio para reproduzir o contedo.

Primeiro, tente carregar uma licena armazenada localmente para reproduzir o contedo:
DRMManager.loadvoucher(drmContentData, LoadVoucherSetting.LOCAL_ONLY)

Depois que o carregamento estiver completo o objeto DRMManager envia DRMStatusEvent.DRM_Status.

6 Caso o objeto DRMVoucher no seja null, o voucher vlido. Avanar para a etapa 13. 7 Caso o objeto DRMVoucher seja null, verifique o mtodo de autenticao necessrio pela poltica para este

contedo. Utilize a propriedade DRMContentData.authenticationMethod .

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de gerenciamento de direitos digitais

518

8 Caso o mtodo de autenticao seja ANONYMOUS, v para o passo 13. 9 Caso o mtodo de autenticao seja USERNAME_AND_PASSWORD, seu aplicativo precisa fornecer um mecanismo para

que o usurio insira as credenciais. Passe estas credenciais para o servidor de licenas para autenticar o usurio:
DRMManager.authenticate(metadata.serverURL, metadata.domain, username, password)

O DRMManagerenvia um DRMAuthenticationErrorEvent caso a autenticao falhe ou um DRMAuthenticationCompleteEvent caso a autenticao funcione. Crie ouvintes para estes eventos.
10 Caso a autenticao falhe, seu aplicativo deve retornar para o passo 9. Certifique-se de que seu aplicativo tenha um

mecanismo para manipular e limitar falhas de autenticao repetidas. Por exemplo, depois de trs tentativas, mostre uma mensagem para o usurio indicando que a autenticao falhou e que o contedo no pode ser reproduzido.
11 Caso a autenticao acontea, baixe a licena do servidor de licenas.
DRMManager.loadvoucher(drmContentData, LoadVoucherSetting.FORCE_REFRESH)

Depois que o carregamento estiver completo o objeto DRMManager envia DRMStatusEvent.DRMStatus Oua este evento e quando ele for enviado, o contedo pode ser reproduzido.
12 (opcional) Caso a autenticao proceda, voc pode capturar o token de autenticao, que uma matriz de bytes

armazenada na memria. Capture este token com a propriedade DRMAuthenticationCompleteEvent.token . Voc pode armazenar e utilizar o token de autenticao para que o usurio no precise inserir as credenciais repetidamente para este contedo. O servidor de licena determina o perodo de validade do token de autenticao. Para utilizar o token armazenado em vez de solicitar que o usurio insira as credenciais, defina o token com o mtodo DRMManager.setAuthenticationToken() . Ento voc pode baixar a licena do servidor de licenas e reproduzir o contedo como no passo 8.
13 Reproduzir o vdeo criando um objeto NetStream e chamando o mtodo play():
stream = new NetStream(connection); stream.addEventListener(DRMStatusEvent.DRM _STATUS, drmStatusHandler); stream.addEventListener(DRMErrorEvent.DRM_ERROR, drmErrorHandler); stream.addEventListener(NetStatusEvent.NET_STATUS, netStatusHandler); stream.client = new CustomClient(); video.attachNetStream(stream); stream.play(videoURL);

Eventos relacionados ao DRM

O tempo de execuo envia vrios eventos quando um aplicativo tenta reproduzir contedo protegido:

DRMAuthenticateEvent (apenas no AIR), enviado pelo NetStream DRMAuthenticationCompleteEvent, enviado pelo DRMManager DRMAuthenticationErrorEvent, enviado pelo DRMManager DRMErrorEvent, enviado pelo NetStream e pelo DRMManager DRMStatusEvent, enviado pelo NetStream e pelo DRMManager StatusEvent NetStatusEvent. Veja Procurando um evento de atualizao na pgina 530
Para dar suporte a contedo protegido pelo Flash Access, adicione ouvintes de eventos para manipular eventos de DRM.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de gerenciamento de direitos digitais

519

Pr-carregar vouchers para reproduo offline

Adobe AIR 1.5 e posterior Voc pode pr-carregar os vouchers (licenas) necessrios para reproduzir contedo protegido pelo Flash Access. Vouchers pr-carregados permitem que os usurios vejam o contedo com ou sem conexo Internet. (O processo de pr-carregamento propriamente dito requer conexo com Internet.) Use o mtodo preloadEmbeddedMetadata() da classe NetStream e a classe DRMManager do para pr-carregar vouchers. No AIR 2.0 e posteriores, voc pode utilizar um objeto DRMContentData para pr-carregar vouchers diretamente. Esta tcnica tem preferncia porque permite a atualizao do objeto DRMContentData independentemente do contedo. (O mtodo preloadEmbeddedData() extrai DRMContentData do contedo.)

Utilizando DRMContentData
Adobe AIR 2.0 e posterior Os passos a seguir descrevem o fluxo de trabalho para pr-carregar o voucher para um arquivo de mdia protegido utilizando um objeto DRMContentData.
1 Obtenha os metadados binrios para o contedo empacotado. Caso esteja utilizando o Java Reference Packager do

Flash Access, este arquivo metadados automaticamente gerado com uma extenso .metadata. Por exemplo, possvel fazer o download destes metadados utilizando a classe URLLoader.
2 Crie um objeto DRMContentData passando os metadados para a funo do construtor:
var drmData:DRMContentData = new DRMContentData( metadata );

3 O restante dos passos so idnticos ao fluxo de trabalho do Entendendo o fluxo de trabalho de contedo

protegido. na pgina 516.

Utilizando preloadEmbeddedMetadata()
Adobe AIR 1.5 e posterior As etapas a seguir descrevem o fluxo de trabalho para pr-carregar o voucher de um arquivo de mdia protegido por DRM utilizando preloadEmbeddedMetadata():
1 Baixe e armazene o arquivo de mdia. (Metadados DRM s podem ser pr-carregados de arquivos armazenados

localmente.)
2 Crie os objetos NetConnection e NetStream, fornecendo implementaes para as funes de retorno de chamada
onDRMContentData() e onPlayStatus() do objeto cliente NetStream.

3 Crie um objeto NetStreamPlayOptions e defina a propriedade stream para a URL do arquivo de mdia local. 4 Chame o NetStream preloadEmbeddedMetadata(), passando no objeto NetStreamPlayOptions que identifica o

arquivo de mdia que ser analisado.

5 Se o arquivo de mdia contiver metadados DRM, a funo de retorno de chamada onDRMContentData() ser

chamada. Os metadados so transmitidos a essa funo como objeto DRMContentData.

6 Use o objeto DRMContentData para obter o voucher usando o mtodo loadVoucher() do DRMManager.

Se o valor da propriedade authenticationMethod do objeto DRMContentData for userNameAndPassword, voc dever autenticar o usurio no servidor de direitos de mdia antes de carregar o voucher. As propriedades serverURL e domain do objeto DRMContentData podem ser passadas para o mtodo authenticate() do DRMManager, juntamente com as credenciais do usurio.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de gerenciamento de direitos digitais

520

7 A funo de retorno de chamada onPlayStatus() chamada aps a concluso da anlise do arquivo. Se a funo
onDRMContentData() no tiver sido chamada, o arquivo no conter os metadados necessrios para obter um

voucher. Esta chamada ausente tambm pode significar que o Flash Access no protege este arquivo. O exemplo de cdigo para o AIR a seguir ilustra como pr-carregar um voucher para um arquivo de mdia local:
package { import flash.display.Sprite; import flash.events.DRMAuthenticationCompleteEvent; import flash.events.DRMAuthenticationErrorEvent; import flash.events.DRMErrorEvent; import flash.ev ents.DRMStatusEvent; import flash.events.NetStatusEvent; import flash.net.NetConnection; import flash.net.NetStream; import flash.net.NetStreamPlayOptions; import flash.net.drm.AuthenticationMethod; import flash.net.drm.DRMContentData; import flash.net.drm.DRMManager; import flash.net.drm.LoadVoucherSetting; public class DRMPreloader extends Sprite { private var videoURL:String = "app-storage:/video.flv"; private var userName:String = "user"; private var password:String = "password"; private var preloadConnection:NetConnection; private var preloadStream:NetStream; private var drmManager:DRMManager = DRMManager.getDRMManager(); private var drmContentData:DRMContentData; public function DRMPreloader():void { drmManager.addEventListener( DRMAuthenticationCompleteEvent.AUTHENTICATION_COMPLETE, onAuthenticationComplete); drmManager.addEventListener(DRMAuthenticationErrorEvent.AUTHENTICATION_ERROR, onAuthenticationError); drmManager.addEventListener(DRMStatusEvent.DRM_STATUS, onDRMStatus); drmManager.addEventListener(DRMErrorEvent.DRM_ERROR, onDRMError); preloadConnection = new NetConnection(); preloadConnection.addEventListener(NetStatusEvent.NET_STATUS, onConnect); preloadConnection.connect(null); } private function onConnect( event:NetStatusEvent ):void { preloadMetadata(); } private function preloadMetadata():void { preloadStream = new NetStream( preloadConnection ); preloadStream.client = this; var options:NetStreamPlayOptions = new NetStreamPlayOptions(); options.streamName = videoURL; preloadStream.preloadEmbeddedData( options ); } public function onDRMContentData( drmMetadata:DRMContentData ):void {

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de gerenciamento de direitos digitais

521

drmContentData = drmMetadata; if ( drmMetadata.authenticationMethod == AuthenticationMethod.USERNAME_AND_PASSWORD ) { authenticateUser(); } else { getVoucher(); } } private function getVoucher():void { drmManager.loadVoucher( drmContentData, LoadVoucherSetting.ALLOW_SERVER ); } private function authenticateUser():void { drmManager.authenticate( drmContentData.serverURL, drmContentData.domain, userName, password ); } private function onAuthenticationError( event:DRMAuthenticationErrorEvent ):void { trace( "Authentication error: " + event.errorID + ", " + event.subErrorID ); } private function onAuthenticationComplete( event:DRMAuthenticationCompleteEvent ):void { trace( "Authenticated to: " + event.serverURL + ", domain: " + event.domain ); getVoucher(); } private function onDRMStatus( event:DRMStatusEvent ):void { trace( "DRM Status: " + event.detail); trace("--Voucher allows offline playback = " + event.isAvailableOffline ); trace("--Voucher already cached = " + event.isLocal ); trace("--Voucher required authentication = " + !event.isAnonymous ); } private function onDRMError( event:DRMErrorEvent ):void { trace( "DRM error event: " + event.errorID + ", " + event.subErrorID + ", " + event.text ); } public function onPlayStatus( info:Object ):void { preloadStream.close(); } } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de gerenciamento de direitos digitais

522

Membros e eventos relacionados a DRM da classe NetStream

Flash Player 10.1 e posterior, Adobe AIR 1.0 e posterior A classe NetStream fornece uma conexo de streaming unidirecional entre o Flash Player ou um aplicativo AIR e o Flash Media Server ou o sistema de arquivos local. (A classe NetStream tambm suporta o download progressivo.) Um objeto NetStream um canal em um objeto NetConnection. A classe NetStream envia quatro eventos relacionados ao DRM:
Evento drmAuthenticate (somente AIR) Descrio Definido na classe DRMAuthenticateEvent. Este evento enviado quando um objeto NetStream tenta reproduzir contedo protegido que requer uma credencial de usurio para autenticao antes da reproduo. As propriedades desse evento incluem as propriedades header, usernamePrompt, passwordPrompt e urlPrompt que podem ser usadas para obter e definir as credenciais do usurio. Esse evento ocorre repetidamente at que o objeto NetStream receba credenciais de usurio vlidas. drmError Definido na classe DRMErrorEvent e enviado quando um objeto NetStream tenta reproduzir contedo protegido e encontra um erro relacionado com o DRM. Por exemplo, um objeto de evento de erro DRM despachado quando a autorizao do usurio falha. Este erro pode ocorrer porque o usurio no adquiriu os direitos de visualizao do contedo. Isto tambm pode ocorrer porque o provedor de contedo no possui suporte para o aplicativo de visualizao. Definido na classe DRMStatusEvent. Este evento enviado quando o contedo protegido comea a ser reproduzido (quando o usurio est autenticado e autorizado a reproduzir o contedo. O objeto DRMStatusEvent contm informaes relacionadas ao voucher. As informaes sobre o voucher incluem se o contedo pode ser disponibilizado offline ou quando o voucher expira e o contedo no pode mais se exibido. Definido em events.StatusEvent e enviado apenas quando o aplicativo tenta reproduzir contedo protegido, chamando o mtodo NetStream.play(). O valor da propriedade do cdigo de status ser "DRM.encryptedFLV".

drmStatus

status

A classe NetStream inclui os seguintes mtodos especficos de DRM, para uso no AIR apenas:
Mtodo resetDRMVouchers() Descrio Exclui todos os dados de comprovao de gerenciamento de direitos digitais armazenados localmente em cache. O aplicativo deve baixar o voucher novamente para que o usurio possa acessar o contedo criptografado. Por exemplo, o cdigo a seguir remove todos os vouchers do cache: NetStream.resetDRMVouchers(); setDRMAuthenticationCredentials() Transmite um conjunto de credenciais de autenticao, a saber, nome de usurio, senha e tipo de autenticao, ao objeto NetStream para autenticao. Os tipos de autenticao vlidos so "drm" e "proxy" . Com o tipo de autenticao "drm" , as credenciais fornecidas so autenticadas em relao ao Flash Access. Com o tipo de autenticao "proxy", as credenciais so autenticadas em comparao ao servidor proxy e devem ser compatveis s solicitadas por ele. Por exemplo, uma empresa pode requerer que o aplicativo faa a autenticao em um servidor proxy antes que o usurio possa acessar a Internet. A opo do proxy permite este tipo de autenticao. A menos que seja usada a autenticao annima, depois da autenticao proxy, o usurio ainda precisar ser autenticado comparando ao Flash Access para obter o voucher e reproduzir o contedo. Voc pode usar setDRMAuthenticationcredentials() uma segunda vez, com a opo "drm" para autenticar no Flash Access. Analisa se um arquivo de mdia local contm metadados incorporados. Quando metadados relacionados a DRM so encontrados, o AIR chama a funo de retorno de chamada onDRMContentData() .

preloadEmbeddedMetadata()

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de gerenciamento de direitos digitais

523

Alm disso, no AIR, um objeto NetStream chama as funes de retorno de chamada onDRMContentData() e onPlayStatus() como resultado de uma chamada para o mtodo preloadEmbeddedMetaData(). A funo onDRMContentData() chamada quando os metadados DRM so encontrados em um arquivo de mdia. A funo onPlayStatus() chamada quando o arquivo analisado. As funes onDRMContentData() e onPlayStatus() devem ser definidas no objeto client atribudo ocorrncia do NetStream. Se voc usar o mesmo objeto NetStream para pr-carregar vouchers e reproduzir contedo, aguarde pela chamada onPlayStatus() gerada pelo preloadEmbeddedMetaData() antes de iniciar a reproduo. No seguinte cdigo para o AIR, nome de usurio (administrator), senha (password) e o tipo de autenticao drm so definidos para autenticar o usurio. O mtodo setDRMAuthenticationCredentials() precisa fornecer credenciais que correspondam as credenciais conhecidas e aceitas pelo provedor de contedo. Estas credenciais so as mesmas credenciais de usurio que permitem a visualizao do contedo. O cdigo para reproduzir o vdeo e certificar-se de que foi feita uma conexo bem-sucedida ao streaming de vdeo no est includa aqui.
var connection:NetConnection = new NetConnection(); connection.connect(null); var videoStream:NetStream = new NetStream(connection); videoStream.addEventListener(DRMAuthenticateEvent.DRM_AUTHENTICATE, drmAuthenticateEventHandler) private function drmAuthenticateEventHandler(event:DRMAuthenticateEvent):void { videoStream.setDRMAuthenticationCredentials("administrator", "password", "drm"); }

Uso da classe DRMStatusEvent

Flash Player 10.1, Adobe AIR 1.0 e posterior Um objeto NetStream envia um objeto DRMStatusEvent quando o contedo protegido pelo Flash Access comea a ser reproduzido com sucesso. (Sucesso implica que a licena foi verificada e que o usurio est autenticado e autorizado a visualizar o contedo). DRMStatusEvent tambm despachado para usurios annimos se for permitido acesso a eles. A licena consultada para verificar se usurios annimos, que no precisam de autenticao, podem acessar e reproduzir o contedo. Usurios annimos podem ter acesso negado por vrias razes. Por exemplo, um usurio annimo no tem acesso ao contedo quando a licena estiver expirada. O objeto DRMStatusEvent contm informaes relacionadas licena. Tais informaes sobre o voucher incluem se o contedo pode ser disponibilizado offline ou quando o voucher expira e o contedo no pode mais se exibido. O aplicativo pode usar esses dados para transmitir suas permisses e o status da poltica do usurio.

Propriedades DRMStatusEvent
Flash Player 10.1, Adobe AIR 1.0 e posterior A classe DRMStatusEvent inclui as seguintes propriedades. Algumas propriedades se ficaram disponveis em verses do AIR posteriores a 1.0. Para informaes sobre informaes completas, veja Referncia do ActionScript 3.0. Para propriedades que no so suportadas no Flash 10.1, a classe DRMVoucher fornece propriedades semelhantes para o Flash Player.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de gerenciamento de direitos digitais

524

Propriedade contentData detail (somente AIR)

Descrio Um objeto DRMContentData contendo os metadados DRM incorporados no contedo. Uma seqncia de caracteres que explica o contexto do evento de status. No DRM 1.0, o nico valor vlido DRM.voucherObtained. Indica se o contedo, protegido com criptografia pelo Flash Access, est disponvel sem exigir que um usurio fornea credenciais de autenticao (true) ou no (false). Um valor false significa que os usurios devem fornecer um nome de usurio e uma senha que corresponda aos conhecidos e esperados pelo provedor de contedo. Indica se o contedo, protegido com criptografia pelo Flash Access, pode ser disponibilizado offline (true) ou no (false). Para que o contedo protegido digitalmente seja disponibilizado offline, seu voucher deve ser armazenado em cache na mquina local do usurio. Indica se o voucher necessrio para reproduzir o contedo est armazenado em cache localmente.

isAnonymous (somente AIR)

isAvailableOffline (apenas no AIR)

isLocal

offlineLeasePeriod (apenas O nmero restante de dias que o contedo pode ser exibido offline. no AIR) polticas (somente AIR) voucher Um objeto personalizado que pode conter propriedades DRM personalizadas. O DRMVoucher.

voucherEndDate (somente A data absoluta na qual o voucher expira e o contedo no pode mais ser exibido. AIR)

Criao de um manipulador DRMStatusEvent

Flash Player 10.1, Adobe AIR 1.0 e posterior O exemplo a seguir cria um manipulador de eventos que fornece as informaes de status de contedo DRM para o objeto NetStream que originou o evento. Adicione esse manipulador de eventos a um objeto NetStream que aponta para o contedo protegido.
function drmStatusEventHandler(event:DRMStatusEvent):void { trace(event); } function drmStatusEventHandler(event:DRMStatusEvent):void { trace(event); }

Uso da classe DRMAuthenticateEvent

Adobe AIR 1.0 e posterior O objeto DRMAuthenticateEvent enviado quando um objeto NetStream tenta reproduzir contedo protegido que requer uma credencial de usurio para autenticao antes da reproduo. O manipulador DRMAuthenticateEvent responsvel pela coleta das credenciais necessrias (nome de usurio, senha e tipo) e pela transmisso dos valores ao mtodo NetStream.setDRMAuthenticationCredentials() para validao. Cada aplicativo AIR deve fornecer algum mecanismo para obter credenciais do usurio. Por exemplo, o aplicativo pode fornecer ao usurio uma interface simples para inserir os valores de nome de usurio e senha. Pode tambm, fornecer um mecanismo para manipular e limitar tentativas repetidas de autenticao.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de gerenciamento de direitos digitais

525

Propriedades DRMAuthenticateEvent
Adobe AIR 1.0 e posterior A classe DRMAuthenticateEvent inclui as seguintes propriedades:
Propriedade authenticationType Descrio Indica se as credenciais fornecidas so para autenticao em comparao ao Flash Access (drm) ou um servidor proxy (proxy). Por exemplo, a opo "proxy" permite que o aplicativo autentique em um servidor proxy caso seja necessrio antes de o usurio acessar a Internet. A menos que seja usada a autenticao annima, depois da autenticao proxy, o usurio ainda precisar ser autenticado comparando ao Flash Access para obter o voucher e reproduzir o contedo. Voc pode usar setDRMAuthenticationcredentials() uma segunda vez, com a opo "drm" para autenticar no Flash Access. O cabealho do arquivo de contedo criptografado fornecido pelo servidor. Ele contm informaes sobre o contexto do contedo criptografado. O objeto NetStream que iniciou esse evento. Um prompt para uma credencial de senha, fornecida pelo servidor. A seqncia de caracteres pode incluir instrues para o tipo de senha necessria. Um prompt para uma seqncia de caracteres de URL, fornecida pelo servidor. A seqncia de caracteres pode fornecer o local para onde o nome de usurio e a senha so enviados. Um prompt para uma credencial de nome de usurio, fornecida pelo servidor. A seqncia de caracteres pode incluir instrues para o tipo de nome de usurio necessrio. Por exemplo, um provedor de contedo pode requerer um endereo de e-mail como nome de usurio.

header

netstream passwordPrompt

urlPrompt

usernamePrompt

Criao de um manipulador DRMAuthenticateEvent

Adobe AIR 1.0 e posterior O exemplo a seguir cria um manipulador de eventos que transmite um conjunto de credenciais de autenticao codificadas ao objeto NetStream que originou o evento. (O cdigo para reproduzir o vdeo e certificar-se de que foi feita uma conexo bem-sucedida ao streaming de vdeo no est includa aqui.)
var connection:NetConnection = new NetConnection(); connection.connect(null); var videoStream:NetStream = new NetStream(connection); videoStream.addEventListener(DRMAuthenticateEvent.DRM_AUTHENTICATE, drmAuthenticateEventHandler) private function drmAuthenticateEventHandler(event:DRMAuthenticateEvent):void { videoStream.setDRMAuthenticationCredentials("administrator", "password", "drm"); }

Criao de uma interface para recuperar credenciais do usurio

Adobe AIR 1.0 e posterior No caso em que o contedo protegido requer autenticao do usurio, o aplicativo AIR normalmente deve obter as credenciais de autenticao do usurio por meio de uma interface de usurio.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de gerenciamento de direitos digitais

526

A seguir, um exemplo do Flex de uma interface de usurio simples para recuperar credenciais do usurio. Ele consiste de um objeto de painel contendo dois objetos TextInput, um para cada uma das credenciais de nome de usurio e senha. O painel tambm contm um boto que inicia o mtodo credentials().
<mx:Panel x="236.5" y="113" width="325" height="204" layout="absolute" title="Login"> <mx:TextInput x="110" y="46" id="uName"/> <mx:TextInput x="110" y="76" id="pWord" displayAsPassword="true"/> <mx:Text x="35" y="48" text="Username:"/> <mx:Text x="35" y="78" text="Password:"/> <mx:Button x="120" y="115" label="Login" click="credentials()"/> </mx:Panel>

O mtodo credentials() um mtodo definido pelo usurio que transmite os valores de nome de usurio e senha para o mtodo setDRMAuthenticationCredentials(). Depois que os valores so passados, o mtodo credentials() redefine os valores dos objetos TextInput.
<mx:Script> <![CDATA[ public function credentials():void { videoStream.setDRMAuthenticationCredentials(uName, pWord, "drm"); uName.text = ""; pWord.text = ""; } ]]> </mx:Script>

Uma forma de implementar este tipo de interface simples incluir o painel como parte de um estado novo. O novo estado tem origem em um estado base onde o objeto DRMAuthenticateEvent lanado. O exemplo a seguir contm um objeto VideoDisplay com um atributo de origem que aponta para um arquivo FLV protegido. Neste caso, o mtodo credentials() modificado para tambm retornar o aplicativo ao estado base. Este mtodo faz isto, enviando as credenciais do usurio e reiniciando os valores de objeto TextInput.
<?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" width="800" height="500" title="DRM FLV Player" creationComplete="initApp()" > <mx:states> <mx:State name="LOGIN"> <mx:AddChild position="lastChild"> <mx:Panel x="236.5" y="113" width="325" height="204" layout="absolute" title="Login"> <mx:TextInput x="110" y="46" id="uName"/> <mx:TextInput x="110" y="76" id="pWord" displayAsPassword="true"/> <mx:Text x="35" y="48" text="Username:"/> <mx:Text x="35" y="78" text="Password:"/> <mx:Button x="120" y="115" label="Login" click="credentials()"/> <mx:Button x="193" y="115" label="Reset" click="uName.text=''; pWord.text='';"/> </mx:Panel> </mx:AddChild> </mx:State> </mx:states>

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de gerenciamento de direitos digitais

527

<mx:Script> <![CDATA[ import flash.events.DRMAuthenticateEvent; private function initApp():void { videoStream.addEventListener(DRMAuthenticateEvent.DRM_AUTHENTICATE, drmAuthenticateEventHandler); } public function credentials():void { videoStream.setDRMAuthenticationCredentials(uName, pWord, "drm"); uName.text = ""; pWord.text = ""; currentState=''; } private function drmAuthenticateEventHandler(event:DRMAuthenticateEvent):void { currentState='LOGIN'; } ]]> </mx:Script> <mx:VideoDisplay id="video" x="50" y="25" width="700" height="350" autoPlay="true" bufferTime="10.0" source="http://www.example.com/flv/Video.flv" /> </mx:WindowedApplication>

Uso da classe DRMErrorEvent

Flash Player 10.1 e posterior, Adobe AIR 1.0 e posterior O Adobe Flash e o Adobe AIR enviam um objeto DRMErrorEvent quando um objeto NetStream, que est tentando reproduzir contedo protegido, encontra um erro relacionado ao DRM. Caso as credenciais de usurio sejam invlidas em um aplicativo AIR, o objeto DRMAuthenticateEvent envia sinais repetidamente at que o usurio insira credenciais vlidas ou o aplicativo recuse outras tentativas. O aplicativo deve ouvir qualquer evento de erro do DRM para detectar, identificar e manipular os erros relacionados a DRM. No Flash Player, o aplicativo deve ouvir a todos os eventos de erro do DRM para detectar, identificar e manipular erros relacionados ao DRM. Mesmo com credenciais de usurio vlidas, os termos do voucher do contedo ainda podem impedir que o usurio visualize o contedo criptografado. Por exemplo, o usurio pode ter o acesso negado ao tentar visualizar um contedo em um aplicativo no autorizado. Um aplicativo no autorizado um aplicativo no qual o provedor do contedo criptografado no foi validado. Neste caso, um objeto DRMErrorEvent despachado. Os eventos de erro tambm podem ser disparados se o contedo estiver corrompido ou se a verso do aplicativo no corresponder s especificaes do voucher. O aplicativo deve fornecer um mecanismo apropriado para manipular erros.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de gerenciamento de direitos digitais

528

Propriedades DRMErrorEvent
Flash Player 10.1 e posterior, Adobe AIR 1.0 e posterior Para uma lista completa de erros, veja Cdigos de erro do tempo de execuo na referncia do ActionScript 3.0. Os erros relacionados ao DRM comeam no erro 3300.

Criao de um manipulador DRMErrorEvent

Flash Player 10.1 e posterior, Adobe AIR 1.0 e posterior O exemplo a seguir cria um manipulador de eventos para o objeto NetStream que originou o evento. Ele chamado quando o NetStream encontra um erro ao tentar reproduzir contedo protegido. Geralmente, quando um aplicativo encontra um erro, ele executa um nmero de tarefas de limpeza. Em seguida, ele informa o erro ao usurio e fornece opes para solucionar o problema.
private function drmErrorEventHandler(event:DRMErrorEvent):void { trace(event.toString()); }

Uso da classe DRMManager

Flash Player 10.1 e posterior, Adobe AIR 1.5 e posterior Use a classe DRMManager para gerenciar vouchers e sesses do servidor de direitos de mdia em aplicativos. Gerenciamento de Vouchers (apenas no AIR) Sempre que um usurio reproduz contedo protegido, o tempo de execuo obtm e armazena a licena necessria para visualizar o contedo. Se o aplicativo salva o arquivo localmente e a licena permite a reproduo offline, o usurio pode visualizar o contedo no aplicativo AIR. A reproduo offline local ocorre com sucesso mesmo se a conexo ao servidor de direitos de mdia no estiver disponvel. Utilizando o DRMManager e o mtodo preloadEmbeddedMetadata() , voc pode pr-armazenar o voucher. O aplicativo no tem que obter a licena necessria para visualizar o contedo. Por exemplo, seu aplicativo pode baixar o arquivo de mdia e obter o voucher enquanto o usurio ainda est online. Para pr-carregar um voucher, use o mtodo preloadEmbeddedMetadata() do NetStream para obter um contedo do objeto DRMContentData. O objeto DRMContentData contm a URL e o domnio do servidor dos direitos de mdia que pode fornecer a licena e descreve se a autenticao necessria. Com essas informaes, voc pode chamar o mtodo loadVoucher() do DRMManager para obter o voucher e armazen-lo em cache. O fluxo de trabalho para pr-carregar vouchers descrito com mais detalhes em Pr-carregar vouchers para reproduo offline na pgina 519. Gerenciamento de sesso Voc tambm pode usar o DRMManager para autenticar o usurio para um servidor de direitos de mdia e gerenciar sesses persistentes.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de gerenciamento de direitos digitais

529

Chame o mtodo authenticate() do DRMManager para estabelecer uma sesso com o servidor de direitos de mdia. Quando a autenticao for concluda com xito, o DRMManager despachar um objeto DRMAuthenticationCompleteEvent. Esse objeto contm um token de sesso. Voc pode salvar esse token para estabelecer sesses futuras, de forma que o usurio no precise fornecer suas credenciais de conta. Envie o token para o mtodo setAuthenticationToken() a fim de estabelecer uma nova sesso autenticada. (As configuraes do servidor que geraram o sinal determinam a expirao do token e outros atributos. O cdigo do aplicativo AIR no deve interpretar a estrutura de dados do token, porque a estrutura pode alterar atualizaes posteriores do AIR.) possvel transferir tokens de autenticao para outros computadores. Para proteger os tokens, armazene-os no depsito local criptografado do AIR. Consulte Armazenamento local criptografado na pgina 696 para obter mais informaes.

Eventos do DRMStatus
Flash Player 10.1 e posterior, Adobe AIR 1.5 e posterior O DRMManager despacha um objeto DRMStatusEvent aps uma chamada bem-sucedida para o mtodo loadVoucher(). Se um voucher for obtido, a propriedade detail (apenas no AIR) do objeto de evento ter um valor: "DRM.voucherObtained", e a propriedade voucher conter o objeto DRMVoucher. Se um voucher no for obtido, a propriedade detail (apenas no AIR) ainda ter o valor: "DRM.voucherObtained"; no entanto, a propriedade voucher ser null. Um voucher no pode ser obtido se, por exemplo, for utilizado LoadVoucherSetting de localOnly e no existir um voucher armazenado em cache localmente. Se a chamada loadVoucher() no for concluda com xito, talvez por causa de um erro de autenticao ou comunicao, o DRMManager despachar um objeto DRMErrorEvent ou DRMAuthenticationErrorEvent em vez disso.

Eventos DRMAuthenticationComplete
Flash Player 10.1 e posterior, Adobe AIR 1.5 e posterior O DRMManager despacha um objeto DRMAuthenticationCompleteEvent quando um usurio autenticado com xito por meio de uma chamada do mtodo authenticate(). O objeto DRMAuthenticationCompleteEvent contm um token reutilizvel que pode ser usado para persistir em autenticaes do usurio em sesses do aplicativo. Passe esse token para o mtodo setAuthenticationToken() do DRMManager, a fim de estabelecer novamente a sesso. (Os atributos do token como, por exemplo, sua expirao, so definidos pelo criador do token. A Adobe no fornece uma API para a examinar atributos de token).

Eventos DRMAuthenticationError
Flash Player 10.1 e posterior, Adobe AIR 1.5 e posterior O DRMManager despacha um objeto DRMAuthenticationErrorEvent quando um usurio no pode ser autenticado com xito por meio de uma chamada para os mtodos authenticate() ou setAuthenticationToken().

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de gerenciamento de direitos digitais

530

Uso da classe DRMContentData

Flash Player 10.1 e posterior, Adobe AIR 1.5 e posterior O objeto DRMContentData contm as propriedades dos metadados do contedo protegido pelo Flash Access. As propriedades DRMContentData contm as informaes necessrias para obter um voucher de licena para exibir o contedo, como essas. Voc pode utilizar a classe DRMContentData para obter o arquivo de metadados associado ao contedo, como descrito no Fluxo de trabalho detalhado na pgina 517. Para obter mais informaes, consulte a descrio da classe DRMContentData em Referncia do ActionScript 3.0 para a plataforma Adobe Flash.

Atualizando o Flash Player para suportar o Flash Access

Flash Player 10.1 e posterior Para suportar o Flash Access o Flash Player requer o mdulo do Flash Access. Quando o Flash Player tenta reproduzir contedo protegido, o tempo de execuo indica se o mdulo ou uma nova verso do Flash Player precisam ser baixados. Desta maneira, o Flash Player fornece aos desenvolvedores SWF a opo de no atualizar caso queiram. Na maioria dos casos, para reproduzir contedo protegido, os desenvolvedores de SWF atualizam para o mdulo requerido pelo Flash Access ou pelo player. Para atualizar, pode-se utilizar a API SystemUpdater para obter a ltima verso do mdulo Flash Access ou do Flash Player. A API SystemUpdater permite apenas uma atualizao por vez. O cdigo de erro 2201 indica que uma atualizao j est em andamento na ocorrncia atual do tempo de execuo ou em outra ocorrncia. Por exemplo, se uma atualizao est em andamento em uma ocorrncia do Flash Player no Internet Explorer, uma atualizao no poder ser executada em uma ocorrncia em execuo no Firefox. A API SystemUpdater suportada para plataformas de desktop apenas. Nota: Em verses do Flash Player anteriores a 10.1, utilize o mecanismo de atualizao suportado em verses anteriores do player (baixe e instale manualmente do site www.adobe.com ou ExpressInstall). O instalador do AIR tambm manipula atualizaes necessrias para o Flash Access e no suporta a API SystemUpdater.

Procurando um evento de atualizao

Flash Player 10.1 e posterior Quando uma atualizao do mdulo Flash Access necessria, o objeto NetStream envia um NetStatusEvent com um valor de cdigo DRM.UpdateNeeded. Este valor indica que o objeto NetStream no pode reproduzir o stream protegido com nenhum dos mdulos do Flash Access instalados. Procure por este evento e chame o seguinte cdigo:
SystemUpdater.update(flash.system.SystemUpdaterType.DRM)

Este cdigo atualiza o mdulo Flash Access instalado no player. A aprovao do usurio para esta atualizao de mdulo no necessria. Caso o mdulo Flash Access no seja encontrado, um erro exibido. Consulte o passo 3 do Fluxo de trabalho detalhado na pgina 517.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso de gerenciamento de direitos digitais

531

Nota: Caso play() chamado em um stream criptografado em players anteriores ao 10.1, um NetStatusEvent como valor de cdigo de NetStream.Play.StreamNotFound enviado. Em verses anteriores de players, utilize o mecanismo de atualizao suportado para estes players (baixe e instale manualmente do site www.adobe.com ou ExpressInstall). Quando uma atualizao para o prprio player necessria o objeto SystemUpdater envia um StatusEvent com um cdigo de DRM.UpdateNeededButIncompatible. Para uma atualizao do player, a aprovao do usurio necessria. Fornea em seu aplicativo um interface para que o usurio concorde e inicie a atualizao do player. Procure pelo evento StatusEvent e chame o seguinte cdigo:
SystemUpdater.update(flash.system.SystemUpdaterType.SYSTEM);

Este cdigo inicia a atualizao do player. Eventos adicionais da classe SystemUpdater esto documentados em Referncia do ActionScript 3.0 para a plataforma Adobe Flash. Depois que a atualizao do player estiver completo, o usurio redirecionado para a pgina onde a atualizao tem incio. O mdulo Flash Access baixado, e o stream pode ser reproduzido.

ltima atualizao em 29/3/2011

532

Captulo 26: Incluso de contedo em PDF no AIR

Adobe AIR 1.0 e posterior Os aplicativos em execuo no Adobe AIR podem produzir no s contedo SWF e HTML, mas tambm em PDF. Aplicativos AIR processam aplicativos em PDF usando a classe HTMLLoader, o mecanismo WebKit e o plug-in para navegador Adobe Reader. Em um aplicativo AIR, o contedo em PDF pode alongar-se pela atura e largura inteiras de seu aplicativo ou, como alternativa, como uma parte da interface. O plug-in de navegador do Adobe Reader controla a exibio de arquivos PDF em um aplicativo AIR. as modificaes na interface de barra de ferramentas do Reader (como controles de posio, ancoragem e visibilidade) persistem na visualizao subsequente de arquivos PDF nos aplicativos AIR e no navegador. Importante: Para processar contedo em PDF no AIR, o usurio deve ter o Adobe Reader ou Adobe Acrobat verso 8.1 ou posterior instalada.

Deteco de recurso de PDF

Adobe AIR 1.0 e posterior Se o usurio no tiver o Adobe Reader ou do Adobe Acrobat 8.1 ou posterior, o contedo PDF no ser exibido no aplicativo AIR. Para detectar se o usurio pode processar contedo em PDF, verifique primeiramente a propriedade HTMLLoader.pdfCapability. Essa propriedade est definida como uma das seguintes constantes da classe HTMLPDFCapability:
Constante HTMLPDFCapability.STATUS_OK Descrio Uma verso suficiente (8.1 ou posterior) do Adobe Reader detectada e o contedo em PDF pode ser carregado em um objeto HTMLLoader. No foi detectada nenhuma verso do Adobe Reader. Um objeto HTMLLoader no pode exibir contedo em PDF. O Adobe Reader foi detectado, mas a verso muito antiga. Um objeto HTMLLoader no pode exibir contedo em PDF. Uma verso suficiente (8.1 ou posterior) do Adobe Reader foi detectada, mas a verso do aplicativo configurada para lidar com contedo em PDF anterior ao Reader 8.1. Um objeto HTMLLoader no pode exibir contedo em PDF.

HTMLPDFCapability.ERROR_INSTALLED_READER_NOT_FOUND

HTMLPDFCapability.ERROR_INSTALLED_READER_TOO_OLD

HTMLPDFCapability.ERROR_PREFERRED_READER_TOO_OLD

No Windows, se o Adobe Acrobat ou o Acrobat Reader verso 7.x ou posterior estiver em execuo no sistema do usurio, essa verso ser usada, mesmo se houver instalada uma verso posterior que oferea suporte a PDF carregado. Nesse caso, se o valor da propriedade pdfCapability for HTMLPDFCapability.STATUS_OK, quando um aplicativo AIR tentar carregar o contedo em PDF, a verso antiga do Acrobat ou do Reader exibir um alerta (e nenhuma exceo ser lanada no aplicativo AIR). Se isso for uma possibilidade para os usurios finais, considere fornecer a eles instrues sobre como fechar o Acrobat enquanto o aplicativo executado. Pode ser conveniente exibir essas instrues se o contedo em PDF no for carregado em um intervalo de tempo aceitvel.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Incluso de contedo em PDF no AIR

533

No Linux, o AIR procura o Adobe Reader no CAMINHO exportado pelo usurio (se ele contiver o comando acroread) e no diretrio /opt/Adobe/Reader. O cdigo a seguir detecta se um usurio pode exibir contedo PDF em um aplicativo AIR. Se o usurio no puder exibir um PDF, o cdigo rastrear o cdigo de erro correspondente ao objeto de erro HTMLPDFCapability:
if(HTMLLoader.pdfCapability == HTMLPDFCapability.STATUS_OK) { trace("PDF content can be displayed"); } else { trace("PDF cannot be displayed. Error code:", HTMLLoader.pdfCapability); }

Carregamento de contedo em PDF

Adobe AIR 1.0 e posterior Voc pode adicionar um PDF a um aplicativo AIR criando uma ocorrncia HTMLLoader, definindo as dimenses e carregando o caminho de um PDF. O exemplo a seguir carrega um PDF de um site externo. Substitua a URLRequest com o caminho para um PDF externo disponvel.
var request:URLRequest = new URLRequest("http://www.example.com/test.pdf"); pdf = new HTMLLoader(); pdf.height = 800; pdf.width = 600; pdf.load(request); container.addChild(pdf);

Voc tambm pode carregar contedo de URLs de arquivos e esquemas de URL especficos do AIR, como app e appstorage. Por exemplo, o cdigo seguinte carrega o arquivo test.pdf no subdiretrio PDFs do diretrio do aplicativo: app:/js_api_reference.pdf Para obter mais informaes sobre esquemas de URL do AIR, consulte Esquemas de URI na pgina 803.

Gravando em script o contedo em PDF

Adobe AIR 1.0 e posterior Voc pode usar o JavaScript para controlar o contedo em PDF, do mesmo modo que em um pgina da Web no navegador. As extenses JavaScript para o Acrobat oferecem alguns recursos, entre eles:

Controle de ampliao e navegao de pgina Processamento de formulrios no documento Controle de eventos multimdia

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Incluso de contedo em PDF no AIR

534

Detalhes completos sobre extenses JavaScript para o Adobe Acrobat so fornecidos na Conexo de desenvolvedores do Adobe Acrobat, em http://www.adobe.com/devnet/acrobat/javascript.html.

Noes bsicas de comunicao HTML-PDF

Adobe AIR 1.0 e posterior O JavaScript em uma pgina HTML pode enviar uma mensagem para o JavaScript no contedo em PDF, chamando o mtodo postMessage() do objeto DOM representando o contedo em PDF. Por exemplo, considere o seguinte contedo em PDF incorporado:
<object id="PDFObj" data="test.pdf" type="application/pdf" width="100%" height="100%"/>

o cdigo JavaScript seguinte, no contedo HTML contido envia uma mensagem para o JavaScript no arquivo em PDF:
pdfObject = document.getElementById("PDFObj"); pdfObject.postMessage(["testMsg", "hello"]);

O arquivo em PDF pode incluirJavaScript para receber essa mensagem. Voc pode adicionar o cdigo JavaScript a arquivos em PDF em alguns contextos, incluindo os contextos em nvel de documento, pasta, pgina, campo e lote. Apenas o contexto em nvel de documento, que define scripts que so avaliados quando o documento em PDF aberto, discutido aqui. Um arquivo em PDF pode adicionar uma propriedade messageHandler ao objeto hostContainer. A propriedade messageHandler um objeto que define funes do manipulador para responder a mensagens. Por exemplo, o cdigo seguinte define a funo para tratar mensagens recebidas pelo arquivo em PDF a partir do continer host (que o contedo HTML incorporando o arquivo em PDF):
this.hostContainer.messageHandler = {onMessage: myOnMessage}; function myOnMessage(aMessage) { if(aMessage[0] == "testMsg") { app.alert("Test message: " + aMessage[1]); } else { app.alert("Error"); } }

O cdigo JavaScript na pgina HTML pode chamar o mtodo postMessage() do objeto PDF contido na pgina. Chamar esse mtodo envia uma mensagem ("Hello from HTML") para o JavaScript em nvel de documento no arquivo em PDF:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Incluso de contedo em PDF no AIR

535

<html> <head> <title>PDF Test</title> <script> function init() { pdfObject = document.getElementById("PDFObj"); try { pdfObject.postMessage(["alert", "Hello from HTML"]); } catch (e) { alert( "Error: \n name = " + e.name + "\n message = " + e.message ); } } </script> </head> <body onload='init()'> <object id="PDFObj" data="test.pdf" type="application/pdf" width="100%" height="100%"/> </body> </html>

Para obter um exemplo mais avanado e mais informaes sobre como utilizar o Acrobat 8 para adicionar JavaScript a um arquivo PDF, consulte Cross-scripting de contedo PDF no Adobe AIR.

Gravao em script de contedo em PDF do ActionScript

Adobe AIR 1.0 e posterior O cdigo do ActionScript (no contedo SWF) no pode se comunicar diretamente com o JavaScript no contedo em PDF. Entretanto, o ActionScript pode se comunicar com o JavaScript na pgina HTML carregada em um objeto HTMLLoader que carrega contedo em PDF, e o cdigo JavaScript pode se comunicar com o JavaScript no arquivo em PDF carregado. Para obter mais informaes, consulte Programao de HTML e JavaScript no AIR na pgina 967.

Limitaes conhecidas do contedo em PDF no AIR

Adobe AIR 1.0 e posterior O contedo em PDF no Adobe AIR tem as seguintes limitaes:

O contedo em PDF no exibido em uma janela (um objeto NativeWindow) que seja transparente (na qual a
propriedade transparent esteja definida como true).

A ordem de exibio de um arquivo em PDF funciona de forma diferente de outros objetos de exibio em um
aplicativo AIR. Embora o contedo em PDF se afixe corretamente de acordo com a ordem de exibio de HTML, ele sempre ficar por cima do contedo na ordem de exibio do aplicativo AIR.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Incluso de contedo em PDF no AIR

536

Se determinadas propriedades visuais de um objeto HTMLLoader que contenha um documento PDF forem
alteradas, o documento PDF se tornar invisvel. Essas propriedades incluem filters, alpha, rotation e scaling. Alterar essas propriedades torna o contedo em PDF invisvel at a redefinio das propriedades. O contedo em PDF tambm fica invisvel se voc alterar essas propriedades de contineres de objeto de exibio que contm o objeto HTMLLoader.

O contedo PDF fica visvel somente quando a propriedade scaleMode do objeto Stage do objeto NativeWindow
contendo o contedo PDF definida como StageScaleMode.NO_SCALE. Quando ela definida com outro valor, o contedo PDF no fica visvel.

Clicar em links para contedo dentro do arquivo em PDF atualiza a posio de rolagem do contedo em PDF.
Clicar em links para contedo fora do arquivo em PDF redireciona o objeto HTMLLoader que contm o PDF (mesmo que o destino de um link seja uma nova janela).

Fluxos de trabalho de comentrio de PDF no funcionam no AIR.

ltima atualizao em 29/3/2011

537

Captulo 27: Princpios bsicos da interao do usurio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Seu aplicativo pode criar a interatividade usando o ActionScript 3.0 para responder atividade do usurio. Essa seo supe que voc j est familiarizado com o modelo de eventos do ActionScript 3.0. Para obter mais informaes, consulte Manipulao de eventos na pgina 118.

Captura da entrada do usurio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A interao do usurio, por meio do teclado, do mouse, da cmera ou de uma combinao desses dispositivos, a base da interatividade. No ActionScript 3.0, identificar e responder interao do usurio envolve principalmente ouvir eventos. A classe InteractiveObject, uma subclasse de DisplayObject, fornece a estrutura comum dos eventos e a funcionalidade necessria para manipular a interao do usurio. Voc no cria diretamente uma ocorrncia da classe InteractiveObject. Em vez disso, objetos de exibio como SimpleButton, Sprite, TextField e vrios componentes da ferramenta de autoria do Flash e do Flex herdam o modelo de interao do usurio dessa classe e, desse modo, compartilham uma estrutura comum. Isso significa que as tcnicas aprendidas e o cdigo que voc grava para manipular a interao do usurio em um objeto derivado de InteractiveObject so aplicveis a todos os outros usurios. Conceitos e termos importantes importante que voc se familiarize com os seguintes termos-chave de interao do usurio antes de continuar:
Cdigo de caractere Um cdigo numrico que representa um caractere no conjunto de caracteres atual (associado a

uma tecla que est sendo pressionada no teclado). Por exemplo, D e d tm cdigos de caractere diferentes embora tenham sido criados pela mesma tecla do teclado do alfabeto ingls.
Menu de contexto Menu que aparece quando um usurio clica com o boto direito do mouse ou usa uma combinao especfica do teclado-mouse. Os comandos do menu de contexto em geral so aplicados diretamente no que foi clicado. Por exemplo, um menu de contexto de uma imagem pode conter um comando para mostrar a imagem em uma janela separada e um comando para fazer download dessa imagem. Foco Indicao de que um elemento selecionado est ativo e o destino da interao do teclado ou do mouse. Cdigo de tecla Cdigo numrico que corresponde a uma tecla fsica no teclado.

Mais tpicos da Ajuda

InteractiveObject Teclado

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Princpios bsicos da interao do usurio

538

Mouse ContextMenu

Gerenciamento do foco
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Um objeto interativo pode receber o foco, programaticamente ou por meio de uma ao do usurio. Alm disso, se a propriedade tabEnabled estiver definida como true, o usurio poder passar o foco de um objeto para outro pressionando a tecla Tab. Observe que o valor de tabEnabled false por padro, exceto nos seguintes casos:

Para um objeto SimpleButton, o valor true. Para um campo de texto de entrada, o valor true. Para um objeto Sprite ou MovieClip com buttonMode definido como true, o valor true.
Em cada uma dessas situaes, voc pode adicionar um ouvinte para FocusEvent.FOCUS_IN ou FocusEvent.FOCUS_OUT a fim de fornecer outros comportamentos quando o foco for alterado. Isso til especialmente para campos de texto e formulrios, mas tambm pode ser usado em entidades grficas, clipes de filme ou qualquer objeto herdado da classe InteractiveObject. O exemplo a seguir mostra como ativar o ciclo do foco com a tecla Tab e como responder ao evento de foco subseqente. Nesse caso, cada quadrado muda de cor assim que recebe o foco. Nota: O Flash Professional usa atalhos do teclado para gerenciar o foco; desse modo, para simular o gerenciamento do foco corretamente, os arquivos SWF devem ser testados em um navegador ou AIR, no no Flash.
var var var var var var for { rows:uint = 10; cols:uint = 10; rowSpacing:uint = 25; colSpacing:uint = 25; i:uint; j:uint; (i = 0; i < rows; i++) for (j = 0; j < cols; j++) { createSquare(j * colSpacing, i * rowSpacing, (i * cols) + j); } } function createSquare(startX:Number, startY:Number, tabNumber:uint):void { var square:Sprite = new Sprite(); square.graphics.beginFill(0x000000); square.graphics.drawRect(0, 0, colSpacing, rowSpacing); square.graphics.endFill(); square.x = startX;

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Princpios bsicos da interao do usurio

539

square.y = startY; square.tabEnabled = true; square.tabIndex = tabNumber; square.addEventListener(FocusEvent.FOCUS_IN, changeColor); addChild(square); } function changeColor(event:FocusEvent):void { event.target.transform.colorTransform = getRandomColor(); } function getRandomColor():ColorTransform { // Generate random values for the red, green, and blue color channels. var red:Number = (Math.random() * 512) - 255; var green:Number = (Math.random() * 512) - 255; var blue:Number = (Math.random() * 512) - 255; // Create and return a ColorTransform object with the random colors. return new ColorTransform(1, 1, 1, 1, red, green, blue, 0); }

Descobrindo tipos de entrada

Flash Player 10.1 e posterior, Adobe AIR 2 e posterior As verses do Flash Player 10.1 e do Adobe AIR 2 introduziram a habilidade de testar o ambiente de tempo de execuo em relao ao suporte de tipos de entrada especificos. Voc pode utilizar ActionScript para testar se o dispositivo no qual o tempo de execuo est implantado:

Suporta entrada de por meio de stylus ou de dedo (ou nenhuma entrada de toque). Tem um teclado virtual ou fsico para o usurio (ou nenhum teclado). Mostra um cursor (caso contrrio, recursos que dependem do posicionamento do cursor sobre um objeto no
funcionaro). As APIs ActionScript de descoberta de entradas incluem:

flash.system.Capabilities.touchscreenType property: Um valor fornecido em tempo de execuo indica que o tipo

de entrada posui suporte no ambiente atual.

classe flash.system.TouchScreenType: Uma classe de constantes de valor de enumerao para a propriedade

Capabilities.touchscreenType.

propriedade flash.ui.Mouse.supportsCursor: Um valor fornecido no tempo de execuo indicando se um cursor

persistente est disponvel ou no.

propriedade flash.ui.Keyboard.physicalKeyboardType: Um valor fornecido no tempo de execuo indicando se um

teclado completo fsico est disponvel ou apenas um teclado numrico ou nenhum teclado.

classe flash.ui.KeyboardType : Uma classe de constantes de valor de enumerao para a propriedade

flash.ui.Keyboard.physicalKeyboardType.

propriedade flash.ui.Keyboard.hasVirtualKeyboard: Um valor fornecido no tempo de execuo indicando se um

teclado virtual fornecido ao usurio (no lugar de um teclado fsico ou em adio a um teclado fsico).

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Princpios bsicos da interao do usurio

540

As APIs de descoberta de entradas permitem que voc aproveite das capacidades do dispositivo do usurio ou fornecem alternativas quando essas capacidades no estejam disponveis. Estas APIs so especialmente uteis para o desenvolvimento de aplicativos mveis e sensveis ao toque. Por exemplo, se houver uma interface para um dispositivo mvel com botes pequenos para uso de stylus, voc pode fornecer uma interface alternativa com botes maiores para um usurio que utiliza toques dos dedos como entrada. O seguinte cdigo se refere a um aplicativo que possui uma funo createStylusUI() que atribui um conjunto de elementos de interface do usurio apropriados para interao com stylus. Outra funo, chamada de createTouchUI(), atribui outro conjunto de elementos de interface do usurio apropriados para interao com dedos:
if(Capabilities.touchscreenType == TouchscreenType.STYLUS ){ //Construct the user interface using small buttons for a stylus //and allow more screen space for other visual content createStylusUI(); } else if(Capabilities.touchscreenType = TouchscreenType.FINGER){ //Construct the user interface using larger buttons //to capture a larger point of contact with the device createTouchUI(); }

Quando estiver desenvolvendo aplicativos para ambientes de entradas diferentes, considere o seguinte grfico:
Ambiente Desktop tradicional supportsCursor true touchscreenType == FINGER false true touchscreenType == STYLUS touchscreenType == NONE false false true false

Dispositivos de tela false sensvel ao toque capacitivos (tablets, PDAs e telefones que detectam toques sutis, como o iPhone da Apple ou o Palm Pre) Dispositivos de tela false sensvel ao toque resistivos (tablets, PDAs e telefones que detectam contatos de alta presso precisos, como o HTC Fuze) Dispositivos que no tem tela sensvel ao toque (telefones bsicos e disposistivos que executam aplicativos, mas no possuem telas que detectem contato) false

false

true

false

false

false

true

Nota: Plataformas de dispositivos diferentes podem suportar vrias combinaes de tipos de entradas. Utilize este grfico como um guia geral.

ltima atualizao em 29/3/2011

541

Captulo 28: Entrada do teclado

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Seu aplicativo pode capturar e responder entrada do teclado e pode manipular um IME para permitir que os usurios digitem caracteres em texto no-ASCII em idiomas de mltiplos bytes. Essa seo supe que voc j est familiarizado com o modelo de eventos do ActionScript 3.0. Para obter mais informaes, consulte Manipulao de eventos na pgina 118. Para obter informaes sobre como descobrir que tipo de suporte teclado est disponvel (como fsico, virtual alfanumrico ou numrico de 12 botes) durante o tempo de execuo, consulte Descobrindo tipos de entrada na pgina 539. Um Editor de mtodo de entrada (Input Method Editor (IME)) permite que os usurios digitem caracteres complexos e smbolos, utilizando um teclado padro. Voc pode utilizar classes IME para permitir que os usurios usufruam das vantagens do IME do sistema em seus aplicativos.

Mais tpicos da Ajuda

flash.events.KeyboardEvent flash.system.IME

Captura da entrada do teclado

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os objetos de exibio que herdam o modelo de interao da classe InteractiveObject podem responder aos eventos de teclado usando ouvintes de eventos. Voc pode colocar, por exemplo, um ouvinte de eventos no palco para ouvir e responder entrada do teclado. No exemplo a seguir, um ouvinte de eventos captura um pressionamento de tecla e as propriedades de cdigo e nome da tecla so exibidos:
function reportKeyDown(event:KeyboardEvent):void { trace("Key Pressed: " + String.fromCharCode(event.charCode) + " (character code: " + event.charCode + ")"); } stage.addEventListener(KeyboardEvent.KEY_DOWN, reportKeyDown);

Algumas teclas, como a tecla Ctrl, geram eventos embora no tenha nenhuma representao de glifo. No exemplo de cdigo anterior, o ouvinte de eventos de teclado capturou a entrada do teclado para todo o palco. Voc tambm pode gravar um ouvinte de eventos para um objeto de exibio especfico no palco; esse ouvinte de eventos acionado quando o objeto est em foco. No exemplo a seguir, os pressionamentos de tecla so refletidos no painel Sada somente quando o usurio digita dentro da ocorrncia TextField. Manter a tecla Shift temporariamente pressionada faz com que a cor da borda de TextField mude para vermelho. Esse cdigo supe a existncia de uma ocorrncia TextField chamada tf no palco.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Entrada do teclado

542

tf.border = true; tf.type = "input"; tf.addEventListener(KeyboardEvent.KEY_DOWN,reportKeyDown); tf.addEventListener(KeyboardEvent.KEY_UP,reportKeyUp); function reportKeyDown(event:KeyboardEvent):void { trace("Key Pressed: " + String.fromCharCode(event.charCode) + " (key code: " + event.keyCode + " character code: " + event.charCode + ")"); if (event.keyCode == Keyboard.SHIFT) tf.borderColor = 0xFF0000; } function reportKeyUp(event:KeyboardEvent):void { trace("Key Released: " + String.fromCharCode(event.charCode) + " (key code: " + event.keyCode + " character code: " + event.charCode + ")"); if (event.keyCode == Keyboard.SHIFT) { tf.borderColor = 0x000000; } }

A classe TextField tambm registra um evento textInput que pode ser ouvido quando um usurio insere algum texto. Para obter mais informaes, consulte Captura de entrada de texto na pgina 364. Nota: No tempo de execuo do AIR, um evento de teclado pode ser cancelado. No tempo de execuo do Flash Player, o evento de teclado no pode ser cancelado.

Cdigos de teclas e de cdigos de caracteres

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc pode acessar as propriedades keyCode e charCode de um evento de teclado para determinar qual tecla foi pressionada e, em seguida, acionar outras aes. A propriedade keyCode um valor numrico que corresponde ao valor de uma tecla no teclado. A propriedade charCode o valor numrico dessa tecla no conjunto de caracteres atual. O conjunto de caracteres padro UTF-8, que oferece suporte para ASCII. A principal diferena entre o cdigo de tecla e os valores de caractere est no fato de o cdigo de tecla representar uma tecla especfica do teclado (o valor 1 de um teclado diferente do valor 1 na linha superior, mas a tecla que gera 1 e a que gera ! so iguais), enquanto o valor de caractere representa um caractere especfico (os caracteres R e r so diferentes). Nota: Consulte as correlaes entre as teclas e seus valores de cdigos de caracteres em ASCII na classe flash.ui.Keyboard da Referncia do ActionScript 3.0 para a plataforma Adobe Flash. O mapeamento entre as teclas e os cdigos de tecla dependem do dispositivo e do sistema operacional. Devido a isso, no use mapeamentos de tecla para acionar comandos. Em vez disso, use os valores de constantes predefinidos fornecidos pela classe Keyboard para fazer referncia s propriedades keyCode adequadas. Por exemplo, em vez de usar o mapeamento para a tecla Shift, use a constante Keyboard.SHIFT (como mostra o cdigo de exemplo anterior).

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Entrada do teclado

543

Precedncia de KeyboardEvent
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Assim como outros eventos, a seqncia de eventos de teclado determinada pela hierarquia de objetos de exibio, no pela ordem em que os mtodos addEventListener() so atribudos no cdigo. Suponha, por exemplo, que voc coloque um campo de texto chamado tf em um clipe de filme chamado container e adicione um ouvinte de eventos para um evento de teclado nas duas ocorrncias, como mostra o exemplo a seguir:
container.addEventListener(KeyboardEvent.KEY_DOWN,reportKeyDown); container.tf.border = true; container.tf.type = "input"; container.tf.addEventListener(KeyboardEvent.KEY_DOWN,reportKeyDown); function reportKeyDown(event:KeyboardEvent):void { trace(event.currentTarget.name + " hears key press: " + String.fromCharCode(event.charCode) + " (key code: " + event.keyCode + " character code: " + event.charCode + ")"); }

Como h um ouvinte no campo de texto e no recipiente pai, a funo reportKeyDown() chamada duas vezes para cada pressionamento de tecla em TextField. Para cada tecla pressionada, o campo de texto envia um evento antes que o clipe de filme container faa isso. O sistema operacional e o navegador da Web processam eventos de teclado antes do Adobe Flash Player ou AIR. No Microsoft Internet Explorer, por exemplo, pressionar Ctrl+W fecha a janela do navegador antes que qualquer arquivo SWF contido envie um evento de teclado.

Uso da classe IME

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe IME permite manipular o IME do sistema operacional de dentro do Flash Player ou do Adobe AIR. Usando o ActionScript, possvel determinar o seguinte:

Se um IME est instalado no computador do usurio (Capabilities.hasIME) Se o IME est ativado ou desativado no computador do usurio (IME.enabled) O modo de converso do IME atual est usando (IME.conversionMode)
possvel associar um campo de texto de entrada a um contexto de IME especfico. Ao alternar entre campos de texto, tambm possvel alternar o IME entre Hiragana (japons), nmeros de largura total, nmeros de meia largura, entrada direta e assim por diante. Um IME permite que os usurios digitem caracteres de texto no-ASCII em idiomas com vrios bytes, como chins, japons e coreano. Para obter mais informaes sobre como trabalhar com IMEs, consulte a documentao do sistema operacional no qual voc est desenvolvendo o aplicativo. Para obter recursos adicionais, consulte os seguintes sites:

http://www.msdn.microsoft.com/goglobal/ http://developer.apple.com/documentation/ http://www.java.sun.com/ ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Entrada do teclado

544

Nota: Se o IME no estiver ativo no computador do usurio, chamadas para mtodos ou propriedades do IME, que no sejam Capabilities.hasIME, falharo. Depois de ativar manualmente o IME, chamadas subseqentes do ActionScript para mtodos e propriedades do IME funcionaro conforme o esperado. Por exemplo, se estiver usando um IME japons, voc dever ativ-lo para poder chamar qualquer mtodo ou propriedade do IME.

Verificao da instalao e ativao do IME

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Antes de chamar qualquer um dos mtodos ou propriedades do IME, voc deve sempre verificar se o computador do usurio tem um IME instalado e ativado. O cdigo a seguir ilustra como verificar se o usurio tem um IME instalado e ativo antes de chamar qualquer mtodo:
if (Capabilities.hasIME) { if (IME.enabled) { trace("IME is installed and enabled."); } else { trace("IME is installed but not enabled. Please enable your IME and try again."); } } else { trace("IME is not installed. Please install an IME and try again."); }

O cdigo anterior primeiro verifica se o usurio tem um IME instalado usando a propriedade Capabilities.hasIME. Se essa propriedade estiver definida como true, o cdigo verificar se o IME do usurio est ativado usando a propriedade IME.enabled.

Determinao de qual modo de converso do IME est ativado

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Ao criar aplicativos multilnge, talvez seja necessrio determinar qual modo de converso est ativo para o usurio. O cdigo a seguir demonstra como verificar se o usurio tem um IME instalado e, nesse caso, qual modo de converso do IME est ativo no momento:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Entrada do teclado

545

if (Capabilities.hasIME) { switch (IME.conversionMode) { case IMEConversionMode.ALPHANUMERIC_FULL: tf.text = "Current conversion mode is alphanumeric (full-width)."; break; case IMEConversionMode.ALPHANUMERIC_HALF: tf.text = "Current conversion mode is alphanumeric (half-width)."; break; case IMEConversionMode.CHINESE: tf.text = "Current conversion mode is Chinese."; break; case IMEConversionMode.JAPANESE_HIRAGANA: tf.text = "Current conversion mode is Japananese Hiragana."; break; case IMEConversionMode.JAPANESE_KATAKANA_FULL: tf.text = "Current conversion mode is Japanese Katakana (full-width)."; break; case IMEConversionMode.JAPANESE_KATAKANA_HALF: tf.text = "Current conversion mode is Japanese Katakana (half-width)."; break; case IMEConversionMode.KOREAN: tf.text = "Current conversion mode is Korean."; break; default: tf.text = "Current conversion mode is " + IME.conversionMode + "."; break; } } else { tf.text = "Please install an IME and try again."; }

O cdigo anterior primeiro verifica se o usurio tem um IME instalado. Em seguida, ele verifica qual modo de converso o IME atual est usando, comparando a propriedade IME.conversionMode com cada uma das constantes na classe IMEConversionMode.

Configurao do modo de converso do IME

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Quando voc altera o modo de converso do IME do usurio, necessrio verificar se o cdigo est inserido em um bloco try..catch, porque a configurao de um modo de converso usando a propriedade conversionMode poder emitir um erro, se o IME no puder definir o modo de converso. O cdigo a seguir demonstra como usar um bloco try..catch ao definir a propriedade IME.conversionMode:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Entrada do teclado

546

var statusText:TextField = new TextField; statusText.autoSize = TextFieldAutoSize.LEFT; addChild(statusText); if (Capabilities.hasIME) { try { IME.enabled = true; IME.conversionMode = IMEConversionMode.KOREAN; statusText.text = "Conversion mode is " + IME.conversionMode + "."; } catch (error:Error) { statusText.text = "Unable to set conversion mode.\n" + error.message; } }

O cdigo anterior primeiro cria um campo de texto que usado para exibir uma mensagem de status para o usurio. Em seguida, se o IME estiver instalado, o cdigo ativar o IME e definir o modo de converso como coreano. Se o computador do usurio no tiver um IME coreano instalado, o Flash Player ou o AIR emitir um erro que ser capturado pelo bloco try..catch. O bloco try..catch exibe a mensagem de erro no campo de texto criado anteriormente.

Desativao do IME para determinados campos de texto

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Em alguns casos, convm desativar o IME do usurio enquanto ele digita caracteres. Por exemplo, se voc tiver um campo de texto que aceita apenas entrada numrica, conveniente ativar o IME e diminuir a velocidade da entrada de dados. O exemplo a seguir demonstra como possvel ouvir os eventos FocusEvent.FOCUS_IN e FocusEvent.FOCUS_OUT e desativar o IME do usurio de maneira correspondente:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Entrada do teclado

547

var phoneTxt:TextField = new TextField(); var nameTxt:TextField = new TextField(); phoneTxt.type = TextFieldType.INPUT; phoneTxt.addEventListener(FocusEvent.FOCUS_IN, focusInHandler); phoneTxt.addEventListener(FocusEvent.FOCUS_OUT, focusOutHandler); phoneTxt.restrict = "0-9"; phoneTxt.width = 100; phoneTxt.height = 18; phoneTxt.background = true; phoneTxt.border = true; addChild(phoneTxt); nameField.type = TextFieldType.INPUT; nameField.x = 120; nameField.width = 100; nameField.height = 18; nameField.background = true; nameField.border = true; addChild(nameField); function focusInHandler(event:FocusEvent):void { if (Capabilities.hasIME) { IME.enabled = false; } } function focusOutHandler(event:FocusEvent):void { if (Capabilities.hasIME) { IME.enabled = true; } }

Esse exemplo cria dois campos de texto de entrada, phoneTxt e nameTxt e, em seguida, adiciona dois ouvintes de eventos ao campo de texto phoneTxt. Quando o usurio define o foco para o campo de texto phoneTxtum evento FocusEvent.FOCUS_IN despachado e o IME desativado. Quando o campo de texto phoneTxt perde o foco, o evento FocusEvent.FOCUS_OUT despachado para reativar o IME.

Ouvir eventos de composio do IME

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os eventos de composio do IME so despachados quando uma string de composio est sendo definida. Por exemplo, se o usurio tiver o IME habilitado e ativo e digitar uma string em japons, o evento IMEEvent.IME_COMPOSITION despachar assim que o usurio selecionar a string da composio. Para ouvir o evento IMEEvent.IME_COMPOSITION, necessrio adicionar um ouvinte de eventos propriedade esttica ime na classe System (flash.system.System.ime.addEventListener(...)), conforme mostrado no exemplo a seguir:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Entrada do teclado

548

var inputTxt:TextField; var outputTxt:TextField; inputTxt = new TextField(); inputTxt.type = TextFieldType.INPUT; inputTxt.width = 200; inputTxt.height = 18; inputTxt.border = true; inputTxt.background = true; addChild(inputTxt); outputTxt = new TextField(); outputTxt.autoSize = TextFieldAutoSize.LEFT; outputTxt.y = 20; addChild(outputTxt); if (Capabilities.hasIME) { IME.enabled = true; try { IME.conversionMode = IMEConversionMode.JAPANESE_HIRAGANA; } catch (error:Error) { outputTxt.text = "Unable to change IME."; } System.ime.addEventListener(IMEEvent.IME_COMPOSITION, imeCompositionHandler); } else { outputTxt.text = "Please install IME and try again."; } function imeCompositionHandler(event:IMEEvent):void { outputTxt.text = "you typed: " + event.text; }

O cdigo anterior cria dois campos de texto e os adiciona lista de exibio. O primeiro campo de texto, inputTxt, um campo de texto de entrada que permite que o usurio digite texto japons. O segundo campo de texto, outputTxt, um campo de texto dinmico que exibe mensagens de erro para o usurio ou ecoa a string em japons que o usurio digita no campo de texto inputTxt.

Teclados virtuais
Flash Player 10.2 e posterior, AIR 2.6 e posterior Dispositivos mveis tais como telefones e tablets frequentemente fornecem um software de teclado virtual em vez de um teclado fsico. As classes da API Flash permitem:

Detectar quando o teclado virtual exibido e quando fechado. Impedir a exibio do teclado virtual.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Entrada do teclado

549

Determinar a rea do palco obscurecida pelo teclado virtual. Criar objetos interativos que ativam o teclado virtual quando esto em foco. (No suportado pelos aplicativos do
AIR que rodam no iOS.)

(Somente para o AIR) Desativa o comportamento de panorama automtico para que o seu aplicativo possa
modificar sua prpria exibio a fim de se adaptar ao teclado.

Controle do comportamento do teclado virtual

O tempo de execuo abre automaticamente o teclado virtual quando o usurio toca dentro de um campo de texto ou um objeto interativo especialmente configurado. Quando o teclado aberto, o tempo de execuo segue as convenes de plataforma nativa deslocando e redimensionando o contedo do aplicativo para que o usurio possa ver o texto enquanto digita. Quando o teclado aberto, o objeto focado envia os seguintes eventos em seqncia: Evento softKeyboardActivating enviado imediatamente antes do teclado comear a aparecer na plataforma. Se voc chamar o mtodo preventDefault() do objeto do evento enviado, o teclado virtual no aberto.
softKeyboardActivate evento enviado aps a manipulao do evento softKeyboardActivating terminar. Quando o objeto focado envia esse evento, a propriedadesoftKeyboardRect do objeto Stage foi atualizado para refletir a rea da plataforma obscurecida pelo teclado virtual. Este evento no pode ser cancelado.

Nota: Se o teclado muda de tamanho, quando o usurio muda o tipo de teclado, por exemplo, o objeto focado envia um segundo evento softKeyboardActivate. Evento softKeyboardDeactivate enviado quando o teclado virtual fechado por algum motivo. Este evento no pode ser cancelado. O exemplo a seguir adiciona dois objetos TextField na plataforma. O TextField superior impede o teclado de surgir quando voc toca o campo e fecha-o se j estiver aparecendo. O TextField inferior demonstra o comportamento padro. O exemplo informa os eventos de teclado de software enviados por ambos os campos de texto.
package { import flash.display.Sprite; import flash.text.TextField; import flash.text.TextFieldType; import flash.events.SoftKeyboardEvent; public class SoftKeyboardEventExample extends Sprite { private var tf1:TextField = new TextField(); private var tf2:TextField = new TextField(); public function SoftKeyboardEventExample() { tf1.width = this.stage.stageWidth; tf1.type = TextFieldType.INPUT; tf1.border = true; this.addChild( tf1 ); tf1.addEventListener( SoftKeyboardEvent.SOFT_KEYBOARD_ACTIVATING, preventSoftKe yboard ); tf1.addEventListener( SoftKeyboardEvent.SOFT_KEYBOARD_ACTIVATE, preventSoftKe yboard ); tf1.addEventListener( SoftKeyboardEvent.SOFT_KEYBOARD_DEACTIVATE, preventSoftKeyboard );

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Entrada do teclado

550

tf2.border = true; tf2.type = TextFieldType.INPUT; tf2.width = this.stage.stageWidth; tf2.y = tf1.y + tf1.height + 30; this.addChild( tf2 ); tf2.addEventListener( SoftKeyboardEvent.SOFT_KEYBOARD_ACTIVATING, allowSoftKeyboard ); tf2.addEventListener( SoftKeyboardEvent.SOFT_KEYBOARD_ACTIVATE, allowSoftKeyboard ); tf2.addEventListener( SoftKeyboardEvent.SOFT_KEYBOARD_DEACTIVATE, allowSoftKeyboard); } private function preventSoftKeyboard( event:SoftKeyboardEvent ):void { event.preventDefault(); this.stage.focus = null; //close the keyboard, if raised trace( "tf1 dispatched: " + event.type + " -- " + event.triggerType ); } private function allowSoftKeyboard( event:SoftKeyboardEvent ) :void { trace( "tf2 dispatched: " + event.type + " -- " + event.triggerType ); } } }

Adicionando suporte a teclado virtual para objetos interativos

Flash Player 10.2 e superior, AIR 2.6 e superior (mas no suportado no iOS) Geralmente o teclado virtual s aberto quando um objeto TextField tocado. Voc pode configurar uma instncia da classe InteractiveObject para abrir o teclado virtual quando esse est em foco. Para configurar uma instncia do InteractiveObject para abrir o teclado virtual, defina sua propriedade needsSoftKeyboard como true. Sempre que o objeto atribudo propriedade focus do palco, o teclado virtual abrese automaticamente. Alm disso, voc pode ativar o teclado virtual chamando o mtodo requestSoftKeyboard() do InteractiveObject. O exemplo seguinte ilustra como voc pode programar um InteractiveObject para atuar como um campo de entrada de texto. A classe TextInput exibida no exemplo define a propriedade needsSoftKeyboard para que o teclado seja ativado quando necessrio. O objeto escuta ento os eventos keyDown e insere o caractere digitado no campo. O exemplo usa o mecanismo de texto do Flash para acrescentar e exibir qualquer texto digitado e manipula alguns eventos importantes. Para simplificar, o exemplo no implementa um campo de texto com recursos completos.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Entrada do teclado

551

package { import import import import import import import import import import

flash.geom.Rectangle; flash.display.Sprite; flash.text.engine.TextElement; flash.text.engine.TextBlock; flash.events.MouseEvent; flash.events.FocusEvent; flash.events.KeyboardEvent; flash.text.engine.TextLine; flash.text.engine.ElementFormat; flash.events.Event;

public class TextInput extends Sprite { public var text:String = " "; public var textSize:Number = 24; public var textColor:uint = 0x000000; private var _bounds:Rectangle = new Rectangle( 0, 0, 100, textSize ); private var textElement: TextElement; private var textBlock:TextBlock = new TextBlock(); public function TextInput( text:String = "" ) { this.text = text; this.scrollRect = _bounds; this.focusRect= false; //Enable keyboard support this.needsSoftKeyboard = true; this.addEventListener(MouseEvent.MOUSE_DOWN, onSelect); this.addEventListener(FocusEvent.FOCUS_IN, onFocusIn); this.addEventListener(FocusEvent.FOCUS_OUT, onFocusOut); //Setup text engine textElement = new TextElement( text, new ElementFormat( null, textSize, textColor ) ); textBlock.content = textElement; var firstLine:TextLine = textBlock.createTextLine( null, _bounds.width - 8 ); firstLine.x = 4; firstLine.y = 4 + firstLine.totalHeight; this.addChild( firstLine ); } private function onSelect( event:MouseEvent ):void { stage.focus = this; } private function onFocusIn( event:FocusEvent ):void { this.addEventListener( KeyboardEvent.KEY_DOWN, onKey ); } private function onFocusOut( event:FocusEvent ):void { this.removeEventListener( KeyboardEvent.KEY_UP, onKey ); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Entrada do teclado

552

private function onKey( event:KeyboardEvent ):void { textElement.replaceText( textElement.text.length, textElement.text.length, String.fromCharCode( event.charCode ) ); updateText(); } public function set bounds( newBounds:Rectangle ):void { _bounds = newBounds.clone(); drawBackground(); updateText(); this.scrollRect = _bounds; //force update to focus rect, if needed if( this.stage!= null && this.focusRect && this.stage.focus == this ) this.stage.focus = this; } private function updateText():void { //clear text lines while( this.numChildren > 0 ) this.removeChildAt( 0 ); //and recreate them var textLine:TextLine = textBlock.createTextLine( null, _bounds.width - 8); while ( textLine) { textLine.x = 4; if( textLine.previousLine != null ) { textLine.y = textLine.previousLine.y + textLine.previousLine.totalHeight + 2; } else { textLine.y = 4 + textLine.totalHeight; } this.addChild(textLine); textLine = textBlock.createTextLine(textLine, _bounds.width - 8 ); } } private function drawBackground():void { //draw background and border for the field this.graphics.clear(); this.graphics.beginFill( 0xededed ); this.graphics.lineStyle( 1, 0x000000 ); this.graphics.drawRect( _bounds.x + 2, _bounds.y + 2, _bounds.width - 4, _bounds.height - 4); this.graphics.endFill(); } } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Entrada do teclado

553

A seguinte classe de aplicao principal ilustra como usar a classe TextInput e gerenciar o layout do aplicativo quando o teclado estiver ativado ou quando a orientao do dispositivo for alterada. A classe main cria um objeto TextInput e define seus limites para preencher o palco. A classe ajusta o tamanho do objeto TextInput quando o teclado virtual ativado ou quando o palco muda de tamanho. A classe escuta os eventos do teclado virtual a partir do objeto TextInput e redimensiona os eventos a partir do palco. Independentemente da causa do evento, o aplicativo determina a rea visvel do palco e redimensiona o controle de entrada para preench-lo. Naturalmente, em uma aplicao real, voc precisaria de um algoritmo de layout mais sofisticado.
package { flash.display.MovieClip; flash.events.SoftKeyboardEvent; flash.geom.Rectangle; flash.events.Event; flash.display.StageScaleMode; flash.display.StageAlign;

import import import import import import

public class CustomTextField extends MovieClip { private var customField:TextInput = new TextInput("Input text: "); public function CustomTextField() { this.stage.scaleMode = StageScaleMode.NO_SCALE; this.stage.align = StageAlign.TOP_LEFT; this.addChild( customField ); customField.bounds = new Rectangle( 0, 0, this.stage.stageWidth, this.stage.stageHeight ); //track soft keyboard and stage resize events customField.addEventListener(SoftKeyboardEvent.SOFT_KEYBOARD_ACTIVATE, onDisplayAreaChange ); customField.addEventListener(SoftKeyboardEvent.SOFT_KEYBOARD_DEACTIVATE, onDisplayAreaChange ); this.stage.addEventListener( Event.RESIZE, onDisplayAreaChange ); } private function onDisplayAreaChange( event:Event ):void { //Fill the stage if possible, but avoid the area covered by a keyboard var desiredBounds = new Rectangle( 0, 0, this.stage.stageWidth, this.stage.stageHeight ); if( this.stage.stageHeight - this.stage.softKeyboardRect.height < desiredBounds.height ) desiredBounds.height = this.stage.stageHeight this.stage.softKeyboardRect.height; customField.bounds = desiredBounds; } } }

Nota: O palco despacha somente eventos de redimensionamento em resposta a uma alterao de orientao quando a propriedade scaleMode definida como noScale. Em outros modos, as dimenses do palco no se alteram; em vez disso, o contedo escalado para compensar.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Entrada do teclado

554

Tratamento de mudanas de exibio do aplicativo

AIR 2.6 e posterior No AIR, voc pode desativar o panorama padro e redimensionar o comportamento associado ativao do teclado virtual, definindo o elemento softKeyboardBehavior, no descritor do aplicativo, como none:
<softKeyboardBehavior>none</softKeyboardBehavior>

Quando voc desativar o comportamento automtico, responsabilidade do seu aplicativo fazer quaisquer ajustes necessrios para a exibio do aplicativo. Um evento softKeyboardActivate despachado quando o teclado aberto. No momento em que o evento softKeyboardActivate enviado, a propriedade softKeyboardRect do palco contm as dimenses da rea obscurecida pelo teclado aberto. Use essas dimenses para mover ou redimensionar seu contedo, de maneira que esse seja exibido adequadamente enquanto o teclado aberto e o usurio digita. (Quando o teclado est fechado, as dimenses do retngulo softKeyboardRect so todas zero.) Quando o teclado fechado, um evento softKeyboardDeactivate enviado, e possvel voltar a exibio do aplicativo ao normal.
package { import import import import import import import import flash.display.MovieClip; flash.events.SoftKeyboardEvent; flash.events.Event; flash.display.StageScaleMode; flash.display.StageAlign; flash.display.InteractiveObject; flash.text.TextFieldType; flash.text.TextField;

public class PanningExample extends MovieClip { private var textField:TextField = new TextField(); public function PanningExample() { this.stage.scaleMode = StageScaleMode.NO_SCALE; this.stage.align = StageAlign.TOP_LEFT; textField.y = this.stage.stageHeight - 201; textField.width = this.stage.stageWidth; textField.height = 200; textField.type = TextFieldType.INPUT; textField.border = true; textField.wordWrap = true; textField.multiline = true; this.addChild( textField ); //track soft keyboard and stage resize events textField.addEventListener(SoftKeyboardEvent.SOFT_KEYBOARD_ACTIVATE, onKeyboardChange ); textField.addEventListener(SoftKeyboardEvent.SOFT_KEYBOARD_DEACTIVATE, onKeyboardChange ); this.stage.addEventListener( Event.RESIZE, onDisplayAreaChange ); } private function onDisplayAreaChange( event:Event ):void {

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Entrada do teclado

555

textField.y = this.stage.stageHeight - 201; textField.width = this.stage.stageWidth; } private function onKeyboardChange( event:SoftKeyboardEvent ):void { var field:InteractiveObject = textField; var offset:int = 0; //if the softkeyboard is open and the field is at least partially covered if( (this.stage.softKeyboardRect.y != 0) && (field.y + field.height > this.stage.softKeyboardRect.y) ) offset = field.y + field.height - this.stage.softKeyboardRect.y; //but don't push the top of the field above the top of the screen if( field.y - offset < 0 ) offset += field.y - offset; this.y = -offset; } } }

Nota: No Android, existem circunstncias, incluindo o modo tela cheia, nas quais as dimenses exatas do teclado no esto disponveis no sistema operacional. Nesses casos, o tamanho estimado. Do mesmo modo, nas orientaes de paisagem, o teclado IME de tela cheia nativo usado para todas as entradas de texto. Esse teclado IME possui um campo de entrada de texto incorporado e oculta o palco inteiro. No existe maneira de ativar um teclado com orientao de paisagem sem preencher a tela.

ltima atualizao em 29/3/2011

556

Captulo 29: Entrada do mouse

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Seu aplicativo pode criar interatividade capturando e respondendo entrada do mouse. Essa seo supe que voc j est familiarizado com o modelo de eventos do ActionScript 3.0. Para obter mais informaes, consulte Manipulao de eventos na pgina 118. Para obter informaes sobre como descobrir que tipo de suporte mouse est disponvel (como cursor persistente , stylus ou entrada de toques) durante o tempo de execuo, consulte Descobrindo tipos de entrada na pgina 539.

Mais tpicos da Ajuda

flash.ui.Mouse flash.events.MouseEvent Toque, multitoque e entrada de gestos na pgina 562

Captura da entrada do mouse

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os cliques criam eventos de mouse que podem ser usados para acionar funes interativas. Voc pode adicionar um ouvinte de eventos ao palco para ouvir eventos de mouse que ocorrem em qualquer lugar no arquivo SWF. Tambm possvel adicionar ouvintes de eventos a objetos no palco que herdam modelos de InteractiveObject (por exemplo, Sprite ou MovieClip); esses ouvintes so acionados quando o objeto clicado. Assim como os eventos de teclado, os eventos de mouse aparecem em bales. No exemplo a seguir, como square filho de Stage, o evento enviado a partir do objeto square da entidade grfica, bem como do objeto Stage quando se clica em square:
var square:Sprite = new Sprite(); square.graphics.beginFill(0xFF0000); square.graphics.drawRect(0,0,100,100); square.graphics.endFill(); square.addEventListener(MouseEvent.CLICK, reportClick); square.x = square.y = 50; addChild(square); stage.addEventListener(MouseEvent.CLICK, reportClick); function reportClick(event:MouseEvent):void { trace(event.currentTarget.toString() + " dispatches MouseEvent. Local coords [" + event.localX + "," + event.localY + "] Stage coords [" + event.stageX + "," + event.stageY + "]"); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Entrada do mouse

557

No exemplo anterior, observe que o evento de mouse contm informaes de posio sobre o clique. As propriedades localX e localY contm o local do clique no filho mais inferior da cadeia de exibio. Por exemplo, clicar no canto superior esquerdo de square registra as coordenadas de local [0,0] porque este o ponto de registro de square. Como alternativo, as propriedades stageX e stageY referem-se s coordenadas globais do clique no palco. O mesmo clique registra [50,50] para essas coordenadas, pois square foi movido at elas. Esses dois pares de coordenadas podem ser teis dependendo do modo como deseja responder interao do usurio. O objeto MouseEvent tambm contm as propriedades booleanas altKey, ctrlKey e shiftKey. Voc pode usar essas propriedades para verificar se a tecla Alt, Ctrl ou Shift tambm est sendo pressionada ao mesmo tempo em que o clique do mouse.

Arrastando Sprites pelo palco

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc pode permitir que os usurios arrastem um objeto Sprite pelo palco usando o mtodo startDrag() da classe Sprite. O cdigo a seguir mostra um exemplo disso:
import flash.display.Sprite; import flash.events.MouseEvent; var circle:Sprite = new Sprite(); circle.graphics.beginFill(0xFFCC00); circle.graphics.drawCircle(0, 0, 40); var target1:Sprite = new Sprite(); target1.graphics.beginFill(0xCCFF00); target1.graphics.drawRect(0, 0, 100, 100); target1.name = "target1"; var target2:Sprite = new Sprite(); target2.graphics.beginFill(0xCCFF00); target2.graphics.drawRect(0, 200, 100, 100); target2.name = "target2"; addChild(target1); addChild(target2); addChild(circle); circle.addEventListener(MouseEvent.MOUSE_DOWN, mouseDown) function mouseDown(event:MouseEvent):void { circle.startDrag(); } circle.addEventListener(MouseEvent.MOUSE_UP, mouseReleased); function mouseReleased(event:MouseEvent):void { circle.stopDrag(); trace(circle.dropTarget.name); }

Para obter mais detalhes, consulte a seo sobre a criao da interao de movimentao do mouse em Alterao da posio na pgina 166.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Entrada do mouse

558

Arrastar e soltar no AIR No Adobe AIR, voc pode permitir a ao de arrastar e soltar para que os usurios arrastem dados para o seu aplicativo e a partir dele. Consulte mais detalhes em Arrastar e soltar no AIR na pgina 590.

Personalizao do cursor do mouse

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O cursor do mouse (ponteiro) pode ser ocultado ou alternado para qualquer objeto de exibio no palco. Para ocultar o cursor do mouse, chame o mtodo Mouse.hide(). Personalize o cursor chamando Mouse.hide(), ouvindo o evento MouseEvent.MOUSE_MOVE no palco e definindo as coordenadas de um objeto de exibio (seu cursor personalizado) com as propriedades stageX e stageY do evento. O exemplo a seguir ilustra uma execuo bsica dessa tarefa:
var cursor:Sprite = new Sprite(); cursor.graphics.beginFill(0x000000); cursor.graphics.drawCircle(0,0,20); cursor.graphics.endFill(); addChild(cursor); stage.addEventListener(MouseEvent.MOUSE_MOVE,redrawCursor); Mouse.hide(); function redrawCursor(event:MouseEvent):void { cursor.x = event.stageX; cursor.y = event.stageY; }

Exemplo de entrada de mouse: WordSearch

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Este exemplo demonstra a interao do usurio por meio da manipulao de eventos de mouse. Os usurios criam o mximo de palavras possvel a partir de uma grade aleatria de letras, movendo-se na horizontal ou vertical na grade, mas nunca usando a mesma letra duas vezes. Este exemplo demonstra os seguintes recursos do ActionScript 3.0:

Criao dinmica de uma grade de componentes Resposta a eventos de mouse Manuteno da pontuao com base na interao do usurio
Para obter os arquivos de aplicativo desse exemplo, consulte www.adobe.com/go/learn_programmingAS3samples_flash_br. Os arquivos do aplicativo WordSearch esto localizados na pasta Amostras/WordSearch. O aplicativo consiste nos seguintes arquivos:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Entrada do mouse

559

Arquivo WordSearch.as WordSearch.fla ou WordSearch.mxml dictionary.txt

Descrio A classe que fornece a funcionalidade principal do aplicativo. O arquivo principal do aplicativo para Flex (MXML) ou Flash (FLA).

Um arquivo usado para determinar se as palavras criadas podem ser pontuadas e foram escritas corretamente.

Carregamento de um dicionrio
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para criar um jogo que envolve a busca de palavras, um dicionrio necessrio. O exemplo inclui um arquivo de texto chamado dictionary.txt que contm uma lista de palavras separadas por retornos de carro. Depois que uma matriz chamada words criada, a funo loadDictionary() solicita esse arquivo que, ao ser carregado com xito, se transforma em uma longa string. possvel analisar essa string em uma matriz de palavras usando o mtodo split(), quebrando-a em cada ocorrncia de um retorno de carro (cdigo de caractere 10) ou de uma nova linha (cdigo de caractere 13). Essa anlise ocorre na funo dictionaryLoaded():
words = dictionaryText.split(String.fromCharCode(13, 10));

Criao da interface de usurio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Depois de armazenar as palavras, voc pode configurar a interface de usurio. Crie duas ocorrncias de boto: uma para enviar uma palavra e outra para apagar uma palavra que esteja com erros ortogrficos no momento. Em cada caso, responda entrada do usurio ouvindo o evento MouseEvent.CLICK que o boto transmite e, em seguida, chamando uma funo. Na funo setupUI(), esse cdigo cria os ouvintes nos dois botes:
submitWordButton.addEventListener(MouseEvent.CLICK,submitWord); clearWordButton.addEventListener(MouseEvent.CLICK,clearWord);

Gerao de uma placa de jogo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A placa de jogo uma grade de letras aleatrias. Na funo generateBoard(), uma grade bidimensional criada, aninhando um loop em outro. O primeiro loop aumenta as linhas e o segundo aumenta o nmero total de colunas por linha. Cada clula criada por essas linhas e colunas contm um boto que representa uma letra na placa.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Entrada do mouse

560

private function generateBoard(startX:Number, startY:Number, totalRows:Number, totalCols:Number, buttonSize:Number):void { buttons = new Array(); var colCounter:uint; var rowCounter:uint; for (rowCounter = 0; rowCounter < totalRows; rowCounter++) { for (colCounter = 0; colCounter < totalCols; colCounter++) { var b:Button = new Button(); b.x = startX + (colCounter*buttonSize); b.y = startY + (rowCounter*buttonSize); b.addEventListener(MouseEvent.CLICK, letterClicked); b.label = getRandomLetter().toUpperCase(); b.setSize(buttonSize,buttonSize); b.name = "buttonRow"+rowCounter+"Col"+colCounter; addChild(b); buttons.push(b); } } }

Embora um ouvinte seja adicionado para um evento MouseEvent.CLICK apenas em uma linha, por estar em um loop for, ele atribudo a cada ocorrncia de boto. Alm disso, cada boto recebe um nome derivado de sua posio de linha e coluna, o que facilita a referncia linha e coluna de cada boto posteriormente no cdigo.

Criao de palavras a partir da entrada do usurio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para criar palavras, possvel selecionar letras que esto prximas na vertical ou na horizontal, mas nunca se deve usar a mesma letra duas vezes. Cada clique gera um evento de mouse e, nesse momento, a palavra fornecida pelo usurio deve ser verificada para assegurar que esteja sendo corretamente formada a partir das letras clicadas antes. Em caso negativo, a palavra anterior removida e uma nova iniciada. Essa verificao ocorre no mtodo isLegalContinuation().
private { var 3)); var 3)); var 3)); var 3)); function isLegalContinuation(prevButton:Button, currButton:Button):Boolean currButtonRow:Number = Number(currButton.name.charAt(currButton.name. indexOf("Row") + currButtonCol:Number = Number(currButton.name.charAt(currButton.name.indexOf("Col") + prevButtonRow:Number = Number(prevButton.name.charAt(prevButton.name.indexOf("Row") + prevButtonCol:Number = Number(prevButton.name.charAt(prevButton.name.indexOf("Col") +

return ((prevButtonCol == currButtonCol && Math.abs(prevButtonRow - currButtonRow) <= 1) || (prevButtonRow == currButtonRow && Math.abs(prevButtonCol - currButtonCol) <= 1)); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Entrada do mouse

561

Os mtodos charAt() e indexOf() da classe String recuperam as linhas e colunas apropriadas do boto clicado atualmente e do boto clicado anteriormente. O mtodo isLegalContinuation() retornar true se a linha ou coluna estiver inalterada e se a linha ou coluna que foi alterada estiver em um nico incremento da anterior. Se desejar alterar as regras do jogo e permitir a formao de palavras na diagonal, remova as verificaes de linhas ou colunas inalteradas; a linha final similar a:
return (Math.abs(prevButtonRow - currButtonRow) <= 1) && Math.abs(prevButtonCol currButtonCol) <= 1));

Verificao do envio de palavras

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para concluir o cdigo do jogo, os mecanismos de verificao do envio de palavras e de clculo da pontuao so necessrios. O mtodo searchForWord() contm os dois:
private function searchForWord(str:String):Number { if (words && str) { var i:uint = 0 for (i = 0; i < words.length; i++) { var thisWord:String = words[i]; if (str == words[i]) { return i; } } return -1; } else { trace("WARNING: cannot find words, or string supplied is null"); } return -1; }

Essa funo percorre todas as palavras do dicionrio. Se a palavra do usurio coincidir com a do dicionrio, sua posio no dicionrio ser retornada. O mtodo submitWord() verifica a resposta e atualiza a pontuao se a posio for vlida.

Personalizao
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior No incio da classe, existem vrias constantes. Voc pode modificar esse jogo modificando essas variveis. possvel, por exemplo, alterar a quantidade de tempo disponvel para jogar aumentando a varivel TOTAL_TIME. Voc tambm pode aumentar ligeiramente a varivel PERCENT_VOWELS para aumentar a probabilidade de busca das palavras.

ltima atualizao em 29/3/2011

562

Captulo 30: Toque, multitoque e entrada de gestos

Flash Player 10.1 e posterior, Adobe AIR 2 e posterior Os recursos de manuseio de evento de toque da plataforma Flash incluem a entrada de um nico ponto de contato ou mltiplos pontos de contato em dispositivos sensveis ao toque. Alm disso, o tempo de execuo do Flash trata de eventos que combinam mltiplos pontos de toque com o movimento criado pelo gesto. Em outras palavras, os tempos de execuo do Flash interpretam dois tipos de entrada:
Toque entrada com um dispositivo de ponto nico como, por exemplo, um dedo, uma stylus ou outra ferramenta em

um dispositivo sensvel ao toque. Alguns dispositivos possuem suporte a pontos de contato simultneos com um dedo ou uma stylus.
Multitoque entrada com mais de um ponto simultneo de contato. Gesto Entrada interpretada por um dispositivo ou sistema operacional em resposta a um ou mais eventos de toque. Por exemple, o usurio gira dois dedos simultaneamente e o dispositivo ou sistema operacional interpreta o toque como um gesto de rotao. Alguns gestos so executados com um dedo ou ponto de toque e, outros gestos podem necessitar de mltiplos pontos de toque. O dispositivo ou o sistema operacional estabelece o tipo de gesto a ser atribudo entrada.

Ambas entradas de toque e gesto podem ser de entrada multitoque, dependendo do dispositivo do usurio. O ActionScript fornece uma API para tratar de eventos de toque, de gestos e eventos rastreados individualmente para entrada multitoque. Nota: A escuta de eventos de toque e gesto pode consumir uma quantidade significativa de recursos (equivalente renderizao de vrios quadros por segundo), dependendo do dispositivo de computao e do sistema operacional. Geralmente melhor usar eventos de mouse quando voc no precisa efetivamente da funcionalidade extra proporcionada por toques ou gestos. Ao usar eventos de toque ou gesto, considere reduzir a quantidade de alteraes grficas que podem ocorrer, especialmente quando tais eventos podem ser despachados rapidamente, seja durante uma pan, seja durante uma operao de rotao ou zoom. Por exemplo, voc poderia parar a animao em um componente enquanto o usurio estivesse a redimensionando com um gesto de zoom.

Mais tpicos da Ajuda

flash.ui.Multitouch flash.events.TouchEvent flash.events.GestureEvent flash.events.TransformGestureEvent flash.events.GesturePhase flash.events.PressAndTapGestureEvent Paul Trani: Touch Events and Gestures on Mobile (Eventos de Toque e Gesto em Dispositivos Mveis)

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Toque, multitoque e entrada de gestos

563

Introduo entrada de toque

Flash Player 10.1 e posterior, Adobe AIR 2 e posterior Quando a plataforma Flash est sendo executada em um ambiente que possui suporte a entrada de toque, as instncias InteractiveObject podem monitorar eventos de toque e manipuladores de chamada. Geralmente, possvel manipular eventos de toque, multitoque e gestos da mesma forma que outros eventos no ActionScript (consulte Manipulao de eventos na pgina 118 para obter as informaes bsicas sobre como gerenciar eventos com o ActionScript). No entanto, para que o tempo de execuo Flash interprete um toque ou um gesto, o tempo de execuo deve estar sendo executado em um ambiente de hardware e software que tenha suporte a entrada de toque ou multitoque. Consulte Descobrindo tipos de entrada na pgina 539 para obter um grfico comparativo de diferentes tipos de telas sensveis ao toque. Alm disso, se o tempo de execuo estiver em um aplicativo continer (por exemplo, um navegador), o continer envia a entrada para o tempo de execuo. Em alguns casos, o hardware atual e o ambiente do sistema operacional possuem suporte a multitoque, mas o navegador que contm o tempo de execuo do Flash interpreta a entrada e no a envia para o tempo de execuo. De forma alternativa, ele pode simplesmente ignorar a entrada por completo. O diagrama a seguir demonstra o fluxo de entrada do usurio para o tempo de execuo:
Sistema operacional Continer do aplicativo (ex: navegador) Tempo de execuo do Flash

Usurio

Dispositivo

Fluxo de entrada do usurio para o tempo de execuo da plataforma Flash

Felizmente, a ActionScript API para desenvolvimento de aplicativos de toque inclui classes, mtodos e propriedades para determinar o suporte para entrada toque e multitoque no ambiente do tempo de execuo. A API utilizada para determinar o suporte entrada de toque a "API de descoberta para manipulao de eventos de toque. Conceitos e termos importantes A lista de referncia a seguir contm termos importantes para programar aplicativos de manipulao de eventos de toque:
API de descoberta Mtodos e propriedades utilizados para detectar no ambiente de tempo de execuo o suporte a

eventos de toque e diferentes modos de entrada.

Evento de toque Uma ao de entrada executada em um dispositivo sensvel ao toque utilizando um nico ponto de

contato.
Ponto de toque Ponto de contato de um nico evento de toque. Mesmo que um dispositivo no tenha suporte

entrada de gestos, ele pode ter suporte a mltiplos pontos de toque simultneos.
Sequncia de toque Srie de eventos que representam a durao de um nico toque. Esses eventos incluem movimentos iniciais, zero ou mais movimentos e um movimento final. Evento multitoque Ao de entrada feita em um dispositivo sensvel ao toque utilizando diversos pontos de contato

(por exemplo, mais de um dedo).

Evento de gesto Ao de entrada, executada em um dispositivo sensvel ao toque que segue um movimento complexo. Por exemplo, um gesto tocar a tela com dois dedos e mov-los simultaneamente ao redor do permetro de um crculo abstrato para indicar rotao.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Toque, multitoque e entrada de gestos

564

Fases Pontos distintos de tempo no fluxo do evento (por exemplo, incio e trmino) Stylus Instrumento (caneta) para interagir com uma tela sensvel ao toque A stylus pode fornecer mais preciso do que o dedo humano. Alguns dispositivos reconhecem somente a entrada de um tipo especfico de stylus. Dispositivos que reconhecem a entrada da stylus podem no reconhecer pontos mltiplos e simultneos de contato ou o contato dos dedos. Pressionar e tocar Um tipo especfico de gesto de entrada multitoque onde o usurio pressiona o dedo contra um

dispositivo sensvel ao toque e, em seguida, toca com outro dedo ou dispositivo apontador. Geralmente, esse gesto utilizado para simular um clique do boto direito do mouse em aplicativos multitoque.

A estrutura de API de entrada de toque

A API de entrada de toque ActionScript projetada para tratar do fato que a manipulao de entrada de toque depende do ambiente de hardware e software do tempo de execuo do Flash. A API de entrada de toque enderea inicialmente trs necessidades de desenvolvimento de aplicativos sensveis ao toque: descoberta, eventos e fases. Coordene essas APIs para produzir uma experincia confivel e gil para o usurio, mesmo se o dispositivo destino for desconhecido durante o desenvolvimento do aplicativo.

Descoberta
A API de descoberta fornece a habilidade de testar o ambiente de hardware e software no tempo de execuo. Os valores preenchidos pelo tempo de execuo determinam a entrada de toque disponvel para o tempo de execuo do Flash no contexto atual. Utilize a coleo de propriedades de descoberta e mtodos para configurar o aplicativo para reagir a eventos do mouse (em vez de eventos de toque no caso de alguma entrada de toque no ter suporte do ambiente). Para obter mais informaes, consulte Descoberta de suporte ao toque na pgina 565

Eventos
O ActionScript gerencia os eventos de entrada de toque com os ouvintes e manipuladores de eventos, da mesma forma como faz com outros eventos. No entanto, a manipulao de evento de entrada de toque tambm inclui os itens a seguir:

Um toque pode ser interpretado de diversas maneiras pelo dispositivo ou pelo sistema operacional, tanto quanto
uma sequncia de toques ou de forma coletiva, como um gesto.

Um nico toque em um dispositivo sensvel ao toque (dedo, stylus ou dispositivo apontador) sempre envia um
evento de mouse tambm. possvel manipular o evento de mouse com os tipos de evento na classe MouseEvent. Opcionalmente, voc pode projetar seu aplicativo para somente responder a eventos de toque. Como alternativa, voc pode projetar um aplicativo que responde a ambos.

Um aplicativo pode responder a mltiplos eventos de toques simultneos e manipular cada um deles
separadamente. Geralmente, utilize a API de descoberta para manipular condicionalmente os eventos que seu aplicativo manipula e a forma como eles so manipulados. Aps o aplicativo conhecer o ambiente de tempo de execuo, ele pode chamar o manipulador adequado ou estabelecer o objeto de evento correto quando o usurio interagir com o aplicativo. Opcionalmente, o aplicativo pode indicar que a entrada especfica no pode ser manipulada no ambiente atual e fornecer ao usurio uma alternativa ou informao. Para obter mais informaes, consulte Tratamento de eventos de toque na pgina 566 e Tratamento de Eventos de gestos na pgina 571.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Toque, multitoque e entrada de gestos

565

Fases
Para aplicativos de toque e multitoque, objetos de evento de toque contm propriedades para monitorar as fases da interao do usurio. Crie um ActionScript para manipular fases como, por exemplo, incio, atualizao e fase final da entrada do usurio para fornecer feedback. Responde s fases de evento de forma que objetos visuais sejam alterados conforme o usurio toca e move o ponto de toque na tela. De forma alternativa, utilize fases para monitorar propriedades especficas de um gesto, conforme o gesto vai evoluindo. Para eventos de ponto de toque, monitore por quanto tempo o usurio mantm pressionado um objeto interativo especfico. Um aplicativo pode monitorar mltiplas fases de pontos de toque simultneos individualmente e manipular cada um conforme necessrio. Para um gesto, interprete as informaes especficas sobre a transformao de um gesto conforme ele ocorre. Monitore as coordenadas de um ponto de contato (ou diversos pontos) conforme eles se movem na tela.

Descoberta de suporte ao toque

Flash Player 10.1 e posterior, Adobe AIR 2 e posterior Utilize as propriedades da classe Multitouchpara definir o escopo de entrada de toque manipulado por seu aplicativo. Em seguida, teste o ambiente para assegurar-se de que existe suporte para os eventos manipulados pelo ActionScript. Especificamente, primeiro estabelea o tipo de entrada de toque de seu aplicativo. As opes so: ponto de toque, gesto ou nenhum (interpretar todas as entradas de toque como cliques do mouse e somente utilizar manipuladores de evento de mouse). Em seguida, utilize as propriedades e mtodos da classe Multitouch para assegurar que o tempo de execuo est em um ambiente que possui suporte entrada de toque que seu aplicativo requer. Teste o ambiente do tempo de execuo para verificar o suporte aos tipos de entrada de toque (como, por exemplo, se possvel interpretar gestos) e prossiga de acordo. Nota: As propriedades da classe Multitouch so propriedades estticas e no pertencem a instncias de nenhuma outra classe. Utilize-as com a sintaxe Multitouch.property, como no exemplo a seguir:
var touchSupport:Boolean = Multitouch.supportsTouchEvents;

Defina o tipo de entrada

O tempo de execuo do Flash deve conhecer o tipo de entrada de toque a ser interpretado porque o evento de toque pode ter diversos elementos ou fases. Se houver o toque de um dedo em uma tela sensvel ao toque, o tempo de execuo envia um evento de toque? Ou ele aguarda por um gesto? Ou o tempo de execuo acompanha o toque como um evento de toque de mouse? Um aplicativo que possui suporte entrada de toque deve estabelecer o tipo dos eventos de toque que ele pode manipular para o tempo de execuo do Flash. Utilize a propriedade Multitouch.inputMode para estabelecer o tipo de entrada de toque para o tempo de execuo. O modo de entrada pode ser uma das trs opes a seguir:
Nenhum Nenhuma manipulao especial fornecida para eventos de toque. Definir:
Multitouch.inputMode=MultitouchInputMode.NONE e utilizar a classe MouseEvent para manipular a entrada.

Pontos de toque nicos Toda a entrada de toque interpretada individualmente e todos os pontos de toque podem ser monitorados e manipulados. Definir: Multitouch.inputMode=MultitouchInputMode.TOUCH_POINT e utilizar a classe TouchEvent para manipular a entrada. Entrada de gestos O dispositivo ou o sistema operacional interpreta a entrada como um formulrio complexo ou

movimento dos dedos na tela. O dispositivo ou o sistema operacional atribui de forma coletiva o movimento a um

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Toque, multitoque e entrada de gestos

566

nico evento de entrada de gesto. Definir: Multitouch.inputMode=MultitouchInputMode.GESTURE e utilizar as classes TransformGestureEvent, PressAndTapGestureEvent ou GestureEvent para manipular a entrada. Consulte Tratamento de eventos de toque na pgina 566 para obter um exemplo que utiliza a propriedade Multitouch.inputMode para definir um tipo de entrada antes de manusear um evento de toque.

Testar suporte de entrada de toque

Outras propriedades da classe Multitouch fornecem valores para ajustar seu aplicativo ao ambiente atual de suporte a toque. O tempo de execuo do Flash preenche os valores do nmero de pontos de toque simultneos permitidos ou gestos disponveis. Se o tempo de execuo estiver em um ambiente sem suporte manipulao de eventos de toque, o aplicativo precisa fornecer ao usurio uma alternativa. Por exemplo, fornea a manipulao de evento de mouse ou informaes sobre quais recursos esto disponveis e indisponveis no ambiente atual. Voc tambm pode utilizar a API para o suporte ao teclado, toque e mouse. Consulte Descobrindo tipos de entrada na pgina 539. Para obter mais informaes sobre o teste de compatibilidade, consulte Soluo de problemas na pgina 574.

Tratamento de eventos de toque

Flash Player 10.1 e posterior, Adobe AIR 2 e posterior Eventos bsicos de toque so manipulados da mesma forma que os outros eventos como, por exemplo, eventos de mouse no ActionScript. Voc pode monitorar uma srie de eventos de toque definidos pelas constantes de tipo de evento na classe TouchEvent. Nota: Para entrada de ponto de diversos toques (tocar o dispositivo com mais de um dedo), o primeiro ponto de contato envia um evento de mouse e de toque. Para manipular um evento de toque bsico:
1 Configure seu aplicativo para manipular eventos de toque, definindo a propriedade
flash.ui.Multitouch.inputMode para MultitouchInputMode.TOUCH_POINT.

2 Anexe um ouvinte de evento uma instncia de uma classe que herda propriedades da classe InteractiveObject

como, por exemplo, Sprite ou TextField.

3 Especifique o tipo de evento de toque a ser manipulado. 4 Chame a funo do manipulador do evento para responder ao evento.

O exemplo a seguir exibe uma mensagem quando o quadrado desenhado em mySprite ativado em uma tela sensvel ao toque:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Toque, multitoque e entrada de gestos

567

Multitouch.inputMode=MultitouchInputMode.TOUCH_POINT; var mySprite:Sprite = new Sprite(); var myTextField:TextField = new TextField(); mySprite.graphics.beginFill(0x336699); mySprite.graphics.drawRect(0,0,40,40); addChild(mySprite); mySprite.addEventListener(TouchEvent.TOUCH_TAP, taphandler); function taphandler(evt:TouchEvent): void { myTextField.text = "I've been tapped"; myTextField.y = 50; addChild(myTextField); }

Proprieade de Evento de toque

Um objeto evento criado quando ocorre um evento. O objeto TouchEvent contm informaes sobre o local e as condies do evento de toque. Voc pode utilizar as propriedades do objeto de evento para obter essas informaes. Por exemplo, o cdigo a seguir cria um objeto TouchEvent evt e, em seguida, exibe a propriedade stageX do objeto de evento (a coordenada x do ponto no espao do Palco onde o toque ocorreu) no campo de texto:
Multitouch.inputMode=MultitouchInputMode.TOUCH_POINT; var mySprite:Sprite = new Sprite(); var myTextField:TextField = new TextField(); mySprite.graphics.beginFill(0x336699); mySprite.graphics.drawRect(0,0,40,40); addChild(mySprite); mySprite.addEventListener(TouchEvent.TOUCH_TAP, taphandler); function taphandler(evt:TouchEvent): void { myTextField.text = evt.stageX.toString; myTextField.y = 50; addChild(myTextField); }

Consulte a classe TouchEvent para obter as propriedades disponveis por meio do objeto de evento. Nota: Nem todas as propriedades TouchEvent possuem suporte em todos os ambientes de tempo de execuo. Por exemplo, nem todos os dispositivos sensveis ao toque so capazes de detectar a presso que o usurio est aplicando na tela. Dessa forma, a propriedade TouchEvent.pressure no possui suporte em todos estes dispositivos. Tente testar o suporte de uma propriedade especfica para verificar se o aplicativo funciona e, em seguida, consulte Soluo de problemas na pgina 574 para obter mais informaes.

Fases de evento de toque

Monitore eventos de toque por meio de diversos estgios externos e sobre InteractiveObject, de forma similar a eventos de mouse. Monitore eventos de toque pelo incio, meio e fim da interao de toque. A classe TouchEvent fornece valores para manipular eventostouchBegin, touchMove e touchEnd.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Toque, multitoque e entrada de gestos

568

Por exemplo, possvel utilizar os eventos touchBegin, touchMove e touchEnd para fornecer ao usurio um feedback visual, conforme ele toca e move um objeto de exibio:
Multitouch.inputMode = MultitouchInputMode.TOUCH_POINT; var mySprite:Sprite = new Sprite(); mySprite.graphics.beginFill(0x336699); mySprite.graphics.drawRect(0,0,40,40); addChild(mySprite); var myTextField:TextField = new TextField(); myTextField.width = 200; myTextField.height = 20; addChild(myTextField); mySprite.addEventListener(TouchEvent.TOUCH_BEGIN, onTouchBegin); stage.addEventListener(TouchEvent.TOUCH_MOVE, onTouchMove); stage.addEventListener(TouchEvent.TOUCH_END, onTouchEnd); function onTouchBegin(event:TouchEvent) { myTextField.text = "touch begin" + event.touchPointID; } function onTouchMove(event:TouchEvent) { myTextField.text = "touch move" + event.touchPointID; } function onTouchEnd(event:TouchEvent) { myTextField.text = "touch end" + event.touchPointID; }

Nota: O ouvinte de toque inicial est anexado mySprite, mas os ouvintes de movimento e finalizao do evento de toque no esto anexados. Se o dedo do usurio ou dispositivo apontador mover-se acima do objeto de exibio, o Palco continua a monitorar o evento de toque.

ID do ponto de toque
A propriedade TouchEvent.touchPointID parte essencial da programao de aplicativos que respondem entrada de toque. O tempo de execuo do Flash atribui a cada ponto de toque, um valor touchPointID exclusivo. Sempre que um aplicativo responder s fases ou movimentos de entrada de toque, consulte touchPointID antes de manipular o evento. Os mtodos de arrastas a entrada de toque da classe Sprite utilizam a propriedade touchPointID como parmetro, de forma que a instncia de entrada correta seja manipulada. A propriedade touchPointID garante que o manipulador de evento responda ao ponto de toque correto. De outra forma, o manipulador de evento responde a qualquer instncia do tipo de evento de toque (como, por exemplo, todos os eventos touchMove) no dispositivo, criando um comportamento imprevisvel. A propriedade especialmente importante quando o usurio est arrastando objetos. Utilize a propriedade touchPointID para gerenciar uma sequncia inteira de toque. Uma sequncia de toque possui um evento touchBegin, zero ou mais eventos touchMove e um evento touchEnd que possuem o mesmo valor touchPointID. O exemplo a seguir estabelece a varivel touchMoveID para testar o valor correto touchPointID antes de responder a um evento de movimento de toque. De outra forma, outras entradas de toque disparam o manipulador de eventos tambm. Observe que os ouvintes das fases de movimento e fim esto no palco mas o objeto de exibio no. O palco monitora as fases de movimento ou fim, no caso do toque do usurio mover-se alm dos limites do objeto de exibio.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Toque, multitoque e entrada de gestos

569

Multitouch.inputMode = MultitouchInputMode.TOUCH_POINT; var mySprite:Sprite = new Sprite(); mySprite.graphics.beginFill(0x336699); mySprite.graphics.drawRect(0,0,40,40); addChild(mySprite); var myTextField:TextField = new TextField(); addChild(myTextField); myTextField.width = 200; myTextField.height = 20; var touchMoveID:int = 0; mySprite.addEventListener(TouchEvent.TOUCH_BEGIN, onTouchBegin); function onTouchBegin(event:TouchEvent) { if(touchMoveID != 0) { myTextField.text = "already moving. ignoring new touch"; return; } touchMoveID = event.touchPointID; myTextField.text = "touch begin" + event.touchPointID; stage.addEventListener(TouchEvent.TOUCH_MOVE, onTouchMove); stage.addEventListener(TouchEvent.TOUCH_END, onTouchEnd); } function onTouchMove(event:TouchEvent) { if(event.touchPointID != touchMoveID) { myTextField.text = "ignoring unrelated touch"; return; } mySprite.x = event.stageX; mySprite.y = event.stageY; myTextField.text = "touch move" + event.touchPointID; } function onTouchEnd(event:TouchEvent) { if(event.touchPointID != touchMoveID) { myTextField.text = "ignoring unrelated touch end"; return; } touchMoveID = 0; stage.removeEventListener(TouchEvent.TOUCH_MOVE, onTouchMove); stage.removeEventListener(TouchEvent.TOUCH_END, onTouchEnd); myTextField.text = "touch end" + event.touchPointID; }

Tocar e arrastar
Flash Player 10.1 e posterior, Adobe AIR 2 e posterior Dois mtodos foram adicionados classe Sprite para fornecer suporte adicional a aplicativos sensveis ao toque com suporte a entrada de ponto de toque: Sprite.startTouchDrag() e Sprite.stopTouchDrag(). Esses mtodos comportamse da mesma forma que Sprite.startDrag() e Sprite.stopDrag() se comportam para eventos de mouse. No entanto, observe que os mtodos Sprite.startTouchDrag() e Sprite.stopTouchDrag() utilizam valores de touchPointID como parmetro.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Toque, multitoque e entrada de gestos

570

O tempo de execuo atribuir o valor touchPointID ao objeto de evento para um evento de toque. Utilize este valor para responder a um ponto de toque especfico no caso do ambiente fornecer suporte a mltiplos pontos de toque simultneos (mesmo que no manipule gestos). Para obter mais informaes sobre a propriedade touchPointID, consulte ID do ponto de toque na pgina 568. O cdigo a seguir demonstra um manipulador de evento simples de incio de arrastar e fim de arrastar de um evento de toque. A varivel bg um objeto de exibio que contm mySprite:
mySprite.addEventListener(TouchEvent.TOUCH_BEGIN, onTouchBegin); mySprite.addEventListener(TouchEvent.TOUCH_END, onTouchEnd); function onTouchBegin(e:TouchEvent) { e.target.startTouchDrag(e.touchPointID, false, bg.getRect(this)); trace("touch begin"); } function onTouchEnd(e:TouchEvent) { e.target.stopTouchDrag(e.touchPointID); trace("touch end"); }

O exemplo a seguir mostra uma forma mais avanada de combinao de fases de arrastar com evento de toque:
Multitouch.inputMode = MultitouchInputMode.TOUCH_POINT; var mySprite:Sprite = new Sprite(); mySprite.graphics.beginFill(0x336699); mySprite.graphics.drawRect(0,0,40,40); addChild(mySprite); mySprite.addEventListener(TouchEvent.TOUCH_BEGIN, onTouchBegin); mySprite.addEventListener(TouchEvent.TOUCH_MOVE, onTouchMove); mySprite.addEventListener(TouchEvent.TOUCH_END, onTouchEnd); function onTouchBegin(evt:TouchEvent) { evt.target.startTouchDrag(evt.touchPointID); evt.target.scaleX *= 1.5; evt.target.scaleY *= 1.5; } function onTouchMove(evt:TouchEvent) { evt.target.alpha = 0.5; } function onTouchEnd(evt:TouchEvent) { evt.target.stopTouchDrag(evt.touchPointID); evt.target.width = 40; evt.target.height = 40; evt.target.alpha = 1; }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Toque, multitoque e entrada de gestos

571

Tratamento de Eventos de gestos

Flash Player 10.1 e posterior, Adobe AIR 2 e posterior Manipule eventos de gesto da mesma forma que eventos de toque bsicos. Voc pode monitorar uma srie de eventos de gesto definidos pelas constantes de tipo de evento na classe TransformGestureEvent, GestureEvent e na classe PressAndTapGestureEvent. Para manipular um evento de toque de gesto:
1 Configure o aplicativo para manipular entrada de gestos defiinindo a propriedade
flash.ui.Multitouch.inputMode para MultitouchInputMode.GESTURE.

2 Anexe um ouvinte de evento uma instncia de uma classe que herda propriedades da classe InteractiveObject

como, por exemplo, Sprite ou TextField.

3 Especifique o tipo de evento de gesto a ser manipulado. 4 Chame a funo do manipulador do evento para responder ao evento.

O exemplo a seguir exibe uma mensagem quando o quadrado desenhado em mySprite tocado em uma tela sensvel ao toque:
Multitouch.inputMode=MultitouchInputMode.GESTURE; var mySprite:Sprite = new Sprite(); var myTextField:TextField = new TextField(); mySprite.graphics.beginFill(0x336699); mySprite.graphics.drawRect(0,0,40,40); addChild(mySprite); mySprite.addEventListener(TransformGestureEvent.GESTURE_SWIPE, swipehandler); function swipehandler(evt:TransformGestureEvent): void { myTextField.text = "I've been swiped"; myTextField.y = 50; addChild(myTextField); }

Eventos de toque de dois dedos so manipulados da mesma forma, mas utilizam a classe GestureEvent:
Multitouch.inputMode=MultitouchInputMode.GESTURE; var mySprite:Sprite = new Sprite(); var myTextField:TextField = new TextField(); mySprite.graphics.beginFill(0x336699); mySprite.graphics.drawRect(0,0,40,40); addChild(mySprite); mySprite.addEventListener(GestureEvent.GESTURE_TWO_FINGER_TAP, taphandler); function taphandler(evt:GestureEvent): void { myTextField.text = "I've been two-finger tapped"; myTextField.y = 50; addChild(myTextField); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Toque, multitoque e entrada de gestos

572

Eventos de pressionar e tocar tambm so manipulados da mesma forma, mas utilizam a classe PressAndTapGestureEvent:
Multitouch.inputMode=MultitouchInputMode.GESTURE; var mySprite:Sprite = new Sprite(); var myTextField:TextField = new TextField(); mySprite.graphics.beginFill(0x336699); mySprite.graphics.drawRect(0,0,40,40); addChild(mySprite); mySprite.addEventListener(PressAndTapGestureEvent.GESTURE_PRESS_AND_TAP, taphandler); function taphandler(evt:PressAndTapGestureEvent): void { myTextField.text = "I've been press-and-tapped"; myTextField.y = 50; addChild(myTextField); }

Nota: Nem todos os tipos de evento GestureEvent, TransformGestureEvent e PressAndTapGestureEvent possuem suporte em todos os ambientes de tempo de execuo. Por exemplo, nem todos os dispositivos sensveis ao toque so capazes de detectar um toque com divesos dedos. Dessa forma, os eventos InteractiveObject gestureSwipe no possuem suporte nestes dispositivos. Tente testar o suporte de um evento especfico para verificar se o aplicativo funciona e, em seguida, consulte Soluo de problemas na pgina 574 para obter mais informaes.

Propriedades de Evento de gestos

Eventos de gesto possuem um escopo menor de propriedades de eventos do que eventos de toque bsicos. Voc pode acess-los da mesma forma, por meio do objeto de vento na funo do manipulador de eventos. Por exemplo, o cdigo a seguir gira amySprite conforme o usurio executa um gesto de rotao nela. O campo de texto mostra o valor da rotao desde o ltimo gesto (ao testar o cdigo, gire-o diversas vezes para verificar a mudana do valor):
Multitouch.inputMode=MultitouchInputMode.GESTURE; var mySprite:Sprite = new Sprite(); var mySpriteCon:Sprite = new Sprite(); var myTextField:TextField = new TextField(); myTextField.y = 50; addChild(myTextField); mySprite.graphics.beginFill(0x336699); mySprite.graphics.drawRect(-20,-20,40,40); mySpriteCon.addChild(mySprite); mySprite.x = 20; mySprite.y = 20; addChild(mySpriteCon); mySprite.addEventListener(TransformGestureEvent.GESTURE_ROTATE, rothandler); function rothandler(evt:TransformGestureEvent): void { evt.target.parent.rotationZ += evt.target.rotation; myTextField.text = evt.target.parent.rotation.toString(); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Toque, multitoque e entrada de gestos

573

Nota: Nem todas as propriedades TransformGestureEvent possuem suporte em todos os ambientes de tempo de execuo. Por exemploe, nem todos os dispositivos sensveis ao toque so capazes de detectar a rotao de um gesto na tela. Dessa forma, a propriedade TransformGestureEvent.rotation no possui suporte em todos estes dispositivos. Tente testar o suporte de uma propriedade especfica para verificar se o aplicativo funciona e, em seguida, consulte Soluo de problemas na pgina 574 para obter mais informaes.

Fases de gestos
Alm disso, eventos de gesto podem ser monitorados por meio de fases, de forma que voc possa acompanhar as propriedades conforme o gesto executado. Por exemplo, possvel acompanhar as coordenadas x conforme um objeto movido com um gesto deslizante. Utilize esses valores para desnhar uma linha por todos os pontos no caminho aps o gesto deslizante ser concludo. De forma alternativa, altere visualmente um objeto de exibio conforme ele arrastado pela tela utilizando um gesto de deslocamento. Altere o objeto novamente para concluir o gesto de deslocamento.
Multitouch.inputMode = MultitouchInputMode.GESTURE; var mySprite = new Sprite(); mySprite.addEventListener(TransformGestureEvent.GESTURE_PAN , onPan); mySprite.graphics.beginFill(0x336699); mySprite.graphics.drawRect(0, 0, 40, 40); var myTextField = new TextField(); myTextField.y = 200; addChild(mySprite); addChild(myTextField); function onPan(evt:TransformGestureEvent):void { evt.target.localX++; if (evt.phase==GesturePhase.BEGIN) { myTextField.text = "Begin"; evt.target.scaleX *= 1.5; evt.target.scaleY *= 1.5; } if (evt.phase==GesturePhase.UPDATE) { myTextField.text = "Update"; evt.target.alpha = 0.5; } if (evt.phase==GesturePhase.END) { myTextField.text = "End"; evt.target.width = 40; evt.target.height = 40; evt.target.alpha = 1; } }

Nota: A frequncia da fase de atualizao depende do ambiente do tempo de execuo. Algumas combinaes de hardware e sistema operacional no podem encaminhar nenhuma atualizao.

A fase de gesto tudo para eventos de gestos simples

Alguns objetos de evento de gestos no acompanham fases individuais do evento de gesto e, em vez disso, preenchem a propriedade de fase do objeto de evento com o valor "all". O gesto simples de giro e toque com dois dedos no acompanha o evento por fases mltiplas. A propriedadephase de um objeto de evento InteractiveObject ouvino um evento gestureSwipe ou gestureTwoFingerTap sempre all, aps o evento ser despachado:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Toque, multitoque e entrada de gestos

574

Multitouch.inputMode = MultitouchInputMode.GESTURE; var mySprite = new Sprite(); mySprite.addEventListener(TransformGestureEvent.GESTURE_SWIPE, onSwipe); mySprite.addEventListener(GestureEvent.GESTURE_TWO_FINGER_TAP, onTwoTap); mySprite.graphics.beginFill(0x336699); mySprite.graphics.drawRect(0, 0, 40, 40); var myTextField = new TextField(); myTextField.y = 200; addChild(mySprite); addChild(myTextField); function onSwipe(swipeEvt:TransformGestureEvent):void { myTextField.text = swipeEvt.phase // Output is "all" } function onTwoTap(tapEvt:GestureEvent):void { myTextField.text = tapEvt.phase // Output is "all" }

Soluo de problemas
Flash Player 10.1 e posterior, Adobe AIR 2 e posterior O suporte de hardware e software para entrada de toque est mudando rapidamente. Esta referncia no mantm uma lista de cada dispositivo que uma combinao de sistema operacional e software pode oferecer suporte a multitoque. No entanto, ela fornece orientaes para utilizar a API de descoberta para determinar se o aplicativo est implementado em um dispositivo que suporte multitoque e fornece dicas para resoluo de problemas no cdigo ActionScript. Os tempos de execuo do Flash respondem a eventos de toque com base nas informaes que o dispositivo, sistema operacional ou software (como, por exemplo, o navegador) passam para o tempo de execuo. Esta dependdncia do ambiente de software complica a docmentao da compatibilidade multitoque. Alguns dispositivos interpretam um gesto ou um toque de forma diferente de outro dispositivo. A rotao definida por dois dedos girando ao mesmo tempo? A rotao de um dedo o mesmo que desenhar um crculo na tela? Depenendo do hardware e do ambiente de software, o gesto de rotao pode ser ambos, ou algo completamente diferente. Dessa forma, o dispositivo comunica ao sistema operacional a entrada do usurio e, em seguida, o sistema operacional transmite essas informaes para o tempo de execuo. Se o tempo de execuo estiver contido em um navegador, o software do navegador interpreta o gesto ou evento de toque e no transmite a entrada para o tempo de execuo. Este comportamento similar ao comportamento das "teclas de atalho": voc tenta utilizar uma combinao especfica de teclas para que o Flash execute algo dentro do navegador e, em vez disso, o navegador abre um menu. API e classes individuais indicam se elas no compatveis com sistemas operacionais especficos. possvel explorar entradas de API individuais aqui, comeando pela classe Multitoque: http://help.adobe.com/pt_BR/FlashPlatform/reference/actionscript/3/flash/ui/Multitouch.html. A seguir, algumas descries de gestos e toque comuns:
Deslocar Mover um dedo da esquerda para a direita ou da direita para a esquerda. Alguns dispositivos requerem dois dedos para deslocar. Girar Tocar com dois dedos e, em seguida, mov-los ao redor em um crculo (como se ambos estivessem traando um

crculo imaginrio em uma superfcie). O ponto piv definido como ponto intermedirio entre os pontos de toque dos dois dedos.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Toque, multitoque e entrada de gestos

575

Deslizar Mover trs dedos da esquerda para a direita ou direita para a esquerda, de cima para baixo ou de baix para cima rapidamente. Ampliar Tocar com dois dedos e distanci-los para ampliar e aproxim-los para reduzir. Pressionar e tocar Mover ou pressionar um dedo e, em seguida, tocar a superfcie com outro dedo.

Cada dispositivo possui sua prpria documentao sobre os gestos que o dispositivo suporta e como executar cada gesto no dispositivo. Geralmente, o usurio deve remover todos os dedos do dispositivo entre gestos, dependendo do sistema operacional. Se voc perceber que seu aplicatiivo no est respondendo a eventos de toque ou gestos, execute os testes a seguir:
1 Existem ouvintes de evento para eventos de gesto ou toque anexados uma classe de objeto que herda atributos da

classe InteractiveObject? Somente instncias InteractiveObjects pode monitorar eventos de gestos ou toques
2 O aplicativo est sendo testado com o Flash Professional CS5? Em caso afirmativo, tente pubicar e testar o

aplicativo, porque o Flash Professional pode interceptar as interaes.

3 Comee de forma simplificada e verifique o que funciona (o cdigo de exemplo a seguir da entrada de API para
Multitouch.inputMode: Multitouch.inputMode=MultitouchInputMode.TOUCH_POINT; var mySprite:Sprite = new Sprite(); var myTextField:TextField = new TextField() mySprite.graphics.beginFill(0x336699); mySprite.graphics.drawRect(0,0,40,40); addChild(mySprite); mySprite.addEventListener(TouchEvent.TOUCH_TAP, taplistener); function taplistener(e:TouchEvent): void { myTextField.text = "I've been tapped"; myTextField.y = 50; addChild(myTextField); }

Toque no retngulo. Se este exemplo fuuncionar, voc saber que o ambiente tem suporte a toque simples, Dessa forma, voc poder testar manipulaes maiis complexas. O teste para suporte de gestos mais complicado. Um dispositivo individual ou sistema operacional possuem suporte a uma combinao de entrada de gestos ou nenhuma combinao. A seguir, um teste simples para o gesto de zoom:
Multitouch.inputMode = MultitouchInputMode.GESTURE; stage.addEventListener(TransformGestureEvent.GESTURE_ZOOM , onZoom); var myTextField = new TextField(); myTextField.y = 200; myTextField.text = "Perform a zoom gesture"; addChild(myTextField); function onZoom(evt:TransformGestureEvent):void { myTextField.text = "Zoom is supported"; }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Toque, multitoque e entrada de gestos

576

Execute um teste de gesto no dispositivo e verifique se o campo de texto populado com a mensagem Zoom is
supported. O ouvinte de evento adicionado ao palco, de forma que voc possa executar o gesto em qualquer

parte do aplicativo. A seguir, um teste simples para o gesto de panormico:

Multitouch.inputMode = MultitouchInputMode.GESTURE; stage.addEventListener(TransformGestureEvent.GESTURE_PAN , onPan); var myTextField = new TextField(); myTextField.y = 200; myTextField.text = "Perform a pan gesture"; addChild(myTextField); function onPan(evt:TransformGestureEvent):void { myTextField.text = "Pan is supported"; }

Execute um teste de gesto panormico no dispositivo e verifique se o campo de texto populado com a mensagem Pan is supported. O ouvinte de evento adicionado ao palco, de forma que voc possa executar o gesto em qualquer parte do aplicativo. Alguns sistemas operacionais e combinaes de dispoitivos possuem suporte a ambos gneros, outros possuem suporte a somente um gnero e outros a nenhum. Teste o ambiente de desenvolvimento de seu aplicativo para certificar-se.

Problemas conhecidos
Os itens a seguir so problemas conhecidos relacionados entrada de toque:
1 Mobile Internet Explorer no sistema operacional Windows Mobile faz o zoom automtico de contedo de arquivo

SWF: Este comportamento do zoom do Internet Explorer pode ser sobrescrito, adicionandoo cdigo a seguir pgina HTML do arquivo SWF:
<head> <meta name="viewport" content="width=device-width, height=device-height, initialscale=1.0"> </head>

2 No Windows 7 (e possivelmente, em outros sistemas operacionais), o usurio deve levantar o dispositivo apontador

(ou os dedos) da tela entre gestos. Por exemplo, para girar e ampliar uma imagem:

Execute o gesto de girar. Levante o dedo da tela. Posicione os dedos de volta tela e execute o gesto de ampliao.
3 No Windows 7 (e possivelmente, outros sistemas operacionais), os gestos de girar e ampliar nem sempre geram

uma fase de atualizao se o usurio executar o gesto de forma muito rpida.

4 O Windows 7 Starter Edition no possui suporte a multitoque. Consulte o frum do AIR Labs para obter mais

detalhes: http://forums.adobe.com/thread/579180?tstart=0
5 Para o Mac OS 10.5.3 e superior, o valores Multitouch.supportsGestureEvents sempre true, mesmo que o

hardware no possua suporte a eventos de gestos.

ltima atualizao em 29/3/2011

577

Captulo 31: Copiar e colar

Flash Player 10 e posterior, Adobe AIR 1.0 e posterior Use as classes na API da rea de transferncia para copiar informaes para e da rea de transferncia do sistema. Os formatos de dados que podem ser transferidos de/para um aplicativo executado no Adobe Flash Player ou no Adobe AIR so os seguintes:

Texto Texto formatado em HTML Dados em RTF Objetos serializados Referncias de objetos (vlido apenas dentro do aplicativo originador) Bitmaps (somente AIR) Arquivos (somente AIR) Strings de URLs (somente AIR)

Princpios bsicos do copiar e colar

Flash Player 10 e posterior, Adobe AIR 1.0 e posterior A API de copiar e colar contm as seguintes classes.
Pacote flash.desktop Classes

Clipboard ClipboardFormats ClipboardTransferMode

A propriedade esttica Clipboard.generalClipboard representa a rea de transferncia do sistema operacional. A classe Clipboard fornece mtodos para ler e escrever dados em objetos da rea de transferncia. As classes HTMLLoader (no AIR) e TextField implementam um comportamento padro para os atalhos comuns do teclado para copiar e colar. Para implementar o comportamento do atalho de copiar e colar para componentes personalizados, voc pode ouvir esses pressionamentos de tecla diretamente. Voc tambm pode usar comandos de menu nativos juntamente com equivalentes de teclas para responder aos pressionamentos de tecla indiretamente. Diferentes representaes das mesmas informaes podem ser disponibilizadas em um nico objeto Clipboard para aumentar a capacidade de outros aplicativos entenderem e usarem os dados. Por exemplo, uma imagem pode ser includa como dados de imagem, como um objeto Bitmap serializado e como um arquivo. O processamento dos dados em um formato pode ser adiado de forma que o formato no seja realmente criado at que os dados naquele formato sejam lidos.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Copiar e colar

578

Leitura e gravao na rea de transferncia do sistema

Flash Player 10 e posterior, Adobe AIR 1.0 e posterior Para ler a rea de transferncia do sistema operacional, chame o mtodo getData() do objeto Clipboard.generalClipbooard, transmitindo o nome do formato a ser lido:
import flash.desktop.Clipboard; import flash.desktop.ClipboardFormats; if(Clipboard.generalClipboard.hasFormat(ClipboardFormats.TEXT_FORMAT)){ var text:String = Clipboard.generalClipboard.getData(ClipboardFormats.TEXT_FORMAT); }

Nota: O contedo em execuo no Flash Player ou em uma caixa de proteo "no aplicativo" no AIR pode chamar apenas o mtodo getData() em um manipulador de eventos para um evento paste. Em outras palavras, somente os cdigos em execuo na caixa de proteo do aplicativo AIR podem chamar o mtodo getData() fora de um manipulador de eventos paste. Para escrever na rea de transferncia, adicione os dados ao objeto Clipboard.generalClipboard em um ou mais formatos. Qualquer dado existente no mesmo formato substitudo automaticamente. No entanto, uma boa prtica limpar tambm a rea de transferncia do sistema antes de escrever novos dados nela para certificar-se de que os dados no relacionados em nenhum outro formato tambm sejam excludos.
import flash.desktop.Clipboard; import flash.desktop.ClipboardFormats; var textToCopy:String = "Copy to clipboard."; Clipboard.generalClipboard.clear(); Clipboard.generalClipboard.setData(ClipboardFormats.TEXT_FORMAT, textToCopy, false);

Nota: O contedo em execuo no Flash Player ou em uma caixa de proteo "no aplicao" no AIR pode chamar apenas o mtodo setData() em um manipulador de eventos para um evento de usurio, como eventos de teclado ou do mouse, alm de um evento copy ou cut. Em outras palavras, somente os cdigos em execuo na caixa de proteo do aplicativo AIR podem chamar o mtodo setData() fora de um manipulador de eventos do usurio.

Copiar e colar HTML no AIR

Adobe AIR 1.0 e posterior O ambiente HTML do Adobe AIR fornece seu prprio conjunto de eventos e comportamento padro para copiar e colar. Apenas cdigos em execuo na caixa de proteo do aplicativo podem acessar a rea de transferncia do sistema diretamente pelo objeto do AIR Clipboard.generalClipboard. Cdigos JavaScript em uma caixa de proteo de no-aplicativo podem acessar a rea de transferncia pelo objeto de evento despachado em resposta a um dos eventos de copiar ou colar despachados por um elemento em um documento HTML. Os eventos de copiar e colar incluem: copy, cut e paste. O objeto despachado para esses eventos fornece acesso rea de transferncia pela propriedade clipboardData.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Copiar e colar

579

Comportamento padro
Adobe AIR 1.0 e posterior Por padro, o AIR copia itens selecionados em resposta ao comando de copiar, que pode ser gerado por um atalho do teclado ou um menu de contexto. Em regies editveis, o AIR recorta textos em resposta ao comando de recortar ou cola textos para o cursor ou seleo em resposta ao comando de colar. Para impedir o comportamento padro, seu manipulador de eventos pode chamar o mtodo preventDefault() do objeto de evento despachado.

Uso da propriedade clipboardData do objeto de evento

Adobe AIR 1.0 e posterior A propriedade clipboardData do objeto de evento despachado como um resultado de um dos eventos de copiar ou colar permite que voc leia e escreva dados da rea de transferncia. Para escrever na rea de transferncia ao manipular um evento de copiar ou recortar, use o mtodo setData() do objeto clipboardData, transmitindo os dados para copiar e o tipo MIME:
function customCopy(event){ event.clipboardData.setData("text/plain", "A copied string."); }

Para acessar os dados que esto sendo colados, voc pode usar o mtodo getData() do objeto clipboardData, transmitindo o tipo MIME do formato de dados. Os formatos disponveis so relatados pela propriedade types.
function customPaste(event){ var pastedData = event.clipboardData("text/plain"); }

O mtodo getData() e a propriedade types podem apenas ser acessados no objeto de evento despachado pelo evento paste. O exemplo a seguir ilustra como substituir o comportamento de copiar e colar padro em uma pgina HTML. O manipulador de eventos copy coloca em itlico o texto copiado e o copia para a rea de transferncia como texto HTML. O manipulador de eventos cut copia os dados selecionados para a rea de transferncia e os remove do documento. O manipulador paste insere o contedo da rea de transferncia como HTML e aplica um estilo na insero como texto em negrito.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Copiar e colar

580

<html> <head> <title>Copy and Paste</title> <script language="javascript" type="text/javascript"> function onCopy(event){ var selection = window.getSelection(); event.clipboardData.setData("text/html","<i>" + selection + "</i>"); event.preventDefault(); } function onCut(event){ var selection = window.getSelection(); event.clipboardData.setData("text/html","<i>" + selection + "</i>"); var range = selection.getRangeAt(0); range.extractContents(); event.preventDefault(); } function onPaste(event){ var insertion = document.createElement("b"); insertion.innerHTML = event.clipboardData.getData("text/html"); var selection = window.getSelection(); var range = selection.getRangeAt(0); range.insertNode(insertion); event.preventDefault(); } </script> </head> <body onCopy="onCopy(event)" onPaste="onPaste(event)" onCut="onCut(event)"> <p>Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt.</p> </body> </html>

Formatos de dados da rea de transferncia

Flash Player 10 e posterior, Adobe AIR 1.0 e posterior Os formatos da rea de transferncia descrevem os dados colocados em um objeto Clipboard. O Flash Player ou o AIR traduz automaticamente os formatos de dados padro entre tipos de dados do ActionScript e formatos da rea de transferncia do sistema. Alm disso, os objetos do aplicativo podem ser transferidos internamente em ou entre aplicativos com base no ActionScript, usando formatos definidos pelo aplicativo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Copiar e colar

581

Um objeto Clipboard pode conter representaes das mesmas informaes em diferentes formatos. Por exemplo, um objeto Clipboard representando um Sprite poderia incluir um formato de referncia para ser usado no mesmo aplicativo, um formato serializado para ser usado por outro aplicativo em execuo no Flash Player ou no AIR, um formato bitmap para ser usado por um editor de imagens e um formato de lista de arquivo, talvez com renderizao adiada para codificar um arquivo PNG, para copiar ou arrastar uma representao do Sprite para o sistema de arquivos.

Formatos de dados padro

Flash Player 10 e posterior, Adobe AIR 1.0 e posterior As constantes que definem os nomes de formato padro so fornecidas na classe ClipboardFormats:
Constante TEXT_FORMAT HTML_FORMAT RICH_TEXT_FORMAT Descrio Dados em formato de texto so traduzidos para e da classe String do ActionScript. Texto com marcao HTML. Dados em RTF so traduzidos para e da classe ByteArray do ActionScript. A marcao RTF no interpretada ou traduzida de forma alguma. (somente AIR) Dados em formato bitmap so traduzidos para e da classe BitmapData do ActionScript. (somente AIR) Dados em formato de lista de arquivo so traduzidos para e de uma matriz de objetos File do ActionScript. (somente AIR) Dados em formato de URL so traduzidos para e a partir da classe String do ActionScript.

BITMAP_FORMAT FILE_LIST_FORMAT

URL_FORMAT

Ao copiar e colar dados em resposta a um evento copy, cut ou paste em contedo HTML hospedado em um aplicativo AIR, devem ser usados tipos MIME em vez das sequncias de caracteres ClipboardFormat. Os tipos MIME de dados vlidos so:
Tipo MIME Texto URL Bitmap Lista de arquivos Descrio "text/plain" "text/uri-list" "image/x-vnd.adobe.air.bitmap" "application/x-vnd.adobe.air.file-list"

Nota: Dados RTF no esto disponveis da propriedade clipboardData do objeto de evento despachado como resultado de um evento paste no contedo HTML.

Formatos de dados personalizados

Flash Player 10 e posterior, Adobe AIR 1.0 e posterior Voc pode usar formatos personalizados definidos por aplicativo para transferir objetos como referncias ou cpias serializadas. As referncias so vlidas apenas no mesmo aplicativo. Os objetos serializados podem ser transferidos entre aplicativos, mas s podem ser usados com objetos que permanecem vlidos quando serializados e desserializados. Geralmente, objetos podem ser serializados se suas propriedades forem tipos simples ou objetos serializvel.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Copiar e colar

582

Para adicionar um objeto serializado a um objeto Clipboard, defina o parmetro serializable como serializable como true ao chamar o mtodo Clipboard.setData(). O nome do formato pode ser um dos formatos padro ou uma seqncia de caracteres arbitrria definida pelo seu aplicativo.

Modos de transferncia
Flash Player 10 e posterior, Adobe AIR 1.0 e posterior Quando um objeto escrito na rea de transferncia usando um formato de dados personalizado, os dados do objeto podem ser lidos da rea de transferncia como referncia ou uma cpia serializada do objeto original. H quatro modos de transferncia que determinam se os objetos so transferidos como referncias ou como cpias serializadas:
Modo de transferncia ClipboardTransferModes.ORIGINAL_ONLY Descrio Apenas uma referncia retornada. Se nenhuma referncia estiver disponvel, um valor null ser retornado. Uma referncia retornada, se disponvel. Caso contrrio, uma cpia serializada retornada. Apenas uma cpia serializada retornada. Se nenhuma cpia serializada estiver disponvel, ser retornado um valor null. Uma cpia serializada retornada, se disponvel. Caso contrrio, uma referncia retornada.

ClipboardTransferModes.ORIGINAL_PREFFERED

ClipboardTransferModes.CLONE_ONLY

ClipboardTransferModes.CLONE_PREFFERED

Leitura e escrita de formatos de dados personalizados

Flash Player 10 e posterior, Adobe AIR 1.0 e posterior Ao gravar um objeto na rea de transferncia, voc pode usar qualquer sequncia de caracteres que no comece com os prefixos reservados air: ou flash: para o parmetro format. Use a mesma seqncia de caracteres do formato para ler o objeto. Os exemplos a seguir ilustram como ler e escrever objetos na rea de transferncia:
public function createClipboardObject(object:Object):Clipboard{ var transfer:Clipboard = Clipboard.generalClipboard; transfer.setData("object", object, true); }

Para extrair um objeto serializado do objeto da rea de transferncia (aps uma operao de soltar ou colar), use o mesmo nome de formato e os modos de transferncia CLONE_ONLY ou CLONE_PREFFERED.
var transfer:Object = clipboard.getData("object", ClipboardTransferMode.CLONE_ONLY);

Uma referncia sempre adicionada ao objeto Clipboard. Para extrair a referncia do objeto da rea de transferncia (aps uma operao de soltar ou colar), em vez da cpia serializada, use os modos de transferncia ORIGINAL_ONLY ou ORIGINAL_PREFFERED:
var transferredObject:Object = clipboard.getData("object", ClipboardTransferMode.ORIGINAL_ONLY);

As referncias so vlidas apenas se o objeto Clipboard se originar do aplicativo atual. Use o modo de transferncia ORIGINAL_PREFFERED para acessar a referncia quando ela estiver disponvel e o clone serializado quando a referncia no estiver disponvel.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Copiar e colar

583

Renderizao adiada
Flash Player 10 e posterior, Adobe AIR 1.0 e posterior Se criar um formato de dados for computacionalmente caro, voc poder usar o processamento adiado fornecendo uma funo que fornea os dados em demanda. A funo s chamada se um receptor da operao de soltar ou colar solicitar dados no formato adiado. A funo de processamento adicionada a um objeto Clipboard usando o mtodo setDataHandler(). A funo deve retornar os dados no formato apropriado. Por exemplo, se voc chamou setDataHandler(ClipboardFormat.TEXT_FORMAT, writeText), a funo writeText() dever retornar uma seqncia de caracteres. Se um formato de dados do mesmo tipo for adicionado a um objeto Clipboard com o mtodo setData(), esses dados tem precedncia sobre a verso adiada (a funo de renderizao nunca chamada). A funo de renderizao pode ou no ser chamada novamente se os mesmos dados da rea de transferncia forem acessados uma segunda vez. Nota: No Mac OS X, a renderizao adiada s funciona com formatos de dados personalizados. No caso de formatos de dados padro, a funo de renderizao chamada imediatamente.

Colagem de texto usando uma funo de renderizao adiada

Flash Player 10 e posterior, Adobe AIR 1.0 e posterior O exemplo a seguir ilustra como implementar uma funo de renderizao adiada. Quando um usurio pressiona o boto Copiar, o aplicativo limpa a rea de transferncia para garantir que nenhum dado de operaes anteriores seja mantido. Em seguida, o mtodo setDataHandler() define a funo renderData() como renderizador da rea de transferncia. Quando um usurio seleciona o comando Colar no menu de contexto do campo de texto de destino, o aplicativo acessa a rea de transferncia e define o texto de destino. Como o formato de dados de texto na rea de transferncia foi definido com uma funo em vez de uma string, a rea de transferncia chama a funo renderData(). A funo renderData() retorna o texto no texto de origem, que ento atribudo ao texto de destino. Observe que se voc editar o texto de origem antes de pressionar o boto Colar, a edio ser refletida no texto colado, mesmo quando a edio ocorrer aps o boto de copiar ter sido pressionado. Isso porque a funo de processamento no copia o texto de origem at que o boto de colar seja pressionado. (Ao usar o processamento adiado em um aplicativo real, voc pode desejar armazenar ou proteger os dados de origem de alguma maneira para impedir esse problema.)

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Copiar e colar

584

Exemplo de Flash
package { import flash.desktop.Clipboard; import flash.desktop.ClipboardFormats; import flash.desktop.ClipboardTransferMode; import flash.display.Sprite; import flash.text.TextField; import flash.text.TextFormat; import flash.text.TextFieldType; import flash.events.MouseEvent; import flash.events.Event; public class DeferredRenderingExample extends Sprite { private var sourceTextField:TextField; private var destination:TextField; private var copyText:TextField; public function DeferredRenderingExample():void { sourceTextField = createTextField(10, 10, 380, 90); sourceTextField.text = "Neque porro quisquam est qui dolorem " + "ipsum quia dolor sit amet, consectetur, adipisci velit."; copyText = createTextField(10, 110, 35, 20); copyText.htmlText = "<a href='#'>Copy</a>"; copyText.addEventListener(MouseEvent.CLICK, onCopy); destination = createTextField(10, 145, 380, 90); destination.addEventListener(Event.PASTE, onPaste); } private function createTextField(x:Number, y:Number, width:Number, height:Number):TextField { var newTxt:TextField = new TextField(); newTxt.x = x; newTxt.y = y; newTxt.height = height; newTxt.width = width; newTxt.border = true; newTxt.multiline = true; newTxt.wordWrap = true; newTxt.type = TextFieldType.INPUT; addChild(newTxt); return newTxt; } public function onCopy(event:MouseEvent):void { Clipboard.generalClipboard.clear(); Clipboard.generalClipboard.setDataHandler(ClipboardFormats.TEXT_FORMAT, renderData); } public function onPaste(event:Event):void {

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Copiar e colar

585

sourceTextField.text = Clipboard.generalClipboard.getData(ClipboardFormats.TEXT_FORMAT).toString; } public function renderData():String { trace("Rendering data"); var sourceStr:String = sourceTextField.text; if (sourceTextField.selectionEndIndex > sourceTextField.selectionBeginIndex) { return sourceStr.substring(sourceTextField.selectionBeginIndex, sourceTextField.selectionEndIndex); } else { return sourceStr; } } } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Copiar e colar

586

Exemplo do Flex
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" width="326" height="330" applicationComplete="init()"> <mx:Script> <![CDATA[ import flash.desktop.Clipboard; import flash.desktop.ClipboardFormats; public function init():void { destination.addEventListener("paste", doPaste); } public function doCopy():void { Clipboard.generalClipboard.clear(); Clipboard.generalClipboard.setDataHandler(ClipboardFormats.TEXT_FORMAT, renderData); } public function doPaste(event:Event):void { destination.text = Clipboard.generalClipboard.getData(ClipboardFormats.TEXT_FORMAT).toString; } public function renderData():String{ trace("Rendering data"); return source.text; } ]]> </mx:Script> <mx:Label x="10" y="10" text="Source"/> <mx:TextArea id="source" x="10" y="36" width="300" height="100"> <mx:text>Neque porro quisquam est qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit.</mx:text> </mx:TextArea> <mx:Label x="10" y="181" text="Destination"/> <mx:TextArea id="destination" x="12" y="207" width="300" height="100"/> <mx:Button click="doCopy();" x="91" y="156" label="Copy"/> </mx:Application>

ltima atualizao em 29/3/2011

587

Captulo 32: Entrada do acelermetro

Flash Player 10.1 e posterior, Adobe AIR 2 e posterior A classe Accelerometer despacha eventos com base na atividade detectada pelo sensor de movimento do dispositivo. Estes dados representam o local do dispositivo ou movimento ao longo de um eixo de tridimensional. Quando o dispositivo se move, o sensor detecta este movimento e retorna as coordenadas de acelerao do dispositivo. A classe Accelerometer fornece mtodos para consultar se o acelermetro suportado ou no e tambm para definir a taxa na qual os eventos de acelerao so despachados. Os eixos do acelermetro so normalizados na orientao do visor, e no na orientao fsica do dispositivo. Quando o dispositivo reorienta o visor, os eixos do acelermetro tambm so reorientados. Assim, o eixo Y est sempre aproximadamente na posio vertical quando o usurio segura o telefone na posio vertical normal de exibio, independentemente da maneira como o telefone girado. Se a orientao automtica estiver desligada, por exemplo quando o contedo SWF em um navegador est no modo de tela cheia, os eixos do acelermetro no sero reorientados quando o dispositivo for girado.

Mais tpicos da Ajuda

flash.sensors.Accelerometer flash.events.AccelerometerEvent Michal Chiaze: AIR e o acelermetro Jonathan Campos: AIR para Android: Acelermetro

Verificando suporte ao acelermetro

Utilize a propriedade Accelerometer.isSupported para testar o ambiente de tempo de execuo em relao a habilidade de utilizar este recurso:
if (Accelerometer.isSupported) { // Set up Accelerometer event listeners and code. }

A classe acelermetro e seus membros so acessveis pelas verses de tempo de execuo listados em cada entrada de API. No entanto o ambiente atual durante o tempo de execuo determina a disponibilidade para este recurso. Por exemplo, voc pode compilar o cdigo as propriedades da classe Accelerometer para o Flash Player 10.1, mas ser necessrio utilizar a propriedade Accelerometer.isSupported para testar a disponibilidade do recurso Accelerometer no dispositivo do usurio. Caso Accelerometer.isSupported seja true durante o tempo de execuo, ento o suporte ao Accelerometer existe.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Entrada do acelermetro

588

Detectando mudanas no acelermetro

Para utilizar o sensor de acelermetro, instancie um objeto Accelerometer e registre para atualizar eventos enviados. O evento update um objeto de evento Accelerometer. O evento possui quatro propriedades, so eles:

accelerationXAcelerao ao longo do eixo x, medida em g. O eixo x vai da esquerda para a direita do

dispositivo quando est na posio perpendicular. (O dispositivo est na vertical quando o topo do dispositivo est voltado para cima). A acelerao ser positiva se o dispositivo for movido para a direita.

accelerationYAcelerao ao longo do eixo y, medida em g. O eixo y percorre a parte superior do dispositivo

quando est na posio perpendicular. (O dispositivo est na vertical quando o topo do dispositivo est voltado para cima). A acelerao ser positiva se o dispositivo for movido para cima deste eixo.

accelerationZAcelerao ao longo do eixo z, medida em g. O eixo z corre perpendicularmente parte fronta

do dispositivo. A acelerao positiva se voc mover o dispositivo de forma que a face do dispositivo aponte para cima. A acelerao negativa se a face do dispositivo apontar para o cho.

timestampO nmero de milissegundos no momento do evento a partir do incio da execuo.

1 g a acelerao padro da gravidade, aproximadamente 9.8 m/s2.. Este um exemplo bsico que exibe dados de um acelermetro em um campo de texto:
var accl:Accelerometer; if (Accelerometer.isSupported) { accl = new Accelerometer(); accl.addEventListener(AccelerometerEvent.UPDATE, updateHandler); } else { accTextField.text = "Accelerometer feature not supported"; } function updateHandler(evt:AccelerometerEvent):void { accTextField.text = "acceleration X: " + evt.accelerationX.toString() + "\n" + "acceleration Y: " + evt.accelerationY.toString() + "\n" + "acceleration Z: " + evt.accelerationZ.toString() }

Para utilizar este exemplo, certifique-se de criar o campo de texto accTextField e adicion-lo para a lista de exibio antes de utilizar este cdigo. Voc pode ajustar o intervalo de tempo para eventos de acelermetro chamando o mtodo setRequestedUpdateInterval() do objeto Accelerometer. Este mtodo usa um parmetro interval, que o intervalo de atualizao solicitado em milisegundos:
var accl:Accelerometer; accl = new Accelerometer(); accl.setRequestedUpdateInterval(1000);

A hora real entre atualizaes do acelermetro pode ser maior ou menor do que este valor. Qualquer mudana no intervalo de atualizao afeta todos os ouvintes registrados. Se o mtodo setRequestedUpdateInterval() no for chamado, o aplicativo recebe atualizaes com base no intervalo padro do dispositivo. Dados do acelermetro tem alguns graus de impreciso. Voc pode utilizar uma mdia de movimento de dados recentes para aperfeioar os dados. Por exemplo, o exemplo a seguir fatora leituras recentes do acelermetro com a leitura atual para obter um resultado arredondado:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Entrada do acelermetro

589

var accl:Accelerometer; var rollingX:Number = 0; var rollingY:Number = 0; var rollingZ:Number = 0; const FACTOR:Number = 0.25; if (Accelerometer.isSupported) { accl = new Accelerometer(); accl.setRequestedUpdateInterval(200); accl.addEventListener(AccelerometerEvent.UPDATE, updateHandler); } else { accTextField.text = "Accelerometer feature not supported"; } function updateHandler(event:AccelerometerEvent):void { accelRollingAvg(event); accTextField.text = rollingX + "\n" + rollingY + "\n" + rollingZ + "\n"; } function accelRollingAvg(event:AccelerometerEvent):void { rollingX = (event.accelerationX * FACTOR) + (rollingX * (1 - FACTOR)); rollingY = (event.accelerationY * FACTOR) + (rollingY * (1 - FACTOR)); rollingZ = (event.accelerationZ * FACTOR) + (rollingZ * (1 - FACTOR)); }

No entanto, esta mdia de movimentao s desejvel se o intervalo de atualizao do acelermetro for pequeno.

ltima atualizao em 29/3/2011

590

Captulo 33: Arrastar e soltar no AIR

Adobe AIR 1.0 e posterior Use as classes na API de arrastar e soltar do Adobe AIR para suportar gestos de arrastar e soltar de interface do usurio. Um gesto neste sentido uma ao do usurio, mediada pelo sistema operacional e seu aplicativo, expressando uma inteno de copiar, mover ou vincular informaes. Um gesto de arrastar para fora ocorre quando o usurio arrasta um objeto para fora de um componente ou aplicativo. Um gesto de arrastar para dentro ocorre quando o usurio arrasta para dentro um objeto de fora um componente ou aplicativo. Com a API de arrastar e soltar, voc pode permitir que um usurio arraste dados entre aplicativos e entre componentes dentro de um aplicativo. Os formatos de transferncia suportados incluem:

Bitmaps Arquivos Texto formatado em HTML Texto Dados em RTF URLs Promessas de arquivo Objetos serializados Referncias a objetos (vlido somente dentro do aplicativo originador)

Princpios bsicos de arrastar e soltar no AIR

Adobe AIR 1.0 e posterior Para ver uma rpida explicao e exemplos de cdigo do uso do arrastar e soltar em um aplicativo AIR, consulte os seguintes artigos de incio rpido no Adobe Developer Connection:

Dando suporte ao arrastar e soltar e ao copiar e colar (Flex) Dando suporte ao arrastar e soltar e ao copiar e colar (Flash)
A API de arrastar e soltar contm as seguintes classes:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Arrastar e soltar no AIR

591

Pacote flash.desktop

Classes

NativeDragManager NativeDragOptions Clipboard URLFilePromise IFilePromise

Constantes usadas com a API de arrastar e soltar so definidas nas seguintes classes: NativeDragActions ClipboardFormat ClipboardTransferModes

flash.events

NativeDragEvent

Estgios do gesto de arrastar e soltar O gesto de arrastar e soltar possui trs estgios:
Iniciao Um usurio inicia uma operao de arrastar e soltar arrastando de um componente, ou um item em um componente, enquanto mantm pressionado o boto do mouse. O componente que a origem do item arrastado normalmente designado como o iniciador do ao de arrastar e despacha eventos nativeDragStart e nativeDragComplete. Um aplicativo do Adobe AIR inicia uma operao de arrastar chamando o mtodo NativeDragManager.doDrag() em resposta a um evento mouseDown ou mouseMove.

Se a operao de arrastar for iniciada de fora do aplicativo AIR, no haver nenhum objeto iniciador para despachar os eventos nativeDragStart ou nativeDragComplete.
Arrastar Ao segurar o boto do mouse, o usurio move o cursor do mouse para outro componente, aplicativo ou a rea de trabalho. Uma vez que a ao de arrastar esteja em andamento, o objeto iniciador despacha eventos nativeDragUpdate. (No entanto, este evento no despachado no AIR para Linux.) Quando o usurio move o mouse sobre um possvel destino no qual soltar em um aplicativo AIR, o destino despacha um evento nativeDragEnter. O manipulador de eventos pode inspecionar o objeto de evento para determinar se os dados arrastados esto disponveis em um formato que o destino aceite e, se sim, permitir ao usurio soltar os dados nele chamando o mtodo NativeDragManager.acceptDragDrop().

Enquanto o gesto de arrastar permanece sobre um objeto interativo, esse objeto despacha eventos nativeDragOver. Quando o gesto de arrastar deixa o objeto interativo, ele despacha um evento nativeDragExit.
Soltar O usurio libera o mouse sobre um destino de soltar aceitvel. Se o destino for um componente ou aplicativo AIR, o objeto de destino despacha um evento nativeDragDrop. O manipulador de eventos pode acessar os dados transferidos do objeto de evento. Se o destino estiver fora do AIR, o sistema operacional ou outro aplicativo manipular a ao de soltar. Nos dois casos, o objeto iniciador despacha um evento nativeDragComplete (se a ao de arrastar tiver iniciado de dentro do AIR).

A classe NativeDragManager controla os gestos de arrastar para dentro e para fora. Todos os membros da classe NativeDragManager so estticos, no crie uma instncia dessa classe.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Arrastar e soltar no AIR

592

O objeto Clipboard Os dados arrastados para dentro ou para fora de um aplicativo ou componente so contidos em um objeto Clipboard. Um nico objeto Clipboard pode disponibilizar representaes diferentes das mesmas informaes para aumentar a probabilidade de que outro aplicativo possa entender e usar os dados. Por exemplo, uma imagem poderia ser includa como dados de imagem, como um objeto Bitmap serializado e como um arquivo. O processamento dos dados em um formato pode ser adiado para uma funo de processamento no chamada at que os dados sejam lidos. Aps um gesto de arrastar ter sido iniciado, o objeto Clipboard pode apenas ser acessado de dentro de um manipulador de eventos para os eventos nativeDragEnter, nativeDragOver e nativeDragDrop. Aps o gesto de arrastar ter sido finalizado, o objeto Clipboard no poder ser lido ou reutilizado. Um objeto de aplicativo pode ser transferido como uma referncia e um objeto serializado. As referncias so vlidas apenas dentro do aplicativo originador. Transferncias de objetos serializados so vlidas entre aplicativos AIR, mas podem apenas ser usadas com objetos que permanecem vlidos quando serializados e desserializados. Objetos serializados so convertidos no Action Message Format para ActionScript 3 (AMF3), um formato de transferncia de dados baseado em seqncia de caracteres. Trabalho com a estrutura do Flex Na maioria dos casos, melhor usar a API de arrastar e soltar do Adobe Flex ao criar aplicativos do Flex. A estrutura do Flex fornece um conjunto de recursos equivalente quando um aplicativo do Flex executado no AIR (ela usa o NativeDragManager do AIR internamente). O Flex tambm mantm um conjunto de recursos mais limitado quando um aplicativo ou componente est em execuo dentro do ambiente do navegador mais restritivo. As classes do AIR no podem ser usadas em componentes ou aplicativos executados fora do ambiente de tempo de execuo do AIR.

Suporte ao gesto de arrastar para fora

Adobe AIR 1.0 e posterior Para suportar o gesto de arrastar para fora, voc deve criar um objeto Clipboard em resposta a um evento mouseDown e envi-lo ao mtodo NativeDragManager.doDrag(). Seu aplicativo pode ento ouvir o evento nativeDragComplete sobre o objeto iniciador para determinar que ao tomar quando o usurio conclui ou abandona o gesto.

Preparao de dados para transferncia

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para preparar dados ou um objeto para arrastar, crie um objeto Clipboard e adicione as informaes a serem transferidas em um ou mais formatos. Voc pode usar os formatos de dados padro para passar dados, que podem ser convertidos automaticamente em formatos nativos da rea de transferncia e em formatos definidos pelo aplicativo para passar objetos. Se, do ponto de vista computacional, for caro converter as informaes a serem transferidas para um formato especfico, voc pode fornecer o nome de uma funo de manipulador para realizar a converso. A funo chamada se, e apenas se, o componente ou aplicativo receptor ler o formato associado. Para mais informaes sobre formatos de rea de transferncia, veja Formatos de dados da rea de transferncia na pgina 580.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Arrastar e soltar no AIR

593

O exemplo a seguir ilustra como criar um objeto Clipboard contendo um bitmap em vrios formatos: um objeto Bitmap, um formato de bitmap nativo e um formato da lista de arquivo contendo o arquivo do qual o bitmap foi originalmente carregado:
import flash.desktop.Clipboard; import flash.display.Bitmap; import flash.filesystem.File; public function createClipboard(image:Bitmap, sourceFile:File):Clipboard{ var transfer:Clipboard = new Clipboard(); transfer.setData("CUSTOM_BITMAP", image, true); //Flash object by value and by reference transfer.setData(ClipboardFormats.BITMAP_FORMAT, image.bitmapData, false); transfer.setData(ClipboardFormats.FILE_LIST_FORMAT, new Array(sourceFile), false); return transfer; }

Incio de uma operao de arrastar e soltar

Adobe AIR 1.0 e posterior Para iniciar uma operao de arrastar, chame o mtodo NativeDragManager.doDrag() em resposta a um evento de mouse para baixo. O mtodo doDrag() um mtodo esttico que adota os seguintes parmetros:
Parmetro iniciador Descrio O objeto do qual a ao de arrastar se origina e que despacha os eventos dragStart e dragComplete. O iniciador deve ser um objeto interativo. O objeto Clipboard contendo os dados a serem transferidos. O objeto Clipboard referenciado nos objetos NativeDragEvent despachados durante a seqncia de arrastar e soltar. (Opcional) Um objeto BitmapData a ser exibido durante a ao de arrastar. A imagem pode especificar um valor alpha. (Observao: o Microsoft Windows sempre aplica uma atenuao alfa fixa a imagens de arrastar). (Opcional) Um objeto Point especificando o deslocamento da imagem de arrastar do ponto ativo do mouse. Use coordenadas negativas para mover a imagem de arrastar para cima e esquerda com relao ao cursor do mouse. Se nenhum deslocamento for fornecido, o canto superior esquerdo da imagem de arrastar ser posicionado no ponto ativo do mouse. (Opcional) Um objeto NativeDragOptions especificando que aes (copiar, mover ou vincular) so vlidas para a operao de arrastar. Se nenhum argumento for fornecido, todas as aes sero permitidas. O objeto DragOptions referenciado em objetos NativeDragEvent para permitir que um possvel destino da ao de arrastar verifique se as aes permitidas so compatveis com o objetivo do componente de destino. Por exemplo, um componente trash pode aceitar apenas gestos de arrastar que permitem a ao de mover.

rea de transferncia

dragImage

deslocamento

actionsAllowed

O exemplo a seguir ilustra como iniciar uma operao de arrastar para um objeto de bitmap carregado de um arquivo. O exemplo carrega uma imagem e, em um evento mouseDown, inicia a operao de arrastar.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Arrastar e soltar no AIR

594

package { import flash.desktop.NativeDragManager; import mx.core.UIComponent; import flash.display.Sprite; import flash.display.Loader; import flash.system.LoaderContext; import flash.net.URLRequest; import flash.geom.Point; import flash.desktop.Clipboard; import flash.display.Bitmap; import flash.filesystem.File; import flash.events.Event; import flash.events.MouseEvent; public class DragOutExample extends UIComponent Sprite { protected var fileURL:String = "app:/image.jpg"; protected var display:Bitmap; private function init():void { loadImage(); } private function onMouseDown(event:MouseEvent):void { var bitmapFile:File = new File(fileURL); var transferObject:Clipboard = createClipboard(display, bitmapFile); NativeDragManager.doDrag(this, transferObject, display.bitmapData, new Point(-mouseX,-mouseY)); } public function createClipboard(image:Bitmap, sourceFile:File):Clipboard { var transfer:Clipboard = new Clipboard(); transfer.setData("bitmap", image, true); // ActionScript 3 Bitmap object by value and by reference transfer.setData(ClipboardFormats.BITMAP_FORMAT, image.bitmapData, false); // Standard BitmapData format transfer.setData(ClipboardFormats.FILE_LIST_FORMAT,

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Arrastar e soltar no AIR

595

new Array(sourceFile), false); // Standard file list format return transfer; } private function loadImage():void { var url:URLRequest = new URLRequest(fileURL); var loader:Loader = new Loader(); loader.load(url,new LoaderContext()); loader.contentLoaderInfo.addEventListener(Event.COMPLETE, onLoadComplete); } private function onLoadComplete(event:Event):void { display = event.target.loader.content; var flexWrapper:UIComponent = new UIComponent(); flexWrapper.addChild(event.target.loader.content); addChild(flexWrapper); flexWrapper.addEventListener(MouseEvent.MOUSE_DOWN, onMouseDown); } } }

Concluso de uma transferncia de arrastar para fora

Adobe AIR 1.0 e posterior Quando um usurio solta o item arrastado liberando o mouse, o objeto iniciador despacha um evento nativeDragComplete. Voc pode verificar a propriedade dropAction do objeto de evento e executar a ao apropriada. Por exemplo, se a ao for NativeDragAction.MOVE, voc poderia remover o item de origem de seu local original. O usurio pode abandonar um gesto de arrastar liberando o boto do mouse enquanto o cursor est fora de um destino de arrastar aceitvel. O gerente de arrastar define a propriedade dropAction para um gesto abandonado a NativeDragAction.NONE.

Suporte ao gesto de arrastar para dentro

Adobe AIR 1.0 e posterior Para suportar o gesto de arrastar para dentro, seu aplicativo (ou, mais tipicamente, um componente visual do seu aplicativo) deve responder aos eventos nativeDragEnter ou nativeDragOver.

Etapas em uma operao tpica de arrastar

Adobe AIR 1.0 e posterior A seguinte seqncia de eventos tpica para uma operao de arrastar:
1 O usurio arrasta um objeto da rea de transferncia sobre um componente. 2 O componente despacha um evento nativeDragEnter. 3 O manipulador de eventos nativeDragEnter examina o objeto de evento para verificar os formatos de dados

disponveis e as aes permitidas. Se o componente pode manipular a ao de soltar, ele chama

NativeDragManager.acceptDragDrop().

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Arrastar e soltar no AIR

596

4 O NativeDragManager altera o cursor do mouse para indicar que o objeto pode ser solto. 5 O usurio solta o objeto sobre o componente. 6 O componente receptor despacha um evento nativeDragDrop. 7 O componente receptor l os dados no formato desejado do objeto Clipboard dentro do objeto de evento. 8 Se o gesto de arrastar foi originado no aplicativo AIR, o objeto interativo iniciador despacha um evento
nativeDragComplete. Se o gesto foi originado fora do AIR, nenhum comentrio enviado.

Reconhecimento de um gesto de arrastar para dentro

Adobe AIR 1.0 e posterior Quando um usurio arrasta um item da rea de transferncia para dentro dos limites de um componente visual, o componente despacha eventos nativeDragEnter e nativeDragOver. Para determinar se o componente pode aceitar o item da rea de transferncia, os manipuladores para esses eventos pode verificar as propriedades clipboard e allowedActions do objeto de evento. Para sinalizar que o componente pode aceitar a ao de soltar, o manipulador de eventos deve chamar o mtodo NativeDragManager.acceptDragDrop(), transmitindo uma referncia ao componente receptor. Se mais de um ouvinte de evento registrado chamar o mtodo acceptDragDrop(), o ltimo manipulador da lista tem precedncia. A chamada acceptDragDrop() permanece vlida at que o mouse deixe os limites do objeto recebedor, disparando o evento nativeDragExit. Se mais de uma ao for permitida no parmetro allowedActions transmitido a doDrag(), o usurio pode indicar qual das aes permitidas pretende mantendo pressionada uma tecla de modificador. O gerente de arrastar altera a imagem do cursor para dizer ao usurio que ao ocorreria se ele conclusse a ao de soltar. A ao pretendida reportado pela propriedade dropAction do evento NativeDragEvent. O conjunto de ao para um gesto de arrastar apenas consultivo. Os componentes envolvidos na transferncia devem implementar o comportamento apropriado. Para completar uma ao de mover, por exemplo, o iniciador de arrastar poderia remover o item arrastado e o destino de soltar poderia adicion-lo. Seu destino de arrastar pode limitar a ao de soltar para uma das trs aes possveis definindo a propriedade
dropAction da classe NativeDragManager. Se um usurio tenta escolher uma ao diferente usando o teclado,

NativeDragManager exibe o cursor unavailable. Define a propriedade dropAction nos manipuladores para os eventos
nativeDragEnter e nativeDragOver.

O exemplo a seguir ilustra um manipulador de eventos para um evento nativeDragEnter ou nativeDragOver. Esse manipulador aceita apenas um gesto de arrastar para dentro se a rea de transferncia sendo arrastada contiver dados em formato de texto.
import flash.desktop.NativeDragManager; import flash.events.NativeDragEvent; public function onDragIn(event:NativeDragEvent):void{ NativeDragManager.dropAction = NativeDragActions.MOVE; if(event.clipboard.hasFormat(ClipboardFormats.TEXT_FORMAT)){ NativeDragManager.acceptDragDrop(this); //'this' is the receiving component } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Arrastar e soltar no AIR

597

Concluso da ao de soltar
Adobe AIR 1.0 e posterior Quando o usurio solta um item arrastado em um objeto interativo que aceitou o gesto, o objeto interativo despacha um evento nativeDragDrop. O manipulador desse evento pode extrair os dados a propriedade clipboard do objeto de evento. Quando a rea de transferncia contm um formato definido por aplicativo, o parmetro transferMode transmitido ao mtodo getData() do objeto Clipboard determina se o gerenciador de arrastar retorna uma referncia ou uma verso serializada do objeto. O exemplo a seguir ilustra um manipulador de eventos para o evento nativeDragDrop:
import flash.desktop.Clipboard; import flash.events.NativeDragEvent; public function onDrop(event:NativeDragEvent):void { if (event.clipboard.hasFormat(ClipboardFormats.TEXT_FORMAT)) { var text:String = String(event.clipboard.getData(ClipboardFormats.TEXT_FORMAT, ClipboardTransferMode.ORIGINAL_PREFERRED)); }

Depois que o manipulador de eventos for encerrado, o objeto Clipboard no ser mais vlido. Qualquer tentativa de acessar o objeto ou seus dados gera um erro.

Atualizao da aparncia visual de um componente

Adobe AIR 1.0 e posterior Um componente pode atualizar sua aparncia visual com base nos eventos NativeDragEvent. A tabela a seguir descreve os tipos de alteraes que um componente tpico faria em resposta aos diferentes eventos:
Evento nativeDragStart Descrio O objeto interativo iniciante pode usar o evento nativeDragStart para fornecer comentrios visuais que o gesto de arrastar originou desse objeto interativo. O objeto interativo iniciante pode usar o evento nativeDragUpdate para atualizar seu estado durante o gesto. (Este evento no existe no AIR para Linux.) Um possvel objeto interativo receptor pode usar esse evento para assumir o foco ou indicar visualmente que ele pode ou no aceitar a ao de soltar. Um possvel objeto interativo receptor pode usar esse evento para responder ao movimento do mouse dentro do objeto interativo, como quando o mouse insere uma regio ativa de um componente complexo, como uma exibio de mapa de rua. Um possvel objeto interativo receptor pode usar esse evento para restaurar seu estado quando um gesto de arrastar se move para fora de seus limites. O objeto interativo iniciante pode usar esse evento para atualizar seu modelo de dados associado, como removendo um item de uma lista e para restaurar seu estado visual.

nativeDragUpdate

nativeDragEnter

nativeDragOver

nativeDragExit

nativeDragComplete

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Arrastar e soltar no AIR

598

Rastreamento da posio do mouse durante um gesto de arrastar para dentro

Adobe AIR 1.0 e posterior Enquanto um gesto de arrastar permanece sobre um componente, esse componente despacha eventos nativeDragOver. Esses eventos so despachados a cada poucos milissegundos e tambm sempre que o mouse se move. O objeto de evento nativeDragOver pode ser usado para determinar a posio do mouse sobre o componente. Ter acesso posio do mouse pode ser til em situaes onde o componente receptor complexo, mas no formado de subcomponentes. Por exemplo, se seu aplicativo exibiu um bitmap contendo um mapa de rua e voc desejava realar zonas no mapa quando o usurio arrastasse informaes a eles, voc poderia usar as coordenadas do mouse reportadas no evento nativeDragOver para rastrear a posio do mouse no mapa.

Arrastar e soltar em HTML

Adobe AIR 1.0 e posterior Para arrastar dados para dentro e fora de um aplicativo baseado em HTML (ou para dentro e fora do HTML exibido em um HTMLLoader), voc pode usar eventos de arrastar e soltar HTML. A API de arrastar e soltar HTML permite que voc arraste para e de elementos DOM no contedo HTML. Nota: Voc tambm pode usar as APIs NativeDragEvent e NativeDragManager do AIR ouvindo eventos no objeto HTMLLoader contendo o contedo HTML. No entanto, a API HTML melhor integrada com o DOM HTML e oferece a voc controle do comportamento padro.

Comportamento padro de arrastar e soltar

Adobe AIR 1.0 e posterior O ambiente HTML fornece o comportamento padro para gestos de arrastar e soltar envolvendo texto, imagens e URLs. Usando o comportamento padro, voc sempre pode arrastar esses tipos de dados para fora de um elemento. No entanto, voc pode apenas arrastar texto em um elemento e apenas a elementos em uma regio editvel de uma pgina. Quando voc arrasta texto entre ou dentro de regies editveis de uma pgina, o comportamento padro executa uma ao de mover. Quando voc arrasta texto para uma regio editvel de uma regio no-editvel ou de fora do aplicativo, o comportamento padro executa uma ao de copiar. Voc pode substituir o comportamento padro manipulando os eventos de arrastar e soltar sozinho. Para cancelar o comportamento padro, voc deve chamar os mtodos preventDefault() dos objetos despachados para os eventos de arrastar e soltar. Voc pode ento inserir dados no destino de soltar e remover dados da origem de arrastar conforme necessrio para executar a ao escolhida. Por padro, o usurio pode selecionar e arrastar qualquer texto e arrastar imagens e links. Voc pode usar a propriedade WebKit CSS, -webkit-user-select, para controlar como qualquer elemento HTML pode ser selecionado. Por exemplo, se voc definir -webkit-user-select como none, o contedo do elemento no podem ser selecionados e, portanto, no podem ser arrastados. Voc tambm pode usar a propriedade CSS -webkit-user-drag para controlar se um elemento como um todo pode ser arrastado. No entanto, o contedo do elemento tratado separadamente. O usurio poderia ainda arrastar uma parte selecionada do texto. Para obter mais informaes, consulte CSS no AIR na pgina 962.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Arrastar e soltar no AIR

599

Eventos de arrastar e soltar em HTML

Adobe AIR 1.0 e posterior Os eventos despachados pelo elemento iniciador do qual uma ao de arrastar se origina so:
Evento dragstart Descrio Despachado quando o usurio inicia o gesto de arrastar. O manipulador desse evento pode impedir a ao de arrastar, se necessrio, chamando o mtodo preventDefault() do objeto de evento. Para controlar se os dados arrastados podem ser copiados, vinculados ou movidos, defina a propriedade effectAllowed. Texto, imagens e links selecionados so colocados na rea de transferncia pelo comportamento padro, mas voc pode definir dados diferentes para o gesto de arrastar usando a propriedade dataTransfer do objeto de evento. Despachado continuamente durante o gesto de arrastar. Despachado quando o usurio libera o boto do mouse para encerrar o gesto de arrastar.

arrastar dragend

Os eventos despachados por um destino de arrastar so:

Evento dragover Descrio Despachado continuamente enquanto o gesto de arrastar permanece dentro dos limites do elemento. O manipulador para esse evento deve definir a propriedade dataTransfer.dropEffect para indicar se a ao de soltar resultar em uma ao de copiar, mover ou vincular se o usurio liberar o mouse. Despachado quando o gesto de soltar entrar nos limites de um elemento. Se voc alterar alguma propriedade de um objeto dataTransfer em um manipulador de eventos dragenter, essas alteraes sero rapidamente substitudas pelo prximo evento dragover. Por outro lado, existe um pequeno atraso entre um evento dragenter e o primeiro dragover que pode fazer com que o cursor pisque se diferentes propriedades forem definidas. Em vrios casos, voc pode usar o mesmo manipulador de eventos para ambos os eventos. dragleave drop Despachado quando o gesto de arrastar deixa os limites do elemento. Despachado quando o usurio solta os dados no elemento. Os dados sendo arrastados podem apenas ser acessados dentro do manipulador desse evento.

dragenter

O objeto de evento despachado em resposta a esses eventos similar a um evento do mouse. Voc pode usar propriedades de evento de mouse como (clientX, clientY) e (screenX, screenY), para determinar a posio do mouse. A propriedade mais importante de um objeto de evento arrastar dataTransfer, que contm os dados que esto sendo arrastados. O objeto dataTransfer em si possui as seguintes propriedades e mtodos:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Arrastar e soltar no AIR

600

Propriedade ou mtodo effectAllowed

Descrio O efeito permitido pela origem da ao de arrastar. Normalmente, o manipulador do evento dragstart define esse valor. Consulte Efeitos de arrastar em HTML na pgina 601. O efeito escolhido pelo destino ou usurio. Se voc define dropEffect em um manipulador de eventos dragover ou dragenter, o AIR atualiza o cursor do mouse para indicar o efeito que ocorre se o usurio libera o mouse. Se a definio de dropEffect no corresponder a um dos efeitos permitidos, nenhuma ao de soltar ser permitida e o cursor unavailable ser exibido. Se no tiver definido dropEffect em resposta a um evento dragover ou dragenter mais recente, o usurio poder escolher dentre os efeitos permitidos com as teclas do modificador do sistema operacional padro. O efeito final relatado pela propriedade dropEffect do objeto despachado para dragend. Se o usurio abandonar a ao de soltar liberando o mouse fora de um destino aceitvel, dropEffect ser definido como none.

dropEffect

tipos

Uma matriz contendo as seqncias de caracteres de tipo MIME para cada formato de dados apresentada no objeto dataTransfer. Obtm os dados no formato especificado pelo parmetro mimeType. O mtodo getData() pode apenas ser chamado em resposta ao evento drop.

getData(mimeType)

setData(mimeType)

Adiciona dados a dataTransfer no formato especificado pelo parmetro mimeType. Voc pode adicionar dados em vrios formatos chamando setData() para cada tipo MIME. Qualquer dado colocado no objeto dataTransfer pelo comportamento de arrastar padro limpo. O mtodo setData() pode apenas ser chamado em resposta ao evento dragstart.

clearData(mimeType) setDragImage(image, offsetX, offsetY)

Limpa qualquer dado no formato especificado pelo parmetro mimeType. Define uma imagem de arrastar personalizada. O mtodo setDragImage() s pode ser chamado em resposta ao evento dragstart e somente quando um elemento inteiro de HTML arrastado ao se definir seu estilo CSS -webkit-user-drag ao element. O parmetro image pode ser um elemento JavaScript ou um objeto Image.

Tipos MIME para arrastar e soltar HTML

Adobe AIR 1.0 e posterior Os tipos MIME a usar com o objeto dataTransfer de um evento arrastar e soltar HTML incluem:
Formato de dados Texto HTML URL Bitmap Lista de arquivos Tipo MIME "text/plain" "text/html" "text/uri-list" "image/x-vnd.adobe.air.bitmap" "application/x-vnd.adobe.air.file-list"

Voc tambm pode usar outras seqncias de caracteres MIME, incluindo as definidas por aplicativo. No entanto, outros aplicativos no podem reconhecer ou usar os dados transferidos. sua responsabilidade adicionar dados ao objeto dataTransfer no formato esperado. Importante: Apenas cdigo em execuo na caixa de proteo do aplicativo pode acessar arquivos soltos. Tentar ler ou definir qualquer propriedade de um objeto File em uma caixa de proteo de no-aplicativo gera um erro de segurana. Consulte Tratamento de arquivos soltos em caixas de proteo HTML de no-aplicativo na pgina 605 para obter mais informaes.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Arrastar e soltar no AIR

601

Efeitos de arrastar em HTML

Adobe AIR 1.0 e posterior O iniciador do gesto de arrastar pode limitar os efeitos de arrastar permitido definindo a propriedade dataTransfer.effectAllowed no manipulador para o evento dragstart. Os seguintes valores de seqncias de caracteres podem ser usados:
Valor de string "none" "copiar" "link" "mover "copyLink" "copyMove" "linkMove" "all" Descrio Nenhuma operao de arrastar permitida. Os dados sero copiados ao destino, deixando o original no lugar. Os dados sero compartilhados com o destino de soltar usando um link de volta ao original. Os dados sero copiados para o destino e removidos do local original. Os dados podem ser copiados ou vinculados. Os dados podem ser copiados ou movidos. Os dados podem ser vinculados ou movidos. Os dados podem ser copiados, movidos ou vinculados. All o efeito padro quando voc impede o comportamento padro.

O destino do gesto de arrastar pode definir a propriedade dataTransfer.dropEffect para indicar a ao tomada se o usurio concluir a ao de soltar. Se o efeito de soltar for uma das aes permitidas, o sistema exibe o cursor apropriado de copiar, mover ou vincular. Caso contrrio, o sistema exibe o cursor unavailable. Se nenhum efeito de soltar for definido pelo destino, o usurio poder escolher dentre as aes permitidas com as teclas do modificador. Defina o valor dropEffect nos manipuladores para os eventos dragover e dragenter:
function doDragStart(event) { event.dataTransfer.setData("text/plain","Text to drag"); event.dataTransfer.effectAllowed = "copyMove"; } function doDragOver(event) { event.dataTransfer.dropEffect = "copy"; } function doDragEnter(event) { event.dataTransfer.dropEffect = "copy"; }

Nota: Embora voc deva sempre definir a propriedade dropEffect no manipulador para dragenter, esteja ciente que o prximo evento dragover redefine a propriedade para seu valor padro. Defina dropEffect em resposta aos dois eventos.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Arrastar e soltar no AIR

602

Arrastar dados para fora de um elemento HTML

Adobe AIR 1.0 e posterior O comportamento padro permite que a maior parte do contedo em uma pgina HTML seja copiada pela ao de arrastar. Voc pode controlar o contedo permitido a ser arrastado usando as propriedades CSS -webkit-userselect e -webkit-user-drag. Substitua o comportamento padro de arrastar para fora no manipulador para o evento dragstart. Chame o mtodo setData() da propriedade dataTransfer do objeto de evento para colocar seus prprios dados no gesto de arrastar. Para indicar que efeitos de arrastar um objeto de origem suporta quando voc no est contando com o comportamento padro, define a propriedade dataTransfer.effectAllowed do objeto de evento despachado para o evento dragstart. Voc pode escolher qualquer combinao de efeitos. Por exemplo, se um elemento de origem suportar os efeitos copy e link, defina a propriedade como "copyLink".

Definio dos dados arrastados

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Adicione os dados para o gesto de arrastar no manipulador para o evento dragstart com a propriedade dataTransfer. Use o mtodo dataTransfer.setData() para colocar dados na rea de transferncia, transmitindo o tipo MIME e os dados a transferir. Por exemplo, se voc tinha um elemento de imagem no seu aplicativo, com a id imageOfGeorge, voc poderia usar o seguinte manipulador de eventos dragstart. Esse exemplo adiciona representaes de uma imagem de George em vrios formatos de dados, que aumenta a probabilidade de que outros aplicativos possam usar os dados arrastados.
function dragStartHandler(event){ event.dataTransfer.effectAllowed = "copy"; var dragImage = document.getElementById("imageOfGeorge"); var dragFile = new air.File(dragImage.src); event.dataTransfer.setData("text/plain","A picture of George"); event.dataTransfer.setData("image/x-vnd.adobe.air.bitmap", dragImage); event.dataTransfer.setData("application/x-vnd.adobe.air.file-list", new Array(dragFile)); }

Nota: Quando voc chama o mtodo setData() de objeto dataTransfer, nenhum dado adicionado pelo comportamento padro de arrastar e soltar.

Arrastar dados para dentro de um elemento HTML

Adobe AIR 1.0 e posterior O comportamento padro apenas permite que texto seja arrastado em regies editveis da pgina. Voc pode especificar que um elemento e seus filhos podem se tornar editveis incluindo o atributo contenteditable na tag de abertura do elemento. Voc tambm pode tornar um documento inteiro editvel definindo a propriedade designMode de objeto de documento como "on".

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Arrastar e soltar no AIR

603

Voc pode suportar um comportamento alternativo de arrastar para dentro em uma pgina manipulando os eventos dragenter, dragover e drop para qualquer elemento que pode aceitar dados arrastados.

Ativao de arrastar para dentro

Adobe AIR 1.0 e posterior Para manipular o gesto de arrastar para dentro, voc deve primeiro cancelar o comportamento padro. Oua os eventos dragenter e dragover em qualquer elemento HTML que deseja usar como destinos de soltar. Nos manipuladores desses eventos, chame o mtodo preventDefault() do objeto de evento despachado. Cancelar o comportamento padro permite que regies no editveis recebam uma ao de soltar.

Obteno de dados soltos

Adobe AIR 1.0 e posterior Voc pode acessar os dados soltos no manipulador para o evento ondrop:
function doDrop(event){ droppedText = event.dataTransfer.getData("text/plain"); }

Use o mtodo dataTransfer.getData() para ler dados na rea de transferncia, transmitindo o tipo MIME do formato de dados a ler. Voc pode descobrir que formatos de dados esto disponveis usando a propriedade types do objeto dataTransfer. A matriz types contm a seqncia de caracteres de tipo MIME de cada formato disponvel. Quando voc cancela o comportamento padro nos eventos dragenter ou dragover, voc responsvel por inserir qualquer dado solto em seu prprio lugar no documento. Nenhuma API existe para converter uma posio do mouse em um ponto de insero dentro de um elemento. Essa limitao pode dificultar a implementao de gestos de arrastar de tipo de insero.

Exemplo: Substituio do comportamento padro de arrastar para dentro HTML

Adobe AIR 1.0 e posterior Esse exemplo implementa um destino de soltar que exibe uma tabela mostrando cada formato de dados disponvel no item solto. O comportamento padro usado para permitir que texto, links e imagens sejam arrastados no aplicativo. O exemplo substitui o comportamento padro de arrastar para dentro para o elemento div que serve como o destino de soltar. A etapa principal para habilitar contedo no-editvel para aceitar um gesto de arrastar para dentro chamar o mtodo preventDefault() do objeto de evento despachado para os eventos dragenter e dragover. Em resposta a um evento drop, o manipulador converte os dados transferidos em um elemento de linha HTML e insere a linha em uma tabela para exibio.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Arrastar e soltar no AIR

604

<html> <head> <title>Drag-and-drop</title> <script language="javascript" type="text/javascript" src="AIRAliases.js"></script> <script language="javascript"> function init(){ var target = document.getElementById('target'); target.addEventListener("dragenter", dragEnterOverHandler); target.addEventListener("dragover", dragEnterOverHandler); target.addEventListener("drop", dropHandler); var source = document.getElementById('source'); source.addEventListener("dragstart", dragStartHandler); source.addEventListener("dragend", dragEndHandler); emptyRow = document.getElementById("emptyTargetRow"); } function dragStartHandler(event){ event.dataTransfer.effectAllowed = "copy"; } function dragEndHandler(event){ air.trace(event.type + ": " + event.dataTransfer.dropEffect); } function dragEnterOverHandler(event){ event.preventDefault(); } var emptyRow; function dropHandler(event){ for(var prop in event){ air.trace(prop + " = " + event[prop]); } var row = document.createElement('tr'); row.innerHTML = "<td>" + event.dataTransfer.getData("text/plain") + "</td>" + "<td>" + event.dataTransfer.getData("text/html") + "</td>" + "<td>" + event.dataTransfer.getData("text/uri-list") + "</td>" + "<td>" + event.dataTransfer.getData("application/x-vnd.adobe.air.file-list") + "</td>"; var imageCell = document.createElement('td'); if((event.dataTransfer.types.toString()).search("image/x-vnd.adobe.air.bitmap") > 1){ imageCell.appendChild(event.dataTransfer.getData("image/xvnd.adobe.air.bitmap")); } row.appendChild(imageCell); var parent = emptyRow.parentNode; parent.insertBefore(row, emptyRow); } </script> </head> <body onLoad="init()" style="padding:5px"> <div> <h1>Source</h1>

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Arrastar e soltar no AIR

605

<p>Items to drag:</p> <ul id="source"> <li>Plain text.</li> <li>HTML <b>formatted</b> text.</li> <li>A <a href="http://www.adobe.com">URL.</a></li> <li><img src="icons/AIRApp_16.png" alt="An image"/></li> <li style="-webkit-user-drag:none;"> Uses "-webkit-user-drag:none" style. </li> <li style="-webkit-user-select:none;"> Uses "-webkit-user-select:none" style. </li> </ul> </div> <div id="target" style="border-style:dashed;"> <h1 >Target</h1> <p>Drag items from the source list (or elsewhere).</p> <table id="displayTable" border="1"> <tr><th>Plain text</th><th>Html text</th><th>URL</th><th>File list</th><th>Bitmap Data</th></tr> <tr id="emptyTargetRow"><td>&nbsp;</td><td>&nbsp;</td><td>&nbsp;</td><td>&nbsp;</td><td>&nbsp;</ td></tr> </table> </div> </div> </body> </html>

Tratamento de arquivos soltos em caixas de proteo HTML de no-aplicativo

Adobe AIR 1.0 e posterior O contedo de no-aplicativo no pode acessar os objetos File resultantes quando arquivos so arrastados em um aplicativo AIR. Nem possvel transmitir um desses objetos File para contedo de aplicativo por uma ponte de caixa de proteo. (As propriedades do objeto devem ser acessadas durante a serializao.) No entanto, voc pode ainda soltar arquivos no seu aplicativo ouvindo os eventos nativeDragDrop do AIR no objeto HTMLLoader. Normalmente, se um usurio solta um arquivo em um quadro que hospeda contedo de no-aplicativo, o evento de soltar no propaga do filho ao pai. No entanto, como os eventos despachados pelo HTMLLoader (que o continer para todo o contedo HTML em um aplicativo AIR) no so parte do fluxo de evento HTML, voc pode ainda receber o evento de soltar em contedo de aplicativo. Para receber o evento para um arquivo solto, o documento pai adiciona um ouvinte de evento ao objeto HTMLLoader usando a referncia fornecida por window.htmlLoader:
window.htmlLoader.addEventListener("nativeDragDrop",function(event){ var filelist = event.clipboard.getData(air.ClipboardFormats.FILE_LIST_FORMAT); air.trace(filelist[0].url); });

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Arrastar e soltar no AIR

606

O exemplo a seguir usa um documento pai que carrega uma pgina filha em uma caixa de proteo remota (http://localhost/). O pai ouve o evento nativeDragDrop no objeto HTMLLoader e marca a URL do arquivo.
<html> <head> <title>Drag-and-drop in a remote sandbox</title> <script language="javascript" type="text/javascript" src="AIRAliases.js"></script> <script language="javascript"> window.htmlLoader.addEventListener("nativeDragDrop",function(event){ var filelist = event.clipboard.getData(air.ClipboardFormats.FILE_LIST_FORMAT); air.trace(filelist[0].url); }); </script> </head> <body> <iframe src="child.html" sandboxRoot="http://localhost/" documentRoot="app:/" frameBorder="0" width="100%" height="100%"> </iframe> </body> </html>

O documento filho deve apresentar um destino de soltar vlido chamando o mtodo preventDefault() do objeto Event nos manipuladores de eventos dragenter e dragover. Do contrrio, o evento de soltar pode nunca ocorrer.
<html> <head> <title>Drag and drop target</title> <script language="javascript" type="text/javascript"> function preventDefault(event){ event.preventDefault(); } </script> </head> <body ondragenter="preventDefault(event)" ondragover="preventDefault(event)"> <div> <h1>Drop Files Here</h1> </div> </body> </html>

Soltando promessas de arquivo

Adobe AIR 2 e posterior Uma promessa de arquivo um formato de rea de transferncia de arrastar e soltar que permite que um usurio arraste um arquivo que ainda no existe para fora de um aplicativo AIR. Por exemplo, usando as promessas de arquivo, seu aplicativo poderia permitir que um usurio arraste um cone de proxy para uma pasta do computador. O cone de proxy representa um arquivo ou alguns dados conhecidos que esto disponveis em um URL. Depois que o usurio solta o cone, o tempo de execuo baixa os dados e escreve o arquivo no local em que foi solto.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Arrastar e soltar no AIR

607

Voc pode usar a classe URLFilePromise em um aplicativo AIR para arrastar e soltar arquivos acessveis em um URL. A implementao do URLFilePromise fornecido na biblioteca do aircore como parte do SDK do AIR 2. Utilize o arquivo aircore.swc ou o aircore.swf encontrados no diretrio frameworks/libs/air. Alternativamente, voc pode implementar sua prpria lgica de promessa de arquivo utilizando a interface IFilePromise (que definida no pacote flash.desktop do tempo de execuo). As promessas de arquivo so semelhantes em conceito renderizao adiada usando uma funo de tratamento de dados na rea de transferncia. Use as promessas de arquivo em vez da renderizao adiada ao arrastar e soltar os arquivos. A tcnica de renderizao adiada pode levar a pausas indesejveis no gesto de arrastar medida que os dados so gerados ou baixados. Use a renderizao adiada para as operaes de copiar e colar (para as quais as promessas do arquivo no recebem suporte). Limitaes ao usar as promessas de arquivo As promessas de arquivo tm as seguintes limitaes em comparao com outros formatos de dados que voc pode colocar em uma rea de transferncia de arrastar e soltar:

As promessas de arquivo s podem ser arrastadas para fora de um aplicativo AIR, no podendo ser soltas em um
arquivo AIR.

As promessas de arquivo no recebem suporte em todos os sistemas operacionais. Use a propriedade

Clipboard.supportsFilePromise para testar se as promessas de arquivo recebem suporte no sistema de host.

Nos sistemas que no oferecem suporte s promessas de arquivo, fornea um mecanismo alternativo para baixar ou gerar os dados do arquivo.

As promessas de arquivo no podem ser usadas com a rea de transferncia de copiar e colar
(Clipboard.generalClipboard).

Mais tpicos da Ajuda

flash.desktop.IFilePromise air.desktop.URLFilePromise

Soltando arquivos remotos

Adobe AIR 2 e posterior Use a classe URLFilePromise para criar objetos de promessa de arquivo que representam arquivos ou dados disponveis em um URL. Acrescente um ou mais objetos de promessa de arquivo rea de transferncia usando o formato FILE_PROMISE_LIST da rea. No exemplo a seguir, um arquivo nico, disponvel em http://www.example.com/foo.txt, baixado e salvo no local em que ser solto como bar.txt. (Os nomes do arquivo remoto e local no precisam coincidir.)
if( Clipboard.supportsFilePromise ) { var filePromise:URLFilePromise = new URLFilePromise(); filePromise.request = new URLRequest("http://example.com/foo.txt"); filePromise.relativePath = "bar.txt"; var fileList:Array = new Array( filePromise ); var clipboard:Clipboard = new Clipboard(); clipboard.setData( ClipboardFormats.FILE_PROMISE_LIST_FORMAT, fileList ); NativeDragManager.doDrag( dragSource, clipboard ); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Arrastar e soltar no AIR

608

Voc pode permitir que o usurio arraste mais de um arquivo por vez acrescentando mais objetos de promessa de arquivo matriz atribuda rea de transferncia. Tambm possvel especificar os subdiretrios na propriedade relativePath, de forma que alguns ou todos os arquivos includos na operao sejam colocados em uma subpasta relativa ao local em que ele ser solto. O exemplo a seguir ilustra como iniciar uma operao de soltar que inclui mltiplas promessas de arquivo. Neste exemplo, uma pgina html, article.html, colocada na rea de transferncia como promessa de arquivo, juntamente com seus dois arquivos de imagem vinculados. As imagens so copiadas para uma subpasta images, de forma que os links relativos sejam mantidos.
if( Clipboard.supportsFilePromise ) { //Create the promise objects var filePromise:URLFilePromise = new URLFilePromise(); filePromise.request = new URLRequest("http://example.com/article.html"); filePromise.relativePath = "article.html"; var image1Promise:URLFilePromise = new URLFilePromise(); image1Promise.request = new URLRequest("http://example.com/images/img_1.jpg"); image1Promise.relativePath = "images/img_1.html"; var image2Promise:URLFilePromise = new URLFilePromise(); image2Promise.request = new URLRequest("http://example.com/images/img_2.jpg"); image2Promise.relativePath = "images/img_2.jpg";

//Put the promise objects onto the clipboard inside an array var fileList:Array = new Array( filePromise, image1Promise, image2Promise ); var clipboard:Clipboard = new Clipboard(); clipboard.setData( ClipboardFormats.FILE_PROMISE_LIST_FORMAT, fileList ); //Start the drag operation NativeDragManager.doDrag( dragSource, clipboard ); }

Implementao da interface IFilePromise

Adobe AIR 2 e posterior Para fornecer promessas de arquivo para os recursos que no podem ser acessados com um objeto URLFilePromise, voc pode implementar a interface IFilePromise em uma classe personalizada. A interface IFilePromise define os mtodos e propriedades usados pelo tempo de execuo do AIR para acessar os dados a serem gravados em um arquivo depois que a promessa solta. Uma implementao IFilePromise passa outro objeto ao tempo de execuo do AIR que fornece os dados para a promessa de arquivo. Esse objeto deve implementar a interface IDataInput, que o tempo de execuo do AIR usa para ler os dados. Por exemplo, a classe URLFilePromise, que implementa IFilePromise, usa um objeto URLStream como fornecedor dos dados. O AIR pode ler os dados de forma sncrona ou assncrona. A implementao IFilePromise informa qual modo de acesso suportado ao devolver o valor apropriado na propriedade isAsync. Se for fornecido acesso aos dados assncronos, o objeto do fornecedor de dados deve implementar a interface IEventDispatcher e despachar os eventos necessrios, como open, progress e complete. Voc pode usar uma classe personalizada ou uma das classes incorporadas seguintes, como fornecedor de dados para uma promessa de dados:

ByteArray (sncrono)

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Arrastar e soltar no AIR

609

FileStream (sncrono ou assncrono) Socket (assncrono) URLStream (assncrono)

Para implementar a interface IFilePromise, voc deve fornecer o cdigo para as funes e propriedades seguintes:

open():IDataInput Devolve o objeto do fornecedor de dados dos quais os dados para o arquivo prometido so lidos. O objeto deve implementar a interface IDataInput. Se os dados so fornecidos de forma assncrona, o objeto tambm deve implementar a interface IEventDispatcher e despachar os eventos necessrios (consulte Uso do fornecedor de dados assncrono em uma promessa de arquivo na pgina 611). get relativePath():String Fornece o caminho, incluindo nome de arquivo, para o arquivo criado. O caminho resolvido em relao ao local de soltar escolhido pelo usurio na operao de arrastar e soltar. Para ter certeza de que o caminho usa o caractere separador adequado para o sistema operacional de host, use a constante File.separator ao especificar os caminhos que contm diretrios. Voc pode adicionar uma funo setter ou usar um parmetro constructor para permitir que o caminho seja definido no tempo de execuo. get isAsync():Boolean Informa o tempo de execuo do AIR se o objeto do fornecedor de dados fornece seus dados de forma sncrona ou assncrona. close():void Chamado pelo tempo de execuo quando os dados so inteiramente lidos (ou um erro impede novas leituras). Voc pode usar essa funo para os recursos de limpeza. reportError( e:ErrorEvent ):void Chamando pelo tempo de execuo quando ocorre um erro ao ler os

dados. Todos os mtodos IFilePromise so chamados pelo tempo de execuo durante uma operao de arrastar e soltar envolvendo a promessa de arquivo. Em geral, sua lgica de aplicativo no deve chamar nenhum desses mtodos diretamente.

Uso do fornecedor de dados sncrono em uma promessa de arquivo

Adobe AIR 2 e posterior A forma mais simples de implementar a interface IFilePromise usar um objeto de fornecedor de dados sncrono, como ByteArray ou um FileStream sncrono. No exemplo a seguir, criado um objeto ByteArray, preenchido com dados e retornado quando se chama o mtodo open().

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Arrastar e soltar no AIR

610

package { import import import import

flash.desktop.IFilePromise; flash.events.ErrorEvent; flash.utils.ByteArray; flash.utils.IDataInput;

public class SynchronousFilePromise implements IFilePromise { private const fileSize:int = 5000; //size of file data private var filePath:String = "SynchronousFile.txt"; public function get relativePath():String { return filePath; } public function get isAsync():Boolean { return false; } public function open():IDataInput { var fileContents:ByteArray = new ByteArray(); //Create some arbitrary data for the file for( var i:int = 0; i < fileSize; i++ ) { fileContents.writeUTFBytes( 'S' ); } //Important: the ByteArray is read from the current position fileContents.position = 0; return fileContents; } public function close():void { //Nothing needs to be closed in this case. } public function reportError(e:ErrorEvent):void { trace("Something went wrong: " + e.errorID + " - " + e.type + ", " + e.text ); } } }

Na prtica, as promessas de arquivo sncronas tm utilidade limitada. Se a quantidade de dados for pequena, voc poderia facilmente criar um arquivo em um diretrio temporrio e acrescentar uma matriz normal da lista de arquivos rea de transferncia de arrastar e soltar. Por outro lado, se a quantidade de dados for grande ou for caro gerar os dados de forma computacional, necessrio um processo sncrono longo. Os processos sncronos longos podem bloquear as atualizaes de UI por um tempo notvel e fazer com que seu aplicativo parea no responder. Para evitar este problema, voc pode criar um fornecedor de dados assncronos orientado por um cronmetro.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Arrastar e soltar no AIR

611

Uso do fornecedor de dados assncrono em uma promessa de arquivo

Adobe AIR 2 e posterior Ao usar um objeto de fornecedor de dados assncrono, a propriedadeisAsync do IFilePromise deve ser true e o objeto devolvido pelo mtodo open() deve implementar a interface IEventDispatcher. O tempo de execuo ouve os vrios eventos alternativos de forma que se possam usar objetos incorporados diferentes como fornecedor de dados. Por exemplo, os eventos progress so despachados pelos objetos FileStream e URLStream, ao passo que os eventos socketData so despachados pelos objetos Socket. O tempo de execuo ouve os eventos apropriados de todos esses objetos. Os eventos a seguir orientam o processo de leitura de dados do objeto do fornecedor de dados:

Event.OPEN Informa ao tempo de execuo que a fonte de dados est pronta. ProgressEvent.PROGRESS Informa ao tempo de execuo que os dados esto disponveis. O tempo de execuo
vai ler a quantidade de dados disponveis do objeto do fornecedor de dados.

ProgressEvent.SOCKET_DATA Informa ao tempo de execuo que os dados esto disponveis. O evento

socketData despachado pelos objetos baseados em soquete. Para os outros tipos de objeto, despache um evento progress. (O tempo de execuo ouve os dois eventos para detectar quando os dados podem ser lidos.)

Event.COMPLETE Informa ao tempo de execuo que os dados foram todos lidos. Event.CLOSE Informa ao tempo de execuo que os dados foram todos lidos. (O tempo de execuo ouve close
e complete para essa finalidade.)

IOErrorEvent.IOERROR Informa ao tempo de execuo que ocorreu um erro ao ler os dados. O tempo de
execuo aborta a criao do arquivo e chama o mtodo close() do IFilePromise.

SecurityErrorEvent.SECURITY_ERROR Informa ao tempo de execuo que ocorreu um erro de segurana. O

tempo de execuo aborta a criao do arquivo e chama o mtodo close() do IFilePromise.

HTTPStatusEvent.HTTP_STATUS Usado, junto com httpResponseStatus, pelo tempo de execuo para

garantir que os dados disponveis representem o contedo desejado, em vez de uma mensagem de erro (como uma pgina 404). Os objetos baseados no protocolo HTTP devem despachar esse evento.

HTTPStatusEvent.HTTP_RESPONSE_STATUS Usado, junto com httpStatus, pelo tempo de execua para

garntir que os dados disponveis representam o contedo desejado. Os objetos baseados no protocolo HTTP devem despachar esse evento. O fornecedor de dados deve despachar esses eventos na sequncia a seguir:
1 evento open 2 Eventos progress ou socketData 3 Evento complete ou close

Nota: Os objetos incorporados, FileStream, Socket e URLStream, despacham os eventos apropriados automaticamente. O exemplo a seguir cria uma promessa de arquivo usando um fornecedor de dados personalizado e assncrono. A classe do fornecedor de dados extende ByteArray (para o suporte do IDataInput) e implementa a interface IEventDispatcher. No evento de cada cronmetro, o objeto gera um pouco de dados e despacha um evento progress para informar ao tempo de execuo que os dados esto disponveis. Quando forem produzidos dados suficientes, o objeto despacha um evento completo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Arrastar e soltar no AIR

612

package { import flash.events.Event; import flash.events.EventDispatcher; import flash.events.IEventDispatcher; import flash.events.ProgressEvent; import flash.events.TimerEvent; import flash.utils.ByteArray; import flash.utils.Timer; [Event(name="open", type="flash.events.Event.OPEN")] [Event(name="complete", type="flash.events.Event.COMPLETE")] [Event(name="progress", type="flash.events.ProgressEvent")] [Event(name="ioError", type="flash.events.IOErrorEvent")] [Event(name="securityError", type="flash.events.SecurityErrorEvent")] public class AsyncDataProvider extends ByteArray implements IEventDispatcher { private var dispatcher:EventDispatcher = new EventDispatcher(); public var fileSize:int = 0; //The number of characters in the file private const chunkSize:int = 1000; //Amount of data written per event private var dispatchDataTimer:Timer = new Timer( 100 ); private var opened:Boolean = false; public function AsyncDataProvider() { super(); dispatchDataTimer.addEventListener( TimerEvent.TIMER, generateData ); } public function begin():void{ dispatchDataTimer.start(); } public function end():void { dispatchDataTimer.stop(); } private function generateData( event:Event ):void { if( !opened ) { var open:Event = new Event( Event.OPEN ); dispatchEvent( open ); opened = true; } else if( position + chunkSize < fileSize ) { for( var i:int = 0; i <= chunkSize; i++ ) { writeUTFBytes( 'A' ); } //Set position back to the start of the new data this.position -= chunkSize; var progress:ProgressEvent = new ProgressEvent( ProgressEvent.PROGRESS, false, false, bytesAvailable, bytesAvailable + chunkSize); dispatchEvent( progress )

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Arrastar e soltar no AIR

613

} else { var complete:Event = new Event( Event.COMPLETE ); dispatchEvent( complete ); } } //IEventDispatcher implementation public function addEventListener(type:String, listener:Function, useCapture:Boolean=false, priority:int=0, useWeakReference:Boolean=false):void { dispatcher.addEventListener( type, listener, useCapture, priority, useWeakReference ); } public function removeEventListener(type:String, listener:Function, useCapture:Boolean=false):void { dispatcher.removeEventListener( type, listener, useCapture ); } public function dispatchEvent(event:Event):Boolean { return dispatcher.dispatchEvent( event ); } public function hasEventListener(type:String):Boolean { return dispatcher.hasEventListener( type ); } public function willTrigger(type:String):Boolean { return dispatcher.willTrigger( type ); } } }

Nota: Como a classe AsyncDataProvider no exemplo estende ByteArray, ela no pode estender tambm o EventDispatcher. Para implementar a interface IEventDispatcher, a clase usa um objeto EventDispatcher interno e encaminha as chamadas do mtodo IEventDispatcher para aquele objeto interno. Voc tambm poderia estender o EventDispatcher e implementar IDataInput (ou implementar as duas interfaces). A implementao assncrona de IFilePromise quase idntica implementao sncrona. As principais diferenas so que isAsync retorna true e que o mtodo open() retorna um objeto de dados assncrono:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Arrastar e soltar no AIR

614

package { import import import import

flash.desktop.IFilePromise; flash.events.ErrorEvent; flash.events.EventDispatcher; flash.utils.IDataInput;

public class AsynchronousFilePromise extends EventDispatcher implements IFilePromise { private var fileGenerator:AsyncDataProvider; private const fileSize:int = 5000; //size of file data private var filePath:String = "AsynchronousFile.txt"; public function get relativePath():String { return filePath; } public function get isAsync():Boolean { return true; } public function open():IDataInput { fileGenerator = new AsyncDataProvider(); fileGenerator.fileSize = fileSize; fileGenerator.begin(); return fileGenerator; } public function close():void { fileGenerator.end(); } public function reportError(e:ErrorEvent):void { trace("Something went wrong: " + e.errorID + " - " + e.type + ", " + e.text ); } } }

ltima atualizao em 29/3/2011

615

Captulo 34: Trabalho com menus

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Use as classes na API de menu de contexto para modificar o menu de contexto em aplicativos do Flex e Flash Player com base na Web. Use as classes na API de menu nativo para definir aplicativo, janela, contexto e menus pop-up no Adobe AIR.

Noes bsicas do menu

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para ver uma rpida explicao e exemplos de cdigo da criao de menus originais em aplicativos AIR, consulte os seguintes artigos de incio rpido no Adobe Developer Connection:

Adicionando menus nativos em aplicativos AIR (Flex) Adicionando menus nativos em aplicativos AIR (Flash)
As classes de menu nativo permitem acessar os recursos do menu nativo do sistema operacional em que o aplicativo est sendo executado. Objetos NativeMenu podem ser usados em menus de aplicativo (disponveis no Mac OS X), menus de janela (disponveis no Windows e no Linux), menus de contexto e menus pop-up. Fora do AIR, voc pode usar as classes de menu de contexto para modificar o menu de contexto que o Flash Player automaticamente exibe quando um usurio clica com o boto direito ou clica com a tecla cmd em um objeto em um aplicativo. (O menu de contexto automtico no exibido para os aplicativos AIR.)

Classes de menu
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior As classes de menu incluem:
Pacote flash.display Classes

NativeMenu NativeMenuItem ContextMenu ContextMenuItem Event ContextMenuEvent

flash.ui

flash.events

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com menus

616

Variedades de menu
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O AIR oferece suporte aos seguintes tipos de menus:
Menus de contexto Os menus de contexto so exibidos em resposta ao clique com o boto direito do mouse ou ao

clique com a tecla Command pressionada em um objeto interativo no contedo SWF ou um elemento de documento no contedo HTML. No tempo de execuo do Flash Player, um menu de contexto automaticamente exibido. Voc pode usar as classes ContextMenu e ContextMenuItem para adicionar seus prprios comandos ao menu. Tambm possvel remover alguns comandos incorporados, mas no todos. No tempo de execuo do AIR, voc pode criar um menu de contexto usando a classe NativeMenu ou ContextMenu. No contedo HTML do AIR, voc pode usar as APIs de kit da Web HTML e JavaScript para adicionar menus de contexto a elementos HTML.
Menus de aplicativo (somente AIR) O menu de aplicativo um menu global aplicvel ao aplicativo inteiro. H suporte

para menus de aplicativo no Mac OS X, mas no no Windows nem no Linux. No Mac OS X , o sistema operacional cria automaticamente o menu de aplicativo. Voc pode usar a API de menu AIR para adicionar itens e submenus aos menus padro. Voc pode adicionar ouvintes para tratar os comandos de menu existentes. Ou voc pode remover itens existentes.
Menus de janela (somente AIR) O menu de janela est associado a uma nica janela e exibido abaixo da barra de ttulo. Os menus podem ser adicionados a uma janela, criando um objeto NativeMenu e atribuindo-o propriedade menu do objeto NativeWindow. H suporte para menus de janela nos sistemas operacionais Windows e Linux, mas no no Mac OS X. Menus de janela nativos s podem ser usados em janelas com o cromo do sistema. Menus do cone de bandeja de encaixe e sistema (somente AIR) Esses menus de cone so semelhantes aos menus de

contexto e so atribudos a um cone de aplicativo no encaixe do Mac OS X ou nas reas de notificao do Windows ou do Linux, na barra de tarefas. Menus de cone da bandeja do sistema e de encaixe usam a classe NativeMenu. No Mac OS X, os itens no menu so adicionados acima dos itens padro do sistema operacional. No h menu padro no Windows nem no Linux.
Menus pop-up (somente AIR) O menu pop-up AIR semelhante ao menu de contexto, mas no est necessariamente

associado a um objeto de aplicativo ou componente especfico. Os menus pop-up podem ser exibidos em qualquer lugar na janela, chamando o mtodo display() de qualquer objeto NativeMenu.
Menus personalizados Menus nativos so inteiramente desenhados pelo sistema operacional e, como tal, esto

presentes fora dos modelos de processamento Flash e HTML. Em vez de usar menus nativos, voc sempre pode criar seus prprios menus no-nativos personalizados usando MXML, ActionScript ou JavaScript (no AIR). Esses menus devem ser inteiramente renderizados no contedo do aplicativo.
menus do Flex A estrutura do Adobe Flex oferece um conjunto de componentes de menu do Flex. Os menus do Flex

so desenhados pelo tempo de execuo, e no pelo sistema operacional, e no so menus nativos. O componente de menu do Flex pode ser usado em janelas do Flex que no tm o cromo do sistema. Outra vantagem de usar o componente do menu Flex que voc pode especificar de forma clara os menus no formato MXML. Se estiver usando a estrutura do Flex, use as classes de menu do Flex em menus de janela, em vez das classes nativas. Menus padro (apenas AIR) Os menus padro a seguir so fornecidos pelo sistema operacional ou uma classe incorporada do AIR:

Menu de aplicativo no Mac OS X Menu de cone de encaixe no Mac OS X

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com menus

617

Menu de contexto de textos e imagens selecionados em contedo HTML Menu de contexto de texto selecionado no objeto TextField (ou em um objeto que estende o TextField)

Sobre menus de contexto

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior No contedo SWF, qualquer objeto herdado de InteractiveObject pode ser determinado um menu de contexto atribuindo um objeto de menu respectiva propriedade contextMenu. Vrios comandos so includos por padro, como Avanar, Voltar, Imprimir, Qualidade e Zoom. No tempo de execuo do AIR, o objeto de menu atribudo ao contextMenu pode ser do tipo NativeMenu ou do tipo ContextMenu. No tempo de execuo do Flash Player, apenas a classe ContextMenu est disponvel. Voc pode ouvir eventos do menu nativo ou de menus contextuais ao usar as classes ContextMenu e ContextMenuItem; as duas so despachadas. Um benefcio fornecido pelas propriedades do objeto ContextMenuEvent que contextMenuOwner identifica o objeto ao qual o menu est associado e mouseTarget identifica o objeto que foi clicado para abrir o menu. Essas informaes no esto disponveis do objeto NativeMenuEvent. O exemplo a seguir cria um Sprite e adiciona um menu de contexto de edio simples:
var sprite:Sprite = new Sprite(); sprite.contextMenu = createContextMenu() private function createContextMenu():ContextMenu{ var editContextMenu:ContextMenu = new ContextMenu(); var cutItem:ContextMenuItem = new ContextMenuItem("Cut") cutItem.addEventListener(ContextMenuEvent.MENU_ITEM_SELECT, doCutCommand); editContextMenu.customItems.push(cutItem); var copyItem:ContextMenuItem = new ContextMenuItem("Copy") copyItem.addEventListener(ContextMenuEvent.MENU_ITEM_SELECT, doCopyCommand); editContextMenu.customItems.push(copyItem); var pasteItem:ContextMenuItem = new ContextMenuItem("Paste") pasteItem.addEventListener(ContextMenuEvent.MENU_ITEM_SELECT, doPasteCommand); editContextMenu.customItems.push(pasteItem); return editContextMenu } private function doCutCommand(event:ContextMenuEvent):void{trace("cut");} private function doCopyCommand(event:ContextMenuEvent):void{trace("copy");} private function doPasteCommand(event:ContextMenuEvent):void{trace("paste");}

Nota: Ao contrrio do contedo SWF exibido em um ambiente de navegador, os menus de contexto no AIR no tm nenhum comando incorporado. Personalizao de um menu de contexto do Flash Player Em um navegador ou projetor, os menus de contexto no contedo SWF sempre tm itens incorporados. Voc pode remover todos esses comandos padro do menu, exceto Configuraes e Sobre. Configurar a propriedade showDefaultContextMenu do palco como false remove esses comandos do menu de contexto.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com menus

618

Para criar um menu de contexto personalizado para um objeto de exibio especfico, crie uma nova ocorrncia da classe ContextMenu, chame o mtodo hideBuiltInItems() e atribua essa ocorrncia propriedade contextMenu dessa instncia DisplayObject. O exemplo a seguir fornece um quadrado desenhado dinamicamente com um comando de menu de contexto para alter-lo para uma cor aleatria:
var square:Sprite = new Sprite(); square.graphics.beginFill(0x000000); square.graphics.drawRect(0,0,100,100); square.graphics.endFill(); square.x = square.y = 10; addChild(square); var menuItem:ContextMenuItem = new ContextMenuItem("Change Color"); menuItem.addEventListener(ContextMenuEvent.MENU_ITEM_SELECT,changeColor); var customContextMenu:ContextMenu = new ContextMenu(); customContextMenu.hideBuiltInItems(); customContextMenu.customItems.push(menuItem); square.contextMenu = customContextMenu; function changeColor(event:ContextMenuEvent):void { square.transform.colorTransform = getRandomColor(); } function getRandomColor():ColorTransform { return new ColorTransform(Math.random(), Math.random(), Math.random(),1,(Math.random() * 512) - 255, (Math.random() * 512) -255, (Math.random() * 512) - 255, 0); }

Estrutura do menu nativo (AIR)

Adobe AIR 1.0 e posterior Os menus nativos so de natureza hierrquica. Os objetos NativeMenu contm objetos-filho NativeMenuItem. Os objetos NativeMenuItem que representam submenus, por sua vez, podem conter objetos NativeMenu. O objeto de menu de nvel superior ou raiz na estrutura representa a barra de menu de menus de aplicativo e janela. (Menus de contexto, cone e pop-up no tm uma barra de menu).

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com menus

619

O diagrama a seguir ilustra a estrutura de um menu tpico. O menu raiz representa a barra de menu e contm dois itens de menu que fazem referncia ao submenu File e ao submenu Edit. O submenu Arquivo nessa estrutura contm dois itens de comando e um item que faz referncia ao submenu Open Recent Menu, que contm, ele mesmo, trs itens. O submenu Edit contm trs comandos e um separador.
NativeMenu Menu de raiz NativeMenuItem NativeMenu Arquivo Menu Arquivo Novo Salvar Abrir recente Menu Abrir recente GreatGatsby.pdf WarAndPeace.pdf Iliad.pdf

NativeMenuItem NativeMenuItem NativeMenuItem

NativeMenu

NativeMenuItem NativeMenuItem NativeMenuItem NativeMenuItem NativeMenu Editar Menu Editar Copiar Colar Separador Preferncias

NativeMenuItem NativeMenuItem NativeMenuItem NativeMenuItem

Definir um submenu requer um objeto NativeMenu e um objeto NativeMenuItem. O objeto NativeMenuItem define o rtulo exibido no menu pai e permite ao usurio abrir o submenu. O objeto NativeMenu funciona como um recipiente de itens no submenu. O objeto NativeMenuItem se refere ao objeto NativeMenu pela propriedade submenu NativeMenuItem. Para exibir um exemplo de cdigo que cria esse menu, consulte Exemplo de menu nativo: menu de janela e de aplicativo (AIR) na pgina 627.

Eventos menu
Adobe AIR 1.0 e posterior Os objetos NativeMenu e NativeMenuItem despacham os eventos preparing, displaying e select: Preparing: sempre que o objeto est prestes a comear uma interao com o usurio, o menu e seus itens de menu despacham um evento preparing para qualquer ouvinte registrado. A interao inclui abrir o menu ou selecionar um item com um atalho no teclado.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com menus

620

Nota: O evento preparing fica disponvel somente no Adobe AIR 2.6 e posteriores.
Displaying: Imediatamente antes de o menu ser exibido, o menu e os respectivos itens de menu despacham o evento
displaying para qualquer ouvinte registrado.

Os eventos preparing e displaying do a oportunidade de atualizar o contedo do menu ou a aparncia do item antes de eles serem mostrados ao usurio. Por exemplo, no ouvinte do evento displaying do menu Abrir recentes, voc pode alterar os itens de menu para que reflitam a lista atual de documentos exibidos recentemente. Se voc remover o item de menu cujo atalho no teclado acionou o evento preparing, a interao com o menu efetivamente cancelada e o evento select no despachado. As propriedades target e currentTarget do evento so ambas um objeto em que o ouvinte est registrado: seja o prprio menu ou um de seus itens. O evento preparing despachado antes do evento displaying. Geralmente, voc ouve um dos dois eventos, mas no ambos.
Select: Quando um item de comando escolhido pelo usurio, o item despacha um evento select para qualquer ouvinte registrado. Itens de submenu e separadores no podem ser selecionados, portanto, nunca despacham um evento select.

O evento select surge em bolha de um item de menu para o menu que o contm, em cima do menu raiz. Voc pode ouvir eventos select diretamente em um item e pode ouvir mais acima na estrutura de menu. Quando voc ouvir o evento select em um menu, poder identificar o item selecionado usando a propriedade target do evento. Conforme o evento surge em bolha pela hierarquia de menu, a propriedade currentTarget do objeto event identifica o objeto de menu atual. Nota: Os objetos ContextMenu e ContextMenuItem despacham eventos menuItemSelect e menuSelect, bem como eventos select, preparing e displaying.

Equivalentes de chave para os comandos do menu nativo (AIR)

Adobe AIR 1.0 e posterior Voc pode atribuir um equivalente de tecla (s vezes chamado de acelerador) em um comando de menu. O item do menu despacha o evento select para qualquer ouvinte registrado quando a tecla ou combinao de teclas pressionada. O menu que contm o item deve ser parte do menu do aplicativo ou a janela ativa do comando que deve ser chamado. Os equivalentes de tecla tm duas partes, uma seqncia representando a tecla primria e uma matriz de teclas do modificador, que tambm devem ser pressionadas. Para atribuir a tecla primria, defina a propriedade keyEquivalent do item de menu para a seqncia de caractere nico dessa tecla. Se voc usar uma letra maiscula, a tecla Shift adicionada matriz do modificador automaticamente. No Mac OS X, o modificador padro a tecla Command (Keyboard.COMMAND). No Windows e no Linux, a tecla Control (Keyboard.CONTROL). Essas teclas padro so adicionadas automaticamente matriz do modificador. Para atribuir teclas do modificador diferentes, atribua uma nova matriz contendo os cdigos de tecla desejados propriedade keyEquivalentModifiers. A matriz padro sobrescrita. Se voc usar os modificadores padro ou atribuir a sua prpria matriz de modificador, a tecla Shift ser adicionada, se a seqncia atribuda propriedade keyEquivalent for uma letra maiscula. As constantes dos cdigos de tecla para usar nas teclas do modificador so definidas na classe Keyboard. A seqncia de equivalente de tecla atribuda exibida automaticamente ao lado no nome do item de menu. O formato depende do sistema operacional do usurio e das preferncias do sistema.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com menus

621

Nota: Se voc atribuir o valor Keyboard.COMMAND a uma matriz de modificador de tecla no sistema operacional do Windows, nenhum equivalente de tecla ser exibido no menu. No entanto, a tecla Control deve ser usada para ativar o comando de menu. O exemplo a seguir atribui Ctrl+Shift+G como equivalente de tecla de um item de menu:
var item:NativeMenuItem = new NativeMenuItem("Ungroup"); item.keyEquivalent = "G";

Este exemplo atribui Ctrl+Shift+G como equivalente de tecla, definindo diretamente a matriz do modificador:
var item:NativeMenuItem = new NativeMenuItem("Ungroup"); item.keyEquivalent = "G"; item.keyEquivalentModifiers = [Keyboard.CONTROL];

Nota: Os equivalentes de tecla s so ativados em menus de aplicativo e de janela. Se voc adicionar um equivalente de tecla a um menu de contexto ou de pop-up, o equivalente de tecla exibido no rtulo do menu, mas o comando de menu associado nunca ser chamado.

Mnemnicos (AIR)
Adobe AIR 1.0 e posterior Os mnemnicos so parte da interface de teclado do sistema operacional em menus. Linux, Mac OS X e Windows permitem a usurios abrir menus e selecionar comandos com o teclado, mas h diferenas sutis. No Mac OS X, o usurio digita a primeira ou as duas primeiras letras do menu ou comando e, em seguida, pressiona a tecla retornar. A propriedade mnemonicIndex ignorada. No Windows, apenas uma nica letra significativa. Por padro, a letra significativa o primeiro caractere no rtulo, mas se voc atribuir um mnemnico ao item de menu, o caractere significativo se torna a letra designada. Se dois itens em um menu tm o mesmo caractere significativo (quer um mnemnico tenha ou no sido atribudo), a interao de teclado do usurio com o menu muda um pouco. Em vez de pressionar uma nica letra para selecionar o menu ou comando, o usurio deve pressionar a letra quantas vezes for necessrio para realar o item desejado e, em seguida, pressionar a tecla Enter para concluir a seleo. Para manter um comportamento consistente, voc deve atribuir um mnemnico exclusivo a cada item no menu, em menus de janela. No Linux, nenhum mnemnico padro fornecido. Voc deve especificar um valor para a propriedade mnemonicIndex de um item de menu para fornecer um mnemnico. Especifique o caractere mnemnico como ndice na seqncia de rtulo. O ndice do primeiro caractere em um rtulo 0. Portanto, para usar "r" como o mnemnico de um item de menu rotulado, "Format", voc deve definir a propriedade mnemonicIndex igual a 2.
var item:NativeMenuItem = new NativeMenuItem("Format"); item.mnemonicIndex = 2;

Estado do item de menu

Adobe AIR 1.0 e posterior Os itens de menu tm duas propriedades de estados, marcados e ativados:
marcado Defina como true para exibir uma marca de seleo ao lado do rtulo de item.
var item:NativeMenuItem = new NativeMenuItem("Format"); item.checked = true;

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com menus

622

ativado Alterne o valor entre true e false para controlar se o comando est ativado. Itens desativados ficam

visualmente esmaecidos e no despacham eventos select.

var item:NativeMenuItem = new NativeMenuItem("Format"); item.enabled = false;

Anexar objeto a um item de menu

Adobe AIR 1.0 e posterior A propriedade data da classe NativeMenuItem permite fazer referncia a um objeto arbitrrio em cada item. Por exemplo, no menu "Open Recent", voc pode atribuir o objeto File de cada documento a cada item do menu.
var file:File = File.applicationStorageDirectory.resolvePath("GreatGatsby.pdf") var menuItem:NativeMenuItem = docMenu.addItem(new NativeMenuItem(file.name)); menuItem.data = file;

Criao de menus nativos (AIR)

Adobe AIR 1.0 e posterior Este tpico descreve como criar os vrios tipos de menu nativos suportados pelo AIR.

Criao de objeto do menu raiz

Adobe AIR 1.0 e posterior Para criar um objeto NativeMenu para servir como raiz do menu, use o construtor NativeMenu:
var root:NativeMenu = new NativeMenu();

Em menus de aplicativo e janela, o menu raiz representa a barra de menu e deve conter apenas itens que abram submenus. Menus de contexto e pop-up no tm barra de menu, portanto, o menu raiz pode conter comandos e linhas separadoras, bem como submenus. Depois que o menu criado, voc pode adicionar itens de menu. Os itens aparecem no menu na ordem em que so adicionados, a menos que voc os adicione em um ndice especfico, usando o mtodo addItemAt() de um objeto de menu. Atribua o menu como aplicativo, janela, cone ou menu de contexto ou exiba-o como menu pop-up, conforme mostrado nas sees a seguir: Configurao do menu de aplicativo ou menu de janela importante que o cdigo possua suporte a ambos menus do aplicativo (suporte no Mac OS) e menus de janela (suporte em outros sistems operacionais)

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com menus

623

var root:NativeMenu = new NativeMenu(); if (NativeApplication.supportsMenu) { NativeApplication.nativeApplication.menu = root; } else if (NativeWindow.supportsMenu) { nativeWindow.menu = root; }

Nota: O Mac OS define um menu contendo itens padro para cada aplicativo. Atribuir um novo objeto NativeMenu propriedade menu do objeto NativeApplication substitui o menu padro. Voc tambm pode usar o menu padro, em vez de substitui-lo. O Adobe Flex fornece uma classe FlexNativeMenu para criar facilmente menus que funcionam em vrias plataformas. Se estiver usando a estrutura do Flex, use as classes FlexNativeMenu no lugar da classe NativeMenu. Configurao de menu de contexto em um objeto interativo
interactiveObject.contextMenu = root;

Configurao de menu de cone de encaixe ou o menu de cone da bandeja do sistema importante que o cdigo possua suporte a ambos menus do aplicativo (suporte no Mac OS) e menus de janela (suporte em outros sistems operacionais)
if (NativeApplication.supportsSystemTrayIcon) { SystemTrayIcon(NativeApplication.nativeApplication.icon).menu = root; } else if (NativeApplication.supportsDockIcon) { DockIcon(NativeApplication.nativeApplication.icon).menu = root; }

Nota: O Mac OS X define um menu padro para o cone de encaixe do aplicativo. Ao atribuir um novo NativeMenu propriedade de menu do objeto DockIcon, os itens nesse menu so exibidos acima dos itens padro. Voc no pode remover, acessar nem modificar os itens de menu padro. Exibio de menu como pop-up
root.display(stage, x, y);

Mais tpicos da Ajuda

Desenvolvimento de aplicativos AIR para vrias plataformas

Criao de submenu
Adobe AIR 1.0 e posterior Para criar um submenu, voc adiciona o objeto NativeMenuItem ao menu pai e, em seguida, atribui o objeto NativeMenu, definindo o submenu para a propriedade submenu do item. O AIR oferece duas maneiras de criar itens de submenu e respectivos objetos de menu associados: Voc pode criar um item de menu e respectivo objeto de menu relacionado em uma etapa, com o mtodo
addSubmenu():

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com menus

624

var editMenuItem:NativeMenuItem = root.addSubmenu(new NativeMenu(), "Edit");

Voc tambm pode criar o item de menu e atribuir separadamente o objeto de menu respectiva propriedade submenu:
var editMenuItem:NativeMenuItem = root.addItem("Edit", false); editMenuItem.submenu = new NativeMenu();

Criao de comando de menu

Adobe AIR 1.0 e posterior Para criar um comando de menu, adicione o objeto NativeMenuItem a um menu e adicione um ouvinte de evento que faa referncia funo que implementa o comando de menu:
var copy:NativeMenuItem = new NativeMenuItem("Copy", false); copy.addEventListener(Event.SELECT, onCopyCommand); editMenu.addItem(copy);

Voc pode ouvir o evento select no prprio item de comando (conforme mostrado no exemplo) ou pode ouvir o evento select em um objeto de menu pai. Nota: Os itens de menu que representam submenus e linhas separadoras no despacham eventos select e, portanto, no podem ser usados como comandos.

Criao de linha separadora de menu

Adobe AIR 1.0 e posterior Para criar uma linha separadora, crie um NativeMenuItem, definindo o parmetro isSeparator como true no construtor. Em seguida, adicione o item separador ao menu no local correto:
var separatorA:NativeMenuItem = new NativeMenuItem("A", true); editMenu.addItem(separatorA);

O rtulo especificado para o separador, se houver, no exibido.

Sobre menus de contexto em HTML (AIR)

Adobe AIR 1.0 e posterior No contedo HTML exibido com o objeto HTMLLoader, o evento contextmenu pode ser usado para exibir um menu de contexto. Por padro, o menu de contexto exibido automaticamente quando o usurio chama o evento de menu de contexto no texto selecionado (clicando com o boto direito do mouse ou clicando com a tecla Command pressionada no texto). Para evitar que o menu padro seja aberto, oua o evento contextmenu e chame o mtodo preventDefault() do objeto de evento:
function showContextMenu(event){ event.preventDefault(); }

Em seguida, voc pode exibir um menu de contexto personalizado usando tcnicas DHTML ou exibindo o menu de contexto nativo do AIR. O exemplo a seguir exibe um menu de contexto nativo, chamando o mtodo display() do menu em resposta ao evento contextmenu de HTML:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com menus

625

<html> <head> <script src="AIRAliases.js" language="JavaScript" type="text/javascript"></script> <script language="javascript" type="text/javascript"> function showContextMenu(event){ event.preventDefault(); contextMenu.display(window.nativeWindow.stage, event.clientX, event.clientY); } function createContextMenu(){ var menu = new air.NativeMenu(); var command = menu.addItem(new air.NativeMenuItem("Custom command")); command.addEventListener(air.Event.SELECT, onCommand); return menu; } function onCommand(){ air.trace("Context command invoked."); } var contextMenu = createContextMenu(); </script> </head> <body> <p oncontextmenu="showContextMenu(event)" style="-khtml-user-select:auto;">Custom context menu.</p> </body> </html>

Exibio de menus nativos pop-up (AIR)

Adobe AIR 1.0 e posterior Voc pode exibir qualquer objeto NativeMenu em um tempo e local arbitrrios acima de uma janela, chamando o mtodo display() do menu. O mtodo requer uma referncia ao palco, portanto, apenas o contedo na caixa de proteo do aplicativo pode exibir o menu como pop-up. O mtodo a seguir exibe o menu definido por um objeto NativeMenu chamado popupMenu em resposta a um clique do mouse:
private function onMouseClick(event:MouseEvent):void { popupMenu.display(event.target.stage, event.stageX, event.stageY); }

Nota: O menu no precisa ser exibido em resposta direta ao evento. Qualquer mtodo pode chamar a funo display().

Tratamento de itens de menu

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O menu despacha eventos quando o usurio o seleciona ou quando seleciona um item de menu.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com menus

626

Resumo de eventos de classes de menu

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Adicione ouvintes de eventos a menus ou itens individuais para tratar eventos de menu.
Objeto NativeMenu (AIR) Eventos despachados Event.PREPARING (Adobe AIR 2.6 e posterior) Event.DISPLAYING Event.SELECT (propagado de itens filho e submenus) NativeMenuItem (AIR) Event.PREPARING (Adobe AIR 2.6 e posterior) Event.SELECT Event.DISPLAYING (propagado do menu pai) ContextMenu ContextMenuItem ContextMenuEvent.MENU_SELECT ContextMenuEvent.MENU_ITEM_SELECT Event.SELECT (AIR)

Eventos de menu Select

Adobe AIR 1.0 e posterior Para manipular o clique de um item de menu, adicione um ouvinte de evento do evento select ao objeto NativeMenuItem:
var menuCommandX:NativeMenuItem = new NativeMenuItem("Command X"); menuCommandX.addEventListener(Event.SELECT, doCommandX)

Como os eventos select surgem em bolhas para os menus que os contm, voc tambm pode ouvir eventos select em um menu pai. Ao ouvir no nvel de menu, possvel usar a propriedade target do objeto evento para determinar que comando de menu foi selecionado. O exemplo a seguir rastreia o rtulo do comando selecionado:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com menus

627

var colorMenuItem:NativeMenuItem = new NativeMenuItem("Choose a color"); var colorMenu:NativeMenu = new NativeMenu(); colorMenuItem.submenu = colorMenu; var red:NativeMenuItem = new NativeMenuItem("Red"); var green:NativeMenuItem = new NativeMenuItem("Green"); var blue:NativeMenuItem = new NativeMenuItem("Blue"); colorMenu.addItem(red); colorMenu.addItem(green); colorMenu.addItem(blue); if(NativeApplication.supportsMenu){ NativeApplication.nativeApplication.menu.addItem(colorMenuItem); NativeApplication.nativeApplication.menu.addEventListener(Event.SELECT, colorChoice); } else if (NativeWindow.supportsMenu){ var windowMenu:NativeMenu = new NativeMenu(); this.stage.nativeWindow.menu = windowMenu; windowMenu.addItem(colorMenuItem); windowMenu.addEventListener(Event.SELECT, colorChoice); } function colorChoice(event:Event):void { var menuItem:NativeMenuItem = event.target as NativeMenuItem; trace(menuItem.label + " has been selected"); }

Se voc estiver usando a classe ContextMenuItem, poder ouvir o evento select ou o evento menuItemSelect. O evento menuItemSelect oferece informaes adicionais sobre o objeto pertencente ao menu de contexto, mas no surge em bolhas para os menus que os contm.

Exibio de eventos de menu

Adobe AIR 1.0 e posterior Para manipular a abertura de um menu, voc pode adicionar um ouvinte ao evento displaying, que despachado antes de o menu ser exibido. Voc pode usar o evento displaying para atualizar o menu, por exemplo, adicionando ou removendo itens ou atualizando os estados ativados ou marcados de itens individuais. Voc tambm pode ouvir o evento menuSelect de um objeto ContextMenu. No AIR 2.6 e posterior, voc pode usar o evento preparing para atualizar um menu em resposta exibio de um menu ou seleo de um item com um atalho no teclado.

Exemplo de menu nativo: menu de janela e de aplicativo (AIR)

Adobe AIR 1.0 e posterior O exemplo a seguir cria o menu mostrado em Estrutura do menu nativo (AIR) na pgina 618.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com menus

628

O menu foi projetado para funcionar no Windows, em que apenas os menus de janela tm suporte, e no Mac OS X, em que apenas menus de aplicativo tm suporte. Para fazer distino, o construtor de classe MenuExample verifica as propriedades supportsMenu estticas das classes NativeWindow e NativeApplication. Se NativeWindow.supportsMenu for true, o construtor cria um objeto NativeMenu para a janela e, em seguida, cria e adiciona os submenus File e Edit. Se NativeApplication.supportsMenu for true, o construtor cria e adiciona os menus File e Edit ao menu existente fornecido pelo sistema operacional Mac OS X. O exemplo tambm ilustra o tratamento de evento de menu. O evento select manipulado no nvel de item e tambm no nvel de menu. Cada menu na cadeia do menu que contm o item selecionado para o menu raiz responde ao evento select. O evento displaying usado com o menu Open Recent. Logo antes de o menu ser aberto, os itens do menu so atualizados da matriz Documentos recentes (que na realidade no alterada neste exemplo). Embora no demonstrado nesse exemplo, voc tambm pode ouvir eventos displaying em itens individuais.
package { import import import import import import import flash.display.NativeMenu; flash.display.NativeMenuItem; flash.display.NativeWindow; flash.display.Sprite; flash.events.Event; flash.filesystem.File; flash.desktop.NativeApplication;

public class MenuExample extends Sprite { private var recentDocuments:Array = new Array(new File("app-storage:/GreatGatsby.pdf"), new File("app-storage:/WarAndPeace.pdf"), new File("app-storage:/Iliad.pdf")); public function MenuExample() { var fileMenu:NativeMenuItem; var editMenu:NativeMenuItem; if (NativeWindow.supportsMenu){ stage.nativeWindow.menu = new NativeMenu(); stage.nativeWindow.menu.addEventListener(Event.SELECT, selectCommandMenu); fileMenu = stage.nativeWindow.menu.addItem(new NativeMenuItem("File")); fileMenu.submenu = createFileMenu(); editMenu = stage.nativeWindow.menu.addItem(new NativeMenuItem("Edit")); editMenu.submenu = createEditMenu(); } if (NativeApplication.supportsMenu){ NativeApplication.nativeApplication.menu.addEventListener(Event.SELECT, selectCommandMenu); fileMenu = NativeApplication.nativeApplication.menu.addItem(new NativeMenuItem("File")); fileMenu.submenu = createFileMenu(); editMenu = NativeApplication.nativeApplication.menu.addItem(new NativeMenuItem("Edit")); editMenu.submenu = createEditMenu(); } } public function createFileMenu():NativeMenu {

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com menus

629

var fileMenu:NativeMenu = new NativeMenu(); fileMenu.addEventListener(Event.SELECT, selectCommandMenu); var newCommand:NativeMenuItem = fileMenu.addItem(new NativeMenuItem("New")); newCommand.addEventListener(Event.SELECT, selectCommand); var saveCommand:NativeMenuItem = fileMenu.addItem(new NativeMenuItem("Save")); saveCommand.addEventListener(Event.SELECT, selectCommand); var openRecentMenu:NativeMenuItem = fileMenu.addItem(new NativeMenuItem("Open Recent")); openRecentMenu.submenu = new NativeMenu(); openRecentMenu.submenu.addEventListener(Event.DISPLAYING, updateRecentDocumentMenu); openRecentMenu.submenu.addEventListener(Event.SELECT, selectCommandMenu); return fileMenu; } public function createEditMenu():NativeMenu { var editMenu:NativeMenu = new NativeMenu(); editMenu.addEventListener(Event.SELECT, selectCommandMenu); var copyCommand:NativeMenuItem = editMenu.addItem(new NativeMenuItem("Copy")); copyCommand.addEventListener(Event.SELECT, selectCommand); copyCommand.keyEquivalent = "c"; var pasteCommand:NativeMenuItem = editMenu.addItem(new NativeMenuItem("Paste")); pasteCommand.addEventListener(Event.SELECT, selectCommand); pasteCommand.keyEquivalent = "v"; editMenu.addItem(new NativeMenuItem("", true)); var preferencesCommand:NativeMenuItem = editMenu.addItem(new NativeMenuItem("Preferences")); preferencesCommand.addEventListener(Event.SELECT, selectCommand); return editMenu; } private function updateRecentDocumentMenu(event:Event):void { trace("Updating recent document menu."); var docMenu:NativeMenu = NativeMenu(event.target); for each (var item:NativeMenuItem in docMenu.items) { docMenu.removeItem(item); } for each (var file:File in recentDocuments) { var menuItem:NativeMenuItem = docMenu.addItem(new NativeMenuItem(file.name)); menuItem.data = file; menuItem.addEventListener(Event.SELECT, selectRecentDocument); } } private function selectRecentDocument(event:Event):void { trace("Selected recent document: " + event.target.data.name); } private function selectCommand(event:Event):void {

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com menus

630

trace("Selected command: " + event.target.label); } private function selectCommandMenu(event:Event):void { if (event.currentTarget.parent != null) { var menuItem:NativeMenuItem = findItemForMenu(NativeMenu(event.currentTarget)); if (menuItem != null) { trace("Select event for \"" + event.target.label + "\" command handled by menu: " + menuItem.label); } } else { trace("Select event for \"" + event.target.label + "\" command handled by root menu."); } } private function findItemForMenu(menu:NativeMenu):NativeMenuItem { for each (var item:NativeMenuItem in menu.parent.items) { if (item != null) { if (item.submenu == menu) { return item; } } } return null; } } }

ltima atualizao em 29/3/2011

631

Captulo 35: cones da barra de tarefas no AIR

Adobe AIR 1.0 e posterior Muitos sistemas operacionais tm uma barra de tarefas, como o encaixe do Mac OS X, que pode conter um cone representando um aplicativo. O Adobe AIR oferece uma interface que permite interagir com o cone na barra de tarefas atravs da propriedade NativeApplication.nativeApplication.icon.

Uso da bandeja do sistema e dos cones de encaixe (Flex) Uso dos cones de bandeja do sistema e do encaixe (Flash)

Mais tpicos da Ajuda

flash.desktop.NativeApplication flash.desktop.DockIcon flash.desktop.SystemTrayIcon

Sobre cones na barra de tarefas

Adobe AIR 1.0 e posterior O AIR cria o objeto NativeApplication.nativeApplication.icon automaticamente. O tipo de objeto DockIcon ou SystemTrayIcon, dependendo do sistema operacional. possvel determinar qual destas subclasses InteractiveIcon suportada pelo AIR no sistema operacional atual usando as propriedades NativeApplication.supportsDockIcon e NativeApplication.supportsSystemTrayIcon. A classe base InteractiveIcon oferece as propriedades width, height e bitmaps, que voc pode usar para alterar a imagem utilizada para o cone. No entanto, acessar propriedades especficas de DockIcon ou SystemTrayIcon no sistema operacional incorreto gera um erro de execuo. Para definir ou alterar a imagem usada para um cone, crie uma matriz que contenha uma ou mais imagens e a atribua propriedade NativeApplication.nativeApplication.icon.bitmaps. O tamanho dos cones na barra de tarefas pode ser diferente nos diferentes sistemas operacionais. Para evitar a degradao da imagem devido ao dimensionamento, possvel adicionar vrios tamanhos de imagem matriz bitmaps. Se voc fornecer mais de uma imagem, o AIR selecionar o tamanho mais prximo do tamanho de exibio atual do cone na barra de tarefas e s o dimensionar se for necessrio. O exemplo abaixo define a imagem para um cone da barra de tarefas usando duas imagens:
NativeApplication.nativeApplication.icon.bitmaps = [bmp16x16.bitmapData, bmp128x128.bitmapData];

Para alterar a imagem de um cone, atribua uma matriz que contenha a(s) nova(s) imagem(ns) propriedade bitmaps. Voc pode animar o cone alterando a imagem em resposta a um evento enterFrame ou timer. Para remover o cone da rea de notificao no Windows e no Linux ou para restaurar a aparncia do cone padro no Mac OS X, defina bitmaps como uma matriz vazia:
NativeApplication.nativeApplication.icon.bitmaps = [];

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

cones da barra de tarefas no AIR

632

cones de encaixe
Adobe AIR 1.0 e posterior O AIR suporta cones de encaixe quando NativeApplication.supportsDockIcon true. A propriedade NativeApplication.nativeApplication.icon representa o cone do aplicativo no encaixe (no um cone de encaixe na janela). Nota: O AIR no permite alterar cones de janela no encaixe do Mac OS X. Alm disso, as alteraes feitas no cone de encaixe de aplicativo s so aplicadas enquanto um aplicativo est em execuo o cone reassume a aparncia normal quando o aplicativo encerrado.

Menus com cone no encaixe

Adobe AIR 1.0 e posterior possvel adicionar comandos ao menu de encaixe padro criando um objeto NativeMenu que contenha os comandos e atribuindo o objeto propriedade NativeApplication.nativeApplication.icon.menu. Os itens do menu so exibidos acima dos itens padro do menu com cones no encaixe.

Fazer o encaixe pular

Adobe AIR 1.0 e posterior possvel fazer com que o cone no encaixe pule chamando o mtodo NativeApplication.nativeApplication.icon.bounce(). Se voc definir o parmetro bounce() priority como informativo, o cone pular uma vez. Se voc definir o parmetro como crtico, o cone pular at o usurio ativar o aplicativo. As constantes do parmetro priority so definidas na classe NotificationType. Nota: O cone no pula se o aplicativo j est ativo.

Eventos de cones no encaixe

Adobe AIR 1.0 e posterior Quando o usurio clica em um cone no encaixe, o objeto NativeApplication despacha um evento invoke. Se o aplicativo no estiver em execuo, ser iniciado pelo sistema. Caso contrrio, o evento invoke ser entregue ocorrncia do aplicativo em execuo.

cones da bandeja do sistema

Adobe AIR 1.0 e posterior O AIR oferece suporte a cones de bandeja do sistema quando NativeApplication.supportsSystemTrayIcon for true, o que no momento s ocorre no Windows e na maioria das distribuies do Linux. No Windows e no Linux, os cones de bandeja do sistema so exibidos na rea de notificao da barra de tarefas. Nenhum cone exibido por padro. Para mostrar um cone, atribua uma matriz contendo objetos BitmapData propriedade bitmaps do cone. Para alterar a imagem do cone, atribua uma matriz que contenha as novas imagens a bitmaps. Para remover o cone, defina bitmaps como null.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

cones da barra de tarefas no AIR

633

Menus de cones da bandeja do sistema

Adobe AIR 1.0 e posterior possvel adicionar um menu ao cone da bandeja do sistema criando-se um objeto NativeMenu e o atribuindo propriedade NativeApplication.nativeApplication.icon.menu (o sistema operacional no oferece um menu padro). Acesse o menu do cone da bandeja do sistema clicando no cone com o boto direito do mouse.

Dicas de ferramentas sobre cones da bandeja do sistema

Adobe AIR 1.0 e posterior Adicione uma dica de ferramenta a um cone definindo a propriedade tooltip:
NativeApplication.nativeApplication.icon.tooltip = "Application name";

Eventos de cone da bandeja do sistema

Adobe AIR 1.0 e posterior O objeto SystemTrayIcon referenciado pela propriedade NativeApplication.nativeApplication.icon despacha um ScreenMouseEvent para eventos click, mouseDown, mouseUp, rightClick, rightMouseDown e rightMouseUp. Voc pode usar esses eventos, junto com um menu de cone, para que os usurios possam interagir com seu aplicativo quando ele no tiver janelas visveis.

Exemplo: Criao de um aplicativo sem janelas

Adobe AIR 1.0 e posterior O exemplo a seguir cria um aplicativo AIR que tem um cone na bandeja do sistema, mas nenhuma janela visvel. (A propriedade visible do aplicativo no deve ser definida como true no descrito do aplicativo, ou a janela ser visvel quando o aplicativo for iniciado.)
package { import import import import import import import import import import

flash.display.Loader; flash.display.NativeMenu; flash.display.NativeMenuItem; flash.display.NativeWindow; flash.display.Sprite; flash.desktop.DockIcon; flash.desktop.SystemTrayIcon; flash.events.Event; flash.net.URLRequest; flash.desktop.NativeApplication;

public class SysTrayApp extends Sprite { public function SysTrayApp():void{ NativeApplication.nativeApplication.autoExit = false; var icon:Loader = new Loader(); var iconMenu:NativeMenu = new NativeMenu(); var exitCommand:NativeMenuItem = iconMenu.addItem(new NativeMenuItem("Exit")); exitCommand.addEventListener(Event.SELECT, function(event:Event):void {

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

cones da barra de tarefas no AIR

634

NativeApplication.nativeApplication.icon.bitmaps = []; NativeApplication.nativeApplication.exit(); }); if (NativeApplication.supportsSystemTrayIcon) { NativeApplication.nativeApplication.autoExit = false; icon.contentLoaderInfo.addEventListener(Event.COMPLETE, iconLoadComplete); icon.load(new URLRequest("icons/AIRApp_16.png")); var systray:SystemTrayIcon = NativeApplication.nativeApplication.icon as SystemTrayIcon; systray.tooltip = "AIR application"; systray.menu = iconMenu; } if (NativeApplication.supportsDockIcon){ icon.contentLoaderInfo.addEventListener(Event.COMPLETE,iconLoadComplete); icon.load(new URLRequest("icons/AIRApp_128.png")); var dock:DockIcon = NativeApplication.nativeApplication.icon as DockIcon; dock.menu = iconMenu; } } private function iconLoadComplete(event:Event):void { NativeApplication.nativeApplication.icon.bitmaps = [event.target.content.bitmapData]; } } }

Nota: Ao usar o componente WindowedApplication do Flex, defina o atributo visible da tag WindowedApplication como false. Este atributo substitui a configurao no descritor de aplicativo. Nota: O exemplo pressupe que existem arquivos de imagem chamados AIRApp_16.png e AIRApp_128.png em um subdiretrio icons do aplicativo. (Arquivos de cone de exemplo, que voc pode copiar para a pasta do seu projeto, so fornecidos no SDK do AIR.)

cones e botes da barra de tarefas do Windows

Adobe AIR 1.0 e posterior As representaes em forma de cone de janelas geralmente so exibidas na rea de janela de uma barra de tarefas ou de um encaixe, para que os usurios tenham fcil acesso a janelas em segundo plano ou minimizadas. O encaixe do Mac OS X exibe um cone do seu aplicativo e um cone de cada janela minimizada. As barras de tarefas do Microsoft Windows e do Linux exibem um boto que contm o cone do programa e o ttulo de cada janela de tipo normal do seu aplicativo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

cones da barra de tarefas no AIR

635

Realce do boto da janela na barra de ferramentas

Adobe AIR 1.0 e posterior Quando uma janela est em segundo plano, voc pode notificar o usurio de que ocorreu um evento de interesse relacionado janela. No Mac OS X, voc pode notificar o usurio fazendo o cone de encaixe do aplicativo pular (conforme descrito em Fazer o encaixe pular na pgina 632). No Windows e no Linux, voc pode realar o boto da barra de tarefas da janela chamando o mtodo notifyUser() da ocorrncia NativeWindow. O parmetro type passado para o mtodo determina a urgncia da notificao:

NotificationType.CRITICAL: o cone da janela fica piscando at o usurio colocar a janela no primeiro plano. NotificationType.INFORMATIONAL: o cone da janela fica realado pela troca de cores.

Nota: No Linux, s h suporte para o tipo informativo de notificao. Passar um dos valores de tipo para a funo notifyUser() criar o mesmo efeito. A seguinte instruo reala o boto da barra de tarefas de uma janela:
stage.nativeWindow.notifyUser(NotificationType.CRITICAL);

Chamar o mtodo NativeWindow.notifyUser() em um sistema operacional que no d suporte a notificaes de janela no produz qualquer efeito. Use a propriedade NativeWindow.supportsNotification para determinar se a notificao de janela suportada.

Criao de janelas sem botes ou cones na barra de tarefas

Adobe AIR 1.0 e posterior No sistema operacional Windows, as janelas criadas com os tipos utility ou lightweight no aparecem na barra de tarefas. As janelas invisveis tambm no. Como a janela inicial necessariamente do tipo normal, para criar um aplicativo sem nenhuma janela aparecendo na barra de tarefas, voc deve fechar a janela inicial ou deix-la invisvel. Para fechar todas as janelas do seu aplicativo sem encerr-lo, defina a propriedade autoExit do objeto NativeApplication como false antes de fechar a ltima janela. Para impedir que a janela inicial se torne visvel, adicione <visible>false</visible> ao elemento <initalWindow> do arquivo de descrio do aplicativo (e no defina a propriedade visible como true ou chame o mtodo activate() da janela). Nas novas janelas abertas pelo aplicativo, defina a propriedade type do objeto NativeWindowInitOption passado para o construtor de janela como NativeWindowType.UTILITY ou NativeWindowType.LIGHTWEIGHT. No Mac OS X, as janelas minimizadas so exibidas na barra de tarefas do encaixe. Para impedir que o cone minimizado seja exibido, oculte a janela em vez de minimiz-la. O exemplo a seguir monitora um evento de alterao nativeWindowDisplayState e o cancela se a janela est sendo minimizada. O manipulador define a propriedade visible da janela como false:
private function preventMinimize(event:NativeWindowDisplayStateEvent):void{ if(event.afterDisplayState == NativeWindowDisplayState.MINIMIZED){ event.preventDefault(); event.target.visible = false; } }

Se uma janela est minimizada no encaixe do Mac OS X quando voc define a propriedade visible como false, o cone no encaixe no removido. Um usurio ainda poder clicar no cone para fazer com que a janela reaparea.

ltima atualizao em 29/3/2011

636

Captulo 36: Trabalho com o sistema de arquivos

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O Flash Player fornece recursos bsicos de leitura e gravao de arquivos, atravs da classe FileReference. Por razes de segurana, ao executar no Flash Player, o usurio sempre deve conceder permisso para que voc possa ler ou gravar um arquivo. O Adobe AIR fornece um acesso mais completo ao sistema de arquivos do computador host que est disponvel no Flash Player. Usando a API do sistema de arquivos do AIR, voc pode acessar e gerenciar diretrios e arquivos, criar diretrios e arquivos, gravar dados em arquivos e assim por diante.

Mais tpicos da Ajuda

flash.net.FileReference flash.net.FileReferenceList flash.filesystem.File flash.filesystem.FileStream

Uso da classe FileReference

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Um objeto FileReference representa um arquivo de dados em um computador cliente ou servidor. Os mtodos da classe FileReference permitem que o seu aplicativo carregue e salve os arquivos de dados localmente, alm de transferir dados de arquivos para ou de servidores remotos. A classe FileReference oferece duas abordagens diferentes para carregar, transferir e salvar arquivos de dados. Desde sua introduo, a classe FileReference contm o mtodo browse(), o mtodo upload(), e o mtodo download(). Use o mtodo browse() para permitir que o usurio selecione um arquivo. Use o mtodo upload() para transferir os dados do arquivo para um servidor remoto. Use o mtodo download() para acessar esses dados no servidor e salvlos em um arquivo local. A partir do Flash Player 10 e do Adobe AIR 1.5, a classe FileReference contm os mtodos load() e save(). Os mtodos load() e save() tambm permitem que voc acesse e salve diretamente os arquivos locais. O uso desses mtodos semelhante ao dos mtodos de nome equivalente nas classes URLLoader e Loader. Nota: A classe File, que estende a classe FileReference, e a classe FileStream fornecem funes adicionais para trabalhar com arquivos e com o sistema de arquivos local. As classes File e FileStream so s suportadas no AIR e no no Flash Player.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

637

classe FileReference
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Cada objeto FileReference representa um arquivo de dados nico no computador local. As propriedades da classe FileReference contm informaes sobre as seguintes caractersticas do arquivo: tamanho, tipo, nome, extenso do nome de arquivo, criador, data de criao e data de modificao. Nota: H suporte para a propriedade creator apenas no Mac OS. Todas as outras plataformas retornam null. Nota: A propriedade extension suportada somente no Adobe AIR. Voc pode criar uma ocorrncia da classe FileReference de duas maneiras:

Use o operador new, conforme apresentado no cdigo a seguir:

import flash.net.FileReference; var fileRef:FileReference = new FileReference();

Chame o mtodo FileReferenceList.browse(), que abre uma caixa de dilogo que solicita ao usurio
selecionar um ou mais arquivos para carregar. Ele pode criar uma matriz de objetos FileReference se o usurio conseguir selecionar um ou mais arquivos. Aps criar um objeto FileReference, voc pode proceder da seguinte maneira:

Chame o mtodo FileReference.browse(), que abre uma caixa de dilogo que solicita ao usurio selecionar um
ou mais arquivos no sistema de arquivos local. Normalmente, isso feito antes de uma chamada subsequente ao mtodo FileReference.upload() ou FileReference.load(). Chame o mtodo FileReference.upload() para transferir o arquivo a um servidor remoto. Chame o mtodo FileReference.load() para abrir um arquivo local.

Chame o mtodo FileReference.download(). Ser aberta uma caixa de dilogo pelo mtodo download() para
possibilitar a seleo de um local para gravao de um novo arquivo. Em seguida, os dados do servidor sero baixados e armazenados no novo arquivo.

Chame o mtodo FileReference.load(). Este mtodo comea a carregar dados de um arquivo previamente
selecionado usando o mtodo browse(). O mtodo load() no pode ser chamado at a operao browse() ser concluda (at o usurio selecionar um arquivo).

Chame o mtodo FileReference.save(). Este mtodo abre uma caixa de dilogo e pede para o usurio escolher
uma nica localizao de arquivo no sistema de arquivos local. Em seguida, ele salva os dados no local especificado. Nota: Voc pode executar apenas uma ao browse(), download() ou save() de cada vez, porque s pode ser aberta uma caixa de dilogo a qualquer momento. As propriedades do objeto FileReference, como name, size ou modificationDate no so definidas at que ocorra um dos eventos a seguir:

O mtodo FileReference.browse() ou o mtodo FileReferenceList.browse() foi chamado e o usurio

selecionou um arquivo usando a caixa de dilogo.

O mtodo FileReference.download() foi chamado e o usurio especificou um novo local para os arquivos
usando a caixa de dilogo. Nota: Ao fazer um download, apenas a propriedade FileReference.name preenchida antes do download ser concludo. Aps o download do arquivo, todas as propriedades esto disponveis. Enquanto as chamadas dos mtodos FileReference.browse(), FileReferenceList.browse(),
FileReference.download(), FileReference.load() ou FileReference.save() esto em execuo, a maioria

dos players continua reproduzindo arquivos SWF, inclusive despachando eventos e executando cdigo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

638

Para operaes de upload e download, um arquivo SWF pode acessar arquivos apenas em seu prprio domnio, incluindo todos os domnios especificados por um arquivo de poltica. Voc deve colocar um arquivo de poltica no servidor que contm o arquivo se esse servidor no est no mesmo domnio do arquivo SWF que est iniciando o upload ou o download. See FileReference.

Carregamento de dados de arquivos

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O mtodo FileReference.load() permite carregar dados de um arquivo local na memria. Nota: O seu cdigo deve chamar primeiro o mtodo FileReference.browse() para que o usurio possa selecionar um arquivo a ser carregado. Essa restrio no se aplica ao contedo que est em execuo no Adobe AIR na caixa de segurana do aplicativo O mtodo FileReference.load() retorna imediatamente depois de ser chamado, mas os dados que esto sendo carregados no ficam disponveis de imediato. O objeto FileReference despacha eventos para chamar mtodos de ouvinte em cada etapa do processo de carregamento. O objeto FileReference despacha os eventos a seguir durante o processo de carregamento.

Evento open (Event.OPEN): despachado quando uma operao de carregamento iniciada. Evento progress (ProgressEvent.PROGRESS): despachado periodicamente na medida em que os dados do
arquivo so lidos.

Evento complete (Event.COMPLETE): despachado quando a operao de carregamento concluda com sucesso. Evento ioError (IOErrorEvent.IO_ERROR): despachado se o processo de carregamento falha devido a um erro
de entrada/sada ocorrido durante a abertura ou a leitura de dados do arquivo. Uma vez que o objeto FileReference despacha o evento complete, os dados carregados podem ser acessados como um ByteArray na propriedade data do objeto FileReference. O exemplo a seguir mostra como solicitar ao usurio que selecione um arquivo e carregue os dados do arquivo na memria:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

639

package { import import import import import import

flash.display.Sprite; flash.events.*; flash.net.FileFilter; flash.net.FileReference; flash.net.URLRequest; flash.utils.ByteArray;

public class FileReferenceExample1 extends Sprite { private var fileRef:FileReference; public function FileReferenceExample1() { fileRef = new FileReference(); fileRef.addEventListener(Event.SELECT, onFileSelected); fileRef.addEventListener(Event.CANCEL, onCancel); fileRef.addEventListener(IOErrorEvent.IO_ERROR, onIOError); fileRef.addEventListener(SecurityErrorEvent.SECURITY_ERROR, onSecurityError); var textTypeFilter:FileFilter = new FileFilter("Text Files (*.txt, *.rtf)", "*.txt;*.rtf"); fileRef.browse([textTypeFilter]); } public function onFileSelected(evt:Event):void { fileRef.addEventListener(ProgressEvent.PROGRESS, onProgress); fileRef.addEventListener(Event.COMPLETE, onComplete); fileRef.load(); } public function onProgress(evt:ProgressEvent):void { trace("Loaded " + evt.bytesLoaded + " of " + evt.bytesTotal + " bytes."); } public function onComplete(evt:Event):void { trace("File was successfully loaded."); trace(fileRef.data); } public function onCancel(evt:Event):void { trace("The browse request was canceled by the user."); } public function onIOError(evt:IOErrorEvent):void { trace("There was an IO Error."); } public function onSecurityError(evt:Event):void { trace("There was a security error."); } } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

640

O cdigo do exemplo primeiro cria o objeto FileReference chamado fileRef e depois chama o mtodo browse() correspondente. Este mtodo browse() abre uma caixa de dilogo que pede para o usurio selecionar um arquivo. Quando um arquivo selecionado, o cdigo chama o mtodo onFileSelected(). Este mtodo adiciona ouvintes dos eventos progress e complete e chama o mtodo load() do objeto FileReference. Os outros mtodos do manipulador citados no exemplo simplesmente geram mensagens que informam o andamento da operao de carregamento. Quando o carregamento for concludo, o aplicativo exibe o contedo do arquivo carregado usando o mtodo trace(). No Adobe AIR, a classe FileStream fornece uma funcionalidade extra para ler dados de um arquivo local. Consulte Leitura e gravao de arquivos na pgina 674.

Gravao de dados em arquivos locais

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O mtodo FileReference.save() permite salvar dados em um arquivo local. Ele iniciado ao abrir uma caixa de dilogo para permitir ao usurio digitar um novo nome para o arquivo e definir um local onde o arquivo ser salvo. Aps a seleo do nome do arquivo e do local, os dados so gravados no novo arquivo. Quando o arquivo for salvo com xito, as propriedades do objeto FileReference sero preenchidas com as propriedades do arquivo local. Nota: O cdigo s pode chamar o mtodo FileReference.save() em resposta a um evento de usurio, como um clique do mouse ou um evento de pressionamento de tecla. Caso contrrio, gerado um erro. Essa restrio no se aplica ao contedo que est em execuo no Adobe AIR na caixa de segurana do aplicativo. O mtodo FileReference.save() retornado imediatamente aps a chamada. Em seguida, o objeto FileReference envia eventos para chamar mtodos de ouvintes em cada etapa do processo de gravao do arquivo. O objeto FileReference despacha os eventos a seguir durante o processo de gravao do arquivo:

Evento select (Event.SELECT): despachado quando o usurio especifica o local e o nome de arquivo para o novo
arquivo a ser salvo.

Evento cancel (Event.CANCEL): despachado quando o usurio clica no boto Cancelar da caixa de dilogo. Evento open (Event.OPEN): despachado quando uma operao de salvamento iniciada. Evento progress (ProgressEvent.PROGRESS): despachado periodicamente na medida em que os dados so
gravados no arquivo.

Evento complete (Event.COMPLETE): despachado quando a operao de gravao concluda com sucesso. Evento ioError (IOErrorEvent.IO_ERROR): despachado se o processo de salvamento falha devido a um erro de
entrada/sada ocorrido durante a tentativa de salvar dados no arquivo. O tipo de objeto transmitido no parmetro data do mtodo FileReference.save() determina como os dados so gravados no arquivo:

Se for um valor String, os dados sero salvos como um arquivo de texto na codificao UTF-8. Se for um objeto XML, eles sero gravados em um arquivo no formato XML com toda a formatao preservada. Se for um objeto ByteArray, seu contedo ser gravado diretamente no arquivo, sem converso. Se for outro objeto, o mtodo FileReference.save() chamar o mtodo toString() do objeto e salvar o valor
String resultante em um arquivo de texto UTF-8. Se no for possvel chamar o mtodo toString() do objeto, ser gerado um erro. Se o valor do parmetro data for null, ser gerado um erro. O cdigo a seguir amplia o exemplo anterior do mtodo FileReference.load(). Aps a leitura dos dados do arquivo, esse exemplo solicita ao usurio um nome de arquivo e, em seguida, salva os dados em um novo arquivo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

641

package { import import import import import import

flash.display.Sprite; flash.events.*; flash.net.FileFilter; flash.net.FileReference; flash.net.URLRequest; flash.utils.ByteArray;

public class FileReferenceExample2 extends Sprite { private var fileRef:FileReference; public function FileReferenceExample2() { fileRef = new FileReference(); fileRef.addEventListener(Event.SELECT, onFileSelected); fileRef.addEventListener(Event.CANCEL, onCancel); fileRef.addEventListener(IOErrorEvent.IO_ERROR, onIOError); fileRef.addEventListener(SecurityErrorEvent.SECURITY_ERROR, onSecurityError); var textTypeFilter:FileFilter = new FileFilter("Text Files (*.txt, *.rtf)", "*.txt;*.rtf"); fileRef.browse([textTypeFilter]); } public function onFileSelected(evt:Event):void { fileRef.addEventListener(ProgressEvent.PROGRESS, onProgress); fileRef.addEventListener(Event.COMPLETE, onComplete); fileRef.load(); } public function onProgress(evt:ProgressEvent):void { trace("Loaded " + evt.bytesLoaded + " of " + evt.bytesTotal + " bytes."); } public function onCancel(evt:Event):void { trace("The browse request was canceled by the user."); } public function onComplete(evt:Event):void { trace("File was successfully loaded."); fileRef.removeEventListener(Event.SELECT, onFileSelected); fileRef.removeEventListener(ProgressEvent.PROGRESS, onProgress); fileRef.removeEventListener(Event.COMPLETE, onComplete); fileRef.removeEventListener(Event.CANCEL, onCancel); saveFile(); } public function saveFile():void { fileRef.addEventListener(Event.SELECT, onSaveFileSelected); fileRef.save(fileRef.data,"NewFileName.txt"); } public function onSaveFileSelected(evt:Event):void { fileRef.addEventListener(ProgressEvent.PROGRESS, onSaveProgress);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

642

fileRef.addEventListener(Event.COMPLETE, onSaveComplete); fileRef.addEventListener(Event.CANCEL, onSaveCancel); } public function onSaveProgress(evt:ProgressEvent):void { trace("Saved " + evt.bytesLoaded + " of " + evt.bytesTotal + " bytes."); } public function onSaveComplete(evt:Event):void { trace("File saved."); fileRef.removeEventListener(Event.SELECT, onSaveFileSelected); fileRef.removeEventListener(ProgressEvent.PROGRESS, onSaveProgress); fileRef.removeEventListener(Event.COMPLETE, onSaveComplete); fileRef.removeEventListener(Event.CANCEL, onSaveCancel); } public function onSaveCancel(evt:Event):void { trace("The save request was canceled by the user."); } public function onIOError(evt:IOErrorEvent):void { trace("There was an IO Error."); } public function onSecurityError(evt:Event):void { trace("There was a security error."); } } }

Quando todos os dados forem carregados do arquivo, o cdigo chamar o mtodo onComplete(). O mtodo onComplete() remove os ouvintes dos eventos de carregamento e, em seguida, chama o mtodo saveFile(). O mtodo saveFile() chama o mtodo FileReference.save(). O mtodo FileReference.save() abre uma nova caixa de dilogo na qual o usurio pode digitar um novo nome e um local para salvar o arquivo. Os mtodos restantes do ouvinte de eventos rastreiam o andamento do processo de gravao do arquivo at que seja concludo. No Adobe AIR, a classe FileStream fornece uma funcionalidade extra para gravar dados em um arquivo local. Consulte Leitura e gravao de arquivos na pgina 674.

Upload de arquivos em um servidor

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para carregar arquivos para um servidor, chame primeiro o mtodo browse() para permitir que um usurio selecione um ou mais arquivos. Em seguida, quando o mtodo FileReference.upload() chamado, o arquivo selecionado transferido para o servidor. Se o usurio seleciona vrios arquivos usando o mtodo FileReferenceList.browse(), o Flash Player cria uma matriz dos arquivos selecionados chamada FileReferenceList.fileList. Em seguida, voc pode usar o mtodo FileReference.upload() para carregar cada arquivo individualmente. Nota: O uso do mtodo FileReference.browse() permite carregar apenas arquivos nicos. Para permitir que um usurio carregue vrios arquivos, use o mtodo FileReferenceList.browse().

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

643

Por padro, a caixa de dilogo de seletor de arquivos do sistema permite que os usurios selecionem qualquer tipo de arquivo do computador local. Os desenvolvedores podem especificar um ou mais filtros do tipo de arquivo personalizado usando a classe FileFilter e transmitindo uma matriz de instncias de filtros de arquivo para o mtodo browse():
var imageTypes:FileFilter = new FileFilter("Images (*.jpg, *.jpeg, *.gif, *.png)", "*.jpg; *.jpeg; *.gif; *.png"); var textTypes:FileFilter = new FileFilter("Text Files (*.txt, *.rtf)", "*.txt; *.rtf"); var allTypes:Array = new Array(imageTypes, textTypes); var fileRef:FileReference = new FileReference(); fileRef.browse(allTypes);

Quando o usurio seleciona os arquivos e clica no boto Abrir no seletor de arquivos do sistema, o evento Event.SELECT enviado. Se o mtodo FileReference.browse() for usado para selecionar um arquivo a ser carregado, o seguinte cdigo enviar o arquivo a um servidor Web:
var fileRef:FileReference = new FileReference(); fileRef.addEventListener(Event.SELECT, selectHandler); fileRef.addEventListener(Event.COMPLETE, completeHandler); try { var success:Boolean = fileRef.browse(); } catch (error:Error) { trace("Unable to browse for files."); } function selectHandler(event:Event):void { var request:URLRequest = new URLRequest("http://www.[yourdomain].com/fileUploadScript.cfm") try { fileRef.upload(request); } catch (error:Error) { trace("Unable to upload file."); } } function completeHandler(event:Event):void { trace("uploaded"); }

Voc pode enviar dados ao servidor com o mtodo FileReference.upload() usando as propriedades URLRequest.method e URLRequest.data para enviar variveis que usam os mtodos POST ou GET. Quando voc tenta carregar um arquivo usando o mtodo FileReference.upload(), os seguintes eventos so despachados:

Evento open (Event.OPEN): despachado quando uma operao de upload iniciada. Evento progress (ProgressEvent.PROGRESS): despachado periodicamente na medida em que os dados do
arquivo so carregados.

Evento complete (Event.COMPLETE): despachado quando a operao de upload concluda com sucesso. Evento httpStatus (HTTPStatusEvent.HTTP_STATUS): despachado quando h uma falha no processo de upload
devido a um erro HTTP.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

644

Evento httpResponseStatus (HTTPStatusEvent.HTTP_RESPONSE_STATUS): Despachado se uma chamada do

mtodo upload() ou uploadUnencoded() tentar acessar os dados atravs de HTTP e o Adobe AIR puder detectar e retornar o cdigo de status da solicitao.

Evento securityError (SecurityErrorEvent.SECURITY_ERROR): despachado quando h uma falha na

operao de upload devido a uma violao de segurana.

Evento uploadCompleteData (DataEvent.UPLOAD_COMPLETE_DATA): despachado quando os dados so

recebidos do servidor aps um upload bem-sucedido.

Evento ioError (IOErrorEvent.IO_ERROR): despachado se houver falha no processo de upload por qualquer um
dos seguintes motivos:

Ocorreu um erro de entrada/sada enquanto o Flash Player estava lendo, gravando ou transmitindo o arquivo. O SWF tentou carregar um arquivo para um servidor que requer autenticao (como um nome de usurio e
senha). Durante o upload, o Flash Player no fornece um meio para os usurios inserirem senhas.

O parmetro url contm um protocolo invlido. O mtodo FileReference.upload() deve usar HTTP ou
HTTPS. O Flash Player no oferece suporte completo para servidores que requerem autenticao. Apenas arquivos SWF que esto em execuo em um navegador que usa o plug-in do navegador ou o controle Microsoft ActiveX podem fornecer uma caixa de dilogo para solicitar que o usurio digite um nome de usurio e senha para autenticao e apenas para downloads. Ocorre falha na transferncia de arquivos, para uploads que usam o plug-in ou o controle ActiveX, ou upload/download que usa player autnomo ou externo. Para criar um script de servidor no ColdFusion para aceitar um upload de arquivo do Flash Player, voc pode usar um cdigo semelhante a este:
<cffile action="upload" filefield="Filedata" destination="#ExpandPath('./')#" nameconflict="OVERWRITE" />

Esse cdigo ColdFusion carrega o arquivo enviado pelo Flash Player e salva-o no mesmo diretrio que o modelo ColdFusion, substituindo qualquer arquivo com o mesmo nome. O cdigo anterior mostra a quantidade mnima bsica de cdigo necessria para aceitar um upload de arquivo. Esse script no deve ser usado em um ambiente de produo. Em condies ideais, adicione validao de dados para garantir que os usurios carreguem apenas tipos de arquivo aceitos, como uma imagem, em vez de um script do lado do servidor potencialmente perigoso. O cdigo a seguir demonstra uploads de arquivo usando PHP e inclui validao de dados. O script limita o nmero de arquivos carregados no diretrio de upload at 10, garante que o arquivo tenha menos do que 200 KB e permite que apenas arquivos JPEG, GIF ou PNG sejam carregados e salvos no sistema de arquivos.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

645

<?php $MAXIMUM_FILESIZE = 1024 * 200; // 200KB $MAXIMUM_FILE_COUNT = 10; // keep maximum 10 files on server echo exif_imagetype($_FILES['Filedata']); if ($_FILES['Filedata']['size'] <= $MAXIMUM_FILESIZE) { move_uploaded_file($_FILES['Filedata']['tmp_name'], "./temporary/".$_FILES['Filedata']['name']); $type = exif_imagetype("./temporary/".$_FILES['Filedata']['name']); if ($type == 1 || $type == 2 || $type == 3) { rename("./temporary/".$_FILES['Filedata']['name'], "./images/".$_FILES['Filedata']['name']); } else { unlink("./temporary/".$_FILES['Filedata']['name']); } } $directory = opendir('./images/'); $files = array(); while ($file = readdir($directory)) { array_push($files, array('./images/'.$file, filectime('./images/'.$file))); } usort($files, sorter); if (count($files) > $MAXIMUM_FILE_COUNT) { $files_to_delete = array_splice($files, 0, count($files) - $MAXIMUM_FILE_COUNT); for ($i = 0; $i < count($files_to_delete); $i++) { unlink($files_to_delete[$i][0]); } } print_r($files); closedir($directory); function sorter($a, $b) { if ($a[1] == $b[1]) { return 0; } else { return ($a[1] < $b[1]) ? -1 : 1; } } ?>

Voc pode transmitir variveis adicionais para o script de upload usando o mtodo de solicitao POST ou oGET. Para enviar variveis POST adicionais ao script de upload, use o seguinte cdigo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

646

var fileRef:FileReference = new FileReference(); fileRef.addEventListener(Event.SELECT, selectHandler); fileRef.addEventListener(Event.COMPLETE, completeHandler); fileRef.browse(); function selectHandler(event:Event):void { var params:URLVariables = new URLVariables(); params.date = new Date(); params.ssid = "94103-1394-2345"; var request:URLRequest = new URLRequest("http://www.yourdomain.com/FileReferenceUpload/fileupload.cfm"); request.method = URLRequestMethod.POST; request.data = params; fileRef.upload(request, "Custom1"); } function completeHandler(event:Event):void { trace("uploaded"); }

O exemplo anterior cria um objeto URLVariables que voc transmite para o script do lado do servidor remoto. Em verses anteriores do ActionScript, era possvel transmitir variveis para o script de upload de servidor transmitindo valores na string da consulta. O ActionScript 3.0 permite transmitir variveis para o script remoto usando um objeto URLRequest, o que permite que voc transmita dados usando o mtodo POST ou o GET. Isso, por sua vez, faz com que a transmisso de conjuntos de dados maiores seja mais fcil e mais limpa. Para especificar se a variveis so transmitidas usando o mtodo de solicitao GET ou POST, defina a propriedade URLRequest.method como URLRequestMethod.GET ou URLRequestMethod.POST, respectivamente. O ActionScript 3.0 tambm permite substituir o nome do campo do arquivo de upload Filedata padro fornecendo um segundo parmetro para o mtodo upload(), conforme demonstrado no exemplo anterior (que substituiu o valor padro Filedata por Custom1). Por padro, o Flash Player no tenta enviar um upload de teste, embora seja possvel substituir esse padro transmitindo um valor true como o terceiro parmetro para o mtodo upload(). A finalidade do upload de teste verificar se o upload do arquivo real ser bem-sucedido e se a autenticao do servidor, se necessria, ter xito. Nota: No momento, um upload de teste ocorre apenas em Flash Players com base no Windows. O script de servidor que manipula o upload do arquivo deve esperar uma solicitao POST HTTP com os seguintes elementos:

Content-Type com um valor de multipart/form-data. Content-Disposition com um atributo name definido como Filedata e um atributo filename definido como

o nome do arquivo original. possvel especificar um atributo name personalizado, transmitindo um valor para o parmetro uploadDataFieldName no mtodo FileReference.upload().

O contedo binrio do arquivo.

Esta uma solicitao POST HTTP de amostra:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

647

POST /handler.asp HTTP/1.1 Accept: text/* Content-Type: multipart/form-data; boundary=----------Ij5ae0ae0KM7GI3KM7ei4cH2ei4gL6 User-Agent: Shockwave Flash Host: www.mydomain.com Content-Length: 421 Connection: Keep-Alive Cache-Control: no-cache ------------Ij5ae0ae0KM7GI3KM7ei4cH2ei4gL6 Content-Disposition: form-data; name="Filename" sushi.jpg ------------Ij5ae0ae0KM7GI3KM7ei4cH2ei4gL6 Content-Disposition: form-data; name="Filedata"; filename="sushi.jpg" Content-Type: application/octet-stream Test File ------------Ij5ae0ae0KM7GI3KM7ei4cH2ei4gL6 Content-Disposition: form-data; name="Upload" Submit Query ------------Ij5ae0ae0KM7GI3KM7ei4cH2ei4gL6 (actual file data,,,)

A seguinte solicitao POST HTTP de amostra envia trs variveis POST: api_sig, api_key e auth_token e usa um valor de nome de campo de dados de upload personalizado de "photo":

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

648

POST /handler.asp HTTP/1.1 Accept: text/* Content-Type: multipart/form-data; boundary=----------Ij5ae0ae0KM7GI3KM7ei4cH2ei4gL6 User-Agent: Shockwave Flash Host: www.mydomain.com Content-Length: 421 Connection: Keep-Alive Cache-Control: no-cache ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7 Content-Disposition: form-data; name="Filename" sushi.jpg ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7 Content-Disposition: form-data; name="api_sig" XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7 Content-Disposition: form-data; name="api_key" XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7 Content-Disposition: form-data; name="auth_token" XXXXXXXXXXXXXXXXXXXXXXX ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7 Content-Disposition: form-data; name="photo"; filename="sushi.jpg" Content-Type: application/octet-stream (actual file data,,,) ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7 Content-Disposition: form-data; name="Upload" Submit Query ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7--

Download de arquivos de um servidor

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior possvel permitir que os usurios baixem arquivos de um servidor usando o mtodo FileReference.download() que utiliza dois parmetros: request e defaultFileName. O primeiro parmetro o objeto URLRequest que contm a URL do arquivo a ser baixado. O segundo parmetro opcional, ele permite especificar um nome de arquivo padro que aparece na caixa de dilogo do arquivo de download. Se voc omitir o segundo parmetro, defaultFileName, o nome de arquivo da URL especificada ser usado. O cdigo a seguir baixa um arquivo denominado index.xml do mesmo diretrio que o arquivo SWF:
var request:URLRequest = new URLRequest("index.xml"); var fileRef:FileReference = new FileReference(); fileRef.download(request);

Para definir o nome padro como currentnews.xml, em vez de index.xml, especifique o parmetro defaultFileName, conforme mostrado no seguinte snippet:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

649

var request:URLRequest = new URLRequest("index.xml"); var fileToDownload:FileReference = new FileReference(); fileToDownload.download(request, "currentnews.xml");

Renomear um arquivo poder ser til se o nome de arquivo do servidor no for intuitivo ou gerado pelo servidor. Tambm bom especificar explicitamente o parmetro defaultFileName ao baixar um arquivo usando um script do lado do servidor, em vez de baixar o arquivo diretamente. Por exemplo, voc precisa especificar o parmetro defaultFileName, se tiver um script do lado do servidor que baixe arquivos especficos com base em variveis de URL transmitidas para ele. Caso contrrio, o nome padro do arquivo baixado ser o nome do script do lado do servidor. Os dados podem ser enviados ao servidor usando o mtodo download() anexando parmetros URL para anlise pelo script do servidor. O seguinte snippet do ActionScript 3.0 baixa um documento com base em quais parmetros so transmitidos para um script ColdFusion:
package { import import import import import

flash.display.Sprite; flash.net.FileReference; flash.net.URLRequest; flash.net.URLRequestMethod; flash.net.URLVariables;

public class DownloadFileExample extends Sprite { private var fileToDownload:FileReference; public function DownloadFileExample() { var request:URLRequest = new URLRequest(); request.url = "http://www.[yourdomain].com/downloadfile.cfm"; request.method = URLRequestMethod.GET; request.data = new URLVariables("id=2"); fileToDownload = new FileReference(); try { fileToDownload.download(request, "file2.txt"); } catch (error:Error) { trace("Unable to download file."); } } } }

O cdigo a seguir demonstra o script ColdFusion, download.cfm, que baixa um de dois arquivos do servidor, dependendo do valor de uma varivel de URL:
<cfparam name="URL.id" default="1" /> <cfswitch expression="#URL.id#"> <cfcase value="2"> <cfcontent type="text/plain" file="#ExpandPath('two.txt')#" deletefile="No" /> </cfcase> <cfdefaultcase> <cfcontent type="text/plain" file="#ExpandPath('one.txt')#" deletefile="No" /> </cfdefaultcase> </cfswitch>

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

650

classe FileReferenceList
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe FileReferenceList permite que o usurio selecione um ou mais arquivos a serem carregados para um script do lado do servidor. O upload de arquivo manipulado pelo mtodo FileReference.upload() que deve ser chamado em cada arquivo selecionado pelo usurio. O cdigo a seguir cria dois objetos FileFilter (imageFilter e textFilter) e transmite-os em uma matriz para o mtodo FileReferenceList.browse(). Isso faz com que a caixa de dilogo de arquivo do sistema operacional exiba dois filtros possveis para tipos de arquivos.
var imageFilter:FileFilter = new FileFilter("Image Files (*.jpg, *.jpeg, *.gif, *.png)", "*.jpg; *.jpeg; *.gif; *.png"); var textFilter:FileFilter = new FileFilter("Text Files (*.txt, *.rtf)", "*.txt; *.rtf"); var fileRefList:FileReferenceList = new FileReferenceList(); try { var success:Boolean = fileRefList.browse(new Array(imageFilter, textFilter)); } catch (error:Error) { trace("Unable to browse for files."); }

Permitir que o usurio selecione e carregue um ou mais arquivos usando a classe FileReferenceList o mesmo que usar FileReference.browse() para selecionar arquivos, embora o FileReferenceList permita selecionar mais de um arquivo. O upload de vrios arquivos requer que voc carregue cada um dos arquivos selecionados usando FileReference.upload(), conforme mostrado no cdigo a seguir:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

651

var fileRefList:FileReferenceList = new FileReferenceList(); fileRefList.addEventListener(Event.SELECT, selectHandler); fileRefList.browse(); function selectHandler(event:Event):void { var request:URLRequest = new URLRequest("http://www.[yourdomain].com/fileUploadScript.cfm"); var file:FileReference; var files:FileReferenceList = FileReferenceList(event.target); var selectedFileArray:Array = files.fileList; for (var i:uint = 0; i < selectedFileArray.length; i++) { file = FileReference(selectedFileArray[i]); file.addEventListener(Event.COMPLETE, completeHandler); try { file.upload(request); } catch (error:Error) { trace("Unable to upload files."); } } } function completeHandler(event:Event):void { trace("uploaded"); }

Como o evento Event.COMPLETE adicionado a cada objeto FileReference individual na matriz, o Flash Player chama o mtodo completeHandler() quando o upload de cada arquivo individual concludo.

Usar a API do sistema de arquivos do AIR

Adobe AIR 1.0 e posterior A API do sistema de arquivos Adobe AIR inclui as seguintes classes:

Arquivo FileMode FileStream

A API do sistema de arquivos permite fazer o seguinte (e muito mais):

Copiar, criar, excluir e mover arquivos e diretrios Entrar de qualquer lugar em arquivos e diretrios Ler e gravar arquivos

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

652

Noes bsicas do arquivo AIR

Adobe AIR 1.0 e posterior Para ver uma explicao rpida e exemplos de cdigo para trabalhar com o sistema de arquivos no AIR, consulte os seguintes artigos de apresentao rpida do Adobe Developer Connection:

Criao de editor de arquivo de texto (Flash) Criao de editor de arquivo de texto (Flex) Criao de aplicativo de pesquisa em diretrio (Flex) Leitura e gravao de um arquivo de preferncias XML (Flex) Compactao de arquivos e dados (Flex)
O Adobe AIR oferece classes que voc pode usar para acessar, criar e gerenciar arquivos e pastas. Essas classes, contidas no pacote flash.filesystem, so usadas da seguinte forma:
Classes File File Descrio O objeto File representa um caminho para um arquivo ou um diretrio. Voc usa o objeto File para criar um indicador para um arquivo ou pasta, iniciando a interao com o arquivo ou a pasta. A classe FileMode define constantes de string usadas no parmetro fileMode dos mtodos open() e openAsync() da classe FileStream. O parmetro fileMode desses mtodos determina os recursos disponveis para o objeto FileStream depois que o arquivo aberto, o que inclui gravao, leitura, acrscimo e atualizao. FileStream O objeto FileStream usado para abrir arquivos de leitura e gravao. Depois que voc criar o objeto File apontando para um arquivo novo ou para um j existente, passe esse ponteiro para o objeto FileStream, de modo a poder abri-lo e, em seguida, manipular dados no arquivo.

FileMode

Alguns mtodos na classe File tm verses sncronas e assncronas:

File.copyTo() e File.copyToAsync() File.deleteDirectory() e File.deleteDirectoryAsync() File.deleteFile() e File.deleteFileAsync() File.getDirectoryListing() e File.getDirectoryListingAsync() File.moveTo() e File.moveToAsync() File.moveToTrash() e File.moveToTrashAsync()

Alm disso, as operaes FileStream funcionam sncrona ou assincronamente, dependendo de como o objeto FileStream abre o arquivo: chamando o mtodo open() ou o mtodo openAsync(). As verses assncronas permitem iniciar processos que so executados em segundo plano e despacham eventos quando concludos (ou quando ocorrerem eventos de erro). Outro cdigo pode ser executado enquanto esses processos de segundo plano assncronos esto ocorrendo. Nas verses assncronas das operaes, voc deve configurar funes do ouvinte de eventos, usando o mtodo addEventListener() do objeto File ou FileStream que chama a funo. As verses sncronas permitem escrever cdigos mais simples que no se baseiam na configurao de ouvintes de evento. No entanto, como nenhum outro cdigo pode ser executado enquanto o mtodo sincrnico est sendo executado, processos importantes, como renderizao e animao de objeto de exibio, podem ser retardados.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

653

Trabalho com objetos File no AIR

Adobe AIR 1.0 e posterior O objeto File um ponteiro para um arquivo ou diretrio no sistema de arquivos. A classe File estende a classe FileReference. A classe FileReference, disponvel no Adobe Flash Player, bem como no AIR, representa um ponteiro para um arquivo, mas a classe File adiciona propriedades e mtodos que no so expostos no Flash Player (em um SWF em execuo no navegador), devido a consideraes sobre segurana.

Sobre a classe File

Adobe AIR 1.0 e posterior Voc pode usar a classe File para o seguinte:

Obter o caminho para diretrios especiais, incluindo o diretrio do usurio, o diretrio de documentos do usurio,
o diretrio do qual o aplicativo foi iniciado e o diretrio de aplicativo.

Cpia de arquivos e diretrios Movimentao de arquivos e diretrios. Excluso de arquivos e diretrios (ou movimentao para a lixeira) Lista de arquivos e diretrios contidos em um diretrio Criao de arquivos e pastas temporrios
Depois que o objeto File aponta para um caminho de arquivo, voc pode us-lo para ler e gravar dados de arquivo, usando a classe FileStream. O objeto File pode apontar para o caminho de um arquivo ou diretrio que ainda no existe. Voc pode usar esse objeto File na criao de arquivos ou diretrios.

Caminhos de objetos File

Adobe AIR 1.0 e posterior Cada objeto File tem duas propriedades que definem cada uma o caminho do objeto:
Propriedade
nativePath

Descrio Especifica o caminho especfico de plataforma para um arquivo. Por exemplo, no Windows o caminho pode ser "c:\Sample directory\test.txt", enquanto no Mac OS pode ser "/Sample directory/test.txt". A propriedade nativePath usa o caractere de barra invertida (\) como o caractere separador de diretrio no Windows e o caractere de barra (/) no Mac OS e no Linux. Ela pode usar o esquema URL de arquivo para apontar para um arquivo. Por exemplo, no Windows o caminho pode ser "file:///c:/Sample%20directory/teste.txt", enquanto no Mac OS pode ser "file:///Sample%20directory/teste.txt". O tempo de execuo inclui outros esquemas especiais de URL alm de file e so descritos em Esquemas URL do AIR com suporte na pgina 662

url

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

654

A classe File inclui propriedades estticas de indicao de diretrios padro no Mac OS, no Windows e no Linux. Essas propriedades incluem:

File.applicationStorageDirectory um diretrio de armazenamento exclusivo para cada aplicativo AIR

instalado. Este diretrio um lugar apropriado para armazenar ativos dinmicos do aplicativo e preferncias do usurio. Considere o armazenamento de grandes volumes de dados em outro local. No Android, o diretrio de armazenamento do aplicativo removido quando o aplicativo desinstalado ou o usurio opta por limpar os dados do aplicativo, mas isso no ocorre em outras plataformas.

File.applicationDirectory o diretrio em que o aplicativo est instalado (junto com quaisquer ativos instalados). Em alguns sistemas operacionais, o aplicativo armazenado em um nico arquivo de pacote e no em um diretrio fsico. Nesse caso, o contedo pode no ficar acessvel por meio do caminho nativo. O diretrio do aplicativo somente leitura. File.desktopDirectory o diretrio de rea de trabalho do usurio. Se a plataforma no definir um diretrio

de rea de trabalho, ser usado outro local no sistema de arquivos.

File.documentsDirectory o diretrio de documentos do usurio. Se a plataforma no definir um diretrio de documentos, ser usado outro local no sistema de arquivo. File.userDirectory o diretrio do usurio. Se a plataforma no definir um diretrio do usurio, ser usado

outro local no sistema de arquivo. Nota: Quando a plataforma no definir locais padro para os diretrios de rea de trabalho, de documentos ou do usurio, File.documentsDirectory, File.desktopDirectory e File.userDirectory podem fazer referncia ao mesmo diretrio. Estas propriedades tm valores diferentes em diferentes sistemas operacionais. Por exemplo, o Mac e o Windows tm caminhos nativos diferentes para o diretrio de rea de trabalho do usurio. Entretanto, a propriedade File.desktopDirectory aponta para um caminho de diretrio apropriado em cada plataforma. Para gravar aplicativos que funcionam bem em vrias plataformas, use essas propriedades como base para fazer referncia a outros diretrios e arquivos usados pelo aplicativo. Use o mtodo resolvePath() para refinar o caminho. Por exemplo, esse cdigo aponta para o arquivo preferences.xml no diretrio de armazenamento do aplicativo:
var prefsFile:File = File.applicationStorageDirectory; prefsFile = prefsFile.resolvePath("preferences.xml");

Embora a classe File permita apontar para um caminho especfico de arquivo, fazer isso pode levar a aplicativos que no funcionam em vrias plataformas. Por exemplo, o caminho C:\Documents and Settings\joe\ s funciona no Windows. Por essas razes, melhor usar as propriedades estticas da classe File, como File.documentsDirectory.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

655

Locais de diretrios comuns

Plataform Tipo de diretrio a Android Aplicativo Armazenamento do aplicativo rea de trabalho Documentos Temporrio Usurio iOS Aplicativo Armazenamento do aplicativo rea de trabalho Documentos Temporrio Usurio Linux Aplicativo Armazenamento do aplicativo rea de trabalho Documentos Temporrio Usurio Mac Aplicativo Armazenamento do aplicativo rea de trabalho Documentos Temporrio Usurio Windows Aplicativo Armazenamento do aplicativo rea de trabalho Documentos Temporrio Local tpico do sistema de arquivos

/data/data/ /data/data/air.applicationID/filename/Local Store

/mnt/sdcard /mnt/sdcard /data/data/applicationID/cache/FlashTmp.randomString /mnt/sdcard /var/mobile/Applications/uid/filename.app /var/mobile/Applications/uid/Library/Application Support/applicationID/Local Store

no acessvel no acessvel
/private/var/mobile/Applications/uid/tmp/FlashTmpNNN

no acessvel
/opt/filename/share /home/userName/.appdata/applicationID/Local Store

/home/userName/Desktop /home/userName/Documents /tmp/FlashTmp.randomString /home/userName /Applications/filename.app/Contents/Resources /Users/userName/Library/Preferences/applicationID/Local Store

/Users/userName/Desktop /Users/userName/Documents /private/var/folders/JY/randomString/TemporaryItems/FlashTmp /Users/userName C:\Arquivos de programa\filename C:\Documents and settings\userName\ApplicationData\applicationID\Local Store C:\Documents and settings\userName\rea de trabalho C:\Documents and settings\userName\Meus documentos C:\Documents and settings\userName\Configuraes locais\Temp\randomString.tmp C:\Documents and settings\userName

Usurio

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

656

Os caminhos nativos reais desses diretrios variam com base no sistema operacional e na configurao do computador. Os caminhos mostrados nesta tabela so exemplos tpicos. Voc deve sempre usar as propriedades estticas apropriadas da classe File para fazer referncia a esses diretrios, de modo que o seu aplicativo funcione corretamente em qualquer plataforma. No aplicativo AIR real, os valores de applicationID e filename mostrados na tabela so obtidos do descritor do aplicativo. Se voc especificar uma ID de editor no descritor do aplicativo, a ID de editor ser anexada ID do aplicativo nesses caminhos. O valor de userName o nome da conta do usurio que faz a instalao.

Visualizao de diretrios para aplicativos AIR for TV

Para assegurar a segurana dos arquivos de sistema em dispositivos AIR for TV, um aplicativo AIR pode acessar somente um limitado conjunto de diretrios. O AIR for TV probe que o aplicativo acesse qualquer outro diretrio. Alm disso, o AIR for TV isola os dados especficos a cada usurio de cada aplicativo AIR. O aplicativo AIR usa nomes de diretrio para uso exclusivo do ActionScript 3.0. Esses nomes no representam diretrios reais no dispositivo. O AIR for TV mapeia esses nomes de diretrio do ActionScript 3.0 para diretrios reais no dispositivo. Esse mapeamento protege aplicativos AIR for TV contra o acesso mal-intencionado ou inadvertido aos arquivos locais que no pertenam a eles. Os nomes de diretrio do ActionScript 3.0 so:
/app/ O diretrio somente leitura do aplicativo para o aplicativo AIR em execuo. /app-storage/ O diretrio de armazenamento do aplicativo de leitura e gravao para o aplicativo AIR em execuo. /Home/ O diretrio de usurio para leitura e gravao. /tmp/ O diretrio temporrio de leitura e gravao do aplicativo AIR em execuo. /volumes/ O diretrio somente leitura que contm zero ou mais subdiretrios somente leitura que representam volumes montados.

Se um aplicativo tentar acessar um diretrio proibido, o tempo de execuo lana uma exceo que pode ser detectada pelo cdigo ActionScript. A tabela a seguir mostra o valor de File.nativePath de vrias propriedades e mtodos de File. Os valores refletem a visualizao limitada do aplicativo do sistema de arquivos do dispositivo.
Propriedade ou mtodo File Valor de
File.nativePat h applicationDirectory applicationStorageDirectory /app/ /app-storage/

Informaes de mapeamento

Mapeia para um diretrio especfico ao aplicativo. Mapas para o diretrio especfico ao aplicativo em um diretrio especfico ao usurio. Mapas para o diretrio especfico ao aplicativo em um diretrio especfico ao usurio. O mesmo diretrio de userDirectory e documentsDirectory. Mapas para o diretrio especfico ao aplicativo em um diretrio especfico ao usurio. O mesmo diretrio de desktopDirectory e documentsDirectory. Mapas para o diretrio especfico ao aplicativo em um diretrio especfico ao usurio. O mesmo diretrio de userDirectory e desktopDirectory. Mapeia para um diretrio temporrio. O AIR for TV exclui este diretrio e seu contedo quando o aplicativo AIR exite.

desktopDirectory

/Home/

userDirectory

/Home/

documentsDirectory

/Home/

createTempDirectory()

/tmp/

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

657

Considere tambm o comportamento dos seguintes mtodos em dispositivos AIR for TV:

File.createTempFile() cria um arquivo no diretrio /tmp/. File.getRootDirectories()retorna uma matriz com um objeto File. A propriedade nativePath do objeto File tem o valor /. Este diretrio raiz contm os diretrios app, app-storage, home e tmp. StorageVolumeInfo.storageVolumeInfo.getStorageVolumes() retorna um vetor de objetos StorageVolume. A propridade rootDirectory de cada objeto StorageVolume um objeto File. O valor de nativePath do objeto File comea com /volumes/. Todos os aplicativos e usurios tm acesso ao diretrio /volumes/.

Como apontar um objeto File para um diretrio

Adobe AIR 1.0 e posterior H maneiras diferentes de configurar o objeto File para apontar para um diretrio. Apontar para o diretrio inicial do usurio Adobe AIR 1.0 e posterior Voc pode apontar o objeto File para o diretrio inicial do usurio. O cdigo a seguir configura o objeto File para apontar para o subdiretrio AIR Test do diretrio inicial:
var file:File = File.userDirectory.resolvePath("AIR Test");

Apontar para o diretrio documentos do usurio Adobe AIR 1.0 e posterior Voc pode apontar o objeto File para o diretrio documentos do usurio. O cdigo a seguir configura o objeto File para apontar para o subdiretrio AIR Test do diretrio documentos:
var file:File = File.documentsDirectory.resolvePath("AIR Test");

Apontar para o diretrio da rea de trabalho Adobe AIR 1.0 e posterior Voc pode apontar o objeto File para a rea de trabalho. O cdigo a seguir configura o objeto File para apontar para o subdiretrio AIR Test da rea de trabalho:
var file:File = File.desktopDirectory.resolvePath("AIR Test");

Apontar para o diretrio de armazenamento do aplicativo Adobe AIR 1.0 e posterior Voc pode apontar o objeto File para o diretrio de armazenamento do aplicativo. Para cada aplicativo AIR, h um caminho associado exclusivo que define o diretrio de armazenamento do aplicativo. Esse diretrio exclusivo de cada aplicativo e usurio. Voc pode usar esse diretrio para armazenar dados especficos do usurio e do aplicativo (como dados do usurio ou arquivos de preferncias). Por exemplo, o cdigo a seguir aponta o objeto File para um arquivo de preferncias, prefs.xml, contido no diretrio de armazenamento do aplicativo:
var file:File = File.applicationStorageDirectory; file = file.resolvePath("prefs.xml");

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

658

Normalmente, o local do diretrio de armazenamento do aplicativo tem base no nome do usurio e no ID do aplicativo. Os seguintes locais no sistema de arquivos so fornecidos aqui para ajudar a depurar o aplicativo. Voc deve sempre usar a propriedade File.applicationStorage ou o esquema de URI app-storage: para resolver arquivos nesse diretrio:

No Mac OS, em:

/Users/user name/Library/Preferences/applicationID/Local Store/

Por exemplo:
/Users/babbage/Library/Preferences/com.example.TestApp/Local Store

No Windows: no diretrio Documents and Settings, em:

C:\Documents and Settings\user name\Application Data\applicationID\Local Store\ Por exemplo:
C:\Documents and Settings\babbage\Application Data\com.example.TestApp\Local Store

No Linux - In:
/home/user name/.appdata/applicationID/Local Store/

Por exemplo:
/home/babbage/.appdata/com.example.TestApp/Local Store

No Android Em:
/data/data/androidPackageID/applicationID/Local Store Por exemplo:
/data/data/air.com.example.TestApp/com.example.TestApp/Local Store

Em dispositivos AIR for TV, o local descrito em Visualizao de diretrios para aplicativos AIR for TV na
pgina 656. Nota: Se um aplicativo possuir um ID de publicao, o ID de publicao tambm utilizado como parte do caminho do diretrio de armazenamento do aplicativo. A URL (e a propriedade url) de um objeto File criado com File.applicationStorageDirectory usa o esquema de URL app-storage (consulte Esquemas URL do AIR com suporte na pgina 662), como a seguir:
var dir:File = File.applicationStorageDirectory; dir = dir.resolvePath("preferences"); trace(dir.url); // app-storage:/preferences

Apontar para o diretrio do aplicativo Adobe AIR 1.0 e posterior Voc pode apontar o objeto File para o diretrio em que o aplicativo foi instalado, conhecido como o diretrio do aplicativo. Voc pode fazer referncia a esse diretrio, usando a propriedade File.applicationDirectory. Voc pode usar esse diretrio para examinar o arquivo do descritor do aplicativo ou outros recursos instalados com o aplicativo. Por exemplo, o cdigo a seguir aponta o objeto File para um diretrio chamado images no diretrio do aplicativo:
var dir:File = File.applicationDirectory; dir = dir.resolvePath("images");

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

659

A URL (e propriedade url) de um objeto File criado com File.applicationDirectory usa o esquema de URL app (consulte Esquemas URL do AIR com suporte na pgina 662), como a seguir:
var dir:File = File.applicationDirectory; dir = dir.resolvePath("images"); trace(dir.url); // app:/images

Nota: No Android, os arquivos no pacote de aplicativos no ficam acessveis pelo nativePath. A propriedade nativePath uma string vazia. Use sempre o URL para acessar arquivos no diretrio do aplicativo em vez de usar um caminho nativo. Apontando para a raiz do sistema de arquivos Adobe AIR 1.0 e posterior O mtodo File.getRootDirectories() lista todos os volumes de raiz, como C: e volumes montados em um computador Windows. No Mac OS e no Linux, esse mtodo sempre retorna o diretrio raiz exclusivo do computador (o diretrio "/"). O mtodo StorageVolumeInfo.getStorageVolumes() fornece informaes mais detalhadas sobre os volumes montados de armazenamento (consulte Trabalho com volumes de armazenamento na pgina 673). Nota: A raiz do sistema de arquivos no legvel no Android. Um objeto File que faz referncia ao diretrio com o caminho nativo / retornado, mas as propriedades do objeto no tm valores precisos. Por exemplo, spaceAvailable sempre 0. Como apontar para um diretrio explcito Adobe AIR 1.0 e posterior Voc pode apontar o objeto File para um diretrio explcito, definindo a propriedade nativePath do objeto File, conforme o seguinte exemplo (no Windows):
var file:File = new File(); file.nativePath = "C:\\AIR Test";

Importante: apontar para um caminho explcito dessa forma pode levar a um cdigo que no funciona em vrias plataformas. Por exemplo, o exemplo anterior s funciona no Windows. Voc pode usar as propriedades estticas do objeto File, como File.applicationStorageDirectory, para localizar um diretrio que funciona em vrias plataformas. Use o mtodo resolvePath() (consulte a prxima seo) para ir at um caminho relativo. Navegao para caminhos relativos Adobe AIR 1.0 e posterior Voc pode usar o mtodo resolvePath() para obter um caminho relativo a outro caminho determinado. Por exemplo, o cdigo a seguir configura o objeto File para apontar para o subdiretrio "AIR Test" do diretrio inicial do usurio:
var file:File = File.userDirectory; file = file.resolvePath("AIR Test");

Voc tambm pode usar a propriedade url do objeto File para apontar para um diretrio com base em uma seqncia de URL, conforme segue:
var urlStr:String = "file:///C:/AIR Test/"; var file:File = new File() file.url = urlStr;

Para obter mais informaes, consulte Modificao de caminhos do File na pgina 662.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

660

Permisso para que o usurio navegue para selecionar um diretrio Adobe AIR 1.0 e posterior A classe File inclui o mtodo browseForDirectory(), que apresenta uma caixa de dilogo de sistema na qual o usurio pode selecionar um diretrio para atribuir ao objeto. O mtodo browseForDirectory() assncrono. O objeto File despachar um evento select se o usurio selecionar um diretrio e clicar no boto Abrir ou despachar um evento cancel se o usurio clicar no boto Cancelar. Por exemplo, o cdigo a seguir permite que o usurio selecione um diretrio e fornece o caminho do diretrio na seleo:
var file:File = new File(); file.addEventListener(Event.SELECT, dirSelected); file.browseForDirectory("Select a directory"); function dirSelected(e:Event):void { trace(file.nativePath); }

Nota: No Android, no h suporte para o mtodo browseForDirectory(). Chamar esse mtodo no tem nenhum efeito. Um evento cancel despachado imediatamente. Em vez disso, para permitir que os usurios selecionem um diretrio, preciso usar uma caixa de dilogo personalizada definida pelo aplicativo. Como apontar para o diretrio do qual o aplicativo foi chamado Adobe AIR 1.0 e posterior Voc pode obter a localizao do diretrio do qual o aplicativo foi chamado, marcando a propriedade currentDirectory do objeto InvokeEvent despachada quando o aplicativo chamado. Para obter detalhes, consulteCaptura de argumentos de linha de comando na pgina 862.

Como apontar um objeto File para um arquivo

Adobe AIR 1.0 e posterior H maneiras diferentes de definir o arquivo para o qual o objeto File aponta. Apontar para um caminho de arquivo explcito Adobe AIR 1.0 e posterior Importante: apontar para um caminho explcito pode levar a um cdigo que no funciona em vrias plataformas. Por exemplo, o caminho C:/foo.txt s funciona no Windows. Voc pode usar as propriedades estticas do objeto File, como File.applicationStorageDirectory, para localizar um diretrio que funciona em vrias plataformas. Use o mtodo resolvePath() (consulte Modificao de caminhos do File na pgina 662 para ir at um caminho relativo. Voc pode usar a propriedade url do objeto File para apont-lo para um arquivo ou diretrio com base em uma seqncia de URL, conforme segue:
var urlStr:String = "file:///C:/AIR Test/test.txt"; var file:File = new File() file.url = urlStr;

Voc tambm pode passar a URL para a funo de construtor File(), como no seguinte:
var urlStr:String = "file:///C:/AIR Test/test.txt"; var file:File = new File(urlStr);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

661

A propriedade url sempre retorna a verso codificada de URI da URL (por exemplo, espaos em branco so substitudos por "%20):
file.url = "file:///c:/AIR Test"; trace(file.url); // file:///c:/AIR%20Test

Voc tambm pode usar a propriedade nativePath do objeto File para definir um caminho explcito. Por exemplo, o cdigo a seguir, quando executado em um computador com o Windows, define um objeto File para o arquivo test.txt no subdiretrio AIR Test da unidade C:
var file:File = new File(); file.nativePath = "C:/AIR Test/test.txt";

Voc tambm pode passar esse caminho para a funo de construtor File(), como no seguinte:
var file:File = new File("C:/AIR Test/test.txt");

Use o caractere barra (/) como o delimitador de caminho para a propriedade nativePath. No Windows, voc tambm pode usar o caractere de barra invertida (\), mas fazer isso leva a aplicativos que no funcionam em vrias plataformas. Para obter mais informaes, consulte Modificao de caminhos do File na pgina 662. Enumerao de arquivos em um diretrio Adobe AIR 1.0 e posterior Voc pode usar o mtodo getDirectoryListing() do objeto File para obter uma matriz de objetos File apontando para arquivos e subdiretrios no nvel raiz de um diretrio. Para obter mais informaes, consulte Enumerao de diretrios na pgina 668. Permisso para que o usurio navegue para selecionar um arquivo Adobe AIR 1.0 e posterior A classe File inclui os seguintes mtodos que apresentam uma caixa de dilogo de sistema na qual o usurio pode selecionar um arquivo para atribuir ao objeto:

browseForOpen() browseForSave() browseForOpenMultiple()

Cada um desses mtodos assncrono. Os mtodos browseForOpen() e browseForSave() despacham o evento select quando o usurio seleciona um arquivo (ou caminho de destino, no caso de browseForSave()). Com os mtodos browseForOpen() e browseForSave(), na seleo, o objeto File de destino aponta para os arquivos selecionados. O mtodo browseForOpenMultiple() despacha um evento selectMultiple quando o usurio seleciona arquivos. O evento selectMultiple do tipo FileListEvent, que tem a propriedade files, que uma matriz de objetos File (apontando para os arquivos selecionados). Por exemplo, o cdigo a seguir apresenta para o usurio a caixa de dilogo "Abrir", na qual possvel selecionar um arquivo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

662

var fileToOpen:File = File.documentsDirectory; selectTextFile(fileToOpen); function selectTextFile(root:File):void { var txtFilter:FileFilter = new FileFilter("Text", "*.as;*.css;*.html;*.txt;*.xml"); root.browseForOpen("Open", [txtFilter]); root.addEventListener(Event.SELECT, fileSelected); } function fileSelected(event:Event):void { trace(fileToOpen.nativePath); }

Se o aplicativo tiver outra caixa de dilogo de navegao aberta quando voc chamar o mtodo de navegao, o tempo de execuo emitir uma exceo Erro. Nota: No Android, somente arquivos de imagem, vdeo e udio podem ser selecionados com os mtodos browseForOpen() e browseForOpenMultiple(). A caixa de dilogo browseForSave() tambm exibe somente arquivos de mdia, embora o usurio possa digitar um nome de arquivo arbitrariamente. Para abrir e salvar arquivos que no sejam de mdia, considere o uso de caixas de dilogo personalizadas em vez desses mtodos.

Modificao de caminhos do File

Adobe AIR 1.0 e posterior Voc tambm pode modificar o caminho de um objeto File existente, chamando o mtodo resolvePath() ou modificando a propriedade nativePath ou url do objeto, conforme nos exemplos a seguir (no Windows):
var file1:File = File.documentsDirectory; file1 = file1.resolvePath("AIR Test"); trace(file1.nativePath); // C:\Documents and Settings\userName\My Documents\AIR Test var file2:File = File.documentsDirectory; file2 = file2.resolvePath(".."); trace(file2.nativePath); // C:\Documents and Settings\userName var file3:File = File.documentsDirectory; file3.nativePath += "/subdirectory"; trace(file3.nativePath); // C:\Documents and Settings\userName\My Documents\subdirectory var file4:File = new File(); file4.url = "file:///c:/AIR Test/test.txt"; trace(file4.nativePath); // C:\AIR Test\test.txt

Ao usar a propriedade nativePath, use o caractere de barra invertida (/) como caractere de separao de diretrio. No Windows, voc tambm pode usar o caractere de barra invertida (\), mas voc no deve fazer isso, pois ele leva a um cdigo que no funciona em vrias plataformas.

Esquemas URL do AIR com suporte

Adobe AIR 1.0 e posterior No AIR, voc pode usar qualquer um dos seguintes esquemas URL na definio da propriedade url de um objeto File:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

663

esquema de URL arquivo

Descrio Use para especificar um caminho relativo raiz do sistema de arquivos. Por exemplo:
file:///c:/AIR Test/test.txt

A URL padro especifica se a URL de arquivo usa a forma file://<host>/<path>. Como um caso especial, <host> pode ser a string vazia, que interpretada como "a mquina a partir da qual a URL est sendo interpretada." Por essa razo, as URLs de arquivo normalmente tm trs barras (///). app Use para especificar um caminho relativo ao diretrio raiz do aplicativo instalado (o diretrio que contm o arquivo application.xml do aplicativo instalado). Por exemplo, o caminho a seguir aponta para um subdiretrio de imagens do diretrio do aplicativo instalado:
app:/images

app-storage

Use para especificar um caminho relativo ao diretrio de armazenamento do aplicativo. Para cada aplicativo instalado, o AIR define um diretrio exclusivo de armazenamento do aplicativo, que um local til para armazenar dados especficos desse aplicativo. Por exemplo, o caminho a seguir aponta para o arquivo prefs.xml em um subdiretrio de configuraes do diretrio de armazenamento do aplicativo:
app-storage:/settings/prefs.xml

Localizao do caminho relativo entre dois arquivos

Adobe AIR 1.0 e posterior Voc pode usar o mtodo getRelativePath() para localizar o caminho relativo entre dois arquivos:
var file1:File = File.documentsDirectory.resolvePath("AIR Test"); var file2:File = File.documentsDirectory file2 = file2.resolvePath("AIR Test/bob/test.txt"); trace(file1.getRelativePath(file2)); // bob/test.txt

O segundo parmetro do mtodo getRelativePath(), o parmetro useDotDot, permite que a sintaxe .... seja retornada nos resultados, para indicar diretrios pai:
var file1:File = File.documentsDirectory; file1 = file1.resolvePath("AIR Test"); var file2:File = File.documentsDirectory; file2 = file2.resolvePath("AIR Test/bob/test.txt"); var file3:File = File.documentsDirectory; file3 = file3.resolvePath("AIR Test/susan/test.txt"); trace(file2.getRelativePath(file1, true)); // ../.. trace(file3.getRelativePath(file2, true)); // ../../bob/test.txt

Obteno de verses cannicas de nomes de arquivo

Adobe AIR 1.0 e posterior No Windows e no Mac OS, os nomes e caminhos de arquivo no fazem distino entre letras maisculas e minsculas. No exemplo a seguir, dois objetos File apontam para o mesmo arquivo:
File.documentsDirectory.resolvePath("test.txt"); File.documentsDirectory.resolvePath("TeSt.TxT");

No entanto, nomes de documentos e de diretrios incluem o uso de maisculas e minsculas. Por exemplo, o seguinte assume que h uma pasta com nome AIR Test no diretrio de documentos, como nos exemplos a seguir:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

664

var file:File = File.documentsDirectory.resolvePath("AIR test"); trace(file.nativePath); // ... AIR test file.canonicalize(); trace(file.nativePath); // ... AIR Test

O mtodo canonicalize() converte o objeto nativePath para usar maisculas e minsculas corretas para o nome de arquivo ou de diretrio. Em sistemas de arquivo que fazem distino entre maisculas e minsculas (como Linux), quando vrios arquivos possuem nomes cuja distino somente a letra maiscula ou minscula, o mtodo canonicalize() ajusta o caminho para que corresponda ao primeiro arquivo encontrado (em uma ordem determinada pelo sistema de arquivos). Voc tambm pode usar o mtodo canonicalize() para converter nomes de arquivos pequenos (nomes "8,3") em nomes de arquivos longos do Windows, como nos exemplos seguintes:
var path:File = new File(); path.nativePath = "C:\\AIR~1"; path.canonicalize(); trace(path.nativePath); // C:\AIR Test

Trabalho com pacotes e links simblicos

Adobe AIR 1.0 e posterior Vrios sistemas operacionais oferecem suporte a arquivos de pacote e arquivos de link simblico: Pacotes No Mac OS, os diretrios podem ser designados como pacotes e mostrados no Finder do Mac OS como um arquivo nico, em vez de um diretrio. Links simblicos O Mac OS, o Linux e o Windows Vista oferecem suporte a links simblicos. Os links simblicos permitem que um arquivo aponte para outro arquivo ou diretrio no disco. Embora semelhantes, os links simblicos no so o mesmo que alias. O alias sempre reportado como arquivo (em vez de diretrio), e ler ou gravar em um alias ou atalho nunca afeta o diretrio ou arquivo original para o qual ele aponta. Por outro lado, o link simblico se comporta exatamente como o arquivo ou diretrio para o qual aponta. Ele pode ser reportado como um arquivo ou diretrio, e ler ou gravar em um link simblico afetar o arquivo ou diretrio para o qual ele aponta, no o link simblico propriamente dito. Alm disso, no Windows, a propriedade isSymbolicLink de um objeto File que faa referncia a um ponto de juno (usado no sistema de arquivos NTFS) definida como true. A classe File inclui as propriedades isPackage e isSymbolicLink para verificar se o objeto File faz referncia a um pacote ou link simblico. O cdigo a seguir percorre o diretrio da rea de trabalho do usurio, listando subdiretrios que no sejam pacotes:
var desktopNodes:Array = File.desktopDirectory.getDirectoryListing(); for (var i:uint = 0; i < desktopNodes.length; i++) { if (desktopNodes[i].isDirectory && !!desktopNodes[i].isPackage) { trace(desktopNodes[i].name); } }

O cdigo a seguir percorre o diretrio da rea de trabalho do usurio, listando arquivos e diretrios que no sejam links simblicos:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

665

var desktopNodes:Array = File.desktopDirectory.getDirectoryListing(); for (var i:uint = 0; i < desktopNodes.length; i++) { if (!desktopNodes[i].isSymbolicLink) { trace(desktopNodes[i].name); } }

O mtodo canonicalize() altera o caminho do link simblico para apontar para o arquivo ou diretrio ao qual o link se refere. O cdigo a seguir percorre o diretrio da rea de trabalho do usurio e relata os caminhos referenciados pelos arquivos que sejam links simblicos:
var desktopNodes:Array = File.desktopDirectory.getDirectoryListing(); for (var i:uint = 0; i < desktopNodes.length; i++) { if (desktopNodes[i].isSymbolicLink) { var linkNode:File = desktopNodes[i] as File; linkNode.canonicalize(); trace(linkNode.nativePath); } }

Determinao de espao disponvel em um volume

Adobe AIR 1.0 e posterior A propriedade spaceAvailable do objeto File o espao disponvel para uso no local do File, em bytes. Por exemplo, o cdigo a seguir verifica o espao disponvel no diretrio de armazenamento do aplicativo:
trace(File.applicationStorageDirectory.spaceAvailable);

Se o objeto File fizer referncia a um diretrio, a propriedade spaceAvailable indicar o espao no diretrio que os arquivos podem usar. Se o objeto File fizer referncia a um arquivo, a propriedade spaceAvailable indicar o espao no qual o arquivo poder crescer. Se o local do arquivo no existir, a propriedade spaceAvailable ser definida como 0. Se o objeto File fizer referncia a um link simblico, a propriedade spaceAvailable ser definida como espao disponvel no local para o qual o link simblico aponta. Geralmente o espao disponvel para um diretrio ou arquivo igual ao espao disponvel no volume que contm o diretrio ou o arquivo. No entanto, o espao disponvel pode levar em conta limites por cotas e por diretrio. A adio de um arquivo ou diretrio a um volume geralmente requer mais espao que o tamanho real do arquivo ou o tamanho do contedo do diretrio. Por exemplo, o sistema operacional pode exigir mais espao para armazenar informaes sobre ndice. Ou os setores de disco necessrios podem usar espao adicional. Alm disso, o espao disponvel muda dinamicamente. Dessa forma, voc no poder alocar todo o espao informado para o armazenamento de arquivos. Para obter informaes sobre como gravar no sistema de arquivos, consulteLeitura e gravao de arquivos na pgina 674. O mtodo StorageVolumeInfo.getStorageVolumes() fornece informaes mais detalhadas sobre os volumes montados de armazenamento (consulte Trabalho com volumes de armazenamento na pgina 673).

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

666

Abertura de arquivos com o aplicativo padro do sistema

Adobe AIR 2 e posterior No AIR 2, voc pode abrir um arquivo usando o aplicativo registrado pelo sistema operacional para abri-lo. Por exemplo, um aplicativo AIR pode abrir um arquivo DOC com o aplicativo registrado para abri-lo. Utilize o mtodo openWithDefaultApplication() de um objeto File para abrir o arquivo. Por exemplo, o cdigo a seguir abre um arquivo chamado test.doc no computador do usurio e abre-o com o aplicativo padro para os arquivos DOC:
var file:File = File.deskopDirectory; file = file.resolvePath("test.doc"); file.openWithDefaultApplication();

Nota: No Linux, o tipo MIME do arquivo, no a extenso do nome de arquivo, determina o aplicativo padro para um arquivo. O cdigo a seguir permite que o usurio navegue at um arquivo mp3 e abra-o no aplicativo padro para reproduzir arquivos mp3:
var file:File = File.documentsDirectory; var mp3Filter:FileFilter = new FileFilter("MP3 Files", "*.mp3"); file.browseForOpen("Open", [mp3Filter]); file.addEventListener(Event.SELECT, fileSelected); function fileSelected(e:Event):void { file.openWithDefaultApplication(); }

Voc no pode usar o mtodo openWithDefaultApplication() com arquivos localizados no diretrio do aplicativo. O AIR impede que voc use o mtodo openWithDefaultApplication() para abrir certos arquivos. No Windows, o AIR impede que voc abra os arquivos que tm certos tipos de arquivos, como EXE ou BAT. No Mac OS, o AIR impede que voc abra arquivos que sero lanados em certos aplicativos. (Incluindo Terminal e AppletLauncher no Mac OS, e csh, bash ou ruby no Linux). Tentar abrir um desses arquivos que usam o mtodo openWithDefaultApplication() resulta em uma exceo. Para ver uma lista completa dos tipos de arquivo impedidos, consulte a entrada de referncia de linguagem para o mtodo File.openWithDefaultApplication(). Nota: Essa limitao no existe para um aplicativo do AIR instalado com um instalador nativo (um aplicativo de desktop expandido).

Obteno de informaes sobre o sistema de arquivos

Adobe AIR 1.0 e posterior A classe File inclui as seguintes propriedades estticas que apresentam algumas informaes teis sobre o sistema de arquivos:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

667

Propriedade
File.lineEnding

Descrio A seqncia de caracteres de final de linha usada pelo sistema operacional de hospedagem. No Mac OS e no Linux, ele o caractere de alimentao de linha. No Windows, esse o caractere de retorno de carro seguido pelo caractere de alimentao de linha. O caractere separador de componente do caminho do sistema operacional de hospedagem. No Mac OS e no Linux, ele o caractere de barra (/). No Windows, ele o caractere de barra invertida (\). A codificao padro usada em arquivos pelo sistema operacional de hospedagem. Ela pertence ao conjunto de caracteres usado pelo sistema operacional, correspondente ao respectivo idioma.

File.separator

File.systemCharset

A classe Capabilities tambm inclui informaes teis sobre o sistema, que podem ser valiosas ao trabalhar com arquivos:
Propriedade Capabilities.hasIME Descrio Especifica se o player est sendo executado em um sistema que possui (true) ou no possui (false) um IME (editor de mtodos de entrada) instalado. Especifica o cdigo de idioma do sistema no qual o player est sendo executado. Especifica o sistema operacional atual.

Capabilities.language Capabilities.os

Nota: Tenha cuidado ao usar Capabilities.os para determinar as caractersticas do sistema. Se existir uma propriedade mais especfica para determinar a caracterstica de um sistema, use-a. Do contrrio, voc corre o risco de gravar cdigo que no funciona corretamente em todas as plataformas. Por exemplo, considere o seguinte cdigo:
var separator:String; if (Capablities.os.indexOf("Mac") > -1) { separator = "/"; } else { separator = "\\"; }

Esse cdigo leva a problemas no Linux. melhor usar simplesmente a propriedade File.separator.

Trabalho com diretrios

Adobe AIR 1.0 e posterior O tempo de execuo oferece a voc recursos para trabalhar com diretrios no sistema de arquivos local. Para obter detalhes sobre a criao de objetos File que apontam para diretrios, consulte Como apontar um objeto File para um diretrio na pgina 657.

Criao de diretrios
Adobe AIR 1.0 e posterior O mtodo File.createDirectory() permite criar um diretrio. Por exemplo, o cdigo a seguir cria um diretrio com nome AIR Test como um subdiretrio do diretrio inicial do usurio:
var dir:File = File.userDirectory.resolvePath("AIR Test"); dir.createDirectory();

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

668

Se o diretrio existir, o mtodo createDirectory() no faz nada. Alm disso, em alguns modos, o objeto FileStream cria diretrios ao abrir arquivos. Diretrios ausentes so criados quando voc cria uma ocorrncia FileStream com o parmetro fileMode do construtor FileStream() definido como FileMode.APPEND ou FileMode.WRITE. Para obter mais informaes, consulte Fluxo de trabalho de leitura e gravao de arquivos na pgina 674.

Criao de diretrio temporrio

Adobe AIR 1.0 e posterior A classe File inclui o mtodo createTempDirectory(), que cria um diretrio na pasta de diretrios temporrios do Sistema, como no exemplo a seguir:
var temp:File = File.createTempDirectory();

O mtodo createTempDirectory() cria automaticamente um diretrio temporrio exclusivo (poupando o seu trabalho de determinar um novo local exclusivo). Voc pode usar um diretrio temporrio para armazenar temporariamente arquivos temporrios usados em uma sesso do aplicativo. Observe que h um mtodo createTempFile() para criar arquivos temporrios novos e exclusivos no diretrio temporrio System. Pode ser conveniente excluir o diretrio temporrio antes de fechar o aplicativo, uma vez que ele no excludo automaticamente em todos os dispositivos.

Enumerao de diretrios
Adobe AIR 1.0 e posterior Voc pode usar o mtodo getDirectoryListing() ou o mtodo getDirectoryListingAsync() do objeto File para obter uma matriz de objetos File apontando para arquivos e subpastas em um diretrio. Por exemplo, o cdigo a seguir lista o contedo do diretrio de documentos do usurio (sem examinar subdiretrios):
var directory:File = File.documentsDirectory; var contents:Array = directory.getDirectoryListing(); for (var i:uint = 0; i < contents.length; i++) { trace(contents[i].name, contents[i].size); }

Ao usar a verso assncrona do mtodo, o objeto de evento directoryListing ter a propriedade files que a matriz de objetos File pertencentes aos diretrios:
var directory:File = File.documentsDirectory; directory.getDirectoryListingAsync(); directory.addEventListener(FileListEvent.DIRECTORY_LISTING, dirListHandler); function dirListHandler(event:FileListEvent):void { var contents:Array = event.files; for (var i:uint = 0; i < contents.length; i++) { trace(contents[i].name, contents[i].size); } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

669

Cpia e movimentao de diretrios

Adobe AIR 1.0 e posterior Voc pode copiar ou mover o diretrio, usando os mesmos mtodos utilizados para copiar ou mover um arquivo. Por exemplo, o cdigo a seguir copia um diretrio de forma sncrona:
var sourceDir:File = File.documentsDirectory.resolvePath("AIR Test"); var resultDir:File = File.documentsDirectory.resolvePath("AIR Test Copy"); sourceDir.copyTo(resultDir);

Quando voc especifica true para o parmetro overwrite do mtodo copyTo(), todos arquivos e pastas em um diretrio de destino existente so excludos e substitudos pelos arquivos e pastas no diretrio de origem (mesmo se o arquivo de destino no existir no diretrio de origem). O diretrio especificado como o parmetro newLocation do mtodo copyTo() especifica o caminho para o diretrio resultante; ele no especifica o diretrio pai que conter o diretrio resultante. Para obter detalhes, consulte Cpia e movimentao de arquivos na pgina 671.

Excluso de contedo do diretrio

Adobe AIR 1.0 e posterior A classe File inclui os mtodos deleteDirectory() e deleteDirectoryAsync(). Esses mtodos excluem diretrios; o primeiro trabalha de forma sncrona, o segundo trabalha de forma assncrona (consulte Noes bsicas do arquivo AIR na pgina 652). Os dois mtodos incluem o parmetro deleteDirectoryContents (com um valor Booleano); quando esse parmetro estiver definido como true (o valor padro ser false) a chamada do mtodo excluir diretrios no vazios; caso contrrio, apenas diretrios vazios sero excludos. Por exemplo, o cdigo a seguir exclui de modo sncrono o subdiretrio AIR Test do diretrio de documentos do usurios:
var directory:File = File.documentsDirectory.resolvePath("AIR Test"); directory.deleteDirectory(true);

O cdigo a seguir exclui de modo assncrono o subdiretrio AIR Test do diretrio de documentos do usurio:
var directory:File = File.documentsDirectory.resolvePath("AIR Test"); directory.addEventListener(Event.COMPLETE, completeHandler) directory.deleteDirectoryAsync(true); function completeHandler(event:Event):void { trace("Deleted.") }

Tambm esto includos os mtodos moveToTrash() e moveToTrashAsync(), que voc pode usar para mover um diretrio para a lixeira do Sistema. Para obter detalhes, consulte Movimentao de arquivo para a lixeira na pgina 672.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

670

Trabalho com arquivos

Adobe AIR 1.0 e posterior Usando a API de arquivo AIR, voc pode adicionar recursos bsicos de interao de arquivo a seus aplicativos. Por exemplo, voc pode ler e gravar arquivos, copiar e excluir arquivos e assim por diante. Como seus aplicativos podem acessar o sistema de arquivos local, consulte Segurana do AIR na pgina 1063, se ainda no tiver feito isso. Nota: Voc pode associar um tipo de arquivo a um aplicativo AIR (de modo que, quando voc clicar nele duas vezes, o aplicativo seja aberto). Para obter detalhes, consulte Gerenciamento de associaes de arquivos na pgina 870.

Obteno de informaes de arquivos

Adobe AIR 1.0 e posterior A classe File inclui as seguintes propriedades que oferecem informaes sobre um arquivo ou diretrio para o qual o objeto File aponta:
Propriedade File creationDate creator Descrio A data de criao do arquivo no disco local. Obsoleto usa a propriedade extension. (Essa propriedade relata o tipo de criador Macintosh do arquivo, usado somente nas verses do Mac OS anteriores ao Mac OS X). (No Air 2 e posteriores) Indica se o arquivo ou o diretrio mencionados foram baixados (da Internet) ou no. Esta propriedade s significativa em sistemas operacionais em que os arquivos podem ser marcados como baixados:

downloaded

exists extension

Windows XP Service Pack 2 e verses posteriores e no Windows Vista SO Mac 10.5 e posterior

Se o arquivo ou diretrio referenciado existir. A extenso de arquivo, que a parte seguinte ao nome (e no incluindo) o ponto final ("."). Se no houver ponto no nome do arquivo, a extenso ser null. Um objeto Icon que contm os cones definidos para o arquivo. Se a referncia do objeto File for a um diretrio. A data da ltima modificao do arquivo ou diretrio no disco local. O nome do arquivo ou diretrio (incluindo a extenso de arquivo, se houver) no disco local. O caminho completo na representao do sistema operacional de hospedagem. Consulte Caminhos de objetos File na pgina 653. A pasta que contm a pasta ou o arquivo representado pelo objeto File. Essa propriedade ser null se o objeto File fizer referncia a um arquivo ou diretrio na raiz do sistema de arquivos. O tamanho do arquivo no disco local, em bytes. Obsoleto usa a propriedade extension. (No Macintosh, essa propriedade o tipo de arquivo com quatro caracteres, usado somente nas verses do Mac OS anteriores ao Mac OS X). A URL do arquivo ou diretrio. Consulte Caminhos de objetos File na pgina 653.

icon isDirectory modificationDate name nativePath

parent

size tipo

url

Para obter detalhes dessas propriedades, consulte a entrada da classe File na Referncia do ActionScript 3.0 para a plataforma Adobe Flash.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

671

Cpia e movimentao de arquivos

Adobe AIR 1.0 e posterior A classe File inclui dois mtodos de cpia de arquivos ou diretrios: copyTo() e copyToAsync(). A classe File inclui dois mtodos para mover arquivos ou diretrios: moveTo() e moveToAsync(). Os mtodos copyTo() e moveTo() funcionam de modo sncrono e os mtodos copyToAsync() e moveToAsync() funcionam de modo assncrono (consulte Noes bsicas do arquivo AIR na pgina 652). Para copiar ou mover um arquivo, defina dois objetos File. Um aponta para o arquivo que deve ser copiado ou movido, e o objeto que chama o mtodo de cpia ou movimentao; o outro aponta para o caminho de destino (resultado). O seguinte copia o arquivo test.txt do subdiretrio AIR Test do diretrio de documentos do usurio em um arquivo com nome copy.txt no mesmo diretrio:
var original:File = File.documentsDirectory.resolvePath("AIR Test/test.txt"); var newFile:File = File.resolvePath("AIR Test/copy.txt"); original.copyTo(newFile, true);

Nesse exemplo, o valor do parmetro overwrite do mtodo copyTo() (o segundo parmetro) definido como true. Definindo overwrite como true, o arquivo de destino existente sobrescrito. Esse parmetro opcional. Se voc defini-lo como false (o valor padro), a operao despacha um evento IOErrorEvent se o arquivo de destino existir (e o arquivo no copiado). As verses Async dos mtodos de cpia e movimentao funcionam de modo assncrono. Use o mtodo addEventListener() para monitorar a concluso da tarefa ou as condies de erro, como no cdigo a seguir:
var original = File.documentsDirectory; original = original.resolvePath("AIR Test/test.txt"); var destination:File = File.documentsDirectory; destination = destination.resolvePath("AIR Test 2/copy.txt"); original.addEventListener(Event.COMPLETE, fileMoveCompleteHandler); original.addEventListener(IOErrorEvent.IO_ERROR, fileMoveIOErrorEventHandler); original.moveToAsync(destination); function fileMoveCompleteHandler(event:Event):void { trace(event.target); // [object File] } function fileMoveIOErrorEventHandler(event:IOErrorEvent):void { trace("I/O Error."); }

A classe File tambm inclui os mtodos File.moveToTrash() e File.moveToTrashAsync(), que movem o arquivo ou diretrio para a lixeira do sistema.

Excluso de arquivo
Adobe AIR 1.0 e posterior A classe File inclui os mtodos deleteFile() e deleteFileAsync(). Esses mtodos excluem arquivos; o primeiro trabalha de forma sncrona, o segundo trabalha de forma assncrona (consulte Noes bsicas do arquivo AIR na pgina 652). Por exemplo, o cdigo a seguir exclui de modo sncrono o arquivo test.txt do diretrio de documentos do usurio:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

672

var file:File = File.documentsDirectory.resolvePath("test.txt"); file.deleteFile();

O cdigo a seguir exclui de modo assncrono o arquivo test.txt do diretrio de documentos do usurio:
var file:File = File.documentsDirectory.resolvePath("test.txt"); file.addEventListener(Event.COMPLETE, completeHandler) file.deleteFileAsync(); function completeHandler(event:Event):void { trace("Deleted.") }

Tambm esto includos os mtodos moveToTrash() e moveToTrashAsync(), que voc pode usar para mover um arquivo ou diretrio para a lixeira do Sistema. Para obter detalhes, consulte Movimentao de arquivo para a lixeira na pgina 672.

Movimentao de arquivo para a lixeira

Adobe AIR 1.0 e posterior A classe File inclui os mtodos moveToTrash() e moveToTrashAsync(). Esses mtodos enviam um arquivo ou diretrio para a lixeira do Sistema; o primeiro trabalha de forma sncrona, o segundo trabalha de forma assncrona (consulte Noes bsicas do arquivo AIR na pgina 652). Por exemplo, o cdigo a seguir move de modo sncrono o arquivo test.txt no diretrio de documentos do usurios para a lixeira do Sistema:
var file:File = File.documentsDirectory.resolvePath("test.txt"); file.moveToTrash();

Nota: Em sistemas operacionais que no oferecem suporte ao conceito de uma pasta de lixeira recupervel, os arquivos so removidos imediatamente.

Criao de arquivo temporrio

Adobe AIR 1.0 e posterior A classe File inclui o mtodo createTempFile(), que cria um arquivo na pasta de diretrios temporrios do Sistema, como no exemplo a seguir:
var temp:File = File.createTempFile();

O mtodo createTempFile() cria automaticamente um arquivo temporrio exclusivo (poupando o seu trabalho de determinar um novo local exclusivo). Voc pode usar um arquivo temporrio para armazenar temporariamente informaes usadas em uma sesso do aplicativo. Observe que tambm h o mtodo createTempDirectory() para criar um diretrio temporrio exclusivo no diretrio temporrio System. Pode ser conveniente excluir o arquivo temporrio antes de fechar o aplicativo, uma vez que ele no excludo automaticamente em todos os dispositivos.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

673

Trabalho com volumes de armazenamento

Adobe AIR 2 e posterior No AIR 2, voc pode detectar quando os volumes de armazenamento em massa so montados ou desmontados. A classe StorageVolumeInfo define um objeto storageVolumeInfo singleton. O objeto StorageVolumeInfo.storageVolumeInfo despacha um evento storageVolumeMount quando um volume de armazenamento montado. E tambm despacha um evento storageVolumeUnmount quando um volume desmontado. A classe StorageVolumeChangeEvent define esses eventos. Nota: Em distribuies modernas de Linux, o objeto StorageVolumeInfo envia apenas eventos storageVolumeMount and storageVolumeUnmount para dispositivos fsicos e unidades de rede montados em locais especficos. A propriedade storageVolume da classe StorageVolumeChangeEvent um objeto StorageVolume. A classe StorageVolume define as propriedades bsicas do volume de armazenamento:

unidadeA letra da unidade do volume no Windows (null em outros sistemas operacionais) fileSystemType O tipo do sistema de arquivo no volume de armazenamento (como "FAT", "NTFS", "HFS" ou

"UFS")
isRemoveable Se um volume removvel true) ou no (false) isWritable Se um volume gravvel true) ou no (false) name O nome do volume rootDirectory Um objeto de arquivo que corresponde ao diretrio raiz do volume

A classe StorageVolumeChangeEvent tambm contm uma propriedade rootDirectory. A propriedade rootDirectory um objeto File que faz referncia ao diretrio raiz do volume de armazenamento que foi montado ou desmontado. A propriedade storageVolume do objeto StorageVolumeChangeEvent no est definida (null) para o volume no montado. No entanto, voc pode acessar a propriedade rootDirectory do evento. O cdigo a seguir libera o nome e o caminho do arquivo de um volume de armazenamento quando montado:
StorageVolumeInfo.storageVolumeInfo.addEventListener(StorageVolumeChangeEvent.STORAGE_VOLUME _MOUNT, onVolumeMount); function onVolumeMount(event:StorageVolumeChangeEvent):void { trace(event.storageVolume.name, event.rootDirectory.nativePath); }

O cdigo a seguir libera o caminho do arquivo de um volume de armazenamento quando desmontado:

StorageVolumeInfo.storageVolumeInfo.addEventListener(StorageVolumeChangeEvent.STORAGE_VOLUME _UNMOUNT, onVolumeUnmount); function onVolumeUnmount(event:StorageVolumeChangeEvent):void { trace(event.rootDirectory.nativePath); }

O objeto StorageVolumeInfo.storageVolumeInfo inclui um mtodo getStorageVolumes(). Esse mtodo retorna um vetor dos objetos StorageVolume que correspondem aos volumes de armazenamento atualmente montados. O cdigo a seguir mostra como listar os nomes e os diretrios raiz de todos os volumes de armazenamento montados:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

674

var volumes:Vector.<StorageVolume> = new Vector.<StorageVolume>; volumes = StorageVolumeInfo.storageVolumeInfo.getStorageVolumes(); for (var i:int = 0; i < volumes.length; i++) { trace(volumes[i].name, volumes[i].rootDirectory.nativePath); }

Nota: Em distribuies modernas de Linux, o mtodo getStorageVolumes() retorna objetos que correspondem a dispositivos fsicos e unidades de rede montados em locais especficos. O mtodo File.getRootDirectories() lista os diretrios raiz (consulte Apontando para a raiz do sistema de arquivos na pgina 659. No entanto, os objetos StorageVolume (enumerados pelo mtodo StorageVolumeInfo.getStorageVolumes()) fornece mais informaes sobre os volumes de armazenamento. Voc pode usar a propriedade spaceAvailable da propriedade rootDirectory de um objeto StorageVolume para obter o espao disponvel em um volume de armazenamento. (Consulte Determinao de espao disponvel em um volume na pgina 665.) Para obter informaes sobre volumes de armazenamento em dispositivos AIR for TV, consulte Visualizao de diretrios para aplicativos AIR for TV na pgina 656.

Mais tpicos da Ajuda

StorageVolume StorageVolumeInfo

Leitura e gravao de arquivos

Adobe AIR 1.0 e posterior A classe FileStream permite que aplicativos AIR leiam e gravem no sistema de arquivos.

Fluxo de trabalho de leitura e gravao de arquivos

Adobe AIR 1.0 e posterior O fluxo de trabalho de leitura e gravao de arquivos o seguinte. Inicializa o objeto File que aponta para o caminho. O objeto File representa o caminho do arquivo com que voc deseja trabalhar (ou um arquivo que voc criar mais tarde).
var file:File = File.documentsDirectory; file = file.resolvePath("AIR Test/testFile.txt");

Este exemplo usa a propriedade File.documentsDirectory e o mtodo resolvePath() do objeto File para inicializ-lo. No entanto, h vrias outras maneiras de apontar o objeto File para um arquivo. Para obter mais informaes, consulte Como apontar um objeto File para um arquivo na pgina 660.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

675

Inicializa o objeto FileStream. Chama o mtodo open() ou openAsync() do objeto FileStream. O mtodo que voc chama depende de voc desejar abrir o arquivo para operaes sncronas ou assncronas. Use o objeto File como parmetro file do mtodo open. No parmetro fileMode, especifique uma constante da classe FileMode que determine o modo como voc usar o arquivo. Por exemplo, o cdigo a seguir inicializa o objeto FileStream que usado para criar um arquivo e substituir algum dado existente:
var fileStream:FileStream = new FileStream(); fileStream.open(file, FileMode.WRITE);

Para obter mais informaes, consulteInicializao de um objeto FileStream e abertura e fechamento de arquivos na pgina 676, e modos de abertura FileStream na pgina 676. Se voc abriu o arquivo de modo assncrono (usando o mtodo openAsync()), adicione e configure ouvintes de eventos para o objeto FileStream. Esses mtodos ouvintes de eventos respondem a eventos gerados pelo objeto FileStream em diversas situaes. Essas situaes incluem quando os dados so lidos do arquivo, quando so encontrados erros de E/S, ou quando a quantidade completa de dados a serem gravados foi gravada. Para obter detalhes, consulte Programao assncrona e eventos gerados por um objeto FileStream aberto assincronicamente na pgina 680. Incluir cdigo de leitura e gravao de dados, conforme necessrio. H vrios mtodos da classe FileStream relacionados a leitura e gravao. (Cada um deles inicia com "read" ou "write"). O mtodo escolhido para ser usado na leitura ou gravao de dados depende do formato de dados no arquivo de destino. Por exemplo, se os dados no arquivo de destino forem texto de codificao UTF, voc pode usar os mtodos
readUTFBytes() e writeUTFBytes(). Se desejar tratar os dados como matrizes de bytes, voc pode usar os mtodos readByte(), readBytes(), writeByte() e writeBytes(). Para saber detalhes, consulte Formatos de dados e seleo de mtodos de leitura e gravao para uso na pgina 681.

Se voc abriu o arquivo de modo assncrono, certifique-se de que h dados suficientes disponveis antes de chamar o mtodo de leitura. Para obter detalhes, consulte O buffer de leitura e a propriedade bytesAvailable do objeto FileStream na pgina 679. Antes de fazer a gravao em um arquivo, se desejar verificar a quantidade de espao em disco disponvel, voc poder assinalar a propriedade spaceAvailable do objeto File. Para obter mais informaes, consulte Determinao de espao disponvel em um volume na pgina 665. Chama o mtodo close() do objeto FileStream quando voc tiver terminado o trabalho no arquivo. Chamar o mtodo close() disponibiliza o arquivo para outros aplicativos. Para obter detalhes, consulte Inicializao de um objeto FileStream e abertura e fechamento de arquivos na pgina 676. Para visualizar um aplicativo de amostra que usa a classe FileStream para ler e gravar arquivos, consulte os seguintes artigos no Centro de desenvolvimento do Adobe AIR:

Criao de editor de arquivo de texto

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

676

Criao de editor de arquivo de texto Leitura e gravao de um arquivo de preferncias XML

Trabalho com objetos FileStream

Adobe AIR 1.0 e posterior A classe FileStream define mtodos de abertura, leitura e gravao de arquivos. modos de abertura FileStream Adobe AIR 1.0 e posterior Cada um dos mtodos open() e openAsync() do objeto FileStream inclui o parmetro fileMode, que define algumas propriedades de um fluxo de arquivo, incluindo o seguinte:

A capacidade de ler do arquivo A capacidade de gravar no arquivo Se os dados sero sempre acrescentados ao final do arquivo (durante a gravao). O que fazer quando o arquivo no existir (e quando os respectivos diretrios pai no existirem)
A seguir, os vrios modos de arquivo (que voc pode especificar como o parmetro fileMode dos mtodos open() e openAsync()):
modo File FileMode.READ FileMode.WRITE Descrio Especifica que o arquivo est aberto somente para leitura. Especifica que o arquivo est aberto para gravao. Se o arquivo no existir, ele criado quando o objeto FileStream aberto. Se o arquivo existir, todos os dados existentes so excludos. Especifica que o arquivo est aberto para acrscimo. O arquivo criado se ele no existir. Se o arquivo existir, os dados existentes no so substitudos e todas as gravaes sero iniciadas no final do arquivo. Especifica que o arquivo est aberto para leitura e gravao. Se o arquivo no existir, ele criado. Especifique esse modo para acesso de leitura/gravao aleatrio ao arquivo. Voc pode ler a partir de qualquer posio no arquivo. Ao gravar no arquivo, apenas os bytes gravados substituiro os bytes existentes (todos os demais bytes permanecero inalterados).

FileMode.APPEND

FileMode.UPDATE

Inicializao de um objeto FileStream e abertura e fechamento de arquivos Adobe AIR 1.0 e posterior Ao abrir o objeto FileStream, voc o torna disponvel para a leitura e gravao de dados em um arquivo. Voc abre o objeto FileStream passando o objeto File para o mtodo open() ou openAsync() do objeto FileStream:
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt"); var myFileStream:FileStream = new FileStream(); myFileStream.open(myFile, FileMode.READ);

O parmetro fileMode (o segundo parmetro dos mtodos open() e openAsync()) especifica o modo em que o arquivo deve ser aberto: para leitura, gravao, acrscimo ou atualizao. Para obter detalhes, consulte a seo anterior,modos de abertura FileStream na pgina 676. Se voc usar o mtodo openAsync() para abrir o arquivo para operaes de arquivo de modo assncrono, configure os ouvintes de eventos para tratar os eventos assncronos:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

677

var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt"); var myFileStream:FileStream = new FileStream(); myFileStream.addEventListener(Event.COMPLETE, completeHandler); myFileStream.addEventListener(ProgressEvent.PROGRESS, progressHandler); myFileStream.addEventListener(IOErrorEvent.IOError, errorHandler); myFileStream.open(myFile, FileMode.READ); function completeHandler(event:Event):void { // ... } function progressHandler(event:ProgressEvent):void { // ... } function errorHandler(event:IOErrorEvent):void { // ... }

O arquivo aberto para operaes sncronas ou assncronas, dependendo de voc usar o mtodo open() ou openAsync(). Para obter detalhes, consulte Noes bsicas do arquivo AIR na pgina 652. Se voc definir o parmetro fileMode como FileMode.READ ou FileMode.UPDATE no mtodo de abertura do objeto FileStream, os dados so lidos no buffer de leitura to logo voc abra o objeto FileStream. Para obter detalhes, consulte O buffer de leitura e a propriedade bytesAvailable do objeto FileStream na pgina 679. Voc pode chamar o mtodo close() do objeto FileStream para fechar o arquivo associado, tornando-o disponvel para uso por outros aplicativos. A propriedade position do objeto FileStream Adobe AIR 1.0 e posterior A propriedade position do objeto FileStream determina quando os dados so lidos ou gravados no prximo mtodo de leitura ou gravao. Antes de uma operao de leitura ou gravao, defina a propriedade position como qualquer posio vlida no arquivo. Por exemplo, o cdigo a seguir grava a seqncia "hello" (na codificao UTF) na posio 8 do arquivo:
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt"); var myFileStream:FileStream = new FileStream(); myFileStream.open(myFile, FileMode.UPDATE); myFileStream.position = 8; myFileStream.writeUTFBytes("hello");

Quando voc abre pela primeira vez o objeto FileStream, a propriedade position definida como 0. Antes de uma operao de leitura, o valor de position deve ser no mnimo 0 e inferior ao nmero de bytes no arquivo (que so posies existentes no arquivo). O valor da propriedade position modificado apenas nas seguintes condies:

Quando voc define explicitamente a propriedade position. Quando voc chama o mtodo de leitura.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

678

Quando voc chama o mtodo de gravao.

Quando voc chama um mtodo de leitura ou gravao do objeto FileStream, a propriedade position imediatamente incrementada pelo nmero de bytes que voc l ou grava. Dependendo do mtodo de leitura usado, a propriedade position tambm incrementada pelo nmero de bytes especificado para leitura ou pelo nmero de bytes disponvel. Quando voc chama o mtodo de leitura ou gravao subseqentemente, ele faz a leitura ou gravao iniciando na nova posio.
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt"); var myFileStream:FileStream = new FileStream(); myFileStream.open(myFile, FileMode.UPDATE); myFileStream.position = 4000; trace(myFileStream.position); // 4000 myFileStream.writeBytes(myByteArray, 0, 200); trace(myFileStream.position); // 4200

H, porm, uma exceo: em um FileStream aberto no modo append, a propriedade position no alterada aps uma chamada de um mtodo de gravao. (No modo append, os dados so sempre gravados no final do arquivo, independentemente do valor da propriedade position.) Em um arquivo aberto para operaes assncronas, a operao de gravao no concluda antes de a prxima linha de cdigo ser executada. No entanto, voc pode chamar vrios mtodos assncronos seqencialmente e o tempo de execuo os executa em ordem:
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt"); var myFileStream:FileStream = new FileStream(); myFileStream.openAsync(myFile, FileMode.WRITE); myFileStream.writeUTFBytes("hello"); myFileStream.writeUTFBytes("world"); myFileStream.addEventListener(Event.CLOSE, closeHandler); myFileStream.close(); trace("started."); closeHandler(event:Event):void { trace("finished."); }

A sada trace desse cdigo a seguinte:

started. finished.

Voc pode especificar o valor position logo aps chamar um mtodo de leitura ou gravao (ou a qualquer momento) e a prxima operao de leitura ou gravao ocorrer no incio dessa posio. Por exemplo, observe que o cdigo a seguir define a propriedade position logo aps uma chamada para a operao writeBytes() e a position definida como esse valor (300) mesmo aps a operao de gravao ser concluda:
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt"); var myFileStream:FileStream = new FileStream(); myFileStream.openAsync(myFile, FileMode.UPDATE); myFileStream.position = 4000; trace(myFileStream.position); // 4000 myFileStream.writeBytes(myByteArray, 0, 200); myFileStream.position = 300; trace(myFileStream.position); // 300

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

679

O buffer de leitura e a propriedade bytesAvailable do objeto FileStream Adobe AIR 1.0 e posterior Quando o objeto FileStream com recursos de leitura (em que o parmetro fileMode do mtodo open() ou openAsync() foi definido como READ ou UPDATE) for aberto, o tempo de execuo armazena os dados em um buffer interno. O objeto FileStream comea a fazer a leitura de dados no buffer assim que o arquivo for aberto (chamando o mtodo open() ou openAsync() do objeto FileStream). Em um arquivo aberto para operaes sncronas (usando o mtodo open()), voc sempre poder definir o ponteiro
position em qualquer posio vlida (dentro dos limites do arquivo) e iniciar a leitura de qualquer quantidade de

dados (dentro dos limites do arquivo), conforme mostra o cdigo a seguir (que supe que o arquivo contm pelo menos 100 bytes):
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt"); var myFileStream:FileStream = new FileStream(); myFileStream.open(myFile, FileMode.READ); myFileStream.position = 10; myFileStream.readBytes(myByteArray, 0, 20); myFileStream.position = 89; myFileStream.readBytes(myByteArray, 0, 10);

Quer o arquivo seja aberto para operaes sncronas ou assncronas, os mtodos de leitura sempre fazem a leitura dos bytes "disponveis", representados pela propriedade bytesAvalable. Ao fazer a leitura sincronicamente, todos os bytes do arquivo ficam disponveis o tempo todo. Ao fazer a leitura assincronicamente, os bytes se tornam disponveis, iniciando na posio especificada pela propriedade position, em uma srie de preenchimentos de buffer assncronos assinalados por eventos progress. Em arquivos abertos para operaes sncronas, a propriedade bytesAvailable sempre definida para representar o nmero de bytes da propriedade position no final do arquivo (todos os bytes no arquivo estaro sempre disponveis para leitura). Em arquivos abertos para operaes assncronas, necessrio assegurar que o buffer de leitura consumiu dados suficientes antes de chamar o mtodo de leitura. Em um arquivo aberto assincronicamente, conforme o andamento da operao de leitura, os dados do arquivo, iniciando na posio especificada quando a operao de leitura iniciou, so adicionados ao buffer, e a propriedade bytesAvailable incrementada com cada byte lido. A propriedade bytesAvailable indica o nmero de bytes disponveis, iniciando com o byte na posio especificada pela propriedade position at o final do buffer. Periodicamente, o objeto FileStream envia um evento progress. Em um arquivo aberto sincronicamente, medida que os dados se tornam disponveis no buffer de leitura, o objeto FileStream despacha periodicamente o evento progress. Por exemplo, o cdigo a seguir l dados em um objeto ByteArray, bytes, conforme lido no buffer:
var bytes:ByteArray = new ByteArray(); var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt"); var myFileStream:FileStream = new FileStream(); myFileStream.addEventListener(ProgressEvent.PROGRESS, progressHandler); myFileStream.openAsync(myFile, FileMode.READ); function progressHandler(event:ProgressEvent):void { myFileStream.readBytes(bytes, myFileStream.position, myFileStream.bytesAvailable); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

680

Em um arquivo aberto assincronicamente, apenas os dados no buffer de leitura podem ser lidos. Alm disso, conforme voc l os dados, eles so removidos do buffer de leitura. Em operaes de leitura voc precisa assegurar que haja dados no buffer de leitura antes de chamar uma operao de leitura. Por exemplo, o cdigo a seguir faz a leitura de 8000 bytes de dados iniciando da posio 4000 no arquivo:
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt"); var myFileStream:FileStream = new FileStream(); myFileStream.addEventListener(ProgressEvent.PROGRESS, progressHandler); myFileStream.addEventListener(Event.COMPLETE, completed); myFileStream.openAsync(myFile, FileMode.READ); myFileStream.position = 4000; var str:String = ""; function progressHandler(event:Event):void { if (myFileStream.bytesAvailable > 8000 ) { str += myFileStream.readMultiByte(8000, "iso-8859-1"); } }

Durante a operao de gravao, o objeto FileStream no faz a leitura de dados no buffer de leitura. Quando a operao de gravao estiver concluda (todos os dados no buffer de gravao so gravados no arquivo), o objeto FileStream inicia um novo buffer de leitura (supondo que o objeto FileStream associado foi aberto com recursos de leitura) e inicia a leitura de dados no buffer de leitura, comeando da posio especificada pela propriedade position. A propriedade position pode ser a posio do ltimo byte gravado ou pode ser uma posio diferente, se o usurio especificar um valor diferente para o objeto position aps a operao de gravao. Programao assncrona e eventos gerados por um objeto FileStream aberto assincronicamente Adobe AIR 1.0 e posterior Quando um arquivo for aberto de modo assncrono (usando o mtodo openAsync()), os arquivos de leitura e gravao sero executados de modo assncrono. medida que os dados so lidos no buffer de leitura e os dados de sada comeam a ser gravados, outro cdigo ActionScript pode ser executado. Isso significa que necessrio se registrar para eventos gerados pelo objeto FileStream abertos de modo assncrono. Registrando-se para o evento progress, voc poder ser notificado quando novos dados se tornarem disponveis para leitura, como no seguinte cdigo:
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt"); var myFileStream:FileStream = new FileStream(); myFileStream.addEventListener(ProgressEvent.PROGRESS, progressHandler); myFileStream.openAsync(myFile, FileMode.READ); var str:String = ""; function progressHandler(event:ProgressEvent):void { str += myFileStream.readMultiByte(myFileStream.bytesAvailable, "iso-8859-1"); }

Voc pode fazer a leitura de todos os dados se registrando para o evento complete, como no seguinte cdigo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

681

var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt"); var myFileStream:FileStream = new FileStream(); myFileStream.addEventListener(Event.COMPLETE, completed); myFileStream.openAsync(myFile, FileMode.READ); var str:String = ""; function completeHandler(event:Event):void { str = myFileStream.readMultiByte(myFileStream.bytesAvailable, "iso-8859-1"); }

Da mesma maneira que os dados de entrada so colocados em buffer para permitir a leitura assncrona, os dados que voc grava em um fluxo assncrono so colocados em buffer e gravados no arquivo de forma assncrona. medida que os dados so gravados em um arquivo, o objeto FileStream despacha periodicamente o objeto OutputProgressEvent. O objeto OutputProgressEvent inclui a propriedade bytesPending definida pelo nmero de bytes restantes para gravao. Voc pode registrar para que o evento outputProgress seja notificado, j que esse buffer , na realidade, gravado no arquivo, talvez para exibir uma caixa de dilogo de progresso. No entanto, isso geralmente no necessrio. Especificamente, voc pode chamar o mtodo close() sem se importar com os bytes no gravados. O objeto FileStream continuar gravando dados e o evento close ser entregue aps o byte final ser gravado no arquivo e o arquivo subjacente ser fechado. Formatos de dados e seleo de mtodos de leitura e gravao para uso Adobe AIR 1.0 e posterior Todo arquivo um conjunto de bytes em um disco. No ActionScript, os dados de um arquivo sempre podem ser representados como ByteArray. Por exemplo, o cdigo a seguir faz a leitura de dados de um arquivo em um objeto ByteArray chamado bytes:
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt"); var myFileStream:FileStream = new FileStream(); myFileStream.addEventListener(Event.COMPLETE, completeHandler); myFileStream.openAsync(myFile, FileMode.READ); var bytes:ByteArray = new ByteArray(); function completeHandler(event:Event):void { myFileStream.readBytes(bytes, 0, myFileStream.bytesAvailable); }

De forma semelhante, o cdigo seguinte grava dados de um ByteArray chamado bytes em um arquivo:
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt"); var myFileStream:FileStream = new FileStream(); myFileStream.open(myFile, FileMode.WRITE); myFileStream.writeBytes(bytes, 0, bytes.length);

No entanto, normalmente voc no quer armazenar dados em um objeto ByteArray do ActionScript. E, geralmente, o arquivo de dados est em um formato de arquivo especificado. Por exemplo, os dados no arquivo podem estar em um formato de arquivo de texto e talvez voc deseje representar esses dados em um objeto String. Por esse motivo, a classe FileStream inclui mtodos de leitura e gravao para leitura e gravao de dados em outros tipos diferentes dos objetos ByteArray e a partir deles. Por exemplo, o mtodo readMultiByte() permite fazer a leitura de dados de um arquivo e armazen-los em uma seqncia, como no cdigo a seguir:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

682

var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt"); var myFileStream:FileStream = new FileStream(); myFileStream.addEventListener(Event.COMPLETE, completed); myFileStream.openAsync(myFile, FileMode.READ); var str:String = ""; function completeHandler(event:Event):void { str = myFileStream.readMultiByte(myFileStream.bytesAvailable, "iso-8859-1"); }

O segundo parmetro do mtodo readMultiByte() especifica o formato de texto que o ActionScript usa para interpretar os dados ("iso-8859-1" no exemplo). O Adobe AIR permite o uso de codificaes comuns de conjuntos de caracteres (consulte Conjuntos de caracteres permitidos). A classe FileStream tambm inclui o mtodo readUTFBytes(), que faz leitura de dados do buffer de leitura em uma seqncia, usando o conjunto de caracteres UTF-8. Como os caracteres no conjunto de caracteres UTF-8 so de tamanho varivel, no use readUTFBytes() em um mtodo que responde ao evento progress, j que os dados no final do buffer de leitura podem representar um caractere incompleto. (Isso tambm verdadeiro ao usar o mtodo readMultiByte() com uma codificao de caractere de tamanho varivel). Por esse motivo, leia o conjunto de dados inteiro quando o objeto FileStream despachar o evento complete. Tambm h mtodos de gravao semelhantes, writeMultiByte() e writeUTFBytes(), para trabalhar com objetos String e arquivos de texto. Os mtodos readUTF() e writeUTF() (no confundir com readUTFBytes() e writeUTFBytes()) tambm fazem leitura e gravao de dados de texto em um arquivo, mas eles supem que os dados de texto so precedidos por dados que especificam o tamanho dos dados de texto, o que no prtica comum em arquivos de texto padro. Alguns arquivos de texto de codificao UTF comeam com um caractere "UTF-BOM" (marca de ordem de bytes) que define que a terminao, bem como o formato de codificao (como UTF-16 ou UTF-32). Para obter um exemplo de leitura e gravao de um arquivo de texto, consulte Exemplo: Leitura de arquivo XML em um objeto XML na pgina 683.
readObject() e writeObject() so formas convenientes de armazenar e recuperar dados de objetos ActionScript

complexos. Os dados so codificados em AMF (ActionScript Message Format). O Adobe AIR, o Flash Player, o Flash Media Server e o Flex Data Services incluem APIs para trabalhar co dados neste formato. H mais alguns mtodos de leitura e gravao (comoreadDouble() e writeDouble()). No entanto, se voc us-los, certifique-se de que o formato de arquivo corresponde ao formato dos dados definidos por esses mtodos. Os formatos de arquivos so normalmente mais complexos do que os formatos de texto simples. Por exemplo, o arquivo MP3 inclui dados compactados que s podem ser interpretados com a descompactao e os algoritmos de decodificao especficos para arquivos MP3. Arquivos MP3 tambm podem incluir marcas ID3 que contm informaes de metatag sobre o arquivo (como o ttulo e o artista de uma cano). H vrias verses do formato ID3, mas a mais simples (ID3 verso 1) discutida na seo Exemplo: Leitura e gravao de dados com acesso aleatrio na pgina 685. Outros formatos de arquivo (de imagens, bancos de dados, documentos de aplicativos etc.) tm estruturas diferentes e, para trabalhar com os respectivos dados no ActionScript, voc deve saber como os dados so estruturados.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

683

Uso dos mtodos load() e save()

Flash Player 10 e posterior, Adobe AIR 1.5 e posterior O Flash Player 10 adicionou os mtodos load() e save() classe FileReference. Esses mtodos tambm esto no AIR 1.5 e a classe File herda os mtodos da classe FileReference. Esses mtodos foram projetados para fornecer um meio seguro para usurios carregarem e salvarem dados de arquivo em Flash Player. No entanto, os aplicativos AIR tambm podem usar esses mtodos como uma maneira fcil de carregar e salvar arquivos de forma assncrona. Por exemplo, o cdigo a seguir salva uma seqncia de caracteres em um arquivo de texto:
var file:File = File.applicationStorageDirectory.resolvePath("test.txt"); var str:String = "Hello."; file.addEventListener(Event.COMPLETE, fileSaved); file.save(str); function fileSaved(event:Event):void { trace("Done."); }

O parmetro data do mtodo save() pode usar um valor String, XML ou ByteArray. Quando o argumento um valor String ou XML, o mtodo salva o arquivo como arquivo de texto criptografado UTF-8. Quando esse exemplo de cdigo executado, o aplicativo exibe uma caixa de dilogo em que o usurio seleciona o destino do arquivo salvo. O cdigo a seguir carrega uma seqncia de caracteres de um arquivo de texto codificado em UTF-8.
var file:File = File.applicationStorageDirectory.resolvePath("test.txt"); file.addEventListener(Event.COMPLETE, loaded); file.load(); var str:String; function loaded(event:Event):void { var bytes:ByteArray = file.data; str = bytes.readUTFBytes(bytes.length); trace(str); }

A classe FileStream fornece mais funcionalidade do que os mtodos load() e save().

Usando a classe FileStream, voc pode ler e gravar dados de forma sncrona e assncrona. O uso da classe FileStream permite gravar em um arquivo de forma incremental. O uso da classe FileStream permite abrir um arquivo para acesso aleatrio (para leitura e gravao em qualquer
seo do arquivo).

A classe FileStream permite especificar o tipo de acesso que voc tem ao arquivo, definindo o parmetro fileMode
do mtodo open() ou openAsync().

A classe FileStream permite salvar dados em arquivos sem apresentar ao usurio uma caixa de dilogo Abrir ou
Salvar.

Voc pode usar diretamente tipos diferentes de matrizes de bytes ao ler dados com a classe FileStream.

Exemplo: Leitura de arquivo XML em um objeto XML

Adobe AIR 1.0 e posterior O exemplo a seguir demonstra como fazer a leitura e a gravao de um arquivo de texto contendo dados XML.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

684

Para ler o arquivo, inicialize os objetos File e FileStream, chame o mtodo readUTFBytes() do FileStream e converta a seqncia em um objeto XML:
var file:File = File.documentsDirectory.resolvePath("AIR Test/preferences.xml"); var fileStream:FileStream = new FileStream(); fileStream.open(file, FileMode.READ); var prefsXML:XML = XML(fileStream.readUTFBytes(fileStream.bytesAvailable)); fileStream.close();

De modo semelhante, gravar dados no arquivo to fcil quanto configurar os objetos File e FileStream apropriados e, em seguida, chamar um mtodo de gravao do objeto FileStream. Passe a verso de seqncia dos dados XML para o mtodo de gravao, como no cdigo seguinte:
var prefsXML:XML = <prefs><autoSave>true</autoSave></prefs>; var file:File = File.documentsDirectory.resolvePath("AIR Test/preferences.xml"); fileStream = new FileStream(); fileStream.open(file, FileMode.WRITE); var outputString:String = '<?xml version="1.0" encoding="utf-8"?>\n'; outputString += prefsXML.toXMLString(); fileStream.writeUTFBytes(outputString); fileStream.close();

Esses exemplos usam os mtodos readUTFBytes() e writeUTFBytes(), porque consideram que os arquivos estejam no formato UTF-8. Caso contrrio, voc pode precisar usar um mtodo diferente (consulte Formatos de dados e seleo de mtodos de leitura e gravao para uso na pgina 681). Os exemplos anteriores usam objetos FileStream abertos para operao sncrona. Voc tambm pode abrir arquivos para operaes assncronas (que dependem das funes de ouvinte de evento para responder aos eventos). Por exemplo, o cdigo a seguir mostra como fazer a leitura de um arquivo XML de modo assncrono:
var file:File = File.documentsDirectory.resolvePath("AIR Test/preferences.xml"); var fileStream:FileStream = new FileStream(); fileStream.addEventListener(Event.COMPLETE, processXMLData); fileStream.openAsync(file, FileMode.READ); var prefsXML:XML; function processXMLData(event:Event):void { prefsXML = XML(fileStream.readUTFBytes(fileStream.bytesAvailable)); fileStream.close(); }

O mtodo processXMLData() chamado quando o arquivo inteiro lido no buffer de leitura (quando o objeto FileStream despacha o evento complete). Ele chama o mtodo readUTFBytes() para obter uma verso de seqncia dos dados lidos e cria um objeto XML, prefsXML, com base nessa seqncia. Para visualizar um aplicativo de amostra que mostre esses recursos, consulte Leitura e gravao de um arquivo de preferncias XML.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

685

Exemplo: Leitura e gravao de dados com acesso aleatrio

Adobe AIR 1.0 e posterior Arquivos MP3 podem incluir marcas ID3, que so sees no incio ou no final do arquivo, contendo metadados que identificam a gravao. O prprio formato de marca ID3 tem revises diferentes. Este exemplo descreve como fazer a leitura e a gravao de um arquivo MP3 que contm o formato ID3 mais simples (ID3 verso 1.0) usando o "acesso aleatrio a dados do arquivo", o que significa que ele l a partir de e grava em locais arbitrrios no arquivo. O arquivo MP3 que contm uma marca ID3 verso 1 inclui dados ID3 no final do arquivo, nos ltimos 128 bytes. Ao acessar um arquivo para acesso de leitura e gravao aleatrio, importante especificar FileMode.UPDATE como o parmetro fileMode do mtodo open() ou openAsync():
var file:File = File.documentsDirectory.resolvePath("My Music/Sample ID3 v1.mp3"); var fileStr:FileStream = new FileStream(); fileStr.open(file, FileMode.UPDATE);

Isso permite ler e gravar no arquivo. Ao abrir o arquivo, voc pode definir o ponteiro position para a posio de 128 bytes antes do final do arquivo:
fileStr.position = file.size - 128;

Esse cdigo define a propriedade position para esse local no arquivo, porque o formato ID3 v1.0 especifica que os dados da marca ID3 so armazenados nos ltimos 128 bytes do arquivo. A especificao tambm diz o seguinte:

Os primeiros 3 bytes da marca contm a seqncia "TAG". Os 30 caracteres seguintes contm o ttulo da trilha MP3, como uma seqncia. Os 30 caracteres seguintes contm o nome do artista, como uma seqncia. Os 30 caracteres seguintes contm o nome do lbum, como uma seqncia. Os 4 caracteres seguintes contm o ano, como uma seqncia. Os 30 caracteres seguintes contm o comentrio, como uma seqncia. O byte seguinte contm um cdigo indicando o gnero da trilha. Todos os dados de texto esto no formato ISO 8859-1.
O mtodo id3TagRead() verifica os dados aps serem lidos (no evento complete):
function id3TagRead():void { if (fileStr.readMultiByte(3, "iso-8859-1").match(/tag/i)) { var id3Title:String = fileStr.readMultiByte(30, "iso-8859-1"); var id3Artist:String = fileStr.readMultiByte(30, "iso-8859-1"); var id3Album:String = fileStr.readMultiByte(30, "iso-8859-1"); var id3Year:String = fileStr.readMultiByte(4, "iso-8859-1"); var id3Comment:String = fileStr.readMultiByte(30, "iso-8859-1"); var id3GenreCode:String = fileStr.readByte().toString(10); } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com o sistema de arquivos

686

Voc tambm pode realizar uma gravao com acesso aleatrio no arquivo. Por exemplo, voc pode analisar a varivel id3Title para assegurar que ela esteja com as maisculas e minsculas corretas (usando mtodos da classe String) e, em seguida, fazer a gravao de uma seqncia modificada, chamada newTitle, no arquivo, como no seguinte:
fileStr.position = file.length - 125; // 128 - 3 fileStr.writeMultiByte(newTitle, "iso-8859-1");

Para corresponder verso 1 padro do ID3, o tamanho da seqncia newTitle deve ter 30 caracteres, preenchidos no final com o caractere de cdigo 0 (String.fromCharCode(0)).

ltima atualizao em 29/3/2011

687

Captulo 37: Armazenamento de dados locais

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Utilize a classe SharedObject para armazenar pequenas quantidades de dados no computador do cliente. No Adobe AIR, voc tambm pode usar a classe EncryptedLocalStore para armazenar pequenas quantidades de dados de privacidade do usurio no computador local em um aplicativo AIR. Voc tambm pode ler e gravar arquivos no sistema de arquivos e (no Adobe AIR) acessar os arquivos locais do banco de dados. Para obter mais informaes, consulte Trabalho com o sistema de arquivos na pgina 636 e Trabalho com bancos de dados SQL locais no AIR na pgina 700. H uma srie de fatores de segurana que se relacionam com os objetos compartilhados. Para obter mais informaes, consulte Objetos compartilhados na pgina 1061 em Segurana na pgina 1027.

Objetos compartilhados
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Um objeto compartilhado, s vezes referenciado como um cookie Flash. um arquivo de dados que pode ser criado no computador pelos sites visitados. Objetos compartilhados so usados com maior frequncia para aprimorar sua experincia de navegao na Web, por exemplo, permitindo personalizar a aparncia de um site visitado com frequncia.

Sobre os objetos compartilhados

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os objetos compartilhados funcionam como os cookies do navegador. Utilize a classe SharedObject para armazenar dados no disco rgido local do usurio e chamar dados durante a mesma sesso ou em uma sesso posterior. Os aplicativos podem acessar apenas seus prprios dados SharedObject, e somente quando executam no mesmo domnio. Os dados no foram enviados ao servidor e no esto acessveis por outros aplicativos em execuo nos outros domnios, mas podem tornar-se acessveis por aplicativos do mesmo domnio.

Objetos compartilhados com cookies

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Cookies e objetos compartilhados so muito similares. Como a maioria dos programadores da Web esto familiarizados com o modo como os cookies funcionam, pode ser til fazer uma analogia entre os cookies e os SharedObjects locais. Os cookies que aderem ao padro RFC 2109 geralmente tm as seguintes propriedades:

Podem expirar e o fazem com frequncia, por padro, ao final da sesso. Podem ser desativados pelo cliente em uma base especfica por site.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Armazenamento de dados locais

688

H um limite total de 300 cookies e 20 o mximo por site. Normalmente, esto limitados ao tamanho de 4 KB cada. Algumas vezes, so percebidos como uma ameaa segurana e, em resultado disso, ficam desativados no cliente. So armazenados em um local especificado pelo navegador cliente. So transmitidos do cliente ao servidor via HTTP.
Por outro lado, os objetos compartilhados apresentam as seguintes propriedades:

No expiram por padro. Por padro, esto limitados ao tamanho de 100 KB cada. Podem armazenar tipos de dados simples (como sequncia de caracteres, matriz e data). So armazenados em um local especificado pelo aplicativo (dentro do diretrio base do usurio). Nunca so transmitidos entre o cliente e o servidor.

Sobre a classe SharedObject

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Utilize a classe SharedObject para criar e excluir objetos compartilhados e tambm, detectar o tamanho atual do objeto SharedObject que est sendo utilizado. A classe SharedObject composta pelos seguintes mtodos:
Mtodo
clear() flush() getLocal()

Descrio Descarta todos os dados do objeto SharedObject e exclui o arquivo SharedObject do disco. Imediatamente grava o arquivo SharedObject em um arquivo no cliente. Retorna uma referncia ao objeto SharedObject local, especfico do domnio. Se no existir nenhum, esse mtodo criar um novo objeto compartilhado no cliente. Obtm o tamanho do arquivo SharedObject, em bytes. O limite de tamanho padro 100 KB, embora possa ser maior se o cliente permitir.

getSize()

Alm desses mtodos, os objetos SharedObject tm as seguintes propriedades:

Propriedade
data

Descrio Propriedade somente leitura que representa a coleo de atributos que o objeto compartilhado armazena. O manipulador de eventos do objeto compartilhado chamado para cada aviso, erro ou nota informativa.

onStatus

Criao de um objeto compartilhado

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para criar um objeto SharedObject utilize o mtodo SharedObject.getLocal(), que possui a sintaxe a seguir:
SharedObject.getLocal("objectName" [, pathname]): SharedObject

O exemplo a seguir cria um objeto compartilhado denominado mySO:

public var mySO:SharedObject; mySO = SharedObject.getLocal("preferences");

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Armazenamento de dados locais

689

Isso cria um arquivo na mquina do cliente denominado preferences.sol. O termo local faz referncia ao local do objeto compartilhado. Nesse caso, o Adobe Flash Player armazena o arquivo SharedObject localmente no diretrio base do cliente. Quando voc cria um objeto compartilhado, o Flash Player cria um novo diretrio para o aplicativo e o domnio dentro da sua caixa de proteo. Cria, tambm, um arquivo *.sol que armazena os dados do SharedObject. O local padro desse arquivo um subdiretrio no diretrio base do usurio. A tabela a seguir apresenta os locais padro desse diretrio:
Sistema operacional Windows 95/98/ME/2000/XP Windows Vista Macintosh OS X Localizao
c:/Documents and Settings/username/Application Data/Macromedia/Flash Player/#SharedObjects c:/Users/username/AppData/Roaming/Macromedia/Flash Player/#SharedObjects /Users/username/Library/Preferences/Macromedia/Flash Player/#SharedObjects/web_domain/path_to_application/applicatio n_name/object_name.sol /home/username/.macromedia/Flash_Player/#SharedObjects/web_doma in/path_to_application/application_name/object_name.sol

Linux/Unix

Abaixo do diretrio #SharedObjects, est um diretrio nomeado randomicamente. Abaixo desse diretrio, vem um diretrio que corresponde ao nome do host, em seguida, o caminho para o aplicativo e, finalmente, o arquivo *.sol. Por exemplo, se voc solicitar um aplicativo denominado MyApp.swf no host local, dentro de um subdiretrio denominado /sos, o Flash Player armazenar o arquivo *.sol no seguinte local (no Windows XP):
c:/Documents and Settings/fred/Application Data/Macromedia/Flash Player/#SharedObjects/KROKWXRK/#localhost/sos/MyApp.swf/data.sol

Nota: Se voc no prover um nome no mtodo SharedObject.getLocal(), o Flash Player nomear o arquivo .sol indefinido. Por padro, o Flash pode salvar objetos SharedObject persistentes de at 100 KB por domnio. Esse valor pode ser configurado pelo usurio. Quando o aplicativo tenta salvar dados para um objeto compartilhado que ultrapassariam 100 KB, o Flash Player exibe a caixa de dilogo Armazenamento local, oferecendo a opo ao usurio de permitir ou negar o armazenamento local para o domnio que est solicitando o acesso.

Especificao de um arquivo
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc pode utillizar o parmetro opcionall pathname para especificar um local no arquivo SharedObject. Esse arquivo deve estar em um subdiretrio do diretrio SharedObject desse domnio. Por exemplo, se voc solicitar um aplicativo no host local e especificar:
mySO = SharedObject.getLocal("myObjectFile","/");

O Flash Player gravar o arquivo SharedObject no diretrio /#localhost (ou /localhost, se o aplicativo estiver offline). Isso ser til caso voc deseje que mais de um aplicativo no cliente seja capaz de acessar o mesmo objeto compartilhado. Nesse caso, o cliente pode executar dois aplicativos Flex, que especifiquem um caminho para o objeto compartilhado que esteja na raiz do domnio, e acessar o mesmo objeto compartilhado em ambos os aplicativos. Para compartilhar dados entre mais de um aplicativo sem persistncia, possvel usar o objeto LocalConnection. Se voc especificar um diretrio no existente, o Flash Player no criar um arquivo SharedObject.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Armazenamento de dados locais

690

Adio de dados a um objeto compartilhado

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Adicione dados a um arquivo SharedObject *.sol utilizando a propriedade data do objeto SharedObject. Para adicionar novos dados ao objeto compartilhado, use a seguinte sintaxe:
sharedObject_name.data.variable = value;

O exemplo a seguir inclui as propriedades userName, itemNumbers e adminPrivileges e seus valores, em um SharedObject:
public var currentUserName:String = "Reiner"; public var itemsArray:Array = new Array(101,346,483); public var currentUserIsAdmin:Boolean = true; mySO.data.userName = currentUserName; mySO.data.itemNumbers = itemsArray; mySO.data.adminPrivileges = currentUserIsAdmin;

Depois de designar valores propriedade data, instrua o Flash Player a grav-los no arquivo do SharedObject. Para forar o Flash Player a gravar os valores no arquivo SharedObject, use o mtodo SharedObject.flush(), como segue:
mySO.flush();

Se voc no chamar o mtodo SharedObject.flush(), o Flash Player gravar os valores no arquivo quando o aplicativo for encerrado. No entanto, isso no conceder ao usurio a oportunidade de aumentar o espao disponvel que o Flash Player ter para armazenar os dados, caso estes excedam as configuraes padro. Assim, chamar SharedObject.flush() uma boa pedida. Ao usar o mtodo flush() para gravar objetos compartilhados em uma unidade de disco rgido do usurio, verifique atentamente se o usurio desativou explicitamente o armazenamento local usando o Gerenciador de configuraes do Flash Player (www.macromedia.com/support/documentation/en/flashplayer/help/settings_manager07.html), conforme mostrado no exemplo a seguir:
var so:SharedObject = SharedObject.getLocal("test"); trace("Current SharedObject size is " + so.size + " bytes."); so.flush();

Armazenamento de objetos em objetos compartilhados Voc pode armazenar objetos simples, como Matrizes ou Sequncias de caracteres, em uma propriedade data do SharedObject. O exemplo a seguir uma classe ActionScript que define os mtodos que controlam a interao com o objeto compartilhado. Estes mtodos permitem que o usurio adicione e remova objetos do objeto compartilhado. Esta classe armazena uma ArrayCollection que contm objetos simples.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Armazenamento de dados locais

691

package { import mx.collections.ArrayCollection; import flash.net.SharedObject; public class LSOHandler { private var mySO:SharedObject; private var ac:ArrayCollection; private var lsoType:String; // The parameter is "feeds" or "sites". public function LSOHandler(s:String) { init(s); } private function init(s:String):void { ac = new ArrayCollection(); lsoType = s; mySO = SharedObject.getLocal(lsoType); if (getObjects()) { ac = getObjects(); } } public function getObjects():ArrayCollection { return mySO.data[lsoType]; } public function addObject(o:Object):void { ac.addItem(o); updateSharedObjects(); } private function updateSharedObjects():void { mySO.data[lsoType] = ac; mySO.flush(); } } }

O aplicativo Flex a seguir cria uma instncia da classe ActionScript para cada um dos tipos de objetos compartilhados de que necessita. Em seguida, chama mtodos nessa classe quando o usurio adiciona ou remove blogs ou URLs de sites.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Armazenamento de dados locais

692

<?xml version="1.0"?> <!-- lsos/BlogAggregator.mxml --> <mx:Application xmlns:local="*" xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="initApp()" backgroundColor="#ffffff" > <mx:Script> <![CDATA[ import mx.collections.ArrayCollection; import mx.utils.ObjectUtil; import flash.net.SharedObject; [Bindable] public var welcomeMessage:String; [Bindable] public var localFeeds:ArrayCollection = new ArrayCollection(); [Bindable] public var localSites:ArrayCollection = new ArrayCollection(); public var lsofeeds:LSOHandler; public var lsosites:LSOHandler; private function initApp():void { lsofeeds = new LSOHandler("feeds"); lsosites = new LSOHandler("sites"); if (lsofeeds.getObjects()) { localFeeds = lsofeeds.getObjects(); } if (lsosites.getObjects()) { localSites = lsosites.getObjects(); } } // Adds a new feed to the feeds DataGrid. private function addFeed():void { // Construct an object you want to store in the // LSO. This object can contain any number of fields. var o:Object = {name:ti1.text, url:ti2.text, date:new Date()}; lsofeeds.addObject(o); // Because the DataGrid's dataProvider property is // bound to the ArrayCollection, Flex updates the // DataGrid when you call this method. localFeeds = lsofeeds.getObjects(); // Clear the text fields. ti1.text = ''; ti2.text = ''; } // Removes feeds from the feeds DataGrid. private function removeFeed():void {

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Armazenamento de dados locais

693

// // // // // if

Use a method of ArrayCollection to remove a feed. Because the DataGrid's dataProvider property is bound to the ArrayCollection, Flex updates the DataGrid when you call this method. You do not need to update it manually. (myFeedsGrid.selectedIndex > -1) {

localFeeds.removeItemAt(myFeedsGrid.selectedIndex); } } private function addSite():void { var o:Object = {name:ti3.text, date:new Date()}; lsosites.addObject(o); localSites = lsosites.getObjects(); ti3.text = ''; } private function removeSite():void { if (mySitesGrid.selectedIndex > -1) { localSites.removeItemAt(mySitesGrid.selectedIndex); } } ]]> </mx:Script> <mx:Label text="Blog aggregator" fontSize="28"/> <mx:Panel title="Blogs"> <mx:Form id="blogForm"> <mx:HBox> <mx:FormItem label="Name:"> <mx:TextInput id="ti1" width="100"/> </mx:FormItem> <mx:FormItem label="Location:"> <mx:TextInput id="ti2" width="300"/> </mx:FormItem> <mx:Button id="b1" label="Add Feed" click="addFeed()"/> </mx:HBox> <mx:FormItem label="Existing Feeds:"> <mx:DataGrid id="myFeedsGrid" dataProvider="{localFeeds}" width="400" /> </mx:FormItem> <mx:Button id="b2" label="Remove Feed" click="removeFeed()"/> </mx:Form> </mx:Panel> <mx:Panel title="Sites">

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Armazenamento de dados locais

694

<mx:Form id="siteForm"> <mx:HBox> <mx:FormItem label="Site:"> <mx:TextInput id="ti3" width="400"/> </mx:FormItem> <mx:Button id="b3" label="Add Site" click="addSite()"/> </mx:HBox> <mx:FormItem label="Existing Sites:"> <mx:DataGrid id="mySitesGrid" dataProvider="{localSites}" width="400" /> </mx:FormItem> <mx:Button id="b4" label="Remove Site" click="removeSite()"/> </mx:Form> </mx:Panel> </mx:Application>

Armazenamento de objetos com tipo em objetos compartilhados. possvel armazenar instncias do ActionScript com tipo em objetos compartilhados. Isso feito chamando o mtodo flash.net.registerClassAlias() para registrar a classe. Se voc criar uma instncia da classe e armazen-la no membro de dados do objeto compartilhado e, posteriormente, ler o objeto, obter uma instncia com tipo. Por padro, a propriedade objectEncoding do SharedObject tem suporte para a codificao AMF3 e extrai a instncia armazenada do objeto SharedObject; a instncia armazenada retm o mesmo tipo especificado quando voc chamou o mtodo registerClassAlias().

Criao de vrios objetos compartilhados

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior possvel criar vrios objetos compartilhados para o mesmo aplicativo Flex. Para fazer isso, designe a cada um deles um nome da instncia diferente, como no exemplo a seguir:
public var mySO:SharedObject = SharedObject.getLocal("preferences"); public var mySO2:SharedObject = SharedObject.getLocal("history");

Isso criar os arquivos preferences.sol e history.sol no diretrio local do aplicativo Flex.

Criao de um SharedObject seguro

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Ao criar um SharedObject remoto ou local usando getLocal() ou getRemote(), h um parmetro opcional denominado secure que determina se o acesso a esse objeto compartilhado restrito para arquivos SWF que so entregues por uma conexo HTTPS. Se esse parmetro estiver definido como true e o arquivo SWF for entregue por HTTPS, o Flash Player criar um novo objeto compartilhado protegido ou obter uma referncia a um objeto compartilhado protegido existente. Esse objeto compartilhado protegido pode ser lido ou gravado apenas por arquivos SWF entregues por HTTPS que chamam SharedObject.getLocal() com o parmetro secure definido como true. Se esse parmetro estiver definido como false e o arquivo SWF for entregue por HTTPS, o Flash Player criar um novo objeto compartilhado ou obter uma referncia a um objeto compartilhado existente.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Armazenamento de dados locais

695

Esse objeto compartilhado pode ser lido ou gravado por arquivos SWF entregues por conexes no-HTTPS. Se o arquivo SWF for entregue por uma conexo no-HTTPS e voc tentar definir esse parmetro como true, haver uma falha na criao de um novo objeto compartilhado (ou o acesso de um objeto compartilhado protegido criado anteriormente), um erro ser emitido e o objeto compartilhado ser definido como null. Se voc tentar executar o seguinte snippet em uma conexo no-HTTPS, o mtodo SharedObject.getLocal() emitir um erro:
try { var so:SharedObject = SharedObject.getLocal("contactManager", null, true); } catch (error:Error) { trace("Unable to create SharedObject."); }

Independentemente do valor desse parmetro, os objetos compartilhados criados sero levados em considerao na contagem da quantidade total de espao em disco permitida para um domnio.

Exibio de contedo de um objeto compartilhado

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os valores so armazenados em objetos compartilhados dentro da propriedade data. Voc pode executar um loop em cada valor dentro de uma ocorrncia do objeto compartilhado usando um loop for..in, conforme mostrado no exemplo a seguir:
var so:SharedObject = SharedObject.getLocal("test"); so.data.hello = "world"; so.data.foo = "bar"; so.data.timezone = new Date().timezoneOffset; for (var i:String in so.data) { trace(i + ":\t" + so.data[i]); }

Destruio de objetos compartilhados

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para destruir um SharedObject no cliente, use o mtodo SharedObject.clear(). Isso no destruir os diretrios no caminho padro dos objetos compartilhados do aplicativo. O exemplo a seguir exclui o arquivo SharedObject do cliente:
public function destroySharedObject():void { mySO.clear(); }

Exemplo de SharedObject
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O exemplo a seguir demonstra que possvel armazenar objetos simples como, por exemplo, Date em um objeto SharedObject sem a necessidade de serializar e desserializar esses objteos.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Armazenamento de dados locais

696

Este exemplo inicia dando boas-vindas a voc pela sua primeira visita. Assim que voc clicar em Log Out, o aplicativo armazenar a data atual em um objeto compartilhado. Na prxima vez que iniciar o aplicativo ou atualizar a pgina, o aplicativo dar boas-vindas pelo seu retorno, com um lembrete sobre o tempo em que esteve desconectado. Para ver o aplicativo em ao, inicie o aplicativo, clique em Log Out e atualize a pgina. O aplicativo exibir a data e hora em que voc clicou no boto Log Out na visita anterior. A qualquer momento, possvel excluir as informaes armazenadas clicando no boto Excluir LSO.
<?xml version="1.0"?> <!-- lsos/WelcomeMessage.mxml --> <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" initialize="initApp()"> <mx:Script><![CDATA[ public var mySO:SharedObject; [Bindable] public var welcomeMessage:String; public function initApp():void { mySO = SharedObject.getLocal("mydata"); if (mySO.data.visitDate==null) { welcomeMessage = "Hello first-timer!" } else { welcomeMessage = "Welcome back. You last visited on " + getVisitDate(); } } private function getVisitDate():Date { return mySO.data.visitDate; } private function storeDate():void { mySO.data.visitDate = new Date(); mySO.flush(); } private function deleteLSO():void { // Deletes the SharedObject from the client machine. // Next time they log in, they will be a 'first-timer'. mySO.clear(); } ]]></mx:Script> <mx:Label id="label1" text="{welcomeMessage}"/> <mx:Button label="Log Out" click="storeDate()"/> <mx:Button label="Delete LSO" click="deleteLSO()"/> </mx:Application>

Armazenamento local criptografado

O tempo de execuo do Adobe AIR fornece um armazenamento local criptografado (ELS) persistente para cada aplicativo AIR instalado no computador de um usurio. Isto permite que voc salve e recupere dados armazenados no disco local do usurio em formato criptografado que no pode ser facilmente decifrado por outros usurios. Um armazenamento local criptografado separado usado para cada aplicativo AIR, e cada aplicativo AIR usa um armazenamento local criptografado separado para cada usurio.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Armazenamento de dados locais

697

Nota: Alm do armazenamento local criptografado, o AIR tambm fornece criptografia para contedo armazenado em bancos de dados do SQL. Para obter detalhes, consulte Uso da criptografia com bancos de dados SQL na pgina 746. Voc pode querer utilizar o armazenamento local criptografado para colocar em cache informaes que precisam ser protegidas como, por exemplo, credenciais de login para servios web. O ELS apropriado para armazenar informaes que precisam ser mantidas e forma particular. No entanto, ele no protege os dados contra outros processos executados da mesma conta de usurio. Por esse motivo, ele no apropriado para proteger dados secretos de aplicativos como, por exemplo, informaes de DRM e chaves de criptografia. O AIR usa o DPAPI no Windows, o KeyChain no Mac OS e o KeyRing ou KWallet no Linux para associar o armazenamento local criptografado a cada aplicativo e usurio. O armazenamento local criptografado usa a criptografia AES-CBC de 128 bits. As informaes no armazenamento local criptografado esto disponveis apenas a contedo de aplicativos AIR na caixa de proteo de segurana do aplicativo. Se voc atualizar um aplicativo AIR, a verso atualizada mantm o acesso dos dados existentes no armazenamento local criptografado, a no ser que:

Itens adicionados com o parmetro stronglyBound definido em true As verses existentes e atualizadas so publicadas com antecedncia no AIR 1.5.3 e a atualizao assinada com
uma assinatura de migrao. Limitaes do armazenamento local criptografado Os dados no armazenamento local criptografado so protegidos pelas credenciais da conta de sistema operacional do usurio. Outras entidades no podem acessar os dados no armazenamento a menos que possam fazer login como aquele usurio. No entanto, os dados no ficam protegidos contra o acesso de outros aplicativos executados por um usurio autenticado. Como o usurio deve ser autenticado para que esses ataques funcionem, os dados privados do usurio ainda esto protegidos (a menos que a prpria conta do usurio esteja comprometida). No entanto, os dados que o seu aplicativo deseja manter em segredo, como as chaves usadas para licenciamento ou o gerenciamento de direitos digitais, no esto seguros. Assim, o ELS no um local adequado para armazenar essas informaes. Isto somente um local apropriado para armazenar dados particulares do usurio como, por exemplo, senhas. Os dados no ELS podem ser perdidos por diversos motivos. Por exemplo, o usurio pode desinstalar o aplicativo e excluir o arquivo criptografado. Ou o ID do publicador pode ser alterado como resultado de uma atualizao. Dessa forma, o ELS deve ser tratado como um cache particular e no um armazenamento de dados permanente. O parmetro stronglyBound foi descontinuado e no deve ser definido como true. Nenhuma proteo adicional fornecida aos dados se o parmetro for definido como true. Ao mesmo tempo, o acesso aos dados perdido sempre que um aplicativo atualizado mesmo se o ID do publicador permanecer o mesmo. O armazenamento local criptografado poder ficar mais lento se os dados armazenados excederem 10 MB. Quando voc desinstala um aplicativo AIR, o desinstalador no exclui os dados armazenados no armazenamento local criptografado. Entre as prticas recomendadas para usar o ELS esto:

Use o ELS para armazenar dados importantes do usurio, como senhas (definindo stronglyBound como false) No use o ELS para armazenar os segredos dos aplicativos como chaves de DRM ou tokens de licenciamento. Fornece uma forma de seu aplicativo recriar os dados armazenados no ELS se os dados do ELS forem perdidos. Por
exemplo, ao solicitar que o usurio digite novamente as credenciais de conta quando necessrio.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Armazenamento de dados locais

698

No utilizar o parmetro stronglyBound. Se voc definir o parmetro stronglyBound como true, no migre os itens armazenados durante uma atualizao.
Em vez disso, recrie os dados aps a atualizao.

Somente armazene quantidades relativamente pequenas de dados. Para grandes quantidades de dados, utilize o
banco de dados SQL do AIR criptografia.

Mais tpicos da Ajuda

flash.data.EncryptedLocalStore

Incluso de dados no armazenamento local criptografado

Use o mtodo esttico setItem() da classe EncryptedLocalStore para armazenar os dados no armazenamento local. Os dados so armazenados em uma tabela de hash, usando seqncias de caracteres como chaves, com os dados armazenados como matrizes de bytes. Por exemplo, o cdigo a seguir armazena uma seqncia de caracteres no armazenamento local criptografado:
var str:String = "Bob"; var bytes:ByteArray = new ByteArray(); bytes.writeUTFBytes(str); EncryptedLocalStore.setItem("firstName", bytes);

O terceiro parmetro do mtodo setItem(), o parmetro stronglyBound, opcional. Quando este parmetro est definido em true, o armazenamento local criptografado associa o item armazenado ao aplicativo aos bits e assinatura do aplicativo AIR:
var str:String = "Bob"; var bytes:ByteArray = new ByteArray(); bytes.writeUTFBytes(str); EncryptedLocalStore.setItem("firstName", bytes, false);

Para um item armazenado com stronglyBound definido como true, as chamadas subseqentes a getItem() apenas so bem-sucedidas se o aplicativo AIR de chamada for idntico ao aplicativo de armazenamento (se nenhum dado nos arquivos do diretrio do aplicativo tiver sido alterado). Se o aplicativo AIR de chamada for diferente do aplicativo de armazenamento, o aplicativo lanar uma exceo de erro quando voc chamar getItem() para um item fortemente ligado. Se voc atualizar seu aplicativo, ele no ser capaz de ler os dados fortemente ligados previamente gravados no armazenamento local criptografado. Se o parmetro stronglyBound estiver definido como false (o padro), s o ID da editora precisa se manter igual para que o aplicativo leia os dados. Os bits do aplicativo podem mudar (e precisam ser atribudos pelo mesmo editor), mas no precisam ser exatamente os mesmos bits que eram no aplicativo que armazenou os dados. Aplicativos atualizados com o mesmo ID do publicado do original podem continuar a acessar os dados. Nota: Na prtica, configurar stronglyBound para true no adiciona nenhuma proteo adicional aos dados. Um usurio mal intencionado ainda pode alterar um aplicativo para obter acesso a itens gravados no ELS. Alm disso, os dados so protegidos de ameaas externas, mesmo se stronglyBound estiver definiddo em true ou false. Por esses motivos, no encorajamos definir stronglyBound em true.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Armazenamento de dados locais

699

Acesso aos dados no armazenamento local criptografado

Adobe AIR 1.0 e posterior Voc pode recuperar um valor do armazenamento local criptografado usando o mtodo EncryptedLocalStore.getItem(), como no seguinte exemplo:
var storedValue:ByteArray = EncryptedLocalStore.getItem("firstName"); trace(storedValue.readUTFBytes(storedValue.length)); // "Bob"

Remoo de dados do armazenamento local criptografado

Adobe AIR 1.0 e posterior Voc pode excluir um valor do armazenamento local criptografado usando o mtodo EncryptedLocalStore.removeItem(), como no seguinte exemplo:
EncryptedLocalStore.removeItem("firstName");

Voc pode limpar todos os dados do armazenamento local criptografado chamando o mtodo EncryptedLocalStore.reset(), como no seguinte exemplo:
EncryptedLocalStore.reset();

ltima atualizao em 29/3/2011

700

Captulo 38: Trabalho com bancos de dados SQL locais no AIR

Adobe AIR 1.0 e posterior O Adobe AIR permite criar e trabalhar com bancos de dados SQL locais. O tempo de execuo inclui um mecanismo de banco de dados SQL com suporte para muitos recursos SQL padro atravs do sistema de banco de dados de cdigofonte aberto SQLite. Um banco de dados SQL local pode ser usado para armazenar dados locais persistentes. Por exemplo, ele pode ser usado para dados de aplicativo, configuraes de usurios de aplicativo, documentos ou qualquer outro tipo de dados que voc desejar que o aplicativo salve localmente.

Sobre bancos de dados SQL locais

Adobe AIR 1.0 e posterior Veja uma explicao rpida e exemplos de cdigos para o uso de bancos de dados SQL nos seguintes artigos de apresentao rpida do Adobe Developer Connection:

Trabalho assncrono com um banco de dados SQL local (Flex) Trabalhar sincronamente com um banco de dados SQL local) (Flex) Usar banco de dados criptografado (Flex) Trabalhar assincronamente com um banco de dados SQL local (Flash) Trabalhar sincronamente com um banco de dados SQL local (Flash) Usar banco de dados criptografado (Flash)
O Adobe AIR inclui um mecanismo de banco de dados relacional baseado em SQL que executado no tempo de execuo, com dados armazenados localmente em arquivos de banco de dados no computador em que o aplicativo AIR executado (no disco rgido do computador, por exemplo). Como a execuo do banco de dados ocorre localmente, da mesma forma que o armazenamento dos arquivos de dados, um banco de dados pode ser usado por um aplicativo AIR independentemente de haver uma conexo de rede disponvel. Por isso, o mecanismo de banco de dados SQL local do tempo de execuo conveniente para armazenar dados de aplicativo locais persistentes, principalmente se voc tem experincia em SQL e bancos de dados relacionais.

Usos de bancos de dados SQL locais

Adobe AIR 1.0 e posterior A funcionalidade de banco de dados SQL local do AIR pode ser utilizada para qualquer finalidade quando voc quiser armazenar dados de aplicativo no computador local de um usurio. O Adobe AIR inclui diversos mecanismos para armazenar dados localmente, e cada um deles tem suas prprias vantagens. Veja abaixo alguns dos usos possveis de um banco de dados SQL local no aplicativo AIR:

No caso de um aplicativo orientado a dados (um catlogo de endereos, por exemplo), possvel usar um banco de
dados para armazenar os principais dados de aplicativo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

701

No caso de um aplicativo orientado a documento, em que os usurios criam documentos para salv-los e
possivelmente compartilh-los, cada documento pode ser salvo como um arquivo de banco de dados em um local designado pelo usurio. (Observe, no entanto, que a menos que o banco de dados seja criptografado, qualquer aplicativo AIR poderia abrir o arquivo do banco de dados. A criptografia recomendada para documentos potencialmente confidenciais.)

No caso de um aplicativo com reconhecimento de rede, possvel usar um banco de dados para armazenar um
cache local de dados de aplicativo ou para armazenar dados temporariamente quando no h uma conexo de rede disponvel. Voc pode criar um mecanismo para sincronizar o banco de dados local com o armazenamento de dados da rede.

No caso de qualquer aplicativo, um banco de dados pode ser usado para armazenar configuraes de aplicativo de
um usurio, como opes ou informaes do aplicativo (por exemplo, o tamanho e a posio das janelas).

Mais tpicos da Ajuda

Christophe Coenraets: diretrio de funcionrios no AIR para Android Raymond Camden: jQuery e AIR - Movimentao da pgina da Web para o aplicativo

Sobre bancos de dados do AIR e arquivos de banco de dados

Adobe AIR 1.0 e posterior Um banco de dados SQL local do Adobe AIR armazenado como um nico arquivo no sistema de arquivos do computador. O tempo de execuo inclui o mecanismo de banco de dados SQL que gerencia a criao e a estruturao de arquivos de banco de dados, bem como a manipulao e a recuperao de dados de um arquivo de banco de dados. O tempo de execuo no especifica como ou onde os dados de banco de dados so armazenados no sistema de arquivos; cada banco de dados armazenado por completo em um nico arquivo. Voc especifica o local no sistema de arquivos em que o arquivo do banco de dados deve ser armazenado. Um nico aplicativo AIR pode acessar um ou vrios bancos de dados separados (isto , arquivos de banco de dados separados). Como o tempo de execuo armazena cada banco de dados como um nico arquivo no sistema de arquivos, voc pode localizar o seu banco de dados quando necessrio pelo design das restries do sistema operacional quanto ao acesso a aplicativos e arquivos. Cada usurio pode ter um arquivo de banco de dados parte para seus dados especficos, ou um arquivo de banco de dados pode ser acessado por todos os usurios do aplicativo em um nico computador para dados compartilhados. Como os dados esto armazenados localmente em um nico computador, eles no so compartilhados automaticamente em diferentes computadores. O mecanismo de banco de dados SQL local no tem um recurso que permita executar instrues SQL em um banco de dados remoto ou baseado em servidor.

Sobre bancos de dados relacionais

Adobe AIR 1.0 e posterior Um banco de dados relacional consiste em um mecanismo para armazenar (e recuperar) dados em um computador. Os dados so organizados em tabelas: as linhas representam registros ou itens, e as colunas (tambm chamadas de campos) dividem cada registro em valores individuais. Por exemplo, um aplicativo de catlogo de endereos pode conter uma tabela chamada amigos. Cada linha da tabela representa um nico amigo armazenado no banco de dados. As colunas da tabela representam dados como nome, sobrenome, data de nascimento e assim por diante. Para cada linha de amigo na tabela, o banco de dados armazena um valor em separado para cada coluna.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

702

Os bancos de dados relacionais tm a finalidade de armazenar dados complexos, em que um item associado ou relacionado a itens de outro tipo. Em um banco de dados relacional, qualquer dado que tem um relacionamento umpara-muitos em que um nico registro pode estar relacionado a vrios registros de um tipo diferente deve ser dividido entre diferentes tabelas. Por exemplo, suponha que voc queira que o aplicativo de catlogo de endereos armazene vrios nmeros de telefone de cada amigo; isto um relacionamento um-para-muitos. A tabela amigos contm todas as informaes pessoais de cada amigo. Uma tabela parte chamada nmeros de telefone contm todos os nmeros de telefone de todos os amigos. Alm de armazenar os dados de amigos e os nmeros de telefone, cada tabela precisa de dados para controlar os relacionamentos entre as duas tabelas a fim de comparar registros de amigo individuais com seus nmeros de telefone. Esses dados so chamados de chave primria, um identificador exclusivo que diferencia cada linha de uma tabela das demais linhas dessa tabela. A chave primria pode ser uma chave natural, ou seja, um dos itens de dados que diferencia cada registro de uma tabela naturalmente. Na tabela amigos, se voc souber que nenhum dos seus amigos tem a mesma data de aniversrio, poder usar a coluna de data de nascimento como a chave primria (uma chave natural) dessa tabela. Se no houver uma chave natural, crie uma coluna de chave primria em separado, como id de amigo: um valor artificial que o aplicativo usa para diferenciar entre as linhas. Utilizando uma chave primria, voc pode configurar relacionamentos entre vrias tabelas. Por exemplo, suponha que na tabela "amigos" exista uma coluna chamada "id de amigo", que contm um nmero exclusivo para cada linha (cada amigo). A tabela nmeros de telefone relacionada pode ser estruturada com duas colunas: uma com o id de amigo do amigo a quem pertence o nmero de telefone e outra com o nmero de telefone propriamente dito. Assim, independentemente de quantos nmeros de telefones um s amigo tiver, todos podero ser armazenados na tabela nmeros de telefone e vinculados ao amigo relacionado atravs da chave primria id de amigo. Quando uma chave primria de uma tabela usada em uma tabela relacionada para especificar a conexo entre os registros, o valor contido na tabela chamado de chave externa. Diferentemente de muitos bancos de dados, o mecanismo de banco de dados local do AIR no permite criar restries de chave externa, que so restries que automaticamente verificam se um valor de chave externa inserido ou atualizado tem uma linha correspondente na tabela de chave primria. Todavia, os relacionamentos de chave externa so uma parte importante da estrutura de um banco de dados relacional, e as chaves externas devem ser usadas quando voc cria relacionamentos entre as tabelas do banco de dados.

Sobre a SQL
Adobe AIR 1.0 e posterior A SQL (linguagem de consulta estruturada) usada com bancos de dados relacionais para manipular e recuperar dados. A SQL uma linguagem descritiva e no de procedimento. Em vez de dar ao computador instrues sobre como recuperar dados, uma instruo SQL descreve o conjunto de dados desejado. O mecanismo de banco de dados determina como recuperar esses dados. A linguagem SQL foi padronizada pelo ANSI (American National Standards Institute). O banco de dados SQL local do Adobe AIR oferece suporte maior parte do padro SQL-92. Para obter descries especficas da linguagem SQL suportada no Adobe AIR, consulte Suporte SQL em bancos de dados locais na pgina 1093.

Sobre classes de banco de dados SQL

Adobe AIR 1.0 e posterior Para trabalhar com bancos de dados SQL locais no ActionScript 3.0, voc deve usar ocorrncias destas classes do pacote flash.data:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

703

Classe flash.data.SQLConnection

Descrio Oferece um modo de criar e abrir bancos de dados (arquivos de banco de dados), bem como mtodos para executar operaes no nvel de banco de dados e controlar transaes de banco de dados. Representa uma nica instruo SQL (uma nica consulta ou comando) que executada em um banco de dados, incluindo a definio do texto da instruo e a configurao dos valores de parmetro. Oferece um modo de obter informaes sobre execuo de uma instruo ou os resultados dela, como as linhas de resultado de uma instruo SELECT, o nmero de linhas afetadas por uma instruo UPDATE ou DELETE e assim por diante.

flash.data.SQLStatement

flash.data.SQLResult

Para obter informaes de esquema que descrevam a estrutura de um banco de dados, use estas classes do pacote flash.data:
Classe flash.data.SQLSchemaResult Descrio Funciona como um continer de resultados do esquema de banco de dados gerados pela chamada do mtodo SQLConnection.loadSchema(). Fornece informaes que descrevem uma nica tabela de um banco de dados. Fornece informaes que descrevem uma nica visualizao de um banco de dados. Fornece informaes que descrevem uma nica coluna de uma tabela ou visualizao de um banco de dados. Fornece informaes que descrevem um nico disparador de um banco de dados.

flash.data.SQLTableSchema flash.data.SQLViewSchema flash.data.SQLIndexSchema

flash.data.SQLTriggerSchem a

Outras classes do pacote flash.data fornecem constantes que so utilizadas com as classes SQLConnection e SQLColumnSchema:
Classe flash.data.SQLMode Descrio Define um conjunto de constantes que representam os possveis valores do parmetro openMode dos mtodos SQLConnection.open() e SQLConnection.openAsync(). Define um conjunto de constantes que representam os possveis valores da propriedade
SQLConnection.columnNameStyle.

flash.data.SQLColumnNameStyle

flash.data.SQLTransactionLockType Define um conjunto de constantes que representam os possveis valores do parmetro de opo do mtodo SQLConnection.begin(). flash.data.SQLCollationType Define um conjunto de constantes que representam os valores possveis para a propriedade
SQLColumnSchema.defaultCollationType e o parmetro defaultCollationType do construtor SQLColumnSchema().

Alm disso, as seguintes classes do pacote flash.events representam os eventos (e as constantes de suporte) que voc utiliza:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

704

Classe flash.events.SQLEvent

Descrio Define os eventos que uma ocorrncia de SQLConnection ou SQLStatement despacha quando alguma de suas operaes executada com xito. Cada operao tem uma constante de tipo de evento associada definida na classe SQLEvent. Define o evento que uma ocorrncia de SQLConnection ou SQLStatement despacha quando alguma de suas operaes resulta em erro.

flash.events.SQLErrorEvent

flash.events.SQLUpdateEven Define o evento que uma ocorrncia de SQLConnection despacha quando dados de tabela de um dos t bancos de dados conectados so alterados como resultado da execuo de uma instruo SQL INSERT, UPDATE ou DELETE.

Para finalizar, as seguintes classes do pacote flash.errors fornecem informaes sobre erros de operao do banco de dados:
Classe flash.errors.SQLError Descrio Fornece informaes sobre um erro de funcionamento do banco de dados, incluindo a operao que foi tentada e a causa da falha. Define um conjunto de constantes que representam os valores possveis para a propriedade operation da classe SQLError, que indica a operao de banco de dados que resultou em erro.

flash.errors.SQLErrorOperati on

Sobre modos de execuo sncrona e assncrona

Adobe AIR 1.0 e posterior Quando voc cria cdigo para trabalhar com um banco de dados SQL local, especifica que a execuo das operaes de banco de dados ocorra de um destes dois modos de execuo: modo de execuo assncrona ou sncrona. Em geral, os exemplos de cdigo mostram como executar cada operao das duas maneiras, para que voc possa usar o exemplo mais adequado s suas necessidades. No modo de execuo assncrona, voc d uma instruo ao tempo de execuo, que despacha um evento quando a operao solicitada concluda ou quando falha. Primeiro voc instrui o mecanismo de banco de dados a executar uma operao. O mecanismo de banco de dados trabalha em segundo plano enquanto o aplicativo continua a executar. Por ltimo, quando a operao concluda (ou se falha), o mecanismo de banco de dados despacha um evento. O seu cdigo, disparado pelo evento, executa operaes subseqentes. Esta abordagem tem uma vantagem significativa: o tempo de execuo realiza as operaes de banco de dados em segundo plano enquanto o cdigo do aplicativo principal continua en execuo. Se a operao de banco de dados demorar muito tempo, o aplicativo continuar executando. O mais importante que o usurio pode continuar a interagir com ele sem que a tela congele. Entretanto, o cdigo de operao assncrona pode ser mais complexo de criar do que outro cdigo. Essa complexidade geralmente ocorre quando vrias operaes dependentes devem ser divididas entre diversos mtodos de ouvinte de evento. Em termos conceituais, mais fcil codificar operaes como uma seqncia simples de etapas (um conjunto de operaes sncronas) e no como um conjunto de operaes divididas em vrios mtodos de ouvinte de evento. Alm das operaes de banco de dados assncronas, o Adobe AIR tambm permite executar operaes de banco de dados de maneira sncrona. No modo de execuo sncrona, as operaes no so executadas em segundo plano. Elas ocorrem na mesma seqncia de execuo que todos os outros cdigos de aplicativo. Voc instrui o mecanismo de banco de dados a executar uma operao. Em seguida, o cdigo pausa nesse ponto enquanto o mecanismo de banco de dados faz o seu trabalho. Quando a operao concluda, a execuo prossegue com a prxima linha do cdigo que voc criou.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

705

O fato de as operaes serem executadas de maneira assncrona ou sncrona definido no nvel de SQLConnection. Usando uma nica conexo de banco de dados, voc no consegue executar algumas operaes ou instrues em modo sncrono e outras em modo assncrono. Voc especifica se uma classe SQLConnection opera no modo de execuo sncrono ou assncrono chamando um mtodo SQLConnection para abrir o banco de dados. Se voc chamar SQLConnection.open(), a conexo funcionar no modo de execuo sncrona; se voc chamar SQLConnection.openAsync(), ela funcionar no modo de execuo assncrona. Uma vez que uma ocorrncia de SQLConnection conectada a um banco de dados usando open() ou openAsync(), ela fixada ao modo de execuo sncrona ou assncrona, a menos que voc feche e reabra a conexo com o banco de dados. Cada modo de execuo tem suas vantagens. Apesar da semelhana entre a maioria dos aspectos de cada modo, existem algumas diferenas das quais voc deve se lembrar quando trabalhar neles. Para obter mais informaes sobre estes tpicos, e sugestes de como trabalhar em cada modo, consulte Uso de operaes de banco de dados sncronas e assncronas na pgina 740.

Criao e modificao de um banco de dados

Adobe AIR 1.0 e posterior Para que o seu aplicativo adicione ou recupere dados, deve haver um banco de dados com tabelas definidas nele que possam ser acessadas pelo aplicativo. Descrevemos aqui as tarefas de criao de um banco de dados e da estrutura de dados de um banco de dados. Embora usadas com menos freqncia do que a insero e a recuperao de dados, estas tarefas so necessrias para a maioria dos aplicativos.

Mais tpicos da Ajuda

Lembre-se do Flex: Carregamento de um banco de dados existente do AIR

Criao de um banco de dados

Adobe AIR 1.0 e posterior Para criar um arquivo de banco de dados, primeiro voc deve criar uma instncia do SQLConnection. Chame o mtodo open() correspondente para abri-la no modo de execuo sncrona ou o mtodo openAsync() para abri-la no modo de execuo assncrona. Os mtodos open() e openAsync() so usados para abrir uma conexo com um banco de dados. Se voc passar uma ocorrncia de File que se refira a um local de arquivo no existente para o parmetro reference (o primeiro parmetro), o mtodo open() ou openAsync() criar um arquivo de banco de dados no local do arquivo e abrir uma conexo com o banco de dados recm-criado. Independentemente de voc chamar o mtodo open() ou openAsync() para criar um banco de dados, o nome do arquivo do banco de dados poder ser qualquer nome de arquivo vlido com qualquer extenso de nome de arquivo. Se voc chamar o mtodo open() ou openAsync() com null para o parmetro reference, ser criado um novo banco de dados na memria e no um arquivo de banco de dados no disco. A listagem de cdigo a seguir mostra o processo de criao de um arquivo de banco de dados (um novo banco de dados) usando o modo de execuo assncrona. Nesse caso, o arquivo de banco de dados salvo no Apontar para o diretrio de armazenamento do aplicativo na pgina 657 com o nome de arquivo DBSample.db:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

706

import import import import

flash.data.SQLConnection; flash.events.SQLErrorEvent; flash.events.SQLEvent; flash.filesystem.File;

var conn:SQLConnection = new SQLConnection(); conn.addEventListener(SQLEvent.OPEN, openHandler); conn.addEventListener(SQLErrorEvent.ERROR, errorHandler); // The database file is in the application storage directory var folder:File = File.applicationStorageDirectory; var dbFile:File = folder.resolvePath("DBSample.db"); conn.openAsync(dbFile); function openHandler(event:SQLEvent):void { trace("the database was created successfully"); } function errorHandler(event:SQLErrorEvent):void { trace("Error message:", event.error.message); trace("Details:", event.error.details); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

707

<?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="init()"> <mx:Script> <![CDATA[ import flash.data.SQLConnection; import flash.events.SQLErrorEvent; import flash.events.SQLEvent; import flash.filesystem.File; private function init():void { var conn:SQLConnection = new SQLConnection(); conn.addEventListener(SQLEvent.OPEN, openHandler); conn.addEventListener(SQLErrorEvent.ERROR, errorHandler); // The database file is in the application storage directory var folder:File = File.applicationStorageDirectory; var dbFile:File = folder.resolvePath("DBSample.db"); conn.openAsync(dbFile); } private function openHandler(event:SQLEvent):void { trace("the database was created successfully"); } private function errorHandler(event:SQLErrorEvent):void { trace("Error message:", event.error.message); trace("Details:", event.error.details); } ]]> </mx:Script> </mx:WindowedApplication>

Nota: Embora a classe File permita apontar para um caminho nativo especfico de arquivo, fazer isso pode levar a aplicativos que no funcionam em vrias plataformas. Por exemplo, o caminho C:\Documents and Settings\joe\test.db s funciona no Windows. Por essas razes, melhor usar as propriedades estticas da classe File, como o mtodo File.applicationStorageDirectory e resolvePath() (como mostrado no exemplo anterior). Para obter mais informaes, consulte Caminhos de objetos File na pgina 653. Para executar operaes de maneira sncrona, quando abrir uma conexo de banco de dados com a ocorrncia de SQLConnection, chame o mtodo open(). O seguinte exemplo mostra como criar e abrir uma ocorrncia de SQLConnection que execute suas operaes de maneira sncrona:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

708

import flash.data.SQLConnection; import flash.errors.SQLError; import flash.filesystem.File; var conn:SQLConnection = new SQLConnection(); // The database file is in the application storage directory var folder:File = File.applicationStorageDirectory; var dbFile:File = folder.resolvePath("DBSample.db"); try { conn.open(dbFile); trace("the database was created successfully"); } catch (error:SQLError) { trace("Error message:", error.message); trace("Details:", error.details); } <?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="init()"> <mx:Script> <![CDATA[ import flash.data.SQLConnection; import flash.errors.SQLError; import flash.filesystem.File; private function init():void { var conn:SQLConnection = new SQLConnection(); // The database file is in the application storage directory var folder:File = File.applicationStorageDirectory; var dbFile:File = folder.resolvePath("DBSample.db"); try { conn.open(dbFile); trace("the database was created successfully"); } catch (error:SQLError) { trace("Error message:", error.message); trace("Details:", error.details); } } ]]> </mx:Script> </mx:WindowedApplication>

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

709

Criao de tabelas de banco de dados

Adobe AIR 1.0 e posterior Criar uma tabela em um banco de dados envolve executar uma instruo SQL nesse banco de dados usando o mesmo processo seguido para executar uma instruo SQL, como SELECT, INSERT, entre outras. Para criar uma tabela, use uma instruo CREATE TABLE, que inclui definies de colunas e restries para a nova tabela. Para obter mais informaes sobre como executar instrues SQL, consulte Trabalhar com instrues SQL na pgina 716. O exemplo a seguir demonstra como criar uma tabela chamada employees em um arquivo de banco de dados existente usando o modo de execuo assncrona. Observe que este cdigo presume que h uma instncia de SQLConnection denominada conn j instanciada e conectada a um banco de dados.
import import import import flash.data.SQLConnection; flash.data.SQLStatement; flash.events.SQLErrorEvent; flash.events.SQLEvent;

// ... create and open the SQLConnection instance named conn ... var createStmt:SQLStatement = new SQLStatement(); createStmt.sqlConnection = conn; var sql:String = "CREATE TABLE IF NOT EXISTS employees (" + " empId INTEGER PRIMARY KEY AUTOINCREMENT, " + " firstName TEXT, " + " lastName TEXT, " + " salary NUMERIC CHECK (salary > 0)" + ")"; createStmt.text = sql; createStmt.addEventListener(SQLEvent.RESULT, createResult); createStmt.addEventListener(SQLErrorEvent.ERROR, createError); createStmt.execute(); function createResult(event:SQLEvent):void { trace("Table created"); } function createError(event:SQLErrorEvent):void { trace("Error message:", event.error.message); trace("Details:", event.error.details); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

710

<?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="init()"> <mx:Script> <![CDATA[ import flash.data.SQLConnection; import flash.data.SQLStatement; import flash.events.SQLErrorEvent; import flash.events.SQLEvent; private function init():void { // ... create and open the SQLConnection instance named conn ... var createStmt:SQLStatement = new SQLStatement(); createStmt.sqlConnection = conn; var sql:String = "CREATE TABLE IF NOT EXISTS employees (" + " empId INTEGER PRIMARY KEY AUTOINCREMENT, " + " firstName TEXT, " + " lastName TEXT, " + " salary NUMERIC CHECK (salary > 0)" + ")"; createStmt.text = sql; createStmt.addEventListener(SQLEvent.RESULT, createResult); createStmt.addEventListener(SQLErrorEvent.ERROR, createError); createStmt.execute(); } private function createResult(event:SQLEvent):void { trace("Table created"); } private function createError(event:SQLErrorEvent):void { trace("Error message:", event.error.message); trace("Details:", event.error.details); } ]]> </mx:Script> </mx:WindowedApplication>

O exemplo a seguir demonstra como criar uma tabela chamada employees em um arquivo de banco de dados existente usando o modo de execuo sncrona. Observe que este cdigo presume que h uma instncia de SQLConnection denominada conn j instanciada e conectada a um banco de dados.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

711

import flash.data.SQLConnection; import flash.data.SQLStatement; import flash.errors.SQLError; // ... create and open the SQLConnection instance named conn ... var createStmt:SQLStatement = new SQLStatement(); createStmt.sqlConnection = conn; var sql:String = "CREATE TABLE IF NOT EXISTS employees (" + " empId INTEGER PRIMARY KEY AUTOINCREMENT, " + " firstName TEXT, " + " lastName TEXT, " + " salary NUMERIC CHECK (salary > 0)" + ")"; createStmt.text = sql; try { createStmt.execute(); trace("Table created"); } catch (error:SQLError) { trace("Error message:", error.message); trace("Details:", error.details); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

712

<?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="init()"> <mx:Script> <![CDATA[ import flash.data.SQLConnection; import flash.data.SQLStatement; import flash.errors.SQLError; private function init():void { // ... create and open the SQLConnection instance named conn ... var createStmt:SQLStatement = new SQLStatement(); createStmt.sqlConnection = conn; var sql:String = "CREATE TABLE IF NOT EXISTS employees (" + " empId INTEGER PRIMARY KEY AUTOINCREMENT, " + " firstName TEXT, " + " lastName TEXT, " + " salary NUMERIC CHECK (salary > 0)" + ")"; createStmt.text = sql; try { createStmt.execute(); trace("Table created"); } catch (error:SQLError) { trace("Error message:", error.message); trace("Details:", error.details); } } ]]> </mx:Script> </mx:WindowedApplication>

Manipulao de dados de um banco de dados SQL

Adobe AIR 1.0 e posterior Existem algumas tarefas comuns que voc executa ao trabalhar com bancos de dados SQL locais. Essas tarefas incluem conectar-se a um banco de dados, adicionar dados a tabelas e recuperar dados de tabelas em um banco de dados. Tambm h vrios problemas dos quais voc deve estar ciente quando executa essas tarefas, como trabalhar com tipos de dados e tratar de erros. Alm disso, h diversas tarefas de banco de dados que envolvem coisas com as quais voc lidar menos freqentemente, mas que dever fazer para poder executar essas tarefas mais comuns. Por exemplo, para poder se conectar a um banco de dados e recuperar dados de uma tabela, voc ter de criar o banco de dados e a estrutura de tabelas nele. Essas tarefas de configurao inicial menos freqentes so discutidas em Criao e modificao de um banco de dados na pgina 705.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

713

Voc pode optar por executar operaes de banco de dados assincronamente, o que significa que o mecanismo de banco de dados executado em segundo plano e despacha um evento para notificar o usurio quando a operao bem-sucedida ou quando falha. Tambm possvel executar estas operaes de forma sncrona. Nesse caso, as operaes de banco de dados so executadas uma aps a outra, e o aplicativo inteiro (inclusive atualizaes da tela) espera at que as operaes sejam concludas para poder executar outro cdigo. Para obter mais informaes sobre como trabalhar no modo de execuo assncrona ou sncrona, consulte Uso de operaes de banco de dados sncronas e assncronas na pgina 740.

Conexo com um banco de dados

Adobe AIR 1.0 e posterior Para que voc possa executar qualquer operao de banco de dados, primeiro abra uma conexo com o arquivo de banco de dados. Uma instncia de SQLConnection usada para representar uma conexo com um ou mais bancos de dados. O primeiro banco de dados conectado usando uma ocorrncia de SQLConnection chamado de banco de dados "principal". Esse banco de dados conectado atravs do mtodo open() (para o modo de execuo sncrona) ou do mtodo openAsync() (para o modo de execuo assncrona). Se voc abrir um banco de dados usando a operao openAsync() assncrona, registre-se para o evento open da ocorrncia de SQLConnection para saber quando a operao openAsync() for concluda. Registre-se para o evento error da ocorrncia de SQLConnection para determinar se a operao falhou. O exemplo a seguir mostra como abrir um arquivo de banco de dados existente para execuo assncrona. O arquivo de banco de dados chama-se DBSample.db e est localizado no Apontar para o diretrio de armazenamento do aplicativo na pgina 657 do usurio.
import import import import import flash.data.SQLConnection; flash.data.SQLMode; flash.events.SQLErrorEvent; flash.events.SQLEvent; flash.filesystem.File;

var conn:SQLConnection = new SQLConnection(); conn.addEventListener(SQLEvent.OPEN, openHandler); conn.addEventListener(SQLErrorEvent.ERROR, errorHandler); // The database file is in the application storage directory var folder:File = File.applicationStorageDirectory; var dbFile:File = folder.resolvePath("DBSample.db"); conn.openAsync(dbFile, SQLMode.UPDATE); function openHandler(event:SQLEvent):void { trace("the database opened successfully"); } function errorHandler(event:SQLErrorEvent):void { trace("Error message:", event.error.message); trace("Details:", event.error.details); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

714

<?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="init()"> <mx:Script> <![CDATA[ import flash.data.SQLConnection; import flash.data.SQLMode; import flash.events.SQLErrorEvent; import flash.events.SQLEvent; import flash.filesystem.File; private function init():void { var conn:SQLConnection = new SQLConnection(); conn.addEventListener(SQLEvent.OPEN, openHandler); conn.addEventListener(SQLErrorEvent.ERROR, errorHandler); // The database file is in the application storage directory var folder:File = File.applicationStorageDirectory; var dbFile:File = folder.resolvePath("DBSample.db"); conn.openAsync(dbFile, SQLMode.UPDATE); } private function openHandler(event:SQLEvent):void { trace("the database opened successfully"); } private function errorHandler(event:SQLErrorEvent):void { trace("Error message:", event.error.message); trace("Details:", event.error.details); } ]]> </mx:Script> </mx:WindowedApplication>

O exemplo a seguir mostra como abrir um arquivo de banco de dados existente para execuo sncrona. O arquivo de banco de dados chama-se DBSample.db e est localizado no Apontar para o diretrio de armazenamento do aplicativo na pgina 657 do usurio.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

715

import import import import

flash.data.SQLConnection; flash.data.SQLMode; flash.errors.SQLError; flash.filesystem.File;

var conn:SQLConnection = new SQLConnection(); // The database file is in the application storage directory var folder:File = File.applicationStorageDirectory; var dbFile:File = folder.resolvePath("DBSample.db"); try { conn.open(dbFile, SQLMode.UPDATE); trace("the database opened successfully"); } catch (error:SQLError) { trace("Error message:", error.message); trace("Details:", error.details); } <?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="init()"> <mx:Script> <![CDATA[ import flash.data.SQLConnection; import flash.data.SQLMode; import flash.errors.SQLError; import flash.filesystem.File; private function init():void { var conn:SQLConnection = new SQLConnection(); // The database file is in the application storage directory var folder:File = File.applicationStorageDirectory; var dbFile:File = folder.resolvePath("DBSample.db"); try { conn.open(dbFile, SQLMode.UPDATE); trace("the database opened successfully"); } catch (error:SQLError) { trace("Error message:", error.message); trace("Details:", error.details); } } ]]> </mx:Script> </mx:WindowedApplication>

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

716

Observe que, na chamada do mtodo openAsync() no exemplo de operao assncrona e na chamada do mtodo open() no exemplo de operao sncrona, o segundo argumento a constante SQLMode.UPDATE. Especificar SQLMode.UPDATE para o segundo parmetro (openMode) faz com que o tempo de execuo despache um erro se o arquivo especificado no existe. Caso voc passe SQLMode.CREATE para o parmetro openMode (ou caso deixe o parmetro openMode como off), o tempo de execuo tentar criar um arquivo de banco de dados se o arquivo especificado no existir. No entanto, se o arquivo existir, ser aberto, o que o mesmo que usar SQLMode.Update. Tambm possvel especificar SQLMode.READ para o parmetro openMode para abrir um banco de dados existente em modo somente leitura. Nesse caso, os dados podem ser recuperados do banco de dados, mas no possvel adicionar, excluir ou alterar nenhum dado.

Trabalhar com instrues SQL

Adobe AIR 1.0 e posterior Uma instruo SQL individual (consulta ou comando) representada no tempo de execuo como um objeto SQLStatement. Siga estas etapas para criar e executar uma instruo SQL: Crie uma ocorrncia de SQLStatement. O objeto SQLStatement representa a instruo SQL no seu aplicativo.
var selectData:SQLStatement = new SQLStatement();

Especifique em que banco de dados a consulta executada. Para isso, defina a propriedade sqlConnection do objeto SQLStatement como a ocorrncia de SQLConnection que est conectada ao banco de dados desejado.
// A SQLConnection named "conn" has been created previously selectData.sqlConnection = conn;

Especifique a instruo SQL propriamente dita. Crie o texto da instruo como String e o atribua propriedade text da ocorrncia de SQLStatement.
selectData.text = "SELECT col1, col2 FROM my_table WHERE col1 = :param1";

Defina funes para trabalhar com o resultado da operao de execuo (somente no modo de execuo assncrona). Use o mtodo addEventListener() para registrar funes como ouvintes para os eventos result e error da ocorrncia de SQLStatement.
// using listener methods and addEventListener() selectData.addEventListener(SQLEvent.RESULT, resultHandler); selectData.addEventListener(SQLErrorEvent.ERROR, errorHandler); function resultHandler(event:SQLEvent):void { // do something after the statement execution succeeds } function errorHandler(event:SQLErrorEvent):void { // do something after the statement execution fails }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

717

Se preferir, voc pode especificar mtodos de ouvinte usando um objeto Responder. Nesse caso, crie a ocorrncia de Responder e vincule os mtodos de ouvinte a ela.
// using a Responder (flash.net.Responder) var selectResponder = new Responder(onResult, onError); function onResult(result:SQLResult):void { // do something after the statement execution succeeds } function onError(error:SQLError):void { // do something after the statement execution fails }

Se o texto da instruo incluir definies de parmetro, atribua valores para esses parmetros. Para atribuir valores de parmetro, use a propriedade de matriz associativa parameters da ocorrncia de SQLStatement.
selectData.parameters[":param1"] = 25;

Execute a instruo SQL. Chame o mtodo execute() da ocorrncia de SQLStatement.

// using synchronous execution mode // or listener methods in asynchronous execution mode selectData.execute();

Alm disso, se voc estiver usando um Responder em vez de ouvintes de evento no modo de execuo assncrona, passe a ocorrncia de Responder para o mtodo execute().
// using a Responder in asynchronous execution mode selectData.execute(-1, selectResponder);

Para obter exemplos especficos que demonstrem estas etapas, consulte os seguintes tpicos: Recuperao de dados de um banco de dados na pgina 720 Insero de dados na pgina 730 Alterao ou excluso de dados na pgina 736

Uso de parmetros em instrues

Adobe AIR 1.0 e posterior O uso de parmetros de instruo SQL permite criar uma instruo SQL reutilizvel. Quando voc usa parmetros de instruo, os valores na instruo podem mudar (como os que esto sendo adicionados a uma instruo INSERT), mas seu texto bsico permanece inalterado. Consequentemente, usar parmetros oferece o benefcio do desempenho, alm de facilitar a codificao de um aplicativo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

718

Noes bsicas sobre parmetros de instruo

Adobe AIR 1.0 e posterior freqente um aplicativo usar uma nica instruo SQL vrias vezes, com uma leve variao. Por exemplo, considere um aplicativo de controle de inventrio no qual um usurio pode adicionar itens de inventrio ao banco de dados. O cdigo do aplicativo que adiciona um item de inventrio ao banco de dados executa uma instruo SQL INSERT que, na verdade, adiciona os dados ao banco de dados. No entanto, cada vez que a instruo executada, h uma leve variao. Especificamente, os valores reais inseridos na tabela so diferentes porque so especficos do item de inventrio que est sendo adicionado. Em casos nos quais voc tem uma instruo SQL que usada vrias vezes com diferentes valores na instruo, a melhor abordagem utilizar uma instruo SQL que inclua parmetros em vez de valores literais no texto SQL. Um parmetro consiste em um alocador de espao no texto da instruo que substitudo por um valor real sempre que a instruo executada. Para usar parmetros em uma instruo SQL, crie a instncia de SQLStatement como de costume. No caso da instruo SQL propriamente dita atribuda propriedade text, use alocadores de espao de parmetro em vez de valores literais. Em seguida, defina o valor para cada parmetro definindo o valor de um elemento na propriedade parameters da ocorrncia de SQLStatement. A propriedade parameters uma matriz associativa, por isso voc define um valor em particular usando a seguinte sintaxe:
statement.parameters[parameter_identifier] = value;

parameter_identifier uma string (se voc est usando um parmetro nomeado) ou um ndice de inteiro (se est usando um parmetro sem nome).

Uso de parmetros nomeados

Adobe AIR 1.0 e posterior Um parmetro pode ser um parmetro nomeado. Um parmetro nomeado tem um nome especfico que o banco de dados utiliza para comparar o valor do parmetro localizao do alocador de espao no texto da instruo. Um nome de parmetro consiste no caractere : ou @ seguido de um nome, como nestes exemplos:
:itemName @firstName

A seguinte listagem de cdigo demonstra o uso de parmetros nomeados:

var sql:String = "INSERT INTO inventoryItems (name, productCode)" + "VALUES (:name, :productCode)"; var addItemStmt:SQLStatement = new SQLStatement(); addItemStmt.sqlConnection = conn; addItemStmt.text = sql; // set parameter values addItemStmt.parameters[":name"] = "Item name"; addItemStmt.parameters[":productCode"] = "12345"; addItemStmt.execute();

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

719

Uso de parmetros sem nome

Adobe AIR 1.0 e posterior Como alternativa ao uso de parmetros nomeados, tambm possvel utilizar parmetros sem nome. Para usar um parmetro sem nome, indique um parmetro em uma instruo SQL usando um caractere ? exigido. Cada parmetro recebe um ndice numrico conforme a ordem dos parmetros da instruo, comeando com o ndice 0 para o primeiro parmetro. Este exemplo demonstra uma verso do exemplo anterior usando parmetros sem nome:
var sql:String = "INSERT INTO inventoryItems (name, productCode)" + "VALUES (?, ?)"; var addItemStmt:SQLStatement = new SQLStatement(); addItemStmt.sqlConnection = conn; addItemStmt.text = sql; // set parameter values addItemStmt.parameters[0] = "Item name"; addItemStmt.parameters[1] = "12345"; addItemStmt.execute();

Benefcios do uso de parmetros

Adobe AIR 1.0 e posterior O uso de parmetros em uma instruo SQL proporciona vrios benefcios:
Melhor desempenho Uma ocorrncia de SQLStatement que usa parmetros executada com mais eficincia se

comparada a uma que cria o texto SQL dinamicamente sempre que executada. A melhoria do desempenho ocorre porque a instruo preparada uma nica vez e pode ser executada vrias vezes usando-se diferentes valores de parmetro, sem a necessidade de recompilar a instruo SQL.
Digitao de dados explcita Os parmetros so usados para permitir a substituio de valores digitados que so desconhecidos no momento em que a instruo SQL construda. O uso de parmetros o nico modo de garantir a classe de armazenamento para um valor passado ao banco de dados. Quando parmetros no so usados, o tempo de execuo tenta converter todos os valores de sua representao em texto para uma classe de armazenamento com base na afinidade de tipo da coluna associada.

Para obter mais informaes sobre classes de armazenamento e afinidade de coluna, consulte Suporte ao tipo de dados na pgina 1116.
Mais segurana O uso de parmetros ajuda a impedir uma tcnica mal-intencionada conhecida como ataque de injeo SQL. Em um ataque de injeo SQL, um usurio insere o cdigo SQL em um local acessvel ao usurio (por exemplo, um campo de entrada de dados). Se o cdigo do aplicativo construir uma instruo SQL concatenando diretamente a entrada do usurio no texto SQL, o cdigo SQL inserido pelo usurio ser executado em relao ao banco de dados. A lista a seguir mostra um exemplo de concatenao da entrada do usurio no texto SQL. No use esta tcnica:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

720

// assume the variables "username" and "password" // contain user-entered data var sql:String = "SELECT userId " + "FROM users " + "WHERE username = '" + username + "' " + " AND password = '" + password + "'"; var statement:SQLStatement = new SQLStatement(); statement.text = sql;

O uso de parmetros de instruo em vez de concatenar valores inseridos pelo usurio no texto de uma instruo impede o ataque de injeo SQL. A injeo de SQL no ocorre porque os valores de parmetro so tratados explicitamente como valores substitudos, em vez de se tornarem parte do texto da instruo literal. Esta uma alternativa recomendvel listagem anterior:
// assume the variables "username" and "password" // contain user-entered data var sql:String = "SELECT userId " + "FROM users " + "WHERE username = :username " + " AND password = :password"; var statement:SQLStatement = new SQLStatement(); statement.text = sql; // set parameter values statement.parameters[":username"] = username; statement.parameters[":password"] = password;

Recuperao de dados de um banco de dados

Adobe AIR 1.0 e posterior A recuperao de dados de um banco de dados envolve duas etapas. Primeiro, voc executa uma instruo SQL SELECT que descreve o conjunto de dados desejado do banco de dados. Em seguida, voc acessa os dados recuperados e os exibe ou manipula conforme exigido pelo aplicativo.

Execuo de uma instruo SELECT

Adobe AIR 1.0 e posterior Para recuperar dados existentes de um banco de dados, use uma instncia de SQLStatement. Atribua a instruo SQL SELECT adequada propriedade text da ocorrncia e, depois, chame o mtodo execute() correspondente. Para obter mais detalhes sobre a sintaxe da instruo SELECT, consulte Suporte SQL em bancos de dados locais na pgina 1093. O exemplo abaixo mostra como executar uma instruo SELECT para recuperar dados de uma tabela chamada products usando o modo de execuo assncrona:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

721

var selectStmt:SQLStatement = new SQLStatement(); // A SQLConnection named "conn" has been created previously selectStmt.sqlConnection = conn; selectStmt.text = "SELECT itemId, itemName, price FROM products"; selectStmt.addEventListener(SQLEvent.RESULT, resultHandler); selectStmt.addEventListener(SQLErrorEvent.ERROR, errorHandler); selectStmt.execute(); function resultHandler(event:SQLEvent):void { var result:SQLResult = selectStmt.getResult(); var numResults:int = result.data.length; for (var i:int = 0; i < numResults; i++) { var row:Object = result.data[i]; var output:String = "itemId: " + row.itemId; output += "; itemName: " + row.itemName; output += "; price: " + row.price; trace(output); } } function errorHandler(event:SQLErrorEvent):void { // Information about the error is available in the // event.error property, which is an instance of // the SQLError class. } <?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="init()"> <mx:Script> <![CDATA[ import flash.data.SQLConnection; import flash.data.SQLResult; import flash.data.SQLStatement; import flash.errors.SQLError; import flash.events.SQLErrorEvent; import flash.events.SQLEvent; private function init():void { var selectStmt:SQLStatement = new SQLStatement(); // A SQLConnection named "conn" has been created previously selectStmt.sqlConnection = conn; selectStmt.text = "SELECT itemId, itemName, price FROM products"; selectStmt.addEventListener(SQLEvent.RESULT, resultHandler); selectStmt.addEventListener(SQLErrorEvent.ERROR, errorHandler);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

722

selectStmt.execute(); } private function resultHandler(event:SQLEvent):void { var result:SQLResult = selectStmt.getResult(); var numResults:int = result.data.length; for (var i:int = 0; i < numResults; i++) { var row:Object = result.data[i]; var output:String = "itemId: " + row.itemId; output += "; itemName: " + row.itemName; output += "; price: " + row.price; trace(output); } } private function errorHandler(event:SQLErrorEvent):void { // Information about the error is available in the // event.error property, which is an instance of // the SQLError class. } ]]> </mx:Script> </mx:WindowedApplication>

O exemplo a seguir demonstra a execuo de uma instruo SELECT para recuperar dados de uma tabela chamada produtos, usando o modo de execuo sncrona:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

723

var selectStmt:SQLStatement = new SQLStatement(); // A SQLConnection named "conn" has been created previously selectStmt.sqlConnection = conn; selectStmt.text = "SELECT itemId, itemName, price FROM products"; try { selectStmt.execute(); var result:SQLResult = selectStmt.getResult(); var numResults:int = result.data.length; for (var i:int = 0; i < numResults; i++) { var row:Object = result.data[i]; var output:String = "itemId: " + row.itemId; output += "; itemName: " + row.itemName; output += "; price: " + row.price; trace(output); } } catch (error:SQLError) { // Information about the error is available in the // error variable, which is an instance of // the SQLError class. } <?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="init()"> <mx:Script> <![CDATA[ import flash.data.SQLConnection; import flash.data.SQLResult; import flash.data.SQLStatement; import flash.errors.SQLError; import flash.events.SQLErrorEvent; import flash.events.SQLEvent; private function init():void { var selectStmt:SQLStatement = new SQLStatement(); // A SQLConnection named "conn" has been created previously selectStmt.sqlConnection = conn; selectStmt.text = "SELECT itemId, itemName, price FROM products"; try { selectStmt.execute(); var result:SQLResult = selectStmt.getResult();

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

724

var numResults:int = result.data.length; for (var i:int = 0; i < numResults; i++) { var row:Object = result.data[i]; var output:String = "itemId: " + row.itemId; output += "; itemName: " + row.itemName; output += "; price: " + row.price; trace(output); } } catch (error:SQLError) { // Information about the error is available in the // error variable, which is an instance of // the SQLError class. } } ]]> </mx:Script> </mx:WindowedApplication>

No modo de execuo assncrona, quando a execuo da instruo concluda, a ocorrncia de SQLStatement despacha um evento result (SQLEvent.RESULT) que indica que a instruo foi executada com sucesso. Como alternativa, se um objeto Responder for passado como argumento no mtodo de execute(), a funo do manipulador resultante do objeto Responder ser chamada. No modo de execuo sncrona, a execuo pausa at que a operao execute() seja concluda e, em seguida, prossegue com a prxima linha de cdigo.

Acesso a dados de resultados da instruo SELECT

Adobe AIR 1.0 e posterior Uma vez concluda a execuo da instruo SELECT, a prxima etapa acessar os dados que foram recuperados. Acesse os dados de resultados com a execuo de uma instruo SELECT, chamando o mtodo getResult() do objeto SQLStatement:
var result:SQLResult = selectStatement.getResult();

O mtodo getResult() gera um objeto SQLResult. A propriedade data do objeto SQLResult um Array que contm os resultados da instruo SELECT:
var numResults:int = result.data.length; for (var i:int = 0; i < numResults; i++) { // row is an Object representing one row of result data var row:Object = result.data[i]; }

Cada linha de dados no conjunto de resultados de SELECT se transforma em uma instncia do Objeto contida no Array data. Esse objeto tem propriedades cujos nomes correspondem aos nomes de coluna do conjunto de resultados. As propriedades contm os valores das colunas do conjunto de resultados. Por exemplo, suponha que uma instruo SELECT especifique um conjunto de resultados com trs colunas chamadas itemId, itemName e price. Para cada linha do conjunto de resultados, criada uma ocorrncia de Object com propriedades chamadas itemId, itemName e price. Essas propriedades contm os valores das respectivas colunas.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

725

A listagem de cdigo a seguir define uma ocorrncia de SQLStatement cujo texto uma instruo SELECT. A instruo recupera linhas que contm os valores de coluna firstName e lastName de todas as linhas de uma tabela denominada employees. Este exemplo utiliza o modo de execuo assncrona. Quando a execuo concluda, o mtodo selectResult() chamado, e as linhas de dados resultantes so acessadas usando SQLStatement.getResult() e exibidas usando o mtodo trace(). Observe que esta listagem presume que existe uma ocorrncia de SQLConnection denominada conn que j foi instanciada e j est conectada ao banco de dados. Ela tambm presume que a tabela employees j foi criada e preenchida com dados.
import import import import import flash.data.SQLConnection; flash.data.SQLResult; flash.data.SQLStatement; flash.events.SQLErrorEvent; flash.events.SQLEvent;

// ... create and open the SQLConnection instance named conn ... // create the SQL statement var selectStmt:SQLStatement = new SQLStatement(); selectStmt.sqlConnection = conn; // define the SQL text var sql:String = "SELECT firstName, lastName " + "FROM employees"; selectStmt.text = sql; // register listeners for the result and error events selectStmt.addEventListener(SQLEvent.RESULT, selectResult); selectStmt.addEventListener(SQLErrorEvent.ERROR, selectError); // execute the statement selectStmt.execute(); function selectResult(event:SQLEvent):void { // access the result data var result:SQLResult = selectStmt.getResult(); var numRows:int = result.data.length; for (var i:int = 0; i < numRows; i++) { var output:String = ""; for (var columnName:String in result.data[i]) { output += columnName + ": " + result.data[i][columnName] + "; "; } trace("row[" + i.toString() + "]\t", output); } } function selectError(event:SQLErrorEvent):void { trace("Error message:", event.error.message); trace("Details:", event.error.details); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

726

<?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="init()"> <mx:Script> <![CDATA[ import flash.data.SQLConnection; import flash.data.SQLResult; import flash.data.SQLStatement; import flash.events.SQLErrorEvent; import flash.events.SQLEvent; private function init():void { // ... create and open the SQLConnection instance named conn ... // create the SQL statement var selectStmt:SQLStatement = new SQLStatement(); selectStmt.sqlConnection = conn; // define the SQL text var sql:String = "SELECT firstName, lastName " + "FROM employees"; selectStmt.text = sql; // register listeners for the result and error events selectStmt.addEventListener(SQLEvent.RESULT, selectResult); selectStmt.addEventListener(SQLErrorEvent.ERROR, selectError); // execute the statement selectStmt.execute(); } private function selectResult(event:SQLEvent):void { // access the result data var result:SQLResult = selectStmt.getResult(); var numRows:int = result.data.length; for (var i:int = 0; i < numRows; i++) { var output:String = ""; for (var columnName:String in result.data[i]) { output += columnName + ": " + result.data[i][columnName] + "; "; } trace("row[" + i.toString() + "]\t", output); } } private function selectError(event:SQLErrorEvent):void { trace("Error message:", event.error.message); trace("Details:", event.error.details); } ]]> </mx:Script> </mx:WindowedApplication>

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

727

A listagem de cdigo a seguir demonstra as mesmas tcnicas que a anterior, mas usa o modo de execuo sncrona. O exemplo define uma instncia de SQLStatement cujo texto uma instruo SELECT. A instruo recupera linhas que contm os valores de coluna firstName e lastName de todas as linhas de uma tabela denominada employees. As linhas de dados resultantes so acessadas usando SQLStatement.getResult() e exibidas usando o mtodo trace(). Observe que esta listagem presume que existe uma ocorrncia de SQLConnection denominada conn que j foi instanciada e j est conectada ao banco de dados. Ela tambm presume que a tabela employees j foi criada e preenchida com dados.
import import import import flash.data.SQLConnection; flash.data.SQLResult; flash.data.SQLStatement; flash.errors.SQLError;

// ... create and open the SQLConnection instance named conn ... // create the SQL statement var selectStmt:SQLStatement = new SQLStatement(); selectStmt.sqlConnection = conn; // define the SQL text var sql:String = "SELECT firstName, lastName " + "FROM employees"; selectStmt.text = sql; try { // execute the statement selectStmt.execute(); // access the result data var result:SQLResult = selectStmt.getResult(); var numRows:int = result.data.length; for (var i:int = 0; i < numRows; i++) { var output:String = ""; for (var columnName:String in result.data[i]) { output += columnName + ": " + result.data[i][columnName] + "; "; } trace("row[" + i.toString() + "]\t", output); } } catch (error:SQLError) { trace("Error message:", error.message); trace("Details:", error.details); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

728

<?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="init()"> <mx:Script> <![CDATA[ import flash.data.SQLConnection; import flash.data.SQLResult; import flash.data.SQLStatement; import flash.errors.SQLError; private function init():void { // ... create and open the SQLConnection instance named conn ... // create the SQL statement var selectStmt:SQLStatement = new SQLStatement(); selectStmt.sqlConnection = conn; // define the SQL text var sql:String = "SELECT firstName, lastName " + "FROM employees"; selectStmt.text = sql; try { // execute the statement selectStmt.execute(); // access the result data var result:SQLResult = selectStmt.getResult(); var numRows:int = result.data.length; for (var i:int = 0; i < numRows; i++) { var output:String = ""; for (var columnName:String in result.data[i]) { output += columnName + ": "; output += result.data[i][columnName] + "; "; } trace("row[" + i.toString() + "]\t", output); } } catch (error:SQLError) { trace("Error message:", error.message); trace("Details:", error.details); } } ]]> </mx:Script> </mx:WindowedApplication>

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

729

Definio do tipo de dados dos dados resultantes de SELECT

Adobe AIR 1.0 e posterior Por padro, cada linha retornada por uma instruo SELECT criada como uma ocorrncia de Object com propriedades nomeadas para os nomes de coluna do conjunto de resultados e com o valor de cada coluna como o valor da propriedade associada. Porm, antes de executar uma instruo SQL SELECT, voc pode definir a propriedade itemClass da ocorrncia de SQLStatement para uma classe. Quando definida a propriedade itemClass, cada linha retornada pela instruo SELECT criada como ocorrncia da classe designada. O tempo de execuo atribui valores de coluna resultantes a valores de propriedade comparando os nomes de coluna do conjunto de resultados de SELECT com os nomes das propriedades da classe itemClass. Qualquer classe designada como um valor da propriedade itemClass deve ter um construtor que no exija parmetros. Alm disso, a classe deve ter uma nica propriedade para cada coluna retornada pela instruo SELECT. Ser considerado um erro se uma coluna da lista SELECT no tiver um nome de propriedade correspondente na classe itemClass.

Recuperao dos resultados de SELECT em partes

Adobe AIR 1.0 e posterior Por padro, a execuo de uma instruo SELECT recupera todas as linhas do conjunto de resultados de uma s vez. Uma vez concluda a instruo, geralmente voc processa os dados recuperados de alguma forma; por exemplo, criando objetos ou exibindo os dados na tela. Se a instruo retornar muitas linhas, processar todos os dados de uma s vez pode exigir bastante do computador, o que, por sua vez, faz com que a interface do usurio no se redesenhe. possvel melhorar o desempenho percebido do aplicativo instruindo o tempo de execuo a retornar um determinado nmero de linhas de resultado por vez. Isso faz com que os dados resultantes iniciais sejam retornados mais rapidamente. Isso tambm permite dividir as linhas de resultados em conjuntos, para que a interface de usurio seja atualizada depois do processamento de cada conjunto de linhas. S prtico usar esta tcnica no modo de execuo assncrona. Para recuperar os resultados de SELECT em partes, especifique um valor para o primeiro parmetro do mtodo
SQLStatement.execute() (o parmetro prefetch). O parmetro prefetch indica o nmero de linhas a serem

recuperadas na primeira vez que a instruo executada. Quando chamar o mtodo execute() de uma instncia de SQLStatement, especifique um valor de parmetro prefetch e somente essas linhas sero recuperadas:
var stmt:SQLStatement = new SQLStatement(); stmt.sqlConnection = conn; stmt.text = "SELECT ..."; stmt.addEventListener(SQLEvent.RESULT, selectResult); stmt.execute(20); // only the first 20 rows (or fewer) are returned

A instruo despacha o evento result, indicando que o primeiro conjunto de linhas de resultado est disponvel. A propriedade data da instncia de SQLResult resultante contm as linhas de dados, e sua propriedade complete indica se existem mais linhas de resultado a serem recuperadas. Para recuperar linhas de resultados adicionais, chame o mtodo next() da ocorrncia de SQLStatement. Assim como o mtodo execute(), o primeiro parmetro do mtodo next() usado para indicar quantas linhas devero ser recuperadas na prxima vez que o evento result for despachado.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

730

function selectResult(event:SQLEvent):void { var result:SQLResult = stmt.getResult(); if (result.data != null) { // ... loop through the rows or perform other processing ... if (!result.complete) { stmt.next(20); // retrieve the next 20 rows } else { stmt.removeEventListener(SQLEvent.RESULT, selectResult); } } }

SQLStatement despacha um evento result sempre que o mtodo next() retorna um conjunto subseqente de linhas de resultado. Conseqentemente, a mesma funo de ouvinte pode ser usada para continuar processando os resultados (de chamadas de next()) at que todas as linhas sejam recuperadas. Para obter mais informaes, consulte as descries do mtodo SQLStatement.execute() (a descrio do parmetro
prefetch) e o mtodo SQLStatement.next().

Insero de dados
Adobe AIR 1.0 e posterior A incluso de dados em um banco de dados envolve executar uma instruo SQL INSERT. Depois de concluda a execuo da instruo, voc poder acessar a chave primria da linha recm-inserida se a chave tiver sido gerada pelo banco de dados.

Execuo de uma instruo INSERT

Adobe AIR 1.0 e posterior Para adicionar dados a uma tabela de um banco de dados, crie e execute uma instncia de SQLStatement cujo texto uma instruo SQL INSERT. O exemplo a seguir usa uma ocorrncia de SQLStatement para adicionar uma linha de dados tabela employees j existente. Este exemplo demonstra como inserir dados usando o modo de execuo assncrona. Observe que esta listagem presume que existe uma instncia de SQLConnection denominada conn que j foi instanciada e j est conectada a um banco de dados. Ela tambm presume que a tabela employees j foi criada.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

731

import import import import import

flash.data.SQLConnection; flash.data.SQLResult; flash.data.SQLStatement; flash.events.SQLErrorEvent; flash.events.SQLEvent;

// ... create and open the SQLConnection instance named conn ... // create the SQL statement var insertStmt:SQLStatement = new SQLStatement(); insertStmt.sqlConnection = conn; // define the SQL text var sql:String = "INSERT INTO employees (firstName, lastName, salary) " + "VALUES ('Bob', 'Smith', 8000)"; insertStmt.text = sql; // register listeners for the result and failure (status) events insertStmt.addEventListener(SQLEvent.RESULT, insertResult); insertStmt.addEventListener(SQLErrorEvent.ERROR, insertError); // execute the statement insertStmt.execute(); function insertResult(event:SQLEvent):void { trace("INSERT statement succeeded"); } function insertError(event:SQLErrorEvent):void { trace("Error message:", event.error.message); trace("Details:", event.error.details); } <?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="init()"> <mx:Script> <![CDATA[ import flash.data.SQLConnection; import flash.data.SQLResult; import flash.data.SQLStatement; import flash.events.SQLErrorEvent; import flash.events.SQLEvent; private function init():void { // ... create and open the SQLConnection instance named conn ... // create the SQL statement var insertStmt:SQLStatement = new SQLStatement(); insertStmt.sqlConnection = conn; // define the SQL text var sql:String = "INSERT INTO employees (firstName, lastName, salary) " +

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

732

"VALUES ('Bob', 'Smith', 8000)"; insertStmt.text = sql; // register listeners for the result and failure (status) events insertStmt.addEventListener(SQLEvent.RESULT, insertResult); insertStmt.addEventListener(SQLErrorEvent.ERROR, insertError); // execute the statement insertStmt.execute(); } private function insertResult(event:SQLEvent):void { trace("INSERT statement succeeded"); } private function insertError(event:SQLErrorEvent):void { trace("Error message:", event.error.message); trace("Details:", event.error.details); } ]]> </mx:Script> </mx:WindowedApplication>

O exemplo a seguir adiciona uma linha de dados tabela employees j existente usando o modo de execuo sncrona. Observe que esta listagem presume que existe uma instncia de SQLConnection denominada conn que j foi instanciada e j est conectada a um banco de dados. Ela tambm presume que a tabela employees j foi criada.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

733

import import import import

flash.data.SQLConnection; flash.data.SQLResult; flash.data.SQLStatement; flash.errors.SQLError;

// ... create and open the SQLConnection instance named conn ... // create the SQL statement var insertStmt:SQLStatement = new SQLStatement(); insertStmt.sqlConnection = conn; // define the SQL text var sql:String = "INSERT INTO employees (firstName, lastName, salary) " + "VALUES ('Bob', 'Smith', 8000)"; insertStmt.text = sql; try { // execute the statement insertStmt.execute(); trace("INSERT statement succeeded"); } catch (error:SQLError) { trace("Error message:", error.message); trace("Details:", error.details); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

734

<?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="init()"> <mx:Script> <![CDATA[ import flash.data.SQLConnection; import flash.data.SQLResult; import flash.data.SQLStatement; import flash.errors.SQLError; private function init():void { // ... create and open the SQLConnection instance named conn ... // create the SQL statement var insertStmt:SQLStatement = new SQLStatement(); insertStmt.sqlConnection = conn; // define the SQL text var sql:String = "INSERT INTO employees (firstName, lastName, salary) " + "VALUES ('Bob', 'Smith', 8000)"; insertStmt.text = sql; try { // execute the statement insertStmt.execute(); trace("INSERT statement succeeded"); } catch (error:SQLError) { trace("Error message:", error.message); trace("Details:", error.details); } } ]]> </mx:Script> </mx:WindowedApplication>

Recuperao de uma chave primria gerada pelo banco de dados de uma linha inserida
Adobe AIR 1.0 e posterior Com freqncia, depois de inserir uma linha de dados a uma tabela, o cdigo precisa ser informado sobre uma chave primria gerada pelo banco de dados ou o valor do identificador da linha recm-inserida. Por exemplo, depois de inserir uma linha em uma tabela, voc deve adicionar linhas a uma tabela relacionada. Nesse caso, convm inserir o valor da chave primria como chave externa na tabela relacionada. A chave primria de uma linha recm-inserida pode ser recuperada usando o objeto SQLResult associado execuo da instruo. o mesmo objeto usado para acessar dados de resultado depois que uma instruo SELECT executada. Assim como ocorre com qualquer instruo SQL, quando a execuo de uma instruo INSERT concluda, o tempo de execuo cria uma ocorrncia de SQLResult. Para acessar a instncia de SQLResult, chame o mtodo getResult() do objeto SQLStatement se voc estiver usando

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

735

um ouvinte de evento ou o modo de execuo sncrona. Se preferir, caso esteja usando o modo de execuo assncrona e passe uma instncia de Responder para a chamada de execute(), a instncia de SQLResult ser passada como argumento para a funo do manipulador resultante. Seja como for, a ocorrncia de SQLResult tem uma propriedade, chamada lastInsertRowID, que contm o identificador de linha da linha inserida mais recentemente se a instruo SQL executada uma instruo INSERT. Este exemplo mostra como acessar a chave primria de uma linha inserida no modo de execuo assncrona:
insertStmt.text = "INSERT INTO ..."; insertStmt.addEventListener(SQLEvent.RESULT, resultHandler); insertStmt.execute(); function resultHandler(event:SQLEvent):void { // get the primary key var result:SQLResult = insertStmt.getResult(); var primaryKey:Number = result.lastInsertRowID; // do something with the primary key }

Este exemplo mostra como acessar a chave primria de uma linha inserida no modo de execuo sncrona:
insertStmt.text = "INSERT INTO ..."; try { insertStmt.execute(); // get the primary key var result:SQLResult = insertStmt.getResult(); var primaryKey:Number = result.lastInsertRowID; // do something with the primary key } catch (error:SQLError) { // respond to the error }

Observe que o identificador de linha pode ou no ser o valor da coluna designada como a coluna de chave primria na definio de tabela, de acordo com as seguintes regras:

Se a tabela est definida com uma coluna de chave primria cuja afinidade (tipo de dados da coluna) INTEGER, a
propriedade lastInsertRowID contm o valor inserido nessa linha (ou o valor gerado pelo tempo de execuo, no caso de uma coluna AUTOINCREMENT).

Se a tabela estiver definida com vrias colunas de chave primria (uma chave composta) ou com uma nica coluna
de chave primria cuja afinidade no INTEGER, o banco de dados gera um valor inteiro identificador de coluna para a linha em segundo plano. Esse valor gerado o valor da propriedade lastInsertRowID.

O valor sempre o identificador de linha da linha inserida mais recentemente. Se uma instruo INSERT faz com
que seja acionado um disparador que, por sua vez, insere uma linha, a propriedade lastInsertRowID contm o identificador de linha da ltima linha inserida pelo disparador em vez da linha criada pela instruo INSERT.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

736

Em virtude dessas regras, se voc quiser ter uma coluna de chave primria definida explicitamente cujo valor fica disponvel aps um comando INSERT atravs da propriedade SQLResult.lastInsertRowID, a coluna dever ser definida como uma coluna INTEGER PRIMARY KEY. Mesmo que a tabela no inclua uma coluna INTEGER PRIMARY KEY explcita, ser igualmente aceitvel usar o identificador de linha gerado pelo banco de dados como uma chave primria para a sua tabela com o intuito de definir relacionamentos com tabelas relacionadas. O valor da coluna do identificador de linha fica disponvel em qualquer instruo SQL atravs do uso de um dos nomes de coluna especiais ROWID, _ROWID_ ou OID. possvel criar uma coluna de chave externa em uma tabela relacionada e usar o valor do identificador de linha como o valor da coluna de chave externa, assim como voc faria com uma coluna INTEGER PRIMARY KEY declarada explicitamente. Nesse sentido, se estiver usando uma chave primria arbitrria em vez de uma chave natural, e desde que no se importe que o tempo de execuo gere o valor da chave primria para voc, faz pouca diferena se voc usa uma coluna INTEGER PRIMARY KEY ou o identificador de linha gerado pelo sistema como a chave primria de uma tabela para definir um relacionamento de chave externa entre duas tabelas. Para obter mais detalhes sobre chaves primrias e identificadores e linha gerados, consulte Suporte SQL em bancos de dados locais na pgina 1093.

Alterao ou excluso de dados

Adobe AIR 1.0 e posterior O processo para executar outras operaes de manipulao de dados idntico ao seguido para executar uma instruo SQL SELECT ou INSERT, conforme descrito em Trabalhar com instrues SQL na pgina 716. Basta substituir uma instruo SQL diferente na propriedade text da instncia de SQLStatement:

Para alterar dados existentes em uma tabela, use uma instruo UPDATE. Para excluir uma ou mais linhas de dados de uma tabela, use uma instruo DELETE.
Para obter descries dessas instrues, consulte Suporte SQL em bancos de dados locais na pgina 1093.

Trabalhar com vrios bancos de dados

Adobe AIR 1.0 e posterior Use o mtodo SQLConnection.attach() para abrir uma conexo com um banco de dados adicional em uma ocorrncia de SQLConnection que j tem um banco de dados aberto. D um nome ao banco de dados anexado usando o parmetro de nome na chamada do mtodo attach(). Ao escrever instrues para manipular esse banco de dados, voc poder usar esse nome em um prefixo (no formato nome-do-bancodedados.nome-da-tabela) para qualificar qualquer nome de tabela em suas instrues SQL, indicando ao tempo de execuo que a tabela pode ser encontrada no banco de dados nomeado. possvel executar uma nica instruo SQL que inclua tabelas de vrios bancos de dados conectados mesma ocorrncia de SQLConnection. Se uma transao for criada na ocorrncia de SQLConnection, ela ser aplicada a todas as instrues SQL executadas usando a ocorrncia de SQLConnection. Isso vlido independentemente do banco de dados anexado no qual a instruo executada.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

737

Se preferir, voc tambm pode criar vrias ocorrncias de SQLConnection em um aplicativo, cada uma delas conectada a um ou a vrios bancos de dados. Contudo, se voc usar vrias conexes com o mesmo banco de dados, lembre-se de que uma transao de banco de dados no compartilhada entre ocorrncias de SQLConnection. Conseqentemente, se voc se conectar ao mesmo arquivo de banco de dados usando vrias ocorrncias de SQLConnection, no poder contar que as alteraes de dados em ambas as conexes sejam aplicadas da maneira esperada. Por exemplo, se duas instrues UPDATE ou DELETE forem executadas no mesmo banco de dados atravs de diferentes ocorrncias de SQLConnection e acontecer um erro de aplicativo depois de executada uma operao, os dados do banco de dados podero ficar em um estado intermedirio irreversvel que talvez afete a integridade do banco de dados (e, conseqentemente, o aplicativo).

Tratamento de erros de banco de dados

Adobe AIR 1.0 e posterior Em geral, o tratamento de erros de banco de dados parecido com o de outros erros de tempo de execuo. Voc deve criar um cdigo preparado para eventuais erros e para responder a eles em vez de deixar que o tempo de execuo faa isso. De um modo geral, os erros de banco de dados possveis dividem-se em trs categorias: erros de conexo, de sintaxe SQL e de restrio.

Erro de conexo
Adobe AIR 1.0 e posterior A maioria dos erros de banco de dados so de conexo, e eles podem ocorrer durante qualquer operao. Embora haja estratgias para prevenir erros de conexo, raramente existe uma forma simples de se recuperar tranqilamente de um erro desse tipo se o banco de dados um componente crtico do seu aplicativo. A maior parte dos erros de conexo tem a ver com a maneira como o tempo de execuo interage com o sistema operacional, o sistema de arquivos e o arquivo de banco de dados. Por exemplo, ocorre um erro de conexo quando o usurio no tem permisso para criar um arquivo de banco de dados em um determinado local do sistema de arquivos. As seguintes estratgias ajudam a prevenir erros de conexo:
Utilize arquivos de banco de dados especficos do usurio Em vez de usar um nico arquivo de banco de dados para

todos os usurios que utilizam um mesmo computador, d a cada usurio seu prprio arquivo de banco de dados. O arquivo deve estar localizado em um diretrio associado com a conta do usurio. Por exemplo, ele pode estar no diretrio de armazenamento do aplicativo, na pasta de documentos do usurio, na rea de trabalho dele, e assim por diante.
Leve em considerao diferentes tipos de usurio Teste seu aplicativo com diferentes tipos de contas de usurio em diferentes sistemas operacionais. No suponha que o usurio tem permisso de administrador no computador. Tambm no presuma que quem instalou o aplicativo o usurio que o est executando. Leve em considerao localizaes de arquivo diferentes Se voc permitir que um usurio especifique onde salvar um

arquivo de banco de dados ou selecione um arquivo a ser aberto, considere as possveis localizaes de arquivo que os usurios podem usar. Alm disso, considere a possibilidade de definir limites quanto aos locais em que os usurios podem armazenar (ou abrir) arquivos de banco de dados. Por exemplo, voc s deve permitir que eles abram arquivos existentes no local de armazenamento de suas contas de usurio. Se acontecer um erro de conexo, mais provvel que ele ocorra na primeira tentativa de criar ou abrir o banco de dados. Isso significa que o usurio no consegue fazer nenhuma operao relacionada a banco de dados no aplicativo. Para certos tipos de erros, como erros de permisso ou somente leitura, uma tcnica de recuperao possvel consiste em copiar o arquivo de banco de dados para outro local. O aplicativo pode copiar o arquivo de banco de dados para outro local, em que o usurio tenha permisso para criar e gravar em arquivos, e pode usar esse local.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

738

Erros de sintaxe
Adobe AIR 1.0 e posterior Um erro de sintaxe ocorre quando uma instruo SQL est formada incorretamente e o aplicativo tenta execut-la. Como as instrues SQL de banco de dados local so criadas como strings, no possvel fazer a verificao da sintaxe SQL durante a compilao. Todas as instrues SQL devem ser executadas para verificar sua sintaxe. Adote as seguintes estratgias para evitar erros de sintaxe SQL:
Teste todas as instrues SQL integralmente Se possvel, enquanto desenvolve o aplicativo, teste as instrues SQL separadamente antes de codific-las como texto de instruo no cdigo do aplicativo. Alm disso, use uma abordagem de teste do cdigo, como teste de unidade, para criar um conjunto de testes que aplique todas as opes e variaes possveis no cdigo. Use parmetros de instruo e evite concatenar (gerar dinamicamente) o SQL Usar parmetros, e evitar instrues

SQL criadas dinamicamente, significa que o mesmo texto de instruo SQL usado sempre que uma instruo executada. Conseqentemente, bem mais fcil testar suas instrues e limitar a variao possvel. Se voc tiver de gerar uma instruo SQL dinamicamente, use o mnimo possvel de partes dinmicas na instruo. Alm disso, seja cauteloso ao validar qualquer entrada de usurio para se certificar de que ela no causar erros de sintaxe. Para se recuperar de um erro de sintaxe, um aplicativo precisa de uma lgica complexa que permita examinar uma instruo SQL e corrigir sua sintaxe. Se forem seguidas as diretrizes acima para evitar erros de sintaxe, o cdigo conseguir identificar qualquer possvel origem de tempo de execuo de erros de sintaxe SQL (como entradas de usurio utilizadas em uma instruo). Para se recuperar de um erro de sintaxe, oriente o usurio. Indique o que deve ser corrigido para que a instruo seja executada corretamente.

Erros de restrio
Adobe AIR 1.0 e posterior Erros de restrio ocorrem quando uma instruo INSERT ou UPDATE tenta adicionar dados a uma coluna. O erro acontece se os novos dados violam uma das restries definidas para a tabela ou coluna. O conjunto de restries possveis inclui:
Restrio exclusiva Indica que, entre todas as linhas de uma tabela, no pode existir valores duplicados em uma

coluna. Como alternativa, quando vrias colunas so combinadas em uma restrio exclusiva, a combinao de valores dessas colunas no deve ser duplicada. Em outras palavras, em termos da(s) coluna(s) exclusiva(s) especificada(s), cada linha deve ser distinta.
Restrio de chave primria Em termos dos dados permitidos e no permitidos por uma restrio, a restrio de chave

primria idntica a uma restrio exclusiva.

Restrio no nula Especifica que uma nica coluna no pode armazenar um valor NULL e, conseqentemente, que em

cada linha essa coluna deve ter um valor.

Restrio de verificao Permite especificar uma restrio arbitrria em uma ou mais tabelas. Uma restrio de

verificao comum uma regra que define que o valor de uma coluna deve estar dentro de certos limites (por exemplo, que o valor de uma coluna numrica deve ser maior que 0). Outro tipo de restrio de verificao comum especifica relacionamentos entre valores de coluna (por exemplo, que o valor de uma coluna deve ser diferente do de outra coluna na mesma linha).
Restrio de tipo de dados (afinidade de coluna) O tempo de execuo impe o tipo de dados de valores de colunas, e

ocorre um erro se feita uma tentativa de armazenar um valor de tipo incorreto em uma coluna. No entanto, em muitas condies os valores so convertidos para corresponder ao tipo de dados declarado da coluna. Consulte Trabalhar com tipos de dados de banco de dados na pgina 740 para obter mais informaes.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

739

O tempo de execuo no impe restries quanto a valores de chave externa. Em outras palavras, os valores de chave externa no precisam corresponder ao valor de uma chave primria existente. Alm dos tipos de restrio predefinidos, o mecanismo SQL de tempo de execuo permite o uso de disparadores. O disparador como um manipulador de eventos. Ele consiste em um conjunto de instrues predefinidas que so executadas quando acontece uma determinada ao. Por exemplo, possvel definir um disparador que seja executado quando dados forem inseridos ou excludos de uma tabela especfica. Um uso possvel de um disparador examinar alteraes feitas em dados e fazer com que ocorra um erro se as condies especificadas no forem atendidas. Conseqentemente, um disparador pode atender ao mesmo objetivo de uma restrio, e as estratgias para evitar e se recuperar de erros de restrio tambm se aplicam a erros gerados por disparadores. Porm, a id de erro dos erros gerados por disparadores diferente da id de erro dos erros de restrio. O conjunto de restries que se aplicam a uma tabela em particular determinado enquanto voc est criando um aplicativo. Elaborar restries com conscincia facilita que voc crie o aplicativo para evitar e se recuperar de erros de constrio. No entanto, os erros de restrio so difceis de prever e impedir sistematicamente. A previso difcil porque os erros de restrio s aparecem depois que so adicionados os dados do aplicativo. Os erros de restrio acontecem com dados que so adicionados a um banco de dados aps sua criao. Com freqncia, esses erros so resultado do relacionamento entre os novos dados e os dados j existentes no banco de dados. As seguintes estratgias podem ajud-lo a evitar muitos erros de restrio:
Planeje cautelosamente a estrutura e as restries do banco de dados A finalidade das restries impor regras de

aplicativo e ajudar a proteger a integridade dos dados do banco de dados. Quando estiver planejando seu aplicativo, pense em como estruturar o banco de dados para dar suporte ao aplicativo. Como parte desse processo, identifique regras para seus dados; por exemplo, se certos valores no necessrios, se um valor tem um padro, se so permitidos valores duplicados e assim por diante. Essas regras orientam a definio de restries do banco de dados.
Especifique nomes de coluna explicitamente possvel criar uma instruo INSERT sem especificar explicitamente as

colunas em que os valores devero ser inseridos, mas faz-lo um risco desnecessrio. Quando voc nomeia explicitamente as colunas em que os valores devero ser inseridos, pode permitir valores gerados de forma automtica, colunas com valores padro e colunas que permitam valores NULL. Alm disso, quando voc faz isso pode assegurar que todas as colunas NOT NULL tero um valor explcito inserido.
Use valores padro Sempre que voc especificar uma restrio NOT NULL para uma coluna, se possvel, especifique um

valor padro na definio de coluna. O cdigo do aplicativo tambm pode fornecer valores padro. Por exemplo, o cdigo pode verificar se uma varivel String null e atribuir um valor a ela antes de us-la para definir um valor de parmetro de instruo.
Valide os dados inseridos pelos usurios Verifique com antecedncia os dados inseridos pelos usurios para ter

certeza de que obedecem aos limites especificados pelas restries, principalmente no caso de restries NOT NULL e
CHECK. Naturalmente, uma restrio UNIQUE mais difcil de verificar porque, para fazer a verificao, necessrio

executar uma consulta SELECT para determinar se os dados so exclusivos.

Use disparadores Voc pode criar um disparador que valide (e possivelmente substitua) os dados inseridos ou que tome outras medidas para corrigir dados invlidos. Esse procedimento de validao e correo pode evitar que acontea um erro de restrio.

Em vrios aspectos, mais difcil evitar os erros de restrio do que outros tipos de erro. Felizmente, existem diversas estratgias para se recuperar de erros de restrio sem tornar o aplicativo instvel ou inutilizvel:
Use algoritmos de conflito Quando voc define uma restrio em uma coluna, e quando cria uma instruo INSERT

ou UPDATE, tem a opo de especificar um algoritmo de conflito. Um algoritmo de conflito define a ao que o banco de dados executa quando ocorre uma violao de restrio. H vrias aes possveis que o mecanismo de banco de dados pode executar. O mecanismo de banco de dados pode encerrar uma nica instruo ou uma transao inteira. Ele pode ignorar o erro. Ele pode at mesmo remover dados antigos e substitu-los pelos dados que o cdigo est tentando armazenar.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

740

Para obter mais informaes consulte a seo ON CONFLICT (algoritmos de conflito) em Suporte SQL em bancos de dados locais na pgina 1093.
Disponibilize feedback de correo possvel identificar antecipadamente o conjunto de restries que pode afetar um determinado comando SQL. Como conseqncia, voc consegue prever os erros de restrio que podem ser causados por uma instruo. Dispondo dessa informao, voc pode desenvolver a lgica do aplicativo para responder a um erro de restrio. Por exemplo, suponha que um aplicativo inclui um formulrio de entrada de dados que permite inserir novos produtos. Se a coluna de nome de produto no banco de dados estiver definida com uma restrio UNIQUE, a ao de inserir uma linha de novo produto no banco de dados poder causar um erro de restrio. Conseqentemente, o aplicativo deve prever um erro de restrio. Quando o erro acontece, o aplicativo alerta o usurio indicando que o nome de produto especificado j est sendo utilizado e pede a ele para escolher outro nome. Outra resposta possvel permitir que o usurio visualize informaes sobre o outro produto que tem o mesmo nome.

Trabalhar com tipos de dados de banco de dados

Adobe AIR 1.0 e posterior Quando uma tabela criada em um banco de dados, a instruo SQL usada para criar a tabela define a afinidade, ou o tipo de dados, de cada coluna da tabela. Embora seja possvel omitir declaraes de afinidade, uma boa idia declarar explicitamente a afinidade de coluna nas instrues SQL CREATE TABLE. Como regra geral, qualquer objeto que voc armazena em um banco de dados usando uma instruo INSERT retornado como ocorrncia do mesmo tipo de dados quando executada uma instruo SELECT. No entanto, o tipo de dados do valor recuperado pode ser diferente, dependendo da afinidade da coluna do banco de dados na qual o valor est armazenado. Quando um valor armazenado em uma coluna, se o respectivo tipo de dados no corresponde afinidade de coluna, o banco de dados tenta converter o valor para que corresponda afinidade de coluna. Por exemplo, se uma coluna de banco de dados est declarada com afinidade NUMERIC, o banco de dados tenta converter os dados inseridos em uma classe de armazenamento numrica (INTEGER ou REAL) antes de armazenar os dados. O banco de dados gera um erro se no possvel converter os dados. De acordo com esta regra, se a String 12345 inserida em uma coluna NUMERIC, o banco de dados automaticamente a converte no valor inteiro 12345 antes de armazen-la no banco de dados. Quando recuperado com uma instruo SELECT, o valor retornado como uma ocorrncia de um tipo de dados numrico (por exemplo, Number) e no como uma ocorrncia de String. A melhor maneira de evitar a converso indesejada de tipos de dados seguir duas regras. Primeiro, defina cada coluna com a afinidade que corresponda ao tipo de dados que pretende armazenar. Em seguida, insira apenas valores cujo tipo de dados corresponda afinidade definida. Se voc seguir essas regras, ter dois benefcios. Quando voc inserir os dados, eles no sero convertidos inesperadamente (com a possibilidade de perderem o significado pretendido). Alm disso, quando voc recupera os dados, eles so retornados com o tipo de dados original. Para obter mais informaes sobre os tipos de afinidade de coluna disponveis e utilizao de tipos de dados em instrues SQL, consulte o Suporte ao tipo de dados na pgina 1116.

Uso de operaes de banco de dados sncronas e assncronas

Adobe AIR 1.0 e posterior As sees anteriores descreveram operaes comuns de banco de dados, como recuperar, inserir, atualizar e excluir dados, alm da criao de um arquivo de banco de dados e de tabelas e outros objetos de um banco de dados. Os exemplos demonstraram como executar essas operaes de maneira assncrona e sncrona.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

741

Como lembrete, no modo de execuo assncrona, voc instrui o mecanismo de banco de dados a executar uma operao. O mecanismo de banco de dados ento trabalha em segundo plano enquanto o aplicativo continua a executar. Quando a operao concluda, o mecanismo de banco de dados despacha um evento para alertar voc sobre o fato. O principal benefcio da execuo assncrona que o tempo de execuo realiza as operaes de banco de dados em segundo plano, enquanto o cdigo do aplicativo principal continua a executar. Isso importante principalmente quando a operao bastante demorada. Por outro lado, no modo de execuo sncrona, as operaes no so executadas em segundo plano. Voc instrui o mecanismo de banco de dados a executar uma operao. O cdigo pausa nesse ponto enquanto o mecanismo de banco de dados faz o seu trabalho. Quando a operao concluda, a execuo prossegue com a prxima linha do cdigo que voc criou. Uma nica conexo de banco de dados no pode executar algumas operaes ou instrues em modo sncrono e outras em modo assncrono. Especifique se uma SQLConnection opera de forma sncrona ou assncrona quando abre a conexo com o banco de dados. Se voc chamar SQLConnection.open(), a conexo funcionar no modo de execuo sncrona; se voc chamar SQLConnection.openAsync(), ela funcionar no modo de execuo assncrona. Uma vez que uma ocorrncia de SQLConnection conectada a um banco de dados usando open() ou openAsync(), ela fixada execuo sncrona ou assncrona.

Uso de operaes de banco de dados sncronas

Adobe AIR 1.0 e posterior H pouca diferente no cdigo que voc usa para executar e responder a operaes na execuo sncrona em comparao com o cdigo para o modo de execuo assncrona. As principais diferenas entre as duas abordagens esto em duas reas. A primeira executar uma operao que depende de outra operao (como linhas de resultado SELECT ou a chave primria da linha adicionada por uma instruo INSERT). A segunda rea de diferena o tratamento de erros.

Criao de cdigo para operaes sncronas

Adobe AIR 1.0 e posterior A principal diferena entre a execuo sncrona e assncrona que, no modo sncrono, voc cria o cdigo como uma nica srie de etapas. Por outro lado, no cdigo assncrono, voc registra ouvintes de evento e com freqncia divide as operaes entre mtodos de ouvinte. Quando um banco de dados conectado no modo de execuo sncrona, voc pode executar uma srie de operaes de banco de dados em sequncia em um nico bloco de cdigo. O exemplo abaixo demonstra esta tcnica:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

742

var conn:SQLConnection = new SQLConnection(); // The database file is in the application storage directory var folder:File = File.applicationStorageDirectory; var dbFile:File = folder.resolvePath("DBSample.db"); // open the database conn.open(dbFile, OpenMode.UPDATE); // start a transaction conn.begin(); // add the customer record to the database var insertCustomer:SQLStatement = new SQLStatement(); insertCustomer.sqlConnection = conn; insertCustomer.text = "INSERT INTO customers (firstName, lastName) " + "VALUES ('Bob', 'Jones')"; insertCustomer.execute(); var customerId:Number = insertCustomer.getResult().lastInsertRowID; // add a related phone number record for the customer var insertPhoneNumber:SQLStatement = new SQLStatement(); insertPhoneNumber.sqlConnection = conn; insertPhoneNumber.text = "INSERT INTO customerPhoneNumbers (customerId, number) " + "VALUES (:customerId, '800-555-1234')"; insertPhoneNumber.parameters[":customerId"] = customerId; insertPhoneNumber.execute(); // commit the transaction conn.commit();

Como voc pode ver, possvel chamar os mesmos mtodos para executar operaes de banco de dados independentemente de usar a execuo sncrona ou assncrona. As principais diferenas entre as duas abordagens so executar uma operao que depende de outra operao e como tratar de erros.

Execuo de uma operao que depende de outra

Adobe AIR 1.0 e posterior Quando voc usa o modo de execuo sncrona, no precisa criar um cdigo que monitore um evento para determinar quando uma operao concluda. Em vez disso, voc pode presumir que, se uma operao em uma linha de cdigo foi concluda com sucesso, a execuo continuar na prxima linha de cdigo. Conseqentemente, para executar uma operao que depende do sucesso de outra, basta criar o cdigo dependente logo depois da operao da qual ela depende. Por exemplo, para codificar um aplicativo para iniciar uma transao, executar uma instruo INSERT, recuperar a chave primria da linha inserida, inserir essa chave primria em outra linha de uma outra tabela e, por fim, confirmar a transao, o cdigo pode ser todo criado como uma srie de instrues. O seguinte exemplo demonstra essas operaes:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

743

var conn:SQLConnection = new SQLConnection(); // The database file is in the application storage directory var folder:File = File.applicationStorageDirectory; var dbFile:File = folder.resolvePath("DBSample.db"); // open the database conn.open(dbFile, SQLMode.UPDATE); // start a transaction conn.begin(); // add the customer record to the database var insertCustomer:SQLStatement = new SQLStatement(); insertCustomer.sqlConnection = conn; insertCustomer.text = "INSERT INTO customers (firstName, lastName) " + "VALUES ('Bob', 'Jones')"; insertCustomer.execute(); var customerId:Number = insertCustomer.getResult().lastInsertRowID; // add a related phone number record for the customer var insertPhoneNumber:SQLStatement = new SQLStatement(); insertPhoneNumber.sqlConnection = conn; insertPhoneNumber.text = "INSERT INTO customerPhoneNumbers (customerId, number) " + "VALUES (:customerId, '800-555-1234')"; insertPhoneNumber.parameters[":customerId"] = customerId; insertPhoneNumber.execute(); // commit the transaction conn.commit();

Tratamento de erros na execuo sncrona

Adobe AIR 1.0 e posterior No modo de execuo sncrona, voc no monitora um evento de erro para determinar se uma operao falhou. Em vez disso, coloque qualquer cdigo que possa disparar erros em um conjunto de blocos de cdigo try..catch..finally. Coloque o cdigo gerador de erro no bloco try. Grave as aes a serem executadas em resposta a cada tipo de erro em blocos catch separados. Coloque qualquer cdigo que voc queira sempre executar independentemente de sucesso ou falha (por exemplo, encerrar uma conexo de banco de dados no mais necessria) em um bloco finally. O exemplo a seguir demonstra o uso de blocos try..catch..finally para tratamento de erros. Ele aproveita o exemplo anterior adicionando cdigo de tratamento de erro:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

744

var conn:SQLConnection = new SQLConnection(); // The database file is in the application storage directory var folder:File = File.applicationStorageDirectory; var dbFile:File = folder.resolvePath("DBSample.db"); // open the database conn.open(dbFile, SQLMode.UPDATE); // start a transaction conn.begin(); try { // add the customer record to the database var insertCustomer:SQLStatement = new SQLStatement(); insertCustomer.sqlConnection = conn; insertCustomer.text = "INSERT INTO customers (firstName, lastName)" + "VALUES ('Bob', 'Jones')"; insertCustomer.execute(); var customerId:Number = insertCustomer.getResult().lastInsertRowID; // add a related phone number record for the customer var insertPhoneNumber:SQLStatement = new SQLStatement(); insertPhoneNumber.sqlConnection = conn; insertPhoneNumber.text = "INSERT INTO customerPhoneNumbers (customerId, number)" + "VALUES (:customerId, '800-555-1234')"; insertPhoneNumber.parameters[":customerId"] = customerId; insertPhoneNumber.execute(); // if we've gotten to this point without errors, commit the transaction conn.commit(); } catch (error:SQLError) { // rollback the transaction conn.rollback(); }

Noes bsicas sobre o modelo de execuo assncrona

Adobe AIR 1.0 e posterior Uma preocupao comum sobre o uso do modo de execuo assncrona a suposio de que no possvel comear a executar uma instncia de SQLStatement se outra instncia de SQLStatement est em execuo na mesma conexo de banco de dados. Na verdade, essa suposio no est correta. Durante a execuo de uma ocorrncia de SQLStatement, no possvel alterar a propriedade text da instruo. Contudo, se voc usar uma ocorrncia de SQLStatement parte para cada instruo SQL que deseja executar, poder chamar o mtodo execute() de um SQLStatement enquanto outra ocorrncia de SQLStatement ainda estiver sendo executada, sem causar erro.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

745

Internamente, quando voc executa operaes de banco de dados utilizando o modo de execuo assncrona, cada conexo de banco de dados (cada instncia de SQLConnection) tem sua prpria fila ou lista de operaes que est instruda a executar. O tempo de execuo realiza cada operao em seqncia, na ordem em que so adicionadas fila. Quando voc cria uma ocorrncia de SQLStatement e chama o mtodo execute() relacionado, a operao de execuo dessa instruo adicionada fila da conexo. Se nenhuma operao estiver sendo executada nessa ocorrncia de SQLConnection, a instruo comear a ser executada em segundo plano. Suponha que, dentro do mesmo bloco de cdigo, voc crie outra ocorrncia de SQLStatement e tambm chame o mtodo execute() daquele mtodo. A operao que executa essa segunda instruo adicionada fila depois da primeira instruo. Assim que concluda a execuo da primeira instruo, o tempo de execuo passa para a prxima operao da fila. O processamento das operaes subseqentes na fila acontece em segundo plano, mesmo quando o evento result da primeira operao est sendo despachado no cdigo do aplicativo principal. O cdigo abaixo demonstra esta tcnica:
// Using asynchronous execution mode var stmt1:SQLStatement = new SQLStatement(); stmt1.sqlConnection = conn; // ... Set statement text and parameters, and register event listeners ... stmt1.execute(); // At this point stmt1's execute() operation is added to conn's execution queue. var stmt2:SQLStatement = new SQLStatement(); stmt2.sqlConnection = conn; // ... Set statement text and parameters, and register event listeners ... stmt2.execute(); // At this point stmt2's execute() operation is added to conn's execution queue. // When stmt1 finishes executing, stmt2 will immediately begin executing // in the background.

Ocorre um importante efeito colateral pelo fato de o banco de dados executar as prximas instrues em fila de maneira automtica. Se uma instruo depende do resultado de outra operao, no possvel adicion-la fila (em outras palavras, voc no pode chamar o mtodo execute() relacionado) at a primeira operao ser concluda. Isso acontece porque, depois que voc chamou o mtodo execute() da segunda instruo, no possvel alterar as propriedades text ou parameters dela. Nesse caso, voc deve aguardar o evento indicando que a primeira operao foi concluda antes de iniciar a prxima operao. Por exemplo, se voc quiser executar uma instruo no contexto de uma transao, a execuo da instruo depender da operao de abrir a transao. Aps chamar o mtodo SQLConnection.begin() para abrir a transao, voc ter de aguardar que a ocorrncia de SQLConnection despache seu evento begin. S ento voc poder chamar o mtodo execute() da ocorrncia de SQLStatement. Neste exemplo, o modo mais simples de organizar o aplicativo para assegurar que as operaes sejam executadas corretamente criar um mtodo que seja registrado como ouvinte do evento begin. O cdigo para chamar o mtodo SQLStatement.execute() colocado dentro do mtodo desse ouvinte.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

746

Uso da criptografia com bancos de dados SQL

Adobe AIR 1.5 e posterior Todos os aplicativos do Adobe AIR compartilham o mesmo mecanismo do banco de dados local. Conseqentemente, qualquer aplicativo AIR pode se conectar, ler e gravar em qualquer arquivo do banco de dados no criptografado. Comeando com o Adobe AIR 1.5, o AIR inclui a capacidade de criar e se conectar a arquivos do banco de dados criptografado. Quando voc usa um banco de dados criptografado, para se conectar a ele um aplicativo deve fornecer a chave de criptografia correta. Se a chave de criptografia incorreta (ou nenhuma chave) for fornecida, o aplicativo no poder se conectar ao banco de dados. Conseqentemente, o aplicativo no poder ler, gravar ou alterar dados do banco de dados. Para usar um banco de dados criptografado, voc deve criar o banco de dados como banco de dados criptografado. Com um banco de dados criptografado existente, possvel abrir uma conexo com o banco de dados. Voc tambm pode alterar a chave de criptografia de um banco de dados criptografado. Em vez de criar e estabelecer conexo com bancos de dados criptografados, as tcnicas para trabalhar com um banco de dados criptografado so as mesmas que para um banco de dados no criptografado. Especificamente, a execuo de instrues SQL ocorre da mesma forma em bancos de dados criptografados e no criptografados.

Uso de um banco de dados criptografado

Adobe AIR 1.5 e posterior A criptografia til sempre que voc desejar restringir o acesso s informaes armazenadas em um banco de dados. A funcionalidade de criptografia do banco de dados do Adobe AIR pode ser usada para vrias finalidades. Estes so exemplos de casos em que voc pode usar um banco de dados criptografado:

Um cache somente leitura de dados de aplicativos privados baixados de um servidor Um armazenamento de aplicativo local para dados privados sincronizado com um servidor (os dados so enviados
e carregados do servidor)

Arquivos criptografados usados como formato de arquivo para documentos criados e editados pelo aplicativo. Os
arquivos podem ser privados para um usurio ou projetados para compartilhamento entre todos os usurios do aplicativo.

Qualquer outro uso de um armazenamento local de dados, como os descrito em Usos de bancos de dados SQL
locais na pgina 700, onde os dados devem ser mantidos privados de pessoas com acesso ao computador ou aos arquivos do banco de dados. Compreender o motivo pelo qual voc deseja usar um banco de dados criptografado ajuda a decidir como arquitetar seu aplicativo. Especificamente, ele pode afetar a forma que seu aplicativo cria, obtm e armazena a chave de criptografia para o banco de dados. Para obter mais informaes sobre essas consideraes, consulte Consideraes para usar criptografia com um banco de dados na pgina 750.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

747

Alm de um banco de dados criptografado, um mecanismo alternativo para manter dados confidenciais privados o armazenamento local criptografado. Com o armazenamento local criptografado, voc armazena um nico valor ByteArray usando uma chave String. Apenas o aplicativo AIR que armazena o valor pode acess-lo, e somente no computador em que ele est armazenado. Com o armazenamento local criptografado, no necessrio criar sua prpria chave de criptografia. Por esses motivos, o armazenamento local criptografado mais adequado para armazenar facilmente um nico valor ou um conjunto de valores que possa ser facilmente codificado em um ByteArray. Um banco de dados criptografado mais adequado para conjuntos de dados maiores, onde o armazenamento de dados e consultas estruturadas so desejveis. Para obter mais informaes sobre o uso de armazenamento local criptografado, consulte Armazenamento local criptografado na pgina 696.

Criao de um banco de dados criptografado

Adobe AIR 1.5 e posterior Para usar um banco de dados criptografado, o arquivo do banco de dados deve ser criptografado quando ele for criado. Quando um banco de dados criado como no criptografado, ele pode no ser criptografado posteriormente. Da mesma forma, um banco de dados criptografado no pode passar a no criptografado posteriormente. Se necessrio, voc tambm pode alterar a chave de criptografia de um banco de dados criptografado. Para obter detalhes, consulte Alterao da chave de criptografia de um banco de dados na pgina 749. Se voc tiver um banco de dados existente que no seja criptografado e desejar usar a criptografia de banco de dados, poder criar um novo banco de dados criptografado e copiar a estrutura de tabela e os dados existentes no novo banco de dados. Criar um banco de dados criptografado quase idntico a criar um banco de dados no criptografado, como descrito em Criao de um banco de dados na pgina 705. Primeiro voc cria uma instncia do SQLConnection que representa a conexo ao banco de dados. Crie o banco de dados chamando o mtodo open() ou o mtodo openAsync() do objeto do SQLConnection, especificando para a localizao do banco de dados um arquivo que ainda no exista. A nica diferena na criao de um banco de dados criptografado que voc fornece um valor para o parmetro encryptionKey (o quinto parmetro do mtodo open() e o sexto parmetro do mtodo openAsync()). Um valor vlido do parmetro encryptionKey um objeto ByteArray que contm exatamente 16 bytes. Os exemplos a seguir demonstram a criao de um banco de dados criptografado. Para simplicidade, nestes exemplos, a chave de criptografia codificada no cdigo do aplicativo. No entanto, essa tcnica altamente desencorajada, pois no segura.
var conn:SQLConnection = new SQLConnection(); var encryptionKey:ByteArray = new ByteArray(); encryptionKey.writeUTFBytes("Some16ByteString"); // This technique is not secure! // Create an encrypted database in asynchronous mode conn.openAsync(dbFile, SQLMode.CREATE, null, false, 1024, encryptionKey); // Create an encrypted database in synchronous mode conn.open(dbFile, SQLMode.CREATE, false, 1024, encryptionKey);

Para obter um exemplo que demonstre uma forma recomendada de gerar uma chave de criptografia, consulte Exemplo: Gerao e uso de uma chave de criptografia na pgina 751.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

748

Conexo com um banco de dados criptografado

Adobe AIR 1.5 e posterior Da mesma forma que criar um banco de dados criptografado, o procedimento para abrir uma conexo com um banco de dados criptografado como conectar-se a um banco de dados no criptografado. Esse procedimento descrito com mais detalhes em Conexo com um banco de dados na pgina 713. Use o mtodo open() para abrir uma conexo no modo de execuo sncrona ou o mtodo openAsync() para abri-la no modo de execuo assncrona. A nica diferena que para abrir um banco de dados criptografado, especifica o valor correto para o parmetro encryptionKey (o quinto parmetro do mtodo open() e o sexto parmetro do mtodo openAsync()). Se a chave de criptografia fornecida no for a correta, ocorre um erro. Para o mtodo open(), lanada uma exceo SQLError. Para o mtodo openAsync(), o objeto SQLConnection gera um SQLErrorEvent, cuja propriedade error contm um objeto SQLError. Em qualquer um dos casos, o objeto SQLError gerado pela exceo tem o valor 3138 na propriedade errorID. Este ID de erro corresponde mensagem de erro O arquivo aberto no corresponde a um arquivo de banco de dados. O exemplo a seguir demonstra a abertura de um banco de dados criptografado em modo de execuo assncrona. Para simplicidade, neste exemplo a chave de criptografia codificada no cdigo do aplicativo. No entanto, essa tcnica altamente desencorajada, pois no segura.
import import import import import flash.data.SQLConnection; flash.data.SQLMode; flash.events.SQLErrorEvent; flash.events.SQLEvent; flash.filesystem.File;

var conn:SQLConnection = new SQLConnection(); conn.addEventListener(SQLEvent.OPEN, openHandler); conn.addEventListener(SQLErrorEvent.ERROR, errorHandler); var dbFile:File = File.applicationStorageDirectory.resolvePath("DBSample.db"); var encryptionKey:ByteArray = new ByteArray(); encryptionKey.writeUTFBytes("Some16ByteString"); // This technique is not secure! conn.openAsync(dbFile, SQLMode.UPDATE, null, false, 1024, encryptionKey); function openHandler(event:SQLEvent):void { trace("the database opened successfully"); } function errorHandler(event:SQLErrorEvent):void { if (event.error.errorID == 3138) { trace("Incorrect encryption key"); } else { trace("Error message:", event.error.message); trace("Details:", event.error.details); } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

749

O exemplo a seguir demonstra a abertura de um banco de dados criptografado em modo de execuo sncrona. Para simplicidade, neste exemplo a chave de criptografia codificada no cdigo do aplicativo. No entanto, essa tcnica altamente desencorajada, pois no segura.
import flash.data.SQLConnection; import flash.data.SQLMode; import flash.filesystem.File; var conn:SQLConnection = new SQLConnection(); var dbFile:File = File.applicationStorageDirectory.resolvePath("DBSample.db"); var encryptionKey:ByteArray = new ByteArray(); encryptionKey.writeUTFBytes("Some16ByteString"); // This technique is not secure! try { conn.open(dbFile, SQLMode.UPDATE, false, 1024, encryptionKey); trace("the database was created successfully"); } catch (error:SQLError) { if (error.errorID == 3138) { trace("Incorrect encryption key"); } else { trace("Error message:", error.message); trace("Details:", error.details); } }

Para obter um exemplo que demonstre uma forma recomendada de gerar uma chave de criptografia, consulte Exemplo: Gerao e uso de uma chave de criptografia na pgina 751.

Alterao da chave de criptografia de um banco de dados

Adobe AIR 1.5 e posterior Quando um banco de dados criptografado, voc pode alterar a chave de criptografia do banco de dados posteriormente. Para alterar a chave criptogrfica de um banco de dados, primeiro abra uma conexo com o banco de dados criando uma instncia de SQLConnection e chamando seu mtodo open() ou openAsync(). Quando o banco de dados for conectado, chame o mtodo reencrypt(), enviando a nova chave de criptografia como um argumento. Como a maioria das operaes de banco de dados, o comportamento do mtodo reencrypt() depende se a conexo do banco de dados usa modo de execuo sncrona ou assncrona. Se voc usar o mtodo open() para conectar-se ao banco de dados, a operao de reencrypt() ser executada de forma sncrona. Quando a operao concluda, a execuo prossegue com a prxima linha do cdigo.
var newKey:ByteArray = new ByteArray(); // ... generate the new key and store it in newKey conn.reencrypt(newKey);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

750

Por outro lado, se a conexo do banco de dados for aberta com o mtodo openAsync(), a operao de reencrypt() ser assncrona. Chamar reencrypt() inicia o processo de recriptografia. Quando a operao concluda, o objeto SQLConnection despacha um evento reencrypt. Use um ouvinte de evento para determinar quando a recriptografia ser concluda:
var newKey:ByteArray = new ByteArray(); // ... generate the new key and store it in newKey conn.addEventListener(SQLEvent.REENCRYPT, reencryptHandler); conn.reencrypt(newKey); function reencryptHandler(event:SQLEvent):void { // save the fact that the key changed }

A operao reencrypt() ser executada na sua prpria transao. Se a operao for interrompida ou falhar (por exemplo, se o aplicativo for fechado antes da concluso da operao), a transao ser revertida. Nesse caso, a chave de criptografia ainda ser a chave de criptografia do banco de dados. O mtodo reencrypt() no pode ser usado para remover a criptografia de um banco de dados. Enviar um valor null ou chave de criptografia que no seja um ByteArray de 16 bytes para o mtodo reencrypt() resulta em erro.

Consideraes para usar criptografia com um banco de dados

Adobe AIR 1.5 e posterior A seo Uso de um banco de dados criptografado na pgina 746 apresenta vrios casos em que voc pode usar um banco de dados criptografado. bvio que as situaes de uso dos aplicativos diferentes (incluindo essas e outras situaes) tm requisitos de privacidade diferentes. A forma que voc arquiteta o uso de criptografia no seu aplicativo tem importante papel no controle do grau de privacidade dos dados de um banco de dados. Por exemplo, se voc estiver usando um banco de dados criptografado para manter os dados pessoais privados, mesmo de usurios do mesmo computador, o banco de dados de cada usurio dever ter a prpria chave de criptografia. Para obter segurana mxima, seu aplicativo pode gerar a chave de uma senha digitada por um usurio. Basear a chave de criptografia em uma senha garante que os dados se mantenham preservados, mesmo se qualquer outra pessoa entrar na conta do usurio no computador. Por outro lado, suponha que voc deseje que um arquivo do banco de dados seja legvel para qualquer usurio do seu aplicativo, mas no para os demais aplicativos. Nesse caso, todas as cpias do aplicativo instaladas precisam de acesso a uma chave de criptografia compartilhada. Voc pode projetar seu aplicativo e, em particular, a tcnica usada para gerar a chave de criptografia, de acordo com o nvel de privacidade que voc deseja para os dados do aplicativo. A lista a seguir fornece sugestes de design para vrios nveis de privacidade de dados.

Para tornar um banco de dados acessvel a qualquer usurio que tenha acesso ao aplicativo em qualquer
computador, use uma nica chave disponvel em todas as instncias do aplicativo. Por exemplo, na primeira vez que um aplicativo for executado, ele poder baixar a chave de criptografia compartilhada de um servidor usando um protocolo seguro, como SSL. Em seguida, ele poder salvar a chave no armazenamento local criptografado para uso futuro. Como alternativa, criptografe os dados por usurio no computador e sincronize os dados com um armazenamento de dados remoto, como servidor, para tornar os dados portteis.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

751

Para tornar um banco de dados acessvel para um nico usurio em qualquer computador, gere a chave de
criptografia a partir de um segredo do usurio (como uma senha). Especificamente, no use nenhum valor associado a um computador especfico (como um valor armazenado no armazenamento local criptografado) para gerar a chave. Como alternativa, criptografe os dados por usurio no computador e sincronize os dados com um armazenamento de dados remoto, como servidor, para tornar os dados portteis.

Para tornar um banco de dados acessvel somente para um nico indivduo em um nico computador, gere a chave
de uma senha e um salt gerado. Para obter um exemplo dessa tcnica, consulte Exemplo: Gerao e uso de uma chave de criptografia na pgina 751. A seguir h algumas consideraes adicionais sobre segurana que so importantes lembrar ao projetar um aplicativo para usar um banco de dados criptografado.

Um sistema s seguro como seu link mais fraco. Se voc estiver usando uma senha gerada pelo usurio para gerar
uma chave de criptografia, considere impor o restries de complexidade e tamanho mnimo s senhas. Uma senha curta que use somente caracteres bsicos pode ser adivinhada rapidamente.

O cdigo-fonte de um aplicativo AIR armazenado no computador de um usurio em texto simples (para

contedo HTML) ou em um formato binrio facilmente descompilvel (para contedo SWF). Como o cdigofonte acessvel, dois pontos a lembrar so:

Nunca codifique uma chave de criptografia no seu cdigo-fonte Sempre suponha que a tcnica usada para gerar uma chave de criptografia (como gerador aleatrio de caracteres
ou um algoritmo de hash especfico) possa ser facilmente descoberta por um invasor

A criptografia do banco de dados AIR usa o modo AES (padro de criptografia avanado) com CCM (contador com
CBC-MAC). Essa cifra de criptografia requer a combinao de uma chave inserida pelo usurio com um valor salt para ser segura. Para obter um exemplo, consulte Exemplo: Gerao e uso de uma chave de criptografia na pgina 751.

Quando voc opta por criptografar um banco de dados, todos os arquivos de discos usados pelo mecanismo de
banco de dados juntamente com esse banco de dados so criptografados. No entanto, o mecanismo do banco de dados retm alguns dados temporariamente em um cache na memria para aprimorar o desempenho de tempos de leitura e gravao em transaes. Todos os dados residentes na memria so criptografados. Se um invasor puder acessar a memria usada por um aplicativo AIR, por exemplo usando um depurador, os dados do banco de dados aberto atualmente e no criptografado ficaro disponveis.

Exemplo: Gerao e uso de uma chave de criptografia

Adobe AIR 1.5 e posterior Esse aplicativo de exemplo demonstra uma tcnica para gerar uma chave de criptografia. Esse aplicativo foi projetado para fornecer o nvel mais alto de privacidade e segurana para dados do usurio. Um aspecto importante da segurana de dados privados exigir que o usurio digite uma senha sempre que o aplicativo se conectar ao banco de dados. Conseqentemente, conforme mostrado no exemplo, um aplicativo que requer este nvel de privacidade nunca dever armazenar diretamente a chave de criptografia do banco de dados. O aplicativo consiste em duas partes: uma classe ActionScript que gera uma chave de criptografia (a classe EncryptionKeyGenerator) e uma interface do usurio bsica que demonstra como usar a classe. Para obter o cdigofonte completo, consulte Exemplo completo de cdigo para gerar e usar uma chave de criptografia na pgina 753.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

752

Usar a classe EncryptionKeyGenerator para obter uma cjave de criptografia segura

Adobe AIR 1.5 e posterior No necessrio compreender os detalhes de como a classe EncryptionKeyGenerator funciona para us-la no seu aplicativo. Se estiver interessado nos detalhes de como a classe gera uma chave de criptografia para um banco de dados, consulte Noes bsicas da classe EncryptionKeyGenerator na pgina 758. Siga essas etapas para usar a classe EncryptionKeyGenerator no seu aplicativo:
1 Baixe a classe EncryptionKeyGenerator como cdigo-fonte ou um SWC compilado. A classe

EncryptionKeyGenerator est includa no projeto biblioteca principal (as3corelib) do ActionScript 3.0 de cdigofonte aberto. Voc pode baixar o pacote as3corelib incluindo o cdigo-fonte e a documentao. Voc tambm pode baixar os arquivos SWC ou de cdigo-fonte na pgina do projeto.
2 Coloque o cdigo-fonte da classe EncryptionKeyGenerator (ou o SWC as3corelib) em um local onde o cdigo-

fonte do seu aplicativo possa encontr-lo.

3 No cdigo-fonte do aplicativo, adicione uma instruo import para a classe EncryptionKeyGenerator.
import com.adobe.air.crypto.EncryptionKeyGenerator;

4 Antes do ponto onde o cdigo cria o banco de dados ou abre uma conexo para ele, adicione o cdigo para criar

uma ocorrncia EncryptionKeyGenerator chamando o construtor EncryptionKeyGenerator().

var keyGenerator:EncryptionKeyGenerator = new EncryptionKeyGenerator();

5 Obtenha uma senha do usurio:

var password:String = passwordInput.text; if (!keyGenerator.validateStrongPassword(password)) { // display an error message return; }

A ocorrncia EncryptionKeyGenerator usa essa senha como base da chave de criptografia (mostrado na prxima etapa). A ocorrncia EncryptionKeyGenerator testa a senha em relao a alguns requisitos de validao de senha forte. Em caso de falha na validao, ocorre um erro. Como o cdigo de exemplo mostra, voc pode verificar a senha antecipadamente chamando o mtodo validateStrongPassword() do objeto EncryptionKeyGenerator. Dessa forma, voc pode determinar se a senha atende aos requisitos mnimos de uma senha forte e evita que haja erro.
6 Gere a chave de criptografia da senha:
var encryptionKey:ByteArray = keyGenerator.getEncryptionKey(password);

O mtodo getEncryptionKey() gera e retorna a chave de criptografia (um ByteArray de 16 bytes). Em seguida, voc pode usar a chave de criptografia para criar seu novo banco de dados criptografado ou abrir um j existente. O mtodo getEncryptionKey() tem um parmetro obrigatrio, que a senha obtida na etapa 5. Nota: Para manter o maior nvel de segurana e privacidade dos dados, o aplicativo deve requerer que o usurio digite uma senha sempre que se conectar ao banco de dados. No armazene diretamente a senha do usurio ou a chave de criptografia do banco de dados. Isso expe a riscos de segurana. Em vez disso, conforme demonstrado nesse exemplo, o aplicativo deve usar a mesma tcnica para derivar a chade de criptografia da senha, ao criar o banco de dados criptografado e quando se conectar a ele mais tarde.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

753

O mtodo getEncryptionKey() tambm aceita um segundo parmetro (opcional), o parmetro overrideSaltELSKey. O EncryptionKeyGenerator cria um valor aleatrio (conhecido como salt) que usado como parte da chave de criptografia. Para ser capaz de criar novamente a chave de criptografia, o valor salt armazenado no armazenamento local criptografado (ELS) do seu aplicativo AIR. Por padro, a classe EncryptionKeyGenerator usa uma String especfica como chave ELS. Embora improvvel, possvel que a chave possa entrar em conflito com outra chave que o aplicativo usa. Em vez de usar a chave padro, talvez voc deseje especificar sua prpria chave ELS. Nesse caso, especifique uma chave personalizada, passando-a como segundo parmetro getEncryptionKey(), conforme mostrado aqui:
var customKey:String = "My custom ELS salt key"; var encryptionKey:ByteArray = keyGenerator.getEncryptionKey(password, customKey);

7 Criar ou abrir o banco de dados

Com a chave de criptografia retornada pelo mtodo getEncryptionKey(), o cdigo pode criar um novo banco de dados criptografado ou tentar abrir o banco de dados criptografado existente. Em ambos os casos, voc usa o mtodo open() ou openAsync() da classe SQLConnection, conforme descrito em Criao de um banco de dados criptografado na pgina 747 e Conexo com um banco de dados criptografado na pgina 748. Nesse exemplo, o aplicativo foi projetado para abrir o banco de dados em modo de execuo assncrona. O cdigo configura os ouvintes do evento apropriados e chama o mtodo openAsync(), enviando a chave de criptografia como argumento final.
conn.addEventListener(SQLEvent.OPEN, openHandler); conn.addEventListener(SQLErrorEvent.ERROR, openError); conn.openAsync(dbFile, SQLMode.CREATE, null, false, 1024, encryptionKey);

Nos mtodos do ouvinte, o cdigo remove os registros do ouvinte do evento. Em seguida, ele exibe uma mensagem de status indicando se o banco de dados foi criado, aberto ou se ocorreu um erro. A parte mais notvel desses manipuladores de eventos est no mtodo openError(). Nesse mtodo, a instruo if verifica se o banco de dados existe (o que significa que o cdigo est tentando se conectar a um banco de dados existente) e se a ID do erro corresponde constante EncryptionKeyGenerator.ENCRYPTED_DB_PASSWORD_ERROR_ID. Se ambas as condies forem verdadeiras, isso significa provavelmente que a senha inserida pelo usurio est incorreta. (Isso tambm pode significar que o arquivo especificado no de maneira nenhuma um arquivo de banco de dados.) A seguir temos o cdigo que verifica a ID do erro:
if (!createNewDB && event.error.errorID == EncryptionKeyGenerator.ENCRYPTED_DB_PASSWORD_ERROR_ID) { statusMsg.text = "Incorrect password!"; } else { statusMsg.text = "Error creating or opening database."; }

Para obter o cdigo completo dos ouvintes de eventos de exemplo, consulte Exemplo completo de cdigo para gerar e usar uma chave de criptografia na pgina 753.

Exemplo completo de cdigo para gerar e usar uma chave de criptografia

Adobe AIR 1.5 e posterior A seguir h um exemplo completo de um cdigo para a aplicao de Gerao e uso da chave de criptografia. O cdigo consiste em duas partes.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

754

O exemplo usa a classe EncryptionKeyGenerator para criar uma chave de criptografia a partir de uma senha. A classe EncryptionKeyGenerator est includa no projeto biblioteca principal (as3corelib) do ActionScript 3.0 de cdigo-fonte aberto. Voc pode baixar o pacote as3corelib incluindo o cdigo-fonte e a documentao. Voc tambm pode baixar os arquivos SWC ou de cdigo-fonte na pgina do projeto. Exemplo do Flex O arquivo do aplicativo MXML contm o cdigo-fonte de um aplicativo simples que cria ou abre uma conexo para um banco de dados criptografado:
<?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical" creationComplete="init();"> <mx:Script> <![CDATA[ import com.adobe.air.crypto.EncryptionKeyGenerator; private const dbFileName:String = "encryptedDatabase.db"; private var dbFile:File; private var createNewDB:Boolean = true; private var conn:SQLConnection; // ------- Event handling ------private function init():void { conn = new SQLConnection(); dbFile = File.applicationStorageDirectory.resolvePath(dbFileName); if (dbFile.exists) { createNewDB = false; instructions.text = "Enter your database password to open the encrypted database."; openButton.label = "Open Database"; } } private function openConnection():void { var password:String = passwordInput.text; var keyGenerator:EncryptionKeyGenerator = new EncryptionKeyGenerator(); if (password == null || password.length <= 0) { statusMsg.text = "Please specify a password."; return; } if (!keyGenerator.validateStrongPassword(password)) { statusMsg.text = "The password must be 8-32 characters long. It must contain at least one lowercase letter, at least one uppercase letter, and at least one number or symbol."; return; }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

755

passwordInput.text = ""; passwordInput.enabled = false; openButton.enabled = false; var encryptionKey:ByteArray = keyGenerator.getEncryptionKey(password); conn.addEventListener(SQLEvent.OPEN, openHandler); conn.addEventListener(SQLErrorEvent.ERROR, openError); conn.openAsync(dbFile, SQLMode.CREATE, null, false, 1024, encryptionKey); } private function openHandler(event:SQLEvent):void { conn.removeEventListener(SQLEvent.OPEN, openHandler); conn.removeEventListener(SQLErrorEvent.ERROR, openError); statusMsg.setStyle("color", 0x009900); if (createNewDB) { statusMsg.text = "The encrypted database was created successfully."; } else { statusMsg.text = "The encrypted database was opened successfully."; } } private function openError(event:SQLErrorEvent):void { conn.removeEventListener(SQLEvent.OPEN, openHandler); conn.removeEventListener(SQLErrorEvent.ERROR, openError); if (!createNewDB && event.error.errorID == EncryptionKeyGenerator.ENCRYPTED_DB_PASSWORD_ERROR_ID) { statusMsg.text = "Incorrect password!"; } else { statusMsg.text = "Error creating or opening database."; } } ]]> </mx:Script> <mx:Text id="instructions" text="Enter a password to create an encrypted database. The next time you open the application, you will need to re-enter the password to open the database again." width="75%" height="65"/> <mx:HBox> <mx:TextInput id="passwordInput" displayAsPassword="true"/> <mx:Button id="openButton" label="Create Database" click="openConnection();"/> </mx:HBox> <mx:Text id="statusMsg" color="#990000" width="75%"/> </mx:WindowedApplication>

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

756

Exemplo do Flash Professional O arquivo FLA do aplicativo contm o cdigo fonte de um aplicativo simples que cria ou abre uma conexo para um banco de dados criptografado. O arquivo FLA tem quatro componentes colocados no palco:
Nome da ocorrncia
instrues passwordInput openButton statusMsg

Tipo do componente

Descrio

Label TextInput Button Label

Contm as instrues fornecidas ao usurio Campo de entrada onde o usurio digita a senha Boto em que o usurio clica aps digitar a senha Exibe mensagens de status (xito ou falha)

O cdigo do aplicativo definido em um quadro-chave no quadro 1 da linha do tempo principal. Este o cdigo do aplicativo:
import com.adobe.air.crypto.EncryptionKeyGenerator; const dbFileName:String = "encryptedDatabase.db"; var dbFile:File; var createNewDB:Boolean = true; var conn:SQLConnection; init(); // ------- Event handling ------function init():void { passwordInput.displayAsPassword = true; openButton.addEventListener(MouseEvent.CLICK, openConnection); statusMsg.setStyle("textFormat", new TextFormat(null, null, 0x990000)); conn = new SQLConnection(); dbFile = File.applicationStorageDirectory.resolvePath(dbFileName); if (dbFile.exists) { createNewDB = false; instructions.text = "Enter your database password to open the encrypted database."; openButton.label = "Open Database"; } else { instructions.text = "Enter a password to create an encrypted database. The next time you open the application, you will need to re-enter the password to open the database again."; openButton.label = "Create Database"; } } function openConnection(event:MouseEvent):void { var keyGenerator:EncryptionKeyGenerator = new EncryptionKeyGenerator(); var password:String = passwordInput.text;

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

757

if (password == null || password.length <= 0) { statusMsg.text = "Please specify a password."; return; } if (!keyGenerator.validateStrongPassword(password)) { statusMsg.text = "The password must be 8-32 characters long. It must contain at least one lowercase letter, at least one uppercase letter, and at least one number or symbol."; return; } passwordInput.text = ""; passwordInput.enabled = false; openButton.enabled = false; var encryptionKey:ByteArray = keyGenerator.getEncryptionKey(password); conn.addEventListener(SQLEvent.OPEN, openHandler); conn.addEventListener(SQLErrorEvent.ERROR, openError); conn.openAsync(dbFile, SQLMode.CREATE, null, false, 1024, encryptionKey); } function openHandler(event:SQLEvent):void { conn.removeEventListener(SQLEvent.OPEN, openHandler); conn.removeEventListener(SQLErrorEvent.ERROR, openError); statusMsg.setStyle("textFormat", new TextFormat(null, null, 0x009900)); if (createNewDB) { statusMsg.text = "The encrypted database was created successfully."; } else { statusMsg.text = "The encrypted database was opened successfully."; } } function openError(event:SQLErrorEvent):void { conn.removeEventListener(SQLEvent.OPEN, openHandler); conn.removeEventListener(SQLErrorEvent.ERROR, openError); if (!createNewDB && event.error.errorID == EncryptionKeyGenerator.ENCRYPTED_DB_PASSWORD_ERROR_ID) { statusMsg.text = "Incorrect password!"; } else { statusMsg.text = "Error creating or opening database."; } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

758

Noes bsicas da classe EncryptionKeyGenerator

Adobe AIR 1.5 e posterior No necessrio compreender o funcionamento interno da classe EncryptionKeyGenerator para us-la com o fim de criar uma chave de criptografia segura para o banco de dados do aplicativo. O processo para usar a classe est explicado em Usar a classe EncryptionKeyGenerator para obter uma cjave de criptografia segura na pgina 752. No entanto, pode ser conveniente entender as tcnicas que a classe utiliza. Por exemplo, pode ser conveniente adaptar a classe ou incorporar algumas de suas tcnicas em situaes nas quais um nvel diferente de privacidade de dados desejado. A classe EncryptionKeyGenerator est includa no projeto biblioteca principal (as3corelib) do ActionScript 3.0 de cdigo-fonte aberto. Voc pode fazer o download dopacote as3corelib, incluindo o cdigo-fonte e a documentao. Tambm possvel exibir o cdigo-fonte no site do projeto ou baix-lo para acompanhar juntamente com as explicaes. Quando o cdigo cria uma ocorrncia EncryptionKeyGenerator e chama o respectivo mtodo getEncryptionKey(), vrias etapas so realizadas para garantir que apenas o usurio com permisso possa acessar os dados. O processo o mesmo para gerar uma chave de criptografia de uma senha inserida pelo usurio antes de o banco de dados ter sido criado, bem como criar novamente a chave de criptografia para abrir o banco de dados. Obter e validar uma senha forte Adobe AIR 1.5 e posterior Quando o cdigo chama o mtodo getEncryptionKey(), ele passa uma senha como um parmetro. A senha usada como base para a chave de criptografia. Usando informaes que somente o usurio conhea, esse design garante que somente o usurio que saiba a senha possa acessar os dados do banco de dados. Mesmo se um invasor acessar a conta do usurio no computador, no poder entrar no banco de dados sem saber a senha. Para fornecer mxima proteo, o aplicativo nunca armazena a senha. O cdigo de um aplicativo cria uma instncia EncryptionKeyGenerator e chama o mtodo getEncryptionKey(), passando uma senha inserida pelo usurio como argumento (a varavel password neste exemplo):
var keyGenerator:EncryptionKeyGenerator = new EncryptionKeyGenerator(); var encryptionKey:ByteArray = keyGenerator.getEncryptionKey(password);

A primeira etapa que a classe EncryptionKeyGenerator executa quando o mtodo getEncryptionKey() chamado, verificar a senha digitada pelo usurio para garantir que ela atende aos requisitos de segurana da senha. A classe EncryptionKeyGenerator exige que a senha tenha de 8 a 32 caracteres. A senha deve conter letras maisculas e minsculas e pelo menos um nmero ou caractere simblico. A expresso regular que marca esse padro definida como uma constante chamada de STRONG_PASSWORD_PATTERN:
private static const STRONG_PASSWORD_PATTERN:RegExp = /(?=^.{8,32}$)((?=.*\d)|(?=.*\W+))(?![.\n])(?=.*[A-Z])(?=.*[a-z]).*$/;

O cdigo que verifica a senha est no mtodo validateStrongPassword() da classe EncryptionKeyGenerator. O cdigo o seguinte:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

759

public function vaidateStrongPassword(password:String):Boolean { if (password == null || password.length <= 0) { return false; } return STRONG_PASSWORD_PATTERN.test(password)) }

Internamente, o mtodo getEncryptionKey() chama o mtodo validateStrongPassword() da classe EncryptionKeyGenerator e, se a senha no vlida, lana uma exceo. O mtodo validateStrongPassword() um mtodo pblico para que o cdigo do aplicativo possa verificar a senha sem chamar o mtodo getEncryptionKey(), para evitar um erro. Expandir a senha para 256 bits Adobe AIR 1.5 e posterior Mais tarde no processo, a senha dever ter 256 bits. Em vez de exigir que cada usurio insira uma senha com exatamente 256 bits (32 caracteres), o cdigo cria uma senha maior, repetindo os caracteres da senha. O mtodo getEncryptionKey() chama o mtodo concatenatePassword() para executar a tarefa de criar a senha longa.
var concatenatedPassword:String = concatenatePassword(password);

A seguir, temos o cdigo do mtodo concatenatePassword():

private function concatenatePassword(pwd:String):String { var len:int = pwd.length; var targetLength:int = 32; if (len == targetLength) { return pwd; } var repetitions:int = Math.floor(targetLength / len); var excess:int = targetLength % len; var result:String = ""; for (var i:uint = 0; i < repetitions; i++) { result += pwd; } result += pwd.substr(0, excess); return result; }

Se a senha tem menos de 256 bits, o cdigo concatena a senha com ele mesmo para torn-la 256 bits. Se o comprimento no funcionar exatamente, a ltima repetio ser reduzida para obter exatamente 256 bits.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

760

Gerar ou recuperar um valor de salt de 256 bits Adobe AIR 1.5 e posterior A prxima etapa obter um valor de salt de 256 bits que, posteriormente, ser combinado com a senha. Um salt um valor aleatrio adicionado ou combinado com um valor inserido pelo usurio para formar uma senha. Usar um salt com uma senha garante que mesmo se um usurio escolher uma palavra real ou termo comum como senha, a combinao senha mais salt que o sistema usa ser um valor aleatrio. Isso, de maneira no aleatria, ajuda a proteger contra um ataque ao dicionrio, em que um invasor usa uma lista de palavras para tentar adivinhar uma senha. Alm disso, gerando o valor salt e armazenando-o no armazenamento local criptografado, ele associado conta do usurio no computador em que o arquivo do banco de dados est localizado. Se o aplicativo estiver chamando o mtodo getEncryptionKey() pela primeira vez, o cdigo criar um valor salt aleatrio de 256 bits. Caso contrrio, o cdigo carregar o valor de salt do armazenamento local criptografado. O salt armazenado em uma varivel chamada de salt. O cdigo determina se j foi criado um salt, ao tentar carregar o salt do armazenamento local criptografado:
var salt:ByteArray = EncryptedLocalStore.getItem(saltKey); if (salt == null) { salt = makeSalt(); EncryptedLocalStore.setItem(saltKey, salt); }

Se o cdigo estiver criando um novo valor salt, o mtodo makeSalt() gera um valor aleatrio de 256 bits. Como o valor eventualmente armazenado no armazenamento local criptografado, ele gerado como um objeto ByteArray. O mtodo makeSalt() usa o mtodo Math.random() para gerar aleatoriamente o valor. O mtodo Math.random() no pode gerar 256 bits de uma vez. Em vez disso, o cdigo usa um loop para chamar o Math.random() oito vezes. A cada vez, um valor uint aleatrio entre 0 e 4294967295 (o valor uint mximo) gerado. Um valor uint usado por convenincia, pois um uint usa exatamente 32 bits. Quando oito valores uint so gravados no ByteArray, gerado um valor de 256 bits. Este o cdigo para o mtodo makeSalt():
private function makeSalt():ByteArray { var result:ByteArray = new ByteArray; for (var i:uint = 0; i < 8; i++) { result.writeUnsignedInt(Math.round(Math.random() * uint.MAX_VALUE)); } return result; }

Quando o cdigo est salvando o salt no armazenamento local criptografado (ELS) ou recuperando o salt do ELS, ele precisa da chave String com a qual o salt salvo. Sem saber a chave, o valor salt no pode ser recuperado. Nesse caso, a chave de criptografia no pode ser recriada todas as vezes para abrir novamente o banco de dados. Por padro, o EncryptionKeyGenerator usa uma chave ELS predefinida que definida na constante SALT_ELS_KEY. Em vez de usar a chave padro, o cdigo do aplicativo tambm pode especificar uma chave ELS para usar na chamada do mtodo getEncryptionKey(). A Chave ELS padro ou a chave ELS salt especificada pelo aplicativo armazenada em uma varivel chamada de saltKey. Essa varivel usada nas chamadas a EncryptedLocalStore.setItem() e EncryptedLocalStore.getItem(), como mostrado antes.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

761

Combinar a senha de 256 bits e o salt usando o operador XOR Adobe AIR 1.5 e posterior O cdigo agora tem uma senha de 256 bits e um valor salt de 256 bits. Em seguida, ele usa uma operao XOR em nvel de bits para combinar o salt e a senha concatenada em um nico valor. Efetivamente, essa tcnica cria um senha de 256 bits que consiste em caracteres do intervalo inteiro de caracteres possveis. Esse princpio verdadeiro, embora muito provavelmente a entrada de senha real consista principalmente em caracteres alfanumricos. Essa no-aleatoriedade elevada oferece o benefcio de tornar o conjunto de senhas possveis maior, sem exigir que o usurio digite uma senha longa e complexa. O resultado da operao XOR armazenado na varivel unhashedKey. O processo real de execuo de um XOR em nvel de bits nos dois valores ocorre no mtodo xorBytes():
var unhashedKey:ByteArray = xorBytes(concatenatedPassword, salt);

O operador XOR em nvel de bits (^) retira dois valores uint e retorna um valor uint. (Um valor uint contm 32 bits.) Os valores de entrada enviados como argumentos para o mtodo xorBytes() so uma String (a senha) e um ByteArray (o salt). Conseqentemente, o cdigo usa um loop para extrair 32 bits de uma vez de cada entrada para combinar usando o operador XOR.
private function xorBytes(passwordString:String, salt:ByteArray):ByteArray { var result:ByteArray = new ByteArray(); for (var i:uint = 0; i < 32; i += 4) { // ... } return result; }

No loop, os primeiros 32 bits (4 bytes) so extrados do parmetro passwordString. Esses bits so extrados e convertidos em um uint (o1) em um processo de duas partes. Primeiro, o mtodo charCodeAt() obtm cada valor numrico do caractere. Depois, esse valor desviado para a posio apropriada na unidade usando o operador de desvio esquerda em nvel de bits (<<) e o valor desviado adicionado ao o1. Por exemplo, o primeiro caractere (i) se torna os primeiros 8 bits usando o operador de desvio esquerda em nvel de bits (<<) para desviar os bits deixados por 24 bits e atribuindo esse valor ao o1. O segundo caractere (i + 1) se torna os segundos 8 bits desviando seu valor 16 bits esquerda e adicionando o resultado a o1. Os valores do terceiro e do quarto caracteres so adicionados da mesma forma.
// ... // Extract 4 bytes from the password string and convert to a uint var o1:uint = passwordString.charCodeAt(i) << 24; o1 += passwordString.charCodeAt(i + 1) << 16; o1 += passwordString.charCodeAt(i + 2) << 8; o1 += passwordString.charCodeAt(i + 3); // ...

A varivel o1 agora contm 32 bits do parmetro passwordString. Em seguida, 32 bits so extrados do parmetro salt, chamando seu mtodo readUnsignedInt(). Os 32 bits so armazenados em uma varivel uint o2.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

762

// ... salt.position = i; var o2:uint = salt.readUnsignedInt(); // ...

Finalmente, os dois valores de 32 bits (uint) so combinados usando o operador XOR, e o resultado gravado em um ByteArray chamado de result.
// ... var xor:uint = o1 ^ o2; result.writeUnsignedInt(xor); // ...

Quando o loop concludo, o ByteArray contendo o resultado XOR retornado.

// ... } return result; }

Hash da chave Adobe AIR 1.5 e posterior Aps a senha concatenada e o salt serem combinados, a prxima etapa oferecer proteo adicional a esse valor, fazendo hash dele por meio do algoritmo de hash SHA-256. O processo de hash dificulta para um invasor realizar a engenharia reversa no valor. Nesse ponto, o cdigo tem um ByteArray chamado de unhashedKey, que contm a senha concatenada combinada com o salt. O projeto de biblioteca central (as3corelib) do ActionScript 3.0 inclui uma classe SHA256 no pacote com.adobe.crypto. O mtodo SHA256.hashBytes(), que realiza um hash de SHA-256 em um ByteArray e retorna uma String contendo o resultado do hash de 256 bits como um nmero decimal. A classe EncryptionKeyGenerator usa a classe SHA256 para aplicar hash chave:
var hashedKey:String = SHA256.hashBytes(unhashedKey);

Extrair a chave de criptografia do hash Adobe AIR 1.5 e posterior A chave de criptografia deve ser um ByteArray com exatamente 16 bytes (128 bits). O resultado do algoritmo de hash SHA-256 tem sempre 256 bits. Conseqentemente, a etapa final selecionar 128 bits do resultado com hash para usar como chave de criptografia real. Na classe EncryptionKeyGenerator, o cdigo reduz a chave para 128 bits chamando o mtodo generateEncryptionKey(). Em seguida, ele retorna esse resultado do mtodo como o resultado do mtodo getEncryptionKey():
var encryptionKey:ByteArray = generateEncryptionKey(hashedKey); return encryptionKey;

necessrio usar os primeiros 128 bits como a chave de criptografia. Voc pode selecionar um intervalo de bits iniciando em algum ponto arbitrrio, pode selecionar todos os outros bits ou usar alguma outra maneira de selecionar bits. O importante que o cdigo selecione 128 bits diferentes e que os mesmos 128 bits sejam usados a cada vez.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

763

Nesse caso, o mtodo generateEncryptionKey() usa o intervalo de bits que comea no 18 byte como a chave de criptografia. Como mencionado antes, a classe SHA256 retorna uma String contendo um hash de 256 bits como nmero hexadecimal. Um nico bloco de 128 bits no tem muitos bytes a acrescentar a um ByteArray de uma vez. Conseqentemente, o cdigo usa um loop for para extrair caracteres da String hexadecimal, convertendo-os em valores numricos reais e adicionando-os ao ByteArray. A String de resultado SHA-256 tem 64 caracteres. Um intervalo de 128 bits equivale a 32 caracteres na String, e cada caractere representa 4 bits. O menor incremento de dados que voc pode adicionar a um ByteArray um byte (8 bits), o que equivalente a dois caracteres na String hash. Conseqentemente, o loop conta de 0 a 31 (32 caracteres) em incrementos de 2 caracteres. Dentro do loop, o cdigo determina primeiro a posio inicial do par de caracteres atual. Como o intervalo desejado comea na posio de indexao 17 (o 18 byte) do caractere, a varivel position atribuda ao valor iterador da corrente (i) mais 17. O cdigo usa o mtodo substr() do objeto da String para extrair os dois caracteres na posio atual. Esses caracteres so armazenados na varivel hex. Em seguida, o cdigo usa o mtodo parseInt() para converter a String hex a um valor inteiro decimal. Ele armazena esse valor na varivel byte. Finalmente, o cdigo adiciona o valor de byte ao ByteArray result usando o mtodo writeByte(). Quando o loop concludo, o ByteArray result contm 16 bytes e est pronto para ser usado como chave de criptografia do banco de dados.
private function generateEncryptionKey(hash:String):ByteArray { var result:ByteArray = new ByteArray(); for (var i:uint = 0; i < 32; i += 2) { var position:uint = i + 17; var hex:String = hash.substr(position, 2); var byte:int = parseInt(hex, 16); result.writeByte(byte); } return result; }

Estratgias para trabalhar com bancos de dados SQL

Adobe AIR 1.0 e posterior Existem vrias maneiras pelas quais um aplicativo pode acessar e trabalhar com um banco de dados SQL local. O design do aplicativo pode variar em termos de como seu cdigo organizado, a seqncia e o intervalo de execuo das operaes, e assim por diante. As tcnicas que voc escolhe podem afetar a facilidade com que o aplicativo desenvolvido. Elas podem afetar a facilidade com que voc modificar o aplicativo em futuras atualizaes. Elas tambm podem afetar o desempenho do aplicativo do ponto de vista dos usurios.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

764

Distribuio de um banco de dados previamente preenchido

Adobe AIR 1.0 e posterior Quando voc usa um banco de dados SQL local do AIR no seu aplicativo, este espera um banco de dados com uma certa estrutura de tabelas, colunas e assim por diante. Alguns aplicativos tambm esperam que certos dados estejam previamente preenchidos no arquivo de banco de dados. Uma forma de assegurar que o banco de dados tenha a estrutura apropriada criar um banco de dados no cdigo do aplicativo. Quando o aplicativo carregado, ele verifica se o arquivo de banco de dados correspondente existe em um determinado local. Se o arquivo no existir, o aplicativo executar um conjunto de comandos para criar o arquivo de banco de dados, criar a estrutura do banco de dados e preencher as tabelas com os dados iniciais. O cdigo que cria o banco de dados e suas tabelas geralmente complexo. Com freqncia, ele s usado uma vez durante o perodo em que o aplicativo fica instalado, mas ainda assim aumenta o tamanho e a complexidade do aplicativo. Como alternativa criao do banco de dados, da estrutura e dos dados de modo programtico, voc pode distribuir um banco de dados previamente preenchido com o aplicativo. Para distribuir um banco de dados predefinido, inclua o arquivo correspondente no pacote AIR do aplicativo. Como todos os arquivos que so includos em um pacote AIR, um arquivo de banco de dados compactado instalado no diretrio do aplicativo (o diretrio representado pela propriedade File.applicationDirectory). No entanto, os arquivos desse diretrio so somente leitura. Use o arquivo do pacote AIR como um banco de dados modelo. Na primeira vez que um usurio executar o aplicativo, copie o arquivo de banco de dados original para o Apontar para o diretrio de armazenamento do aplicativo na pgina 657 do usurio (ou outro local) e use esse banco de dados no aplicativo.

Prticas recomendadas de trabalho com bancos de dados SQL locais

Adobe AIR 1.0 e posterior A lista a seguir um conjunto de tcnicas sugeridas que voc pode usar para melhorar o desempenho, a segurana e a facilidade de manuteno dos seus aplicativos quando trabalhar com bancos de dados SQL locais.

Crie conexes de banco de dados previamente

Adobe AIR 1.0 e posterior Mesmo que o seu aplicativo no execute nenhuma instruo quando inicialmente carregado, instancie um objeto SQLConnection e chame o mtodo open() ou openAsync() correspondente com antecedncia (por exemplo, aps a inicializao do aplicativo) para evitar atrasos na execuo de instrues. Consulte Conexo com um banco de dados na pgina 713.

Reutilize conexes de banco de dados

Adobe AIR 1.0 e posterior Se voc acessa um certo banco de dados ao longo da execuo do seu aplicativo, mantenha uma referncia ocorrncia de SQLConnection e a reutilize no aplicativo inteiro em vez de fechar e reabrir a conexo. Consulte Conexo com um banco de dados na pgina 713.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com bancos de dados SQL locais no AIR

765

D preferncia ao modo de execuo assncrona

Adobe AIR 1.0 e posterior Quando criamos um cdigo de acesso a dados, pode ser tentador executar operaes de maneira sncrona em vez de assncrona, porque usar operaes sncronas geralmente requer um cdigo mais curto e menos complexo. Porm, conforme descrito na seo Uso de operaes de banco de dados sncronas e assncronas na pgina 740, as operaes sncronas podem ter um impacto no desempenho que bvio para os usurios e prejudicial para a experincia deles no aplicativo. O tempo usado para uma nica operao varia conforme a operao e, principalmente, o volume de dados envolvido. Por exemplo, uma instruo SQL INSERT que s adiciona uma linha ao banco de dados demora menos tempo do que uma instruo SELECT que recupera milhares de linhas de dados. No entanto, quando voc usa a execuo sncrona para realizar vrias operaes, as operaes normalmente so encadeadas. Mesmo que o tempo que cada operao leve seja muito curto, o aplicativo fica congelado at a concluso de todas as operaes sncronas. Por isso, o tempo acumulado de vrias operaes encadeadas pode ser suficiente para paralisar o aplicativo. Use operaes assncronas como uma abordagem padro, principalmente no caso de operaes que envolvem um grande nmero de linhas. H uma tcnica para dividir o processamento de grandes conjuntos de resultados de instrues SELECT, descrita em Recuperao dos resultados de SELECT em partes na pgina 729. No entanto, ela s pode ser usada no modo de execuo assncrona. Utilize operaes sncronas apenas quando no conseguir obter uma certa funcionalidade usando programao assncrona, quando tiver considerado as vantagens e desvantagens para os usurios do aplicativo em termos de desempenho e quando testar o aplicativo e perceber que o desempenho foi afetado. O uso da execuo assncrona pode envolver uma codificao mais complexa. Porm, lembre-se de que voc s precisa criar o cdigo uma vez, mas que os usurios do aplicativo tm de us-lo repetidas vezes, de forma gil ou lentamente. Em muitos casos, usando uma ocorrncia de SQLStatement parte para cada instruo SQL a ser executada, possvel enfileirar vrias operaes SQL de uma s vez, o que torna o cdigo assncrono parecido com o cdigo sncrono quanto maneira como ele criado. Para obter mais informaes, consulte Noes bsicas sobre o modelo de execuo assncrona na pgina 744.

Use instrues SQL separadas e no altere a propriedade text de SQLStatement

Adobe AIR 1.0 e posterior Para qualquer instruo SQL executada mais de uma vez em um aplicativo, crie uma ocorrncia de SQLStatement parte para cada instruo SQL. Use essa ocorrncia de SQLStatement sempre que esse comando SQL for executado. Por exemplo, suponha que voc est criando um aplicativo que inclui quatro operaes SQL diferentes executadas vrias vezes. Nesse caso, crie quatro ocorrncias separadas de SQLStatement e chame o mtodo execute() de cada instruo para execut-la. Evite a alternativa de usar uma nica ocorrncia de SQLStatement para todas as instrues SQL, sempre redefinindo sua propriedade text antes de executar a instruo.

Use parmetros de instruo

Adobe AIR 1.0 e posterior Use parmetros SQLStatement nunca concatene a entrada do usurio no texto da instruo. O uso de parmetros torna o seu aplicativo mais seguro porque impede a possibilidade de ataques de injeo SQL. Isso permite usar objetos em consultas (e no apenas valores literais SQL). Tambm torna a execuo das instrues mais eficiente, porque elas podem ser reutilizadas sem que voc precise recompil-las todas as vezes que forem executadas. Consulte Uso de parmetros em instrues na pgina 717 para obter mais informaes.

ltima atualizao em 29/3/2011

766

Captulo 39: Trabalhar com matrizes de bytes

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe ByteArray permite que voc leia de e escreva para um fluxo de dados binrio, que essencialmente uma matriz de bytes. Essa classe fornece uma maneira de acessar dados no nvel mais elementar. Como os dados do computador consistem em bytes, ou grupos de 8 bits, a capacidade de ler dados em bytes significa que voc pode acessar dados para os quais classes e mtodos de acesso no existem. A classe ByteArray permite que voc analise qualquer fluxo de dados, de um bitmap a um fluxo de dados que viaje pela rede, no nvel de byte. O mtodo writeObject() permite que voc escreva um objeto em AMF serializado para um ByteArray, enquanto o mtodo readObject() permite que voc leia um objeto serializado de um ByteArray para uma varivel do tipo de dados original. Voc pode serializar qualquer objeto, exceto objetos de exibio, que so aqueles que podem ser colocados na lista de exibio. Voc tambm pode atribuir objetos serializados de volta s instncias de classe personalizada se a classe personalizada estiver disponvel para o tempo de execuo. Aps converter um objeto para AMF, voc pode transferi-lo de modo eficiente por uma conexo de rede ou salv-lo em um arquivo. O aplicativo de exemplo do Adobe AIR descrito aqui l um arquivo .zip como exemplo de processar um fluxo de bytes, extrair uma lista dos arquivos contidos no arquivo .zip e escrev-los na rea de trabalho.

Mais tpicos da Ajuda

flash.utils.ByteArray flash.utils.IExternalizable Especificao do Action Message Format

Ler e escrever um ByteArray

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe ByteArray parte do pacote flash.utils. Para criar um objeto ByteArray no ActionScript 3.0, importe a classe ByteArray e invoque o construtor, conforme exibido no seguinte exemplo:
import flash.utils.ByteArray; var stream:ByteArray = new ByteArray();

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalhar com matrizes de bytes

767

Mtodos ByteArray
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Qualquer fluxo de dados significativo organizado em um formato que voc pode analisar para encontrar as informaes desejadas. Um registro em um simples arquivo de um funcionrio, por exemplo, provavelmente incluiria um nmero de ID, um nome, um endereo, um nmero de telefone e assim por diante. Um arquivo de udio MP3 contm uma marca ID3 que identifica o ttulo, autor, lbum, data de publicao e gnero do arquivo que est sendo obtido por download. O formato permite que voc saiba a ordem na qual esperar os dados no fluxo de dados. Ele permite que voc leia o fluxo de bytes de modo inteligente. A classe ByteArray inclui vrios mtodos que facilitam ler de e escrever para um fluxo de dados. Alguns desses mtodos incluem readBytes() e writeBytes(), readInt() e writeInt(), readFloat() e writeFloat(), readObject() e writeObject() e readUTFBytes() e writeUTFBytes(). Esses mtodos permitem que voc leia dados do fluxo de dados em variveis de tipos de dados especficos e escreva de tipos de dados especficos diretamente para o fluxo de dados binrio. Por exemplo, o cdigo a seguir l uma matriz simples de seqncias de caracteres e nmeros de ponto flutuante e escreve cada elemento em um ByteArray. A organizao da matriz permite que o cdigo chame os mtodos ByteArray apropriados (writeUTFBytes() e writeFloat()) para escrever os dados. O padro de dados repetitivo possibilita ler a matriz com um loop.
// The following example reads a simple Array (groceries), made up of strings // and floating-point numbers, and writes it to a ByteArray. import flash.utils.ByteArray; // define the grocery list Array var groceries:Array = ["milk", 4.50, "soup", 1.79, "eggs", 3.19, "bread" , 2.35] // define the ByteArray var bytes:ByteArray = new ByteArray(); // for each item in the array for (var i:int = 0; i < groceries.length; i++) { bytes.writeUTFBytes(groceries[i++]); //write the string and position to the next item bytes.writeFloat(groceries[i]);// write the float trace("bytes.position is: " + bytes.position);//display the position in ByteArray } trace("bytes length is: " + bytes.length);// display the length

A propriedade position
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A propriedade position armazena a posio atual do ponteiro que indexa ByteArray durante a leitura ou escrita. O valor inicial da propriedade position 0 (zero), como exibido no seguinte cdigo:
var bytes:ByteArray = new ByteArray(); trace("bytes.position is initially: " + bytes.position); // 0

Quando voc l de ou escreve em um ByteArray, o mtodo usado atualiza a propriedade position para apontar para o local imediatamente seguindo o ltimo byte lido ou escrito. Por exemplo, o cdigo a seguir escreve uma seqncia de caracteres em um ByteArray e, posteriormente, a propriedade position aponta para o byte imediatamente seguindo a seqncia de caracteres no ByteArray:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalhar com matrizes de bytes

768

var bytes:ByteArray = new ByteArray(); trace("bytes.position is initially: " + bytes.position); // 0 bytes.writeUTFBytes("Hello World!"); trace("bytes.position is now: " + bytes.position);// 12

Da mesma forma, uma operao de leitura incrementa a propriedade position pelo nmero de bytes lidos.
var bytes:ByteArray = new ByteArray(); trace("bytes.position is initially: " + bytes.position); // 0 bytes.writeUTFBytes("Hello World!"); trace("bytes.position is now: " + bytes.position);// 12 bytes.position = 0; trace("The first 6 bytes are: " + (bytes.readUTFBytes(6)));//Hello trace("And the next 6 bytes are: " + (bytes.readUTFBytes(6)));// World!

Observe que voc pode definir a propriedade position para um local especfico no ByteArray para ler ou escrever naquele deslocamento.

As propriedades bytesAvailable e length

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior As propriedades length e bytesAvailable dizem a voc quanto tempo um ByteArray possui e quantos bytes permanecem nele da posio atual at o fim. O exemplo a seguir ilustra como voc pode usar essas propriedades. O exemplo escreve uma seqncia de caracteres de texto para o ByteArray e, em seguida, l um byte de cada vez do ByteArray at que ele encontre o caractere a ou o final (bytesAvailable <= 0).
var bytes:ByteArray = new ByteArray(); var text:String = "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Vivamus etc."; bytes.writeUTFBytes(text); // write the text to the ByteArray trace("The length of the ByteArray is: " + bytes.length);// 70 bytes.position = 0; // reset position while (bytes.bytesAvailable > 0 && (bytes.readUTFBytes(1) != 'a')) { //read to letter a or end of bytes } if (bytes.position < bytes.bytesAvailable) { trace("Found the letter a; position is: " + bytes.position); // 23 trace("and the number of bytes available is: " + bytes.bytesAvailable);// 47 }

A propriedade endian
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os computadores podem diferir em como armazenam nmeros de vrios bytes, isto , nmeros que exigem mais de um 1 byte de memria para armazen-los. Um inteiro, por exemplo, pode levar 4 bytes, ou 32 bits, de memria. Alguns computadores armazenam o byte mais significativo do nmero primeiro, no endereo de memria mais baixo e outros armazenam o byte menos significativo primeiro. Esse atributo de um computador, ou de uma ordem de bytes, conhecido como sendo big endian (byte mais significativo primeiro) ou little endian (byte menos significativo primeiro). Por exemplo, o nmero 0x31323334 seria armazenado da seguinte forma para ordem de bytes big endian e little endian, onde a0 representa o endereo de memria mais baixo dos 4 bytes e a3 representa o mais alto:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalhar com matrizes de bytes

769

Big Endian a0 31

Big Endian a1 32

Big Endian a2 33

Big Endian a3 34

Little Endian a0 34

Little Endian a1 33

Little Endian a2 32

Little Endian a3 31

A propriedade endian da classe ByteArray permite que voc denote essa ordem de bytes para nmeros de vrios bytes que voc esteja processando. Os valores aceitveis para essa propriedade so "bigEndian" ou "littleEndian" e a classe Endian define as constantes BIG_ENDIAN e LITTLE_ENDIAN para definir a propriedade endian com essas seqncias de caracteres.

Os mtodos compress() e uncompress()

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O mtodo compress() permite que voc compacte um ByteArray de acordo com um algoritmo de compactao especificado como um parmetro. O mtodo uncompress() permite que voc descompacte um ByteArray compactado de acordo com um algoritmo de compactao. Aps chamar compress() e uncompress(), o comprimento da matriz de bytes definida para o novo comprimento e a propriedade position definida para o fim. A classe CompressionAlgorithm (AIR) define constantes que voc pode usar para especificar o algoritmo de compactao. A classe ByteArray suporta os algoritmos deflate (apenas no AIR) e zlib. O algoritmo de compactao deflate usado em vrios formatos de compactao, tais como zlib, gzip e algumas implementaes zip. O formato de dados compactado zlib descrito em http://www.ietf.org/rfc/rfc1950.txt e o algoritmo de compactao deflate descrito em http://www.ietf.org/rfc/rfc1951.txt. O exemplo a seguir compacta um ByteArray chamado bytes usando o algoritmo deflate:
bytes.compress(CompressionAlgorithm.DEFLATE);

O exemplo a seguir descompacta um ByteArray compactado usando o algoritmo deflate:

bytes.uncompress(CompressionAlgorithm.DEFLATE);

Leitura e escrita de objetos

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os mtodos readObject() e writeObject() lem um objeto de e escrevem um objeto para um ByteArray, codificado em AMF serializado. AMF um protocolo de mensagens proprietrio criado pela Adobe e usado por vrias classes do ActionScript 3.0, incluindo Netstream, NetConnection, NetStream, LocalConnection e Shared Objects. Um marcador de tipo de um byte descreve o tipo dos dados codificados que segue. O AMF usa os 13 tipos de dados a seguir:
value-type = undefined-marker | null-marker | false-marker | true-marker | integer-type | double-type | string-type | xml-doc-type | date-type | array-type | object-type | xml-type | byte-array-type

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalhar com matrizes de bytes

770

Os dados codificados seguem o marcador de tipo, a menos que o marcador represente um nico valor possvel, como null ou true ou false, em cujo caso nada mais codificado. Existem duas verses do AMF: AMF0 e AMF3. O AMF 0 suporta o envio de objetos complexos por referncia e permite pontos de extremidade para restaurar as relaes entre objetos. O AMF 3 melhora o AMF 0 enviando caractersticas de objetos e seqncias de caracteres por referncia, alm de referncias de objetos, e suportando novos tipos de dados introduzidos no ActionScript 3.0. A propriedade ByteArray.objectEcoding especifica a verso do AMF usada para codificar os dados do objeto. A classe flash.net.ObjectEncoding define constantes para especificar a verso do AMF: ObjectEncoding.AMF0 e ObjectEncoding.AMF3. O exemplo a seguir chama writeObject() para escrever um objeto XML para um ByteArray, que ele, em seguida compacta usando o algoritmo Deflate e escreve para o arquivo order na rea de trabalho. O exemplo usa um rtulo para exibir a mensagem Arquivo de ordem escrito na rea de trabalho! na janela do AIR quando concludo.
/* The following lines, minus comment characters , are for Flex version: * <?xml version="1.0" encoding="utf-8"?> * <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" * creationComplete="init();"> * <mx:Script> * <![CDATA[ */ import flash.filesystem.*; import flash.utils.ByteArray; // import mx.controls.Label for Flex import fl.controls.Label // for Flash; Label component must be in Library // for Flex: private function init():void { var bytes:ByteArray = new ByteArray(); var myLabel:Label = new Label(); myLabel.move(150, 150); myLabel.width = 200; addChild(myLabel); var myXML:XML = <order> <item id='1'> <menuName>burger</menuName> <price>3.95</price> </item> <item id='2'> <menuName>fries</menuName> <price>1.45</price> </item> </order> // Write XML object to ByteArray bytes.writeObject(myXML);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalhar com matrizes de bytes

771

bytes.position = 0;//reset position to beginning bytes.compress(CompressionAlgorithm.DEFLATE);// compress ByteArray outFile("order", bytes); myLabel.text = "Wrote order file to desktop!"; // for Flex: } // end of init()function outFile(fileName:String, data:ByteArray):void { var outFile:File = File.desktopDirectory; // dest folder is desktop outFile = outFile.resolvePath(fileName); // name of file to write var outStream:FileStream = new FileStream(); // open output file stream in WRITE mode outStream.open(outFile, FileMode.WRITE); // write out the file outStream.writeBytes(data, 0, data.length); // close it outStream.close(); } /* Add the following lines for Flex, minus comment characters: * ]]> * </mx:Script> * </mx:WindowedApplication> */

O mtodo readObject() l um objeto no AMF serializado de um ByteArray e o armazena em um objeto do tipo especificado. O exemplo a seguir l o arquivo order da rea de trabalho em um ByteArray (inBytes), o descompacta e chama readObject() para armazen-lo no objeto XML orderXML. O exemplo usa uma construo de loop for each() para adicionar cada n a uma rea de texto para exibio. O exemplo tambm exibe o valor da propriedade objectEncoding juntamente com um cabealho para o contedo do arquivo order.
/* The following lines, minus comment characters, are for Flex version: * <?xml version="1.0" encoding="utf-8"?> * <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" * creationComplete="init();"> * <mx:Script> * <![CDATA[ */ import flash.filesystem.*; import flash.utils.ByteArray; import fl.controls.TextArea; // in Flash, TextArea component must be in Library // for Flex version: import mx.controls; // for Flex version: private function init():void {var inBytes:ByteArray = new ByteArray(); // define text area for displaying XML content var myTxt:TextArea = new TextArea(); myTxt.width = 550; myTxt.height = 400; addChild(myTxt); //display objectEncoding and file heading myTxt.text = "Object encoding is: " + inBytes.objectEncoding + "\n\n" + "order file: \n\n"; readFile("order", inBytes); inBytes.position = 0; // reset position to beginning inBytes.uncompress(CompressionAlgorithm.DEFLATE); inBytes.position = 0;//reset position to beginning // read XML Object var orderXML:XML = inBytes.readObject();

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalhar com matrizes de bytes

772

//for each node in orderXML for each(var child:XML in orderXML) { // append child node to text area myTxt.text += child + "\n"; } // for Flex version: } // end of init() // read specified file into byte array function readFile(fileName:String, data:ByteArray) { var inFile:File = File.desktopDirectory; // source folder is desktop inFile = inFile.resolvePath(fileName); // name of file to read var inStream:FileStream = new FileStream(); inStream.open(inFile, FileMode.READ); inStream.readBytes(data, 0, data.length); inStream.close(); } /* Add the following lines, minus comment characters, for Flex: * ]]> * </mx:Script> * * </mx:WindowedApplication> */

Exemplo de ByteArray: leitura de um arquivo .zip

Adobe AIR 1.0 e posterior Esse exemplo demonstra como ler um simples arquivo .zip contendo vrios arquivos de diferentes tipos. Ele faz isso extraindo dados relevantes dos metadados para cada arquivo, descompactando cada arquivo em um ByteArray e escrevendo o arquivo na rea de trabalho. A estrutura geral de um arquivo .zip baseada na especificao de PKWARE Inc., mantida em http://www.pkware.com/documents/casestudies/APPNOTE.TXT. Primeiramente, est o cabealho de um arquivo e os dados do arquivo para o primeiro arquivo no arquivo .zip, seguido por um cabealho de arquivo e par de dados de arquivo para cada arquivo adicional. (A estrutura do cabealho do arquivo descrita posteriormente.) Em seguida, o arquivo .zip inclui opcionalmente um registro de descritor de dados (normalmente quando o arquivo zip de sada foi criado na memria, e no salvo em um disco). Em seguida, esto vrios elementos opcionais adicionais: cabealho de descriptografia do arquivo, registro de dados extra do arquivo, estrutura de diretrio central, final Zip64 de registro de diretrio central, final Zip64 de localizador de diretrio central e final de registro de diretrio central. O cdigo nesse exemplo escrito para analisar apenas arquivos zip que no contm pastas e ele no espera registros de descritor de dados. Ele ignora todas as informaes seguindo os dados do ltimo arquivo. O formato do cabealho do arquivo para cada arquivo o seguinte:
assinatura do cabealho do arquivo verso necessria sinalizador de bits de propsito geral mtodo de compactao ltima hora de modificao do arquivo ltima data de modificao do arquivo 4 bytes 2 bytes 2 bytes 2 bytes (8=DEFLATE; 0=UNCOMPRESSED) 2 bytes 2 bytes

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalhar com matrizes de bytes

773

crc-32 tamanho compactado tamanho descompactado comprimento do nome do arquivo comprimento de campo extra nome de arquivo campo extra

4 bytes 4 bytes 4 bytes 2 bytes 2 bytes varivel varivel

Seguindo o cabealho do arquivo esto os dados reais do arquivo, que podem ser compactados ou no, dependendo do sinalizador de mtodo de compactao. O sinalizador 0 (zero) se os dados do arquivo so descompactados, 8 se os dados so compactados usando o algoritmo DEFLATE ou outro valor para outros algoritmos de compactao. A interface de usurio para esse exemplo consiste de um rtulo e uma rea de texto (taFiles). O aplicativo escreve as seguintes informaes na rea de texto para cada arquivo encontrado no arquivo .zip: o nome de arquivo, o tamanho compactado e o tamanho descompactado. O documento MXML a seguir define a interface do usurio para a verso Flex do aplicativo:
<?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical" creationComplete="init();"> <mx:Script> <![CDATA[ // The application code goes here ]]> </mx:Script> <mx:Form> <mx:FormItem label="Output"> <mx:TextArea id="taFiles" width="320" height="150"/> </mx:FormItem> </mx:Form> </mx:WindowedApplication>

O incio do programa executa as seguintes tarefas:

Importa as classes necessrias

import flash.filesystem.*; import flash.utils.ByteArray; import flash.events.Event;

Define a interface de usurio para Flash

import fl.controls.*; //requires TextArea and Label components in the Library var taFiles = new TextArea(); var output = new Label(); taFiles.setSize(320, 150); taFiles.move(10, 30); output.move(10, 10); output.width = 150; output.text = "Contents of HelloAir.zip"; addChild(taFiles); addChild(output);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalhar com matrizes de bytes

774

Define o ByteArray bytes

var bytes:ByteArray = new ByteArray();

Define variveis para armazenar metadados do cabealho do arquivo

// var var var var var var var var variables for reading fixed portion of file header fileName:String = new String(); flNameLength:uint; xfldLength:uint; offset:uint; compSize:uint; uncompSize:uint; compMethod:int; signature:int;

Define os objetos File (zfile) e FileStream (zStream) para representar o arquivo .zip e especifica o local do arquivo
.zip a partir do qual os arquivos so extrados um arquivo chamado HelloAIR.zip no diretrio da rea de trabalho.
// File variables for accessing .zip file var zfile:File = File.desktopDirectory.resolvePath("HelloAIR.zip"); var zStream:FileStream = new FileStream();

No Flex, o cdigo do programa comea no mtodo init(), chamado como manipulador creationComplete para a marca raiz mx:WindowedApplication.
// for Flex private function init():void {

O programa comea abrindo o arquivo .zip em modo READ.

zStream.open(zfile, FileMode.READ);

Ele, em seguida, define a propriedade endian de bytes para LITTLE_ENDIAN para indicar que a ordem de bytes de campos numricos possui o byte menos significativo primeiro.
bytes.endian = Endian.LITTLE_ENDIAN;

Em seguida, uma instruo while() comea um loop que continua at que a posio atual no fluxo do arquivo seja maior que ou igual ao tamanho do arquivo.
while (zStream.position < zfile.size) {

A primeira instruo dentro do loop l os primeiros 30 bytes do fluxo do arquivo no ByteArray bytes. Os primeiros 30 bytes formam a parte de tamanho fixo do cabealho do primeiro arquivo.
// read fixed metadata portion of local file header zStream.readBytes(bytes, 0, 30);

Em seguida, o cdigo l um inteiro (signature) dos primeiros bytes do cabealho de 30 bytes. A definio do formato ZIP especifica que a assinatura para cada cabealho de arquivo o valor hexadecimal 0x04034b50; se a assinatura for diferente, significa que o cdigo se moveu alm da parte do arquivo .zip e no existem mais arquivos para extrair. Nesse caso, o cdigo sai do loop while imediatamente, em vez de esperar pelo final da matriz de bytes.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalhar com matrizes de bytes

775

bytes.position = 0; signature = bytes.readInt(); // if no longer reading data files, quit if (signature != 0x04034b50) { break; }

A parte seguinte do cdigo l o byte do cabealho na posio de deslocamento 8 e armazena o valor na varivel compMethod. Esse byte contm um valor que indica o mtodo de compactao usado para compactar esse arquivo. Vrios mtodos de compactao so permitidos, mas, na prtica, praticamente todos os arquivos .zip usam o algoritmo de compactao DEFLATE. Se o arquivo atual compactado com a compactao DEFLATE, compMethod 8; se o arquivo descompactado, compMethod 0.
bytes.position = 8; compMethod = bytes.readByte(); // store compression method (8 == Deflate)

Seguindo os primeiros 30 bytes est uma parte de comprimento varivel do cabealho que contm o nome do arquivo e, possivelmente, um campo extra. A varivel offset armazena o tamanho dessa parte. O tamanho calculado pela adio do comprimento do nome do arquivo e o comprimento do campo extra, lido do cabealho nos deslocamentos 26 e 28.
offset = 0;// stores length of variable portion of metadata bytes.position = 26; // offset to file name length flNameLength = bytes.readShort();// store file name offset += flNameLength; // add length of file name bytes.position = 28;// offset to extra field length xfldLength = bytes.readShort(); offset += xfldLength;// add length of extra field

Em seguida, o programa l a parte de comprimento varivel do cabealho do arquivo para o nmero de bytes armazenados na varivel offset.
// read variable length bytes between fixed-length header and compressed file data zStream.readBytes(bytes, 30, offset);

O programa l o nome do arquivo da parte de comprimento varivel do cabealho e o exibe na rea de texto, juntamente com os tamanhos compactados (zip) e descompactados (original) do arquivo.
// Flash version bytes.position = 30; fileName = bytes.readUTFBytes(flNameLength); // read file name taFiles.appendText(fileName + "\n"); // write file name to text area bytes.position = 18; compSize = bytes.readUnsignedInt(); // store size of compressed portion taFiles.appendText("\tCompressed size is: " + compSize + '\n'); bytes.position = 22; // offset to uncompressed size uncompSize = bytes.readUnsignedInt(); // store uncompressed size taFiles.appendText("\tUncompressed size is: " + uncompSize + '\n');

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalhar com matrizes de bytes

776

// Flex version bytes.position = 30; fileName = bytes.readUTFBytes(flNameLength); // read file name taFiles.text += fileName + "\n"; // write file name to text area bytes.position = 18; compSize = bytes.readUnsignedInt(); // store size of compressed portion taFiles.text += "\tCompressed size is: " + compSize + '\n'; bytes.position = 22; // offset to uncompressed size uncompSize = bytes.readUnsignedInt(); // store uncompressed size taFiles.text += "\tUncompressed size is: " + uncompSize + '\n';

O exemplo l o resto do arquivo do fluxo de arquivos em bytes para o comprimento especificado pelo tamanho compactado, substituindo o cabealho do arquivo nos primeiros 30 bytes. O tamanho compactado preciso, mesmo se o arquivo no est compactado, porque, nesse caso, o tamanho compactado igual ao tamanho descompactado do arquivo.
// read compressed file to offset 0 of bytes; for uncompressed files // the compressed and uncompressed size is the same zStream.readBytes(bytes, 0, compSize);

Em seguida, o exemplo descompacta o arquivo compactado e chama a funo outfile() para escrev-la no fluxo de arquivos de sada. Ele transmite a outfile() o nome do arquivo e a matriz de bytes que contm os dados do arquivo.
if (compMethod == 8) // if file is compressed, uncompress { bytes.uncompress(CompressionAlgorithm.DEFLATE); } outFile(fileName, bytes); // call outFile() to write out the file

As chaves de fechamento indicam o final do loop while e do mtodo init() e do cdigo do aplicativo Flex, exceto para o mtodo outFile(). A execuo volta ao incio do loop while e continua processando os prximos bytes no arquivo .zip extraindo outro arquivo ou finalizando o processamento do arquivo .zip se o ltimo arquivo tiver sido processado.
} // end of while loop } // for Flex version, end of init() method and application

A funo outfile() abre um arquivo de sada no modo WRITE na rea de trabalho, dando a ele o nome fornecido pelo parmetro filename. Ela, em seguida, escreve os dados do arquivo do parmetro data para o fluxo do arquivo de sada (outStream) e fecha o arquivo.
// Flash version function outFile(fileName:String, data:ByteArray):void { var outFile:File = File.desktopDirectory; // destination folder is desktop outFile = outFile.resolvePath(fileName); // name of file to write var outStream:FileStream = new FileStream(); // open output file stream in WRITE mode outStream.open(outFile, FileMode.WRITE); // write out the file outStream.writeBytes(data, 0, data.length); // close it outStream.close(); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalhar com matrizes de bytes

777

private function outFile(fileName:String, data:ByteArray):void { var outFile:File = File.desktopDirectory; // dest folder is desktop outFile = outFile.resolvePath(fileName); // name of file to write var outStream:FileStream = new FileStream(); // open output file stream in WRITE mode outStream.open(outFile, FileMode.WRITE); // write out the file outStream.writeBytes(data, 0, data.length); // close it outStream.close(); }

ltima atualizao em 29/3/2011

778

Captulo 40: Noes bsicas de rede e comunicao

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Ao criar aplicativos no Flash Player ou no AIR, voc precisa frequentemente acessar recursos fora de seu aplicativo. Por exemplo, voc pode enviar uma solicitao por uma imagem para um servidor web e receber os dados da imagem como retorno. Ou, voc pode enviar objetos serializados de um lado para o outro sobre uma conexo socket com um servidor de aplicativos. As APIs do Flash Player e do AIR fornecem vrias classes que permitem a seus aplicativos participao nesta troca. Estas APIs suportam rede com base em IP para protocolos como UDP,TCP, HTTP, RMTP e RTMFP. AS classes a seguir podem ser utilizadas para enviar e receber dados atravs de uma rede:
Classe Loader Formatos suportados de dados SWF, PNG, JPEG, GIF Protocolos HTTP, HTTPS Descrio Carrega tipos de dados com suporte e converte os dados em objetos de exibio. Consulte Carregamento dinmico do contedo da exibio na pgina 192. Carrega formatos arbitrarios de dados. Seu aplicativo responsvel por interpretar os dados. Consulte Uso da classe URLLoader na pgina 805 Enviar e baixar arquivos. Consulte Uso da classe FileReference na pgina 636 Faz conexo de vdeo, udio e strams de objetos remotos. Consulte Trabalho com vdeo na pgina 462. HTTP Carrega e reproduz formatos de udio com suporte. Consulte Carregamento de arquivos de som externos na pgina 431. Troca mensagens XML como um servidor XMLSocket. Consulte Soquetes XML na pgina 792. Conecta a um servidor de socket TCP. Consulte Soquetes binrios de cliente na pgina 787. Conecta a um servidor de socket TCP que requer segurana SSL ou TLS. Consulte Soquetes de cliente seguros (AIR) na pgina 787. Atua como um servidor para conexes de socket TCP de entrada. Consulte Soquetes de servidor na pgina 795.

URLLoader

Qualquer (texto, XML, binrio, etc.)

HTTP, HTTPS

FileReference

Qualquer elemento

HTTP

NetConnection

Som

Vdeo, udio, Formato de mensagem ActionScript (ActionScript Message Format AMF) udio

HTTP, HTTPS, RTMP e RTMFP

XMLSocket

XML

TCP

Socket

Qualquer elemento

TCP

SecureSocket (AIR)

Qualquer elemento

TCP com SSLv3 ou TLSv1

ServerSocket (AIR)

Qualquer elemento

TCP

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Noes bsicas de rede e comunicao

779

Classe DatagramSocket (AIR)

Formatos suportados de dados Qualquer elemento

Protocolos UDP

Descrio Envia e recebe pacotes UDP. Consulte Soquetes UDP (AIR) na pgina 797

Frequentemente, na criao de aplicativos web de grande ajuda armazenar informaes persistentes sobre o estado do aplicativo do usurio. Pginas e aplicativos HTML geralmente utilizam cookies para este propsito. No Flash Player, voc pode utilizar a classe ShareObject para o mesmo propsito. Consulte Objetos compartilhados na pgina 687. (A classe SharedObject pode ser utilizada em aplicativos AIR, mas existem menos restries ao apenas salvar os dados em um arquivo normal). Quando o seu Flash Player ou aplicativo AIR precisa se comunicar com outro Flash Player ou outro aplicativo AIR no mesmo computador, voc poder utilizar a classe LocalConnection. Por exemplo, dois (ou mais) arquivos SWF na mesma pgina podem se comunicar. Da mesma forma, um arquivo SWF em uma pgina pode se comunicar com um aplicativo AIR. Consulte Comunicao com outras instncias do Flash Player e AIR na pgina 820. Quando houver a necessidade de se comunicar com outros processos que no sejam SWF no computador local, voc pode utilizar a classe NativeProcess adicionada no AIR 2. A classe NativeProcess permite ao seu aplicativo AIR lanar e se comunicar com outros aplicativos. Consulte Comunicao com processos nativos do AIR na pgina 827. Quando for necessrio saber informaes sobre o ambiente de rede do computador no qual um aplicativo AIR est sendo executado, pode-se utilizar as seguintes classes:

NetworkInfoFornece informaes sobre as interfaces de rede disponveis, como o endereo IP do computador.

Consulte Interfaces de rede na pgina 780.

DNSResolverPermite o acesso aos registros de DNS. Consulte Registro do Sistema de Nome de Domnios
(DNS) na pgina 784.

ServiceMonitorPermite que voc monitore a disponibilidade de um servidor. Consulte Monitoramento de

servios na pgina 782.

URLMonitorPermite que voc monitore a disponibilidade de um recurso em um URL especifico. Consulte

Monitoramento de HTTP na pgina 783.

SocketMonitor e SecureSocketMonitorPermite que voc monitore a disponibilidade de um recurso em um

socket. Consulte Monitoramento de soquetes na pgina 783. Conceitos e termos importantes A lista a seguir de referncia contm termos importantes que voc vai encontrar ao programar o cdigo de sistemas de rede e comunicao:
Dados externos Dados que so armazenados em algum formato fora do aplicativo do e carregados no aplicativo quando necessrio. Esses dados podem ser armazenados em um arquivo que carregado diretamente, em um banco de dados ou de algum modo que permita recuper-los ao chamar scripts ou programas em execuo no servidor. Variveis codificadas por URL O formato codificado por URL permite representar diversas variveis (pares de nomes e valores de variveis) em uma nica string de texto. Variveis individuais so escritas no formato nome=valor. Cada varivel (ou seja, cada par de nome e valor) separada por caracteres E comercial, desta maneira: varivel1=valor1&varivel2=valor2. Desse modo, possvel enviar um nmero indefinido de variveis como uma s mensagem. Tipo MIME Cdigo padro usado para identificar o tipo de um dado arquivo em comunicao na Internet. Qualquer tipo de arquivo que tem um cdigo especfico usado para identific-lo. Ao enviar um arquivo ou uma mensagem, um computador (como um servidor Web ou uma ocorrncia do Flash Player ou do AIR de usurio) especificar o tipo de arquivo que est sendo enviado.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Noes bsicas de rede e comunicao

780

HTTP forma abreviada do termo em ingls Hypertext Transfer Protocol, um formato padro para apresentao de

pginas da Web e vrios outros tipos de contedo enviados pela Internet.

Mtodo de solicitao Quando um aplicativo (como um aplicativo AIR ou um navegador da Web) envia uma

mensagem (chamada de solicitao HTTP) para um servidor Web, qualquer dado que est sendo enviado pode ser incorporado solicitao de duas maneiras, por meio dos mtodos de solicitao GET e POST. No servidor, o programa que recebe a solicitao precisar localizar os dados no trecho adequado da solicitao, por isso o mtodo de solicitao usado para enviar dados do seu aplicativo deve corresponder ao mtodo de solicitao usado para ler esses dados no servidor.
Conexo de soquete Uma conexo persistente para comunicao entre dois computadores. Carregar o envio de arquivos para outro computador. Baixar usado para recuperar um arquivo contido em outro computador.

Interfaces de rede
Adobe AIR 2 e posterior Voc pode usar o objeto NetworkInfo para detectar as interfaces de rede de hardware e software disposio do seu aplicativo. O objeto NetworkInfo um objeto singleton, e voc no precisa cri-lo. Em vez disso, use a propriedade esttica de classe networkInfo para acessar o nico objeto NetworkInfo. Alm disso, o objeto NetworkInfo gera um evento networkChange quando uma das interfaces disponveis mudar. Chame o mtodo findInterfaces() para obter uma lista de objetos NetworkInterface. Cada objeto NetworkInterface da lista descreve uma das interfaces disponveis. O objeto NetworkInterface fornece informaes, tais como o endereo IP, endereo de hardware, unidade mxima de transmisso e se a interface est ativa. O exemplo de cdigo a seguir rastreia as propriedades do NetworkInterface de cada interface no computador cliente:
package { import flash.display.Sprite; import flash.net.InterfaceAddress; import flash.net.NetworkInfo; import flash.net.NetworkInterface; public class NetworkInformationExample extends Sprite { public function NetworkInformationExample() { var networkInfo:NetworkInfo = NetworkInfo.networkInfo; var interfaces:Vector.<NetworkInterface> = networkInfo.findInterfaces(); if( interfaces != null ) { trace( "Interface count: " + interfaces.length ); for each ( var interfaceObj:NetworkInterface in interfaces ) { trace( "\nname: " + interfaceObj.name ); trace( "display name: " + interfaceObj.displayName ); trace( "mtu: " + interfaceObj.mtu );

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Noes bsicas de rede e comunicao

781

trace( "active?: " + interfaceObj.active ); trace( "parent interface: " + interfaceObj.parent ); trace( "hardware address: " + interfaceObj.hardwareAddress ); if( interfaceObj.subInterfaces != null ) { trace( "# subinterfaces: " + interfaceObj.subInterfaces.length ); } trace("# addresses: " + interfaceObj.addresses.length ); for each ( var address:InterfaceAddress in interfaceObj.addresses ) { trace( " type: " + address.ipVersion ); trace( " address: " + address.address ); trace( " broadcast: " + address.broadcast ); trace( " prefix length: " + address.prefixLength ); } } } } } }

Para obter mais informaes, consulte:

NetworkInfo NetworkInterface InterfaceAddress

Mudanas na conectividade de rede

Adobe AIR 1.0 e posterior Seu aplicativo AIR pode ser executado em ambientes com conectividade de rede incerta e em mudana. Para ajudar um aplicativo a gerenciar conexes em recursos on-line, o Adobe AIR envia um evento de mudana de rede sempre que uma conexo de rede se torna disponvel ou indisponvel. O objeto NetworkInfo e o objeto NativeApplication do aplicativo geram o evento networkChange. Para reagir a esse evento, adicione um ouvinte:
NetworkInfo.networkInfo.addEventListener(Event.NETWORK_CHANGE, onNetworkChange);

E defina uma funo do manipulador de eventos:

function onNetworkChange(event:Event) { //Check resource availability }

O evento networkChange no indica uma mudana em toda a atividade de rede, mas apenas que uma conexo de rede individual sofreu mudana. O AIR no tenta interpretar o significado da mudana de rede. Um computador em rede pode ter vrias conexes reais e virtuais, portanto, perder uma conexo no significa necessariamente perder um recurso. Por outro lado, novas conexes tambm no garantem melhor disponibilidade de recursos. s vezes uma nova conexo pode at bloquear o acesso a recursos anteriormente disponveis (por exemplo, ao se conectar a uma VPN).

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Noes bsicas de rede e comunicao

782

Em geral, a nica maneira de um aplicativo determinar se ele pode se conectar a um recurso remoto por tentativa. A estrutura de monitoramento de servio um meio, com base em eventos, de reagir a mudanas na conectividade de rede de um host especfico. Nota: A estrutura de monitoramento de servio detecta se um servidor responde de maneira aceitvel a uma solicitao. Uma verificao bem-sucedida no garante conectividade plena. Servios dimensionveis da Web geralmente usam aparatos de cache e balanceamento de carga para redirecionar o trfego para um cluster de servidores Web. Nessa situao, provedores de servio s oferecem um diagnstico parcial de conectividade de rede.

Monitoramento de servios
Adobe AIR 1.0 e posterior O framework do monitor de servio, separado do framework do AIR, reside no arquivo aircore.swc. Para utilizar o framework, o arquivo aircore.swc deve ser includo no processo de criao. O Adobe Flash Builder inclui essa biblioteca automaticamente. A classe ServiceMonitor implementa a estrutura para monitorar servios de rede e oferece uma funcionalidade bsica para monitores de servio. Por padro, uma ocorrncia da classe ServiceMonitor despacha eventos relacionados conectividade de rede. O objeto ServiceMonitor envia esses eventos quando a instncia criada e sempre que o tempo de execuo detectar uma alterao na rede. Alm disso, voc pode definir a propriedade pollInterval de uma ocorrncia ServiceMonitor para verificar a conectividade em um intervalo especificado em milissegundos, independentemente de eventos gerais de conectividade de rede. Um objeto ServiceMonitor no verifica a conectividade de rede at que o mtodo start() seja chamado. A classe URLMonitor, uma subclasse da classe ServiceMonitor, detecta mudanas na conectividade HTTP para um URLRequest especificado. A classe SocketMonitor, tambm uma subclasse da classe ServiceMonitor, detecta mudanas na conectividade em um host especificado de uma porta especificada. Nota: Em verses anteriores ao AIR 2, o framework do monitor de servio era publicado na biblioteca servicemonitor.swc. A utilizao dessa biblioteca no mais recomendada. Em vez disso, utilize a biblioteca aircore.swc. Flash CS4 e CS5 Professional Execute as etapas a seguir para utilizar essas classes no Adobe Flash CS4 ou CS5 Professional:
1 Selecione o comando Arquivo > Configuraes de publicao. 2 Clique no boto Configuraes do ActionScript 3.0. Selecione Caminho da biblioteca. 3 Clique no boto Procurar em no SWC e navegue at a pasta AIK no diretrio dde instalao do Flash Professional. 4 Dentro dessa pasta, localize o arquivo /frameworks/libs/air/aircore.swc (para AIR 2) ou

/frameworks/libs/air/servicemonitor.swc (para AIR 1.5).

5 Clique no boto OK. 6 Adicione a seguinte instruo de importao ao cdigo do ActionScript 3.0:
import air.net.*;

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Noes bsicas de rede e comunicao

783

Flash CS3 Professional Para usar essas classes no Adobe Flash CS3 Professional, arraste o componente ServiceMonitorShim do painel Componentes para a Biblioteca e, em seguida, adicione a seguinte declarao import ao cdigo do ActionScript 3.0:
import air.net.*;

Monitoramento de HTTP
Adobe AIR 1.0 e posterior A classe URLMonitor determina se podem ser feitas solicitaes HTTP a um endereo especificado na porta 80 (a porta tpica para comunicao HTTP). O cdigo seguinte usa uma instncia da classe URLMonitor para detectar mudanas de conectividade no site da Adobe:
import air.net.URLMonitor; import flash.net.URLRequest; import flash.events.StatusEvent; var monitor:URLMonitor; monitor = new URLMonitor(new URLRequest('http://www.example.com')); monitor.addEventListener(StatusEvent.STATUS, announceStatus); monitor.start(); function announceStatus(e:StatusEvent):void { trace("Status change. Current status: " + monitor.available); }

Monitoramento de soquetes
Adobe AIR 1.0 e posterior Aplicativos AIR tambm podem usar conexes de soquete para conectividade modelo empurrar. Firewalls e roteadores de rede geralmente restringem a comunicao em rede em portas no autorizadas, por questes de segurana. Por esse motivo, os desenvolvedores devem considerar que usurios podem nem sempre ter recursos para fazer conexes de soquete. O cdigo seguinte usa uma instncia da classe SocketMonitor para detectar mudanas de conectividade com uma conexo de soquete. A porta monitorada a 6667, uma porta comum do IRC:
import air.net.ServiceMonitor; import flash.events.StatusEvent; socketMonitor = new SocketMonitor('www.example.com',6667); socketMonitor.addEventListener(StatusEvent.STATUS, socketStatusChange); socketMonitor.start(); function announceStatus(e:StatusEvent):void { trace("Status change. Current status: " + socketMonitor.available); }

Caso o servidor socket necessite um conexo segura, voc pode utilizar a classe SecureSocketMonitor ao invs da SocketMonitor.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Noes bsicas de rede e comunicao

784

Registro do Sistema de Nome de Domnios (DNS)

Adobe AIR 2.0 e posterior Voc pode consultar os registros do recurso de DNS atravs da classe DNSResolver. Os registros do recurso de DNS geram informaes como o endereo IP de um nome de domnio e o nome de domnio de um endereo IP. Voc pode consultar os seguintes tipos de registros do recurso de DNS:

ARecordendereo IPv4 de um host. AAAARecordendereo IPv6 de um host. MXRecordregistro de troca de email de um host. PTRRecordnome de host de um endereo IP. SRVRecordregistro de um servio.
Para consultar um registro, transmita uma sequncia de caracteres de consulta e o objeto de classe que representa o tipo de registro ao mtodo lookup() do objeto DNSResolver. A sequncia de caracteres de consulta a ser usada depende do tipo de registro:
Classe de registro Sequncia de caracteres de consulta Exemplo de sequncia de caracteres example.com example.com example.com 208.77.188.166 _sip._tcp.example.com

ARecord AAAARecord MXRecord PTRRecord SRVRecord

nome do host nome do host nome do host Endereo IP Identificador de servio: _service._protocol.host

O seguinte exemplo de cdigo consulta o endereo IP do host example.com.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Noes bsicas de rede e comunicao

785

package { import import import import import

flash.display.Sprite; flash.events.DNSResolverEvent; flash.events.ErrorEvent; flash.net.dns.ARecord; flash.net.dns.DNSResolver;

public class DNSResolverExample extends Sprite { public function DNSResolverExample() { var resolver:DNSResolver = new DNSResolver(); resolver.addEventListener( DNSResolverEvent.LOOKUP, lookupComplete ); resolver.addEventListener( ErrorEvent.ERROR, lookupError ); resolver.lookup( "example.com.", ARecord ); } private function lookupComplete( event:DNSResolverEvent ):void { trace( "Query string: " + event.host ); trace( "Record count: " + event.resourceRecords.length ); for each( var record:* in event.resourceRecords ) { if( record is ARecord ) trace( record.address ); } } private function lookupError( error:ErrorEvent ):void { trace("Error: " + error.text ); } } }

Para obter mais informaes, consulte:

DNSResolver DNSResolverEvent ARecord AAAARecord MXRecord PTRRecord SRVRecord

ltima atualizao em 29/3/2011

786

Captulo 41: Soquetes

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Um soquete um tipo de conexo de rede estabelecida entre dois processos de computador. Geralmente, os processos so executados em dois computadores diferentes, conectados na mesma rede de Protocolo de Internet (IP). No entanto, os processos conectados podem ser executados no mesmo computador, utilizando o endereo IP especial local host. O Adobe Flash Player oferece suporte a soquetes de Protocolo de Controle de Transporte (TCP) do lado do cliente. Um aplicativo Flash Player pode conectar a outro processo, atuando como servidor de soquete, mas no pode aceitar solicitaes de conexes de entrada de outros processos. Em outras palavras, um aplicativo Flash Player pode se conectar a um servidor TCP, mas no pode agir como um. A API do Flash Player tambm inclui a classe XMLSocket. A classe XMLSocket utiliza um protocolo especfico do Flash Player que permite a troca de mensagens XML com um servidor compatvel com o protocolo. A classe XMLSocket foi introduzida no ActionScript 1 e ainda possui suporte para fornecer compatibilidade com a verso anterior. No geral, a classe Socket pode ser utilizada para aplicativos novos, a no ser que voc esteja estabelecendo uma conexo com um servidor especificamente criado para comunicar-se com Flash XMLSockets. O Adobe AIR adiciona diversas classes para programao de rede com base em soquetes. Aplicativos AIR podem agir como servidor de soquete TCP com a classe ServerSocket e podem conectar-se a servidores de soquete que requerem segurana SSL ou TLS com a classe SecureSocket. Os aplicativos AIR tambm podem enviar e receber mensagens de Protocolo de Datagrama Universal (UDP) com a classe DatagramSocket.

Mais tpicos da Ajuda

pacote flash.net Conexo a soquetes na pgina 1055

Soquetes TCP
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O protocolo de controle de transmisso (TCP) fornece uma maneira de trocar mensagens em uma conexo de rede permanente. O TCP garante que as mensagens enviadas cheguem na ordem correta (salvo quando ocorrem problemas de rede). As conexes TCP requerem um cliente em um servidor. O Flash Player pode criar soquetes de cliente. O Adobe AIR pode, alm disso, criar soquetes de servidor. As APIs de ActionScript a seguir fornecem conexes TCP:

Soquete permite que um aplicativo de cliente conecte ao servidor. A classe Socket no pode monitorar conexes
de entrada.

SecureSocket (AIR) permite que o aplicativo do cliente conecte-se a um servidor confivel e inicie a comunicao
criptografada.

ServerSocket (AIR) permite que um aplicativo monitore conexes de entrada e atue como servidor. XMLSocket permite que um aplicativo de cliente conecte-se a um servidor XMLSocket.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Soquetes

787

Soquetes binrios de cliente

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Uma conexo de soquete binrio semelhante a um soquete XML, exceto que o cliente e o servidor no ficam limitados troca de mensagens XML. Em vez disso, a conexo pode transferir dados como informaes binrias. Assim, voc pode se conectar a uma gama maior de servios, incluindo servidores de email (POP3, SMTP e IMAP) e novos servidores (NNTP).

classe Socket
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe Socket permite que voc faa conexes de soquete e leia e grave dados binrios brutos. A classe Socket til para interoperar com servidores que usam protocolos binrios. Usando conexes de soquete binrio, voc pode gravar cdigo que interage com vrios protocolos de Internet diferentes, como POP3, SMTP, IMAP e NNTP. Essa interao, por sua vez, permite que seus aplicativos se conectem a servidores de email e de notcias. O Flash Player pode fazer interface com um servidor usando o protocolo binrio desse servidor diretamente. Alguns servidores usam a ordem de bytes big-endian, e outros utilizam a ordem de bytes little-endian. A maioria dos servidores na Internet usa a ordem de bytes big-endian porque a ordem de bytes da rede big-endian. A ordem de bytes little-endian popular porque a usada pela arquitetura Intel x86. Voc deve usar a ordem de bytes endian compatvel com a ordem de bytes do servidor que est enviando ou recebendo dados. Todas as operaes executadas pelas interfaces IDataInput e IDataOutput, e as classes que implementam essas interfaces (ByteArray, Socket e URLStream), por padro, so codificadas no formato big-endian, isto , com o byte mais significativo primeiro. Esta ordem padro de bytes foi escolhida para corresponder ordem de bytes de rede oficial e do Java. Para alterar se a ordem de bytes big-endian ou a little-endian usada, voc pode definir a propriedade endian como Endian.BIG_ENDIAN ou Endian.LITTLE_ENDIAN. A classe Socket herda todos os mtodos definidos pelas interfaces IDataInput e IDataOutput (localizadas no pacote flash.utils). Esses mtodos devem ser usados para gravar no Socket e ler a partir do Socket. Para obter mais informaes, consulte:

Socket IDataInput
IDataOutput

evento socketData

Soquetes de cliente seguros (AIR)

Adobe AIR 2 e posterior Voc pode usar a classe SecureSocket para conexo a servidores de soquete que usam o Secure Sockets Layer verso 4 (SSLv4) ou o Transport Layer Security verso 1 (TLSv1). Um soquete seguro oferece trs benefcios: autenticao do servidor, integridade de dados e sigilo da mensagem. O tempo de execuo do autentica um servidor usando o certificado do servidor e seu relacionamento com os certificados raiz ou intermedirios da autoridade de certificao no repositrio confivel do usurio. O tempo de execuo utiliza os algoritmos de criptografia usados pelas implementaes de protocolo SSL e TLS para proporcionar integridade de dados e confidencialidade das mensagens. Quando voc se conecta a um servidor atravs do objeto SecureSocket, o tempo de execuo verifica o certificado do servidor utilizando o repositrio confivel de certificados. No Windows e Mac, o sistema operacional fornece o armazenamento de confiana. No Linux, o tempo de execuo do fornece seu prprio repositrio confivel.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Soquetes

788

Se o certificado do servidor no for vlido nem confivel, o tempo de execuo gerar um evento ioError. Voc pode verificar a propriedade serverCertificateStatus do objeto SecureSocket para saber por que a verificao falhou. No h nenhuma previso para comunicao com um servidor que no possua um certificado vlido e confivel. A classe CertificateStatus define as constantes alfanumricas que representam os possveis resultados da verificao:

Vencidoa data de vencimento do certificado j passou. Invlidoh vrios motivos pelos quais um certificado pode no ser vlido. Por exemplo, o certificado pode ter
sido alterado, corrompido, ou pode ser do tipo incorreto.

Cadeia invlidaum ou mais certificados na cadeia de certificados do servidor no so vlidos. Discrepncia principalo nome de host do servidor e o nome comum do certificado no coincidem. Em outras
palavras, o servidor est usando o certificado incorreto.

Revogadoa autoridade de certificao emissora revogou o certificado. Confivelo certificado vlido e confivel. Um objeto SecureSocket pode se conectar apenas a um servidor que
utilize um certificado vlido e confivel.

Desconhecidoo objeto SecureSocket ainda no verificou o certificado. A propriedade

serverCertificateStatus tem este valor de status antes que voc chame connect() e antes que um evento connect ou ioError seja gerado.

Signatrios no confiveiso certificado no gera uma cadeia com um certificado raiz confivel no repositrio
confivel do computador cliente. A comunicao com um objeto SecureSocket exige que o servidor use um protocolo seguro e tenha um certificado vlido e confivel. Em outros aspectos, usar o objeto SecureSocket igual a usar um objeto Socket. O objeto SecureSocket no pode ser usado em todas as plataformas. Use a propriedade isSupported da classe SecureSocket para testar se o tempo de execuo permite o uso do objeto SecureSocket no computador cliente atual. Para obter mais informaes, consulte:

SecureSocket CertificateStatus IDataInput

IDataOutput

evento socketData

Exemplo de soquete TCP: construo de um cliente Telnet

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O exemplo de Telnet demonstra tcnicas de conexo com um servidor remoto e transmisso de dados usando a classe Socket. O exemplo demonstra as seguintes tcnicas:

Criao de um cliente Telnet personalizado usando a classe Socket Envio de texto ao servidor remoto usando um objeto ByteArray Tratamento de dados recebidos de um servidor remoto
Para obter os arquivos do aplicativo deste exemplo, consulte www.adobe.com/go/learn_programmingAS3samples_flash_br. Os arquivos do aplicativo Telnet podem ser encontrados na pasta Amostras/Telnet. O aplicativo consiste nos seguintes arquivos:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Soquetes

789

Arquivo TelnetSocket.fla ou TelnetSocket.mxml TelnetSocket.as com/example/programmingas3/Telnet/Telnet.as

Descrio O arquivo principal do aplicativo formado pela interface de usurio para Flex (MXML) ou Flash (FLA).

Classe Document que fornece a lgica da interface de usurio (somente no Flash). Fornece a funcionalidade de cliente Telnet para o aplicativo, como conectar-se a um servidor remoto e enviar, receber e exibir dados.

Viso geral do aplicativo de soquete Telnet Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O arquivo TelnetSocket.mxml principal responsvel por criar a interface do usurio (UI) para o aplicativo inteiro. Alm da UI, esse arquivo tambm define dois mtodos, login() e sendCommand(), para conectar o usurio ao servidor especificado. O cdigo a seguir lista o ActionScript no arquivo principal do aplicativo:
import com.example.programmingas3.socket.Telnet; private var telnetClient:Telnet; private function connect():void { telnetClient = new Telnet(serverName.text, int(portNumber.text), output); console.title = "Connecting to " + serverName.text + ":" + portNumber.text; console.enabled = true; } private function sendCommand():void { var ba:ByteArray = new ByteArray(); ba.writeMultiByte(command.text + "\n", "UTF-8"); telnetClient.writeBytesToSocket(ba); command.text = ""; }

A primeira linha de cdigo importa a classe Telnet do pacote com.example.programmingas.socket personalizado. A segunda linha de cdigo declara uma instncia da classe Telnet, telnetClient, que inicializada posteriormente pelo mtodo connect(). Em seguida, o mtodo connect() declarado e inicializa a varivel telnetClient declarada anteriormente. Esse mtodo transmite o nome do servidor telnet especificado pelo usurio, a porta do servidor telnet e uma referncia a um componente TextArea na lista de exibio que usada para exibir as respostas de texto do servidor de soquete. As duas linhas finais do mtodo connect() definem a propriedade title do Painel e ativam o componente Painel, o que permite que o usurio envie dados ao servidor remoto. O mtodo final no arquivo principal do aplicativo, sendCommand(), usado para enviar os comandos do usurio ao servidor remoto como um objeto ByteArray. Viso geral da classe Telnet Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe Telnet responsvel por conectar-se ao servidor Telnet remoto e enviar/receber dados. A classe Telnet declara as seguintes variveis particulares:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Soquetes

790

private private private private private

var var var var var

serverURL:String; portNumber:int; socket:Socket; ta:TextArea; state:int = 0;

A primeira varivel, serverURL, contm o endereo do servidor especificado pelo usurio ao qual conectar-se. A segunda varivel, portNumber, o nmero da porta na qual o servidor Telnet est em execuo atualmente. Por padro, o servio Telnet executado na porta 23. A terceira varivel, socket, uma instncia de Socket que tentar conectar-se ao servidor definido pelas variveis serverURL e portNumber. A quarta varivel, ta, uma referncia a uma ocorrncia do componente TextArea no Palco. Esse componente usado para exibir respostas do servidor Telnet remoto ou qualquer mensagem de erro possvel. A varivel final, state, um valor numrico usado para determinar quais opes so suportadas pelo cliente Telnet. Conforme visto anteriormente, a funo do construtor da classe Telnet chamada pelo mtodo connect() no arquivo principal do aplicativo. O construtor Telnet utiliza trs parmetros: server, port e output. Os parmetros server e port especificam o nome do servidor e o nmero da porta em que o servidor Telnet est executando. O parmetro final, output, uma referncia a uma instncia do componente TextArea no Palco onde a sada do servidor exibida aos usurios.
public function Telnet(server:String, port:int, output:TextArea) { serverURL = server; portNumber = port; ta = output; socket = new Socket(); socket.addEventListener(Event.CONNECT, connectHandler); socket.addEventListener(Event.CLOSE, closeHandler); socket.addEventListener(ErrorEvent.ERROR, errorHandler); socket.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler); socket.addEventListener(ProgressEvent.SOCKET_DATA, dataHandler); Security.loadPolicyFile("http://" + serverURL + "/crossdomain.xml"); try { msg("Trying to connect to " + serverURL + ":" + portNumber + "\n"); socket.connect(serverURL, portNumber); } catch (error:Error) { msg(error.message + "\n"); socket.close(); } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Soquetes

791

Gravao de dados em um soquete Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para gravar dados em uma conexo de soquete, voc pode chamar qualquer um dos mtodos de gravao da classe Socket. Entre esses mtodos de gravao esto os seguintes: writeBoolean(), writeByte(), writeBytes(), writeDouble() e outros. Ento, esvazie os dados do buffer de sada usando o mtodo flush(). No servidor Telnet, os dados so gravados na conexo de soquete usando o mtodo writeBytes() que utiliza a matriz de bytes como um parmetro e envia-a ao buffer de sada. O mtodo writeBytesToSocket() o seguinte:
public function writeBytesToSocket(ba:ByteArray):void { socket.writeBytes(ba); socket.flush(); }

Esse mtodo chamado pelo mtodo sendCommand() do arquivo principal do aplicativo. Exibio de mensagens do servidor de soquete Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Sempre que uma mensagem recebida do servidor de soquete, ou ocorre um evento, o mtodo msg() personalizado chamado. Esse mtodo anexa uma sequncia de caracteres ao TextArea no Palco e chama um mtodo setScroll() personalizado, o que faz com que o componente TextArea role para a parte inferior. O mtodo msg() o seguinte:
private function msg(value:String):void { ta.text += value; setScroll(); }

Se voc no rolou automaticamente o contedo do componente TextArea, os usurios precisaro arrastar manualmente as barras de rolagem na rea de texto para ver a resposta mais recente do servidor. Rolagem de um componente TextArea Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O mtodo setScroll() contm uma nica linha do ActionScript que rola o contedo do componente TextArea verticalmente de forma que o usurio possa ver a ltima linha do texto retornado. O seguinte snippet mostra o mtodo setScroll():
public function setScroll():void { ta.verticalScrollPosition = ta.maxVerticalScrollPosition; }

Esse mtodo define a propriedade verticalScrollPosition, que o nmero da linha superior de caracteres exibida atualmente, e define-a como o valor da propriedade maxVerticalScrollPosition.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Soquetes

792

Soquetes XML
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Um soquete XML permite que voc crie uma conexo com um servidor remoto que permanece aberta at que ela seja expressamente fechada. Voc pode trocar dados de string como, por exemplo, XML entre o servidor e o cliente. Um dos benefcios de utilizar um servidor de soquete XML que o cliente no precisa solicitar dados expressamente. O servidor pode enviar dados sem aguardar por uma solicitao e enviar dados para cada cliente conectado. No Flash Player e em contedo Adobe AIR fora da rea de segurana, as conexes XML requerem a presena de um arquivo de poltica de soquete no servidor destino. Para obter mais informaes, consulte Controles de site (arquivos de poltica) na pgina 1037 eConexo a soquetes na pgina 1055. A classe XMLSocket no pode encapsular em firewalls automaticamente porque, ao contrrio do protocolo RTMP (Real-Time Messaging Protocol), ela no tem recurso de encapsulamento HTTP. Se voc precisar usar o encapsulamento HTTP, considere o uso do Flash Remoting ou do Flash Media Server (que oferece suporte a RTMP). As restries a seguir aplicam-se a como e onde o contedo do Flash Player ou de um aplicativo AIR fora da rea de segurana do aplicativo pode utilizar um objeto XMLSocket para conectar-se ao servidor:

No caso de contedo fora da caixa de proteo de segurana do aplicativo, o mtodo XMLSocket.connect() s

pode se conectar a nmeros de porta TCP maiores ou iguais a 1024. Uma conseqncia dessa restrio que os daemons de servidor que se comunicam com o objeto XMLSocket tambm devem ser atribudos a nmeros de porta maiores ou iguais a 1024. Os nmeros de porta menores que 1024 normalmente so usados por servios do sistema, como FTP (21), Telnet (23), SMTP (25), HTTP (80) e POP3 (110). Portanto, os objetos XMLSocket so barrados nessas portas por motivos de segurana. A restrio de nmero de porta limita a possibilidade de esses recursos serem indevidamente acessados e mal utilizados.

No caso de contedo fora da caixa de proteo de segurana do aplicativo, o mtodo XMLSocket.connect() s

pode se conectar a computadores do mesmo domnio onde reside o contedo. (Esta restrio idntica s regras de segurana para URLLoader.load().) Para se conectar a um daemon de servidor executado em um domnio que no seja o domnio em que reside o contedo, voc pode criar um arquivo de polticas entre domnios no servidor que permita acesso de domnios especficos. Para obter detalhes sobre arquivos de polticas entre domnios, consulte Segurana do AIR na pgina 1063. Nota: Pode ser desafiador configurar um servidor para comunicar-se com o objeto XMLSocket. Se o seu aplicativo no exigir interatividade em tempo real, use a classe URLLoader em vez da classe XMLSocket. Voc pode usar os mtodos XMLSocket.connect() e XMLSocket.send() da classe XMLSocket para transferir XML para e de um servidor via conexo de soquete. O mtodo XMLSocket.connect() estabelece uma conexo de soquete com uma porta de servidor Web. O mtodo XMLSocket.send() analisa um objeto XML para o servidor especificado na conexo de soquete. Ao chamar o mtodo XMLSocket.connect(), o aplicativo abre uma conexo TCP/IP com o servidor de mantm a conexo aberta at que uma das condies a seguir ocorra:

O mtodo XMLSocket.close() da classe XMLSocket chamado. No h mais referncias ao objeto XMLSocket. O Flash Player encerrado. A conexo perdida (por exemplo, o modem se desconecta).

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Soquetes

793

Conexo a um servidor com a classe XMLSocket

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para criar uma conexo de soquete, necessrio criar uma aplicativo server side Flash Player ou AIR para aguardar pela solicitao de conexo do soquete e enviar a resposta para o aplicativo Flash Player ou AIR. Este tipo de aplicativo server side pode ser escrito em AIR ou em outra linguagem de programao como, por exemplo Java, Python ou Perl. Para utilizar a classe XMLSocket, o serviddor deve executar uma daemon que entenda o protocolo simples utilizado pela classe XMLSocket:

Mensagens XML so enviadas por meio de uma conexo de soquete de fluxo TCP/IP full-duplex. Cada mensagem XML um documento XML completo, terminado por um byte zero (0). Um nmero ilimitado de mensagens XML pode ser enviado e recebido por meio de uma nica conexo
XMLSocket. Criao e conexo a um servidor de soquete XML Java Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O cdigo a seguir demonstra um servidor XMLSocket simples criado em Java que aceita conexes de entrada e exibe as mensagens recebidas na janela do prompt de comando. Por padro, um novo servidor criado na porta 8080 da mquina local, embora voc possa especificar um nmero de porta diferente quando iniciar o servidor a partir da linha de comando. Crie um novo documento de texto e adicione o seguinte cdigo:
import java.io.*; import java.net.*; class SimpleServer { private static SimpleServer server; ServerSocket socket; Socket incoming; BufferedReader readerIn; PrintStream printOut; public static void main(String[] args) { int port = 8080; try { port = Integer.parseInt(args[0]); } catch (ArrayIndexOutOfBoundsException e) { // Catch exception and keep going. } server = new SimpleServer(port); } private SimpleServer(int port) { System.out.println(">> Starting SimpleServer");

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Soquetes

794

try { socket = new ServerSocket(port); incoming = socket.accept(); readerIn = new BufferedReader(new InputStreamReader(incoming.getInputStream())); printOut = new PrintStream(incoming.getOutputStream()); printOut.println("Enter EXIT to exit.\r"); out("Enter EXIT to exit.\r"); boolean done = false; while (!done) { String str = readerIn.readLine(); if (str == null) { done = true; } else { out("Echo: " + str + "\r"); if(str.trim().equals("EXIT")) { done = true; } } incoming.close(); } } catch (Exception e) { System.out.println(e); } } private void out(String str) { printOut.println(str); System.out.println(str); } }

Salve o documento no disco rgido como SimpleServer.java e o compile usando um compilador Java, que cria um arquivo de classe Java chamado SimpleServer.class. Voc pode iniciar o servidor XMLSocket abrindo um prompt de comando e digitando java SimpleServer. O arquivo SimpleServer.class pode ser colocado em qualquer lugar do computador local ou da rede; no necessrio coloc-lo no diretrio raiz do servidor Web. Se voc no puder iniciar o servidor porque os arquivos no esto localizados dentro do caminho de classe Java, tente iniciar o servidor com java -classpath. SimpleServer. Para se conectar ao XMLSocket do aplicativo , necessrio criar uma nova ocorrncia da classe XMLSocket, e chamar o mtodo XMLSocket.connect() ao transmitir um nome do host e um nmero de porta, da seguinte maneira:
var xmlsock:XMLSocket = new XMLSocket(); xmlsock.connect("127.0.0.1", 8080);

Sempre que voc receber dados do servidor, o evento data (flash.events.DataEvent.DATA) despachado:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Soquetes

795

xmlsock.addEventListener(DataEvent.DATA, onData); private function onData(event:DataEvent):void { trace("[" + event.type + "] " + event.data); }

Para enviar dados ao servidor XMLSocket, use o mtodo XMLSocket.send() e transmita um objeto ou string XML. O Flash Player converte o parmetro fornecido em um objeto String e envia o contedo ao servidor XMLSocket seguido de um byte zero (0):
xmlsock.send(xmlFormattedData);

O mtodo XMLSocket.send() no retorna um valor que indica se os dados foram transmitidos com xito. Se houve um erro durante a tentativa de enviar dados, gerado um erro IOError. Cada mensagem enviada ao servidor de soquete XML deve ser terminada por uma nova linha (caractere \n). Para obter mais informaes, consulte XMLSocket.

Soquetes de servidor
Adobe AIR 2 e posterior Use a classe ServerSocket para permitir que outros processos se conectem ao seu aplicativo usando um soquete do Protocolo de Controle de Transporte (TCP). O processo em conexo pode estar sendo executado no computador local ou em outro computador conectado rede. Quando um objeto ServerSocket recebe uma solicitao de conexo, ele gera um evento connect. O objeto ServerSocketConnectEvent gerado com o evento contm um objeto Socket. Voc pode usar esse objeto Socket em comunicaes subsequentes com o outro processo. Para ouvir conexes de soquete recebidas:
1 Crie um objeto ServerSocket e vincule-o a uma porta local 2 Inclua ouvintes de eventos para o evento connect 3 Chame o mtodo listen(). 4 Responda ao evento connect, que fornece um objeto Socket para cada conexo recebida

O objeto ServerSocket continua a escutar novas conexes at que voc chame o mtodo close(). O exemplo de cdigo a seguir ilustra como criar um aplicativo de servidor de soquete. O exemplo ouve conexes que chegam porta 8087. Quando uma conexo for recebida, o exemplo envia uma mensagem (a sequncia de caracteres Conectado) para o soquete do cliente. Da em diante, o servidor "rebate" todas as mensagens para o cliente.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Soquetes

796

package { import import import import import import import

flash.display.Sprite; flash.events.Event; flash.events.IOErrorEvent; flash.events.ProgressEvent; flash.events.ServerSocketConnectEvent; flash.net.ServerSocket; flash.net.Socket;

public class ServerSocketExample extends Sprite { private var serverSocket:ServerSocket; private var clientSockets:Array = new Array(); public function ServerSocketExample() { try { // Create the server socket serverSocket = new ServerSocket(); // Add the event listener serverSocket.addEventListener( Event.CONNECT, connectHandler ); serverSocket.addEventListener( Event.CLOSE, onClose ); // Bind to local port 8087 serverSocket.bind( 8087, "127.0.0.1" ); // Listen for connections serverSocket.listen(); trace( "Listening on " + serverSocket.localPort ); } catch(e:SecurityError) { trace(e); } } public function connectHandler(event:ServerSocketConnectEvent):void { //The socket is provided by the event object var socket:Socket = event.socket as Socket; clientSockets.push( socket ); socket.addEventListener( ProgressEvent.SOCKET_DATA, socketDataHandler); socket.addEventListener( Event.CLOSE, onClientClose ); socket.addEventListener( IOErrorEvent.IO_ERROR, onIOError ); //Send a connect message socket.writeUTFBytes("Connected."); socket.flush(); trace( "Sending connect message" ); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Soquetes

797

public function socketDataHandler(event:ProgressEvent):void { var socket:Socket = event.target as Socket //Read the message from the socket var message:String = socket.readUTFBytes( socket.bytesAvailable ); trace( "Received: " + message); // Echo the received message back to the sender message = "Echo -- " + message; socket.writeUTFBytes( message ); socket.flush(); trace( "Sending: " + message ); } private function onClientClose( event:Event ):void { trace( "Connection to client closed." ); //Should also remove from clientSockets array... } private function onIOError( errorEvent:IOErrorEvent ):void { trace( "IOError: " + errorEvent.text ); } private function onClose( event:Event ):void { trace( "Server socket closed by OS." ); } }}

Para obter mais informaes, consulte:

ServerSocket ServerSocketConnectEvent Socket

Soquetes UDP (AIR)

Adobe AIR 2 e posterior O Protocolo Universal de Datagramas (UDP) uma forma de troca de mensagens atravs de uma conexo de rede sem estado (stateless). O UDP no garante que as mensagens sero entregues na ordem nem que elas sero realmente entregues. Com o UDP, o cdigo de rede do sistema operacional normalmente gasta menos tempo organizando, rastreando e confirmando as mensagens. Portanto, as mensagens de UDP normalmente chegam ao aplicativo de destino com um atraso menor do que as mensagens de TCP. A comunicao por soquete do UDP til quando existe a necessidade de enviar informaes em tempo real, tais como atualizaes de posies em um jogo ou pacotes de som em um aplicativo de bate-papo por voz. Nesses aplicativos, aceitvel alguma perda de dados, e uma baixa latncia de transmisso mais importante que a garantia de chegada. Para praticamente todas as outras finalidades, os soquetes TCP so uma opo mais adequada.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Soquetes

798

Seu aplicativo AIR pode enviar e receber mensagens UDP com as classes DatagramSocket e DatagramSocketDataEvent. Para enviar ou receber uma mensagem UDP:
1 Crie um objeto DatagramSocket 2 Adicione um evento ouvinte para o evento data 3 Vincule o soquete a um endereo IP e a uma porta local atravs do mtodo bind() 4 Envie mensagens chamando o mtodo send(), transmitindo o endereo IP e a porta do computador de destino 5 Receba as mensagens respondendo ao evento data. O objeto DatagramSocketDataEvent gerado para este evento

contm um objeto ByteArray que contm os dados de mensagem. O exemplo de cdigo a seguir ilustra como um aplicativo pode enviar e receber mensagens UDP. O exemplo envia uma nica mensagem contendo a sequncia de caracteres, Ol. ao computador de destino. Ele tambm rastreia o contedo de todas as mensagens recebidas.
package { import flash.display.Sprite; import flash.events.DatagramSocketDataEvent; import flash.events.Event; import flash.net.DatagramSocket; import flash.utils.ByteArray; public class DatagramSocketExample extends Sprite { private var datagramSocket:DatagramSocket; //The IP and port for this computer private var localIP:String = "192.168.0.1"; private var localPort:int = 55555; //The IP and port for the target computer private var targetIP:String = "192.168.0.2"; private var targetPort:int = 55555; public function DatagramSocketExample() { //Create the socket datagramSocket = new DatagramSocket(); datagramSocket.addEventListener( DatagramSocketDataEvent.DATA, dataReceived ); //Bind the socket to the local network interface and port

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Soquetes

799

datagramSocket.bind( localPort, localIP ); //Listen for incoming datagrams datagramSocket.receive(); //Create a message in a ByteArray var data:ByteArray = new ByteArray(); data.writeUTFBytes("Hello."); //Send the datagram message datagramSocket.send( data, 0, 0, targetIP, targetPort); } private function dataReceived( event:DatagramSocketDataEvent ):void { //Read the data from the datagram trace("Received from " + event.srcAddress + ":" + event.srcPort + "> " + event.data.readUTFBytes( event.data.bytesAvailable ) ); } }}

No se esquea dos seguintes aspectos quando usar soquetes UDP:

Um nico pacote de dados no pode ser maior que a menor unidade mxima de transmisso (MTU) da interface
de rede nem que qualquer n de rede entre o remetente e o destinatrio. Todos os dados do objeto ByteArray transmitidos ao mtodo send() so enviados como um nico pacote. (No TCP, mensagens grandes so subdivididas em pacotes separados).

No h negociao entre o remetente e o destino. As mensagens so descartadas sem erro se o destino no existir
ou se no tiver um ouvinte ativo na porta especificada.

Quando voc usar o mtodo connect(), as mensagens enviadas de outras fontes sero ignoradas. Uma conexo
UDP oferece apenas uma filtragem prtica de pacotes. Isso no significa que existe um processo de escuta necessariamente vlido no endereo e na porta de destino.

O trfego de UDP pode afogar uma rede. Os administradores de rede podem precisar implementar controles de
qualidade de servio caso ocorra um congestionamento de rede. (O TCP tem um controle de trfego prprio para reduzir o impacto do congestionamento de rede). Para obter mais informaes, consulte:

DatagramSocket DatagramSocketDataEvent ByteArray

Endereos IPv6
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O Flash Player 9.0.115.0 e suas verses posteriores oferecem suporte a IPv6 (Internet Protocol verso 6). O IPv6 uma verso do Internet Protocol que oferece suporte a endereos de 128 bits (um aprimoramento do protocolo IPv4 anterior, que oferece suporte a endereos de 32 bits). Talvez seja necessrio ativar o IPv6 nas suas interfaces de rede. Para obter mais informaes, consulte a Ajuda do sistema operacional que est hospedando os dados.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Soquetes

800

Se o IPv6 for suportado no sistema de host, ser possvel especificar endereos literais IPv6 numricos em URLs, contidos entre parnteses ([]), como apresentado seguir:
[2001:db8:ccc3:ffff:0:444d:555e:666f]

O Flash Player retorna valores IPv6 literais, de acordo com as regras a seguir:

O Flash Player retorna o formato longo da string para endereos IPv6. O valor de IP no possui abreviaes com dois pontos. Os dgitos hexadecimais so expressos apenas em letras minsculas. Os endereos IPv6 so apresentados entre parnteses ([]). Cada quarteto de endereo transformado em dgitos hexadecimais de 0 a 4, com os zeros esquerda omitidos. Um quarteto de endereo composto por zeros transformado em um nico zero (e no em dois-pontos duplos),
exceto se mencionado na lista de excees a seguir. Os valores IPv6 retornados pelo Flash Player tm as seguintes excees:

Um endereo IPv6 no especificado (somente zeros) transformado em [::]. O endereo IPv6 de retorno ou de host local transformado em [::1]. Os endereos IPv4 mapeados (convertido para IPv6) so transformados em [::ffff:a.b.c.d], em que a.b.c.d
corresponde a um tpico valor decimal IPv4 separado por pontos.

Os endereos IPv4 compatveis so transformados em [::a.b.c.d], em que a.b.c.d corresponde a um tpico valor
decimal IPv4 separado por pontos.

ltima atualizao em 29/3/2011

801

Captulo 42: Comunicao HTTP

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os aplicativos Adobe AIR e Adobe Flash Player podem ser comunicar com servidores HTTP para carregar dados, imagens, vdeo e trocar mensagens.

Mais tpicos da Ajuda

flash.net.URLLoader flash.net.URLStream flash.net.URLRequest flash.net.URLRequestDefaults flash.net.URLRequestHeader flash.net.URLRequestMethod flash.net.URLVariables

Carregamento de dados externos

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O ActionScript 3.0 inclui mecanismos para carregamento de dados de fontes externas. As origens podem fornecer contedo esttico, como arquivos de texto, ou contedo dinmico, como o contedo gerado por um script da Web. Os dados podem ser formatados de diversas maneiras, e o ActionScript oferece a funcionalidade para decodific-los e acess-los. Voc tambm pode enviar dados para o servidor externo como parte do processo de recuperao de dados.

Uso da classe URLRequest

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Muitas APIs que carregam dados externos utilizam a classe URLRequest para definir as propriedades da solicitao de rede necessria.

Propriedades de URLRequest
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc pode definir as propriedades a seguir de uma objeto URLRequest em qualquer rea de segurana:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao HTTP

802

Propriedade contentType

Descrio O tipo de contedo MIME de qualquer dado enviado com a solicitao de URL. Se nenhum valor definido para contentType, os valores sero enviados como application/x-www-form-urlencoded. Um objeto contendo dados a serem transmitidos com a solicitao de URL. Uma string que identifica de forma exclusiva o componente da plataforma Adobe assinado a ser armazenado (ou recuperado) no cache do Adobe Flash Player. O mtodo de solicitao HTTP, como uma operao GET ou POST. (O contedo em execuo no domnio de segurana do aplicativo AIR pode especificar strings diferentes de "GET" ou "POST" como a propriedade method. permitido qualquer verbo HTTP, e "GET" o mtodo padro. Consulte Segurana do AIR na pgina 1063.) A matriz de cabealhos de solicitao HTTP a ser acrescentada solicitao HTTP. Observe que as permisses para definir alguns cabealhos so restritas no Flash Player, assim como no contedo do AIR executado fora da rea de segurana do aplicativo. Especifica a URL a ser solicitada.

data digest

method

requestHeaders

url

No AIR, voc pode definir propriedades adicionais da classe URLRequest, disponveis somente no contedo AIR, executado na rea de segurana do aplicativo. O contedo na caixa de proteo do aplicativo tambm pode definir URLs usando novos esquemas de URL (alm de esquemas padro, como file e http).
Propriedade followRedirects Descrio Especifica se os redirecionamentos devem ser seguidos (true, o valor padro) ou no (false). Isso s recebe suporte na caixa de proteo do aplicativo AIR. Especifica se a pilha de protocolo HTTP deve gerenciar cookies (true, o valor padro) ou no (false) desta solicitao. Definir essa propriedade s recebe suporte na caixa de proteo do aplicativo AIR. Especifica se as solicitaes de autenticao relativas a esta solicitao devem ser manipuladas (true). Definir essa propriedade s recebe suporte na caixa de proteo do aplicativo AIR. O padro autenticar as solicitaes, o que pode fazer com que seja exibida uma caixa de dilogo de autenticao se o servidor exigir as credenciais. Voc tambm pode definir o nome de usurio e a senha utilizando a classe URLRequestDefaults consulte Definir os padres de URLRequest (somente AIR) na pgina 802. Especifica se os dados de resposta devem ser armazenados em cache para esta solicitao. Definir essa propriedade s recebe suporte na caixa de proteo do aplicativo AIR. O padro armazenar a resposta em cache (true). Especifica se o cache local deve ser consultado antes que URLRequest saia em busca dos dados. Definir essa propriedade s recebe suporte na caixa de proteo do aplicativo AIR. O padro (true) usar a verso armazenada no cache local, se disponvel. Especifica a string user-agent a ser usada na solicitao HTTP.

manageCookies

authenticate

cacheResponse

useCache

userAgent

Nota: A classe HTMLLoader tem propriedades relacionadas para configuraes que pertencem ao contedo carregado por um objeto HTMLLoader. Para obter detalhes, consulte Sobre a classe HTMLLoader na pgina 967 .

Definir os padres de URLRequest (somente AIR)

Adobe AIR 1.0 e posterior A classe URLRequestDefaults permite definir configuraes padro especficas do aplicativo para objetos URLRequest. Por exemplo, o cdigo abaixo define os valores padro para as propriedades manageCookies e useCache. Todos os objetos URLRequest novos utilizaro os valores especificados para essas propriedades, em vez dos padres normais:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao HTTP

803

URLRequestDefaults.manageCookies = false; URLRequestDefaults.useCache = false;

Nota: A classe URLRequestDefaults definida para o contedo em execuo apenas no Adobe AIR. No h suporte no Flash Player. A classe URLRequestDefaults inclui um mtodo setLoginCredentialsForHost() que permite especificar um nome de usurio e uma senha padro para uso em um determinado host. O host, definido no parmetro hostname do mtodo, pode ser um domnio, como "www.example.com", ou um domnio e um nmero de porta, como "www.example.com:80". Observe que "example.com", "www.example.com" e "sales.example.com" so todos considerados hosts nicos. Essas credenciais s sero utilizadas se exigidas pelo servidor. Se o usurio j foi autenticado (por exemplo, utilizando a caixa de dilogo de autenticao), a chamada do mtodo setLoginCredentialsForHost() no altera o usurio autenticado. O cdigo a seguir define o usurio padro e a senha utilizada para solicitaes enviadas para www.example.com:
URLRequestDefaults.setLoginCredentialsForHost("www.example.com", "Ada", "love1816$X");

As configuraes de URLRequestDefaults somente se aplicam ao domnio atual do aplicativo, com uma exceo. As credenciais enviadas para o mtodo setLoginCredentialsForHost() so utilizadas para solicitaes feitas em qualquer domnio de aplicativo, dentro do aplicativo AIR. Para obter mais informaes, consulte a classe URLRequestDefaults em Referncia do ActionScript 3.0 para a plataforma Adobe Flash.

Esquemas de URI
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os esquemas padro de URI como os esquemas a seguir, podem ser utilizados em solicitaes feitas a partir de qualquer rea de segurana: http: e https: Utilize-as para URLs padro da Internet (da mesma forma como so utilizadas pelo navegador a Web). arquivo: Use file: para especificar o URL de um arquivo localizado no sistema de arquivos local. Por exemplo:
file:///c:/AIR Test/test.txt

No AIR, tambm possvel utilizar os esquemas a seguir para definir o URL para contedo em execuo na rea de segurana do aplicativo: app: Use app: para especificar um caminho relativo ao diretrio raiz do aplicativo instalado. Por exemplo, o seguinte caminho aponta para um subdiretrio de recursos do diretrio do aplicativo instalado:
app:/resources

Quando o aplicativo AIR executado utilizando o AIR Debug Launcher (ADL), o diretrio do aplicativo o diretrio que contm o arquivo descritor do aplicativo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao HTTP

804

app-storage: Use app-storage: para especificar um caminho relativo ao diretrio de armazenamento de dados do aplicativo. Para cada aplicativo (e usurio) instalado, o AIR cria um diretrio exclusivo de armazenamento do aplicativo, que um local til para armazenar dados especficos desse aplicativo. Por exemplo, o caminho a seguir aponta para o arquivo prefs.xml em um subdiretrio de configuraes do diretrio de armazenamento do aplicativo:
app-storage:/settings/prefs.xml

A localizao do diretrio de armazenamento do aplicativo baseia-se no nome do usurio, na ID do aplicativo e na ID do publicador (se aplicvel):

No Mac OS, em:

/Users/user name/Library/Preferences/applicationID.publisherID/Local Store/

Por exemplo:
/Users/babbage/Library/Preferences/com.example.TestApp.02D88EEED35F84C264A183921344EEA353 A629FD.1/Local Store

No Windows: no diretrio Documents and Settings, em:

user name/Application Data/applicationID.publisherID/Local Store/ Por exemplo:
C:\Documents and Settings\babbage\Application Data\com.example.TestApp.02D88EEED35F84C264A183921344EEA353A629FD.1\Local Store

No Linux - In:
/home/user name/.appdata/applicationID.publisherID/Local Store/

Por exemplo:
/home/babbage/.appdata/com.example.TestApp.02D88EEED35F84C264A183921344EEA353A629FD.1\Loc al Store

Nota: Desde a verso 1.5.3 do AIR, nem todos os aplicativos AIR tm um ID de publicador. A URL (e a propriedade url) de um objeto File criado com File.applicationStorageDirectory usa o esquema de URL app-storage, como no exemplo abaixo:
var dir:File = File.applicationStorageDirectory; dir = dir.resolvePath("preferences"); trace(dir.url); // app-storage:/preferences

mailto: Voc pode usar o esquema mailto em objetos URLRequests enviados para a funo navigateToURL(). Consulte Abertura de um URL em outro aplicativo na pgina 818. Voc pode usar um objeto URLRequest que utiliza qualquer um desses esquemas de URL para definir uma solicitao de diferentes objetos como, por exemplo, um objeto FileStream ou Sound. Tambm possvel usar esses esquemas em um contedo HTML em execuo no AIR; por exemplo, voc pode us-los no atributo src de uma tag img. Porm, voc s pode usar estes esquemas de URI especficos do AIR, (app: e app-storage:) no contedo localizado na rea de segurana do aplicativo. Para obter mais informaes, consulte Segurana do AIR na pgina 1063.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao HTTP

805

Esquemas de URI proibidos (no AIR) Algumas APIs permitem iniciar contedo em um navegador da Web. Por motivos de segurana, alguns esquemas de URL so proibidos quando essas APIs so utilizadas no AIR. A lista de esquemas proibidos depende da caixa de proteo de segurana do cdigo que usa a API. Para obter detalhes, consulte Abertura de um URL em outro aplicativo na pgina 818.

Definio de variveis de URL

Embora seja possvel adicionar variveis diretamente na sequncia de caracteres do URL, pode ser mais fcil utilizar a classe URL Variables para definir quaisquer variveis necessrias para uma solicitao. Existem trs formas em que possvel adicionar parmetros a um objeto URLVariables:

No construtor URLVariables Com o mtodo URLVariables.decode() Como propriedades dinmicas no prprio objeto URLVariables
O exemplo a seguir ilustra todos os trs mtodos e tambm como atribuir variveis ao objeto URLRequest:
var urlVar:URLVariables = new URLVariables( "one=1&two=2" ); urlVar.decode("amp=" + encodeURIComponent( "&" ) ); urlVar.three = 3; urlVar.amp2 = "&&"; trace(urlVar.toString()); //amp=%26&amp2=%26%26&one=1&two=2&three=3 var urlRequest:URLRequest = new URLRequest( "http://www.example.com/test.cfm" ); urlRequest.data = urlVar;

Ao definir variveis no construtor URLVariables ou no mtodo URLVariables.decode(), certifique-se de que os caracteres que possuem um significado especial em uma sequncia de caracteres de URI sejam codificados em formato URL. Por exemplo, ao utilizar o & (e comercial) em um nome de parmetro ou valor, necessrio codificar o &, alterando-o de & para %26, porque o & atua como um delimitador de parmetros. A funo de nvel superior encodeURIComponent() pode ser utilizada para isso.

Uso da classe URLLoader

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe URLLoader permite enviar uma solicitao ao servidor e acessar as informaes retornadas. Voc tambm pode utilizar a classe URLLoader para acessar arquivos no sistema de arquivos local, onde o acesso de arquivos permitido (por exemplo, na rea de segurana local do Flash Player e do aplicativo AIR). A classe URLLoader baixa dados de um URL como texto, dados binrios ou variveis codificadas em URL. A classe URLLoader envia eventos como complete, httpStatus, ioError, open, progress e securityError. O modelo de manipulao de eventos do ActionScript 3.0 substancialmente diferente do modelo do ActionScript 2.0 que utilizava os manipuladores de evento LoadVars.onData, LoadVars.onHTTPStatus e LoadVars.onLoad. Para obter mais informaes sobre como tratar eventos no ActionScript 3.0, consulte Manipulao de eventos na pgina 118 Os dados descarregados s ficam disponveis depois que o download concludo. Voc pode monitorar o andamento do download (bytes carregados e total de bytes) ouvindo o evento progress a ser despachado. No entanto, se um arquivo carregado muito rapidamente, o evento progress pode no ser despachado. Quando um arquivo baixado com sucesso, o evento complete despachado. Ao definir a propriedade URLLoader dataFormat, possvel receber os dados como texto, raw, dados binrios ou como objeto URLVariables.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao HTTP

806

O mtodo URLLoader.load() (e opcionalmente o construtor da classe URLLoader) utiliza um nico parmetro, request, que um objeto URLRequest. Um objeto URLRequest contm todas as informaes para uma nica solicitao HTTP, como o URL de destino, mtodo de solicitao (GET ou POST), informaes de cabealho adicionais e o tipo MIME. Por exemplo, para carregar um pacote XML em um script de servidor, voc pode usar o seguinte cdigo:
var secondsUTC:Number = new Date().time; var dataXML:XML = <clock> <time>{secondsUTC}</time> </clock>; var request:URLRequest = new URLRequest("http://www.yourdomain.com/time.cfm"); request.contentType = "text/xml"; request.data = dataXML.toXMLString(); request.method = URLRequestMethod.POST; var loader:URLLoader = new URLLoader(); loader.load(request);

O snippet anterior cria um documento XML denominado dataXML que contm um pacote XML a ser enviado ao servidor. O exemplo define a propriedade URLRequest contentType para "text/xml" e atribui o documento XML propriedade URLRequest data. Por fim, o exemplo cria um objeto URLLoader e envia a solicitao para o script remoto utilizando o mtodo load().

Uso da classe URLStream

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe URLStream fornece acesso aos dados descarregados conforme os dados se tornam disponveis. A classe URLStream tambm permite encerrar um fluxo antes que o seu download seja finalizado. Os dados descarregados esto disponveis como dados binrios raw. Ao ler dados de um objeto URLStream, use a propriedade bytesAvailable para determinar se dados suficientes esto disponveis antes da leitura. Uma exceo EOFError enviada se voc tentar ler mais dados do que o disponvel. O evento httpResponseStatus (AIR) No Adobe AIR, a classe URLStream envia um evento httpResponseStatus alm do evento httpStatus. O evento httpResponseStatus entregue antes de quaisquer dados de resposta. O evento httpResponseStatus (representado pela classe HTTPStatusEvent) inclui uma propriedade responseURL, que o URL do qual a resposta foi retornada, e uma propriedade responseHeaders, que uma matriz de objetos URLRequestHeader representando os cabealhos de resposta retornados pela resposta.

Carregamento de dados de documentos externos

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Ao construir aplicativos dinmicos, pode ser til carregar os dados de arquivos externos ou de scripts do lado do servidor. Isso permite criar aplicativos dinmicos sem precisar editar ou recompilar seu aplicativo. Por exemplo, se voc criar um aplicativo dica do dia, poder gravar um script do lado do servidor que recupera uma dica aleatria de um banco de dados e salva-a em um arquivo de texto uma vez por dia. Em seguida, o aplicativo pode carregar o contedo de um arquivo de texto esttico em vez de consultar o banco de dados a cada vez.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao HTTP

807

O seguinte snippet cria um objeto URLRequest e URLLoader que carrega o contedo de um arquivo de texto externo, params.txt:
var request:URLRequest = new URLRequest("params.txt"); var loader:URLLoader = new URLLoader(); loader.load(request);

Por padro, se voc no definir um mtodo de solicitao, o Flash Player e o Adobe AIR carregaro o contedo usando o mtodo GET HTTP. Para enviar os dados usando o mtodo POST, defina a propriedade request.method como POST usando a constante esttica URLRequestMethod.POST, conforme mostrado no seguinte cdigo:
var request:URLRequest = new URLRequest("sendfeedback.cfm"); request.method = URLRequestMethod.POST;

O documento externo (params.txt), que carregado no tempo de execuo, contm os seguintes dados:
monthNames=January,February,March,April,May,June,July,August,September,October,November,Dece mber&dayNames=Sunday,Monday,Tuesday,Wednesday,Thursday,Friday,Saturday

O arquivo contm dois parmetros: monthNames e dayNames. Cada parmetro contm uma lista separada por vrgulas que analisada como strings. Voc pode dividir essa lista em uma matriz usando o mtodo String.split(). Evite usar palavras reservadas ou construes de linguagem como nomes de variveis em arquivos de dados externos, porque isso dificulta a leitura e a depurao do cdigo. Depois que os dados so carregados, o evento complete despachado, e o contedo do documento externo fica disponvel para uso na propriedade data de URLLoader, como ilustrado neste cdigo:
function completeHandler(event) { var loader2 = event.target; air.trace(loader2.data); }

Se o documento remoto contm pares de nome e valor, possvel analisar os dados atravs da classe URLVariables passando o contedo do arquivo carregado, como segue:
private function completeHandler(event:Event):void { var loader2:URLLoader = URLLoader(event.target); var variables:URLVariables = new URLVariables(loader2.data); trace(variables.dayNames); }

Cada par de nome e valor do arquivo externo criado como propriedade no objeto URLVariables. Cada propriedade no objeto variables do exemplo de cdigo anterior tratada como string. Se o valor do par de nome e valor uma lista de termos, voc pode converter a string em qualquer matriz chamando o mtodo String.split(), como segue:
var dayNameArray:Array = variables.dayNames.split(",");

Se voc estiver carregando dados numricos de arquivos de texto externos, converta os valores em valores numricos usando a funo de nvel superior, como int(), uint() ou Number(). Em vez de carregar o contedo do arquivo remoto como uma string e criar um novo objeto URLVariables, voc pode definir a propriedade URLLoader.dataFormat como uma das propriedades estticas encontradas na classe URLLoaderDataFormat. Os trs valores possveis para a propriedade URLLoader.dataFormat so os seguintes:

URLLoaderDataFormat.BINARY a propriedade URLLoader.data contm dados binrios armazenados em um

objeto ByteArray.
URLLoaderDataFormat.TEXT a propriedade URLLoader.data contm texto em um objeto String.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao HTTP

808

URLLoaderDataFormat.VARIABLES a propriedade URLLoader.data contm variveis codificadas em URL armazenadas em um objeto URLVariables.

O cdigo a seguir demonstra como a configurao da propriedade URLLoader.dataFormat como URLLoaderDataFormat.VARIABLES permite analisar automaticamente dados carregados em um objeto URLVariables:
package { import import import import import

flash.display.Sprite; flash.events.*; flash.net.URLLoader; flash.net.URLLoaderDataFormat; flash.net.URLRequest;

public class URLLoaderDataFormatExample extends Sprite { public function URLLoaderDataFormatExample() { var request:URLRequest = new URLRequest("http://www.[yourdomain].com/params.txt"); var variables:URLLoader = new URLLoader(); variables.dataFormat = URLLoaderDataFormat.VARIABLES; variables.addEventListener(Event.COMPLETE, completeHandler); try { variables.load(request); } catch (error:Error) { trace("Unable to load URL: " + error); } } private function completeHandler(event:Event):void { var loader:URLLoader = URLLoader(event.target); trace(loader.data.dayNames); } } }

Nota: O valor padro de URLLoader.dataFormat URLLoaderDataFormat.TEXT. Como ilustrado no exemplo a seguir, carregar XML de um arquivo externo o mesmo que carregar URLVariables. Voc pode criar uma ocorrncia de URLRequest e uma de URLLoader e us-las para baixar um documento XML remoto. Quando o arquivo baixado completamente, o evento Event.COMPLETE despachado e o contedo do arquivo externo convertido para uma ocorrncia XML, que pode ser analisada usando mtodos e propriedades XML.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao HTTP

809

package { import import import import import

flash.display.Sprite; flash.errors.*; flash.events.*; flash.net.URLLoader; flash.net.URLRequest;

public class ExternalDocs extends Sprite { public function ExternalDocs() { var request:URLRequest = new URLRequest("http://www.[yourdomain].com/data.xml"); var loader:URLLoader = new URLLoader(); loader.addEventListener(Event.COMPLETE, completeHandler); try { loader.load(request); } catch (error:ArgumentError) { trace("An ArgumentError has occurred."); } catch (error:SecurityError) { trace("A SecurityError has occurred."); } } private function completeHandler(event:Event):void { var dataXML:XML = XML(event.target.data); trace(dataXML.toXMLString()); } } }

Comunicao com scripts externos

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Alm de carregar arquivos de dados externos, voc pode usar tambm a classe URLVariables para enviar variveis a um script do lado do servidor e processar a resposta do servidor. Isso til, por exemplo, se voc est programando um jogo e deseja enviar a pontuao do usurio para um servidor, que calcular se ela deve ser adicionada lista de pontuaes mais altas, ou mesmo enviar informaes de logon de um usurio para um servidor valid-las. Um script de servidor pode processar o nome do usurio e a senha, valid-los em um banco de dados e confirmar se as credenciais fornecidas pelo usurio so vlidas. O seguinte snippet cria um objeto URLVariables denominado variables que cria uma nova varivel chamada name. Em seguida, criado um objeto URLRequest que especifica a URL do script de servidor para a qual enviar as variveis. Depois, voc define a propriedade method do objeto URLRequest para enviar as variveis como uma solicitao HTTP POST. Para adicionar o objeto URLVariables solicitao de URL, defina a propriedade data do objeto URLRequest como o objeto URLVariables criado anteriormente. Por fim, criada a ocorrncia de URLLoader e o mtodo URLLoader.load(), que inicia a solicitao, chamado.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao HTTP

810

var variables:URLVariables = new URLVariables("name=Franklin"); var request:URLRequest = new URLRequest(); request.url = "http://www.[yourdomain].com/greeting.cfm"; request.method = URLRequestMethod.POST; request.data = variables; var loader:URLLoader = new URLLoader(); loader.dataFormat = URLLoaderDataFormat.VARIABLES; loader.addEventListener(Event.COMPLETE, completeHandler); try { loader.load(request); } catch (error:Error) { trace("Unable to load URL"); } function completeHandler(event:Event):void { trace(event.target.data.welcomeMessage); }

O cdigo a seguir contm o contedo do documento greeting.cfm do Adobe ColdFusion usado no exemplo anterior:
<cfif NOT IsDefined("Form.name") OR Len(Trim(Form.Name)) EQ 0> <cfset Form.Name = "Stranger" /> </cfif> <cfoutput>welcomeMessage=#UrlEncodedFormat("Welcome, " & Form.name)# </cfoutput>

Solicitaes do servio da Web

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Existem diversos servios web com base em HTTP. Os principais tipos so:

REST XML-RPC SOAP

Para utilizar um servio web no ActionScript 3, crie um objeto URLRequest, construa a chamada do servio web utilizando variveis URL ou um documento XML e envie o servio utilizando um objeto URLLoader. O framework do Flex contm diversas classes que facilitam a utilizao de servios webespecialmente teis para o acesso a servios SOAP complexos. Desde o Flash Professional CS3, possvel utilizar classes Flex em aplicativos desenvolvidos no Flash Professional e tambm em aplicativos desenvolvidos no Flash Builder. Em aplicativos AIR com base em HTML, voc pode utilizar as classes URLRequest e URLLoader ou a classe Javascript XMLHttpRequest. Se desejar, voc tambm pode criar uma biblioteca SWF que expe os componentes de servio web do framework Flex para o cdigo Javascript.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao HTTP

811

Quando o aplicativo executado em um navegador, voc somente pode utilizar os servios web no mesmo domnio de Internet em que o SWF de chamada est localizado, a no ser que o servidor que hospeda o servio web tambm hospede um arquivo de poltica entre domnios que permite o acesso a partir de outro domnio. Uma tcnica muito utilizada quando no existe um arquivo de poltica entre domnios disponvel encaminhar as solicitaes por meio de seu prprio servidor. O Adobe Blaze DS E Adobe LiveCycle possuem suporte a encaminhamento de servio web. Em aplicativos AIR, um arquivo de polticas entre domnios no obrigatrio quando a chamada do servio web originada da rea de segurana do aplicativo. O contedo do aplicativo AIR nunca servido a partir de um domnio remoto, portanto ele no se enquadram nos tipos de ataques que as polticas entre domnios evitam. Em aplicativos AIR com base na web, a rea de segurana do aplicativo pode fazer XMLHttpRequests entre domnios. Voc tambm pode permitir o contedo em outras reas de segurana para fazer XMLHttpRequests entre domnios, contanto que o contedo seja carregado em um iframe.

Mais tpicos da Ajuda

Controles de site (arquivos de poltica) na pgina 1037 Adobe BlazeDS Adobe LiveCycle ES2 Arquitetura REST XML-RPC Protocolo SOAP

Solicitaes de servio web estilo REST

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Servios web estilo REST utilizam verbos do mtodo HTTP para atribuir a ao bsica e as variveis de URL para especificar detalhes de ao. Por exemplo, uma solicitao para obter dados de um item pode utilizar o verbo GET e variveis de URL para especificar um nome de mtodo e ID de item. A sequncia de caracteres do URL resultante pode ser similar a:
http://service.example.com/?method=getItem&id=d3452

Para acessar um servio web estilo REST com o ActionScript, voc pode utilizar as classes URLRequest, URLVariables e URLLoader classes. No cdigo Javascript de um aplicativo AIR, voc tambm pode utilizar um XMLHttpRequest. Geralmente, a programao de uma chamada de servio web estilo REST no ActionScript envolve as etapas a seguir:
1 Crie um objeto URLRequest. 2 Defina o URL do servio e o mtodo HTTP no objeto de solicitao. 3 Crie um objeto URLVariables. 4 Configure os parmetros de chamada do servio como propriedades dinmicas do objeto variveis. 5 Atribua o objeto variveis propriedade de dados do objeto de solicitao. 6 Envie uma chamada para o servio com um objeto URLLoader. 7 Gerencie o evento complete enviado pelo URLLoader indicando que a chamada do servio foi concluda. Tambm

aconselhvel monitorar os diversos eventos de erro que podem ser enviados pelo objeto URLLoader. Por exemplo, imagine um servio web que expe um mtodo de teste que ecoa os parmetros da chamada de volta para o solicitante. O cdigo ActionScript a seguir pode ser utilizado para chamar um servio:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao HTTP

812

import import import import import import import import

flash.events.Event; flash.events.ErrorEvent; flash.events.IOErrorEvent; flash.events.SecurityErrorEvent; flash.net.URLLoader; flash.net.URLRequest; flash.net.URLRequestMethod; flash.net.URLVariables;

private var requestor:URLLoader = new URLLoader(); public function restServiceCall():void { //Create the HTTP request object var request:URLRequest = new URLRequest( "http://service.example.com/" ); request.method = URLRequestMethod.GET; //Add the URL variables var variables:URLVariables = new URLVariables(); variables.method = "test.echo"; variables.api_key = "123456ABC"; variables.message = "Able was I, ere I saw Elba."; request.data = variables; //Initiate the transaction requestor = new URLLoader(); requestor.addEventListener( Event.COMPLETE, httpRequestComplete ); requestor.addEventListener( IOErrorEvent.IOERROR, httpRequestError ); requestor.addEventListener( SecurityErrorEvent.SECURITY_ERROR, httpRequestError ); requestor.load( request ); } private function httpRequestComplete( event:Event ):void { trace( event.target.data ); } private function httpRequestError( error:ErrorEvent ):void{ trace( "An error occured: " + error.message ); }

No Javascript de um aplicativo AIR, voc pode fazer a mesma solicitao utilizando o objeto XMLHttpRequest:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao HTTP

813

<html> <head><title>RESTful web service request</title> <script type="text/javascript"> function makeRequest() { var requestDisplay = document.getElementById( "request" ); var resultDisplay = document.getElementById( "result" ); //Create a conveninece object to hold the call properties var request = {}; request.URL = "http://service.example.com/"; request.method = "test.echo"; request.HTTPmethod = "GET"; request.parameters = {}; request.parameters.api_key = "ABCDEF123"; request.parameters.message = "Able was I ere I saw Elba."; var requestURL = makeURL( request ); xmlhttp = new XMLHttpRequest(); xmlhttp.open( request.HTTPmethod, requestURL, true); xmlhttp.onreadystatechange = function() { if (xmlhttp.readyState == 4) { resultDisplay.innerHTML = xmlhttp.responseText; } } xmlhttp.send(null); requestDisplay.innerHTML = requestURL; } //Convert the request object into a properly formatted URL function makeURL( request ) { var url = request.URL + "?method=" + escape( request.method ); for( var property in request.parameters ) { url += "&" + property + "=" + escape( request.parameters[property] ); } return url; } </script> </head> <body onload="makeRequest()"> <h1>Request:</h1> <div id="request"></div> <h1>Result:</h1> <div id="result"></div> </body> </html>

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao HTTP

814

Solicitaes de servio web XML-RPC

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Um servio web XML-RPC recebe seus parmetros de chamada como um documento XML, em vez de um conjunto de variveis do URL. Par efetuar uma operao com um servio web XML-RPC, crie uma mensagem XML formatada de corretamente e envia-a para o servio web utilizando o mtodo HTTP POST. Alm disso, voc deve definir o cabealho Content-Type para a solicitao, de forma que o servidor trate os dados da solicitao como XML. O exemplo a seguir ilustra como utilizar a mesma chamada de servio web mostrada no exemplo REST, mas desta vez, como um servio XML-RPC:
import flash.events.Event; import flash.events.ErrorEvent; import flash.events.IOErrorEvent; import flash.events.SecurityErrorEvent; import flash.net.URLLoader; import flash.net.URLRequest; import flash.net.URLRequestMethod; import flash.net.URLVariables; public function xmlRPCRequest():void { //Create the XML-RPC document var xmlRPC:XML = <methodCall> <methodName></methodName> <params> <param> <value> <struct/> </value> </param> </params> </methodCall>; xmlRPC.methodName = "test.echo"; //Add the method parameters var parameters:Object = new Object(); parameters.api_key = "123456ABC"; parameters.message = "Able was I, ere I saw Elba."; for( var propertyName:String in parameters ) { xmlRPC..struct.member[xmlRPC..struct.member.length + 1] = <member> <name>{propertyName}</name> <value> <string>{parameters[propertyName]}</string> </value> </member>; } //Create the HTTP request object var request:URLRequest = new URLRequest( "http://service.example.com/xml-rpc/" ); request.method = URLRequestMethod.POST; request.cacheResponse = false; request.requestHeaders.push(new URLRequestHeader("Content-Type", "application/xml"));

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao HTTP

815

request.data = xmlRPC; //Initiate the request requestor = new URLLoader(); requestor.dataFormat = URLLoaderDataFormat.TEXT; requestor.addEventListener( Event.COMPLETE, xmlRPCRequestComplete ); requestor.addEventListener( IOErrorEvent.IO_ERROR, xmlRPCRequestError ); requestor.addEventListener( SecurityErrorEvent.SECURITY_ERROR, xmlRPCRequestError ); requestor.load( request ); } private function xmlRPCRequestComplete( event:Event ):void { trace( XML(event.target.data).toXMLString() ); } private function xmlRPCRequestError( error:ErrorEvent ):void { trace( "An error occurred: " + error ); }

O WebKit no AIR no oferece suporte a sintaxe E4X de forma que o mtodo utilizado para criar o documento XML no exemplo anterior, no funciona com cdigo Javascript. Em vez disse, utilize os mtodos DOM para criar o documento XML ou o documento como uma sequncia de caracteres e utilizar a classe Javascript DOMParser para converter a sequncia de caracteres para XML. O exemplo a seguir utiliza mtodos DOM para criar uma mensagem XML-RPC e um XMLHttpRequest para executar a operao do servio web:
<html> <head> <title>XML-RPC web service request</title> <script type="text/javascript"> function makeRequest() { var requestDisplay = document.getElementById( "request" ); var resultDisplay = document.getElementById( "result" ); var request = {}; request.URL = "http://services.example.com/xmlrpc/"; request.method = "test.echo"; request.HTTPmethod = "POST"; request.parameters = {}; request.parameters.api_key = "123456ABC"; request.parameters.message = "Able was I ere I saw Elba."; var requestMessage = formatXMLRPC( request ); xmlhttp = new XMLHttpRequest(); xmlhttp.open( request.HTTPmethod, request.URL, true); xmlhttp.onreadystatechange = function() { if (xmlhttp.readyState == 4) { resultDisplay.innerText = xmlhttp.responseText; } } xmlhttp.send( requestMessage );

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao HTTP

816

requestDisplay.innerText = xmlToString( requestMessage.documentElement ); } //Formats a request as XML-RPC document function formatXMLRPC( request ) { var xmldoc = document.implementation.createDocument( "", "", null ); var root = xmldoc.createElement( "methodCall" ); xmldoc.appendChild( root ); var methodName = xmldoc.createElement( "methodName" ); var methodString = xmldoc.createTextNode( request.method ); methodName.appendChild( methodString ); root.appendChild( methodName ); var params = xmldoc.createElement( "params" ); root.appendChild( params ); var param = xmldoc.createElement( "param" ); params.appendChild( param ); var value = xmldoc.createElement( "value" ); param.appendChild( value ); var struct = xmldoc.createElement( "struct" ); value.appendChild( struct ); for( var property in request.parameters ) { var member = xmldoc.createElement( "member" ); struct.appendChild( member ); var name = xmldoc.createElement( "name" ); var paramName = xmldoc.createTextNode( property ); name.appendChild( paramName ) member.appendChild( name ); var value = xmldoc.createElement( "value" ); var type = xmldoc.createElement( "string" ); value.appendChild( type ); var paramValue = xmldoc.createTextNode( request.parameters[property] ); type.appendChild( paramValue ) member.appendChild( value ); } return xmldoc; } //Returns a string representation of an XML node function xmlToString( rootNode, indent ) { if( indent == null ) indent = ""; var result = indent + "<" + rootNode.tagName + ">\n"; for( var i = 0; i < rootNode.childNodes.length; i++) { if(rootNode.childNodes.item( i ).nodeType == Node.TEXT_NODE ) { result += indent + " " + rootNode.childNodes.item( i ).textContent + "\n"; } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao HTTP

817

if( rootNode.childElementCount > 0 ) { result += xmlToString( rootNode.firstElementChild, indent + " } if( rootNode.nextElementSibling ) { result += indent + "</" + rootNode.tagName + ">\n"; result += xmlToString( rootNode.nextElementSibling, indent ); } else { result += indent +"</" + rootNode.tagName + ">\n"; } return result; } </script> </head> <body onload="makeRequest()"> <h1>Request:</h1> <pre id="request"></pre> <h1>Result:</h1> <pre id="result"></pre> </body> </html>

" );

Solicitao do servio web SOAP

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O SOAP fortalece o conceito de geral de servio web XML-RPC e fornece um forma mais rica, no entanto complexa, de transferir dados digitados. Os servios web SOAP geralmente fornece um arquivo Web Service Description Language (WSDL) que especifica chamadas de servio web, tipos de dados e o URL do servio. Embora o ActionScript 3 no fornea suporte direto para SOAP, possvel criar uma mensagem SOAP XML manualmente, public-la no servidor e analisar os resultados. No entanto, para outras coisas com exceo do servio web SOAP mais simples, voc pode economizar tempo de desenvolvimento utilizando uma biblioteca SOAP j existente. O framework Flex inclui biblioteca para acessar servios web SOAP. No Flash Builder, a biblioteca rpc.swc includa automaticamente em projetos Flex, j que ela faz parte do framework Flex. No Flash Professional, voc pode adicionar o Flex framework.swc e rpc.swc no caminho da biblioteca de um projeto e, em seguida, acessar as classes Flex com o ActionScript.

Mais tpicos da Ajuda

Utilizando o componente de servio web Flex no Flash Professional Cristophe Coenraets: Real-time Trader Desktop para Android

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao HTTP

818

Abertura de um URL em outro aplicativo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc pode usar a funo navigateToURL() para abrir um URL em um navegador da Web ou em outro aplicativo. Para o contedo em execuo no AIR, a funo navigateToURL() abre a pgina no navegador da Web do sistema padro. Para o objeto URLRequest que voc passar como parmetro request desta funo, somente a propriedade url usada. O primeiro parmetro da funo navigateToURL(), o parmetro navigate, um objeto URLRequest (consulte Uso da classe URLRequest na pgina 801). O segundo um parmetro window opcional, no qual voc pode especificar o nome da janela. Por exemplo, o cdigo a seguir abre a pgina www.adobe.com:
var url:String = "http://www.adobe.com"; var urlReq:URLRequest = new URLRequest(url); navigateToURL(urlReq);

Nota: Na utilizao da funo navigateToURL(), o tempo de execuo trata um objeto URLRequest que usa o mtodo POST (um que tenha a propriedade method definida como URLRequestMethod.POST) Quando usada a funo navigateToURL(), so permitidos esquemas de URL baseados na rea de segurana do cdigo que chama a funo navigateToURL(). Algumas APIs permitem iniciar contedo em um navegador da Web. Por motivos de segurana, alguns esquemas de URL so proibidos quando essas APIs so utilizadas no AIR. A lista de esquemas proibidos depende da caixa de proteo de segurana do cdigo que usa a API. (Para obter detalhes sobre caixas de proteo de segurana, consulte Segurana do AIR na pgina 1063.) Caixa de proteo do aplicativo (somente AIR) Os esquemas abaixo so permitidos. Use esses esquemas da mesma forma que voc os utilizaria em um navegador da Web.

http: https: arquivo: mailto: O AIR direciona essas solicitaes para o aplicativo de email registrado do sistema app: app-storage: sms: em dispositivos mveis, o AIR redireciona solicitaes sms: para o aplicativo de mensagem de texto padro.

(Se nenhum aplicativo estiver configurado para lidar com URLs de sms:, a solicitao no far nada.) O formato do URL precisa estar em conformidade com as convenes do sistema em que o aplicativo est sendo executado. Por exemplo, no Android, o esquema URI precisa estar em minsculas.
navigateToURL( new URLRequest( "sms:+15555550101") );

tel: em dispositivos mveis, o AIR redireciona solicitaes tel: para o aplicativo de discagem telefnica padro. (Se nenhum aplicativo estiver configurado para lidar com URLs de tel:, a solicitao no far nada.) O formato do URL precisa estar em conformidade com as convenes do sistema em que o aplicativo est sendo executado. Por exemplo, no Android, o esquema URI precisa estar em minsculas. navigateToURL( new URLRequest( "tel:5555555555") );

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao HTTP

819

market: em dispositivos Android, o AIR redireciona solicitaes market: para o aplicativo Market. navigateToURL( new URLRequest( "market://search?q=Adobe Flash") ); navigateToURL( new URLRequest( "market://search?q=pname:com.adobe.flashplayer") );

Todos os demais esquemas de URL so proibidos. Caixas de proteo remotas Os esquemas abaixo so permitidos. Use esses esquemas da mesma forma que voc os utilizaria em um navegador da Web.

http: https: mailto: O AIR direciona essas solicitaes para o aplicativo de email registrado do sistema

Todos os demais esquemas de URI so proibidos. Caixa de proteo Local com arquivo Os esquemas abaixo so permitidos. Use esses esquemas da mesma forma que voc os utilizaria em um navegador da Web.

arquivo: mailto: O AIR direciona essas solicitaes para o aplicativo de email registrado do sistema

Todos os demais esquemas de URI so proibidos. Caixa de proteo Local com rede Os esquemas abaixo so permitidos. Use esses esquemas da mesma forma que voc os utilizaria em um navegador da Web.

http: https: mailto: O AIR direciona essas solicitaes para o aplicativo de email registrado sistema

Todos os demais esquemas de URI so proibidos. Caixa de proteo Local confivel Os esquemas abaixo so permitidos. Use esses esquemas da mesma forma que voc os utilizaria em um navegador da Web.

arquivo: http:

https:
mailto: O AIR direciona essas solicitaes para o aplicativo de email registrado do sistema

Todos os demais esquemas de URI so proibidos.

ltima atualizao em 29/3/2011

820

Captulo 43: Comunicao com outras instncias do Flash Player e AIR

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe LocalConnection permite a comunicao entre aplicativos Adobe AIR e tambm com o contedo SWF executado no navegador. Voc tambm pode usar a classe LocalConnection para se comunicar entre um aplicativo AIR e o contedo SWF em execuo no navegador. A classe LocalConnection permite construir aplicativos versteis que podem compartilhar dados entre as instncias do Flash Player e do AIR.

Sobre a classe Local

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe LocalConnection permite desenvolver arquivos SWF que podem enviar instrues a outros arquivos SWF sem o uso do mtodo fscommand() ou do JavaScript. Objetos LocalConnection podem se comunicar apenas entre arquivos SWF que esto em execuo no mesmo computador cliente, mas podem ser executados em diferentes aplicativos. Por exemplo, um arquivo SWF em execuo em um navegador e um arquivo SWF em execuo em um projetor podem compartilhar informaes, com o projetor mantendo informaes locais e o arquivo SWF com base em navegador conectado remotamente. (Um projetor um arquivo SWF salvo em um formato que pode ser executado como um aplicativo autnomo, isto , o projetor no requer que o Flash Player seja instalado porque est incorporado dentro do executvel.) Objetos LocalConnection podem ser usados para comunicao entre SWFs usando diferentes verses do ActionScript:

Objetos LocalConnection do ActionScript 3.0 podem se comunicar com objetos LocalConnection criados no
ActionScript 1.0 ou 2.0.

Objetos LocalConnection do ActionScript 1.0 ou 2.0 podem se comunicar com objetos LocalConnection criados
no ActionScript 3.0. O Flash Player manipula automaticamente essa comunicao entre objetos LocalConnection de diferentes verses. O modo mais simples de usar um objeto LocalConnection permitir a comunicao somente entre objetos LocalConnection localizados no mesmo domnio ou no mesmo aplicativo AIR. Desse modo, no necessrio se preocupar com problemas de segurana. No entanto, se precisar permitir a comunicao entre domnios, h vrios modos de implementar medidas de segurana. Para obter mais informaes, consulte a discusso do parmetro connectionName do mtodo send() e das entradas allowDomain() e domain na listagem da classe LocalConnection, na Referncia do ActionScript 3.0 para a plataforma Adobe Flash. possvel usar objetos LocalConnection para enviar e receber dados dentro de um arquivo SWF nico, mas a Adobe no recomenda esse procedimento. Em vez disso, use objetos compartilhados. H trs maneiras de adicionar mtodos de retorno de chamada aos objetos LocalConnection:

Criar subclasse da classe LocalConnection e adicionar mtodos. Definir a propriedade LocalConnection.client como um objeto que implementa os mtodos. Criar uma classe dinmica que estende o LocalConnection e anexar mtodos dinamicamente.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao com outras instncias do Flash Player e AIR

821

A primeira maneira de adicionar mtodos de retorno de chamada estender a classe LocalConnection. Voc define os mtodos dentro da classe personalizada em vez de adicion-los dinamicamente ocorrncia de LocalConnection. Essa abordagem demonstrada no cdigo a seguir:
package { import flash.net.LocalConnection; public class CustomLocalConnection extends LocalConnection { public function CustomLocalConnection(connectionName:String) { try { connect(connectionName); } catch (error:ArgumentError) { // server already created/connected } } public function onMethod(timeString:String):void { trace("onMethod called at: " + timeString); } } }

possvel utilizar o cdigo a seguir para criar uma nova instncia da classe CustomLocalConnection:
var serverLC:CustomLocalConnection; serverLC = new CustomLocalConnection("serverName");

A segunda maneira de adicionar mtodos de retorno de chamada usar a propriedade LocalConnection.client. Isso envolve a criao de uma classe personalizada e a atribuio de uma nova ocorrncia para a propriedade cliente, conforme mostrado no cdigo a seguir:
var lc:LocalConnection = new LocalConnection(); lc.client = new CustomClient();

A propriedade LocalConnection.client indica os mtodos de retorno de chamada do objeto que devem ser chamados. No cdigo anterior, a propriedade client foi definida como uma nova ocorrncia de uma classe personalizada, CustomClient. O valor padro da propriedade client a ocorrncia LocalConnection atual. Voc poder usar a propriedade client, se tiver dois manipuladores de dados que tenham o mesmo conjunto de mtodos, mas funcionam de modo diferente, por exemplo, em um aplicativo em que um boto em uma janela alterna a exibio em uma segunda janela. Para criar a classe CustomClient, voc pode usar o seguinte cdigo:
package { public class CustomClient extends Object { public function onMethod(timeString:String):void { trace("onMethod called at: " + timeString); } } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao com outras instncias do Flash Player e AIR

822

A terceira maneira de adicionar mtodos de retorno de chamada criando uma classe dinmica e anexando os mtodos dinamicamente, muito semelhante ao uso da classe LocalConnection em verses anteriores do ActionScript, conforme mostrado no cdigo a seguir:
import flash.net.LocalConnection; dynamic class DynamicLocalConnection extends LocalConnection {}

Os mtodos de retorno de chamada podem ser adicionados dinamicamente a essa classe usando o seguinte cdigo:
var connection:DynamicLocalConnection = new DynamicLocalConnection(); connection.onMethod = this.onMethod; // Add your code here. public function onMethod(timeString:String):void { trace("onMethod called at: " + timeString); }

A maneira anterior de adicionar mtodos de retorno de chamada no recomendada porque o cdigo no muito porttil. Alm disso, o uso desse mtodo de criao de conexes locais pode criar problemas de desempenho, porque o acesso a propriedades dinmicas drasticamente mais lento do que o acesso a propriedades seladas. Propriedade isPerUser A propriedade isPerUser foi adicionada ao Flash Player (10.0.32) e AIR (1.5.2) para solucionar um conflito que ocorre quando mais de um usurio est conectado em um computador Mac. Em outros sistemas, a propriedade ignorada, j que a conexo local sempre foi estendida aos usurios. A propriedade isPerUser deve ser definida para true no cdigo novo. No entanto, o valor padro false para manter a compatibilidade com verses anteriores. O padro pode ser mudado em verses futuras dos tempos de execuo.

Envio de mensagens entre dois aplicativos

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Use a classe LocalConnection para se comunicar entre aplicativos AIR diferentes e entre aplicativos AIR diferentes e aplicativos Adobe Flash Player (SWF) diferentes em execuo em um navegador. Voc tambm pode usar a classe LocalConnection para se comunicar entre um aplicativo AIR e um aplicativo SWF em execuo no navegador. Por exemplo, voc pode ter vrias ocorrncias do Flash Player em uma pgina da Web ou fazer com que uma ocorrncia do Flash Player recupere dados de uma ocorrncia do Flash Player em uma janela pop-up. O cdigo seguinte define um objeto LocalConnection que atua como um servidor e aceita chamadas LocalConnection recebidas de outros aplicativos:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao com outras instncias do Flash Player e AIR

823

package { import flash.net.LocalConnection; import flash.display.Sprite; public class ServerLC extends Sprite { public function ServerLC() { var lc:LocalConnection = new LocalConnection(); lc.client = new CustomClient1(); try { lc.connect("conn1"); } catch (error:Error) { trace("error:: already connected"); } } } }

Esse cdigo primeiro cria um objeto LocalConnection chamado lc e define a propriedade client como um objeto, clientObject. Quando outro aplicativo chama um mtodo nessa instncia LocalConnection, o tempo de execuo pesquisa por esse mtodo no objeto clientObject. Caso possua uma conexo com o nome especificado, uma exceo de Argument Error enviada, indicando que a tentativa de conexo falhou porque o objeto j est conectado. Sempre que uma ocorrncia do Flash Player se conecta a esse arquivo SWF e tenta chamar qualquer mtodo para a conexo local especificada, a solicitao enviada para a classe especificada pela propriedade client, definida como classe CustomClient1:
package { import flash.events.*; import flash.system.fscommand; import flash.utils.Timer; public class CustomClient1 extends Object { public function doMessage(value:String = ""):void { trace(value); } public function doQuit():void { trace("quitting in 5 seconds"); this.close(); var quitTimer:Timer = new Timer(5000, 1); quitTimer.addEventListener(TimerEvent.TIMER, closeHandler); } public function closeHandler(event:TimerEvent):void { fscommand("quit"); } } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao com outras instncias do Flash Player e AIR

824

Para criar um servidor LocalConnection, chame o mtodo LocalConnection.connect() e fornea um nome de conexo exclusivo. Se voc j tiver uma conexo com o nome especificado, um erro ArgumentError ser gerado, indicando que houve falha durante a tentativa de conexo, porque o objeto j est conectado. O snippet seguinte demonstra como criar uma LocalConnection com o nome conn1:
try { connection.connect("conn1"); } catch (error:ArgumentError) { trace("Error! Server already exists\n"); }

A conexo a um aplicativo primrio a partir de um secundrio requer primeiramente que voc crie um objeto LocalConnection no objeto LocalConnection de envio e, em seguida, chame o mtodo LocalConnection.send() com o nome da conexo e o nome do mtodo a ser executado. Por exemplo, para enviar o mtodo doQuit para o objeto LocalConnection que voc criou anteriormente, use o seguinte cdigo:
sendingConnection.send("conn1", "doQuit");

Esse cdigo se conecta a um objeto LocalConnection existente com o nome de conexo conn1 e chama o mtodo doMessage() no aplicativo remoto. Para enviar parmetros para o aplicativo remoto, especifique argumentos adicionais aps o nome do mtodo, no mtodo send(), como mostrado no seguinte snippet:
sendingConnection.send("conn1", "doMessage", "Hello world");

Conexo a contedo em domnios diferentes e a aplicativos AIR

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para permitir conexes apenas de domnios especficos, chame o mtodo allowDomain() ou o allowInsecureDomain() da classe LocalConnection e passe uma lista de um ou mais domnios que so permitidos para acessar esse objeto LocalConnection, passando um ou mais nomes de domnios a serem permitidos. Em verses anteriores do ActionScript, LocalConnection.allowDomain() e LocalConnection.allowInsecureDomain() eram mtodos de retorno de chamada que precisavam ser implementados por desenvolvedores e retornar um valor booleano. No ActionScript 3.0, LocalConnection.allowDomain() e LocalConnection.allowInsecureDomain() so mtodos internos que os desenvolvedores podem chamar exatamente como Security.allowDomain() e Security.allowInsecureDomain(), transmitindo um ou mais nomes de domnios a serem permitidos. O Flash Player 8 introduziu restries de segurana em arquivos SWF locais. Um arquivo SWF com acesso permitido Internet no pode ter acesso tambm ao sistema de arquivos local. Se voc especificar localhost, qualquer arquivo SWF local poder acessar o arquivo SWF. Se o mtodo LocalConnection.send() tentar se comunicar com um arquivo SWF a partir de uma caixa de proteo de segurana qual o cdigo de chamada no possui acesso, um evento securityError (SecurityErrorEvent.SECURITY_ERROR) ser despachado. Para solucionar esse erro, voc pode especificar o domnio do chamador no mtodo LocalConnection.allowDomain() do receptor.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao com outras instncias do Flash Player e AIR

825

H dois valores especiais que voc pode passar para os mtodos LocalConnection.allowDomain() e LocalConnection.allowInsecureDomain(): * e localhost. O valor asterisco (*) permite o acesso de todos os domnios. A string localhost permite chamadas para o aplicativo a partir do contedo instalado localmente, mas fora do diretrio de recursos do aplicativo. Se o mtodo LocalConnection.send() tentar se comunicar com um aplicativo a partir de uma caixa de proteo de segurana qual o cdigo de chamada no tem acesso, um evento securityError (SecurityErrorEvent.SECURITY_ERROR) ser despachado. Para solucionar esse erro, voc pode especificar o domnio do chamador no mtodo LocalConnection.allowDomain() do receptor. Se voc implementar a comunicao apenas entre o contedo no mesmo domnio, possvel especificar um parmetro connectionName que no inicie com um caractere sublinhado (_) e no especifique um nome de domnio (por exemplo, myDomain:connectionName). Use a mesma same string no comando LocalConnection.connect(connectionName). Se voc implementar a comunicao entre o contedo em domnios diferentes, especifique um parmetro connectionName que inicie com um sublinhado. Especificar o sublinhado torna o contedo com o objeto LocalConnection de recebimento mais durvel entre domnios. Estes so os dois casos possveis:

Se a string para connectionName no comear com um sublinhado, o tempo de execuo adicionar um prefixo
com o superdomnio e um caractere de dois pontos (por exemplo, myDomain:connectionName). Embora isso garanta que a sua conexo no entre em conflito com as conexes de nome idntico em outros domnios, qualquer objeto LocalConnection de envio deve especificar esse superdomnio (por exemplo, myDomain:connectionName). Se voc mover o arquivo HTML ou SWF com o objeto LocalConnection de recebimento para outro domnio, o tempo de execuo alterar o prefixo de para refletir o novo superdomnio (por exemplo, anotherDomain:connectionName). Todos os objetos LocalConnection de envio precisam ser manualmente editados de modo a apontar para o novo superdomnio.

Se a string para connectionName comear com um sublinhado (por exemplo, _connectionName), o tempo de
execuo no adicionar um prefixo a essa string. Isso significa que os objetos LocalConnection de recebimento e envio usam strings idnticas para connectionName. Se o objeto de recebimento usar LocalConnection.allowDomain() para especificar que sero aceitas conexes de qualquer domnio, voc poder mover o arquivo HTML OU SWF com o objeto LocalConnection de recebimento para outro domnio sem alterar nenhum objeto LocalConnection de envio. Uma desvantagem de usar nomes sublinhados em connectionName o potencial para colises, como quando dois aplicativos tentam, ambos, se conectar, usando o mesmo connectionName. Uma outra desvantagem est relacionada segurana. Nomes de conexes que utilizam sintaxe sublinhada no identificam o domnio do aplicativo ouvinte. Por esses motivos, nomes qualificados de domnio so preferveis. Adobe AIR Para comunicar-se com contedo executado na rea de segurana de aplicativo AIR (contedo instalado por aplicativo AIR), voc deve utilizar um prefixo no nome da conexo com um superdomnio que identifica o aplicativo AIR. A string de superdomnio inicia com app# seguido pelo ID de aplicativo ID e um ponto (.) , seguido pelo ID do publicador (se definido). Por exemplo, o superdomnio apropriado a ser utilizado com o parmetro connectionName para um aplicativo com o ID de aplicativo, com.example.air.MyApp e ID de publicador : "app#com.example.air.MyApp". Portanto, se o nome de conexo base for appConnection, a string inteira a ser utilizada no parmetro connectionName : "app#com.example.air.MyApp:appConnection". Se o aplicativo possuir o ID de publicador, o ID tambm deve ser includo na string do superdomnio: "app#com.example.air.MyApp.B146A943FBD637B68C334022D304CEA226D129B4.1".

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao com outras instncias do Flash Player e AIR

826

Quando voc permite que outro aplicativo AIR se comunique com seu aplicativo pela conexo local, preciso chamar o allowDomain() do objeto LocalConnection, passando o nome de domnio da conexo local. Para um aplicativo AIR, esse nome de domnio formado a partir das IDs do aplicativo e do editor, da mesma forma que na string de conexo. Por exemplo, se o aplicativo AIR de envio tem uma ID de aplicativo de com.example.air.FriendlyApp e uma ID de editor de 214649436BD677B62C33D02233043EA236D13934.1, a string de domnio a usar para permitir que esse aplicativo se conecte : app#com.example.air.FriendlyApp.214649436BD677B62C33D02233043EA236D13934.1. (Desde a verso 1.5.3 do AIR, nem todos os aplicativos AIR tm ID de publicador.)

ltima atualizao em 29/3/2011

827

Captulo 44: Comunicao com processos nativos do AIR

Adobe AIR 2 e posterior Como o Adobe AIR 2, os aplicativos AIR podem executar e se comunicar com outros processos nativos por meio da linha de comando. Por exemplo, um aplicativo AIR pode executar um processo e se comunicar com ele pode meio da entrada padro e dos fluxos de sada. Para se comunicar com processos nativos, empacote um aplicativo AIR para ser instalado atravs de um instalador nativo. O tipo de arquivo do instalador nativo epecifico do sistema operacional para o qual criado:

um arquivo DMG no Mac OS. um arquivo EXE no Windows. um pacote RPM ou DEB no Linux.
Esses aplicativos so conhecidos como aplicativos de perfil estendido de desktop. Voc pode criar um arquivo do instalador nativo especificando a opo -target native ao chamar o comando -package usando ADT.

Mais tpicos da Ajuda

flash.filesystem.File.openWithDefaultApplication() flash.desktop. NativeProcess

Viso geral das comunicaes do processo nativo

Adobe AIR 2 e posterior Uma aplicativo AIR no perfil estendido de desktop pode executar um arquivo, como se ele fosse chamado pela linha de comando. Ele pode se comunicar com os streams padro do processo nativo. Os fluxos padro incluem o fluxo de entrada padro (stdin), o fluxo de sada (stdout) e o fluxo de erro padro (stderr). Nota: Os aplicativos no perfil estendido de desktop tambm podem abrir arquivos e aplicativos usando o mtodo File.openWithDefaultApplication(). No entanto, usar este mtodo no fornece ao aplicativo AIR acesso aos fluxos padro. Para obter mais informaes, consulte Abertura de arquivos com o aplicativo padro do sistema na pgina 666. O exemplo de cdigo a seguir mostra como abrir um aplicativo test.exe no diretrio do aplicativo. O aplicativo passa o argumento "hello" como argumento da linha de comando, e acrescenta um ouvinte de evento ao fluxo de sada padro do processo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao com processos nativos do AIR

828

var nativeProcessStartupInfo:NativeProcessStartupInfo = new NativeProcessStartupInfo(); var file:File = File.applicationDirectory.resolvePath("test.exe"); nativeProcessStartupInfo.executable = file; var processArgs:Vector.<String> = new Vector.<String>(); processArgs.push("hello"); nativeProcessStartupInfo.arguments = processArgs; process = new NativeProcess(); process.addEventListener(ProgressEvent.STANDARD_OUTPUT_DATA, onOutputData); process.start(nativeProcessStartupInfo); public function onOutputData(event:ProgressEvent):void { var stdOut:ByteArray = process.standardOutput; var data:String = stdOut.readUTFBytes(process.standardOutput.bytesAvailable); trace("Got: ", data); }

Abertura e fechamento de um processo nativo

Adobe AIR 2 e posterior Para abrir um processo nativo, configure um objeto NativeProcessInfo para fazer o seguinte:

Aponte para o arquivo que voc deseja abrir Armazene os argumentos da linha de comando a serem passados para o processo quando abertos (opcional) Defina o diretrio de trabalho do processo (opcional)
Para iniciar o processo nativo, passe o objeto NativeProcessInfo como parmetro do mtodo start() de um objeto NativeProcess. Por exemplo, o cdigo a seguir mostra como abrir um aplicativo test.exe no diretrio do aplicativo. O aplicativo passa o argumento "hello" e define o diretrio de documentos do usurio como diretrio de trabalho:
var nativeProcessStartupInfo:NativeProcessStartupInfo = new NativeProcessStartupInfo(); var file:File = File.applicationDirectory.resolvePath("test.exe"); nativeProcessStartupInfo.executable = file; var processArgs:Vector.<String> = new Vector.<String>(); processArgs[0] = "hello"; nativeProcessStartupInfo.arguments = processArgs; nativeProcessStartupInfo.workingDirectory = File.documentsDirectory; process = new NativeProcess(); process.start(nativeProcessStartupInfo);

Para encerrar o processo, chame o mtodo exit() do objeto NativeProcess. Se voc desejar que um arquivo seja executvel no aplicativo instalado, certifique-se de que ele executvel no sistema de arquivos, durante a criao do pacote do aplicativo. (No Mac e Linux, voc pode utilizar o comando chmod para definir o indicador de executvel, se necessrio.)

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao com processos nativos do AIR

829

Comunicao com um processo nativo

Adobe AIR 2 e posterior Depois que um aplicativo AIR iniciar um processo nativo, ele pode se comunicar com os fluxos de entrada padro, sada padro e erro padro do processo. Voc l e grava os dados nos fluxos usando as seguintes propriedades do objeto NativeProcess:

standardInput Contm acesso aos dados do fluxo de entrada padro. standardOutput Contm acesso aos dados do fluxo de sada padro. standardError Contm acesso aos dados do fluxo de erro padro.

Gravao no fluxo de entrada padro Voc pode gravar os dados no fluxo de entrada padro usando os mtodos de gravao da propriedade standardInput do objeto NativeProcess. Como o aplicativo AIR grava os dados ao processo, o objeto NativeProcess despacha os eventos standardInputProgress. Se ocorrer um erro na gravao para um fluxo de entrada padro, o objeto NativeProcess envia um evento
ioErrorStandardInput.

Voc pode fechar o fluxo de entrada chamando o mtodo closeInput() do objeto NativeProcess. Quando o fluxo de entrada se fecha, o objeto NativeProcess despacha o evento standardInputClose.
var nativeProcessStartupInfo:NativeProcessStartupInfo = new NativeProcessStartupInfo(); var file:File = File.applicationDirectory.resolvePath("test.exe"); nativeProcessStartupInfo.executable = file; process = new NativeProcess(); process.start(nativeProcessStartupInfo); process.standardInput.writeUTF("foo"); if(process.running) { process.closeInput(); }

Leitura de um fluxo de sada padro Voc pode ler os dados do fluxo de sada padro usando os mtodos de leitura desta propriedade. Como o aplicativo AIR recebe os dados do fluxo de sada do processo, o objeto NativeProcess despacha os eventos standardOutputData. Se ocorrer um erro ao gravar no fluxo de sada padro, o objeto NativeProcess envia um evento
standardOutputError.

Quando o processo fecha o fluxo de sada, o objeto NativeProcess envia um evento standardOutputClose. Ao ler dados do stream de entrada padro, certifique-se de ler os dados como eles so gerados. Em outras palavras, adicione um ouvinte de enventos para o evento standardOutputData. No ouvinte de eventos standardOutputData , leia os dados da propriedade standardOutput do objeto NativeProcess. No fique apenas aguardando pelo evento standardOutputClose ou pelo evento exit para ler todos os dados. Caso voc no leia os dados na medida em que o processo nativo os gera, o buffer pode encher ou dados podem ser perdidos. Um buffer cheio pode fazer com que o processo nativo pare quando estiver tentando escrever mais dados. No entanto, se voc no registrar um ouvinte de eventos para o evento standardOutputData , o buffer no vai encher e o processo no vai parar. Neste caso, os dados no podero ser acessados.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao com processos nativos do AIR

830

var nativeProcessStartupInfo:NativeProcessStartupInfo = new NativeProcessStartupInfo(); var file:File = File.applicationDirectory.resolvePath("test.exe"); nativeProcessStartupInfo.executable = file; process = new NativeProcess(); process.addEventListener(ProgressEvent.STANDARD_OUTPUT_DATA, dataHandler); process.start(nativeProcessStartupInfo); var bytes:ByteArray = new ByteArray(); function dataHandler(event:ProgressEvent):void { bytes.writeBytes(process.standardOutput.readBytes(process.standardOutput.bytesAvailable); }

Leitura de um fluxo de erro padro Voc pode ler os dados do fluxo de erro padro usando os mtodos de leitura desta propriedade. Como o aplicativo AIR l os dados de erros do fluxo de erro do processo, o objeto NativeProcess despacha os eventos standardErrorData. Se ocorrer um erro ao gravar no fluxo de erro padro, o objeto NativeProcess envia um evento standardErrorIoError. Quando o processo fecha o fluxo de erros, o objeto NativeProcess envia um evento standardErrorClose.. Ao ler dados do stream de erro padro, certifique-se de ler os dados como eles so gerados. Em outras palavras, adicione um ouvinte de enventos para o evento standardErrorData. No ouvinte de eventos standardErrorData , leia os dados da propriedade standardError do objeto NativeProcess. No fique apenas aguardando pelo evento standardErrorClose ou pelo evento exit para ler todos os dados. Caso voc no leia os dados na medida em que o processo nativo os gera, o buffer pode encher ou dados podem ser perdidos. Um buffer cheio pode fazer com que o processo nativo pare quando estiver tentando escrever mais dados. No entanto, se voc no registrar um ouvinte de eventos para o evento standardErrorData , o buffer no vai encher e o processo no vai parar. Neste caso, os dados no podero ser acessados.
var nativeProcessStartupInfo:NativeProcessStartupInfo = new NativeProcessStartupInfo(); var file:File = File.applicationDirectory.resolvePath("test.exe"); nativeProcessStartupInfo.executable = file; process = new NativeProcess(); process.addEventListener(ProgressEvent.STANDARD_ERROR_DATA, errorDataHandler); process.start(nativeProcessStartupInfo); var errorBytes:ByteArray = new ByteArray(); function errorDataHandler(event:ProgressEvent):void { bytes.writeBytes(process.standardError.readBytes(process.standardError.bytesAvailable); }

Consideraes de segurana para a comunicao do processo nativo

Adobe AIR 2 e posterior A API de processo nativa pode executar qualquer executvel no sistema do usurio. Seja muito cuidadoso ao construir e executar comandos. Se qualquer parte de um comando a ser executado tiver origem em uma fonte externa, valide cuidadosamente o comando para execuo. Da mesma forma, o aplicativo AIR deve validar quaisquer dados enviados para um processo em execuo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Comunicao com processos nativos do AIR

831

No entanto, a validao de entrada pode ser difcil. Para evitar problemas, o ideal escrever um aplicativo nativo (ex: arquivo EXE do Windows) que possui a API especfica. Estas APIs devem processar s aqueles comandos definidos pelo aplicativo. Por exemplo, o aplicativo pode aceitar somente um conjunto limitado de instrues por meio de fluxo de entrada padro. O AIR no Windows no permite que voc execute arquivos do tipo .bat diretamente. O aplicativo interpretador de comandos (cmd.exe) executa os arquivos .bat do Windows. Ao chamar um arquivo .bat, este aplicativo de comando pode interpretar argumentos enviados ao comando como, por exemplo, aplicativos adicionais a serem executados. Uma injeo maliciosa de caracteres adicionais na string de argumento pode fazer com que o cmd.exe execute um aplicativo no seguro e que pode causar danos. Por exemplo, sem a validao apropriada de dados, seu aplicativo AIR pode fazer uma chamada para meuBat.bat meusParametros c:/evil.exe. O aplicativo de comando iniciaria o aplicativo evil.exe alm de executar o arquivo de lote.

ltima atualizao em 29/3/2011

832

Captulo 45: Uso da API externa

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A API externa do ActionScript 3.0 (flash.external.ExternalInterface) permite a comunicao direta entre o ActionScript e o aplicativo de continer no qual o Adobe Flash Player est sendo executado. Existem diversas situaes nas quais voc poder optar por usar a API externa como, por exemplo, ao criar a interao entre um documento SWF e o JavaScript em uma pgina HTML ou ao criar um aplicativo de rea de trabalho que usa o Flash Player para exibir um arquivo SWF. Voc pode utilizar a API externa para interagir com um aplicativo de continer, como transmitir dados entre o ActionScript e o JavaScript em uma pgina HTML e como estabelecer a comunicao e fazer o intercmbio de dados entre o ActionScript e um aplicativo de rea de trabalho. Algumas tarefas comuns da API externa so:

Obteno de informaes sobre o aplicativo de continer Uso do ActionScript para chamar o cdigo em um aplicativo de continer, incluindo uma pgina da Web ou um
aplicativo de rea de trabalho

Chamada do cdigo do ActionScript a partir do cdigo de um aplicativo de continer Criao de um proxy para simplificar a chamada do cdigo do ActionScript a partir de um aplicativo de continer
Nota: Esta discusso abrange apenas a comunicao entre o ActionScript em um arquivo SWF e o aplicativo de continer que inclui uma referncia ao Flash Player ou ocorrncia na qual o arquivo SWF est carregado. Qualquer outro uso do Flash Player em um aplicativo est fora do escopo desta documentao. O Flash Player foi desenvolvido para ser usado como um plug-in de navegador ou como um projetor (aplicativo dedicado). Outros ambientes de uso podem ter suporte limitado. Utilizando a API externa no AIR Como um aplicativo AIR no possui um continer externo, esta interface externa geralmente no se aplica - ou no geralmente necessria. Quando seu aplicativo AIR carrega um arquivo SWF diretamente, o cdigo do aplicativo pode se comunicar diretamente como o cdigo do ActionScript no arquivo SWF (sujeito a restries de caixa de proteo de segurana). No entanto, quando seu aplicativo AIR carrega um arquivo SWF utilizando uma pgina HTML em um objeto HTMLLoader ( ou um componente HTML no Flex) o objeto HTMLLoader serve como o continer externo. Portanto, voc pode utilizar a interface externa para estabelecer comunicao entre o cdigo ActionScript no SWF carregado e o cdigo JavaScript na pgina HTML carregado no HTMLLoader.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API externa

833

Noes bsicas de uso da API externa

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Embora em alguns casos um arquivo SWF possa funcionar sozinho (por exemplo, se voc usar o Adobe Flash Professional para criar um projetor SWF), na maioria dos casos, o aplicativo SWF funciona como elemento dentro de outro aplicativo. Normalmente, o continer que inclui o SWF um arquivo HTML; um arquivo SWF usado, com menos freqncia, em toda ou parte da interface de usurio de um aplicativo de rea de trabalho. medida que voc trabalha em aplicativos mais avanados, talvez precise configurar a comunicao entre o arquivo SWF e o aplicativo de continer. Por exemplo, uma pgina da Web normalmente exibe texto ou outras informaes em HTML e inclui um arquivo SWF para exibir contedo visual dinmico, como um grfico ou vdeo. Nesse caso, talvez seja til especificar que, quando os usurios clicam em um boto na pgina da Web, alguma coisa deve mudar no arquivo SWF. O ActionScript contm um mecanismo, conhecido como API externa, que facilita esse tipo de comunicao entre o ActionScript em um arquivo SWF e outro cdigo no aplicativo de continer. Conceitos e termos importantes A lista de referncia a seguir contm termos importantes relevantes a este recurso:
Continer ActiveX Um aplicativo de continer (no um navegador da Web) que inclui uma ocorrncia do controle

ActiveX do Flash Player para exibir o contedo do SWF no aplicativo.

Aplicativo de continer O aplicativo no qual o Flash Player est executando o arquivo SWF, como um navegador da Web e a pgina HTML que inclui o contedo do Flash Player. Projetor Um arquivo executvel que inclui contedo SWF e uma verso incorporada do Flash Player. Voc pode criar um arquivo de projetor usando o Flash Professional ou o Flash Player independente. Os projetores normalmente so usados para distribuir arquivos SWF por CD-ROM ou em situaes similares onde o tamanho do download no um problema e o autor do SWF quer garantir que o usurio possa executar o arquivo SWF, independentemente da instalao do Flash Player no computador do usurio. Proxy Um aplicativo ou cdigo mediador que chama o cdigo de um aplicativo (o aplicativo externo) em nome de outro aplicativo (o aplicativo de chamada) e retorna valores para o aplicativo de chamada. Um proxy pode ser usado por vrios motivos, como:

Para simplificar o processo de chamada de funes externas, convertendo as chamadas de funes nativas do
aplicativo de chamada no formato reconhecido pelo aplicativo externo.

Para obter uma soluo alternativa para segurana ou outras restries que impedem a comunicao direta do
chamador com o aplicativo externo.
Serializar Converter valores de objetos ou dados em um formato que pode ser usado para transmitir os valores em

mensagens entre dois sistemas de programao, como via Internet ou entre dois aplicativos diferentes em execuo em um nico computador. Trabalho por meio de exemplos Muitos exemplos de cdigo fornecidos so pequenas listagens apenas para demonstrao, no exemplos de trabalho completos ou cdigo que verifica valores. Como o uso da API externa requer (por definio) a gravao do cdigo do ActionScript, bem como do cdigo de um aplicativo de continer, o teste dos exemplos envolve a criao de um continer (por exemplo, uma pgina da Web que contm o arquivo SWF) e o uso das listagens de cdigo para interagir com o continer.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API externa

834

Para testar um exemplo de comunicao entre ActionScript e JavaScript: 1 Crie um novo documento usando o Flash Professional e salve-o em seu computador.
2 No menu principal, escolha Arquivo > Configuraes de publicao. 3 Na caixa de dilogo Configuraes de publicao, na aba Formatos, verifique se as caixas de seleo Flash e HTML

esto marcadas.
4 Clique no boto Publicar. Isso gera um arquivo SWF e um arquivo HTML na mesma pasta, com o mesmo nome

usado para salvar o documento. Clique em OK para fechar a caixa de dilogo Configuraes de publicao.
5 Desmarque a caixa de seleo HTML. Agora que a pgina HTML foi gerada, voc ir modific-la para adicionar o

cdigo do JavaScript apropriado. Desmarcar a caixa de seleo HTML garante que, aps a modificao da pgina HTML, o Flash no substituir as alteraes por uma nova pgina HTML ao publicar o arquivo SWF.
6 Clique em OK para fechar a caixa de dilogo Configuraes de publicao. 7 Com um aplicativo de editor de texto ou HTML, abra o arquivo HTML criado pelo Flash ao publicar o arquivo

SWF. No cdigo-fonte HTML, adicione as tags script de abertura e fechamento e copie-as no cdigo do JavaScript na listagem de cdigo de exemplo:
<script> // add the sample JavaScript code here </script>

8 Salve o arquivo HTML e volte ao Flash. 9 Selecione o quadro-chave no Quadro 1 da Linha de tempo e abra o painel Aes. 10 Copie a listagem de cdigo do ActionScript no painel Script. 11 No menu principal, escolha Arquivo > Publicar para atualizar o arquivo SWF com as alteraes feitas. 12 Usando um navegador da Web, abra a pgina HTML editada para visualiz-la e testar a comunicao entre o

ActionScript e a pgina HTML. Para testar um exemplo de comunicao de continer entre ActionScript e ActiveX: 1 Crie um novo documento usando o Flash Professional e salve-o em seu computador. Salve-o na pasta onde o aplicativo de continer dever localizar o arquivo SWF.
2 No menu principal, escolha Arquivo > Configuraes de publicao. 3 Na caixa de dilogo Configuraes de publicao, na aba Formatos, verifique se apenas a caixa de seleo Flash est

marcada.
4 No campo Arquivo prximo caixa de seleo Flash, clique no cone de pasta para selecionar a pasta na qual o

arquivo SWF ser publicado. Uma vez definido o local do arquivo SWF, voc pode, por exemplo, manter o documento em uma determinada pasta e colocar o arquivo SWF publicado em outra pasta, como a que contm o cdigo-fonte do aplicativo de continer.
5 Selecione o quadro-chave no Quadro 1 da Linha de tempo e abra o painel Aes. 6 Copie o cdigo do ActionScript do exemplo no painel Script. 7 No menu principal, escolha Arquivo > Publicar para republicar o arquivo SWF. 8 Crie e execute o aplicativo de continer para testar a comunicao entre o ActionScript e o aplicativo de continer.

Para ver exemplos completos do uso da API externa para se comunicar com uma pgina HTML e um aplicativo de desktop C#, consulte os seguintes tpicos:

Exemplo de API externa: comunicaa entre ActionScript e JavaScript em um navegador da Web na pgina 840

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API externa

835

Exemplo de API externa: comunicao entre ActionScript e um aplicativo de desktop que usa o controle de
ActiveX na pgina 846 Estes exemplos incluem o cdigo completo, inclusive o cdigo de verificao de erro do ActionScript e do continer, que deve ser usado ao programar o cdigo com a API externa. Para obter outro exemplo completo de uso da API externa, consulte o exemplo da classe ExternalInterface na Referncia do ActionScript 3.0.

Requisitos e vantagens da API externa

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A API externa a parte do ActionScript que fornece um mecanismo para comunicao entre o ActionScript e o cdigo em execuo em um aplicativo externo que est agindo como continer para o Flash Player (normalmente um navegador da Web ou aplicativo de projetor dedicado). No ActionScript 3.0, a funcionalidade da API externa fornecida pela classe ExternalInterface. Nas verses do Flash Player anteriores ao Flash Player 8, a ao fscommand() era usada para estabelecer a comunicao com o aplicativo de continer. A classe ExternalInterface a substituio para fscommand(). Nota: Se precisar usar a funo fscommand() antiga (por exemplo, para manter a compatibilidade com aplicativos mais antigos ou para interagir com um aplicativo de continer SWF de terceiros ou o Flash Player), ela ainda est disponvel como uma funo no pacote flash.system. A classe ExternalInterface um subsistema que permite a comunicao fcil entre ActionScript e Flash Player com JavaScript em uma pgina HTML ou com qualquer aplicativo de rea de trabalho que inclui uma ocorrncia do Flash Player. A classe ExternalInterface s est disponvel nas seguintes condies:

Em todas as verses compatveis do Internet Explorer para Windows (5.0 e posterior) Em um aplicativo de continer como um aplicativo de rea de trabalho que usa uma ocorrncia do controle ActiveX
do Flash Player

Em qualquer navegador compatvel com a interface NPRuntime, que no momento inclui o Firefox 1.0 e posterior,
o Mozilla 1.7.5 e posterior, o Netscape 8.0 e posterior e o Safari 1.3 e posterior. Em todas as outras situaes (como a execuo em um player dedicado), a propriedade ExternalInterface.available retorna false. No ActionScript, possvel chamar uma funo JavaScript na pgina HTML. A API externa tem uma funcionalidade aprimorada em comparao com fscommand():

possvel usar qualquer funo JavaScript, no apenas as funes que podem ser usadas com a funo
fscommand().

possvel transmitir qualquer nmero de argumentos, com qualquer nome; voc no fica limitado a transmitir um
comando e um nico argumento de string. Desse modo, a API externa tem muito mais flexibilidade do que fscommand().

possvel transmitir vrios tipos de dados (como booleano, nmero e string); voc no est limitado aos
parmetros String.

Voc pode receber o valor de uma chamada e esse valor retorna imediatamente para o ActionScript (como o valor
de retorno da chamada feita).

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API externa

836

Importante: Se o nome dado ocorrncia do Flash Player em uma pgina HTML (atributo id da tag object) incluir um hfen (-) ou outros caracteres que so definidos como operadores no JavaScript (como +, *, /, \, ., e assim por diante), as chamadas ExternalInterface do ActionScript no vo funcionar quando a pgina da Web do continer visualizada no Internet Explorer. Alm disso, se as tags HTML que definem a ocorrncia do Flash Player (as tags object e embed) estiverem em uma tag HTML form, as chamadas ExternalInterface do ActionScript no vo funcionar.

Uso da classe ExternalInterface

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A comunicao entre o ActionScript e o aplicativo de continer pode ser realizada de duas formas: o ActionScript pode chamar o cdigo (como uma funo do JavaScript) definido no continer ou o cdigo do continer pode chamar uma funo do ActionScript que foi designada como chamvel. De qualquer modo, as informaes podem ser enviadas para o cdigo que est sendo chamado e os resultados podem ser retornados para o cdigo que est fazendo a chamada. Para facilitar essa comunicao, a classe ExternalInterface inclui duas propriedades estticas e dois mtodos estticos. Esses mtodos e propriedades so usados para obter informaes sobre a conexo da interface externa, para executar o cdigo no continer do ActionScript e para disponibilizar as funes do ActionScript para serem chamadas pelo continer.

Obteno de informaes sobre o continer externo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A propriedade ExternalInterface.available indica se o Flash Player atual est em um continer que oferece uma interface externa. Se a interface externa estiver disponvel, esta propriedade ser true; caso contrrio, ela ser false. Antes de usar qualquer outra funcionalidade na classe ExternalInterface, sempre verifique se o continer atual oferece suporte comunicao da interface externa do seguinte modo:
if (ExternalInterface.available) { // Perform ExternalInterface method calls here. }

Nota: A propriedade ExternalInterface.available informa se o continer atual um tipo compatvel com a conectividade de ExternalInterface. Ela no informa se o JavaScript est ativado no navegador atual. A propriedade ExternalInterface.objectID permite determinar o identificador exclusivo da ocorrncia do Flash Player (especificamente, o atributo id da tag object no Internet Explorer ou o atributo name da tag embed nos navegadores que usam a interface NPRuntime). Essa ID exclusiva representa o documenta SWF atual no navegador e pode ser usada para fazer referncia ao documento SWF (por exemplo, ao chamar uma funo do JavaScript em uma pgina HTML de continer). Quando o continer do Flash Player no um navegador da Web, essa propriedade null.

Chamada do cdigo externo a partir do ActionScript

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O mtodo ExternalInterface.call() executa o cdigo no aplicativo de continer. Ele requer pelo menos um parmetro, uma string que contm o nome da funo a ser chamada no aplicativo de continer. Quaisquer parmetros adicionais transmitidos para o mtodo ExternalInterface.call() so transmitidos ao longo do continer como parmetros da chamada de funo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API externa

837

// calls the external function "addNumbers" // passing two parameters, and assigning that function's result // to the variable "result" var param1:uint = 3; var param2:uint = 7; var result:uint = ExternalInterface.call("addNumbers", param1, param2);

Se o continer for uma pgina HTML, esse mtodo invocar a funo do JavaScript com o nome especificado, que deve ser definido em um elemento script na pgina HTML de continer. O valor de retorno da funo do JavaScript transmitido novamente para o ActionScript.
<script language="JavaScript"> // adds two numbers, and sends the result back to ActionScript function addNumbers(num1, num2) { return (num1 + num2); } </script>

Se o continer for algum outro continer ActiveX, esse mtodo far com que o controle ActiveX do Flash Player envie o evento FlashCall. O nome da funo e os parmetros especificados so serializados em uma string XML pelo Flash Player. O continer pode acessar essas informaes na propriedade request do objeto de evento e us-las para determinar como seu prprio cdigo deve ser executado. Para retornar um valor para o ActionScript, o cdigo do continer chama o mtodo SetReturnValue() do objeto ActiveX, transmitindo o resultado (serializado em uma string XML) como um parmetro desse mtodo. Para obter mais informaes sobre o formato XML usado para essa comunicao, consulte O formato XML da API externa na pgina 838. Independentemente de o continer ser um navegador da Web ou outro continer ActiveX, se a chamada falhar ou o mtodo do continer no especificar um valor de retorno, null ser retornado. O mtodo ExternalInterface.call() lanar uma exceo SecurityError se o ambiente includo pertencer a uma caixa de proteo de segurana para a qual o cdigo de chamada no tem acesso. Para solucionar isso temporariamente, defina um valor apropriado para allowScriptAccess no ambiente includo. Por exemplo, para alterar o valor de allowScriptAccess em uma pgina HTML, edite o atributo adequado nas tags object e embed.

Chamada do cdigo do ActionScript a partir do continer

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Um continer s pode chamar o cdigo do ActionScript que esteja em uma funo - nenhum outro cdigo do ActionScript pode ser chamado por um continer. Para chamar um funo do ActionScript a partir do aplicativo de continer, voc deve fazer duas coisas: registrar a funo com a classe ExternalInterface e cham-la a partir do cdigo do continer. Primeiro, voc deve registrar a funo do ActionScript para indicar se ela deve ser disponibilizada para o continer. Use o mtodo ExternalInterface.addCallback() do seguinte modo:
function callMe(name:String):String { return "busy signal"; } ExternalInterface.addCallback("myFunction", callMe);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API externa

838

O mtodo addCallback() tem dois parmetros. O primeiro, um nome de funo como String, o nome pelo qual a funo ser reconhecida pelo continer. O segundo parmetro a funo real do ActionScript que ser executada quando o continer chamar o nome de funo definido. Como esses nomes so diferentes, voc pode especificar um nome de funo que ser usado pelo continer, mesmo se a funo real do ActionScript tiver um nome diferente. Isso especialmente til se o nome da funo no for conhecido - por exemplo, se uma funo annima for especificada ou se a funo a ser chamada for determinada em tempo de execuo. Depois que uma funo do ActionScript registrada com a classe ExternalInterface, o continer pode realmente chamar a funo. O modo como isso feito varia de acordo com o tipo de continer. Por exemplo, no cdigo do JavaScript em um navegador da Web, a funo do ActionScript chamada com o nome de funo registrado, visto que este um mtodo do objeto de navegador do Flash Player (isto , um mtodo do objeto JavaScript que representa a tag object ou embed). Em outras palavras, os parmetros so transmitidos e um resultado retornado como uma funo local que est sendo chamada.
<script language="JavaScript"> // callResult gets the value "busy signal" var callResult = flashObject.myFunction("my name"); </script> ... <object id="flashObject"...> ... <embed name="flashObject".../> </object>

Como alternativa, ao chamar uma funo do ActionScript em um arquivo SWF em execuo em um aplicativo de rea de trabalho, o nome de funo registrado e os parmetros devem ser serializados em uma string XML. Em seguida, a chamada realmente feita para o mtodo CallFunction() do controle ActiveX com a string XML como parmetro. Para obter mais informaes sobre o formato XML usado para essa comunicao, consulte O formato XML da API externa na pgina 838. De qualquer modo, o valor de retorno da funo do ActionScript transmitido novamente para o cdigo do continer, diretamente como um valor quando o chamador o cdigo JavaScript em um navegador ou serializado com uma string XML quando o chamador um continer ActiveX.

O formato XML da API externa

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A comunicao entre o ActionScript e um aplicativo que hospeda o controle ActiveX do Shockwave Flash usa um formato XML especfico para codificar chamadas e valores de funo. Duas partes do formato XML so usadas pela API externa. Um formato usado para representar chamadas de funo. Outro formato usado para representar valores individuais; esse formato usado para parmetros em funes e em valores de retorno de funo. O formato XML das chamadas de funo usado para chamadas feitas e recebidas pelo ActionScript. Para uma chamada de funo a partir do ActionScript, o Flash Player transmite o XML para o continer; para uma chamada a partir do continer, o Flash Player espera que o aplicativo de continer o transmita como uma string XML nesse formato. O fragmento XML a seguir mostra o exemplo de uma chamada de funo em formato XML:
<invoke name="functionName" returntype="xml"> <arguments> ... (individual argument values) </arguments> </invoke>

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API externa

839

O n raiz o n invoke. Ele tem dois atributos: name indica o nome da funo a ser chamada e returntype sempre xml. Se a chamada de funo incluir parmetros, o n invoke ter um n filho arguments, cujos ns filho sero os valores de parmetro formatados que usam o formato de valor individual explicado a seguir. Os valores individuais, incluindo parmetros de funo e valores de retorno de funo, usam um esquema de formatao que inclui informaes sobre o tipo de dados alm dos valores reais. A tabela a seguir lista as classes do ActionScript e o formato XML usado para codificar valores desse tipo de dados:
Classe/valor do ActionScript null Booleano true Booleano false String Nmero, int, uint Array (os elementos podem ser de tipos diferentes) Classe/valor do C# Formato Comentrios

null bool true bool false string nico, duplo, int, uint Uma coleo que permite elementos de tipos diferentes, como ArrayList ou object[]

<null/> <true/> <false/> <string>valor da string</string>

<number>27.5</number> <number>-12</number> <array> <property id="0"> <number>27.5</number> </property> <property id="1"> <string>Hello there!</string> </property> ... </array> <object> <property id="name"> <string>John Doe</string> </property> <property id="age"> <string>33</string> </property> ... </object> <null/> or <object></object>

O n property define elementos individuais e o atributo id o ndice numrico baseado em zero.

Objeto

Um dicionrio com chaves de string e valores de objeto, como HashTable com chaves de string

O n property define propriedades individuais e o atributo id o nome da propriedade (uma string).

Outras classes internas ou personalizadas

O ActionScript codifica outros objetos como nulos ou como um objeto vazio. De qualquer modo, os valores de propriedade so perdidos.

Nota: Por exemplo, esta tabela mostra as classes C# equivalentes alm das classes do ActionScript; no entanto, a API externa pode ser usada para comunicao com qualquer linguagem de programao ou tempo de execuo compatvel com os controles ActiveX, no se limitando aos aplicativos C#. Quando est criando seus prprios aplicativos usando a API externa com um aplicativo de continer ActiveX, voc provavelmente achar til gravar um proxy que ir converter as chamadas de funo nativas no formato XML serializado. Para obter um exemplo de uma classe de proxy gravada em C#, consulte Dentro da classe ExternalInterfaceProxy na pgina 850.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API externa

840

Exemplo de API externa: comunicaa entre ActionScript e JavaScript em um navegador da Web

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Este aplicativo de amostra demonstra tcnicas adequadas de comunicao entre o ActionScript e o JavaScript em um navegador da Web, no mbito de um aplicativo de mensagem instantnea que permite que uma pessoa converse consigo mesma (da o nome do aplicativo: Introvert IM). As mensagens so enviadas entre um formulrio HTML na pgina da Web e uma interface SWF usando a API externa. As tcnicas demonstradas neste exemplo incluem as seguintes:

Incio adequado da comunicao, verificando se o navegador est preparado para se comunicar antes de estabelecer
uma comunicao

Verificao da compatibilidade entre o continer e a API externa Chamada das funes do JavaScript a partir do ActionScript, transmitindo parmetros e recebendo valores em
resposta

Disponibilizao dos mtodos do ActionScript para serem chamados pelo JavaScript, e realizao dessas chamadas
Para obter os arquivos do aplicativo para este exemplo, consulte www.adobe.com/go/learn_programmingAS3samples_flash_br. Os arquivos do aplicativo Introvert IM esto localizados na pasta Amostras/IntrovertIM_HTML. O aplicativo consiste nos seguintes arquivos:
Arquivo IntrovertIMApp.fla ou IntrovertIMApp.mxml com/example/programmingas3/introvertIM/IMManager.as A classe que estabelece e gerencia a comunicao entre o ActionScript e o continer. Tipo de evento personalizado, enviado pela classe IMManager quando uma mensagem recebida do continer. Enumerao cujos valores representam diferentes status de "disponibilidade" que podem ser selecionados no aplicativo. A pgina HTML do aplicativo para Flash (html-flash/IntrovertIMApp.html) ou o modelo usado para criar a pgina HTML do continer do aplicativo para Adobe Flex (html-template/index.template.html). Esse arquivo contm todas as funes do JavaScript que fazem parte do continer do aplicativo. Descrio O arquivo de aplicativo principal no Flash (FLA) ou Flex (MXML).

com/example/programmingas3/introvertIM/IMMessageEvent.as

com/example/programmingas3/introvertIM/IMStatus.as

html-flash/IntrovertIMApp.html ou html-template/index.template.html

Preparao da comunicao entre o ActionScript e o navegador

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A API externa normalmente usada para permitir a comunicao dos aplicativos do ActionScript com um navegador da Web. Usando a API externa, os mtodos do ActionScript podem chamar o cdigo gravado em JavaScript e viceversa. Devido complexidade dos navegadores e ao modo de renderizao interna das pginas, no possvel garantir que um documento SWF registrar seus retornos de chamada antes da execuo do primeiro JavaScript na pgina HTML. Por esse motivo, antes de chamar funes no documento SWF a partir do JavaScript, o documento SWF sempre deve chamar a pgina HTML para notificar se o documento SWF est pronto para aceitar conexes.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API externa

841

Por exemplo, por meio de uma srie de etapas realizadas pela classe IMManager, o Introvert IM determina se o navegador est pronto para comunicao e prepara o arquivo SWF para comunicao. A primeira etapa, determinar quando o navegador est pronto para comunicao, acontece no construtor IMManager do seguinte modo:
public function IMManager(initialStatus:IMStatus) { _status = initialStatus; // Check if the container is able to use the external API. if (ExternalInterface.available) { try { // This calls the isContainerReady() method, which in turn calls // the container to see if Flash Player has loaded and the container // is ready to receive calls from the SWF. var containerReady:Boolean = isContainerReady(); if (containerReady) { // If the container is ready, register the SWF's functions. setupCallbacks(); } else { // If the container is not ready, set up a Timer to call the // container at 100ms intervals. Once the container responds that // it's ready, the timer will be stopped. var readyTimer:Timer = new Timer(100); readyTimer.addEventListener(TimerEvent.TIMER, timerHandler); readyTimer.start(); } } ... } else { trace("External interface is not available for this container."); } }

Primeiro, o cdigo verifica se a API externa est realmente disponvel no continer atual usando a propriedade ExternalInterface.available. Se estiver, o processo de configurao da comunicao iniciado. Como excees de segurana e outros erros podem ocorrer ao tentar se comunicar com um aplicativo externo, o cdigo fica entre um bloco try (os blocos catch correspondentes foram omitidos da listagem para facilitar). O cdigo a seguir chama o mtodo isContainerReady(), listado aqui:
private function isContainerReady():Boolean { var result:Boolean = ExternalInterface.call("isReady"); return result; }

O mtodo isContainerReady(), por sua vez, usa o mtodo ExternalInterface.call() para chamar a funo isReady() do JavaScript do seguinte modo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API externa

842

<script language="JavaScript"> <!-// ------- Private vars ------var jsReady = false; ... // ------- functions called by ActionScript ------// called to check if the page has initialized and JavaScript is available function isReady() { return jsReady; } ... // called by the onload event of the <body> tag function pageInit() { // Record that JavaScript is ready to go. jsReady = true; } ... //--> </script>

A funo isReady() simplesmente retorna o valor da varivel jsReady. Essa varivel inicialmente false; assim que o evento onload da pgina da Web acionado, o valor da varivel muda para true. Em outras palavras, se o ActionScript chamar a funo isReady() antes que a pgina seja carregada, o JavaScript retornar false para ExternalInterface.call("isReady") e, conseqentemente, o mtodo isContainerReady() do ActionScript retornar false. Assim que a pgina for carregada, a funo isReady() do JavaScript retornar true, de modo que o mtodo isContainerReady() do ActionScript tambm retornar true. De volta ao construtor IMManager, uma de duas coisas acontecem dependendo da disponibilidade do continer. Se isContainerReady() retornar true, o cdigo simplesmente chamar o mtodo setupCallbacks(), que concluir o processo de configurao da comunicao com o JavaScript. Por outro lado, se isContainerReady() retornar false, o processo ser basicamente suspenso. Um objeto Timer criado e suspenso para chamar o mtodo timerHandler() a cada 100 milissegundos do seguinte modo:
private function timerHandler(event:TimerEvent):void { // Check if the container is now ready. var isReady:Boolean = isContainerReady(); if (isReady) { // If the container has become ready, we don't need to check anymore, // so stop the timer. Timer(event.target).stop(); // Set up the ActionScript methods that will be available to be // called by the container. setupCallbacks(); } }

Sempre que chamado, o mtodo timerHandler() verifica mais uma vez o resultado do mtodo isContainerReady(). Assim que o continer inicializado, esse mtodo retorna true. Em seguida, o cdigo pra o objeto Timer e chama o mtodo setupCallbacks() para finalizar o processo de configurao da comunicao com o navegador.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API externa

843

Exposio dos mtodos do ActionScript ao JavaScript

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Conforme mostrou o exemplo anterior, assim que o cdigo determina que o navegador est pronto, o mtodo setupCallbacks() chamado. Esse mtodo prepara o ActionScript para receber chamadas do JavaScript, conforme mostrado a seguir:
private function setupCallbacks():void { // Register the SWF client functions with the container ExternalInterface.addCallback("newMessage", newMessage); ExternalInterface.addCallback("getStatus", getStatus); // Notify the container that the SWF is ready to be called. ExternalInterface.call("setSWFIsReady"); }

O mtodo setCallBacks() termina a tarefa de preparao de comunicao com o continer chamando ExternalInterface.addCallback() para registrar os dois mtodos que estaro disponveis para serem chamados a partir do JavaScript. Neste cdigo, o primeiro parmetro - o nome pelo qual o mtodo conhecido pelo JavaScript ("newMessage" e "getStatus") - igual ao nome do mtodo no ActionScript. Neste caso, no seria til usar nomes diferentes, de modo que o mesmo nome foi reutilizado para simplificar. Finalmente, o mtodo ExternalInterface.call() usado para chamar a funo setSWFIsReady() do JavaScript, que avisa ao continer que as funes do ActionScript foram registradas.

Comunicao do ActionScript com o navegador

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O aplicativo Introvert IM demonstra diversos exemplos de chamada das funes do JavaScript na pgina do continer. No caso mais simples (um exemplo do mtodo setupCallbacks()), a funo setSWFIsReady() do JavaScript chamada sem transmitir nenhum parmetro nem receber um valor de retorno:
ExternalInterface.call("setSWFIsReady");

Em outro exemplo do mtodo isContainerReady(), o ActionScript chama a funo isReady() e recebe um valor booleano em resposta:
var result:Boolean = ExternalInterface.call("isReady");

Tambm possvel transmitir parmetros para as funes do JavaScript usando a API externa. Por exemplo, considere o mtodo sendMessage() da classe IMManager, que chamado quando o usurio est enviando uma nova mensagem para seu "parceiro de conversa":
public function sendMessage(message:String):void { ExternalInterface.call("newMessage", message); }

Novamente, ExternalInterface.call() usado para chamar a funo designada do JavaScript, notificando o navegador sobre a nova mensagem. Alm disso, a mensagem propriamente dita transmitida como um parmetro adicional para ExternalInterface.call() e, conseqentemente, transmitida como parmetro para a funo newMessage() do JavaScript.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API externa

844

Chamada do cdigo do ActionScript a partir do JavaScript

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A comunicao uma rua de mo dupla e o aplicativo Introvert IM no foge regra. O cliente IM do Flash Player no s chama o JavaScript para enviar mensagens, mas o formulrio HTML chama o cdigo do JavaScript para enviar mensagens e solicitar informaes do arquivo SWF tambm. Por exemplo, quando o arquivo SWF avisa o continer que terminou de estabelecer o contato e est pronto para se comunicar, a primeira coisa que o navegador faz chamar o mtodo getStatus() da classe IMManager para recuperar o status de disponibilidade inicial do usurio a partir do cliente IM do SWF. Isso feito na pgina da Web, na funo updateStatus(), do seguinte modo:
<script language="JavaScript"> ... function updateStatus() { if (swfReady) { var currentStatus = getSWF("IntrovertIMApp").getStatus(); document.forms["imForm"].status.value = currentStatus; } } ... </script>

O cdigo verifica o valor da varivel swfReady, que controla se o arquivo SWF notificou o navegador sobre o registro dos mtodos com a classe ExternalInterface. Se o arquivo SWF estiver pronto para receber comunicao, a prxima linha (var currentStatus = ...) realmente chamar o mtodo getStatus() na classe IMManager. Trs coisas acontecem nesta linha de cdigo:

A funo getSWF() do JavaScript chamada, retornando uma referncia ao objeto do JavaScript que representa o
arquivo SWF. O parmetro transmitido para getSWF() determina qual objeto de navegador retornado caso haja mais de um arquivo SWF em uma pgina HTML. O valor transmitido para esse parmetro deve corresponder ao atributo id da tag object e ao atributo name da tag embed usados para incluir o arquivo SWF.

Usando a referncia ao arquivo SWF, o mtodo getStatus() chamado embora seja um mtodo do objeto SWF.
Nesse caso, o nome da funo getStatus usado porque esse o nome com o qual a funo do ActionScript foi registrada com ExternalInterface.addCallback().

O mtodo getStatus() do ActionScript retorna um valor e esse valor atribudo varivel currentStatus, que
atribuda como contedo (a propriedade value) do campo de texto status. Nota: Se estiver seguindo o cdigo, voc provavelmente percebeu que, no cdigo-fonte da funo updateStatus(), a linha de cdigo que chama a funo getSWF() realmente escrita do seguinte modo: var currentStatus = getSWF("${application}").getStatus(). O texto ${application} um alocador de espao contido no modelo da pgina HTML. Quando o Adobe Flash Builder gera a pgina HTML real para o aplicativo, esse alocador substitudo pelo mesmo texto usado como o atributo id da tag object e o atributo name da tag embed (que corresponde a IntrovertIMApp no exemplo). Este o valor esperado pela funo getSWF(). A funo sendMessage() do JavaScript demonstra a transmisso de um parmetro como uma funo do ActionScript. (sendMessage() afuno que foi chamada quando o usurio pressionou o boto Enviar na pgina HTML.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API externa

845

<script language="JavaScript"> ... function sendMessage(message) { if (swfReady) { ... getSWF("IntrovertIMApp").newMessage(message); } } ... </script>

O mtodo newMessage() do ActionScript espera um parmetro, de modo que a varivel message do JavaScript transmitida para o ActionScript como um parmetro na chamada do mtodo newMessage() no cdigo do JavaScript.

Deteco do tipo de navegador

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Devido s diferenas de acesso ao contedo dos navegadores, importante sempre usar o JavaScript para detectar qual navegados est sendo executado pelo usurio e para acessar o filme de acordo com a sintaxe especfica do navegador, usando o objeto de janela ou documento, como mostra a funo getSWF() do JavaScript neste exemplo:
<script language="JavaScript"> ... function getSWF(movieName) { if (navigator.appName.indexOf("Microsoft") != -1) { return window[movieName]; } else { return document[movieName]; } } ... </script>

Se o seu script no detectar o tipo de navegador do usurio, o usurio poder observar um comportamento inesperado ao reproduzir arquivos SWF em um continer HTML.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API externa

846

Exemplo de API externa: comunicao entre ActionScript e um aplicativo de desktop que usa o controle de ActiveX
Flash Player 9 e posterior Este exemplo demonstra o uso da API externa para comunicao entre o ActionScript e um aplicativo de rea de trabalho que usa o controle ActiveX. O exemplo reutiliza o aplicativo Introvert IM, incluindo o cdigo do ActionScript e o mesmo arquivo SWF, e, assim, no descreve o uso da API externa no ActionScript. Para entender esse exemplo, til estar familiarizado com o exemplo anterior. O aplicativo de rea de trabalho desse exemplo gravado em C# com o Microsoft Visual Studio .NET. O foco da discusso so as tcnicas especficas para trabalhar com a API externa usando o controle ActiveX. Este exemplo demonstra o seguinte:

Chamada das funes do ActionScript a partir de um aplicativo de rea de trabalho que hospeda o controle ActiveX
do Flash Player

Recebimento das chamadas de funo do ActionScript e processamento dessas chamadas em um continer ActiveX Uso de uma classe de proxy para ocultar os detalhes do formato XML usado pelo Flash Player para as mensagens
enviadas para um continer ActiveX Para obter os arquivos do aplicativo para este exemplo, consulte www.adobe.com/go/learn_programmingAS3samples_flash_br. Os arquivos do aplicativo Introvert IM em C# esto localizados na pasta Amostras/IntrovertIM_CSharp. O aplicativo consiste nos seguintes arquivos:
Arquivo AppForm.cs bin/Debug/IntrovertIMApp.swf ExternalInterfaceProxy/ExternalInterfaceProxy.cs Descrio O arquivo de aplicativo principal com a interface do Windows Forms em C#. O arquivo SWF carregado pelo aplicativo. A classe que serve como envoltrio no controle ActiveX para comunicao da interface externa. Ela fornece mecanismos para chamar e receber chamadas a partir do ActionScript. A classe que converte as mensagens em formato XML do Flash Player em objetos do .NET. Esse arquivo define dois tipos de C# (classes): um delegado personalizado e uma classe de argumentos de evento, que so usados pela classe ExternalInterfaceProxy para notificar o ouvinte sobre uma chamada de funo do ActionScript. Essa classe um objeto de valor que representa uma chamada de funo do ActionScript para o continer ActiveX, com propriedades para o nome da funo e os parmetros. O arquivo SWF carregado pelo aplicativo. Assemblies envoltrios criados pelo Visual Studio .NET que so necessrios para acessar o controle ActiveX do Flash Player (Adobe Shockwave Flash) a partir do cdigo gerenciado.

ExternalInterfaceProxy/ExternalInterfaceSerializer.cs

ExternalInterfaceProxy/ExternalInterfaceEventArgs.cs

ExternalInterfaceProxy/ExternalInterfaceCall.cs

bin/Debug/IntrovertIMApp.swf obj/AxInterop.ShockwaveFlashObjects.dll, obj/Interop.ShockwaveFlashObjects.dll

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API externa

847

Viso geral do aplicativo Introvert IM em C#

Flash Player 9 e posterior Este aplicativo de exemplo representa dois programas cliente de mensagem instantnea (um no arquivo SWF e outro incorporado no Windows Forms) que se comunicam. A interface de usurio inclui uma ocorrncia do controle ActiveX do Shockwave Flash, na qual carregado o arquivo SWF que contm o cliente IM do ActionScript. A interface tambm inclui diversos campos de texto que fazem parte do cliente IM do Windows Forms: um campo para inserir mensagens (MessageText), outro que exibe a transcrio das mensagens enviadas entre os clientes (Transcript) e um terceiro (Status) que exibe o status de disponibilidade definido no cliente IM do SWF.

Incluso do controle ActiveX do Shockwave Flash

Flash Player 9 e posterior Para incluir o controle ActiveX do Shockwave Flash no seu prprio aplicativo Windows Forms, adicione-o primeiro caixa de ferramentas do Microsoft Visual Studio. Para adicionar o controle caixa de ferramentas: 1 Abra a caixa de ferramentas do Visual Studio.
2 Clique com o boto direito do mouse na seo Windows Forms no Visual Studio 2003 ou em qualquer seo no

Visual Studio 2005. No menu de contexto, selecione Adicionar/Remover Itens no Visual Studio 2003 (Escolher Itens... no Visual Studio 2005). A caixa de dilogo Personalizar caixa de ferramentas (2003)/Escolher itens da caixa de ferramentas (2005) exibida.
3 Selecione a aba Componentes COM, que lista todos os componentes COM disponveis no seu computador,

incluindo o controle ActiveX do Flash Player.

4 Navegue at Objeto do Shockwave Flash e selecione-o.

Se esse item no estiver listado, verifique se o controle ActiveX do Flash Player est instalado no seu sistema.

Noes bsicas sobre a comunicao do ActionScript com o continer ActiveX

Flash Player 9 e posterior A comunicao feita com a API externa e um aplicativo de continer ActiveX funciona como a comunicao com um navegador da Web, com uma diferena importante. Conforme descrito anteriormente, quando o ActionScript se comunica com um navegador da Web, contanto que o navegador queira, as funes so chamadas diretamente; os detalhes de como as chamadas e respostas de funo so formatadas para serem transmitidas entre o player e o navegador so ocultos. No entanto, quando a API externa usada para se comunicar com um aplicativo de continer ActiveX, o Flash Player envia mensagens (chamadas de funo e valores de retorno) ao aplicativo em um formato XML especfico e espera chamadas de funo e valores de retorno do aplicativo de continer para usar o mesmo formato XML. O desenvolvedor do aplicativo de continer ActiveX deve gravar o cdigo entendido e pode criar chamadas de funo e respostas no formato apropriado. O exemplo do Introvert IM em C# inclui um conjunto de classes que permitem evitar mensagens de formatao; em vez disso, voc pode trabalhar com tipos de dados padro ao chamar funes do ActionScript e receber chamadas de funo do ActionScript. A classe ExternalInterfaceProxy, junto com outras classes auxiliares, fornece essa funcionalidade e pode ser reutilizada em qualquer projeto .NET para facilitar a comunicao da API externa.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API externa

848

As sees de cdigo a seguir, extradas do formulrio do aplicativo principal (AppForm.cs), demonstram a interao simplificada que atingida com a classe ExternalInterfaceProxy:
public class AppForm : System.Windows.Forms.Form { ... private ExternalInterfaceProxy proxy; ... public AppForm() { ... // Register this app to receive notification when the proxy receives // a call from ActionScript. proxy = new ExternalInterfaceProxy(IntrovertIMApp); proxy.ExternalInterfaceCall += new ExternalInterfaceCallEventHandler(proxy_ExternalInterfaceCall); ... } ...

O aplicativo declara e cria uma ocorrncia de ExternalInterfaceProxy chamada proxy, transmitindo uma referncia ao controle ActiveX do Shockwave Flash que est na interface de usurio (IntrovertIMApp). Em seguida, o cdigo registra o mtodo proxy_ExternalInterfaceCall() para receber o evento ExternalInterfaceCall do proxy. Esse evento enviado pela classe ExternalInterfaceProxy quando uma chamada de funo vem do Flash Player. A inscrio nesse evento o modo como o cdigo C# recebe e responde s chamadas de funo do ActionScript. Quando uma chamada de funo vem do ActionScript, a ocorrncia de ExternalInterfaceProxy (proxy) recebe a chamada, a converte em formato XML e notifica os objetos que so ouvintes do evento ExternalInterfaceCall do proxy. No caso da classe AppForm, o mtodo proxy_ExternalInterfaceCall() manipula esse evento da seguinte forma:
/// <summary> /// Called by the proxy when an ActionScript ExternalInterface call /// is made by the SWF /// </summary> private object proxy_ExternalInterfaceCall(object sender, ExternalInterfaceCallEventArgs e) { switch (e.FunctionCall.FunctionName) { case "isReady": return isReady(); case "setSWFIsReady": setSWFIsReady(); return null; case "newMessage": newMessage((string)e.FunctionCall.Arguments[0]); return null; case "statusChange": statusChange(); return null; default: return null; } } ...

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API externa

849

O mtodo transmitido como uma ocorrncia de ExternalInterfaceCallEventArgs, chamada e neste exemplo. Esse objeto tem uma propriedade FunctionCall que uma ocorrncia da classe ExternalInterfaceCall. Uma ocorrncia de ExternalInterfaceCall um simples objeto de valor com duas propriedades. A propriedade
FunctionName contm o nome de funo especificado na instruo ExternalInterface.Call() do ActionScript.

Se algum parmetro for adicionado ao ActionScript, esses parmetros sero includos na propriedade Arguments do objeto ExternalInterfaceCall. Nesse caso, o mtodo que manipula o evento simplesmente uma instruo switch que age como um gerenciador de trfego. O valor da propriedade FunctionName (e.FunctionCall.FunctionName) determina qual mtodo da classe AppForm chamado. As ramificaes da instruo switch na listagem de cdigo anterior demonstram cenrios comuns de chamada de mtodo. Por exemplo, qualquer mtodo deve retornar um valor para o ActionScript (como a chamada do mtodo isReady()) ou deve retornar null (conforme visto nas outras chamadas de mtodo). O acesso aos parmetros transmitidos do ActionScript demonstrado na chamada do mtodo newMessage() (que transmitido como o parmetro e.FunctionCall.Arguments[0], o primeiro elemento da matriz Arguments). Chamar uma funo do ActionScript em C# usando a classe ExternalInterfaceProxy ainda mais simples do que receber uma chamada de funo a partir do ActionScript. Para chamar uma funo do ActionScript, use o mtodo Call() da ocorrncia de ExternalInterfaceProxy do seguinte modo:
/// <summary> /// Called when the "Send" button is pressed; the value in the /// MessageText text field is passed in as a parameter. /// </summary> /// <param name="message">The message to send.</param> private void sendMessage(string message) { if (swfReady) { ... // Call the newMessage function in ActionScript. proxy.Call("newMessage", message); } } ... /// <summary> /// Call the ActionScript function to get the current "availability" /// status and write it into the text field. /// </summary> private void updateStatus() { Status.Text = (string)proxy.Call("getStatus"); } ... }

Como mostra este exemplo, o mtodo Call() da classe ExternalInterfaceProxy muito parecido com seu correspondente no ActionScript, ExternalInterface.Call(). O primeiro parmetro uma string, o nome da funo a ser chamada. Todos os parmetros adicionais (no mostrados aqui) so transmitidos junto com a funo do ActionScript. Se a funo do ActionScript retornar um valor, esse valor ser retornado pelo mtodo Call() (conforme visto no exemplo anterior).

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API externa

850

Dentro da classe ExternalInterfaceProxy

Flash Player 9 e posterior Usar um envoltrio de proxy em torno do controle ActiveX talvez nem sempre seja prtico ou voc talvez queira gravar sua prpria classe de proxy (por exemplo, em uma linguagem de programao diferente ou visando uma plataforma diferente). Embora nem todos os detalhes da criao do proxy sejam explicados aqui, til entender o funcionamento da classe de proxy desse exemplo. Use o mtodo CallFunction() do controle ActiveX do Shockwave Flash para chamar uma funo do ActionScript a partir do continer ActiveX usando a API externa. Isso mostrado no trecho do mtodo Call() da classe ExternalInterfaceProxy:
// Call an ActionScript function on the SWF in "_flashControl", // which is a Shockwave Flash ActiveX control. string response = _flashControl.CallFunction(request);

Neste trecho de cdigo, _flashControl o controle ActiveX do Shockwave Flash. As chamadas de funo do ActionScript so feitas com o mtodo CallFunction(). Esse mtodo assume um parmetro (request no exemplo), que uma string que contm as instrues em formato XML, incluindo o nome da funo do ActionScript a ser chamada e os parmetros. Todos os valores retornados do ActionScript so codificados como uma string XML e enviados de volta como o valor de retorno da chamada CallFunction(). Neste exemplo, essa string XML armazenada na varivel response. O recebimento de uma chamada de funo do ActionScript um processo de vrias etapas. As chamadas de funo do ActionScript fazem com que o controle ActiveX do Shockwave Flash envie o evento FlashCall, de modo que a classe (como a classe ExternalInterfaceProxy) que deve receber as chamadas de um arquivo SWF precisa definir um manipulador para esse evento. Na classe ExternalInterfaceProxy, a funo do manipulador de eventos chamada de _flashControl_FlashCall(), e registrada para ouvir o evento no construtor da classe do seguinte modo:
private AxShockwaveFlash _flashControl; public ExternalInterfaceProxy(AxShockwaveFlash flashControl) { _flashControl = flashControl; _flashControl.FlashCall += new _IShockwaveFlashEvents_FlashCallEventHandler(_flashControl_FlashCall); } ... private void _flashControl_FlashCall(object sender, _IShockwaveFlashEvents_FlashCallEvent e) { // Use the event object's request property ("e.request") // to execute some action. ... // Return a value to ActionScript; // the returned value must first be encoded as an XML-formatted string. _flashControl.SetReturnValue(encodedResponse); }

O objeto de evento (e) tem uma propriedade request (e.request) que uma string que contm informaes sobre a chamada de funo, como o nome da funo e os parmetros, em formato XML. Essas informaes podem ser usadas pelo continer para determinar o cdigo a ser executado. Na classe ExternalInterfaceProxy, a solicitao convertida do formato XML em um objeto ExternalInterfaceCall, que fornece as mesmas informaes de forma mais acessvel. O mtodo SetReturnValue() do controle ActiveX usado para retornar um resultado de funo para o chamador do ActionScript; novamente, o parmetro resultante deve ser codificado no formato XML usado pela API externa.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Uso da API externa

851

A comunicao entre o ActionScript e um aplicativo que hospeda o controle ActiveX do Shockwave Flash usa um formato XML especfico para codificar chamadas e valores de funo. No exemplo do Introvert IM em C#, a classe ExternalInterfaceProxy possibilita isso para o cdigo no formulrio do aplicativo a ser aplicado diretamente nos valores enviados ou recebidos do ActionScript, e ignora os detalhes do formato XML usado pelo Flash Player. Para fazer isso, a classe ExternalInterfaceProxy usa os mtodos da classe ExternalInterfaceSerializer para realmente converter as mensagens XML em objetos .NET. A classe ExternalInterfaceSerializer tem quatro mtodos pblicos:

EncodeInvoke(): codifica um nome de funo e um C# ArrayList de argumentos no formato XML apropriado. EncodeResult(): codifica um valor de resultado no formato XML apropriado. DecodeInvoke(): decodifica uma chamada de funo do ActionScript. A propriedade request do objeto de evento FlashCall transmitida para o mtodo DecodeInvoke() e converte a chamada em um objeto ExternalInterfaceCall. DecodeResult(): decodifica o XML recebido em resultado da chamada de uma funo do ActionScript.

Esses mtodos codificam valores C# no formato XML da API externa e decodificam o XML em objetos C#. Para obter informaes sobre o formato XML usado pelo Flash Player, consulte O formato XML da API externa na pgina 838.

ltima atualizao em 29/3/2011

852

Captulo 46: Ambiente do sistema cliente

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Essa discusso explica como interagir com o sistema do usurio. Mostra como determinar quais recursos possuem suporte e como criar aplicativos em diversos idiomas utilizando o editor de mtodo de entrada (IME) do usurio, quando disponvel. Ele tambm mostra usurios tpicos para domnios de aplicativo.

Mais tpicos da Ajuda

flash.system.System flash.system.Capabilities

Noes bsicas do ambiente do sistema cliente

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Conforme voc cria aplicativos mais avanados, talvez ache necessrio conhecer detalhes e funes de acesso dos sistemas operacionais dos usurios. O pacote flash.system contm uma coleo de classes que permitem acessar funcionalidades de nvel de sistema:

Determinando qual aplicativo e cdigo de domnio de segurana executado no Determinar as capacidades da ocorrncia do tempo de execuo do Flash (como Flash Player ou Adobe AIR) do
usurio, como o tamanho da tela (resoluo), e se determinadas funcionalidades esto disponveis, como udio mp3

Criar sites multilnges usando o IME. Interagir com o continer do tempo de execuo do Flash (que pode ser uma pgina HTML ou um aplicativo de
continer).

Salvar informaes na rea de transferncia do usurio.

O pacote flash.system tambm inclui as classes IMEConversionMode e SecurityPanel. Essas classes contm constantes estticas que so usadas com as classes IME e Security, respectivamente. Conceitos e termos importantes A lista de referncias a seguir contm termos importantes:
Sistema operacional O programa principal executado em um computador, no qual todos os outros aplicativos so

executados, como o Microsoft Windows, Mac OS X ou Linux.

Clipboard O continer do sistema operacional onde manter texto ou itens que so copiados ou recortados e do qual os itens so colados nos aplicativos. Domnio do aplicativo Um mecanismo para separao de classes usadas em diferentes arquivos SWF, de forma que

os arquivos SWF incluam diferentes classes com o mesmo nome, as classes no so substitudas umas pelas outras.
IME (editor do mtodo de entrada) Um programa (ou ferramenta do sistema operacional) usado para inserir

caracteres ou smbolos complexos usando um teclado padro.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Ambiente do sistema cliente

853

Sistema cliente Em termos de programao, um cliente a parte de um aplicativo (ou todo o aplicativo) que executado no computador individual e usada por um nico usurio. O sistema cliente o sistema operacional subjacente no computador do usurio.

Uso da classe System

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe System contm mtodos e propriedades que permitem interagir com o sistema operacional do usurio e recuperar a utilizao de memria atual do tempo de execuo. Os mtodos e as propriedades da classe System tambm permitem ouvir eventos imeComposition, instruir o tempo de execuo do a carregar arquivos de texto externos usando a pgina de cdigo atual do usurio ou carreg-las como Unicode ou definir o contedo da rea de transferncia do usurio.

Obteno de dados sobre o sistema do usurio em tempo de execuo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Com a verificao da propriedade System.totalMemory, possvel determinar a quantidade de memria (em bytes) que o tempo de execuo do est usando no momento. Essa propriedade permite monitorar o uso de memria do monitor e otimizar os aplicativos com base em como o nvel de memria alterado. Por exemplo, se um efeito visual especfico provocar um grande aumento no uso de memria, voc poder desejar considerar modificar ou eliminar o efeito completamente. A propriedade System.ime uma referncia ao IME (Editor de mtodo de entrada) instalado. Essa propriedade permite ouvir eventos imeComposition (flash.events.IMEEvent.IME_COMPOSITION) usando o mtodo addEventListener(). A terceira propriedade na classe System useCodePage. Quando useCodePage est definido como true, o tempo de execuo do usa a pgina de cdigo tradicional do sistema operacional para carregar os arquivos de texto externos. Se definir essa propriedade como false, voc indicar ao tempo de execuo do para interpretar o arquivo externo como Unicode. Se voc definir System.useCodePage como true, lembre-se de que a pgina de cdigo tradicional do sistema operacional deve incluir os caracteres usados no arquivo de texto externo para que o texto seja exibido. Por exemplo, se voc carregar um arquivo de texto externo com caracteres chineses, esses caracteres no podero ser exibidos em um sistema que use a pgina de cdigo do Windows em ingls, pois essa pgina de cdigo no inclui caracteres chineses. Para garantir que usurios em diversas plataformas visualizem arquivos de texto externos utilizados em seu aplicativo, codifique todos os arquivos texto como Unicode e mantenha System.useCodePage definido emfalse com padro. Dessa forma, o tempo de execuo do interpreta o texto como Unicode.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Ambiente do sistema cliente

854

Salvamento de texto na rea de transferncia

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe System inclui um mtodo chamado setClipboard() que permite que o tempo de execuo do Flash defina o contedo da rea de transferncia do usurio com uma string especificada. Por motivos de segurana, no existe nenhum mtodo Security.getClipboard(), pois esse mtodo pode potencialmente permitir que sites malintencionados acessem os dados copiados recentemente na rea de transferncia do usurio. O cdigo a seguir ilustra como uma mensagem de erro pode ser copiada na rea de transferncia do usurio quando ocorre um erro de segurana. A mensagem de erro poder ser til se o usurio desejar relatar um bug potencial com um aplicativo.
private function securityErrorHandler(event:SecurityErrorEvent):void { var errorString:String = "[" + event.type + "] " + event.text; trace(errorString); System.setClipboard(errorString); }

Flash Player 10 e AIR 1.0 Voc pode usar a classe Clipboard para ler e gravar dados na rea de transferncia e reagir a um evento do usurio. No AIR, um evento de usurio no obrigatrio para cdigo executado na rea de segurana do aplicativo para acessar a rea de transferncia.

Uso da classe Capabilities

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe Capabilities permite que os desenvolvedores determinem o ambiente no qual o aplicativo est sendo executado. Com o uso de vrias propriedades da classe Capabilities, possvel descobrir a resoluo do sistema do usurio, se o sistema do usurio oferece suporte a software de acessibilidade, o idioma do sistema operacional do usurio, bem como a verso do tempo de execuo do Flash. Verificando as propriedade da classe Capabilities, possvel personalizar o aplicativo para trabalhar melhor com o ambiente especfico do usurio. Por exemplo, verificando as propriedades Capabilities.screenResolutionX e Capabilities.screenResolutionY, possvel determinar a resoluo de vdeo que o sistema do usurio est usando e decidir qual tamanho de vdeo pode ser mais apropriado. Ou possvel verificar a propriedade Capabilities.hasMP3 para verificar se o sistema do usurio oferece suporte reproduo de mp3 antes de tentar carregar um arquivo mp3 externo. O cdigo a seguir usa uma expresso regular para analisar a verso do tempo de execuo do Flash que est sendo usada pelo cliente:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Ambiente do sistema cliente

855

var versionString:String = Capabilities.version; var pattern:RegExp = /^(\w*) (\d*),(\d*),(\d*),(\d*)$/; var result:Object = pattern.exec(versionString); if (result != null) { trace("input: " + result.input); trace("platform: " + result[1]); trace("majorVersion: " + result[2]); trace("minorVersion: " + result[3]); trace("buildNumber: " + result[4]); trace("internalBuildNumber: " + result[5]); } else { trace("Unable to match RegExp."); }

Para enviar as capacidades do sistema do usurio para um script do lado do servidor de forma que as informaes sejam armazenadas em um banco de dados, possvel usar o seguinte cdigo ActionScript:
var url:String = "log_visitor.cfm"; var request:URLRequest = new URLRequest(url); request.method = URLRequestMethod.POST; request.data = new URLVariables(Capabilities.serverString); var loader:URLLoader = new URLLoader(request);

Exemplo de recursos: deteco de capacidades do sistema

Flash Player 9 e posterior O exemplo CapabilitiesExplorer demonstra como usar a classe flash.system.Capabilities para determinar quais recursos so suportados pela verso do usurio do tempo de execuo do Flash. Este exemplo ensina as seguintes tcnicas:

Deteco das capacidades suportadas pela verso do usurio do tempo de execuo do Flash usando a classe
Capabilities.

Uso da classe ExternalInterface para detectar quais configuraes de navegador so suportadas pelo navegador do
usurio. Para obter os arquivos de aplicativo deste exemplo, consulte www.adobe.com/go/learn_programmingAS3samples_flash_br. Os arquivos do aplicativo CapabilitiesExplorer podem ser encontrados na pasta Amostras/CapabilitiesExplorer. Esse aplicativo consiste nos seguintes arquivos:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Ambiente do sistema cliente

856

Arquivo CapabilitiesExplorer.fla ou CapabilitiesExplorer.mxml com/example/programmingas3/capabilities/CapabilitiesGrabber.as

Descrio O arquivo principal do aplicativo no Flash (FLA) ou no Flex (MXML).

A classe que fornece a funcionalidade principal do aplicativo, incluindo a adio das capacidades do sistema a uma matriz, a classificao dos itens e o uso da classe ExternalInterface para recuperar as capacidades do navegador. Um continer HTML que contm o JavaScript necessrio para se comunicar com a API externa.

capabilities.html

Viso geral de CapabilitiesExplorer

Flash Player 9 e posterior O arquivo CapabilitiesExplorer.mxml responsvel por configurar a interface do usurio para o aplicativo CapabilitiesExplorer. As capacidades da verso do usurio do tempo de execuo do Flash sero exibidas dentro de uma ocorrncia do componente DataGrid no Palco. As capacidades do navegador tambm sero exibidas se eles estiverem executando o aplicativo em um continer HTML e se a API externa estiver disponvel. Quando o evento creationComplete do arquivo do aplicativo principal despachado, o mtodo initApp() chamado. O mtodo initApp() chama o mtodo getCapabilities() de dentro da classe com.example.programmingas3.capabilities.CapabilitiesGrabber. O cdigo do mtodo initApp() o seguinte:
private function initApp():void { var dp:Array = CapabilitiesGrabber.getCapabilities(); capabilitiesGrid.dataProvider = dp; }

O mtodo CapabilitiesGrabber.getCapabilities() retorna uma matriz classificada do tempo de execuo do Flash e as capacidades do navegador que, em seguida, so definidas para a propriedade dataProvider da ocorrncia do componente DataGrid capabilitiesGrid no Palco.

Viso geral da classe CapabilitiesGrabber

Flash Player 9 e posterior O mtodo esttico getCapabilities() da classe CapabilitiesGrabber adiciona cada propriedade da classe flash.system.Capabilities a uma matriz (capDP). Em seguida, ele chama o mtodo esttico getBrowserObjects() na classe CapabilitiesGrabber. O mtodo getBrowserObjects() usa a API externa para loop sobre o objeto navigator do navegador que contm as capacidades do navegador. O mtodo getCapabilities() o seguinte:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Ambiente do sistema cliente

857

public static function getCapabilities():Array { var capDP:Array = new Array(); capDP.push({name:"Capabilities.avHardwareDisable", value:Capabilities.avHardwareDisable}); capDP.push({name:"Capabilities.hasAccessibility", value:Capabilities.hasAccessibility}); capDP.push({name:"Capabilities.hasAudio", value:Capabilities.hasAudio}); ... capDP.push({name:"Capabilities.version", value:Capabilities.version}); var navArr:Array = CapabilitiesGrabber.getBrowserObjects(); if (navArr.length > 0) { capDP = capDP.concat(navArr); } capDP.sortOn("name", Array.CASEINSENSITIVE); return capDP; }

O mtodo getBrowserObjects() retorna uma matriz de cada uma das propriedades do objeto navigator no navegador. Se essa matriz tiver um comprimento de um ou mais itens, a matriz de capacidades do navegador (navArr) ser anexada matriz de capacidades do Flash Player (capDP) e a matriz inteira ser classificada alfabeticamente. Finalmente, a matriz classificada ser retornada ao arquivo do aplicativo principal que, em seguida preencher a grade de dados. O cdigo para o mtodo getBrowserObjects() o seguinte:
private static function getBrowserObjects():Array { var itemArr:Array = new Array(); var itemVars:URLVariables; if (ExternalInterface.available) { try { var tempStr:String = ExternalInterface.call("JS_getBrowserObjects"); itemVars = new URLVariables(tempStr); for (var i:String in itemVars) { itemArr.push({name:i, value:itemVars[i]}); } } catch (error:SecurityError) { // ignore } } return itemArr; }

Se a API externa estiver disponvel no ambiente atual do usurio, o tempo de execuo do Flash chamar o mtodo JS_getBrowserObjects() do JavaScript que executa loop sobre o objeto navigator do navegador e retorna uma string de valores codificados de URL ao ActionScript. Em seguida, essa string convertida em um objeto URLVariables (itemVars) e adicionada matriz itemArr que retornada para o script de chamada.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Ambiente do sistema cliente

858

Comunicao com o JavaScript

Flash Player 9 e posterior A parte final da criao do aplicativo CapabilitiesExplorer a escrita do JavaScript necessrio para executar loop sobre cada um dos itens no objeto navigator do navegador e anexar um par de nome e valor a uma matriz temporria. O cdigo do mtodo JS_getBrowserObjects() do JavaScript no container.html o seguinte:
<script language="JavaScript"> function JS_getBrowserObjects() { // Create an array to hold each of the browser's items. var tempArr = new Array(); // Loop over each item in the browser's navigator object. for (var name in navigator) { var value = navigator[name]; // If the current value is a string or Boolean object, add it to the // array, otherwise ignore the item. switch (typeof(value)) { case "string": case "boolean": // Create a temporary string which will be added to the array. // Make sure that we URL-encode the values using JavaScript's // escape() function. var tempStr = "navigator." + name + "=" + escape(value); // Push the URL-encoded name/value pair onto the array. tempArr.push(tempStr); break; } } // Loop over each item in the browser's screen object. for (var name in screen) { var value = screen[name]; // If the current value is a number, add it to the array, otherwise // ignore the item. switch (typeof(value)) { case "number": var tempStr = "screen." + name + "=" + escape(value); tempArr.push(tempStr); break; } } // Return the array as a URL-encoded string of name-value pairs. return tempArr.join("&"); } </script>

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Ambiente do sistema cliente

859

O cdigo comea com a criao de uma matriz temporria que conter todos os pares de nome e valor no objeto navigator. Em seguida, um loop executado no objeto navigator usando um loopfor..in e o tipo de dados do valor atual avaliado para filtrar valores indesejados. Neste aplicativo, estamos interessados somente nos valores de string ou booleanos e outros tipos de dados (como funes ou matrizes) so ignorados. Cada valor de string ou booleano no objeto navigator anexado matriz tempArr. Em seguida, executado um loop no objeto da tela do navegador usando um for..in e cada valor numrico adicionado matriz tempArr. Finalmente, a matriz temporria convertida em uma string usando o mtodo Array.join(). A matriz usa um e comercial (&) como um delimitador, o que permite que o ActionScript analise os dados facilmente usando a classe URLVariables.

ltima atualizao em 29/3/2011

860

Captulo 47: Chamada e encerramento do aplicativo AIR

Adobe AIR 1.0 e posterior Essa seo discute as formas atravs das quais um aplicativo Adobe AIR instalado pode ser invocado, bem como opes e consideraes para fechar um aplicativo em execuo. Nota: Os objetos NativeApplication, InvokeEvent e BrowserInvokeEvent s esto disponveis para o contedo SWF em execuo na caixa de proteo do aplicativo AIR. O contedo SWF que est sendo reproduzido no tempo de execuo do Flash Play, dentro do navegador ou no player autnomo (projetor), ou em um aplicativo AIR fora da caixa de proteo do aplicativo, no pode acessar essas classes. Para ver uma rpida explicao e exemplos de cdigo da chamada e encerramento de aplicativos AIR, consulte os seguintes artigos de incio rpido no Adobe Developer Connection:

Opes de inicializao

Mais tpicos da Ajuda

flash.desktop.NativeApplication flash.events.InvokeEvent flash.events.BrowserInvokeEvent

Chamada do aplicativo
Adobe AIR 1.0 e posterior Um aplicativo AIR invocado quando o usurio (ou o sistema operacional):

Inicia o aplicativo do shell da rea de trabalho. Usa o aplicativo como um comando em um shell de linha de comando. Abre um tipo de arquivo para o qual o aplicativo o aplicativo de abertura padro. (Mac OS X) clica no cone do aplicativo na barra de tarefas do encaixe (esteja o aplicativo em execuo ou no no
momento).

Opta por inicializar o aplicativo do instalador (na extremidade de um novo processo de instalao ou aps clicar
duas vezes no arquivo do AIR para um aplicativo j instalado).

Comea uma atualizao de um aplicativo AIR quando a verso instalada tiver assinalado que est lidando sozinha
com atualizaes do aplicativo (incluindo uma declarao <customUpdateUI>true</customUpdateUI> no arquivo do descritor do aplicativo).

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Chamada e encerramento do aplicativo AIR

861

Visita uma pgina da Web que hospeda um crach ou aplicativo do Flash que chama o mtodo
com.adobe.air.AIR launchApplication() especificando as informaes de identificao para o aplicativo AIR. (O descritor do aplicativo tambm deve incluir uma declarao <allowBrowserInvocation>true</allowBrowserInvocation> para que a chamada do navegador seja bemsucedida.)

Sempre que um aplicativo AIR for invocado, o AIR despacha um objeto de tipo InvokeEvent invoke pelo objeto singleton NativeApplication. Para permitir que o tempo de um aplicativo se inicialize e registre um ouvinte de evento, eventos invoke so enfileirados em vez de descartados. Assim que um ouvinte registrado, todos os eventos enfileirados so entregues. Nota: Quando um aplicativo chamado usando o recurso de chamada do navegador, o objeto NativeApplication emite somente um evento invoke se o aplicativo ainda no estiver em execuo. Para receber eventos invoke, chame o mtodo addEventListener() do objeto NativeApplication (NativeApplication.nativeApplication). Quando um ouvinte de evento registra um evento invoke, ele tambm recebe todos os eventos invoke que ocorreram antes do registro. Eventos invoke enfileirados so despachados um de cada vez em um curto intervalo aps a chamada para addEventListener() ser retornada. Se um novo evento invoke ocorrer durante esse processo, ele poder ser despachado antes de um ou mais dos eventos enfileirados. Esse enfileiramento de eventos permite que voc manipule qualquer evento invoke que tenha ocorrido antes de seu cdigo de inicializao ser executado. Tenha em mente que, se voc adicionar um ouvinte de evento depois na execuo (depois da inicializao do aplicativo), ele ainda receber todos os eventos invoke que ocorreram desde que o aplicativo foi iniciado. Apenas uma instncia de um aplicativo AIR iniciada. Quando um aplicativo j em execuo invocado novamente, o AIR despacha um novo evento invoke para a instncia em execuo. de responsabilidade de um aplicativo AIR responder a um evento invoke e executar a ao apropriada (como abrir uma janela de um novo documento). Um objeto InvokeEvent contm qualquer argumento transmitido ao aplicativo, bem como o diretrio a partir do qual o aplicativo foi invocado. Se o aplicativo foi invocado devido a uma associao de tipo de arquivo, todo o caminho para o arquivo ser includo nos argumentos de linha de comando. Da mesma forma, se o aplicativo foi invocado devido a uma atualizao de aplicativo, todo o caminho para o arquivo do AIR atualizado ser fornecido. Quando vrios arquivos so abertos em uma operao, um nico objeto InvokeEvent despachado no Mac OS X. Cada arquivo includo na matriz arguments. No Windows e no Linux, um objeto InvokeEvent distinto despachado para cada arquivo. Seu aplicativo pode manipular eventos invoke registrando um ouvinte com seu objeto NativeApplication:
NativeApplication.nativeApplication.addEventListener(InvokeEvent.INVOKE, onInvokeEvent);

E definindo um ouvinte de evento:

var arguments:Array; var currentDir:File; public function onInvokeEvent(invocation:InvokeEvent):void { arguments = invocation.arguments; currentDir = invocation.currentDirectory; }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Chamada e encerramento do aplicativo AIR

862

Captura de argumentos de linha de comando

Adobe AIR 1.0 e posterior Os argumentos de linha de comando associados invocao de um aplicativo AIR so entregues no objeto InvokeEvent despachado pelo objeto NativeApplication. A propriedade arguments do InvokeEvent contm uma matriz dos argumentos transmitidos pelo sistema operacional quando um aplicativo AIR invocado. Se os argumentos contm caminhos de arquivos relativos, voc pode normalmente resolver os caminhos usando a propriedade currentDirectory. Os argumentos transmitidos a um programa do AIR so tratados como seqncias delimitadas de espao em branco, a menos que estejam entre aspas duplas:
Argumentos tick tock tick "tick tock" "tick" tock \"tick\" \"tock\" Array {tick,tock} {tick,tick tock} {tick,tock} {"tick","tock"}

A propriedade currentDirectory de um objeto InvokeEvent contm um objeto File que representa o diretrio a partir do qual o aplicativo foi iniciado. Quando um aplicativo invocado porque um arquivo de um tipo registrado pelo aplicativo aberto, o caminho nativo para o arquivo includo nos argumentos de linha de comando como uma seqncia de caracteres. (Seu aplicativo responsvel por abrir ou executar a operao pretendida no arquivo.) Da mesma forma, quando um aplicativo programado para se atualizar (em vez de confiar na interface de usurio de atualizao do AIR padro), o caminho nativo para o arquivo do AIR includo quando um usurio clica duas vezes em um arquivo do AIR que contm um aplicativo com uma ID correspondente do aplicativo. Voc pode acessar o arquivo usando o mtodo resolve() do objeto File currentDirectory:
if((invokeEvent.currentDirectory != null)&&(invokeEvent.arguments.length > 0)){ dir = invokeEvent.currentDirectory; fileToOpen = dir.resolvePath(invokeEvent.arguments[0]); }

Voc tambm deve validar se um argumento realmente um caminho para um arquivo.

Exemplo: log de eventos de invocao

Adobe AIR 1.0 e posterior O exemplo a seguir demonstra como registrar ouvintes para e manipular o evento invoke. O exemplo registra todos os eventos de invocao recebidos e exibe o diretrio atual e os argumentos de linha de comando.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Chamada e encerramento do aplicativo AIR

863

Exemplo do ActionScript
package { import import import import

flash.display.Sprite; flash.events.InvokeEvent; flash.desktop.NativeApplication; flash.text.TextField;

public class InvokeEventLogExample extends Sprite { public var log:TextField; public function InvokeEventLogExample() { log = new TextField(); log.x = 15; log.y = 15; log.width = 520; log.height = 370; log.background = true; addChild(log); NativeApplication.nativeApplication.addEventListener(InvokeEvent.INVOKE, onInvoke); } public function onInvoke(invokeEvent:InvokeEvent):void { var now:String = new Date().toTimeString(); logEvent("Invoke event received: " + now); if (invokeEvent.currentDirectory != null) { logEvent("Current directory=" + invokeEvent.currentDirectory.nativePath); } else {

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Chamada e encerramento do aplicativo AIR

864

logEvent("--no directory information available--"); } if (invokeEvent.arguments.length > 0) { logEvent("Arguments: " + invokeEvent.arguments.toString()); } else { logEvent("--no arguments--"); } } public function logEvent(entry:String):void { log.appendText(entry + "\n"); trace(entry); } } }

Exemplo do Flex
<?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical" invoke="onInvoke(event)" title="Invocation Event Log"> <mx:Script> <![CDATA[ import flash.events.InvokeEvent; import flash.desktop.NativeApplication; public function onInvoke(invokeEvent:InvokeEvent):void { var now:String = new Date().toTimeString(); logEvent("Invoke event received: " + now); if (invokeEvent.currentDirectory != null){ logEvent("Current directory=" + invokeEvent.currentDirectory.nativePath); } else { logEvent("--no directory information available--"); } if (invokeEvent.arguments.length > 0){ logEvent("Arguments: " + invokeEvent.arguments.toString()); } else { logEvent("--no arguments--"); } } public function logEvent(entry:String):void { log.text += entry + "\n"; trace(entry); } ]]> </mx:Script> <mx:TextArea id="log" width="100%" height="100%" editable="false" valueCommit="log.verticalScrollPosition=log.textHeight;"/> </mx:WindowedApplication>

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Chamada e encerramento do aplicativo AIR

865

Invocando um aplicativo AIR no logon do usurio

Adobe AIR 1.0 e posterior Um aplicativo AIR pode ser definido para ser inicializado automaticamente quando o usurio atual faz login definindo a propriedade StartAtLogi do NativeApplication como true. Depois de definido, o aplicativo iniciado automaticamente sempre que o usurio fizer login. Ele continua a ser aberto no logon at que a configurao seja alterada para false, o usurio altera manualmente a configurao pelo sistema operacional ou o aplicativo desinstalado. A inicializao no logon uma configurao de tempo de execuo. A configurao se aplica apenas ao usurio atual. O aplicativo deve ser instalado para definir com xito a propriedade startAtLogin como true. Um erro lanado se a propriedade for definida quando um aplicativo no est instalado (como quando ele inicializado com o ADL). Nota: O aplicativo no iniciado quando o sistema do computador iniciado. Ele iniciado quando o usurio faz login. Para determinar se um aplicativo foi iniciado automaticamente ou como resultado de uma ao do usurio, voc pode examinar a propriedade reason do objeto InvokeEvent. Se a propriedade foi igual a InvokeEventReason.LOGIN, ento o aplicativo iniciado automaticamente. Para qualquer outro caminho de invocao, a propriedade reason igual a InvokeEventReason.STANDARD. Para acessar a propriedade reason, seu aplicativo deve se focalizar em AIR 1.5.1 (definindo o valor correto de namespace no arquivo de descrio do aplicativo). O aplicativo simplificado a seguir usa a propriedade reason do InvokeEvent para decidir como se comportar quando ocorre um evento invoke. Se a propriedade reason for "login", o aplicativo continua em plano de fundo. Do contrrio, ele torna o aplicativo principal visvel. O aplicativo que usa esse padro em geral iniciado no logon, de forma que possa realizar o processamento de fundo ou o monitoramento do evento e abre uma janela em resposta a um evento invoke disparador pelo usurio.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Chamada e encerramento do aplicativo AIR

866

package { import import import import

flash.desktop.InvokeEventReason; flash.desktop.NativeApplication; flash.display.Sprite; flash.events.InvokeEvent;

public class StartAtLogin extends Sprite { public function StartAtLogin() { try { NativeApplication.nativeApplication.startAtLogin = true; } catch ( e:Error ) { trace( "Cannot set startAtLogin:" + e.message ); } NativeApplication.nativeApplication.addEventListener( InvokeEvent.INVOKE, onInvoke ); } private function onInvoke( event:InvokeEvent ):void { if( event.reason == InvokeEventReason.LOGIN ) { //do background processing... trace( "Running in background..." ); } else { this.stage.nativeWindow.activate(); } } } }

Nota: Para ver a diferena no comportamento, empacote e instale o aplicativo. A propriedade startAtLogin s pode ser definida para os aplicativos instalados.

Invocao de um aplicativo AIR do navegador

Adobe AIR 1.0 e posterior Usando o recurso de invocao do navegador, um site da Web pode inicializar um aplicativo instalado do AIR do navegador. A chamada do navegador permitida apenas se o arquivo descritor do aplicativo definir allowBrowserInvocation como true:
<allowBrowserInvocation>true</allowBrowserInvocation>

Quando o aplicativo invocado pelo navegador, o objeto NativeApplication do aplicativo despacha um objeto BrowserInvokeEvent.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Chamada e encerramento do aplicativo AIR

867

Para receber eventos BrowserInvokeEvent, chame o mtodo addEventListener() do objeto NativeApplication (NativeApplication.nativeApplication) no aplicativo AIR. Quando um ouvinte de evento registra um evento BrowserInvokeEvent, ele tambm recebe todos os eventos BrowserInvokeEvent que ocorreram antes do registro. Esses eventos so despachados depois que a chamada a addEventListener() retorna, mas no necessariamente antes de outros eventos BrowserInvokeEvent, que podem ser recebidos depois do registro. Isso permite que voc manipule os eventos BrowserInvokeEvent ocorridos antes que seu cdigo de inicializao fosse executado (por exemplo, quando o aplicativo foi inicialmente invocado do navegador). Tenha em mente que, se voc adicionar um ouvinte de evento depois na execuo (depois da inicializao do aplicativo), ele ainda receber todos os eventos BrowserInvokeEvent ocorridos desde que o aplicativo foi iniciado. O objeto BrowserInvokeEvent inclui as seguintes propriedades:
Propriedade argumentos isHTTPS isUserEvent Descrio Uma matriz de argumentos (seqncias de caracteres) para transmitir ao aplicativo. Se o contedo do navegador usa o esquema de URL https (true) ou no (false). Se a invocao do navegador resultou em um evento de usurio (como clique do mouse). No AIR 1.0, este ajuste sempre true; o AIR exige um evento de usurio para o recurso de invocao do navegador. O tipo de caixa de proteo para o contedo do navegador. Valores vlidos so definidos como aqueles que podem ser usados na propriedade Security.sandboxType e podem ser um dos seguintes:

sandboxType

securityDomain

Security.APPLICATION O contedo est na caixa de proteo de segurana do aplicativo. Security.LOCAL_TRUSTED O contedo est na caixa de proteo de segurana local com sistema de

arquivos.
Security.LOCAL_WITH_FILE O contedo est na caixa de proteo de segurana local com sistema

de arquivos.
Security.LOCAL_WITH_NETWORK O contedo est na caixa de proteo de segurana local com rede. Security.REMOTE O contedo est em um domnio remoto (de rede).

O domnio de segurana para o contedo do navegador, como "www.adobe.com" ou "www.example.org". Essa propriedade definida apenas para contedo na caixa de proteo de segurana remota (para contedo de um domnio de rede). Ele no definido para contedo em uma caixa de proteo de segurana local ou do aplicativo.

Se voc usa o recurso de invocao do navegador, certifique-se de considerar implicaes de segurana. Quando um site da Web inicia um aplicativo AIR, ele pode enviar dados pela propriedade arguments do objeto BrowserInvokeEvent. Cuidado ao usar esses dados em qualquer operao confidencial, como carregar cdigo ou arquivo de APIs. Esse nvel de risco depende do que o aplicativo est fazendo com os dados. Se voc espera apenas um site da Web especfico para invocar o aplicativo, o aplicativo deve verificar a propriedade securityDomain do objeto BrowserInvokeEvent. Voc tambm pode exigir que o site invoque o aplicativo para usar HTTPs, o que voc pode verificar marcando a propriedade isHTTPS do objeto BrowserInvokeEvent. O aplicativo deve validar os dados transmitidos. Por exemplo, se um aplicativo espera para transmitir URLs a um domnio especfico, ele deve validar se as URLs realmente apontam para aquele domnio. Isso pode impedir que um invasor engane o aplicativo para lhe enviar dados confidenciais. Nenhum aplicativo deve usar argumentos BrowserInvokeEvent que possam apontar para recursos locais. Por exemplo, um aplicativo no deve criar objetos File com base em um caminho transmitido do navegador. Se espera-se que caminhos remotos sejam transmitidos do navegador, o aplicativo deve garantir que os caminhos no usem o protocolo file:// em vez de um protocolo remoto.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Chamada e encerramento do aplicativo AIR

868

Encerramento do aplicativo
Adobe AIR 1.0 e posterior A forma mais rpida de encerrar um aplicativo chamar o mtodo exit() do NativeApplication. Isso funciona bem quando seu aplicativo no tem dados para salvar ou recursos externos para limpar. Chamar exit() fecha todas as janelas e, em seguida, encerra o aplicativo. No entanto, para permitir que janelas ou outros componentes do seu aplicativo interrompam o processo de encerramento, talvez para salvar dados vitais, despache os eventos de aviso adequados antes de chamar exit(). Outra considerao sobre como fechar um aplicativo graciosamente fornecer um nico caminho de execuo, sem importar como o processo de encerramento iniciado. O usurio (ou sistema operacional) pode disparar o encerramento do aplicativo das seguintes maneiras:

Fechando a ltima janela do aplicativo quando NativeApplication.nativeApplication.autoExit for true. Selecionando o comando de sada do aplicativo do sistema operacional; por exemplo, quando o usurio escolhe o
comando de sair do aplicativo do menu padro. (Isso s ocorre com o Mac OS. O Windows e o Linux no fornecem um comando de sada do aplicativo por meio do cromo do sistema.)

Desligando o computador.
Quando um comando de sada mediado pelo sistema operacional por uma dessas rotas, o NativeApplication despacha um evento exiting. Se nenhum ouvinte cancelar o evento exiting, qualquer janela aberta ser fechada. Cada janela despacha um evento closing e, em seguida, um close. Se alguma das janelas cancelar o evento closing, o processo de encerramento ser interrompido. Se a ordem do fechamento das janelas for um problema para o seu aplicativo, oua o evento exiting do NativeApplication e feche voc mesmo as janelas na ordem adequada. Talvez voc precise fazer isso, por exemplo, se tiver uma janela de documento com as paletas da ferramenta. Poderia ser inconveniente, ou pior, se o sistema fechou as paletas, mas o usurio decidiu cancelar o comando de sair para salvar alguns dados. No Windows, o nico momento que voc obter o evento exiting depois de fechar a ltima janela (quando a propriedade autoExit do objeto NativeApplication for definida como true). Para fornecer um comportamento consistente em todas as plataformas, seja a seqncia de sada iniciada pelo cromo do sistema operacional, por comandos de menu ou pela lgica do aplicativo, observe as seguintes prticas recomendadas para sair do aplicativo:
1 Sempre despache um evento exiting pelo objeto NativeApplication antes de chamar exit() no cdigo do

aplicativo e verifique se outro componente do seu aplicativo no cancela o evento.

public function applicationExit():void { var exitingEvent:Event = new Event(Event.EXITING, false, true); NativeApplication.nativeApplication.dispatchEvent(exitingEvent); if (!exitingEvent.isDefaultPrevented()) { NativeApplication.nativeApplication.exit(); } }

2 Oua o evento exiting do aplicativo do objeto NativeApplication.nativeApplication e, no manipulador,

feche qualquer janela (despachando um evento closing primeiro). Execute qualquer tarefa de limpeza necessria, como salvar dados de aplicativo ou excluir arquivos temporrios, aps todas as janelas terem sido fechadas. Apenas use mtodos sncronos durante a limpeza para garantir que eles sejam concludos antes que o aplicativo seja encerrado.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Chamada e encerramento do aplicativo AIR

869

Se a ordem na qual suas janelas forem fechadas no importar, voc pode efetuar um loop pela matriz NativeApplication.nativeApplication.openedWindows e fechar cada janela sucessivamente. Se a ordem importar, fornea um modo de fechar as janelas na seqncia correta.
private function onExiting(exitingEvent:Event):void { var winClosingEvent:Event; for each (var win:NativeWindow in NativeApplication.nativeApplication.openedWindows) { winClosingEvent = new Event(Event.CLOSING,false,true); win.dispatchEvent(winClosingEvent); if (!winClosingEvent.isDefaultPrevented()) { win.close(); } else { exitingEvent.preventDefault(); } } if (!exitingEvent.isDefaultPrevented()) { //perform cleanup } }

3 As janelas devem sempre manipular sua prpria limpeza ouvindo seus prprios eventos closing. 4 Use apenas um ouvinte exiting no seu aplicativo uma vez que manipuladores chamados anteriormente no

podem saber se os manipuladores subseqentes iro cancelar o evento exiting (e no seria inteligente confiar na ordem de execuo).

ltima atualizao em 29/3/2011

870

Captulo 48: Trabalho com informaes de tempo de execuo do AIR e de sistema operacional
Adobe AIR 1.0 e posterior Essa seo discute formas atravs das quais um aplicativo AIR pode gerenciar as associaes do arquivo do sistema operacional, detectar a atividade do usurio e obter informaes sobre o tempo de execuo do Adobe AIR.

Mais tpicos da Ajuda

flash.desktop.NativeApplication

Gerenciamento de associaes de arquivos

Adobe AIR 1.0 e posterior Associaes entre seu aplicativo e um tipo de arquivo devem ser declaradas no descritor do aplicativo. Durante o processo de instalao, o instalador do aplicativo AIR associa o aplicativo AIR como o aplicativo de abertura padro para cada um dos tipos de arquivo declarados, a menos que outro aplicativo j seja o padro. O processo de instalao do aplicativo AIR no substitui uma associao de tipo de arquivo existente. Para se apoderar da associao de outro aplicativo, chame o mtodo NativeApplication.setAsDefaultApplication() no tempo de execuo. Constitui boa prtica verificar se as associaes de arquivos esperadas esto em vigor quando seu aplicativo inicializar Isso porque o instalador do aplicativo AIR no sobrescreve associaes de arquivo existentes e porque associaes de arquivo em um sistema de usurio podem mudar a qualquer momento. Quando outro aplicativo tem a associao de arquivo atual, tambm boa prtica solicitar ao usurio antes de se apoderar de uma associao existente. Os mtodos seguintes da classe NativeApplication permitem que um aplicativo gerencie associaes de arquivos. Cada um dos mtodos toma a extenso de tipo de arquivo como um parmetro:
Mtodo isSetAsDefaultApplication() setAsDefaultApplication() removeAsDefaultApplication() getDefaultApplication() Descrio Retorna true se o aplicativo AIR est associado atualmente ao tipo de arquivo especificado. Cria a associao entre o aplicativo AIR e a ao aberta do tipo de arquivo. Remove a associao entre o aplicativo AIR e o tipo de arquivo. Reporta o caminho do aplicativo que est associado atualmente ao tipo de arquivo.

O AIR s pode gerenciar associaes para os tipos de arquivo originalmente declarados no descritor do aplicativo. Voc no pode obter informaes sobre as associaes de um tipo de arquivo no declarado, mesmo que um usurio tenha criado manualmente a associao entre esse tipo de arquivo e seu aplicativo. Chamar algum dos mtodos de gerenciamento de associao de arquivo com a extenso de um tipo de arquivo no declarado no descritor do aplicativo faz com que o aplicativo lance uma exceo de tempo de execuo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com informaes de tempo de execuo do AIR e de sistema operacional

871

Obteno da verso do tempo de execuo e do nvel de patch

Adobe AIR 1.0 e posterior O objeto NativeApplication tem uma propriedade runtimeVersion, que a verso do tempo de execuo em que o aplicativo est sendo executado (uma string, como "1.0.5"). O objeto NativeApplication tambm tem uma propriedade runtimePatchLevel, que o nvel de patch do tempo de execuo (um nmero, como 2960). O cdigo seguinte usa estas propriedades:
trace(NativeApplication.nativeApplication.runtimeVersion); trace(NativeApplication.nativeApplication.runtimePatchLevel);

Deteco de recursos do AIR

Adobe AIR 1.0 e posterior Para um arquivo que esteja reunido com o aplicativo Adobe AIR, a propriedade Security.sandboxType est definida como o valor definido pela constante Security.APPLICATION. Voc pode carregar o contedo (que pode ou no conter APIs especficas ao AIR) baseado em um arquivo estar na caixa de proteo de segurana do Adobe AIR, como ilustrado no cdigo seguinte:
if (Security.sandboxType == Security.APPLICATION) { // Load SWF that contains AIR APIs } else { // Load SWF that does not contain AIR APIs }

Todos os recursos no instalado com o aplicativo AIR so atribudos s mesmas caixas de proteo de segurana como seriam atribudos pelo Adobe Flash em um navegador da Web. Recursos remotos so colocados em caixas de proteo, de acordo com seus domnios de origem, e recursos locais so colocados na caixa de proteo local com rede, local com sistema de arquivos ou local confivel. Voc pode verificar se a propriedade esttica Capabilities.playerType est definida como "Desktop" para ver se o contedo est sendo executado no tempo de execuo (e no em execuo no Flash Player em execuo em um navegador). Para obter mais informaes, consulte Segurana do AIR na pgina 1063.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com informaes de tempo de execuo do AIR e de sistema operacional

872

Rastreamento de presena do usurio

Adobe AIR 1.0 e posterior O objeto NativeApplication despacha dois eventos que o ajudam a detectar quando o usurio est usando o computador ativamente. Se no for detectada nenhuma atividade do mouse nem do teclado no intervalo de tempo determinado pela propriedade NativeApplication.idleThreshold, o NativeApplication despacha um evento userIdle. Quando ocorrer a prxima entrada de mouse ou teclado, o objeto NativeApplication despachar um evento userPresent. O intervalo idleThreshold medido em segundos e tem um valor padro de 300 (5 minutos). Voc tambm ode obter o nmero de segundos desde a ltima entrada de usurio da propriedade NativeApplication.nativeApplication.lastUserInput. As linhas seguintes de cdigo definem o limite de ociosidade para 2 minutos e ouvem tanto eventos userIdle como userPresent:
NativeApplication.nativeApplication.idleThreshold = 120; NativeApplication.nativeApplication.addEventListener(Event.USER_IDLE, function(event:Event) { trace("Idle"); }); NativeApplication.nativeApplication.addEventListener(Event.USER_PRESENT, function(event:Event) { trace("Present"); });

Nota: Apenas um nico evento userIdle despachado entre quaisquer dois eventos userPresent.

ltima atualizao em 29/3/2011

873

Captulo 49: Trabalho com janelas nativas do AIR

Adobe AIR 1.0 e posterior Use as classes fornecidas pela API de janela nativa do Adobe AIR para criar e gerenciar janelas da rea de trabalho.

Princpios bsicos das janelas nativas no AIR

Adobe AIR 1.0 e posterior Para ver uma explicao rpida e exemplos de cdigo para trabalhar com janelas originais no AIR, consulte os seguintes artigos de incio rpido do Adobe Developer Connection:

Criao de um aplicativo com janela transparente (Flex) Interao com uma janela (Flex) Personalizao da aparncia de uma janela nativa (Flex) Abertura de janelas (Flex) Criao de janelas no estilo pop-up (Flex) Controle da ordem de exibio das janelas (Flex) Criao de janelas no retangulares redimensionveis (Flex) Interao com uma janela (Flex) Personalizao da aparncia de uma janela nativa (Flex) Criao de janelas no estilo pop-up (Flash) Controle da ordem de exibio das janelas (Flash) Criao de janelas no retangulares redimensionveis (Flash)
O AIR oferece uma API de janelas fcil de usar e compatvel com vrias plataformas, que permite criar janelas de sistema operacional nativas usando tcnicas de programao em Flash, Flex e HTML. Com o AIR, voc tem grande liberdade para desenvolver a aparncia do seu aplicativo. As janelas que voc cria parecem um aplicativo padro de rea de trabalho, correspondendo ao estilo Apple quando em execuo no Mac, em conformidade com convenes Microsoft quando executadas no Windows e em harmonia com o gerenciador de janelas do Linux, tudo sem incluir um cdigo especfico de linha de plataforma. Se preferir, voc pode usar o cromo extensvel e que pode ter a capa trocada, fornecido pela estrutura do Flex, para estabelecer o seu prprio estilo, independentemente do local onde o aplicativo executado. Voc pode at mesmo desenhar seus prprios cromos de janelas usando arte final vetorial e de bitmap com suporte completo para transparncia e mesclagem alfa na rea de trabalho. Cansado de janelas retangulares? Desenhe uma redonda.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

874

Janelas no AIR
Adobe AIR 1.0 e posterior O AIR suporta trs APIs diferentes para se trabalhar com janelas:

A classe NativeWindow orientada para ActionScript fornece o nvel mais baixo de API de janela. Use o
NativeWindows em aplicativos de autoria Flash Professional e ActionScript. Considere estender a classe NativeWindow para especializar as janelas usadas em seu aplicativo.

No ambiente HTML, voc pode usar a classe JavaScript Window, assim como faria em um aplicativo da Web
baseado em navegador. As chamadas para os mtodos JavaScript Window so encaminhadas para o objeto janela nativo subjacente.

As classes mx:WindowedApplication e mx:Window da estrutura do Flex fornecem um "invlucro" para a classe

NativeWindow. O componente WindowedApplication substitui o componente Application quando voc cria um aplicativo AIR com Flex e deve ser sempre usado como janela inicial no aplicativo Flex. Janelas ActionScript Quando criar janelas com a classe NativeWindow, use a lista de exibio no palco do Flash Player diretamente. Para adicionar um objeto visual a uma NativeWindow, adicione o objeto lista de exibio do palco da janela ou a outro continer do objeto de exibio no palco. Janelas HTML Quando cria janelas HTML, voc usa HTML, CSS e JavaScript para exibir o contedo. Para adicionar um objeto visual a uma janela HTML, voc adiciona esse contedo ao HTML DOM. As janelas HTML so uma categoria especial de NativeWindow. O host do AIR define uma propriedade nativeWindow em janelas HTML que d acesso ocorrncia subjacente de NativeWindow. Voc pode usar essa propriedade para acessar as propriedades, os mtodos e os eventos de NativeWindow descritos aqui. Nota: O objeto JavaScript Window tambm tem mtodos para gerar scripts da janela que o contm, como moveTo() e
close(). Se houver mtodos de sobreposio disponveis, voc poder usar o mtodo que for mais conveniente.

Janelas da estrutura do Flex Quando voc cria janelas com a estrutura do Flex, normalmente usa componentes MXML para preencher a janela. Para adicionar um componente do Flex a uma janela, adicione o elemento componente definio MXML da janela. Tambm possvel usar o ActionScript para adicionar contedo dinamicamente. Os componentes mx:WindowedApplication e mx:Window so projetados como contineres do Flex e, por isso, podem aceitar componentes do Flex diretamente, enquanto os objetos NativeWindow no. Quando necessrio, as propriedades e os mtodos de NativeWindow podem ser acessados atravs dos objetos WindowedApplication e Window usando-se a propriedade nativeWindow. A janela inicial do aplicativo. A primeira janela do seu aplicativo criada automaticamente para voc pelo AIR. O AIR define as propriedades e o contedo da janela usando os parmetros especificados no elemento initialWindow do arquivo de descrio do aplicativo. Se o contedo raiz um arquivo SWF, o AIR cria uma ocorrncia de NativeWindow, carrega o arquivo SWF e o adiciona ao palco da janela. Se o contedo raiz um arquivo HTML, o AIR cria uma janela HTML e carrega o cdigo HTML.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

875

Classes de janela nativa

Adobe AIR 1.0 e posterior A API de janela nativa contm as seguintes classes:
Pacote flash.display Classes

NativeWindow NativeWindowInitOptions NativeWindowDisplayState NativeWindowResize NativeWindowSystemChrome NativeWindowType NativeWindowBoundsEvent NativeWindowDisplayStateEvent

flash.events

Fluxo de eventos de janelas nativas

Adobe AIR 1.0 e posterior As janelas nativas despacham eventos para notificar os componentes interessados de que uma alterao importante est prestes a ocorrer ou j ocorreu. Muitos eventos relacionados a janelas so despachados em pares. O primeiro evento avisa que uma alterao est prestes a ocorrer. O segundo comunica que a alterao foi feita. possvel cancelar um evento de aviso, mas no um evento de notificao. Esta seqncia ilustra o fluxo de eventos que ocorre quando um usurio clica no boto Maximizar de uma janela:
1 O objeto NativeWindow despacha um evento displayStateChanging. 2 Se nenhum ouvinte registrado cancelar o evento, a janela ser maximizada. 3 O objeto NativeWindow despacha um evento displayStateChange.

Alm disso, o objeto NativeWindow despacha eventos de alteraes relacionadas feitas no tamanho e na posio de uma janela. A janela no despacha eventos de aviso referentes a essas alteraes relacionadas. Os eventos relacionados so:
a Um evento move despachado se o canto superior esquerdo da janela foi movido por causa da operao de

maximizao.
b Um evento resize despachado se o tamanho da janela mudou devido operao de maximizao.

Um objeto NativeWindow despacha uma seqncia semelhante de eventos quando maximiza, restaura, fecha, movimenta e redimensiona uma janela. Os eventos de aviso so despachados somente quando uma alterao iniciada atravs do cromo da janela ou de outro mecanismo controlado pelo sistema operacional. Quando voc chama um mtodo de janela para alterar o tamanho, a posio ou o estado de exibio de uma janela, a janela s despacha um evento para comunicar a alterao. Se desejar, voc pode despachar um evento de aviso usando o mtodo de janela dispatchEvent() e, depois, verificar se o seu evento de aviso foi cancelado antes de prosseguir com a alterao. Veja informaes detalhadas sobre as classes, os mtodos, as propriedades e os eventos da API de janela na Referncia do ActionScript 3.0 para a plataforma Adobe Flash.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

876

Propriedades que controlam o estilo e o comportamento de janelas nativas

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior As seguintes propriedades controlam a aparncia e o comportamento bsicos de uma janela:

type systemChrome transparent owner

Quando cria uma janela, voc define essas propriedades no objeto NativeWindowInitOptions passado para o construtor da janela. O AIR l as propriedades da janela inicial do aplicativo no descritor do aplicativo. (Com exceo da propriedade type, que no pode ser definida no descritor do aplicativo e sempre definida como normal.) No possvel alterar as propriedades aps a criao da janela. Algumas configuraes dessas propriedades so mutuamente incompatveis: systemChrome no pode ser definida como standard quando transparent true ou quando type lightweight.

Tipos de janela
Adobe AIR 1.0 e posterior Os tipos de janela do AIR combinam atributos de cromo e visibilidade do sistema operacional nativo para criar trs tipos funcionais de janela. Use as constantes definidas na classe NativeWindowType para fazer referncia aos nomes de tipo no cdigo. O AIR oferece os seguintes tipos de janela:
Tipo Normal Descrio Uma janela tpica. As janelas normais usam o cromo de estilo em tamanho mximo e so exibidas na barra de tarefas do Windows e no menu de janela do Mac OS X. Uma paleta de ferramentas. As janelas de utilitrio usam uma verso reduzida do cromo do sistema e no so exibidas na barra de tarefas do Windows nem no menu de janela do Mac OS X. As janelas leves no tm cromo e no so exibidas na barra de tarefas do Windows nem no menu de janela do Mac OS X. Alm disso, as janelas leves no tm o menu Sistema (Alt+espao) no Windows. As janelas leves so adequadas para as bolhas de notificao e controles como caixas de combinao que abrem uma rea de exibio de curta durao. Quando se usa o tipo leve, a propriedade systemChrome deve ser definida como none.

Utilitrio

Leve

Cromo de janela
Adobe AIR 1.0 e posterior O cromo de janela o conjunto de controles que permitem aos usurios manipular uma janela no ambiente da rea de trabalho. Os elementos do cromo incluem a barra de ttulo e seus botes, borda e alas de redimensionamento. Cromo do sistema possvel definir a propriedade systemChrome como standard ou none. Escolha o cromo do sistema standard para dar sua janela o conjunto de controles padro criados e estilizados pelo sistema operacional do usurio. Escolha none para fornecer o seu prprio cromo para a janela. Use as constantes definidas na classe NativeWindowSystemChrome para fazer referncia s configuraes de cromo do sistema no cdigo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

877

O cromo do sistema gerenciado pelo sistema. Seu aplicativo no tem acesso direto aos controles propriamente ditos, mas pode reagir a eventos despachados quando eles so usados. Quando voc usa o cromo padro para uma janela, a propriedade transparent deve ser definida como false e a propriedade type deve ser normal ou utility. Cromo do Flex Quando voc usa os componentes :WindowedApplication ou :Window do Flex, a janela pode utilizar o cromo do sistema ou o cromo fornecido pela estrutura do Flex. Para usar o cromo do Flex, defina a propriedade systemChrome usada para criar a janela como none. Ao utilizar componentes spark Flex 4 em vez de componentes mx, necessrio especificar a classe da skin para utilizar o Flex chrome. possvel utilizar as skins integradas ou uma outra skin. O exemplo a seguir demonstra como utilizar a classe de skin spark WindowedApplication para fornecer o chrome da janela:
<?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"> <fx:Style> @namespace "library://ns.adobe.com/flex/spark"; WindowedApplication { skinClass:ClassReference("spark.skins.spark.SparkChromeWindowedApplicationSkin"); } </fx:Style> </s:WindowedApplication>

Para obter mais informaes, consulte Utilizando o Flex 4: Sobre continers de janela do AIR: Controlando o chrome da janela Cromo personalizado Se voc criar uma janela sem um cromo do sistema, dever adicionar seus prprios controles de cromo para administrar as interaes entre um usurio e a janela. Voc tambm tem liberdade para criar janelas no retangulares transparentes. Para usar o cromo personalizado com os componentes mx:WindowedApplication ou mx:Window, defina o estilo showFlexChrome como false. Do contrrio, o Flex vai acrescentar seu prprio cromo s suas janelas.

Transparncia de janelas
Adobe AIR 1.0 e posterior Para permitir a mesclagem alfa de uma janela com a rea de trabalho ou outras janelas, defina a propriedade transparent da janela como true. A propriedade transparent deve ser definida antes de a janela ser criada e no possvel alter-la. Uma janela transparente no tem um plano de fundo padro. Qualquer rea da janela que no contm um objeto desenhado pelo aplicativo fica invisvel. Se um objeto exibido tiver uma configurao alfa de menos de 1, qualquer coisa abaixo do objeto ficar visvel, inclusive outros objetos de exibio na mesma janela, em outras janelas e na rea de trabalho. As janelas transparentes so teis quando voc deseja criar aplicativos com bordas irregulares ou que desaparecem ou parecem ser invisveis. No entanto, o processamento de grandes reas com mesclagem alfa pode ser lento, por isso o efeito deve ser usado com cautela.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

878

Importante: No Linux, eventos de mouse no passam por pixels totalmente transparentes. Voc deve evitar criar janelas com reas grandes totalmente transparentes, j que isso pode bloquear invisivelmente o acesso do usurio a outras janelas ou itens na rea de trabalho. No Mac OS X e no Windows, eventos de mouse passam por pixels totalmente transparentes. A transparncia no pode ser usada com janelas que tm um cromo do sistema. Alm disso, o contedo SWF e PDF em HTML no pode ser exibido em janelas transparentes. Para obter mais informaes, consulte Consideraes ao carregar contedo SWF ou PDF em uma pgina HTML na pgina 993. A propriedade esttica NativeWindow.supportsTransparency informa se a transparncia de janela est disponvel. Quando no h suporte para transparncia, o aplicativo composto com um plano de fundo preto. Nesses casos, qualquer rea transparente do aplicativo exibida como uma rea preta opaca. uma boa prtica fornecer um recurso de emergncia caso essa propriedade se mostre false. Por exemplo, voc poderia exibir uma caixa de dilogo de aviso para o usurio ou exibir uma interface de usurio de retangular no transparente. Vale observar que sempre h suporte para transparncia nos sistemas operacionais Mac e Windows. O suporte em sistemas operacionais Linux requer um gerenciador de composio de janela, mas mesmo quando um gerenciador de composio de janela est ativo, a transparncia pode estar indisponvel devido s opes de exibio do usurio ou configurao de hardware.

Transparncia em uma janela de aplicativo MXML

Adobe AIR 1.0 e posterior Por padro, o plano de fundo de uma janela MXML opaco, mesmo que voc crie a janela como transparent. (Observe o efeito de transparncia nos cantos da janela.) Para mostrar um plano de fundo transparente da janela, defina uma cor de plano de fundo e um valor alfa na folha de estilo ou no elemento <mx:Style> contido no arquivo MXML do seu aplicativo. Por exemplo, a seguinte declarao de estilo confere ao plano de fundo uma sombra verde levemente transparente:
WindowedApplication { background-alpha:".8"; background-color:"0x448234"; }

Transparncia em uma janela de aplicativo HTML

Adobe AIR 1.0 e posterior Por padro, o plano de fundo do contedo HTML exibido em janelas HTML e objetos HTMLLoader opaco, mesmo quando a janela que o contm transparente. Para desativar o plano de fundo padro exibido com contedo HTML, defina a propriedade paintsDefaultBackground como false. O exemplo abaixo cria um objeto HTMLLoader e desativa o plano de fundo padro:
var htmlView:HTMLLoader = new HTMLLoader(); htmlView.paintsDefaultBackground = false;

Este exemplo usa JavaScript para desativar o plano de fundo padro de uma janela HTML:
window.htmlLoader.paintsDefaultBackground = false;

Se um elemento do documento HTML define uma cor de plano de fundo, o plano de fundo desse elemento no fica transparente. No h suporte para definir um valor de transparncia parcial (ou opacidade). No entanto, voc pode usar um elemento grfico no formato PNG transparente para uma pgina ou um elemento de pgina a fim de obter um efeito visual semelhante.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

879

Propriedade de janelas
Uma janela pode ser proprietria de uma ou mais janelas. Essas janelas subordinadas sempre aparecem na frente da janela proprietria, so minimizadas e restauradas juntamente com a janela proprietria e so fechadas quando a janela proprietria fechada. A propriedade de uma janela no pode ser transferida para outra janela nem removida. Uma janela pode ter apenas uma proprietria, mas pode ser proprietria de qualquer nmero de outras janelas. Voc pode usar a propriedade de janelas para facilitar o gerenciamento das janelas usadas para paletas de ferramentas e caixas de dilogo. Por exemplo, se voc tiver exibido uma caixa de dilogo Salvar associada a uma janela de documento, tornar a janela de documento proprietria da caixa de dilogo manter automaticamente a caixa de dilogo na frente da janela de documento.

Um catlogo de janelas visuais

Adobe AIR 1.0 e posterior A seguinte tabela ilustra os efeitos visuais de diferentes combinaes de configuraes de propriedades de janela nos sistemas operacionais Mac OS X, Windows e Linux:
Configuraes de janela Tipo: normal SystemChrome: standard Transparente: false Mac OS X Microsoft Windows Linux*

Tipo: utilitrio SystemChrome: standard Transparente: false

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

880

Configuraes de janela Tipo: Qualquer um SystemChrome: none Transparente: false

Mac OS X

Microsoft Windows

Linux*

Tipo: Qualquer um SystemChrome: none Transparente: true

mxWindowedApplication ou mx:Window Tipo: Qualquer um SystemChrome: none Transparente: true

Gerenciador de janela *Ubuntu with Compiz Nota: Os seguintes elementos de cromo do sistema no tm suporte no AIR: a barra de ferramentas do OS X, o cone Proxy do Mac OS X, os cones na barra de ttulo do Windows e o cromo do sistema alternativo.

Criao de janelas
Adobe AIR 1.0 e posterior O AIR cria automaticamente a primeira janela de um aplicativo, mas voc pode criar qualquer outra janela de que precise. Para criar uma janela nativa, use o mtodo de construtor NativeWindow. Para criar uma janela HTML, use o mtodo createRootWindow() de HTMLLoader ou, em um documento HTML, chame o mtodo JavaScript window.open(). A janela criada um objeto NativeWindow cuja lista de exibio contm um objeto HTMLLoader. O objeto HTMLLoader interpreta e exibe o contedo HTML e JavaScript para a janela. possvel acessar as propriedades o objeto subjacente NativeWindow a partir do JavaScript usando a propriedade window.nativeWindow. (Essa propriedade s est acessvel ao cdigo em execuo na caixa de proteo do aplicativo AIR.)

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

881

Quando uma janela inicializadaincluindo a janela inicial do aplicativovoc deve considerar criar a janela no estado invisvel, carregando o contedo ou executando atualizaes grficas e, em seguida, tornando a janela visvel. Esta sequncia impede a visualizao de alteraes visuais conflitantes pelos usurios. possvel especificar que a janela inicial do aplicativo deve ser criada no estado invisvel, indicando a tag <visible>false</visible> no descritor do aplicativo (ou no indicando a tag, j que false o valor padro). Novas NativeWindows so invisveis por padro. Ao criar uma janela HTML com o mtodo HTMLLoader createRootWindow(), voc pode definir o argumento visible para false. Chame o mtodo NativeWindow activate() ou defina a propriedade visible para true para tornar a janela visvel.

Especificao das propriedades de inicializao de uma janela

Adobe AIR 1.0 e posterior As propriedades de inicializao de uma janela nativa no podem ser alteradas aps a criao da janela da rea de trabalho. Entre as propriedades imutveis e seus valores padro esto os seguintes:
Propriedade systemChrome tipo transparent owner maximizable minimizable resizable Valor padro standard normal false null true true true

Defina as propriedades da janela inicial criada pelo AIR no arquivo de descrio do aplicativo. A janela principal de um aplicativo AIR sempre do tipo normal. ( possvel especificar outras propriedades de janela no arquivo de descrio, tais como visible, width e height, mas elas podem ser alteradas a qualquer momento.) Defina as propriedades de outras janelas nativas e HTML criadas pelo seu aplicativo usando a classe NativeWindowInitOptions. Quando voc cria uma janela, deve passar um objeto NativeWindowInitOptions que especifique as propriedades da janela para a funo de construtor NativeWindow ou o mtodo createRootWindow() de HTMLLoader. O seguinte cdigo cria um objeto NativeWindowInitOptions para uma janela de utilitrio:
var options:NativeWindowInitOptions = new NativeWindowInitOptions(); options.systemChrome = NativeWindowSystemChrome.STANDARD; options.type = NativeWindowType.UTILITY options.transparent = false; options.resizable = false; options.maximizable = false;

No permitido definir systemChrome como standard quando transparent true ou quando type lightweight. Nota: No possvel definir as propriedades de inicializao de uma janela criada com a funo JavaScript window.open(). No entanto, voc pode ignorar como elas so criadas implementando sua prpria classe HTMLHost. Para obter mais informaes, consulte Tratamento de chamadas JavaScript de window.open() na pgina 1005.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

882

Quando criar uma janela com a classe mx:Window do Flex, especifique as propriedades de inicializao no prprio objeto Window, seja na declarao MXML correspondente ou no cdigo que cria a janela. O objeto NativeWindow subjacente s criado quando voc chama o mtodo open(). Uma vez aberta uma janela, no possvel alterar essas propriedades de inicializao.

Criao da janela inicial do aplicativo

Adobe AIR 1.0 e posterior O AIR cria a janela inicial do aplicativo com base nas propriedades especificadas no descritor do aplicativo e carrega o arquivo mencionado no elemento de contedo. O elemento de contedo deve referenciar um arquivo SWF ou um arquivo HTML. A janela inicial pode ser a janela principal do seu aplicativo ou pode simplesmente servir para iniciar uma ou mais janelas. No necessrio torn-la visvel.

Criao da janela inicial com o ActionScript

Adobe AIR 1.0 e posterior Quando voc cria um aplicativo AIR usando o ActionScript, a classe principal do aplicativo deve estender a classe Sprite (ou uma subclasse dela). Esta classe funciona como o principal ponto de entrada do aplicativo. Quando o seu aplicativo iniciado, o AIR cria uma janela e uma ocorrncia da classe principal e adiciona a ocorrncia ao palco da janela. Para acessar a janela, voc pode monitorar o evento addedToStage e utilizar a propriedade nativeWindow do objeto Stage para obter uma referncia ao objeto NativeWindow. Este exemplo ilustra a estrutura bsica da classe principal de um aplicativo AIR criado com o ActionScript:
package { import flash.display.NativeWindow; import flash.display.Sprite; import flash.events.Event; public class MainClass extends Sprite { private var mainWindow:NativeWindow; public function MainClass(){ this.addEventListener(Event.ADDED_TO_STAGE, initialize); } private function initialize(event:Event):void{ mainWindow = this.stage.nativeWindow; //perform initialization... mainWindow.activate(); //show the window } } }

Nota: Tecnicamente, voc PODE acessar a propriedade nativeWindow na funo constructor da classe principal. No entanto, este um caso especial que se aplica apenas janela do aplicativo inicial. Ao criar um aplicativo no Flash Professional, a classe de documento principal criada automaticamente se voc no criar a sua prpria em um arquivo separado do ActionScript. Voc pode acessar o objeto NativeWindow para a janela inicial usando a propriedade nativeWindow. Por exemplo, o cdigo a seguir ativa a janela principal no estado maximizado (a partir da linha de tempo):

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

883

import flash.display.NativeWindow; var mainWindow:NativeWindow = this.stage.nativeWindow; mainWindow.maximize(); mainWindow.activate();

Criao da janela inicial com o Flex

Adobe AIR 1.0 e posterior Ao criar um aplicativo AIR com a estrutura do Flex, use mx:WindowedApplication como o elemento raiz do seu principal arquivo MXML. (Voc pode usar o componente mx:Application, mas ele no d suporte a todos os recursos disponveis no AIR.) O componente WindowedApplication funciona como o ponto de entrada inicial do aplicativo. Quando voc inicia o aplicativo, o AIR cria uma janela nativa, inicializa a estrutura do Flex e adiciona o objeto WindowedApplication ao palco da janela. Ao trmino da seqncia de inicializao, o objeto WindowedApplication despacha um evento applicationComplete. Acesse o objeto da janela de rea de trabalho com a propriedade nativeWindow da ocorrncia de WindowedApplication. O exemplo abaixo cria um componente WindowedApplication simples que define suas coordenadas x e y:
<?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" applicationComplete="placeWindow()"> <mx:Script> <![CDATA[ private function placeWindow():void{ this.nativeWindow.x = 300; this.nativeWindow.y = 300; } ]]> </mx:Script> <mx:Label text="Hello World" horizontalCenter="0" verticalCenter="0"/> </mx:WindowedApplication>

Criao de um objeto NativeWindow

Adobe AIR 1.0 e posterior Para criar um NativeWindow, passe um objeto NativeWindowInitOptions para o construtor NativeWindow:
var options:NativeWindowInitOptions = new NativeWindowInitOptions(); options.systemChrome = NativeWindowSystemChrome.STANDARD; options.transparent = false; var newWindow:NativeWindow = new NativeWindow(options);

A janela no exibida at voc definir a propriedade visible como true ou chamar o mtodo activate(). Uma vez criada a janela, voc pode inicializar suas propriedades e carregar contedo nela usando as tcnicas de propriedade de palco e lista de exibio do Flash.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

884

Em quase todos os casos, voc deve definir a propriedade de palco scaleMode de uma nova janela nativa como noScale (use a constante StageScaleMode.NO_SCALE). Os modos de dimensionamento do Flash foram desenvolvidos para situaes em que o autor do aplicativo no sabe de antemo a proporo do espao de exibio do aplicativo. Os modos de dimensionamento permitem que o autor escolha o melhor ajuste: recorte o contedo, aumente ou compacte o contedo ou preencha-o com espao vazio. Desde que voc controle o espao de exibio no AIR (o quadro da janela), pode dimensionar a janela conforme o contedo ou vice-versa, sem comprometer o resultado final. O modo de dimensionamento de janelas Flex e HTML definido como noScale automaticamente. Nota: Para determinar os tamanhos mximo e mnimo de uma janela permitidos no sistema operacional atual, use as seguintes propriedades estticas da classe NativeWindow:
var maxOSSize:Point = NativeWindow.systemMaxSize; var minOSSize:Point = NativeWindow.systemMinSize;

Criao de uma janela HTML

Adobe AIR 1.0 e posterior Para criar uma janela HTML, voc pode chamar o mtodo JavaScript Window.open() ou o mtodo createRootWindow() da classe HTMLLoader do AIR. O contedo HTML em qualquer caixa de proteo de segurana pode usar o mtodo JavaScript Window.open() padro. Se o contedo estiver sendo executado fora da caixa de proteo do aplicativo, o mtodo open() s poder ser chamado em resposta a interaes do usurio, como cliques do mouse ou pressionamentos de tecla. Quando open() chamado, criada uma janela com o cromo do sistema para exibir o contedo na URL especificada. Por exemplo:
newWindow = window.open("xmpl.html", "logWindow", "height=600, width=400, top=10, left=10");

Nota: Voc pode estender a classe HTMLHost no ActionScript para personalizar a janela criada com a funo JavaScript window.open(). Consulte Sobre estender a classe HTMLHost na pgina 997. O contedo na caixa de proteo de segurana do aplicativo tem acesso ao mtodo de criao de janelas mais eficiente, HTMLLoader.createRootWindow(). Com ele, voc pode especificar todas as opes de criao de uma nova janela. Por exemplo, o seguinte cdigo JavaScript cria uma janela do tipo leve sem cromo do sistema e com tamanho de 300x400 pixels:
var options = new air.NativeWindowInitOptions(); options.systemChrome = "none"; options.type = "lightweight"; var windowBounds = new air.Rectangle(200,250,300,400); newHTMLLoader = air.HTMLLoader.createRootWindow(true, options, true, windowBounds); newHTMLLoader.load(new air.URLRequest("xmpl.html"));

Nota: Se o contedo carregado por uma nova janela estiver fora da caixa de proteo de segurana do aplicativo, o objeto Window no ter as propriedades do AIR: runtime, nativeWindow ou htmlLoader. Ao criar uma janela transparente, o contedo SWF integrado no HTML carregado nessa janela nem sempre exibido. Voc deve definir o parmetro wmode do objeto ou a tag integrada utilizada para fazer referncia ao arquivo SWF para opaque ou transparent. O valor padro de wmode window e, por padro, o contedo SWF no exibido em janelas transparentes. O contedo PDF no pode ser exibido em janelas transparentes, no importando com o valor wmode est definido. (Antes da verso AIR 1.5.2, o contedo SWF tambm no podia ser exibido em janelas transparentes.)

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

885

As janelas criadas com o mtodo createRootWindow() permanecem independentes da janela de abertura. As propriedades parent e opener do objeto JavaScript Window so null. A janela de abertura pode acessar o objeto Window da nova janela usando a referncia a HTMLLoader retornada pela funo createRootWindow(). No contexto do exemplo anterior, a instruo newHTMLLoader.window faria referncia ao objeto JavaScript Window da janela criada. Nota: A funo createRootWindow() pode ser chamada no JavaScript e no ActionScript.

Criao de uma classe mx:Window

Adobe AIR 1.0 e posterior Para criar uma classe mx:Window, crie um arquivo MXML usando mx:Window como a tag raiz ou chame o construtor de classe Window diretamente. O exemplo abaixo cria e mostra uma mx:Window chamando o construtor Window:
var newWindow:Window = new Window(); newWindow.systemChrome = NativeWindowSystemChrome.NONE; newWindow.transparent = true; newWindow.title = "New Window"; newWindow.width = 200; newWindow.height = 200; newWindow.open(true);

Adio de contedo a uma janela

Adobe AIR 1.0 e posterior O tipo de uma janela do AIR determina a maneira como voc adiciona contedo a ela. Por exemplo, as linguagens MXML e HTML permitem definir o contedo bsico da janela declarativamente. possvel incorporar recursos nos arquivos SWF do aplicativo ou carreg-los a partir de arquivos de aplicativo separados. O contedo Flex, Flash e HTML pode ser criado dinamicamente e adicionado a uma janela de forma dinmica. Quando voc carrega contedo SWF, ou HTML com JavaScript, deve levar em considerao o modelo de segurana do AIR. Qualquer contedo existente na caixa de proteo de segurana do aplicativo, ou seja, contedo instalado com seu aplicativo e carregvel com o esquema de URL app:, tem privilgios totais para acessar todas as APIs do AIR. Qualquer contedo carregado de fora dessa caixa de proteo no pode acessar as APIs do AIR. O contedo JavaScript fora da caixa de proteo do aplicativo no pode usar as propriedades runtime, nativeWindow ou htmlLoader do objeto JavaScript Window. Para permitir cdigo entre scripts seguro, voc pode usar uma ponte de caixa de proteo para disponibilizar uma interface limitada entre contedo de aplicativo e contedo que no de aplicativo. No contedo HTML, tambm possvel mapear pginas do seu aplicativo para uma caixa de proteo que no seja de aplicativo, de maneira que essa pgina possa cruzar scripts de contedo externo. Consulte Segurana do AIR na pgina 1063. Carregamento de arquivo ou imagem SWF Voc pode carregar arquivos ou imagens SWF do Flash na lista de exibio de uma janela nativa usando a classe flash.display.Loader:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

886

package { import import import import

flash.display.Sprite; flash.events.Event; flash.net.URLRequest; flash.display.Loader;

public class LoadedSWF extends Sprite { public function LoadedSWF(){ var loader:Loader = new Loader(); loader.load(new URLRequest("visual.swf")); loader.contentLoaderInfo.addEventListener(Event.COMPLETE,loadFlash); } private function loadFlash(event:Event):void{ addChild(event.target.loader); } } }

Nota: Arquivos SWF mais antigos criados com o ActionScript 1 ou 2 compartilham estados globais, como definies de classe, singletons e variveis globais, se carregados na mesma janela. Se tal arquivo SWF depender de estados globais intocados para funcionar corretamente, no ser possvel carreg-lo mais de uma vez na mesma janela nem carreg-lo na mesma janela como outro arquivo SWF usando variveis e definies de classe de sobreposio. Este contedo pode ser carregado em janelas separadas. Carregamento de contedo HTML em um objeto NativeWindow Para carregar contedo HTML em um NativeWindow, voc pode adicionar um objeto HTMLLoader ao palco da janela e carregar o contedo HTML no HTMLLoader ou criar uma janela que j contenha um objeto HTMLLoader usando o mtodo HTMLLoader.createRootWindow(). O seguinte exemplo mostra contedo HTML em uma rea de exibio de 300 por 500 pixels no palco de uma janela nativa:
//newWindow is a NativeWindow instance var htmlView:HTMLLoader = new HTMLLoader(); htmlView.width = 300; htmlView.height = 500; //set the stage so display objects are added to the top-left and not scaled newWindow.stage.align = "TL"; newWindow.stage.scaleMode = "noScale"; newWindow.stage.addChild( htmlView ); //urlString is the URL of the HTML page to load htmlView.load( new URLRequest(urlString) );

Para carregar uma pgina HTML em um aplicativo do Flex, use o componente HTML do Flex. O contedo SWF em um arquivo HTML no exibido se a janela utilizar transparncia (propriedade transparent da janela true) a no ser que o parmetro wmode do objeto ou da tag integrada utilizada para referncia ao arquivo SWF esteja definido em opaque ou transparent. Como o valor padro de wmode window, o contedo SWF no exibido em uma janela transparente. O contedo do PDF no exibido em uma janela transparente, no importando como o valor wmode utilizado. Alm disso, o contedo SWF ou PDF no exibido se o controle HTMLLoader estiver dimensionado ou se a propriedade HTMLLoader alpha estiver definida em um valor diferente de 1.0.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

887

Adicionar contedo SWF como sobreposio em uma janela HTML Como as janelas HTML so contidas em uma ocorrncia de NativeWindow, possvel adicionar objetos de exibio do Flash tanto acima quanto abaixo da camada HTML na lista de exibio. Para adicionar um objeto de exibio acima da camada HTML, use o mtodo addChild() da propriedade window.nativeWindow.stage. O mtodo addChild() adiciona contedo em camada acima de qualquer contedo existente na janela. Para adicionar um objeto de exibio abaixo da camada HTML, use o mtodo addChildAt() da propriedade
window.nativeWindow.stage, passando um valor de zero para o parmetro index. Colocar um objeto no ndice zero

movimenta o contedo existente, inclusive a exibio HTML, uma camada acima e insere o novo contedo na parte inferior. Para que o contedo disposto abaixo da pgina HTML fique visvel, defina a propriedade paintsDefaultBackground do objeto HTMLlLoader como false. Alm disso, quaisquer elementos da pgina que tm uma cor de plano de fundo definida no ficaro transparentes. Por exemplo, se voc definir uma cor de plano de fundo para o elemento body da pgina, nenhuma parte dela ficar transparente. O exemplo a seguir ilustra como adicionar objetos de exibio do Flash na forma de sobreposies e bases a uma pgina HTML. O exemplo cria dois objetos de forma simples, adiciona um abaixo do contedo HTML e um acima. O exemplo tambm atualiza a posio da forma com base no evento enterFrame.
<html> <head> <title>Bouncers</title> <script src="AIRAliases.js" type="text/javascript"></script> <script language="JavaScript" type="text/javascript"> air.Shape = window.runtime.flash.display.Shape; function Bouncer(radius, color){ this.radius = radius; this.color = color; //velocity this.vX = -1.3; this.vY = -1; //Create a Shape object and draw a circle with its graphics property this.shape = new air.Shape(); this.shape.graphics.lineStyle(1,0); this.shape.graphics.beginFill(this.color,.9); this.shape.graphics.drawCircle(0,0,this.radius); this.shape.graphics.endFill(); //Set the starting position this.shape.x = 100; this.shape.y = 100;

//Moves the sprite by adding (vX,vY) to the current position this.update = function(){ this.shape.x += this.vX; this.shape.y += this.vY; //Keep the sprite within the window if( this.shape.x - this.radius < 0){ this.vX = -this.vX; }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

888

if( this.shape.y - this.radius < 0){ this.vY = -this.vY; } if( this.shape.x + this.radius > window.nativeWindow.stage.stageWidth){ this.vX = -this.vX; } if( this.shape.y + this.radius > window.nativeWindow.stage.stageHeight){ this.vY = -this.vY; } }; } function init(){ //turn off the default HTML background window.htmlLoader.paintsDefaultBackground = false; var bottom = new Bouncer(60,0xff2233); var top = new Bouncer(30,0x2441ff); //listen for the enterFrame event window.htmlLoader.addEventListener("enterFrame",function(evt){ bottom.update(); top.update(); }); //add the bouncing shapes to the window stage window.nativeWindow.stage.addChildAt(bottom.shape,0); window.nativeWindow.stage.addChild(top.shape); } </script> <body onload="init();"> <h1>de Finibus Bonorum et Malorum</h1> <p>Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.</p> <p style="background-color:#FFFF00; color:#660000;">This paragraph has a background color.</p> <p>At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis praesentium voluptatum deleniti atque corrupti quos dolores et quas molestias excepturi sint occaecati cupiditate non provident, similique sunt in culpa qui officia deserunt mollitia animi, id est laborum et dolorum fuga.</p> </body> </html>

Este exemplo faz uma introduo rudimentar a algumas tcnicas avanadas que cruzam os limites entre o JavaScript e o ActionScript no AIR. Se voc no estiver familiarizado em utilizar objetos de exibio ActionScript, consulte Programao de exibio na pgina 145 no Guia do desenvolvedor ActionScript 3.0.

Exemplo: Criao de uma janela nativa

Adobe AIR 1.0 e posterior O exemplo abaixo mostra como criar uma janela nativa:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

889

public function createNativeWindow():void { //create the init options var options:NativeWindowInitOptions = new NativeWindowInitOptions(); options.transparent = false; options.systemChrome = NativeWindowSystemChrome.STANDARD; options.type = NativeWindowType.NORMAL; //create the window var newWindow:NativeWindow = new NativeWindow(options); newWindow.title = "A title"; newWindow.width = 600; newWindow.height = 400; newWindow.stage.align = StageAlign.TOP_LEFT; newWindow.stage.scaleMode = StageScaleMode.NO_SCALE; //activate and show the new window newWindow.activate(); }

Gerenciamento de janelas
Adobe AIR 1.0 e posterior Use as propriedades e os mtodos da classe NativeWindow para gerenciar a aparncia, o comportamento e o ciclo de vida das janelas de rea de trabalho. Nota: Ao usar a estrutura do Flex, em geral melhor gerenciar o comportamento da janela usando as classes da estrutura. A maioria das propriedades e mtodos NativeWindow podem ser acessados atravs das classes mx:WindowedApplication e mx:Window classes.

Obteno de uma ocorrncia de NativeWindow

Adobe AIR 1.0 e posterior Para manipular uma janela, primeiro voc deve obter a ocorrncia dela. A ocorrncia da janela pode ser obtida em um dos seguintes lugares:

O construtor nativo de janela usado para criar a janela:

var win:NativeWindow = new NativeWindow(initOptions);

A propriedade nativeWindow do estgio da janela:

var win:NativeWindow = stage.nativeWindow;

A propriedade stage de um objeto de exibio na janela:

var win:NativeWindow = displayObject.stage.nativeWindow;

A propriedade target de um evento de janela nativa despachada pela janela:

private function onNativeWindowEvent(event:NativeWindowBoundsEvent):void { var win:NativeWindow = event.target as NativeWindow; }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

890

A propriedade nativeWindow de uma pgina HTML exibida na janela:

var win:NativeWindow = htmlLoader.window.nativeWindow;

As propriedades activeWindow e openedWindows do objeto NativeApplication:

var nativeWin:NativeWindow = NativeApplication.nativeApplication.activeWindow; var firstWindow:NativeWindow = NativeApplication.nativeApplication.openedWindows[0]; NativeApplication.nativeApplication.activeWindow faz referncia janela ativa de um aplicativo (mas

retorna null se a janela ativa no uma janela deste aplicativo AIR). A matriz
NativeApplication.nativeApplication.openedWindows contm todas as janelas de um aplicativo AIR que

no foram fechadas. Como os objetos mx:WindowedApplication e Window do Flex so objetos de exibio, voc pode fazer referncia facilmente janela do aplicativo em um arquivo MXML usando a propriedade stage, da seguinte maneira:
<?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" applicationComplete="init();"> <mx:Script> <![CDATA[ import flash.display.NativeWindow; public function init():void{ var appWindow:NativeWindow = this.stage.nativeWindow; //set window properties appWindow.visible = true; } ]]> </mx:Script> </WindowedApplication

Nota: At o componente WindowedApplication ou Window ser adicionado ao palco da janela pela estrutura do Flex, a propriedade stage do componente null. Este comportamento consistente com o do componente Application do Flex, mas significa que no possvel acessar o palco ou a ocorrncia de NativeWindow em ouvintes de eventos que ocorrem anteriormente no ciclo de inicializao dos componentes WindowedApplication e Window, como creationComplete. seguro acessar o palco e a ocorrncia de NativeWindow quando o evento applicationComplete despachado.

Ativar, mostrar e ocultar janelas

Adobe AIR 1.0 e posterior Para ativar uma janela, chame o mtodo activate() de NativeWindow. A ativao de uma janela a traz para frente, d a ela foco do teclado e do mouse e, se necessrio, a torna visvel mediante a restaurao da janela ou a definio da propriedade visible como true. A ativao de uma janela no altera a ordem de outras janelas do aplicativo. A chamada do mtodo activate() faz com que a janela despache um evento activate. Para mostrar uma janela oculta sem ativ-la, defina a propriedade visible como true. Isso traz a janela para frente, mas no atribui o foco para ela. Para ocultar uma janela de forma que no seja exibida, defina sua propriedade visible como false. Ocultar uma janela suprime a exibio tanto da janela quanto de qualquer cone relacionado na barra de tarefas e, no Mac OS X, a entrada no menu Janelas.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

891

Quando voc altera a visibilidade de uma janela, a visibilidade de quaisquer janelas de propriedade dessa janela tambm alterada. Por exemplo, se voc ocultar uma janela, todas as janelas de sua propriedade tambm ficaro ocultas. Nota: No Mac OS X, no possvel ocultar totalmente uma janela minimizada que tenha um cone na parte de janela do encaixe. Se a propriedade visible est definida como false em uma janela minimizada, o cone de encaixe da janela continua sendo exibido. Se o usurio clica no cone, a janela restaurada para um estado visvel e exibida.

Alterao da ordem de exibio de janelas

Adobe AIR 1.0 e posterior O AIR oferece diversos mtodos para alterar diretamente a ordem de exibio das janelas. possvel mover uma janela para o comeo ou o final da ordem de exibio, bem como colocar uma janela em cima de outra ou atrs dela. Ao mesmo tempo, o usurio pode reordenar as janelas ativando-as. Voc pode manter uma janela em frente de outras definindo sua propriedade alwaysInFront como true. Se mais de uma janela tiver essa configurao, a ordem de exibio dessas janelas ser definida entre elas, mas sempre sero organizadas acima das janelas cuja propriedade alwaysInFront esteja definida como false. As janelas que esto no primeiro grupo tambm so exibidas acima das janelas de outros aplicativos, mesmo quando o aplicativo AIR no est ativo. Como esse comportamento pode interromper o trabalho do usurio, definir alwaysInFront como true algo que s deve ser feito quando necessrio e apropriado. Os exemplos de usos justificados incluem:

Janelas pop-up temporrias de controles, como dicas de ferramentas, listas pop-up, menus personalizados e caixas
de combinao. Como essas janelas devem ser fechadas quando perdem o foco, pode-se evitar a dor de cabea de impedir um usurio de ver outra janela.

Mensagens de erro e alertas extremamente urgentes. Quando pode ocorrer uma alterao irrevogvel se o usurio
no responde de imediato, pode ser justificvel trazer uma janela de alerta para frente. No entanto, a maioria dos erros e alertas pode ser tratada na ordem de exibio normal das janelas.

Janelas pop-up de curta durao.

Nota: O AIR no impe o uso apropriado da propriedade alwaysInFront. Entretanto, se o seu aplicativo interrompe o fluxo de trabalho de um usurio, possivelmente ser enviado para a lixeira desse mesmo usurio. Se uma janela for proprietria de outras, essas outras so sempre ordenadas sua frente. Se voc chamar orderToFront() ou definir alwaysInFront como true em uma janela que seja proprietria de outras, as janelas subordinadas so reordenadas com a janela proprietria em frente s outras janelas, mas as janelas subordinadas ainda so exibidas na frente da proprietria. Chamar os mtodos de ordenao de janelas em janelas subordinadas funciona normamente entre janelas de propriedade da mesma janela, mas tambm pode alterar a ordem de todo o grupo de janelas subordinadas em relao a janelas fora desse grupo. Por exemplo, se voc chamar orderToFront() em uma janela subordinada, essa janela, sua proprietria e quaisquer outras janelas subordinadas mesma proprietria so movidos para a frente da ordem de exibio de janelas. A classe NativeWindow oferece estas propriedades e mtodos para definir a ordem de exibio de uma janela em relao a outras janelas:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

892

Membro propriedade alwaysInFront

Descrio Especifica se a janela exibida no primeiro grupo de janelas. Em quase todos os casos, false a melhor configurao. Alterar o valor de false para true traz a janela para frente de todas as janelas (mas no a ativa). Alterar o valor de true para false coloca a janela atrs das demais janelas do primeiro grupo, mas ainda na frente de outras. Definir a propriedade de uma janela com seu valor atual no altera a ordem de exibio. A configurao alwaysInFront no tem nenhum efeito nas janelas de propriedade de outra janela.

orderToFront() orderInFrontOf() orderToBack() orderBehind() activate()

Traz a janela para frente. Coloca a janela diretamente frente de uma determinada janela. Envia a janela para trs de outras janelas. Coloca a janela diretamente atrs de uma determinada janela. Traz a janela para frente (alm de torn-la visvel e de lhe atribuir foco).

Nota: Se uma janela est oculta (visible false) ou minimizada, chamar os mtodos de ordem de exibio no surte nenhum efeito. No sistema operacional Linux, diferentes gerenciadores de janela foram regras diferentes, dependendo da ordem de exibio da janela:

Em alguns gerenciadores de janela, as janelas do utilitrio so sempre exibidas em frente s janelas normais. Em alguns gerenciadores de janela, uma janela de tela cheia com alwaysInFront definida como true sempre
exibida na frente de outras janelas que tambm tenham alwaysInFront definida como true.

Fechamento de janelas
Adobe AIR 1.0 e posterior Para fechar uma janela, use o mtodo NativeWindow.close(). Fechar uma janela descarrega o contedo dela; porm, se outros objeto tiverem referncias a esse contedo, os objetos de contedo no sero destrudos. O mtodo NativeWindow.close() executado de forma assncrona, e o aplicativo que est contido na janela continua a executar durante o processo de fechamento. O mtodo close despacha um evento close quando a operao de fechamento concluda. O objeto NativeWindow ainda tecnicamente vlido, mas o acesso maioria das propriedades e dos mtodos em uma janela fechada gera IllegalOperationError. No possvel reabrir uma janela fechada. Verifique a propriedade closed de uma janela para testar se a janela foi fechada. Para simplesmente ocultar a exibio de uma janela, defina a propriedade NativeWindow.visible como false. Se a propriedade Nativeapplication.autoExit true, o padro, o aplicativo encerrado ao ser fechada sua ltima janela. Quaisquer janelas que tenham uma proprietria so fechadas quando a proprietria fechada. As janelas que so propriedade de outra no despacham um evento closing e, portanto, no podem impedir seu fechamento. Um evento close despachado.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

893

Permisso do cancelamento de operaes de janela

Adobe AIR 1.0 e posterior Quando uma janela usa o cromo do sistema, a interao do usurio com ela pode ser cancelada monitorando ou cancelando o comportamento padro dos eventos apropriados. Por exemplo, quando um usurio clica no boto Fechar do cromo do sistema, o evento closing despachado. Se algum ouvinte registrado chamar o mtodo preventDefault() do evento, a janela no ser fechada. Quando uma janela no usa o cromo do sistema, os eventos de notificao referentes s alteraes pretendidas no so despachados automaticamente antes de a alterao ser feita. Por isso, se voc chamar os mtodos para fechar uma janela ou se alterar o estado dela ou definir qualquer uma das propriedades de limites de janela, a alterao no poder ser cancelada. Para notificar os componentes do seu aplicativo antes que seja feita uma alterao de janela, a lgica do aplicativo poder despachar o evento de notificao relevante usando o mtodo dispatchEvent() da janela. Por exemplo, a seguinte lgica implementa um manipulador de eventos cancelvel para o boto Fechar de uma janela:
public function onCloseCommand(event:MouseEvent):void{ var closingEvent:Event = new Event(Event.CLOSING,true,true); dispatchEvent(closing); if(!closingEvent.isDefaultPrevented()){ win.close(); } }

O mtodo dispatchEvent() retorna false se o mtodo preventDefault() do evento chamado por um ouvinte. No entanto, ele tambm pode retornar false por outros motivos, portanto melhor usar o mtodo isDefaultPrevented() explicitamente para testar se a alterao deve ser cancelada.

Maximizao, minimizao e restaurao de uma janela

Adobe AIR 1.0 e posterior Para maximizar a janela, use o mtodo maximize() da classe NativeWindow.
myWindow.maximize();

Para minimizar a janela, use o mtodo minimize() de NativeWindow.

myWindow.minimize();

Para restaurar a janela (isto , coloc-la novamente no tamanho em que estava antes de ser minimizada ou maximizada), use o mtodo restore() de NativeWindow.
myWindow.restore();

Uma janela que tenha uma proprietria minimizada e restaurada quando a janela proprietria minimizada ou restaurada. Nenhum evento despachado pela janela subordinada quando minimizada porque sua proprietria est minimizada. Nota: O comportamento resultante da maximizao de uma janela do AIR diferente do comportamento padro do Mac OS X. Em vez de alternar entre um tamanho padro definido pelo aplicativo e o ltimo tamanho definido pelo usurio, as janelas do AIR alternam entre o ltimo tamanho definido pelo aplicativo ou pelo usurio e a rea til total da tela.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

894

No sistema operacional Linux, diferentes gerenciadores de janela foram regras diferentes com relao a configurao do estado de exibio da janela:

Em alguns gerenciadores de janela, no possvel maximizar as janelas dos utilitrios. Se um tamanho mximo for definido para a janela, algumas janelas no permitiro a maximizao. Alguns outros
gerenciadores de janela definem o estado de exibio como maximizado, mas no redimensionam a janela. Em qualquer um dos casos, no despachado nenhum evento de alterao do estado de exibio.

Alguns gerenciadores de janela no cumprem as configuraes maximizable ou minimizable de janela.

Nota: No Linux, as propriedades da janela so alteradas de forma assncrona. Se voc alterar o estado de exibio em uma linha do programa e ler os valores na linha seguinte, o valor lido ainda refletir a configurao antiga. Em todas as plataformas, o objeto NativeWindow despacha o evento displayStateChange quando o estado de exibio muda. Se voc precisar realizar algumas aes com base no novo estado da janela, sempre faa isso em um manipulador de eventos displayStateChange. Consulte Monitorando eventos de janela na pgina 899.

Exemplo: minimizao, maximizao, restaurao e fechamento de uma janela

Adobe AIR 1.0 e posterior O seguinte aplicativo MXML demonstra os mtodos maximize(), minimize(), restore() e close() de janela:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

895

<?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical">

<mx:Script> <![CDATA[ public function minimizeWindow():void { this.stage.nativeWindow.minimize(); } public function maximizeWindow():void { this.stage.nativeWindow.maximize(); } public function restoreWindow():void { this.stage.nativeWindow.restore(); } public function closeWindow():void { this.stage.nativeWindow.close(); } ]]> </mx:Script> <mx:VBox> <mx:Button <mx:Button <mx:Button <mx:Button </mx:VBox>

label="Minimize" click="minimizeWindow()"/> label="Restore" click="restoreWindow()"/> label="Maximize" click="maximizeWindow()"/> label="Close" click="closeWindow()"/>

</mx:WindowedApplication>

O seguinte exemplo do ActionScript para Flash cria quatro campos de texto clicveis que acionam os mtodos minimize(), maximize(), restore() e close() de NativeWindow:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

896

package { import flash.display.Sprite; import flash.events.MouseEvent; import flash.text.TextField; public class MinimizeExample extends Sprite { public function MinimizeExample():void { var minTextBtn:TextField = new TextField(); minTextBtn.x = 10; minTextBtn.y = 10; minTextBtn.text = "Minimize"; minTextBtn.background = true; minTextBtn.border = true; minTextBtn.selectable = false; addChild(minTextBtn); minTextBtn.addEventListener(MouseEvent.CLICK, onMinimize); var maxTextBtn:TextField = new TextField(); maxTextBtn.x = 120; maxTextBtn.y = 10; maxTextBtn.text = "Maximize"; maxTextBtn.background = true; maxTextBtn.border = true; maxTextBtn.selectable = false; addChild(maxTextBtn); maxTextBtn.addEventListener(MouseEvent.CLICK, onMaximize); var restoreTextBtn:TextField = new TextField(); restoreTextBtn.x = 230; restoreTextBtn.y = 10; restoreTextBtn.text = "Restore"; restoreTextBtn.background = true; restoreTextBtn.border = true; restoreTextBtn.selectable = false; addChild(restoreTextBtn); restoreTextBtn.addEventListener(MouseEvent.CLICK, onRestore); var closeTextBtn:TextField = new TextField(); closeTextBtn.x = 340; closeTextBtn.y = 10; closeTextBtn.text = "Close Window"; closeTextBtn.background = true; closeTextBtn.border = true; closeTextBtn.selectable = false; addChild(closeTextBtn);

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

897

closeTextBtn.addEventListener(MouseEvent.CLICK, onCloseWindow); } function onMinimize(event:MouseEvent):void { this.stage.nativeWindow.minimize(); } function onMaximize(event:MouseEvent):void { this.stage.nativeWindow.maximize(); } function onRestore(event:MouseEvent):void { this.stage.nativeWindow.restore(); } function onCloseWindow(event:MouseEvent):void { this.stage.nativeWindow.close(); } } }

Redimensionamento e movimentao de uma janela

Adobe AIR 1.0 e posterior Quando uma janela usa o cromo do sistema, o cromo oferece controles de arrastar que permitem redimensionar a janela e moviment-la na rea de trabalho. Se uma janela no usa o cromo do sistema, adicione seus prprios controles para que o usurio possa redimensionar e movimentar a janela. Nota: Para redimensionar ou movimentar uma janela, primeiro voc deve obter uma referncia ocorrncia de NativeWindow. Para mais informaes sobre como obter uma referncia janela, consulte Obteno de uma ocorrncia de NativeWindow na pgina 889. Redimensionamento de uma janela Para permitir que um usurio redimensione uma janela de forma interativa, use o mtodo NativeWindowstartResize(). Quando esse mtodo chamado a partir de um evento mouseDown, a operao de redimensionamento orientada pelo mouse e executada quando o sistema operacional recebe um evento mouseUp. Quando chama startResize(), voc passa um argumento que especifica a borda ou o canto a partir do qual a janela deve ser redimensionada. Para definir o tamanho das janelas de forma programtica, defina as propriedades width, height ou bounds da janela nas dimenses desejadas. Quando voc define os limites, o tamanho da janela e a posio podem ser alterados ao mesmo tempo., No entanto, no h garantias da ordem de exibio das alteraes. Alguns gerenciadores de janela do Linux no permitem que janelas se estendam alm dos limites da tela da rea de trabalho. Nesses casos, o tamanho final da janela pode ser limitado devido ordem em que as propriedades so definidas, apesar de as alteraes resultarem em uma janela legal. Por exemplo, se voc alterar a altura e a posio y de uma janela perto da parte inferior da tela, a alterao na altura total pode no ocorrer quando for aplicada antes da alterao na posio y. Nota: No Linux, as propriedades da janela so alteradas de forma assncrona. Se voc redimensionar uma janela em uma linha do seu programa, e ler as dimenses na prxima, elas ainda vo refletir as configuraes antigas. Em todas as plataformas, o objeto NativeWindow despacha o evento resize quando a janela redimensionada. Se precisar realizar alguma ao, como dispor controles na janela, com base no novo tamanho ou estado da janela, sempre faa isso em um manipulador de eventos resize. Consulte Monitorando eventos de janela na pgina 899.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

898

O modo de dimensionamento do palco determina o comportamento do palco da janela e de seu contedo quando uma janela redimensionada. Lembre-se de que os modos de dimensionamento de palco devem ser usados em situaes em que o aplicativo no tem controle sobre o tamanho ou a proporo de seu espao de exibio, como o caso de um navegador da Web. Em geral, os melhores resultados so obtidos quando voc define a propriedade scaleMode do palco como StageScaleMode.NO_SCALE. Para que o contedo da janela seja dimensionado, tambm possvel definir os parmetros do contedo scaleX e scaleY em resposta s alteraes nos limites da janela. Movimentao de uma janela Para mover uma janela sem redimension-la, utilize o mtodo NativeWindow startMove(). Como acontece com o mtodo startResize(), quando voc chama o mtodo startMove() a partir de um evento mouseDown, o processo de movimentao orientado pelo mouse e executado quando o sistema operacional recebe um evento mouseUp. Para obter mais informaes, sobre os mtodos startResize() e startMove(), consulte a Referncia do ActionScript 3.0 para a plataforma Adobe Flash. Para mover uma janela em termos programticos, defina as propriedades x, y ou bounds da janela at a posio desejada. Quando voc define os limites, o tamanho da janela e a posio podem ser alterados ao mesmo tempo. Nota: No Linux, as propriedades da janela so alteradas de forma assncrona. Se voc mover uma janela em uma linha do programa e ler a posio na linha seguinte, o valor lido ainda refletir a configurao antiga. Em todas as plataformas, o objeto NativeWindow despacha o evento move quando a posio muda. Se voc precisar realizar algumas aes com base na nova posio da janela, sempre faa isso em um manipulador de eventos move. Consulte Monitorando eventos de janela na pgina 899.

Exemplo: redimensionamento e movimentao de janelas

Adobe AIR 1.0 e posterior O exemplo abaixo mostra como iniciar operaes de redimensionamento e movimentao em uma janela:
package { import flash.display.Sprite; import flash.events.MouseEvent; import flash.display.NativeWindowResize; public class NativeWindowResizeExample extends Sprite { public function NativeWindowResizeExample():void { // Fills a background area. this.graphics.beginFill(0xFFFFFF); this.graphics.drawRect(0, 0, 400, 300); this.graphics.endFill(); // Creates a square area where a mouse down will start the resize. var resizeHandle:Sprite = createSprite(0xCCCCCC, 20, this.width - 20, this.height - 20); resizeHandle.addEventListener(MouseEvent.MOUSE_DOWN, onStartResize); // Creates a square area where a mouse down will start the move. var moveHandle:Sprite = createSprite(0xCCCCCC, 20, this.width - 20, 0); moveHandle.addEventListener(MouseEvent.MOUSE_DOWN, onStartMove); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

899

public function createSprite(color:int, size:int, x:int, y:int):Sprite { var s:Sprite = new Sprite(); s.graphics.beginFill(color); s.graphics.drawRect(0, 0, size, size); s.graphics.endFill(); s.x = x; s.y = y; this.addChild(s); return s; } public function onStartResize(event:MouseEvent):void { this.stage.nativeWindow.startResize(NativeWindowResize.BOTTOM_RIGHT); } public function onStartMove(event:MouseEvent):void { this.stage.nativeWindow.startMove(); } } }

Monitorando eventos de janela

Adobe AIR 1.0 e posterior Para monitorar os eventos despachados por uma janela, registre um ouvinte na ocorrncia da janela. Por exemplo, para monitorar o evento closing, registre um ouvinte na janela, da seguinte maneira:
myWindow.addEventListener(Event.CLOSING, onClosingEvent);

Quando um evento despachado, a propriedade target faz referncia janela que o est enviando. A maioria dos eventos de janela tem duas mensagens relacionadas. A primeira mensagem sinaliza que uma alterao de janela iminente (e pode ser cancelada), enquanto a segunda indica que a alterao foi executada. Por exemplo, quando um usurio clica no boto Fechar de uma janela, a mensagem do evento closing despachada. Se nenhum ouvinte cancelar o evento, a janela ser fechada e o evento close ser despachado para qualquer ouvinte. Normalmente, os eventos de aviso, como closing, s so despachados quando o cromo do sistema foi usado para acionar um evento. Se voc chamar o mtodo de janela close(), por exemplo, o evento closing no ser despachado automaticamente (ser despachado apenas o evento close). No entanto, voc pode construir um objeto de evento closing e despach-lo usando o mtodo de janela dispatchEvent(). Os eventos de janela que despacham um objeto Event so:
Evento activate Descrio Despachado quando a janela recebe foco.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

900

Evento deactivate closing

Descrio Despachado quando a janela perde foco. Despachado quando a janela est prestes a fechar. Este evento s ocorre automaticamente quando o boto Fechar do cromo do sistema pressionado ou, no Mac OS X, quando chamado o comando Quit. Despachado quando a janela foi fechada.

close

Os eventos de janela que despacham um objeto NativeWindowBoundsEvent so:

Evento moving Descrio Despachado imediatamente depois que o canto superior esquerdo da janela muda de posio, seja como resultado da movimentao, do redimensionamento ou da alterao do estado de exibio da janela. Despachado depois que a posio do canto superior esquerdo alterada. Despachado imediatamente antes de a largura ou a altura da janela ser alterada, seja como resultado do redimensionamento ou de uma alterao no estado de exibio. Despachado aps uma alterao no tamanho da janela.

move resizing

resize

Para eventos NativeWindowBoundsEvent, voc pode usar as propriedades beforeBounds e afterBounds para determinar os limites da janela antes e depois da alterao iminente ou concluda. Os eventos de janela que despacham um objeto NativeWindowDisplayStateEvent so:
Evento displayStateChanging displayStateChange Descrio Despachado imediatamente antes de uma alterao no estado de exibio da janela. Despachado depois que o estado de exibio da janela foi alterado.

Para eventos NativeWindowDisplayStateEvent , voc pode usar as propriedades beforeDisplayState e afterDisplayState para determinar o estado de exibio da janela antes e depois da alterao iminente ou concluda. Em alguns gerenciadores de janela do Linux, um evento de alterao do estado de exibio no despachado quando uma janela com uma configurao de tamanho mximo maximizada. (A janela definida como estado de exibio mximo, mas no redimensionada).

Exibio de janelas em tela cheia

Adobe AIR 1.0 e posterior Definir a propriedade displayState da classe Stage como StageDisplayState.FULL_SCREEN_INTERACTIVE coloca a janela em modo de tela cheia, que permite entrada pelo teclado. (No contedo SWF em execuo em um navegador, a entrada pelo teclado no permitida). Para sair do modo de tela cheia, o usurio deve pressionar a tecla Escape. Nota: Alguns gerenciadores de janela do Linux no alteraro as dimenses de janela para encher a tela, caso um tamanho mximo seja definido para a janela (mas removero o cromo do sistema da janela). Por exemplo, o seguinte cdigo do Flex define um aplicativo simples do AIR que configura um terminal simples para tela cheia:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

901

<?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical" applicationComplete="init()" backgroundColor="0x003030" focusRect="false"> <mx:Script> <![CDATA[ private function init():void { stage.displayState = StageDisplayState.FULL_SCREEN_INTERACTIVE; focusManager.setFocus(terminal); terminal.text = "Welcome to the dumb terminal app. Press the ESC key to exit..\n"; terminal.selectionBeginIndex = terminal.text.length; terminal.selectionEndIndex = terminal.text.length; } ]]> </mx:Script> <mx:TextArea id="terminal" height="100%" width="100%" scroll="false" backgroundColor="0x003030" color="0xCCFF00" fontFamily="Lucida Console" fontSize="44"/> </mx:WindowedApplication>

O seguinte exemplo do ActionScript para Flash simula um terminal de texto simples em tela cheia:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Trabalho com janelas nativas do AIR

902

import import import import

flash.display.Sprite; flash.display.StageDisplayState; flash.text.TextField; flash.text.TextFormat;

public class FullScreenTerminalExample extends Sprite { public function FullScreenTerminalExample():void { var terminal:TextField = new TextField(); terminal.multiline = true; terminal.wordWrap = true; terminal.selectable = true; terminal.background = true; terminal.backgroundColor = 0x00333333; this.stage.displayState = StageDisplayState.FULL_SCREEN_INTERACTIVE; addChild(terminal); terminal.width = 550; terminal.height = 400; terminal.text = "Welcome to the dumb terminal application. Press the ESC key to exit.\n_"; var tf:TextFormat = new TextFormat(); tf.font = "Courier New"; tf.color = 0x00CCFF00; tf.size = 12; terminal.setTextFormat(tf); terminal.setSelection(terminal.text.length - 1, terminal.text.length); } }

ltima atualizao em 29/3/2011

903

Captulo 50: Exibio de telas no AIR

Adobe AIR 1.0 e posterior Use a classe Screen do Adobe AIR para acessar informaes sobre as telas de exibio anexadas a um computador ou dispositivo.

Mais tpicos da Ajuda

flash.display.Screen

Princpios bsicos das telas de exibio no AIR

Adobe AIR 1.0 e posterior

Medida da rea de trabalho virtual (Flex) Medida da rea de trabalho virtual (Flash)
A API de tela contm uma classe nica, Screen, que oferece membros estticos para obter informaes de tela do sistema e membros de ocorrncia para descrever uma tela especfica. Um sistema de computador pode ter vrios monitores ou exibies anexadas, que podem corresponder a diversas telas da rea de trabalho organizadas em um espao virtual. A classe Screen do AIR fornece informaes sobre as telas, sua organizao relativa e seu espao utilizvel. Se mais de um monitor for mapeado para a mesma tela, haver somente uma tela. Se o tamanho da tela maior que a rea de exibio do monitor, no h como determinar que parte da tela est visvel atualmente A tela representa uma rea de exibio independente da rea de trabalho. As telas so descritas como retngulos na rea de trabalho virtual. O canto superior esquerdo da tela designado como exibio principal a origem do sistema de coordenadas da rea de trabalho virtual. Todos os valores usados para descrever a tela so fornecidos em pixels.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Exibio de telas no AIR

904

Limites da tela Tela virtual Limites utilizveis Nessa organizao de telas, h duas telas na rea de trabalho virtual. As coordenadas do canto superior esquerdo da tela principal (n 1) so sempre (0,0). Se a organizao da tela for alterada para designar a tela n 2 como tela principal, as coordenadas da tela n 1 se tornaro negativas. Barras de menu, barras de tarefa e encaixes so excludos ao reportar limites utilizveis de uma tela.

Para obter informaes mais detalhadas sobre a funo da classe API, mtodos, propriedades e eventos, consulte a Referncia do ActionScript 3.0 para a plataforma Adobe Flash.

Enumerao das telas

Adobe AIR 1.0 e posterior Voc pode enumerar as telas da rea de trabalho virtual com os seguintes mtodos e propriedades de tela:
Mtodo ou Propriedade Screen.screens Descrio Oferece uma matriz de objetos Screen que descreve as telas disponveis. A ordem da matriz no significativa. Oferece o objeto Screen da tela principal. No Mac OS X, a tela principal a tela que exibe a barra de menu. No Windows, a tela principal a tela primria designada pelo sistema.

Screen.mainScreen

Screen.getScreensForRectangle() Oferece uma matriz de objetos Screen que descreve as telas intersectadas pelo retngulo determinado. O retngulo passado para este mtodo est em coordenadas de pixel na rea de trabalho virtual. Se nenhuma tela intersectar o retngulo, a matriz ficar vazia. Voc pode usar esse mtodo para descobrir em que telas a janela exibida.

No salve os valores retornados pelos mtodos e propriedades da classe Screen. O usurio ou sistema operacional pode alterar as telas disponveis e a respectiva disposio a qualquer momento. O exemplo a seguir usa a API da tela para mover uma janela entre vrias telas em resposta ao pressionamento das teclas de seta. Para mover a janela para a prxima tela, o exemplo obtm a matriz screens e a classifica verticalmente ou horizontalmente (dependendo da tecla de seta pressionada). Em seguida, o cdigo passa pela matriz classificada, comparando cada tela com as coordenadas da tela atual. Para identificar a tela atual da janela, o exemplo chama Screen.getScreensForRectangle(), passando nos limites da janela.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Exibio de telas no AIR

905

package { import import import import import import

flash.display.Sprite; flash.display.Screen; flash.events.KeyboardEvent; flash.ui.Keyboard; flash.display.StageAlign; flash.display.StageScaleMode;

public class ScreenExample extends Sprite { public function ScreenExample() { stage.align = StageAlign.TOP_LEFT; stage.scaleMode = StageScaleMode.NO_SCALE; stage.addEventListener(KeyboardEvent.KEY_DOWN,onKey); } private function onKey(event:KeyboardEvent):void{ if(Screen.screens.length > 1){ switch(event.keyCode){ case Keyboard.LEFT : moveLeft(); break; case Keyboard.RIGHT : moveRight(); break; case Keyboard.UP : moveUp(); break; case Keyboard.DOWN : moveDown(); break; } } } private function moveLeft():void{ var currentScreen = getCurrentScreen(); var left:Array = Screen.screens; left.sort(sortHorizontal); for(var i:int = 0; i < left.length - 1; i++){ if(left[i].bounds.left < stage.nativeWindow.bounds.left){ stage.nativeWindow.x += left[i].bounds.left - currentScreen.bounds.left; stage.nativeWindow.y += left[i].bounds.top - currentScreen.bounds.top; } } } private function moveRight():void{ var currentScreen:Screen = getCurrentScreen(); var left:Array = Screen.screens; left.sort(sortHorizontal); for(var i:int = left.length - 1; i > 0; i--){ if(left[i].bounds.left > stage.nativeWindow.bounds.left){ stage.nativeWindow.x +=

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Exibio de telas no AIR

906

left[i].bounds.left - currentScreen.bounds.left; stage.nativeWindow.y += left[i].bounds.top - currentScreen.bounds.top; } } } private function moveUp():void{ var currentScreen:Screen = getCurrentScreen(); var top:Array = Screen.screens; top.sort(sortVertical); for(var i:int = 0; i < top.length - 1; i++){ if(top[i].bounds.top < stage.nativeWindow.bounds.top){ stage.nativeWindow.x += top[i].bounds.left - currentScreen.bounds.left; stage.nativeWindow.y += top[i].bounds.top - currentScreen.bounds.top; break; } } } private function moveDown():void{ var currentScreen:Screen = getCurrentScreen(); var top:Array = Screen.screens; top.sort(sortVertical); for(var i:int = top.length - 1; i > 0; i--){ if(top[i].bounds.top > stage.nativeWindow.bounds.top){ stage.nativeWindow.x += top[i].bounds.left - currentScreen.bounds.left; stage.nativeWindow.y += top[i].bounds.top - currentScreen.bounds.top; break; } } } private function sortHorizontal(a:Screen,b:Screen):int{ if (a.bounds.left > b.bounds.left){ return 1; } else if (a.bounds.left < b.bounds.left){ return -1; } else {return 0;} } private function sortVertical(a:Screen,b:Screen):int{ if (a.bounds.top > b.bounds.top){ return 1; } else if (a.bounds.top < b.bounds.top){ return -1; } else {return 0;} } private function getCurrentScreen():Screen{ var current:Screen; var screens:Array = Screen.getScreensForRectangle(stage.nativeWindow.bounds); (screens.length > 0) ? current = screens[0] : current = Screen.mainScreen; return current; } } }

ltima atualizao em 29/3/2011

907

Captulo 51: Impresso

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os tempos de execuo do Flash (como o Adobe Flash Player e o Adobe AIR) podem se comunicar com a interface de impresso de um sistema operacional para que voc consiga passar as pginas para o spooler de impresso. Cada pgina enviado ao spooler pode ter contedo visvel, dinmico ou fora da tela do usurio, incluindo valores de banco de dados e texto dinmico. Alm disso, as propriedades da classe flash.printing.PrintJob contm valores com base nas configuraes da impressora do usurio, para que voc possa formatar as pginas adequadamente. O contedo a seguir detalha estratgias para uso dos mtodos e propriedades da classe flash.printing.PrintJob para criar um trabalho de impresso, ler as configuraes de impresso de um usurio e ajustar um trabalho de impresso com base no comentrio do aplicativo Flash e no sistema operacional do usurio.

Noes bsicas de impresso

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior No ActionScript 3.0, voc usa a classe PrintJob para criar instantneos de contedo de exibio a serem convertidos em uma representao de tinta e papel em uma impresso. Sob alguns aspectos, configurar o contedo para impresso o mesmo que configur-lo para exibio na tela: voc posiciona e classifica os elementos por tamanho para criar o layout desejado. No entanto, a impresso possui caractersticas nicas que a tornam diferente do layout de tela. Por exemplo, a resoluo usada por impressoras diferente da resoluo de monitores de computador. O contedo de uma tela do computador dinmico e pode ser alterado, enquanto o contedo impresso basicamente esttico, e no planejamento da impresso, as restries de tamanho da pgina fixa e a possibilidade de impresso de vrias pginas precisam ser consideradas. Embora essas diferenas paream bvias, importante t-las em mente ao configurar a impresso com o ActionScript. A impresso exata depende de uma combinao de valores especificados por voc e das caractersticas da impressora do usurio. A classe PrintJob contm propriedades que permitem determinar as caractersticas importantes da impressora do usurio. Conceitos e termos importantes A lista de referncia a seguir contm termos importantes relacionados impresso:
Spooler Uma parte do sistema operacional ou do software do driver da impressora que mantm o controle das pginas

que esto aguardando para serem impressas e as envia para a impressora quando ela estiver disponvel.
Orientao de pgina A rotao do contedo impresso em relao ao papel, horizontal (paisagem) ou vertical

(retrato).
Trabalho de impresso A pgina ou o conjunto de pginas que compem uma nica impresso.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Impresso

908

Impresso de uma pgina

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc usa uma ocorrncia da classe PrintJob para manipular a impresso. Para imprimir uma pgina bsica por meio do Flash Player ou do AIR, use estas quatro instrues em seqncia:

new PrintJob(): Cria uma nova ocorrncia do trabalho de impresso com o nome especificado. PrintJob.start(): Inicia o processo de impresso do sistema operacional chamando a caixa de dilogo de

impresso do usurio e preenche as propriedades somente leitura do trabalho de impresso.

PrintJob.addPage(): Contm os detalhes sobre o contedo do trabalho de impresso, incluindo o objeto Sprite

(e todos os filhos que ele contm), o tamanho da rea de impresso e se a impressora imprimir a imagem como um vetor ou um bitmap. Voc pode usar chamadas sucessivas para addPage() para imprimir vrias entidades grficas em vrias pginas.

PrintJob.send(): Envia as pginas para a impressora do sistema operacional.

Portanto, por exemplo, um script simples de trabalho de impresso (inclusive as instrues package, import e class para compilao):
package { import flash.printing.PrintJob; import flash.display.Sprite; public class BasicPrintExample extends Sprite { var myPrintJob:PrintJob = new PrintJob(); var mySprite:Sprite = new Sprite(); public function BasicPrintExample() { myPrintJob.start(); myPrintJob.addPage(mySprite); myPrintJob.send(); } } }

Nota: Esse exemplo tem o objetivo de mostrar os elementos bsicos de um script de trabalho de impresso e no contm nenhuma manipulao de erros. Para criar um script que responda corretamente a um usurio que cancela um trabalho de impresso, consulte Trabalho com excees e retornos na pgina 909. Para limpar as propriedades de um objeto PrintJob por qualquer motivo, defina a varivel PrintJob como null (como em myPrintJob = null).

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Impresso

909

Tarefas do tempo de execuo e impresso de sistema do Flash

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Devido aos tempos de execuo do Flash enviarem pginas para a interface de impresso do sistema operacional, observe as tarefas gerenciadas pelos tempos de execuo do Flash e tarefas gerenciadas pela interface de impresso do prprio sistema operacional. Os aplicativos Flash podem iniciar um trabalho de impresso, ler algumas configuraes de pgina de uma impressora, transmitir o contedo de um trabalho de impresso para o sistema operacional e verificar se o usurio ou o sistema cancelou um trabalho de impresso. Outros processos, como exibir caixas de dilogo especficas impressora, cancelar um trabalho de impresso no spool ou relatar o status da impressora, so todos manipulados pelo sistema operacional. Os tempos de execuo do Flash podem responder se h um problema ao iniciar ou formatar um trabalho de impresso, mas podem relatar apenas determinadas propriedades ou condies da interface de impresso do sistema operacional. Como desenvolvedor, seu cdigo precisa responder a essas propriedades ou condies.

Trabalho com excees e retornos

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Verifique se o mtodo PrintJob.start() retorna true antes de executar as chamadas addPage() e send(), no caso do usurio ter cancelado o trabalho de impresso. Uma maneira simples de verificar se esses mtodos foram cancelados antes de continuar delimit-los em uma instruo if, da seguinte maneira:
if (myPrintJob.start()) { // addPage() and send() statements here }

Se PrintJob.start() for true, o Print selecionado pelo usurio (ou um aplicativo Flash, como o Flash Player ou o AIR, iniciou um comando Print). Portanto, os mtodos addPage() e send() podem ser chamados. Alm disso, para ajudar a gerenciar o processo de impresso, os tempos de execuo do Flash emitem excees para o mtodo PrintJob.addPage() para que seja possvel capturar os erros e fornecer informaes e opes ao usurio. Se um mtodo PrintJob.addPage() falhar, voc tambm poder chamar outra funo ou parar o trabalho de impresso atual. Voc captura essas excees incorporando as chamadas de addPage() dentro de uma instruo try..catch, conforme no exemplo a seguir. No exemplo, [params] um alocador de espao para os parmetros que especificam o contedo real a ser impresso:
if (myPrintJob.start()) { try { myPrintJob.addPage([params]); } catch (error:Error) { // Handle error, } myPrintJob.send(); }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Impresso

910

Depois que o trabalho de impresso for iniciado, voc pode adicionar o contedo usando PrintJob.addPage() e verificar se isso gera uma exceo (por exemplo, se o usurio cancelou o trabalho de impresso). Se for gerada uma exceo, voc poder adicionar lgica instruo catch para fornecer informaes e opes ao usurio (ou ao tempo de execuo do Flash) ou poder parar o trabalho de impresso atual. Se voc adicionar a pgina com xito, poder continuar a enviar as pginas impressora usando PrintJob.send(). Se o tempo de execuo do Flash encontrar um problema quando enviar o trabalho de impresso para a impressora (por exemplo, se a impressora estiver offline), voc tambm poder capturar essa exceo e apresentar informaes ou mais opes (por exemplo, exibir o texto da mensagem ou fornecer um alerta dentro de uma animao). Por exemplo, voc pode atribuir texto novo a um campo de texto em uma instruo if..else, conforme mostrado no cdigo a seguir:
if (myPrintJob.start()) { try { myPrintJob.addPage([params]); } catch (error:Error) { // Handle error. } myPrintJob.send(); } else { myAlert.text = "Print job canceled"; }

Para obter um exemplo que funciona, consulte Exemplo de impresso: escala, corte e resposta na pgina 918.

Trabalho com propriedades da pgina

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Quando o usurio clica em OK na caixa de dilogo Imprimir e PrintJob.start() retorna true, ele pode acessar as propriedades definidas pelas configuraes da impressora. Essas configuraes incluem a largura e a altura do papel (pageHeight e pageWidth), e a orientao do contedo no papel. Como essas so configuraes da impressora, no controladas pelo tempo de execuo do Flash, voc no pode alter-las. Mas pode us-las para alinhar o contedo enviado para a impressora para que corresponda s configuraes atuais. Para obter mais informaes, consulte Configurao de tamanho, escala e orientao na pgina 912.

Configurao da renderizao de vetores ou de bitmaps

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Voc pode definir manualmente o trabalho de impresso para armazenar no spool cada pgina, como grficos de vetor ou uma imagem de bitmap. Em alguns casos, a impresso de vetores produz um arquivo de spool menor e uma imagem melhor do que a impresso de bitmap. No entanto, se o contedo incluir uma imagem de bitmap, e voc desejar preservar qualquer transparncia alfa ou efeitos de cor, dever imprimir a pgina como uma imagem de bitmap. Alm disso, uma impressora no-PostScript converte automaticamente todos os grficos de vetor em imagens de bitmap.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Impresso

911

possvel especificar a impresso de bitmap, indicando o objeto PrintJobOptions como terceiro parmetro de PrintJob.addPage(). Para o Flash Player e AIR anterior ao AIR 2, defina o parmetro printAsBitmap do objeto PrintJobOptions para
true, conforme o exemplo a seguir: var options:PrintJobOptions = new PrintJobOptions(); options.printAsBitmap = true; myPrintJob.addPage(mySprite, null, options);

Se voc no especificar um valor para o terceiro parmetro, o trabalho de impresso usar o padro, que a impresso de vetor. Para o AIR 2 e posterior, utilize a propriedade printMethod do objeto PrintJobOptions para especificar o mtodo de impresso. Essa propriedade aceita trs valores, definidos como constantes na classe PrintMethod:

PrintMethod.AUTO: Automaticamente selecione o melhor mtodo de impresso com base no contedo impresso.

Por exemplo, se a pgina consiste em texto, o mtodo de impresso vetorial selecionado. No entanto, se uma imagem de marca d'gua com transparncia alfa for sobreposta no texto, a impresso de bitmap selecionada para manter a transparncia.

PrintMethod.BITMAP: Fora a impresso bitmap, imprimindo independentemente do contedo PrintMethod.BITMAP: Fora a impresso vetor, imprimindo independentemente do contedo

Controle de tempo de instrues de trabalho de impresso

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O ActionScript 3.0 no restringe o objeto PrintJob a um nico quadro (como faziam as verses anteriores do ActionScript). No entanto, como o sistema operacional exibe informaes do status de impresso para o usurio depois que ele clicou no boto OK na caixa de dilogo Imprimir, voc deve chamar PrintJob.addPage() e PrintJob.send() assim que possvel para enviar as pginas para o spooler. Um atraso que atinja o quadro que contm a chamada do PrintJob.send() atrasar o processo de impresso. No ActionScript 3.0, h um tempo limite de script de 15 segundos. Portanto, o tempo entre cada instruo principal em uma seqncia de trabalho de impresso no pode exceder 15 segundos. Em outras palavras, o tempo limite de 15 segundos de script se aplica aos seguintes intervalos:

Entre PrintJob.start() e o primeiro PrintJob.addPage() Entre

PrintJob.addPage() e o prximo PrintJob.addPage()

Entre o ltimo PrintJob.addPage() e PrintJob.send()

Se qualquer um desses intervalos se estender por mais de 15 segundos, a chamada seguinte para o PrintJob.start(), na ocorrncia PrintJob, retornar false e o seguinte PrintJob.addPage() na ocorrncia PrintJob far com que o Flash Player ou o AIR emitam uma exceo de tempo de execuo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Impresso

912

Configurao de tamanho, escala e orientao

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A seo Impresso de uma pgina na pgina 908 fornece detalhes das etapas de um trabalho de impresso bsico, em que a sada reflete diretamente o equivalente impresso do tamanho e posio da tela da entidade grfica especificada. No entanto as impressoras usam resolues diferentes para impresso e podem ter configuraes que afetam contrariamente a aparncia da entidade grfica impressa. Os tempos de execuo do Flash podem ler configuraes de impresso de um sistema operacional, mas observe que essas propriedades so somente leitura: embora voc possa responder a seus valores, no pode defini-los. Portanto, por exemplo, voc pode localizar a configurao de tamanho da pgina da impressora e ajustar seu contedo para se adequar ao tamanho. Tambm possvel determinar as configuraes de margem e de orientao da pgina da impressora. Para responder s configuraes da impressora, especifique uma rea de impresso, ajuste a diferena entre a resoluo da tela e as medidas de ponto da impressora ou transforme o contedo para atender s configuraes de tamanho ou de orientao da impressora do usurio.

Uso de retngulos para a rea de impresso

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O mtodo PrintJob.addPage() permite especificar a regio de uma entidade grfica que voc deseja que seja impressa. O segundo parmetro, printArea, est na forma de um objeto Rectangle. H trs opes para fornecer um valor para esse parmetro:

Crie um objeto Rectangle com propriedades especficas e, em seguida, use esse retngulo na chamada de
addPage(), conforme no exemplo a seguir: private var rect1:Rectangle = new Rectangle(0, 0, 400, 200); myPrintJob.addPage(sheet, rect1);

Se voc ainda no tiver especificado um objeto Rectangle, poder fazer isso dentro da prpria chamada, como no
exemplo a seguir:
myPrintJob.addPage(sheet, new Rectangle(0, 0, 100, 100));

Se voc planejar fornecer valores para o terceiro parmetro na chamada de addPage(), mas no desejar especificar
um retngulo, poder usar null para o segundo parmetro, como no exemplo a seguir:
myPrintJob.addPage(sheet, null, options);

Comparao de pontos e pixels

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A largura e a altura do retngulo so valores em pixels. Uma impressora usa pontos como unidades de medida de impresso. Os pontos tm tamanho fsico fixo (1/72 polegadas), mas o tamanho de um pixel na tela depende da resoluo da tela especfica. A taxa de converso entre pixels e pontos depende das configuraes da impressora e se a entidade grfica est dimensionada. Um sprite no dimensionado, com 72 pixels de largura, ter uma polegada de largura na impresso, com um ponto igual a um pixel, independentemente da resoluo da tela. Voc pode usar as equivalncias a seguir para converter polegadas ou centmetros em twips (1/20 de um ponto) ou pontos:

1 ponto = 1/72 pol = 20 twips

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Impresso

913

1 pol = 72 pontos = 1440 twips 1 centmetro = 567 twips

Se voc omitir o parmetro printArea, ou se ele for passado incorretamente, a rea total da entidade grfica ser impressa.

Escala
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para dimensionar um objeto Sprite antes de imprimi-lo, defina as propriedades da escala (consulte Manipulao do tamanho e dimensionamento de objetos na pgina 172) antes de chamar o mtodo PrintJob.addPage() e definaas novamente como seus valores originais aps a impresso. A escala de um objeto Sprite no tem nenhuma relao com a propriedade printArea. Em outras palavras, se voc especificar uma rea de impresso de 50 x 50 pixels, sero impressos 2500 pixels. Se voc dimensionar o objeto Sprite, sero impressos os mesmos 2500 pixels, mas o objeto Sprite ser impresso no tamanho dimensionado. Para obter um exemplo, consulte Exemplo de impresso: escala, corte e resposta na pgina 918.

Impresso de orientao paisagem ou retrato

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Como o Flash Player e o AIR podem detectar as configuraes de orientao, voc pode criar lgica no ActionScript para ajustar o tamanho ou a rotao do contedo em resposta s configuraes da impressora, conforme ilustrado no exemplo a seguir:
if (myPrintJob.orientation == PrintJobOrientation.LANDSCAPE) { mySprite.rotation = 90; }

Nota: Se voc planeja ler a configurao do sistema para obter a orientao do contedo no papel, lembre-se de importar a classe PrintJobOrientation. A classe PrintJobOrientation fornece valores de constante que definem a orientao do contedo na pgina. Importe a classe usando a seguinte instruo:
import flash.printing.PrintJobOrientation;

Resposta altura e largura da pgina

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Usando uma estratgia semelhante manipulao das configuraes de orientao da impressora, voc pode ler as configuraes de altura e largura da pgina e responder a elas incorporando alguma lgica em uma instruo if. O cdigo a seguir mostra um exemplo:
if (mySprite.height > myPrintJob.pageHeight) { mySprite.scaleY = .75; }

Alm disso, as configuraes da margem de uma pgina podem ser determinadas comparando as dimenses da pgina e do papel, conforme ilustrado no exemplo a seguir:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Impresso

914

margin_height = (myPrintJob.paperHeight - myPrintJob.pageHeight) / 2; margin_width = (myPrintJob.paperWidth - myPrintJob.pageWidth) / 2;

Tcnicas avanadas de impresso

Adobe AIR 2 e posterior Desde o Adobe AIR 2, a classe PrintJob possui propriedades adicionais, mtodos e suporte a trs classes adicionais: PrintUIOptions, PaperSize e PrintMethod. Essas mudanas permitem adicionar novos fluxos de trabalho de impressora e permite que os autores tenham um controle maior sobre o processo de impresso. As modificaes incluem:

Dilogos de configurao de pgina: os dilogos padro e personalizado podem ser exibidos. O usurio pode definir
intervalos de pginas, tamanho do papel e o dimensionamento antes de imprimir.

Visualizao da impresso: um modo de visualizao pode ser criado para exibir com preciso o tamanho do papel,
margens e o a posio do contedo na pgina.

Impresso restrita: os autores podem restringir as opes de impresso como, por exemplo, o intervalo de pginas
que podem ser impressas.

Opes de qualidade: os autores podem ajustar a qualidade da impresso para um documento e permitir que o
usurio selecione a resoluo e opes de cor.

Diversas sesses de impresso: uma instncia nica PrintJob pode ser utilizada para diversas sesses de impresso.
Os aplicativos podem fornecer configuraes consistentes a cada momento em que as configuraes de pgina e dilogos de impresso so exibidos.

Alteraes no fluxo de trabalho de impresso

O fluxo de trabalho de uma impresso nova consiste nas seguintes etapas:

new PrintJob(): Cria uma instncia PrintJob (ou reutiliza uma instncia existente). Diversas propriedades PrintJob e mtodos como, por exemplo, selectPaperSize()esto disponveis antes da tarefa de impresso iniciar ou durante a impresso. PrintJob.showPageSetupDialog(): (opcional) Exibe o dilogo de configurao da pgina sem iniciar uma tarefa

de impresso.
PrintJob.start() ou PrintJob.start2(): Alm do mtodo start(), o novo mtodo start2() utilizado

para iniciar o processo de spooling de impresso. O mtodo start2() permite selecionar quando o dilogo de Impresso e personalizar o dilogo quando ele exibido.

PrintJob.addPage(): Adicionar contedo tarefa de impresso. Sem modificaes no processo existente. PrintJob.send() ou PrintJob.terminate(): Envia as pginas para a impressora selecionada ou encerra o tarefa de impresso sem enviar. As tarefas de impresso so encerradas em resposta a um erro. Se uma instncia PrintJob encerrada, ela ainda pode ser reutilizada. Independentemente da tarefa de impresso ser enviada para a impressora ou encerrada, as configuraes atuais de impresso so mantidas quando a instncia PrintJob reutilizada.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Impresso

915

Caixa de dilogo Configurar Pgina

O mtodo showPageSetupDialog()exibe o dilogo de Configurao de impresso do sistema, se o ambiente atual tiver suporte. Sempre verifique a propriedadesupportsPageSetupDialog antes de chamar este mtodo. A seguir, um exemplo simples:
import flash.printing.PrintJob; var myPrintJob:PrintJob = new PrintJob(); //check for static property supportsPageSetupDialog of PrintJob class if (PrintJob.supportsPageSetupDialog) { myPrintJob.showPageSetupDialog(); }

Opcionalmente, o mtodo pode ser chamado com uma PrintUIOptions class propriedade para controlar quais opes so exibidas no dilogo de Configuraes de impresso. O nmero mnimo e mximo de pginas que pode ser definido. O exemplo a seguir limita a impresso para as trs primeiras pginas:
import flash.printing.PrintJob; var myPrintJob:PrintJob = new PrintJob(); if (PrintJob.supportsPageSetupDialog) { var uiOpt:PrintUIOptions = new PrintUIOptions(); uiOpt.minPage = 1; uiOpt.maxPage = 3; myPrintJob.showPageSetupDialog(uiOpt); }

Alterao das configuraes de impresso

As configuraes da instncia PrintJob podem ser alteradas a qualquer momento aps ela ser construda. Isto inclui alterar configuraes entre chamadas addPage()e aps a tarefa de impresso ter sido enviada ou encerrada. Algumas configuraes como a propriedadeprinter, aplicam-se tarefa de impresso toda e no a pginas individuais. Algumas configuraes devem ser definidas antes de uma chamada para start() ou start2(). O mtodo selectPaperSize() pode ser chamado para definir o tamanho de papel padro nos dilogos de Configuraes da pgina e Configuraes de impresso. Ele tambm pode ser chamado durante uma tarefa de impresso para definir o tamanho do papel para um intervalo de pginas. Ele chamado por constantes definidas na classe PaperSize como nestes exemplo, que seleciona um nmero 10 de tamanho de envelope:
import flash.printing.PrintJob; import flash.printing.PaperSize; var myPrintJob:PrintJob = new PrintJob(); myPrintJob.selectPaperSize(PaperSize.ENV_10);

Utilize a propriedadeprinter para obter ou definir o nome da impressora para o trabalho atual. Por padro, isto definido com o nome da impressora padro. A propriedade printer null nenhuma impressora estiver disponvel ou o sistema no tiver suporte impresso. Para alterar a impressora, primeiro obtenha uma lista de impressoras disponveis utilizando a propriedade printers. Essa propriedade um Vetor cujo os elementos de Sequncia de caracteres so os nomes das impressoras disponveis. Defina a propriedade printer para um desses valores de Sequncia de caracteres para tornar a impressora ativa. A propriedade printer de um trabalho de impresso ativo no pode ser modificada. Tenta mudar aps uma chamada com sucesso para start() ou start2() e antes da tarefa ser enviada ou o terminal falhar. Segue um exemplo de configurao dessa propriedade:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Impresso

916

import flash.printing.PrintJob; var myPrintJob:PrintJob = new PrintJob(); myPrintJob.printer = "HP_LaserJet_1"; myPrintJob.start();

A propriedade copies obtm o valor do nmero de cpias definidas no dilogo Imprimir do sistema operacional. As propriedades firstPage e lastPage obtm o intervalo de pginas. A propriedade orientation obtm as configuraes de orientao de pgina. Essas propriedades podem ser definidas para sobrescrever os valores do dilogo Imprimir. O exemplo a seguir define essas propriedades:
import flash.printing.PrintJob; import flash.printing.PrintJobOrientation; var myPrintJob:PrintJob = new PrintJob(); myPrintJob.copies = 3; myPrintJob.firstPage = 1; myPrintJob.lastPage = 3; myPrintJob.orientation = PrintJobOrientation.LANDSCAPE;

A configurao somente leitura a seguir associada com PrintJob fornece informaes teis sobre a configurao atual da impressora:

paperArea: representa em pontos os limites retangulares do papel da impressora. printableArea: representa em pontos os limites retangulares da rea que pode ser impressa. maxPixelsPerInch: representa em pixels por polegada a resoluo fsica da impressora atual. isColor: A habilidade da impressora de imprimir em cores (retorna true se a impressora pode imprimir em

cores). Consulte Exemplo de impresso: configurao de pgina e opes de impresso na pgina 920.

Exemplo de impresso: impresso de vrias pginas

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Ao imprimir mais de uma pgina de contedo, voc pode associar cada pgina de contedo a uma entidade grfica diferente (neste caso, sheet1 e sheet2) e usar PrintJob.addPage() para cada entidade grfica. O cdigo a seguir ilustra esta tcnica:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Impresso

917

package { import import import import import import import

flash.display.MovieClip; flash.printing.PrintJob; flash.printing.PrintJobOrientation; flash.display.Stage; flash.display.Sprite; flash.text.TextField; flash.geom.Rectangle;

public class PrintMultiplePages extends MovieClip { private var sheet1:Sprite; private var sheet2:Sprite; public function PrintMultiplePages():void { init(); printPages(); } private function init():void { sheet1 = new Sprite(); createSheet(sheet1, "Once upon a time...", {x:10, y:50, width:80, height:130}); sheet2 = new Sprite(); createSheet(sheet2, "There was a great story to tell, and it ended quickly.\n\nThe end.", null); } private function createSheet(sheet:Sprite, str:String, imgValue:Object):void { sheet.graphics.beginFill(0xEEEEEE); sheet.graphics.lineStyle(1, 0x000000); sheet.graphics.drawRect(0, 0, 100, 200); sheet.graphics.endFill(); var txt:TextField = new TextField(); txt.height = 200; txt.width = 100; txt.wordWrap = true; txt.text = str; if (imgValue != null) { var img:Sprite = new Sprite(); img.graphics.beginFill(0xFFFFFF); img.graphics.drawRect(imgValue.x, imgValue.y, imgValue.width, imgValue.height); img.graphics.endFill(); sheet.addChild(img); } sheet.addChild(txt); } private function printPages():void { var pj:PrintJob = new PrintJob();

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Impresso

918

var pagesToPrint:uint = 0; if (pj.start()) { if (pj.orientation == PrintJobOrientation.LANDSCAPE) { throw new Error("Page is not set to an orientation of portrait."); } sheet1.height = pj.pageHeight; sheet1.width = pj.pageWidth; sheet2.height = pj.pageHeight; sheet2.width = pj.pageWidth; try { pj.addPage(sheet1); pagesToPrint++; } catch (error:Error) { // Respond to error. } try { pj.addPage(sheet2); pagesToPrint++; } catch (error:Error) { // Respond to error. } if (pagesToPrint > 0) { pj.send(); } } } } }

Exemplo de impresso: escala, corte e resposta

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Em alguns casos, voc pode desejar ajustar o tamanho (ou outras propriedades) do objeto de exibio durante a impresso para acomodar diferenas entre a forma como ele exibido na tela e como impresso no papel. Quando voc ajusta as propriedades de um objeto de exibio antes da impresso (por exemplo, usando as propriedades scaleX e scaleY), lembre-se de que, se o objeto tiver a escala maior do que o retngulo definido para a rea de impresso, ele ser cortado. Talvez voc tambm queira redefinir as propriedades depois que as pginas foram impressas.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Impresso

919

O cdigo a seguir escala as dimenses do objeto de exibio txt (mas no o plano de fundo da caixa verde) e o campo de texto acaba sendo cortado pelas dimenses do retngulo especificado. Aps a impresso, o campo de texto volta ao seu tamanho original para exibio na tela. Se o usurio cancelar o trabalho de impresso da caixa de dilogo Imprimir do sistema operacional, o contedo no tempo de execuo do Flash ser alterado para alertar o usurio de que o trabalho foi cancelado.
package { import import import import import

flash.printing.PrintJob; flash.display.Sprite; flash.text.TextField; flash.display.Stage; flash.geom.Rectangle;

public class PrintScaleExample extends Sprite { private var bg:Sprite; private var txt:TextField; public function PrintScaleExample():void { init(); draw(); printPage(); } private function printPage():void { var pj:PrintJob = new PrintJob(); txt.scaleX = 3; txt.scaleY = 2; if (pj.start()) { trace(">> pj.orientation: " + pj.orientation); trace(">> pj.pageWidth: " + pj.pageWidth); trace(">> pj.pageHeight: " + pj.pageHeight); trace(">> pj.paperWidth: " + pj.paperWidth); trace(">> pj.paperHeight: " + pj.paperHeight); try { pj.addPage(this, new Rectangle(0, 0, 100, 100)); } catch (error:Error) { // Do nothing. } pj.send(); } else { txt.text } // Reset the txt.scaleX = txt.scaleY =

= "Print job canceled"; txt scale properties. 1; 1;

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Impresso

920

} private function init():void { bg = new Sprite(); bg.graphics.beginFill(0x00FF00); bg.graphics.drawRect(0, 0, 100, 200); bg.graphics.endFill(); txt = new TextField(); txt.border = true; txt.text = "Hello World"; } private function draw():void { addChild(bg); addChild(txt); txt.x = 50; txt.y = 50; } } }

Exemplo de impresso: configurao de pgina e opes de impresso

Adobe AIR 2 e posterior O exemplo a seguir inicializa as configuraes de PrintJob para o nmero de cpias, tamanho de papel (ofcio) e orientao da pgina (paisagem). Ela fora a exibio do dilogo de Configuraes da pgina e, em seguida, inicia a tarefa de impresso, exibindo o dilogo Imprimir.
package { import import import import import import import import

flash.printing.PrintJob; flash.printing.PrintJobOrientation; flash.printing.PaperSize; flash.printing.PrintUIOptions; flash.display.Sprite; flash.text.TextField; flash.display.Stage; flash.geom.Rectangle;

public class PrintAdvancedExample extends Sprite { private var bg:Sprite = new Sprite(); private var txt:TextField = new TextField(); private var pj:PrintJob = new PrintJob(); private var uiOpt:PrintUIOptions = new PrintUIOptions(); public function PrintAdvancedExample():void {

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Impresso

921

initPrintJob(); initContent(); draw(); printPage(); } private function printPage():void { //test for dialog support as a static property of PrintJob class if (PrintJob.supportsPageSetupDialog) { pj.showPageSetupDialog(); } if (pj.start2(uiOpt, true)) { try { pj.addPage(this, new Rectangle(0, 0, 100, 100)); } catch (error:Error) { // Do nothing. } pj.send(); } else { txt.text = "Print job terminated"; pj.terminate(); } } private function initContent():void { bg.graphics.beginFill(0x00FF00); bg.graphics.drawRect(0, 0, 100, 200); bg.graphics.endFill(); txt.border = true;

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Impresso

922

txt.text = "Hello World"; } private function initPrintJob():void { pj.selectPaperSize(PaperSize.LEGAL); pj.orientation = PrintJobOrientation.LANDSCAPE; pj.copies = 2; pj.jobName = "Flash test print"; } private function draw():void { addChild(bg); addChild(txt); txt.x = 50; txt.y = 50; } } }

ltima atualizao em 29/3/2011

923

Captulo 52: Geolocation

Caso um dispositivo suporte geolocalizao, voc pode utilizar a API de geolocalizao para obter a localizao geogrfica atual do dispositivo. Caso o dispositivo suporte este recurso, voc pode obter informao sobre geolocalizao. Estas informaes incluem a altitude, direo, velocidade e carimbo de data e hora da ltima mudana na localizao. A classe Geolocation despacha eventos update em resposta ao sensor de local do dispositivo. O evento update um objeto GeolocationEvent.

Mais tpicos da Ajuda

flash.sensors.Geolocation flash.events.GeolocationEvent

Detectando mudanas de geolocalizao

Para utilizar o sensor de geolocalizao, instancie um objeto Geolocation e registre para atualizar eventos enviados. O evento update um objeto de evento Geolocation. O evento possui oito propriedades:

altitudeAltitude em metros. headingA direo do movimento (com respeito ao Norte Verdadeiro) em graus de nmero inteiro. horizontalAccuracyA exatido horizontal em metros. latitudeA latitude em graus. longitudeA longitude em graus. speedA velocidade em metros por segundo. timestampO nmero de milissegundos no momento do evento a partir do incio da execuo. verticalAccuracyA exatido vertical em metros.

A propriedade timestamp um objeto int. Os outros so objetos Number. Este um exemplo bsico que exibe dados de geolocalizao em um campo de texto:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Geolocation

924

var geo:Geolocation; if (Geolocation.isSupported) { geo = new Geolocation(); geo.addEventListener(GeolocationEvent.UPDATE, updateHandler); } else { geoTextField.text = "Geolocation feature not supported"; } function updateHandler(event:GeolocationEvent):void { geoTextField.text = "latitude: " + event.latitude.toString() + "\n" + "longitude: " + event.longitude.toString() + "\n" + "altitude: " + event.altitude.toString() + "speed: " + event.speed.toString() + "heading: " + event.heading.toString() + "horizontal accuracy: " + event.horizontalAccuracy.toString() + "vertical accuracy: " + event.verticalAccuracy.toString() }

Para utilizar este exemplo, certifique-se de criar o campo de texto geoTextField e adicion-lo para a lista de exibio antes de utilizar este cdigo. Voc pode ajustar o intervalo de tempo para eventos de geolocalizao chamando o mtodo setRequestedUpdateInterval() do objeto Geolocation. Este mtodo usa um parmetro interval, que o intervalo de atualizao solicitado em milisegundos:
var geo:Geolocation = new Geolocation(); geo.setRequestedUpdateInterval(10000);

A hora real entre atualizaes de geolocalizao pode ser maior ou menor do que este valor. Qualquer mudana no intervalo de atualizao afeta todos os ouvintes registrados. Se o mtodo setRequestedUpdateInterval() no for chamado, o aplicativo recebe atualizaes com base no intervalo padro do dispositivo. O usurio pode impedir que um aplicativo acesse dados de geolocalizao. Por exemplo, o iPhone consulta o usurio quando um aplicativo tenta obter dados de geolocalizao. Em resposta consulta, o usurio pode negar o acesso do aplicativo aos dados de geolocalizao. O objeto Geolocation envia um evento status quando o usurio no fornece acesso aos dados de geolocalizao. Alm disso objeto Geolocation possui uma propriedade muted que definida como true quando o sensor de geolocalizao no est disponvel. O objeto Geolocation envia um evento status quando a propriedade muted muda. O cdigo a seguir mostra como detectar quando os dados de geolocalizao no esto disponveis:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Geolocation

925

var geo:Geolocation; var latitude:Number; var longitude:Number; if (Geolocation.isSupported) { geo = new Geolocation(); if (!geo.muted) { geo.addEventListener(GeolocationEvent.UPDATE, updateHandler); geo.addEventListener(StatusEvent.STATUS, geoStatusHandler); } } else { trace("not supported"); } function updateHandler(event:GeolocationEvent):void { latitude = event.latitude; longitude = event.longitude; } function geoStatusHandler(event:StatusEvent):void { geo.removeEventListener(GeolocationEvent.UPDATE, updateHandler); }

Nota: iPhones de primeira gerao que no possuam uma unidade GPS, enviam eventos de update ocasionalmente. Nestes dispositivos, o objeto Geolocation inicialmente envia um ou dois eventosupdate. Em seguida, ele envia eventos update quando as informaes so alteradas consideravalmente.

Verificando o suporte a geolocalizao

Utilize a propriedade Geolocation.isSupported para testar o ambiente de tempo de execuo em relao a habilidade de utilizar este recurso:
if (Geolocation.isSupported) { // Set up geolocation event listeners and code. }

Atualmente, a geolocalizao suportada apenas em aplicativos com base no ActionScript para o iPhone e no Flash Lite 4. Caso Geolocation.isSupported for true no tempo de execuo, ento o suporte a geolocalizao est disponvel. Alguns modelos de iPhone no tem uma unidade GPS. Estes modelos utilizam outros meios (assim como triangulao de telefone mvel) para obter dados de geolocalizao. Para estes modelos, ou para qualquer modelo de iPhone que no tenham GPS desabilitado, um objeto Geolocation pode enviar apenas um ou dois eventos deatualizao iniciais.

ltima atualizao em 29/3/2011

926

Captulo 53: Internacionalizao de aplicativos

Flash Player 10.1 e posterior, Adobe AIR 2.0 e posterior O pacote flash.globalization torna mais fcil criar softwares internacionais que se adaptam s convenes de diferentes idiomas e regies.

Mais tpicos da Ajuda

Pacote flash.globalization Localizao de aplicativos na pgina 944 Charles Bihis: Want to Localize your Flex/AIR Apps? (Deseja Localizar seus Aplicativos Flex/AIR)

Introduo internacionalizao de aplicativos

Em alguns casos, os termos globalizao e internacionalizao so utilizados alternadamente. No entanto, as definies mais populares desses termos dizem que a globalizao refere-se combinao de processos de negcios e engenharia enquanto a internacionalizao refere-se somente engenharia. Seguem algumas definies de termos importantes:
Globalizao Uma grande variedade de processos de engenharia e negcios necessrios para preparar e lanar produtos e atividades da companhia globalmente. A globalizao consiste em atividades de engenharia como, por exemplo, internacionalizao, localizao e culturalizao e atividades de negcios como gerenciamento de produto, planejamento financeiro, marketing e trabalho jurdico. Globalization as vezes abreviado como G11n (letra G, mais 11 letras e n). Globalizao o que a empresa faz. Internacionalizao Processo de engenharia para generalizar um produto de forma que ele possa utilizar diversos idiomas, scripts e convenes culturais (incluindo moedas, regras de classificao, formatos de data e nmeros, etc.) sem necessidade de um novo design ou nova compilao. Esse processo pode ser dividido em dois conjuntos de atividades: capacitao e localizao. s vezes a internacionalizao conhecida como world-readiness e abreviada como I18n. A internacionalizao o que os engenheiros fazem. Localizao Processo de adaptao de um produto ou servio para uma cultura e idioma especfico e a aparncia local

desejada. s vezes a localizao abreviada como L10n. Localizao o que os tradutores fazem.
Culturizao Processo de engenharia para desenvolvimento ou adaptao de recursos especficos s necessidades de

uma cultura. Alguns exemplos incluem os recursos de publicao para o idioma japons disponveis no Adobe InDesign e o recursos de suporte a Hanko no Adobe Acrobat. Alguns termos importantes de internacionalizao podem ser definidos da seguinte forma:
Conjunto de caracteres Caracteres utilizados pelo idioma ou por um grupo de idiomas. Um conjunto de caracteres inclui caracteres nacionais e especiais (ex: pontuao e smbolos matemticos), dgitos numricos e caracteres controlados por computador. Ordem alfabtica Classificao de texto na ordem adequada para uma localidade especfica.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Internacionalizao de aplicativos

927

Localidade Valor que representa as convenes culturais e de idioma utilizadas em uma regio geogrfica, poltica ou

cultural (o que muitas vezes pode indicar um nico pas). Um identificador de localidade nico (ID de localidade) representa este valor. O ID de localidade utilizado para definir dados de localidade que fornecem suporte especfico da localidade. O suporte aplica-se a unidades de medida, anlise e formatao de nmeros, datas e assim por diante.
Pacote de recursos Conjunto armazenado de elementos especficos de localidade criados para uma localidade na qual

um aplicativo utilizado. Um recurso geralmente contm todos os elementos de texto na interface de usurio ddo aplicativo. Dentro de um pacote, os elementos so traduzidos no idioma apropriado para a localidade especificada. Ele tambm pode conter outras configuraes como o layout ou comportamento da interface de usurio de uma localidade especfica. Um pacote de recurso pode conter outros tipos de mdia ou referncias a outros tipos de mdia, especficas do local.

Viso geral do pacote flash.globalization

Flash Player 10.1 e posterior, Adobe AIR 2.0 e posterior O pacote flash.globalization utiliza os recursos de suporte cultural do sistema operacional base. Ele torna mais fcil escrever aplicativos que seguem as convenes culturais de usurios individuais. As principais classes do pacote incluem:

A classe Collator que governa a classificao e correspondncia das strings. A classe CurrencyFormatter que formata nmeros em strings de valores de moeda e analisa os smbolos e valores
de moedas de strings de entrada

A classe DateTimeFormatter que formata os valores de data A classe LocaleID para obter informaes sobre uma localidade especifica A classe NumberFormatter que formata e analisa valores numricos A classe StringTools que trata de converses de strings sensveis a localidades

O pacote flash.globalization e localizao de recursos

O pacote flash.globalization no manipula localizao de recursos. No entanto voc pode utilizar a ID de localidade flash.globalization como o valor chave para obter recursos localizados utilizando outras tcnicas. Por exemplo, voc pode localizar recursos de aplicatiivo criados com o Flex usando as classes ResourceManager e ResourceBundle. Para mais informaes, acesse Localizando aplicativos Flex. O Adobe AIR 1.1 possui tambm alguns recursos para ajudar na localizao de aplicativos AIR como discutido em Localizao de aplicativos AIR na pgina 945.

Uma abordagem geral para internacionalizao de um aplicativo

Os seguintes passos descrevem uma aproximao de alto nvel para internacionalizar um aplicativo utilizando o pacote flash.globalization:
1 Determinar ou definir a localidade. 2 Criar uma ocorrncia de uma classe de servio (Collator, CurrencyFormatter, DateTimeFormatter,

NumberFormatter ou StringTools).
3 Verifique se existem erros e redues de velocidade utilizando as propriedades lastOperationStatus.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Internacionalizao de aplicativos

928

4 Formatar e exibir informaes utilizando configuraes de localidade especifica.

O prximo passo carregar e exibir strings e recursos UI (interface do usurio) que so especificas para a localidade. Esta etapa pode incluir tarefas como, por exemplo:

Utilizao de recursos autolayout para redimensionar a UI para acomodar comprimentos de seqncia de

caracteres

Selecionar as fontes corretas e os fontes reserva de suporte Utilizar o mecanismo de texto FTE para fornecer suporte a outros sistemas de escrita Certificar-se de que os editores de mtodo de entrada so tratados corretamente

Verificando erros e redues de velocidade

As classes de servio flash.globalization seguem um padro similar para identificar erros. Elas tambm compartilham um pado para retornar de uma localidade solicitada indisponvel para uma que possua suporte do sistema operacional. O exemplo a seguir mostra como verificar a existncia de erros e fallbacks ao instanciar classes de servio. Cada classe de servico posssui uma propriedade lastOperationStatus que indica se a chamada de mtodo mais recente disparou erros ou avisos.
var nf:NumberFormatter = new NumberFormatter("de-DE"); if(nf.lastOperationStatus != LastOperationStatus.NO_ERROR) { if(nf.lastOperationStatus == LastOperationStatus.USING_FALLBACK_WARNING) { // perform fallback logic here, if needed trace("Warning - Fallback locale ID: " + nf.actualLocaleIDName); } else { // perform error handling logic here, if needed trace("Error: " + nf.lastOperationStatus); } }

Este exemplo apenas rastreia uma mensagem se uma ID de localidade fallback utilizada ou se h um erro. Seu aplicativo pode executar lgicas de manipulao de erros adicionais, caso seja necessrio. Por exemplo, voc pode exibir uma mensagem para o usurio ou forar o aplicativo a utilizar uma localidade especifica suportada.

Determinando a localidade
Flash Player 10.1 e posterior, Adobe AIR 2.0 e posterior Uma localidade identifica uma combinao especifica de linguagem e convenes culturais para um pas ou regio. Um identificador de localidade pode ser gerenciado de forma segura como uma string. Mas voc pode utilizar a classe LocaleID para obter informaes adicionais relacionadas localidade. Voc pode criar um objeto LocaleID da seguinte forma:
var locale:LocaleID = new LocaleID("es-MX");

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Internacionalizao de aplicativos

929

Ap o objeto LocaleID ser criado, voc pode recuperar os dados do ID de localidade. Utilize os mtodos getKeysAndValues(), getLanguage(), getRegion(), getScript(), getVariant() e isRightToLeft() e a propriedade name. Os valores obtidos destes mtodos e propriedades podem refletir informaes adicionais sobre a localidade, que no podem ser extradas diretamente do identificador de localidade. Quando um aplicativo cria um servio de informaes sobre localidade, como um formatador de data, a localidade tem que ser especificada. A lista de localidades que possuem suporte pode variar conforme o sistema operacional, portanto, a localidade solicitada pode no estar disponvel. Primeiro o Flash Player tenta combinar o cdigo de linguagem solicitado. Ento ele tenta refinar a localidade procurando um sistema de escrita e regio correspondentes (script) Por exemplo:
var loc:LocaleID = new LocaleID("es"); trace(loc.getLanguage()); // es trace(loc.getScript()); // Latn trace(loc.getRegion()); // ES

Neste exemplo o construtor LocaleID() obteve dados sobre a localidade que corresponde melhor ao cdigo de linguagem "es" para o usurio.

Definindo o ID de localidade
Existem algumas maneiras de definir a localidade atual para um aplicativo, incluindo:

Codificando um ID de localidade no aplicativo. Esta uma abordagem comum, mas no suporta a

internacionalizao do aplicativo.

Utilizar as preferncias de ID de localidade do sistema operacional do usurio, ou do navegador, ou de outras

preferncias de usurio. Isto geralmente resulta nas melhores configuraes de localidade para o usurio, mas nem sempre possui preciso. Existe um risco de que as configuraes do sistema operacional no reflitam as preferncias em uso do usurio. Por exemplo, o usurio pode estar utilizando um computador compartilhado e ser capaz de mudar as localidades preferidas do sistema operacional.

Depois de definir o ID de localidade com base nas preferncias do usurio, permita ao usurio selecionar em uma
lista de localidades suportadas. Geralmente, esta estratgia a melhor opo caso o seu aplicativo possa suportar mais de uma localidade. Voc pode implementar esta terceira opo da seguinte forma:
1 Obtenha uma lista das localidades ou linguagens preferidas pelo usurio de um perfil de usurio, configuraes de

navegador, configuraes de sistema operacional ou de um cookie. (Seu aplicativo dever implementar sua esta lgica por si. A biblioteca flash.globalization no suporta leitura direta de tais preferncias).
2 Determine quais dessas localidades so suportadas por seu aplicativo e selecione a melhor por padro. Utilize o

mtodo LocaleID.determinePreferredLocales() para encontrar as melhores localidades para um usurio com base em suas localidades preferidas e as localidades suportadas pelo sistema operacional
3 Fornea ao usurio uma maneira de alterar a configurao de localidade padro no caso da localidade padro no

seja satisfatria.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Internacionalizao de aplicativos

930

Limitaes de outras classes de localidade e idioma

A classe fl.lang.Locale permite que voc substitua strings de texto com base em uma localidade, utilizando pacotes de recursos contendo valores de string. No entanto, esta classe no suporta outros recursos de internacionalizao como nmero, moeda ou formatao de data, classificao e comparao, e assim por diante. Alm disso esta classe est disponvel apenas no Flash Professional. Voc tambm pode obter a configurao atual do cdigo de linguagem do sistema operacional utilizando a propriedade flash.system.Capabilities.language. No entanto, essa propriedade recupera somente cdigos de idioma ISO 639-1 de caracteres duplos - e no o ID de localidade completo e somente possui suporte a um conjunto especfico de localidades. No AIR 1.5, possvel utilizar a propriedade flash.system.Capabilities.languages. Essa propriedade fornece um conjunto de idiomas de interface preferidos dos usurio. Portanto, no possui as limitaes de Capabilities.language.

Formatando nmeros
Flash Player 10.1 e posterior, Adobe AIR 2.0 e posterior O formato de exibio de valores numricos variam muito de regio para regio. Por exemplo, o nmero 123456.78 formatado para certas localidades da seguinte maneira:
Localidade en-US (English, USA) de-DE (German, Germany) fr-FR (France, French) de-CH (German, Switzerland) en-IN (English, India) Vrias localidades rabes Formato do nmero -123,456.78 -123.456,78 -123 456,78 -123'456.78 -1,23,456.78 123,456.78-

Existem vrios fatores que influenciam formatos de nmero, incluindo:

Separadores. O separador decimal colocado entre as partes inteira e fracionrio de um nmero. Pode ser um
ponto, uma vrgula ou outro caractere. O separador de agrupamento ou de milhares pode ser um ponto, uma vrgula, um espao sem quebra ou outro caractere.

Padres de agrupamento. O nmero de dgitos entre cada separador de agrupamento esquerda do ponto decimal
pode ser dois ou trs ou outro valor.

Indicadores de nmeros negativos. Nmeros negativos podem ser mostrados com um sinal de menos esquerda
ou direita do nmero, ou dentro de parnteses para aplicativos financeiros. Por exemplo, 19 negativo pode ser mostrado como -19, 19- ou (19).

Zeros esquerda e direita. Algumas convenes culturais adicionam zeros esquerda ou direita em nmeros
exibidos. Por exemplo, o valor 0.17 pode ser exibido como .17, 0.17, ou 0.170, entre outras opes.

Conjunto de caracteres de dgito. Muitas linguagens, incluindo Hindi, rabe e Japons utilizam diferentes
conjuntos de caracteres de dgitos. O pacote flash.globalization suporta quaisquer conjuntos de caracteres de dgitos que mapeiam para os dgitos 0-9.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Internacionalizao de aplicativos

931

A classe NumberFormatter considera todos estes fatores ao formatar valores numricos.

Utilizando a classe NumberFormatter

A classe NumberFormatter formata valores numricos (do tipo int, uint, ou Number) de acordo com as convenes de uma localidade especifica. O exemplo a seguir mostra a maneira mais simples de formatar um nmero utilizando as propriedades de formatao padro fornecidas pelo sistema operacional do usurio:
var nf:NumberFormatter = new NumberFormatter(LocaleID.DEFAULT); trace(nf.formatNumber(-123456.789))

O resultado pode variar com base nas configuraes de localidade e das preferncias do usurio. Por exemplo, se a localidade do usurio fr-FR o valor formatado deve ser: -123.456,789 Caso voc queira apenas formatar um nmero para uma localidade especifica, independente das configuraes de usurio, defina o nome da localidade especificamente. Por exemplo:
var nf:NumberFormatter = new NumberFormatter("de-CH"); trace(nf.formatNumber(-123456.789));

Nesse caso, o resultado : -123'456.789 O mtodo formatNumber() obtm um Number como parmetro. A classe NumberFormatter tambm tem um mtodo formatInt() que obtm um int (inteiro) como entrada e um mtodo formatUint() que obtm um uint. Voc pode controlar explicitamente a lgica de formatao definindo as propriedades da classe NumberFormatter, como mostra este exemplo:
var nf:NumberFormatter = new NumberFormatter("de-CH"); nf.negativeNumberFormat = 0; nf.fractionalDigits = 5; nf.trailingZeros = true; nf.decimalSeparator = ","; nf.useGrouping = false; trace(nf.formatNumber(-123456.789)); //(123456.78900)

Este exemplo cria primeiro um objeto NumberFormatter e, em seguida:

define o formato de nmero negativo para utilizar parnteses (como em aplicativos financeiros); define o nmero de dgitos depois do separador decimal para 5; especifica que os zeros direita devem ser utilizados para garantir cinco casas decimais, define o separador decimal como vrgula; informa ao formatador para no utilizar qualquer separador de agrupamento.
Nota: Caso alguma alterao seja feita nessas propriedades, o formato de nmero resultante no corresponder ao formato de preferncia para a localidade especificada. Utilize algumas dessas propriedades somente quando a deteco de localidade no for importante, quando preciso obter um controle detalhado sobre um nico aspecto do formato como, por exemplo, o nmero de zeros direita ou quando o usurio solicitar a alterao diretamente, pelo Painel de Controle do Windows.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Internacionalizao de aplicativos

932

Analisando strings que contm valores numricos

A classe NumberFormatter pode tambm extrair valores numricos de strings que se ajustem s necessidades de formatao especificas de localidade. O mtodo NumberFormatter.parseNumber() extrai um valor numrico nico de uma string. Por exemplo:
var nf:NumberFormatter = new NumberFormatter( "en-US" ); var inputNumberString:String = "-1,234,567.890" var parsedNumber:Number = nf.parseNumber(inputNumberString); trace("Value:" + parsedNumber); // -1234567.89 trace("Status:" + nf.lastOperationStatus); // noError

O mtodo parseNumber() manipula strings que contm caracteres de formatao de dgitos e nmeros como sinais negativos e separadores. Se a cadeira de caracteres contiver outros caracteres, um cdigo de erro definido:
var nf:NumberFormatter = new NumberFormatter( "en-US" ); var inputNumberString:String = "The value is 1,234,567.890" var parsedNumber:Number = nf.parseNumber(inputNumberString); trace("Value:" + parsedNumber); // NaN trace("Status:" + nf.lastOperationStatus); // parseError

Para extrair nmeros de strings que contm caracteres de alfabeto adicionais, utilize o mtodo NumberFormatter.parse:
var nf:NumberFormatter = new NumberFormatter( "en-US" ); var inputNumberString:String = "The value is 123,456,7.890"; var parseResult:NumberParseResult = nf.parse(inputNumberString); trace("Value:" + parseResult.value); // 1234567.89 trace("startIndex: " + parseResult.startIndex); // 14 trace("Status:" + nf.lastOperationStatus); // noError

O mtodo parse() retorna um objeto NumberParseResult que contm o valor numrico analisado em sua propriedade de valor. A propriedade startIndex indica o ndice do primeiro caractere numrico encontrado. Voc pode utilizar tambm as propriedades startIndex e endIndex para extrair as pores da string que venham antes e depois dos dgitos.

Formatando valores de moeda

Flash Player 10.1 e posterior, Adobe AIR 2.0 e posterior Os formatos de exibio de valores de moeda variam tanto quanto os formatos de nmeros Por exemplo, o valor em dlar $123456.78 formatado para certas localidades da seguinte maneira:
Localidade en-US (English, USA) de-DE (German, Germany) en-IN (English, India) Formato do nmero $123,456.78 123.456,78 $ $ 1,23,456.78

A formatao de moeda envolve todos os mesmos fatores da formatao de nmeros, mais os adicionais:

Cdigo ISO de moeda. As trs letras de cdigo de moeda ISO 4217 para a localidade sendo utilizada, assim como
USD ou EUR.

Smbolo de moeda. O smbolo de moeda ou sequncia de caracteres da localidade sendo utilizada, como $ ou .

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Internacionalizao de aplicativos

933

Formato de moeda negativo. Define o local do smbolo de moeda e o smbolo negativo ou parnteses em relao
poro numrica do valor da moeda.

Formato de moeda positivo. Define o local do smbolo de moeda quanto poro numrica do valor da moeda.

Utilizando a classe CurrencyFormatter

A classe CurrencyFormatter formata valores numricos em strings que contm strings de moeda e nmeros formatados, de acordo com as convenes de uma localidade especifica. Quando voc instancia um novo objeto CurrencyFormatter, ele define a moeda para o padro para a localidade fornecida. O exemplo a seguir mostra que um objeto CurrencyFormatter criado com o uso da localidade alem assume que as quantidades de moeda esto em Euros:
var cf:CurrencyFormatter = new CurrencyFormatter( "de-DE" ); trace(cf.format(1234567.89)); // 1.234.567,89 EUR

Na maioria dos casos voc no deve contar com o padro de moeda para uma localidade. Caso no existe suporte para a localidade padro do usurio, a classe CurrencyFormatter define uma localidade fallback. A localidade fallback pode ter uma moeda padro diferente. Alm disso, voc desejar que os formatos de moeda paream corretas para seu usurio, mesmo se as quantidades no estejam na moeda local do usurio. Por exemplo, um usurio canadense pode querer ver os preos de uma empresa alem em euros, mas formatados no estilo canadense. O mtodo CurrencyFormatter.setCurrency() especifica a cadeia de caracteres de moeda exata e o smbolo da moeda a ser utilizado. O exemplo a seguir mostra quantidades de moeda em Euros para usurios na parte francesa do Canad:
var cf:CurrencyFormatter = new CurrencyFormatter( "fr-CA" ); cf.setCurrency("EUR", ""); trace(cf.format(1234567.89)); // 1.234.567,89 EUR

O mtodo setCurrency() pode tambm ser utilizada para reduzir a confuso ao definir smbolos de moeda sem ambiguidade. Por exemplo:
cf.setCurrency("USD","US$");

O mtodo format() exibe um cdigo de moeda IDO 4217 de trs caracteres ao invs do smbolo de moeda. Os cdigos ISO 4217 no possuem ambigidade e no requerem localizao. No entanto muitos usurios preferem ver smbolos de moeda ao invs de cdigos ISO. A classe CurremcyFormatter pode ajud-lo a decidir se uma string de moeda formatada deve utilizar um smbolo de moeda, como um smbolo de dlar ou de euro, ou uma string de moeda ISO de trs caracteres, como USD ou EUR. Por exemplo, um valor em dlares Canadenses pode ser exibido como $200 para um usurio no Canad. No entanto, para um usurio nos EUA, ele pode ser exibido como CAD 200. Utilize o mtodo formattingWithCurrencySymbolIsSafe() para determinar se o smbolo de moeda de quantidade seria ambguo ou incorreto para em relao s configuraes de localidade do usurio. O exemplo a seguir formata um valor em euros em um formato par a localidade en-US. Dependendo da localidade do usurio, a string de sada usar o cdigo de moeda ISO ou o smbolo de moeda.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Internacionalizao de aplicativos

934

var cf:CurrencyFormatter = new CurrencyFormatter( "en-CA"); if (cf.formattingWithCurrencySymbolIsSafe("USD")) { trace(cf.format(1234567.89, true)); // $1,234,567.89 } else { cf.setCurrency("USD", "$"); trace(cf.format(1234567.89)); // USD1,234,567.89 }

Analisando strings que contm valores numricos de moeda

A classe CurrencyFormatter pode tambm extrair uma string de quantidade de moeda de uma string de entrada que corresponda s necessidades de formatao especificas de localidade. O mtodo CurrencyFormatter.parse() armazena a quantidade analisada e a string de moeda em um objeto CurrencyParseResult, como mostrado em:
var cf:CurrencyFormatter = new CurrencyFormatter( "en-US" ); var inputCurrencyString:String = "(GBP 123,56,7.890)"; var parseResult:CurrencyParseResult = cf.parse(inputCurrencyString); trace("parsed amount: " + parseResult.value); // -1234567.89 trace("currencyString: " + parseResult.currencyString ); // GBP

A poro de string de moeda da string de entrada pode conter um smbolo de moeda, um cdigo ISO de moeda, e caracteres adicionais de texto. As posies da cadeia de caracteres de moeda, o indicador de nmero negativo e o valor numrico, devem corresponder aos formatos especificados pelas propriedades negativeCurrencyFormat e positiveCurrencyFormat. Por exemplo:
var cf:CurrencyFormatter = new CurrencyFormatter( "en-US" ); var inputCurrencyString:String = "Total $-123,56,7.890"; var parseResult:CurrencyParseResult = cf.parse(inputCurrencyString); trace("status: " + cf.lastOperationStatus ); // parseError trace("parsed amount: " + parseResult.value); // NaN trace("currencyString: " + parseResult.currencyString ); // cf.negativeCurrencyFormat = 2; parseResult = cf.parse(inputCurrencyString); trace("status: " + cf.lastOperationStatus ); // noError trace("parsed amount: " + parseResult.value); // -123567.89 trace("currencyString: " + parseResult.currencyString ); // Total $

Neste exemplo, a string de entrada tem uma string de moeda seguida por um sinal de menos e um nmero. No entanto o valor padro de negativeCurrencyFormat para a localidade en-US especifica que o indicador negativo deve vir primeiro. Como resultado, o mtodo parse() gera um erro e o valor analisado NaN. Em seguida ele define o negativeCurrencyFormat para 2, o qual especifica que a string de moeda vem primeiro, o mtodo parse() ter xito.

Formatando data e hora

Flash Player 10.1 e posterior, Adobe AIR 2.0 e posterior O formato de exibio de valores de data e tempo tambm variam muito de uma regio para outra. Por exemplo, aqui est como o segundo dia de janeiro, de 1962 s 1:01 PM exibido em um formato curto para certas localidades:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Internacionalizao de aplicativos

935

Localidade en-US (English, USA) fr-FR (France, French) ja-JP (Japan, Japanese)

Formato de data e hora 2/1/62 1:01pm 2/1/62 13:01 1962/2/1 13:01

Utilizando a classe DateFormatter

A classe DateTimeFormatter formata valores Date em strings de data e hora de acordo com as convenes de uma localidade especifica. A formatao orientada por uma string de padro que contm seqncias de letras que sero substitudas por valores de data ou tempo. Por exemplo, no padro "aaaa/MM", os caracteres o "aaaa" ser substitudo por um ano de quatro dgitos, seguido pelo caractere "/" e um ms de dois dgitos. A string de padro pode ser definida explicitamente utilizando o mtodo setDateTimePattern(). No entanto, melhor permitir que o padro seja definido automaticamente, de acordo com a localidade do usurio e as preferncias do sistema operacional. Esta prtica ajuda a garantir que o resultado seja apropriado de forma cultural. O DateTimeFormatter pode representar datas e horrios em trs estilos padro (LONG, MEDIUM e SHORT) alm de poder utilizar um padro CUSTOM. Um padro pode ser utilizado para data, e o secundo para a hora. Os padres reais utilizados para cada estilo podem variar um pouco entre sistemas operacionais. possvel especificar estilos ao criar um objeto DateTimeFormatter. Caso os parmetros de estilo no estejam especificados, ento eles sero definidos para DateTimeStyle.LONG por padro. Voc pode alterar os estilos posteriormente utilizando o mtodo setDateTimeStyles(), como mostrado no seguinte exemplo:
var date:Date = new Date(2009, 2, 27, 13, 1); var dtf:DateTimeFormatter = new DateTimeFormatter("en-US", DateTimeStyle.LONG, DateTimeStyle.LONG); var longDate:String = dtf.format(date); trace(longDate); // March 27, 2009 1:01:00 PM dtf.setDateTimeStyles(DateTimeStyle.SHORT, DateTimeStyle.SHORT); var shortDate:String = dtf.format(date); trace(shortDate); // 3/27/09 1:01 PM

Localizando nomes de meses e de dias

Muitos aplicativos utilizam listagens de nomes de meses e os nomes dos dias da semana em exibies de calendrio ou listas pull-down. Voc pode obter uma lista localizada dos nomes dos meses utilizando o mtodo DateTimeFormatter.getMonthNames(). Dependendo do sistema operacional, formas completas e abreviadas podem estar disponveis. Passe o valor DateTimeNameStyle.FULL para obter nomes completos de meses. Passe os valores DateTimeNameStyle.LONG_ABBREVIATION ou DateTimeNameStyle.SHORT_ABBREVIATION para obter uma verso menor. Em alguns idiomas, o nome do ms mudado (em sua forma genitiva) quando colocado ao lado de um valor de dia em um formato de data. Caso planeje utilizar os nomes de meses separados, dever passar o valor DateTimeNameContext.STANDALONE para o mtodo getMonthNames(). No entanto, para utilizar nomes de ms em datas formatadas, passe o valor DateTimeNameContext.FORMAT.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Internacionalizao de aplicativos

936

var dtf:DateTimeFormatter = new DateTimeFormatter("fr-FR"); var months:Vector.<String> = dtf.getMonthNames(DateTimeNameStyle.FULL, DateTimeNameContext.STANDALONE); trace(months[0]); // janvier months = dtf.getMonthNames(DateTimeNameStyle.SHORT_ABBREVIATION, DateTimeNameContext.STANDALONE); trace(months[0]); // janv.

O mtodo DateTimeFormatter.getWeekdayNames() fornece uma lista localizada dos nomes dos dias da semana. O mtodo getWeekdayNames() aceita os mesmos parmetros de contexto e nameStyle que o mtodo getMonthNames() aceita.
var dtf:DateTimeFormatter = new DateTimeFormatter("fr-FR"); var weekdays:Vector.<String> = dtf.getWeekdayNames(DateTimeNameStyle.FULL, DateTimeNameContext.STANDALONE); trace(weekdays[0]); // dimanche weekdays = dtf.getWeekdayNames(DateTimeNameStyle.LONG_ABBREVIATION, DateTimeNameContext.STANDALONE); trace(weekdays[0]); // dim.

Alm disso, o mtodo getFirstWeekday() retorna o valor de ndice do dia que tradicionalmente marca o comeo da semana na localidade selecionada.

Classificando e comparando strings

Flash Player 10.1 e posterior, Adobe AIR 2.0 e posterior Comparao o processo de arrumar coisas na ordem apropriada. As regras de comparao variam bastante por localidade. As regras tambm so diferentes caso esteja classificando uma lista ou correspondenddo itens similares como, por exemplo, um algoritmo de busca de texto. Quando estiver classificando, pequenas diferenas como letras maisculas e minsculas ou marcas diacrticas como acentos so geralmente significativos. Por exemplo, a letra (o com trema) considerado na maioria dos casos como equivalente letra simples o em francs ou ingls. No entanto, a mesma letra segue a letra z em sueco. Alm disso, em francs e algumas outras linguagens, a ltima diferena de acento em uma palavra determina sua ordem em uma lista classificada. Ao fazer uma busca, voc geralmente vai querer ignorar diferenas entre maisculas e minsculas ou diacrticos, para aumentar a chance de encontrar resultados relevantes. Por exemplo, uma busca pelos caracteres "cote" em um documento em francs deve provavelmente retornar resultados para cote, cte e cot.

Utilizando a classe Collator

Os principais mtodos da classe Collator so o compare() que utilizado primariamente para classificar, e o equals() utilizado para comparar valores. O exemplo a seguir mostra os diferentes comportamentos dos mtodos compare() e equals().

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Internacionalizao de aplicativos

937

var words:Array = new

Array("cot", "cte");

var sorter:Collator = new Collator("fr-FR", CollatorMode.SORTING); words.sort(sorter.compare); trace(words); // cte,cot var matcher:Collator = new Collator("fr-FR", CollatorMode.MATCHING); if (matcher.equals(words[0], words[1])) { trace(words[0] + " = " + words[1]); // cte = cot }

O exemplo primeiro cria um objeto Collator no modo SORTING para a localidade French-France. Ele ento classifica duas palavras que diferem pelas marcas diacrticas apenas. Isto mostra que a comparao SORTING diferencia entre caracteres com e sem acento. A classificao feita passando uma referncia para o mtodo sort() do objeto Collator como um parmetro para o mtodo Array.sort(). Esta uma das maneiras mais eficientes de utilizar um objeto Collator para controlar a ordem de classificao. O exemplo cria ento um objeto Collator no modo MATCHING. Quando este objeto Collator compara as duas palavras, ele trata as duas como iguais. Isto mostra que a comparao MATCHING valoriza caracteres acentuados ou no da mesma forma.

Personalizando o comportamento da classe Collator

Por padro, a classe Collator utiliza regras de comparao de string obtidas do sistema operacional com base na localidade e nas preferncias do sistema do usurio. Voc pode personalizar o comportamento dos mtodos compare() e equals() definindo vrias propriedades explicitamente. As tabela a seguir lista as propriedades e o efeito que elas tem sobre as comparaes:
Propriedade Collator numericComparison ignoreCase ignoreCharacterWidth Efeito Controla se os caracteres de dgito so tratados como nmeros ou texto. Controle se as diferenciao entre maisculas e minsculas ser ignorada. Controla se as formas de largura total e parcial de alguns caracteres chineses e japoneses so avaliados como iguais. Controla se as strings que utilizam as mesma base de caracteres exceto acentos ou outras marcas diacrticas so avaliadas como iguais. Controla se as cadeias de caracteres que se diferem apenas pelo tipo de caractere kana em uso sero tratadas como iguais. Controla se caracteres de smbolo como espaos, smbolos de moeda, smbolos matemticos e outros so ignorados.

ignoreDiacritics

ignoreKanaType

ignoreSymbols

O cdigo a seguir mostra que definir a propriedade ignoreDiacritics para verdadeiro muda a ordem de classificao de uma lista de palavras em francs:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Internacionalizao de aplicativos

938

var words:Array = new Array("COTE", "cot", "cte", "Cot","cote"); var sorter:Collator = new Collator("fr-CA", CollatorMode.SORTING); words.sort(sorter.compare); trace(words); // cote,COTE,cte,cot,Cot sorter.ignoreDiacritics = true; words.sort(sorter.compare); trace(words); // cte,cot,cote,Cot,COTE

Converso de caracteres maisculos e minsculos

Flash Player 10.1 e posterior, Adobe AIR 2.0 e posterior Linguagens diferem tambm em suas regras para converter letras entre maisculas (majiscules) e minsculas (minuscules). Por exemplo, a maioria dos idiomas que utilizam o alfabeto Latino a forma da letra minscula "I" "i". No entanto em algumas linguagens (como o turco e o azeri) existem uma letra sem ponto. Como resultado disso, nesses idiomas, um minsculo sem acento transformado em um I maisculo. Um i minsculo transformado em um maisculo sem o ponto. A classe StringTools fornece mtodos que utilizam regras especificas de linguagem para executar tais transformaes.

Utilizando a classe StringTools

A classe StringTools fornece dois mtodos para executar transformaes de maisculas e minsculas: toLowerCase() e toUpperCase(). O objeto StringTools criado ao chamar o construtor como um ID de localidade. A classe StringTools ir obter as regras de converso de maisculas e minsculas para a loocalidade (ou localidade fallback) do sistema operacional. No possvel fazer mais personalizaes no algoritimo de converso de maisculas e minsculas. O exemplo a seguir utiliza os mtodos toUpperCase() e toLowerCase() para transformar uma frase em alemo que inclui a letra (sharp S).
var phrase:String = "Schlo Neuschwanstein"; var converter:StringTools = new StringTools("de-DE"); var upperPhrase:String = converter.toUpperCase(phrase); trace(upperPhrase); // SCHLOSS NEUSCHWANSTEIN var lowerPhrase:String = converter.toLowerCase(upperPhrase); trace(lowerPhrase);// schloss neuschwanstein

O mtodo toUpperCase() transforma a letra minscula na letra maiscula SS. Essa transformao funciona somente em uma direo. Quando as letras "SS" so transformadas em minsculas, o resultado "ss" e no .

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Internacionalizao de aplicativos

939

Exemplo: Internacionalizao de um aplicativo de acionamento de aes

Flash Player 10.1 e posterior, Adobe AIR 2.0 e posterior O aplicativo Acionador de aces globais obtm e exibe dados ficticios sobre aes em trs mercados de aes diferentes: dos Estados Unidos, Jpo e Europa. Ele formata dos dados de acordo s convenes de vrias localidades. Este exemplo ilustra os seguintes recursos do pacote flash.globalization:

Formatao de nmero sensvel a localidade Formatao de moeda sensvel a localidade Definindo cdigo ISO e smbolos de moeda Formatao de data sensvel a localidade Obtendo e exibindo abreviaes apropriadas de nome de meses
Para obter os arquivos do aplicativo deste exemplo, consulte www.adobe.com/go/learn_programmingAS3samples_flash_br. Os arquivos do aplicativo Acionador de aes gloabais podem ser localizados no diretrio Samples/GlobalStockTicker. O aplicativo consiste nos seguintes arquivos:
Arquivo Descrio

GlobalStockTicker.mxm A interface do usurio do aplicativo para Flex (MXML) ou Flash (FLA). l ou GlobalStockTicker.fla styles.css Estilos da interface de usurio do aplicativo (somente no Flex).

com/example/program Um componente MXML que exibe um grfico de dados de simulados de aes, apenas para o Flex. mingas3/stockticker/fle x/FinGraph.mxml com/example/program Classe Document que contm a lgica da interface de usurio do aplicativo (somente no Flash). mingas3/stockticker/fla sh/GlobalStockTicker.as comp/example/progra Um processador de clula personalizado para o componente Flash DataGrid (apenas no Flash). mmingas3/stockticker/f lash/RightAlignedColu mn.as com/example/program Uma clase ActionScript que desenha um grfico de dados simulados de aes. mingas3/stockticker/Fi nancialGraph.as com/example/program Uma classe ActionScript que gerencia a localidade e a moeda e manipula a formatao localizada de nmeros, mingas3/stockticker/Lo quantidades de moeda e datas. calizer.as com/example/program Uma classe ActionScript que armazena todos os dados de amostra para o exemplo do Acionador de aes globais. mingas3/stockticker/St ockDataModel.as

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Internacionalizao de aplicativos

940

Entendendo a interface do usurio e amostra de dados

Os elementos da interface do usurio principal do aplicativo so:

uma caixa combinada para selecionar uma Localidade uma caixa combinada para selecionar um Mercado um DataGrid que exibe dados para seis companias em cada mercado um grfico que mostra dados de histrico simulados para as aes da compania selecionada
O aplicativo armazena todos os seus dados de amostra sobre localidades, mercados e aes de companias na classe StockDataModel. Um aplicativo real deve obter dados de um servidor e, em seguida, armazen-los em uma classe como a StockDataModel. Neste exemplo, todos os dados esto codificados na classe StockDataModel. Nota: Os dados exibidos no grfico financeiro no correspondem necessariamente com os dados no controle do DataGrid. O grfico redesenhado aleatriamente cada vez que uma compania diferente selecionada. Para propsitos ilustrativos apenas.

Definindo a localidade
Depois de algum trabalho inicial de configurao, o aplicativo chama o mtodo Localizer.setLocale() para criar objetos formatadores para a localidade padro. O mtodo setLocale() tambm chamado a cada vez que o usurio seleciona um novo valor da caixa combinada de Localidade.
public function setLocale(newLocale:String):void { locale = new LocaleID(newLocale); nf = new NumberFormatter(locale.name); traceError(nf.lastOperationStatus, "NumberFormatter", nf.actualLocaleIDName); cf = new CurrencyFormatter(locale.name); traceError(cf.lastOperationStatus, "CurrencyFormatter", cf.actualLocaleIDName); symbolIsSafe = cf.formattingWithCurrencySymbolIsSafe(currentCurrency); cf.setCurrency(currentCurrency, currentSymbol); cf.fractionalDigits = currentFraction; df = new DateTimeFormatter(locale.name, DateTimeStyle.LONG, DateTimeStyle.SHORT); traceError(df.lastOperationStatus, "DateTimeFormatter", df.actualLocaleIDName); monthNames = df.getMonthNames(DateTimeNameStyle.LONG_ABBREVIATION); } public function traceError(status:String, serviceName:String, localeID:String) :void { if(status != LastOperationStatus.NO_ERROR) { if(status == LastOperationStatus.USING_FALLBACK_WARNING)

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Internacionalizao de aplicativos

941

{ trace("Warning - Fallback locale ID used by " + serviceName + ": " + localeID); } else if (status == LastOperationStatus.UNSUPPORTED_ERROR) { trace("Error in " + serviceName + ": " + status); //abort application throw(new Error("Fatal error", 0)); } else { trace("Error in " + serviceName + ": " + status); } } else { trace(serviceName + " created for locale ID: " + localeID); } }

Primeiro o mtodo setLocale() cria um objeto LocaleID. Isto faz com que seja mais fcil obter detalhes sobre a localidade real posteriormente, se necessrio. Em seguida ele cria novos objetos NumberFormatter, CurrencyFormatter e DateTimeFormatte para a localidade. Aps criar cada objeto formatador, o mtodo traceError() chamado. Este mtodo exibe erros e mensagens de avisos no consolte, caso exista um problema na localidade solicitada. (Um aplicativo real deve executar aes com base nestes erros, em vez de somente rastre-los). Depois de criar o objeto CurrencyFormatter, o mtodo setLocale() define o cdigo ISO de moeda do formatador, smbolo de moeda e propriedades fractionalDigits para valores prviamente determinados. (Estes valores so definidos cada vez que o usurio seleciona um novo mercado da caixa combinada Mercados). Depois de criar o objeto DateTimeFormatter, o mtodo setLocale() tambm obtm uma matriz de abreviaes de nomes de meses localizados.

Formatando os dados
Os dados de aes formatados so apresentados em um controle DataGrid. Cada coluna DataGrid chama uma funo de rtulo que formata o valor da coluna utilizando o objeto formatador apropriado. Na verso do Flash, por exemplo, o seguinte cdigo define as colunas DataGrid:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Internacionalizao de aplicativos

942

var col1:DataGridColumn = new DataGridColumn("ticker"); col1.headerText = "Company"; col1.sortOptions = Array.NUMERIC; col1.width = 200; var col2:DataGridColumn = new DataGridColumn("volume"); col2.headerText = "Volume"; col2.width = 120; col2.cellRenderer = RightAlignedCell; col2.labelFunction = displayVolume; var col3:DataGridColumn = new DataGridColumn("price"); col3.headerText = "Price"; col3.width = 70; col3.cellRenderer = RightAlignedCell; col3.labelFunction = displayPrice; var col4:DataGridColumn = new DataGridColumn("change"); col4.headerText = "Change"; col4.width = 120; col4.cellRenderer = RightAlignedCell; col4.labelFunction = displayPercent;

A verso do Flex do exemplo declara seu DataGrid no MXML. Isto tambm define funes de rtulo semelhantes para cada coluna. As propriedades labelFunction se referem s seguintes funes, as quais chamam mtodos de formatao da classe Localizer:
private function displayVolume(item:Object):String { return localizer.formatNumber(item.volume, 0); } private function displayPercent(item:Object):String { return localizer.formatPercent(item.change ) ; } private function displayPrice(item:Object):String { return localizer.formatCurrency(item.price); }

Os mtodos Localizer ento definem e chamam os formatadores apropriados:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Internacionalizao de aplicativos

943

public function formatNumber(value:Number, fractionalDigits:int = 2):String { nf.fractionalDigits = fractionalDigits; return nf.formatNumber(value); } public function formatPercent(value:Number, fractionalDigits:int = 2):String { // HACK WARNING: The position of the percent sign, and whether a space belongs // between it and the number, are locale-sensitive decisions. For example, // in Turkish the positive format is %12 and the negative format is -%12. // Like most operating systems, flash.globalization classes do not currently // provide an API for percentage formatting. nf.fractionalDigits = fractionalDigits; return nf.formatNumber(value) + "%"; } public function formatCurrency(value:Number):String { return cf.format(value, symbolIsSafe); } public function formatDate(dateValue:Date):String { return df.format(dateValue); } |

ltima atualizao em 29/3/2011

944

Captulo 54: Localizao de aplicativos

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Localizao o processo de incluso de recursos para oferecer suporte a vrios cdigos de idiomas. Cdigo de idiomas a combinao de um idioma e um cdigo de um pas. Por exemplo, en_US se refere ao idioma ingls falado nos Estados Unidos e fr_FR se refere ao idioma francs falado na Frana. Para localizar um aplicativo para esses cdigos de idiomas, voc fornece dois conjuntos de recursos: um para o cdigo de idioma en_US e um para o cdigo de idiomas fr_FR. Os cdigos de idiomas podem compartilhar idiomas. Por exemplo, en_US e en_GB (Gr-Bretanha) so cdigos de idiomas diferentes. Nesse caso, os dois cdigos de idiomas usam o idioma ingls, mas o cdigo do pas indica que so cdigos de idiomas diferentes e podem, portanto, usar recursos diferentes. Por exemplo, um aplicativo no cdigo de idioma sen_US pode escrever a palavra "color", ao passo que ela seria "colour" no cdigo de idiomas en_GB. Alm disso, unidades monetrias seriam representadas em dlares ou em libras, dependendo do cdigo de idiomas, e o formato de data e hora tambm pode ser diferente. Voc tambm podem fornecer um conjunto de recursos para um idioma sem especificar o cdigo do pas. Por exemplo, voc pode fornecer recursos en para o idioma Ingls e fornecer recursos adicionais do cdigo de idiomas en_US, especficos para ingls dos EUA. A localizao vai alm de s traduzir as seqncias usadas no aplicativo. Ela tambm pode incluir qualquer tipo de recurso, como arquivos de udio, imagens e vdeos.

Seleo de cdigo de idiomas

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para determinar qual local seu contedo ou aplicativo usa, voc pode usar um dos seguintes mtodos:

Pacote flash.globalization Utilize as classes sensveis a localidades no pacote flash.globalization para obter a
localidade padro para o usurio com base no sistema operacional e nas preferncias do usurio. Esta a aproximao preferida para aplicativos que sero executados no Flash Player 10.1 ou posterior ou AIR 2.0 ou tempos de execuo posteriores. Consulte Determinando a localidade na pgina 928 para mais informaes.

Prompt de usurio: voc pode iniciar o aplicativo em algum cdigo de idiomas padro e, ento, solicitar ao usurio
que selecione o cdigo de idiomas preferido.

(Apenas no AIR)Capabilities.languages: a propriedade Capabilities.languages lista uma matriz de

idiomas disponveis nos idiomas de preferncia do usurio, conforme definido pelo sistema operacional. As seqncias contm tags de idioma (e informaes de script e regio, quando aplicvel) definidas por RFC4646 (http://www.ietf.org/rfc/rfc4646.txt). As seqncias usam hfens como delimitadores (por exemplo, "en-US" ou "ja-JP"). A primeira entrada na matriz retornada tem a mesma ID de idioma principal da propriedade language. Por exemplo, se languages[0] for definido como "en-US", a propriedade language ser definida como "en". Entretanto, se a propriedade language for definida como "xu" (especificando um idioma desconhecido), o primeiro elemento na matriz languages diferente.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Localizao de aplicativos

945

Capabilities.language: a propriedade Capabilities.language oferece o cdigo de idioma da interface do usurio do sistema operacional. No entanto, essa propriedade est limitada a 20 idiomas conhecidos. E, nos sistemas em ingls, essa propriedade retorna somente o cdigo do idioma, no o cdigo do pas. Por esses motivos, melhor usar o primeiro elemento na matriz Capabilities.languages.

Localizao de contedo Flex

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O Adobe Flex inclui uma estrutura para localizao de contedo Flex. Essa estrutura inclui as classes Locale, ResourceBundle e ResourceManagerImpl, bem como as interfaces IResourceBundle e IResourceManagerImpl. Uma biblioteca de localizao do Flash contendo classes de utilitrio para classificar localidades de aplicativos est disponvel no Google Code (http://code.google.com/p/as3localelib/).

Mais tpicos da Ajuda

http://code.google.com/p/as3localelib/

Localizao de contedo Flash

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O Adobe Flash Professional inclui a classe Locale nos componentes do ActionScript 3.0. A classe Locale permite controlar como o arquivo SWF exibe o texto multilnge. O painel Strings do Flash permite usar IDs de string em vez de literais de string nos campos de texto dinmicos. Essa facilidade permite criar um arquivo SWF que exibe o texto carregado de um arquivo XML especfico do idioma. Para obter mais informaes sobre como utilizar a classe Locale, consulte Referncia do ActionScript 3.0 para a plataforma Adobe Flash.

Localizao de aplicativos AIR

Adobe AIR 1.0 e posterior O AIR SDK oferece uma estrutura de localizao HTML (contida no arquivo AIRLocalizer.js). Este framework inclui APIs para auxiliar no trabalho com diversas localidades em um aplicativo com base em HTML. Uma biblioteca ActionScript para classificao de localidades est disponvel em http://code.google.com/p/as3localelib/.

Mais tpicos da Ajuda

http://code.google.com/p/as3localelib/

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Localizao de aplicativos

946

Localizao de datas, horas e moedas

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A maneira como os aplicativos apresentam dados, horas e moedas varia consideravelmente em cada cdigo de idiomas. Por exemplo, o padro dos EUA para representao de datas ms/dia/ano, enquanto o padro europeu para representao de datas dia/ms/ano. Voc pode gravar um cdigo para formatar datas, horas e moedas. Por exemplo, o cdigo a seguir converte o objeto Date no formato ms/dia/ano ou no formato dia/ms/ano. Se a varivel locale (representando o cdigo de idiomas) for definida como "en_US", a funo retornar o formato ms/dia/ano. O exemplo converte o objeto Date no formato dia/ms/ano de todos os outros cdigos de idiomas:
function convertDate(date) { if (locale == "en_US") { return (date.getMonth() + 1) + "/" + date.getDate() + "/" + date.getFullYear(); } else { return date.getDate() + "/" + (date.getMonth() + 1) + "/" + date.getFullYear(); } }

ADOBE FLEX A estrutura Flex inclui controles para formatar datas, horas e moedas. Esses controles incluem os controles DateFormatter e CurrencyFormatter.

mx:DateFormatter mx:CurrencyFormatter

ltima atualizao em 29/3/2011

947

Captulo 55: Sobre o ambiente HTML

Adobe AIR 1.0 e posterior O Adobe AIR usa o WebKit (www.webkit.org), tambm usado pelo navegador Safari para analisar gerar layout e renderizar o contedo HTML e JavaScript. Usar as APIs do AIR em contedo HTML opcional. Voc pode programar no contedo de um objeto HTMLLoader ou janela HTML inteiramente com HTML e JavaScript. A maioria dos aplicativos e pginas HTML existentes deve ser executada com algumas alteraes (supondo que eles usam recursos HTML, CSS, DOM e JavaScript compatveis com WebKit). Importante: as novas verses do tempo de execuo do Adobe AIR podem incluir verses atualizadas do WebKit. A atualizao do WebKit em uma nova verso do AIR pode resultar em mudanas inesperadas em um aplicativo AIR implantado. Essas alteraes podem afetar o comportamento ou a aparncia do contedo HTML em um aplicativo. Por exemplo, os aprimoramentos ou as correes na renderizao do Webkit podem alterar o layout dos elementos na interface de usurio de um aplicativo. Por essa razo, altamente recomendado que voc fornea um mecanismo de atualizao no seu aplicativo. Caso necessite atualizar seu aplicativo devido a uma alterao na verso do Webkit que vem com o AIR, o mecanismo de atualizao do AIR pode solicitar que o usurio instale a nova verso do aplicativo. A tabela a seguir lista a verso do WebKit utilizado em cada lanamento do AIR. A verso de lanamento correspondente mais prxima do navegador web Safari tambm fornecida:
Verso do AIR 1.0 1.1 1.5 2.0 2.5 2.6 Verso do WebKit 420 523 526.9 531.9 531.9 531.9 Verso do Safari 2.04 3.04 4.0 Beta 4.03 4.03 4.03

Voc sempre pode determinar a verso instalada do WebKit examinando a sequncia de caracteres de agente do usurio retornado por um objeto HTMLLoader:
var htmlLoader:HTMLLoader = new HTMLLoader(); trace( htmlLoader.userAgent );

Lembre-se que a verso do WebKit utilizado no AIR no idntica a verso de cdigo aberto. Alguns recursos no so suportados no AIR e a verso do AIR pode conter correes de segurana e de falhas que ainda no esto disponveis na verso correspondente do WebKit. Recursos do WebKit no suportados no AIR na pgina 963. Como aplicativos AIR so executados diretamente na rea de trabalho, com acesso completo ao sistema de arquivos, o modelo de segurana para contedo HTML mais rigoroso que o modelo de segurana de um navegador da Web tpico. No AIR, apenas o contedo carregado do diretrio de instalao do aplicativo colocado na caixa de proteo do aplicativo. A caixa de proteo do aplicativo tem o nvel mais alto de privilgio e permite acesso s APIs do AIR. O AIR coloca outro contedo em caixas de proteo isoladas com base na origem do contedo. Arquivos carregados do sistema de arquivos entram em uma caixa de proteo local. Arquivos carregados da rede usando os protocolos http: ou https: entram em uma caixa de proteo baseada no domnio do servidor remoto. O contedo nessas caixas de proteo que no so de aplicativo no pode acessar nenhuma API do AIR e executado da mesma forma que em um navegador da Web tpico. O contedo HTML no AIR no exibe contedo SWF ou PDF se as configuraes de alfa, dimensionamento ou transparncia forem aplicadas. Para obter informaes, consulte Consideraes ao carregar contedo SWF ou PDF em uma pgina HTML na pgina 993 e Transparncia de janelas na pgina 877.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Sobre o ambiente HTML

948

Mais tpicos da Ajuda

Referncia DOM do Webkit Referncia HTML do Safari Referncia CSS do Safari www.webkit.org

Viso geral do ambiente HTML

Adobe AIR 1.0 e posterior O Adobe AIR fornece um ambiente JavaScript completo do tipo de navegador com um processador de HTML, um modelo de objeto de documento e um intrprete do JavaScript. O ambiente JavaScript representado pela classe HTMLLoader do AIR. Em janelas HTML, um objeto HTMLLoader contm todo o contedo HTML e est, por sua vez, contido em um objeto NativeWindow. Em contedo SWF, a classe HTMLLoader, que estende a classe Sprite, pode ser adicionada lista de exibio de um estgio como qualquer outro objeto de exibio. As propriedades da classe no ActionScript 3.0 so descritas em Script no continer HTML do AIR na pgina 991 e na Referncia do ActionScript 3.0 para a plataforma Adobe Flash. Na estrutura do Flex, a classe HTMLLoader do AIR delimitada em um componente mx:HTML. O componente mx:HTML estende a classe UIComponent, para que possa ser usado diretamente com outros contineres do Flex. O ambiente JavaScript no componente mx:HTML , de outro modo, idntico.

Sobre o ambiente JavaScript e seu relacionamento com o host AIR

Adobe AIR 1.0 e posterior O diagrama a seguir ilustra o relacionamento entre o ambiente JavaScript e o ambiente de tempo de execuo do AIR. Embora apenas uma nica janela nativa seja exibida, um aplicativo AIR pode conter vrias janelas. (E uma nica janela pode conter vrios objetos HTMLLoader.)

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Sobre o ambiente HTML

949

Ambiente de tempo de execuo do AIR

NativeWindow

HTMLLoader window Ambiente do JavaScript window

document

htmlLoader

body

head

nativeWindow tempo de execuo

h1

div

table

O ambiente JavaScript possui seus prprios objetos Document e Window. O cdigo JavaScript pode interagir com o ambiente de tempo de execuo do AIR por meio das propriedades runtime, nativeWindow e htmlLoader. O cdigo ActionScript pode interagir com o ambiente JavaScript pela propriedade window de um objeto HTMLLoader, que uma referncia ao objeto Window do JavaScript. Alm disso, os objetos ActionScript e JavaScript podem ouvir eventos despachados por objetos AIR e JavaScript.

A propriedade runtime fornece acesso a classes API do AIR, permitindo que voc crie novos objetos do AIR, bem como membros de classe de acesso (tambm chamados estticos). Para acessar uma API do AIR, voc adiciona o nome da classe, com pacote, propriedade runtime. Por exemplo, para criar um objeto File, voc usaria a instruo:
var file = new window.runtime.filesystem.File();

Nota: O SDK do AIR fornece um arquivo JavaScript, AIRAliases.js, que define aliases mais convenientes para as classes do AIR usadas mais comumente. Quando voc importa esse arquivo, pode usar a forma mais curta air.Class em vez de window.runtime.package.Class. Por exemplo, voc poderia criar o objeto File com new air.File(). O objeto NativeWindow fornece propriedades para controlar a janela da rea de trabalho. De uma pgina HTML, voc pode acessar o objeto NativeWindow contido com a propriedade window.nativeWindow. O objeto HTMLLoader fornece propriedades, mtodos e eventos para controlar como o contedo carregado e processado. De uma pgina HTML, voc pode acessar o objeto HTMLLoader pai com a propriedade window.htmlLoader.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Sobre o ambiente HTML

950

Importante: Apenas pginas instaladas como parte de um aplicativo possuem as propriedades htmlLoader, nativeWindow ou runtime e apenas quando carregadas como o documento de nvel superior. Essas propriedades no so adicionadas quando um documento carregado em um frame ou iframe. (Um documento filho pode acessar essas propriedades no documento pai desde que ele esteja na mesma caixa de proteo de segurana. Por exemplo, um documento carregado em um frame poderia acessar a propriedade runtime de seu pai com parent.runtime.)

Sobre a segurana
Adobe AIR 1.0 e posterior O AIR executa todos os cdigos em uma caixa de proteo de segurana baseada no domnio de origem. O contedo do aplicativo, limitado ao contedo carregado do diretrio de instalao do aplicativo, colocado na caixa de proteo do aplicativo. O acesso ao ambiente de tempo de execuo e s APIs do AIR est disponvel apenas para HTML e JavaScript em execuo nessa caixa de proteo. Ao mesmo tempo, a maior parte da execuo e avaliao dinmica de JavaScript bloqueada na caixa de proteo do aplicativo aps todos os manipuladores da pgina de evento load terem sido retornados. Voc pode mapear uma pgina de aplicativo em uma caixa de proteo que no seja de aplicativo carregando a pgina em um frame ou iframe e definindo os atributos sandboxRoot e documentRoot especficos do AIR do frame. Definindo o valor sandboxRoot para um domnio remoto real, voc pode habilitar o contedo da caixa de proteo para cruzar contedo de scripts nesse domnio. Mapear pginas dessa maneira pode ser til ao carregar e fazer o script de contedo remoto, como em um aplicativo mash-up. Outra maneira de permitir que o contedo de aplicativo e que no de aplicativo cruze scripts entre si, e a nica maneira de fornecer acesso a contedo de no-aplicativo s APIs do AIR, criar uma ponte de caixa de proteo. Uma ponte pai-para-filho permite contedo em um frame filho, iframe ou window para acessar mtodos designados e propriedades definidas na caixa de proteo do aplicativo. Por outro lado, uma ponte filho-para-pai permite que contedo de aplicativo acesse mtodos e propriedades designadas definidas na caixa de proteo do filho. As pontes de caixa de proteo so estabelecidas pela definio das propriedades parentSandboxBridge e childSandboxBridge do objeto window. Para obter mais informaes, consulte Segurana HTML no Adobe AIR na pgina 1067 e Elementos HTML frame e iframe na pgina 958.

Sobre plug-ins e objetos incorporados

Adobe AIR 1.0 e posterior O AIR suporta o plug-in do Adobe Acrobat. Os usurios devem ter o Acrobat ou Adobe Reader 8.1 (ou superior) para exibir contedo PDF. O objeto HTMLLoader fornece uma propriedade para verificar se o sistema de um usurio pode exibir PDF. O contedo de arquivo SWF tambm pode ser exibido no ambiente HTML, mas esse recurso incorporado ao AIR e no usa um plug-in externo. Nenhum outro plug-in de Webkit suportado no AIR.

Mais tpicos da Ajuda

Segurana HTML no Adobe AIR na pgina 1067 Caixas de proteo HTML na pgina 951 Elementos HTML frame e iframe na pgina 958 Objeto Window do JavaScript na pgina 956

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Sobre o ambiente HTML

951

O objeto XMLHttpRequest na pgina 952 Incluso de contedo em PDF no AIR na pgina 532

AIR e Webkit
Adobe AIR 1.0 e posterior O Adobe AIR usa o mecanismo do Webkit de cdigo aberto, tambm usado no navegador da Web Safari. O AIR adiciona vrias extenses para permitir acesso s classes e objetos de tempo de execuo, bem como segurana. Alm disso, o Webkit por si s adiciona recursos no includos nos padres da W3C para HTML, CSS e JavaScript. Apenas as adies do AIR e as extenses do Webkit mais dignas de nota so tratadas aqui. Para obter uma documentao adicional sobre HTML no-padro, CSS e JavaScript, consulte www.webkit.org e developer.apple.com. Para obter informaes sobre padres, consulte o site da W3C. O Mozilla tambm fornece uma referncia geral valiosa sobre tpicos HTML, CSS e DOM ( claro que os mecanismos do Webkit e da Mozilla no so idnticos).

JavaScript no AIR
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O AIR faz vrias alteraes no comportamento tpico de objetos JavaScript comuns. Vrias dessas alteraes so feitas para tornar fcil escrever aplicativos seguros no AIR. Ao mesmo tempo, essas diferenas em comportamento significam que alguns padres de codificao JavaScript comuns, e aplicativos Web existentes usando esses padres, nem sempre podem executar conforme esperado no AIR. Para obter informaes sobre como corrigir esses tipos de problemas, consulte Como evitar erros JavaScript relacionados segurana na pgina 969.

Caixas de proteo HTML

Adobe AIR 1.0 e posterior O AIR coloca contedo em caixas de proteo isoladas de acordo com a origem do contedo. As regras da caixa de proteo so consistentes com a poltica de mesma origem implementada pela maioria dos navegadores da Web, bem como as regras para caixas de proteo implementadas pelo Adobe Flash Player. Alm disso, o AIR fornece um novo tipo de caixa de proteo do aplicativo para conter e proteger contedo do aplicativo. Consulte Caixas de proteo de segurana na pgina 1029 para obter mais informaes sobre os tipos de caixas de proteo que voc pode encontrar ao desenvolver aplicativos AIR. O acesso ao ambiente de tempo de execuo e s APIs do AIR est disponvel apenas para HTML e JavaScript em execuo na caixa de proteo do aplicativo. Ao mesmo tempo, no entanto, a execuo e avaliao dinmica de JavaScript, em suas vrias formas, so amplamente restritas na caixa de proteo do aplicativo por razes de segurana. Essas restries so adequadas quer seu aplicativo realmente carregue ou no informaes diretamente de um servidor. (At mesmo contedo de arquivo, seqncias de caracteres coladas e entrada do usurio direta podem ser incertos.) A origem do contedo em uma pgina determina a caixa de proteo qual ele consignado. Apenas o contedo carregado do diretrio do aplicativo (o diretrio de instalao referenciado pelo app: esquema de URL) colocado na caixa de proteo do aplicativo. O contedo carregado do sistema de arquivos colocado na caixa de proteo local com sistema de arquivos ou confivel local, que permite acesso e interao com contedo no sistema de arquivos local, mas no contedo remoto. O contedo carregado da rede colocado em uma caixa de proteo remota correspondente ao seu domnio de origem.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Sobre o ambiente HTML

952

Para permitir que uma pgina de aplicativo interaja livremente com o contedo em uma caixa de proteo remota, a pgina pode ser mapeada para o mesmo domnio do contedo remoto. Por exemplo, se voc escreve um aplicativo que exibe dados de mapas de um servio de Internet, a pgina do seu aplicativo que carrega e exibe contedo do servio poderia ser mapeada para o domnio de servio. Os atributos para mapear pginas em um domnio e uma caixa de proteo remota so novos atributos adicionados aos elementos HTML frame e iframe. Para permitir contedo em uma caixa de proteo que no seja de aplicativo para usar com segurana recursos do AIR, voc pode configurar uma ponte de caixa de proteo pai. Para permitir que o contedo de aplicativo chame com segurana mtodos e acesse propriedades de contedo em outras caixas de proteo, voc pode configurar uma ponte de caixa de proteo filha. Segurana aqui significa que o contedo remoto no pode obter acidentalmente referncias a objetos, propriedades ou mtodos que no so expostos explicitamente. Apenas tipos de dados simples, funes e objetos annimos podem ser transmitidos pela ponte. No entanto, voc ainda deve evitar expor explicitamente funes potencialmente perigosas. Se, por exemplo, voc exps uma interface que permitiu ao contedo remoto ler e escrever arquivos em qualquer lugar no sistema de um usurio, voc pode estar fornecendo ao contedo remoto o meio para fazer um dano considervel aos seus usurios.

Funo eval() do JavaScript

Adobe AIR 1.0 e posterior O uso da funo eval() restrito caixa de proteo do aplicativo depois que o carregamento de uma pgina tiver sido concludo. Alguns usos so permitidos para que dados formatados por JSON possam ser analisados com segurana, mas qualquer avaliao que resulte em instrues executveis ter como conseqncia um erro. O captulo Restries de cdigo de contedo em caixas de proteo distintas na pgina 1070 descreve os usos permitidos da funo eval().

Construtores de funes
Adobe AIR 1.0 e posterior Na caixa de proteo do aplicativo, os construtores de funes podem ser usados antes que o carregamento de uma pgina tenha sido concludo. Aps todos os manipuladores de eventos load da pgina terem sido concludos, novas funes no podem ser criadas.

Carregamento de scripts externos

Adobe AIR 1.0 e posterior As pginas HTML na caixa de proteo do aplicativo no podem usar a tag de script para carregar arquivos de JavaScript de fora do diretrio do aplicativo. Para uma pgina no seu aplicativo carregar um script de fora do diretrio do aplicativo, a pgina deve ser mapeada para uma caixa de proteo que no seja de aplicativo.

O objeto XMLHttpRequest
Adobe AIR 1.0 e posterior O AIR fornece um objeto XMLHttpRequest (XHR) que os aplicativos podem usar para fazer solicitaes de dados. O exemplo a seguir ilustra uma solicitao de dados simples:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Sobre o ambiente HTML

953

xmlhttp = new XMLHttpRequest(); xmlhttp.open("GET", "http:/www.example.com/file.data", true); xmlhttp.onreadystatechange = function() { if (xmlhttp.readyState == 4) { //do something with data... } } xmlhttp.send(null);

Em contraste com um navegador, o AIR permite que o contedo em execuo na caixa de proteo do aplicativo solicite dados de qualquer domnio. O resultado de um XHR que contm uma seqncia de caracteres JSON pode ser avaliado em objetos de dados, a menos que o resultado tambm contenha cdigo executvel. Se instrues executveis esto presentes no resultado de XHR, um erro lanado e a tentativa de avaliao falha. Para impedir a injeo acidental de cdigo de fontes remotas, os XHRs sncronos retornam um resultado vazio se feito antes que o carregamento de uma pgina seja concludo. Os XHRs assncronos sempre so retornados aps o carregamento de uma pgina. Por padro, o AIR bloqueia XMLHttpRequests entre vrios domnios em caixas de proteo de no-aplicativos. Uma janela pai na caixa de proteo do aplicativo pode optar por permitir solicitaes entre domnios em um frame filho com contedo em uma caixa de proteo que no seja de aplicativo definindo allowCrossDomainXHR, um atributo adicionado pelo AIR, como true no elemento frame ou iframe contido:
<iframe id="mashup" src="http://www.example.com/map.html" allowCrossDomainXHR="true" </iframe>

Nota: Quando conveniente, a classe URLStream do AIR tambm pode ser usada para fazer o download de dados. Se voc despachar um XMLHttpRequest para um servidor remoto de um frame ou iframe contendo contedo de aplicativo que tenha sido mapeado para uma caixa de proteo remota, verifique se a URL de mapeamento no mascara o endereo do servidor usado no XHR. Por exemplo, considere a seguinte definio de iframe, que mapeia contedo de aplicativo em uma caixa de proteo remota para o domnio example.com:
<iframe id="mashup" src="http://www.example.com/map.html" documentRoot="app:/sandbox/" sandboxRoot="http://www.example.com/" allowCrossDomainXHR="true" </iframe>

Como o atributo sandboxRoot remapeia a URL raiz do endereo www.example.com, todas as solicitaes so carregadas do diretrio do aplicativo, e no do servidor remoto. As solicitaes so remapeadas derivem elas de navegao de pgina ou de um XMLHttpRequest. Para evitar bloquear solicitaes de dados acidentalmente para o seu servidor remoto, mapeie sandboxRoot para um subdiretrio da URL remota, e no da raiz. O diretrio no precisa existir. Por exemplo, para permitir solicitaes ao www.example.com para ser carregado do servidor remoto, e no do diretrio do aplicativo, altere o iframe anterior para o seguinte:
<iframe id="mashup" src="http://www.example.com/map.html" documentRoot="app:/sandbox/" sandboxRoot="http://www.example.com/air/" allowCrossDomainXHR="true" </iframe>

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Sobre o ambiente HTML

954

Nesse caso, apenas contedo no subdiretrio air carregado localmente. Para obter mais informaes sobre o mapeamento de caixa de proteo, consulte Elementos HTML frame e iframe na pgina 958 e Segurana HTML no Adobe AIR na pgina 1067.

Cookies
Adobe AIR 1.0 e posterior Em aplicativos AIR, apenas o contedo em caixas de proteo remotas (contedo carregado de fontes http: e https:) pode usar cookies (a propriedade document.cookie). Na caixa de proteo do aplicativo, h outras formas para armazenar os dados persistentes, incluindo as classes EncryptedLocalStore, SharedObject e FileStream.

O objeto Clipboard
Adobe AIR 1.0 e posterior A API Clipboard do WebKit conduzida com os seguintes eventos: copy, cut e paste. O objeto event transmitido nesses eventos fornece acesso rea de transferncia pela propriedade clipboardData. Use os seguintes mtodos do objeto clipboardData para ler ou escrever dados da rea de transferncia:
Mtodo clearData(mimeType) getData(mimeType) Descrio Limpa os dados da rea de transferncia. Defina o parmetro mimeType para o tipo MIME dos dados a apagar. Obtm os dados da rea de transferncia. Esse mtodo pode ser chamado apenas em um manipulador para o evento paste. Defina o parmetro mimeType para o tipo MIME dos dados a retornar. Copia dados para a rea de transferncia. Defina o parmetro mimeType para o tipo MIME dos dados.

setData(mimeType, data)

O cdigo JavaScript fora da caixa de proteo do aplicativo pode acessar apenas a rea de transferncia por esses eventos. No entanto, o contedo na caixa de proteo do aplicativo pode acessar a rea de transferncia do sistema diretamente usando a classe Clipboard do AIR. Por exemplo, voc poderia usar a seguinte instruo para obter dados do formato do texto na rea de transferncia:
var clipping = air.Clipboard.generalClipboard.getData("text/plain", air.ClipboardTransferMode.ORIGINAL_ONLY);

Os tipos MIME de dados vlidos so:

Tipo MIME Texto HTML URL Bitmap Lista de arquivos Valor "text/plain" "text/html" "text/uri-list" "image/x-vnd.adobe.air.bitmap" "application/x-vnd.adobe.air.file-list"

Importante: Apenas contedo na caixa de proteo do aplicativo pode acessar dados de arquivos presentes na rea de transferncia. Se um contedo que no seja de aplicativo tentar acessar um objeto de arquivo da rea de transferncia, ser lanado um erro de segurana. Para obter mais informaes sobre o uso da rea de transferncia, consulte Copiar e colar na pgina 577 e Utilizao da rea de trabalho de JavaScript (Centro de desenvolvedores da Apple).

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Sobre o ambiente HTML

955

Arrastar e soltar
Adobe AIR 1.0 e posterior Gestos de arrastar e soltar para dentro e para fora do HTML produzem os seguintes eventos DOM: dragstart, drag, dragend, dragenter, dragover, dragleave e drop. O objeto event transmitido nesses eventos fornece acesso aos dados arrastados pela propriedade dataTransfer. A propriedade dataTransfer faz referncia a um objeto que fornece os mesmos mtodos do objeto clipboardData associado a um evento clipboard. Por exemplo, voc poderia usar a seguinte funo para obter dados do formato de um evento drop:
function onDrop(dragEvent){ return dragEvent.dataTransfer.getData("text/plain", air.ClipboardTransferMode.ORIGINAL_ONLY); }

O objeto dataTransfer possui os seguintes membros importantes:

Membro clearData(mimeType) getData(mimeType) Descrio Limpa os dados. Defina o parmetro mimeType para o tipo MIME da representao de dados para apagar. Obtm os dados arrastados. Esse mtodo pode ser chamado apenas em um manipulador para o evento drop. Defina o parmetro mimeType para o tipo MIME dos dados a obter. Defina os dados a serem arrastados. Defina o parmetro mimeType para o tipo MIME dos dados. Uma matriz de seqncias de caracteres contendo os tipos MIME de todas as representaes de dados disponveis no momento no objeto dataTransfer. Especifica se os dados que esto sendo arrastados podem ser copiados, movidos, vinculados ou alguma combinao disso. Defina a propriedade effectsAllowed no manipulador para o evento dragstart. Especifica quais dos efeitos drop permitidos so suportados por um drag target. Defina a propriedade
dropEffect no manipulador para o evento dragEnter. Durante a ao de arrastar, o cursor muda para indicar que efeito ocorreria se o usurio soltasse o mouse. Se nenhum dropEffect for especificado, um efeito da propriedade effectsAllowed ser escolhido. O efeito de copiar tem prioridade sobre o efeito de

setData(mimeType, data) tipos

effectsAllowed

dropEffect

mover, que por si s tem prioridade sobre o efeito de vincular. O usurio pode modificar a prioridade padro usando o teclado.

Para obter mais informaes sobre como adicionar suporte para arrastar e soltar em um aplicativo AIR, consulte Arrastar e soltar no AIR na pgina 590 e Utilizao de arrastar e soltar de JavaScript (Centro de desenvolvedores da Apple).

Propriedades innerHTML e outerHTML

Adobe AIR 1.0 e posterior O AIR coloca restries de segurana sobre o uso das propriedades innerHTML e outerHTML para contedo em execuo na caixa de proteo do aplicativo. Antes do evento de carregamento da pgina, bem como durante a execuo de qualquer manipulador de evento de carregamento, o uso das propriedades innerHTML e outerHTML irrestrito. No entanto, depois que a pgina carregada, voc pode apenas usar as propriedades innerHTML ou outerHTML para adicionar contedo esttico ao documento. Qualquer instruo na seqncia de caracteres atribuda a innerHTML ou outerHTML avaliada como cdigo executvel ignorada. Por exemplo, se voc incluir um atributo de retorno de evento em uma definio de elemento, o ouvinte de eventos no ser adicionado. Da mesma forma, tags <script> incorporadas no so avaliadas. Para obter mais informaes, consulte Segurana HTML no Adobe AIR na pgina 1067.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Sobre o ambiente HTML

956

Mtodos Document.write() e Document.writeln()

Adobe AIR 1.0 e posterior O uso dos mtodos write() e writeln() no restrito caixa de proteo do aplicativo antes do evento load da pgina. No entanto, depois que a pgina carregada, chamar um desses mtodos no limpa a pgina ou cria uma nova. Em uma caixa de proteo que no seja de aplicativo, como na maioria dos navegadores da Web, chamar document.write() ou writeln(), aps a concluso do carregamento de uma pgina, limpa a pgina atual e abre uma nova em branco.

Propriedade Document.designMode
Adobe AIR 1.0 e posterior Defina a propriedade document.designMode para um valor de on para tornar todos os elementos do documento editveis. O suporte a editor incorporado inclui editar texto, copiar, colar e arrastar e soltar. Definir designMode como on equivalente a definir a propriedade contentEditable do elemento body como true. Voc pode usar a propriedade contentEditable na maioria dos elementos HTML para definir que sees de um documento so editveis. Consulte Atributo contentEditable HTML na pgina 961 para obter informaes adicionais.

Eventos unload (para objetos body e frameset)

Adobe AIR 1.0 e posterior Na tag de nvel superior frameset ou body de uma janela (incluindo a janela principal do aplicativo), no use o evento unload para responder janela (ou aplicativo) que est sendo fechada. Em vez disso, use o evento exiting do objeto NativeApplication (para detectar quando um aplicativo est sendo fechando). Em vez disso, use o evento exiting do objeto NativeWindow (para detectar quando um aplicativo est sendo fechado). Por exemplo, o seguinte cdigo JavaScript exibe uma mensagem ("Goodbye.") quando o usurio fecha o aplicativo:
var app = air.NativeApplication.nativeApplication; app.addEventListener(air.Event.EXITING, closeHandler); function closeHandler(event) { alert("Goodbye."); }

No entanto, scripts podem responder com xito ao evento unload causado pela navegao de um contedo frame, iframe ou window de nvel superior. Nota: Essas limitaes podem ser removidas em uma verso futura do Adobe AIR.

Objeto Window do JavaScript

Adobe AIR 1.0 e posterior O objeto Window permanece o objeto global no contexto de execuo do JavaScript. Na caixa de proteo do aplicativo, o AIR adiciona novas propriedades ao objeto Window do JavaScript para fornecer acesso s classes incorporadas do AIR, bem como importantes objetos de host. Alm disso, alguns mtodos e propriedades se comportam de modo diferente dependendo se esto ou no na caixa de proteo do aplicativo.
Propriedade Window.runtime A propriedade runtime permite que voc instancie e use classes runtime incorporadas da caixa de proteo do aplicativo. Essas classes incluem APIs do AIR e do Flash Player (mas no, por exemplo, a estrutura do Flex). Por exemplo, a seguinte instruo cria um objeto de arquivo do AIR:
var preferencesFile = new window.runtime.flash.filesystem.File();

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Sobre o ambiente HTML

957

O arquivo AIRAliases.js, fornecido no SDK do AIR, contm definies de aliases que permitem a voc encurtar tais referncias. Por exemplo, quando AIRAliases.js importado em uma pgina, um objeto File pode ser criado com a seguinte instruo:
var preferencesFile = new air.File();

A propriedade window.runtime somente definida para contedo dentro da caixa de proteo do aplicativo e apenas para o documento pai de uma pgina com frames ou iframes. Consulte Uso do arquivo AIRAliases.js na pgina 975.
Propriedade Window.nativeWindow A propriedade nativeWindow fornece uma referncia ao objeto de janela nativa

subjacente. Com essa propriedade, voc pode fazer o script de funes e propriedades de janela, como posio da tela, tamanho e visibilidade e manipular eventos de janela, como fechar, redimensionar e mover. Por exemplo, a seguinte instruo fecha a janela:
window.nativeWindow.close();

Nota: Os recursos de controle da janela fornecidos pelo objeto NativeWindow sobrepem os recursos fornecidos pelo objeto Window do JavaScript. Em tais casos, voc pode usar qualquer mtodo que considerar mais conveniente. A propriedade window.nativeWindow somente definida para contedo dentro da caixa de proteo do aplicativo e apenas para o documento pai de uma pgina com frames ou iframes.
Propriedade Window.htmlLoader A propriedade htmlLoader fornece uma referncia ao objeto AIR HTMLLoader que contm o contedo HTML. Com essa propriedade, voc pode fazer o script da aparncia e do comportamento do ambiente HTML. Por exemplo, voc pode usar a propriedade htmlLoader.paintsDefaultBackground para determinar se o controle pinta um plano de fundo branco padro:
window.htmlLoader.paintsDefaultBackground = false;

Nota: O objeto HTMLLoader por si s possui uma propriedade window, que faz referncia ao objeto Window do JavaScript do contedo HTML contido nele. Voc pode usar essa propriedade para acessar o ambiente JavaScript por uma referncia ao HTMLLoader contido. A propriedade window.htmlLoader somente definida para contedo dentro da caixa de proteo do aplicativo e apenas para o documento pai de uma pgina com frames ou iframes.
Propriedades Window.parentSandboxBridge e Window.childSandboxBridge As propriedades
parentSandboxBridge e childSandboxBridge permitem que voc defina uma interface entre um frame filho e um pai. Para obter mais informaes, consulte Contedo cross-scripting em caixas de proteo de segurana distintas na pgina 986.

Funes Window.setTimeout() e Window.setInterval() O AIR coloca restries de segurana sobre o uso das funes
setTimeout() e setInterval() na caixa de proteo do aplicativo. No possvel definir o cdigo a ser executado

como uma seqncia de caracteres ao chamar setTimeout() ou setInterval(). necessrio usar uma referncia de funo. Para obter mais informaes, consulte setTimeout() e setInterval() na pgina 972.
Funo Window.open() Quando chamado por cdigo em execuo em uma caixa de proteo que no seja de

aplicativo, o mtodo open() abrir somente uma janela quando chamado como resultado da interao do usurio (como um clique do mouse ou pressionamento de tecla). Alm disso, o ttulo da janela prefixado com o ttulo do aplicativo (para impedir que janelas sejam abertas por contedo remoto personifiquem janelas abertas pelo aplicativo). Para obter mais informaes, consulte o captulo Restries na chamada do mtodo window.open() de JavaScript na pgina 1073.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Sobre o ambiente HTML

958

Objeto air.NativeApplication
Adobe AIR 1.0 e posterior O objeto NativeApplication fornece informaes sobre o estado do aplicativo, despacha vrios eventos de nvel de aplicativo importantes e fornece funes teis para controlar o comportamento do aplicativo. Uma nica instncia do objeto NativeApplication criada automaticamente e pode ser acessada pela propriedade NativeApplication.nativeApplication definida pela classe. Para acessar o objeto do cdigo JavaScript, voc poderia usar:
var app = window.runtime.flash.desktop.NativeApplication.nativeApplication;

Ou, se o script AIRAliases.js tiver sido importado, voc poderia usar a forma mais curta:
var app = air.NativeApplication.nativeApplication;

O objeto NativeApplication pode apenas ser acessado de dentro da caixa de proteo do aplicativo. Para obter mais informaes sobre o objeto NativeApplication, consulte Trabalho com informaes de tempo de execuo do AIR e de sistema operacional na pgina 870.

O esquema de URL JavaScript

Adobe AIR 1.0 e posterior A execuo do cdigo definida em um esquema de URL de JavaScript (como em href="javascript:alert('Test')") bloqueada na caixa de proteo do aplicativo. Nenhum erro lanado.

HTML no AIR
Adobe AIR 1.0 e posterior O AIR e o WebKit definem alguns atributos e elementos HTML no-padro, incluindo: Elementos HTML frame e iframe na pgina 958 Manipuladores de eventos de elementos HTML na pgina 960

Elementos HTML frame e iframe

Adobe AIR 1.0 e posterior O AIR adiciona novos atributos aos elementos frame e iframe de contedo na caixa de proteo do aplicativo:
Atributo sandboxRoot O atributo sandboxRoot especifica um domnio de origem alternativo que no seja de

aplicativo para o arquivo especificado pelo atributo src do frame. O arquivo carregado na caixa de proteo que no seja de aplicativo correspondente ao domnio especificado. O contedo no arquivo e o contedo carregado do domnio especificado podem cruzar scripts entre si. Importante: Se voc definir o valor de sandboxRoot para a URL base do domnio, todas as solicitaes para contedo desse domnio sero carregadas do diretrio do aplicativo, e no do servidor remoto (resulte a solicitao de navegao de pgina, de um XMLHttpRequest ou de qualquer outro meio de carregar contedo).
Atributo documentRoot O atributo documentRoot especifica o diretrio local a partir do qual carregar URLs que

procuram endereos para arquivos no local especificado por sandboxRoot.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Sobre o ambiente HTML

959

Ao consultar endereos de URLs, no atributo src do frame ou no contedo carregado no frame, a parte da URL que corresponde ao valor especificado em sandboxRoot substituda pelo valor especificado em documentRoot. Portanto, na seguinte tag de frame:
<iframe src="http://www.example.com/air/child.html" documentRoot="app:/sandbox/" sandboxRoot="http://www.example.com/air/"/> child.html carregado do subdiretrio sandbox da pasta de instalao do aplicativo. Os endereos das URLs relativas em child.html so procurados com base no diretrio sandbox. Observe que qualquer arquivo no servidor remoto em www.example.com/air no pode ser acessado no frame, uma vez que o AIR tentaria carreg-lo do diretrio app:/sandbox/.

Atributo allowCrossDomainXHR Inclua allowCrossDomainXHR="allowCrossDomainXHR" na tag de frame de

abertura para permitir que o contedo no frame faa XMLHttpRequests para qualquer domnio remoto. Por padro, o contedo que no de aplicativo apenas pode fazer tais solicitaes em seu prprio domnio de origem. Existem implicaes de segurana srias envolvidas na permisso de XHRs entre domnios. O cdigo da pgina pode trocar dados com qualquer domnio. Se o contedo mal-intencionado de certa forma injetado na pgina, qualquer dado acessvel para cdigo na caixa de proteo atual pode ficar comprometido. Apenas ative XHRs entre domnios para pginas que voc cria e controla e somente quando o carregamento de dados entre domnios for realmente necessrio. Alm disso, valide cuidadosamente todos os dados externos carregados pela pgina para impedir a injeo de dados ou outras formas de ataque. Importante: Se o atributo allowCrossDomainXHR for includo em um elemento frame ou iframe, XHRs entre domnios sero ativados (a menos que o valor atribudo seja "0" ou comece com as letras "f" ou "n"). Por exemplo, definir allowCrossDomainXHR como "deny" ainda ativaria XHRs entre domnios. Deixe o atributo totalmente fora da declarao do elemento se no desejar ativar solicitaes entre domnios.
Atributo ondominitialize Especifica um manipulador de eventos para o evento dominitialize de um frame. Esse

um evento especfico do AIR disparado quando os objetos window e document do frame tiverem sido criados, mas antes que qualquer script tenha sido analisado ou elementos document tenham sido criados. O frame despacha o evento dominitialize cedo o suficiente na seqncia de carregamento de forma que qualquer script na pgina filha possa se referir a objetos, variveis e funes adicionadas ao documento filho pelo manipulador dominitialize. A pgina pai deve estar na mesma caixa de proteo da filha para adicionar ou acessar diretamente qualquer objeto em um documento filho. No entanto, um pai na caixa de proteo do aplicativo pode estabelecer uma ponte de caixa de proteo para se comunicar com contedo em uma caixa de proteo que no seja de aplicativo. Os exemplos a seguir ilustram o uso da tag iframe no AIR: Coloque child.html em uma caixa de proteo remota, sem mapear para um domnio real em um servidor remoto:
<iframe src="http://localhost/air/child.html" documentRoot="app:/sandbox/" sandboxRoot="http://localhost/air/"/>

Coloque child.html em uma caixa de proteo remota, permitindo XMLHttpRequests apenas para www.example.com:
<iframe src="http://www.example.com/air/child.html" documentRoot="app:/sandbox/" sandboxRoot="http://www.example.com/air/"/>

Coloque child.html em uma caixa de proteo remota, permitindo XMLHttpRequests para qualquer domnio remoto:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Sobre o ambiente HTML

960

<iframe src="http://www.example.com/air/child.html" documentRoot="app:/sandbox/" sandboxRoot="http://www.example.com/air/" allowCrossDomainXHR="allowCrossDomainXHR"/>

Coloque child.html em uma caixa de proteo local com sistema de arquivos:

<iframe src="file:///templates/child.html" documentRoot="app:/sandbox/" sandboxRoot="app-storage:/templates/"/>

Coloque child.html em uma caixa de proteo remota, usando o evento dominitialize para estabelecer uma ponte de caixa de proteo:
<html> <head> <script> var bridgeInterface = {}; bridgeInterface.testProperty = "Bridge engaged"; function engageBridge(){ document.getElementById("sandbox").parentSandboxBridge = bridgeInterface; } </script> </head> <body> <iframe id="sandbox" src="http://www.example.com/air/child.html" documentRoot="app:/" sandboxRoot="http://www.example.com/air/" ondominitialize="engageBridge()"/> </body> </html>

O seguinte documento child.html ilustra como o contedo filho pode acessar a ponte da caixa de proteo pai:
<html> <head> <script> document.write(window.parentSandboxBridge.testProperty); </script> </head> <body></body> </html>

Para obter mais informaes, consulte Contedo cross-scripting em caixas de proteo de segurana distintas na pgina 986 e Segurana HTML no Adobe AIR na pgina 1067.

Manipuladores de eventos de elementos HTML

Adobe AIR 1.0 e posterior Os objetos DOM no AIR e no Webkit despacham alguns eventos no encontrados no modelo de eventos DOM padro. A tabela a seguir lista os atributos de eventos relacionados que podem ser usados para especificar manipuladores para estes eventos:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Sobre o ambiente HTML

961

Nome do atributo de retorno de chamada oncontextmenu

Descrio

Chamado quando um menu de contexto invocado, como pelo clique do boto direito do mouse ou clique da tecla Command no texto selecionado. Chamado quando uma seleo em um elemento copiada. Chamado quando uma seleo em um elemento cortada. Chamado quando o DOM de um documento carregado em um frame ou iframe criado, mas antes que qualquer elemento de DOM seja criado ou script analisado. Chamado quando um elemento arrastado. Chamado quando uma ao de arrastar liberada. Chamado quando um gesto de ao de arrastar entra nos limites de um elemento. Chamado quando um gesto de ao de arrastar deixa os limites de um elemento. Chamado continuamente enquanto um gesto de ao de arrastar est dentro dos limites de um elemento. Chamado quando um gesto de ao de arrastar iniciado. Chamado quando um gesto de ao de arrastar liberado sobre um elemento. Chamado quando um erro ocorre ao carregar um elemento. Chamado quanto o texto inserido em um elemento de formulrio. Chamado quando um item colado em um elemento. Chamado quando o contedo de um elemento rolvel rolado. Chamado quando uma seleo iniciada.

oncopy oncut ondominitialize

ondrag ondragend ondragenter

ondragleave

ondragover

ondragstart ondrop

onerror oninput onpaste onscroll onselectstart

Atributo contentEditable HTML

Adobe AIR 1.0 e posterior Voc pode adicionar o atributo contentEditable a qualquer elemento HTML para permitir aos usurios editar o contedo do elemento. Por exemplo, o seguinte cdigo de exemplo HTML define todo o documento como editvel, exceto para o primeiro elemento p:
<html> <head/> <body contentEditable="true"> <h1>de Finibus Bonorum et Malorum</h1> <p contentEditable="false">Sed ut perspiciatis unde omnis iste natus error.</p> <p>At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis.</p> </body> </html>

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Sobre o ambiente HTML

962

Nota: Se voc define a propriedade document.designMode como on, todos os elementos do documento so editveis, independentemente da configurao de contentEditable para um elemento individual. No entanto, definir designMode como off no desativa a edio de elementos para os quais contentEditable true. Consulte Propriedade Document.designMode na pgina 956 para obter informaes adicionais.

Dados: URLs
Adobe AIR 2 e posterior O AIR oferece suporte a URLs data: para os seguintes elementos:

img tipo de entrada =imagem Regras CSS que permitem imagens (por exemplo: imagens de fundo)
URLs de dados permitem que voc insira dados de imagens binrias diretamente em um documento CSS ou HTML como em uma string codificada em base 64. O exemplo a seguir utiliza uma URL:dados como um segundo plano repetitivo.
<html> <head> <style> body { backgroundimage:url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGQAAABkCAMAAABHPGVmAAAAGXRFWHRTb2Z 0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAAZQTFRF%2F6cA%2F%2F%2F%2Fgxp3lwAAAAJ0Uk5T%2FwDltzBKAAA BF0lEQVR42uzZQQ7CMAxE0e%2F7X5oNCyRocWzPiJbMBZ6qpIljE%2BnwklgKG7kwUjc2IkIaxkY0CPdEsCCasws6ShX BgmBBmEagpXQQLAgWBAuSY2gaKaWPYEGwIEwg0FRmECwIFoQeQjJlhJWUEFazjFDJCkI5WYRWMgjtfEGYyQnCXD4jTCd m1zmngFpBFznwVNi5RPSbwbWnpYr%2BBHi%2FtCTfgPLEPL7jBctAKBRptXJ8M%2BprIuZKu%2BUKcg4YK1PLz7kx4bS qHyPaT4d%2B28OCJJiRBo4FCQsSA0bziT3XubMgYUG6fc5fatmGBQkL0hoJ1IaZMiQsSFiQ8vRscTjlQOI2iHZwtpHuf %2BJAYiOiJSkj8Z%2FIQ4ABANvXGLd3%2BZMrAAAAAElFTkSuQmCC'); background-repeat:repeat; } </style> </head> <body> </body> </html>

Ao utilizar URLS: dados, saiba que espaos em branco extra so insignificantes. Por exemplo, a string de dados precisa ser inserida como uma linha nica e sem quebra. Caso contrrio, as quebras de linha sero tratadas como parte dos dados e a imagem no poder ser decodificada.

CSS no AIR
Adobe AIR 1.0 e posterior O WebKit suporta vrias propriedades CSS estendidas. Muitas destas extenses utilizam o prefixo -webkit. Observe que algumas destas extenses so de natureza experimental e podem ser removidas de uma verso futura do WebKit. Para obter mais informaes sobre o suporte do WebKit para CSS e de suas extenses para p CSS, consulte Referncia do Safari CSS.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Sobre o ambiente HTML

963

Recursos do WebKit no suportados no AIR

Adobe AIR 1.0 e posterior O AIR no oferece suporte aos seguintes recursos disponveis no WebKit ou no Safari 4:

Mensagens entre domnios por meio de window.postMessage (o AIR fornece suas prprias APIs de comunicao
entre domnios)

Variveis CSS Fontes WOFF (Web Open Font Format) e SVG. Tags HTML de vdeo e udio Consultas de dispositivos de mdia Cache de aplicativos offline Imprimindo (O AIR fornece sua prpria API PrintJob) Verificadores de ortografia e gramtica SVG WAI-ARIA WebSockets (O AIR fornece suas prprias APIs de soquete) Web workers API SQL do WebKit (o AIR fornece sua prpria API) API de geolocalizao do WebKit (o AIR fornece sua prpria API de geolocalizao em dispositivos suportados) API para upload de vrios arquivos Eventos de toque do WebKit (O AIR fornece seus prprios eventos de toque) Wireless Markup Language (WML)
As listas a seguir contm APIs JavaScript especficas, elementos HTML e propriedades CSS, e valores que o AIR no suporta: Membros do objeto JavaScript Window no suportados: applicationCache()

console openDatabase() postMessage() document.print()

Tags HTML no suportadas: udio

video
Atributos HTML no suportados: aria-*

draggable

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Sobre o ambiente HTML

964

formnovalidate lista novalidate onbeforeload onhashchange onorientationchange onpagehide onpageshow onpopstate ontouchstart ontouchmove ontouchend ontouchcancel onwebkitbeginfullscreen onwebkitendfullscreen pattern required sandbox
Eventos JavaScript no suportados: beforeload

hashchange orientationchange pagehide pageshow popstate touchstart touchmove touchend touchcancel webkitbeginfullscreen webkitendfullscreen
Propriedades CSS no suportadas: background-clip

background-origin (uso -webkit-background-origin) background-repeat-x background-repeat-y

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Sobre o ambiente HTML

965

background-size (uso -webkit-background-size) border-bottom-left-radius border-bottom-right-radius border-radius border-top-left-radius border-top-right-radius text-rendering -webkit-animation-play-state -webkit-background-clip -webkit-color-correction -webkit-font-smoothing
Valores CSS no suportados: valores de propriedade de aparncia:

media-volume-slider-container media-volume-slider media-volume-sliderthumb outer-spin-button border-box (background-clip e background-origin) contain (background-size) content-box (background-clip e background-origin) cover (background-size) valores de lista de propriedade: afar amharic amharic-abegede cjk-earthly-branch cjk-heavenly-stem ethiopic ethiopic-abegede ethiopic-abegede-am-et ethiopic-abegede-gez ethiopic-abegede-ti-er ethiopic-abegede-ti-et ethiopic-halehame-aa-er ethiopic-halehame-aa-et ethiopic-halehame-am-et

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Sobre o ambiente HTML

966

ethiopic-halehame-gez ethiopic-halehame-om-et ethiopic-halehame-sid-et ethiopic-halehame-so-et ethiopic-halehame-ti-er ethiopic-halehame-ti-et ethiopic-halehame-tig hangul hangul-consonant lower-norwegian oromo sidama somali tigre tigrinya-er tigrinya-er-abegede tigrinya-et tigrinya-et-abegede upper-greek upper-norwegian -wap-marquee (propriedade display)

ltima atualizao em 29/3/2011

967

Captulo 56: Programao de HTML e JavaScript no AIR

Adobe AIR 1.0 e posterior Vrios tpicos de programao so exclusivos para o desenvolvimento de aplicativos Adobe AIR com HTML e JavaScript. As seguintes informaes so importantes caso voc esteja programando um aplicativo baseado em HTML ou um aplicativo AIR baseado em SWF que execute HTML e JavaScript usando a classe HTMLLoader (ou o componente mx:HTML Flex).

Sobre a classe HTMLLoader

Adobe AIR 1.0 e posterior A classe HTMLLoader do Adobe AIR define o objeto de exibio que pode mostrar contedo HTML em um aplicativo AIR. Os aplicativos baseados em SWF podem adicionar um controle HTMLLoader a uma janela existente ou criar uma janela HTML que contenha automaticamente um objeto HTMLLoader com HTMLLoader.createRootWindow(). O objeto HTMLLoader pode ser acessado por meio da propriedade window.htmlLoader de JavaScript de dentro da pgina HTML carregada.

Carregamento de contedo HTML de uma URL

Adobe AIR 1.0 e posterior O cdigo a seguir carrega uma URL no objeto HTMLLoader (adicione o HTMLLoader como filho do estgio ou outro continer do objeto de exibio para exibir o contedo HTML no seu aplicativo):
import flash.html.HTMLLoader; var html:HTMLLoader = new HTMLLoader; html.width = 400; html.height = 600; var urlReq:URLRequest = new URLRequest("http://www.adobe.com/"); html.load(urlReq);

Por padro, as propriedades width e height de um objeto HTMLLoader so definidas como 0. Voc desejar definir essas dimenses quando adicionar um objeto HTMLLoader ao palco. O HTMLLoader despacha diversos eventos medida que a pgina carrega. Voc pode usar esses eventos para determinar quando seguro interagir com a pgina carregada. Esses eventos so descritos em Tratamento de eventos relacionados a HTML no AIR na pgina 1010. Nota: Na estrutura do Flex, somente as classes que estendem a classe UIComponent podem ser adicionadas como filhos de componentes do recipiente Flex. Por esse motivo, voc no pode adicionar diretamente o HTMLLoader como filho de um componente do recipiente do Flex; no entanto, possvel usar o controle Flex mx:HTML; voc pode criar uma classe personalizada que estende UIComponent e contm um HTMLLoader como filho do UIComponent ou pode adicionar o HTMLLoader como filho de um UIComponent e adicionar o UIComponent ao recipiente do Flex.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de HTML e JavaScript no AIR

968

Voc tambm pode processar texto HTML usando a classe TextField, mas os respectivos recursos so limitados. A classe Textfield do Adobe Flash Player oferece suporte a um subconjunto de markup de HTML, mas, devido a limitaes de tamanho, os recursos respectivos so limitados. (A classe HTMLLoader includa no Adobe AIR no est disponvel no Flash Player.)

Carregamento de contedo HTML de uma sequncia de caracteres

Adobe AIR 1.0 e posterior O mtodo loadString() do objeto HTMLLoader carrega uma string de contedo HTML no objeto HTMLLoader:
var html:HTMLLoader = new HTMLLoader(); var htmlStr:String = "<html><body>Hello <b>world</b>.</body></html>"; html.loadString(htmlStr);

Por padro, o contedo carregado por meio do mtodo loadString() colocado em uma caixa de proteo que no aplicativo com as seguintes caractersticas:

Ela tem acesso ao contedo carregado da rede (mas no do sistema de arquivos). Ela no pode carregar dados usando XMLHttpRequest. A propriedade window.location definida como "about:blank". O contedo no pode acessar a propriedade window.runtime (como pode em qualquer caixa de proteo que no
aplicativo). No AIR 1.5, a classe HTMLLoader inclui uma propriedade placeLoadStringContentInApplicationSandbox. Quando essa propriedade definida como true para um objeto HTMLLoader, o contedo carregado pelo mtodo loadString() colocado na caixa de proteo do aplicativo. (O valor padro false.) Isso fornece ao contedo carregado pelo mtodo loadString() acesso propriedade window.runtime e a todas as APIs do ARI. Se voc definir essa propriedade como true, assegure que a fonte de dados para uma seqncia de caracteres usada em uma chamada para o mtodo loadString() seja confivel. As instrues de cdigo na seqncia de caracteres HTML so executadas com privilgios totais de aplicativo quando essa propriedade definida como true. S defina a propriedade como true quando estiver certo de que a seqncia de caracteres no possa conter cdigo nocivo. Em aplicativos compilados com SDKs do AIR 1.0 ou 1.1, o contedo carregado pelo mtodo loadString() inserido na caixa de proteo do aplicativo.

Regras de segurana importantes no uso de HTML em aplicativos AIR

Adobe AIR 1.0 e posterior Os arquivos instalados com o aplicativo AIR tm acesso s respectivas APIs. Por motivos de segurana, o contedo de outras fontes no tem acesso. Por exemplo, essa restrio impede que contedo de um domnio remoto (como http://example.com) leia o contedo de diretrio da rea de trabalho do usurio (ou algo pior). Como h buracos de segurana que podem ser explorados atravs da chamada da funo eval() (e APIs relacionadas), o contedo instalado com o aplicativo, por padro, no pode usar esses mtodos. No entanto, algumas estruturas Ajax usam a chamada da funo eval() e APIs relacionadas.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de HTML e JavaScript no AIR

969

Para estruturar adequadamente o contedo para trabalhar em um aplicativo AIR, voc deve considerar as regras das restries de segurana sobre contedo de fontes diversas. O contedo de fontes diversas colocado em classificaes de segurana distintas, chamadas de caixas de proteo (consulteCaixas de proteo de segurana na pgina 1029). Por padro, o contedo instalado com o aplicativo est instalado em uma caixa de proteo conhecida como caixa de proteo de aplicativo e isso concede a ele acesso s APIs do AIR. Normalmente, a caixa de proteo do aplicativo a mais segura, com restries projetadas para impedir a execuo de cdigo no confivel. O tempo de execuo permite carregar o contedo instalado com o aplicativo em uma caixa de proteo diferente da caixa de proteo do aplicativo. O contedo em caixas de proteo que no so de aplicativo opera em um ambiente de segurana semelhante ao de um navegador da Web tpico. Por exemplo, o cdigo das caixas de proteo que no so de aplicativo pode usar eval() e mtodos relacionados (mas, ao mesmo tempo, no permitido acesso s APIs do AIR). O tempo de execuo inclui maneiras de fazer com que o contedo em caixas de proteo distintas se comuniquem com segurana (sem expor, por exemplo, as APIs do AIR a contedo de no-aplicativo). Para obter detalhes, consulte Contedo cross-scripting em caixas de proteo de segurana distintas na pgina 986. Se voc chamar um cdigo com uso restrito em uma caixa de proteo por motivos de segurana, o tempo de execuo despachar um erro JavaScript: "Violao de segurana de tempo de execuo do Adobe AIR para cdigo JavaScript na caixa de proteo de segurana do aplicativo." Para evitar esse erro, siga as prticas de codificao descritas na prxima seo, Como evitar erros JavaScript relacionados segurana na pgina 969. Para obter mais informaes, consulte Segurana HTML no Adobe AIR na pgina 1067.

Como evitar erros JavaScript relacionados segurana

Adobe AIR 1.0 e posterior Se voc chamar um cdigo com uso restrito em uma caixa de proteo, devido a essas restries de segurana, o tempo de execuo despachar um erro de JavaScript: "Violao de segurana de tempo de execuo do Adobe AIR para cdigo JavaScript na caixa de proteo de segurana do aplicativo." Para evitar esse erro, siga essas prticas de codificao.

Causas de erros JavaScript relacionados segurana

Adobe AIR 1.0 e posterior O cdigo em execuo na caixa de proteo do aplicativo est restrito maioria das operaes que envolvem avaliao e execuo de seqncias depois que o evento load tiver sido disparado e todos os manipuladores de evento load tiverem encerrado. A tentativa de usar os seguintes tipos de instrues JavaScript que avaliam e executam strings potencialmente inseguras gera erros JavaScript:

funo eval() setTimeout() e setInterval() Construtor de funes

Alm disso, os tipos de instrues JavaScript seguintes falham sem gerar um erro JavaScript inseguro:

javascript: URLs Retornos de chamada de evento atribudos por meio de atributos onevent em instrues innerHTML e outerHTML

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de HTML e JavaScript no AIR

970

Carregamento de arquivos JavaScript externos ao diretrio de instalao do aplicativo document.write() e document.writeln() XMLHttpRequests sncronas antes do evento load ou durante um manipulador de eventos load Elementos de script criados dinamicamente
Nota: Em alguns casos restritos, a avaliao de strings permitida. Consulte Restries de cdigo de contedo em caixas de proteo distintas na pgina 1070 para obter mais informaes. A Adobe mantm uma lista das estruturas Ajax conhecidas para oferecer suporte caixa de proteo de segurana do aplicativo em http://www.adobe.com/go/airappsandboxframeworks_br. As sees seguintes descrevem como regravar os scripts para evitar esses erros JavaScript inseguro e falhas silenciosas do cdigo em execuo na caixa de proteo do aplicativo.

Mapeamento de contedo do aplicativo para uma caixa de proteo distinta

Adobe AIR 1.0 e posterior Na maioria dos casos, voc pode regravar ou reestruturar o aplicativo para evitar erros JavaScript relacionados segurana. No entanto, quando no for possvel regra ou reestruturar, voc poder carregar o contedo do aplicativo em uma caixa de proteo distinta usando a tcnica descrita em Carregamento de contedo do aplicativo em uma caixa de proteo "no aplicativo" na pgina 987. Se esse contedo tambm deve acessar as APIs do AIR, voc pode criar uma ponte de caixa de proteo, conforme descrito em Configurao de interface de ponte de caixa de proteo na pgina 987.

funo eval()
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Na caixa de proteo do aplicativo, a funo eval() s pode ser usada antes do evento load da pgina ou durante o manipulador de eventos load. Aps a pgina ter sido carregada, as chamadas para eval() no executaro cdigo. No entanto, nos seguintes casos, voc pode regravar o cdigo para evitar o uso de eval().

Atribuio de propriedades a um objeto

Adobe AIR 1.0 e posterior Em vez de analisar uma string para criar o acessador de propriedades:
eval("obj." + propName + " = " + val);

acesse propriedades com notao entre colchetes:

obj[propName] = val;

Criao de funo com variveis disponveis no contexto

Adobe AIR 1.0 e posterior Substitua instrues como as seguintes:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de HTML e JavaScript no AIR

971

function compile(var1, var2){ eval("var fn = function(){ this."+var1+"(var2) }"); return fn; }

com:
function compile(var1, var2){ var self = this; return function(){ self[var1](var2) }; }

Criao de objeto usando o nome da classe como parmetro de seqncia

Adobe AIR 1.0 e posterior Considere uma classe JavaScript hipottica definida com o seguinte cdigo:
var CustomClass = { Utils: { Parser: function(){ alert('constructor') } }, Data: { } }; var constructorClassName = "CustomClass.Utils.Parser";

A maneira mais simples de criar uma ocorrncia usar eval():

var myObj; eval('myObj=new ' + constructorClassName +'()')

No entanto, voc pode evitar a chamada para eval(), analisando cada componente de nome de classe e criando o novo objeto usando notao entre colchetes:
function getter(str) { var obj = window; var names = str.split('.'); for(var i=0;i<names.length;i++){ if(typeof obj[names[i]]=='undefined'){ var undefstring = names[0]; for(var j=1;j<=i;j++) undefstring+="."+names[j]; throw new Error(undefstring+" is undefined"); } obj = obj[names[i]]; } return obj; }

Para criar a ocorrncia, use:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de HTML e JavaScript no AIR

972

try{ var Parser = getter(constructorClassName); var a = new Parser(); }catch(e){ alert(e); }

setTimeout() e setInterval()
Adobe AIR 1.0 e posterior Substitua a string passada como a funo do manipulador por uma referncia de funo ou objeto. Por exemplo, substitua uma instruo como a seguinte:
setTimeout("alert('Timeout')", 100);

com:
setTimeout(function(){alert('Timeout')}, 100);

Ou, quando a funo precisar que o objeto this seja definido pelo chamador, substitua uma instruo como:
this.appTimer = setInterval("obj.customFunction();", 100);

pelo seguinte:
var _self = this; this.appTimer = setInterval(function(){obj.customFunction.apply(_self);}, 100);

Construtor de funes
Adobe AIR 1.0 e posterior As chamadas para new Function(param, body) podem ser substitudas por uma declarao de funo inline ou usadas apenas antes que o evento load da pgina tenha sido tratado.

javascript: URLs
Adobe AIR 1.0 e posterior O cdigo definido em um link usando o javascript: O esquema de URL ignorado na caixa de proteo do aplicativo. No gerado nenhum erro JavaScript inseguro. Voc pode substituir links usando javascript: URLs, como:
<a href="javascript:code()">Click Me</a>

com:
<a href="#" onclick="code()">Click Me</a>

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de HTML e JavaScript no AIR

973

Retornos de chamada de evento atribudos por meio de atributos onevent em instrues innerHTML e outerHTML
Adobe AIR 1.0 e posterior Ao usar innerHTML ou outerHTML para adicionar elementos ao DOM de um documento, todos os retornos de chamadas de evento atribudos na instruo, como onclick ou onmouseover, so ignorados. Nenhum erro de segurana gerado. Em vez disso, voc pode atribuir um atributo id aos novos elementos e definir as funes de retorno de chamada do manipulador de eventos, usando o mtodo addEventListener(). Por exemplo, determinado um elemento de destino em um documento, como:
<div id="container"></div>

Substitua instrues como:

document.getElementById('container').innerHTML = '<a href="#" onclick="code()">Click Me.</a>';

com:
document.getElementById('container').innerHTML = '<a href="#" id="smith">Click Me.</a>'; document.getElementById('smith').addEventListener("click", function() { code(); });

Carregamento de arquivos JavaScript externos ao diretrio de instalao do aplicativo

Adobe AIR 1.0 e posterior No permitido o carregamento de arquivos de script externos caixa de proteo do aplicativo. Nenhum erro de segurana gerado. Todos os arquivos de script que so executados na caixa de proteo do aplicativo devem ser instalados no diretrio do aplicativo. Para usar scripts externos em uma pgina, voc deve mapear a pgina para uma caixa de proteo distinta. Consulte Carregamento de contedo do aplicativo em uma caixa de proteo "no aplicativo" na pgina 987.

document.write() e document.writeln()
Adobe AIR 1.0 e posterior As chamadas para document.write() ou document.writeln() sero ignoradas aps o evento load da pgina ser tratado. Nenhum erro de segurana gerado. Como alternativa, voc pode carregar um novo arquivo ou substituir o corpo do documento usando tcnicas de manipulao DOM.

XMLHttpRequests sncronas antes do evento load ou durante um manipulador de eventos load

Adobe AIR 1.0 e posterior As XMLHttpRequests sncronas iniciadas antes do evento load da pgina ou durante um manipulador de eventos load no retornam nenhum contedo. As XMLHttpRequests assncronas podem ser iniciadas, mas no retornam at depois do evento load. Aps o evento load ser tratado, as XMLHttpRequests sncronas se comportam normalmente.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de HTML e JavaScript no AIR

974

Elementos de script criados dinamicamente

Adobe AIR 1.0 e posterior Elementos de script criados dinamicamente, como quando criados com o innerHTML ou o mtodo document.createElement(), so ignorados.

Acesso s classes API do AIR no JavaScript

Adobe AIR 1.0 e posterior Alm dos elementos padro e estendidos de kit da Web, o cdigo HTML e JavaScript pode acessar as classes host fornecidas pelo tempo de execuo. Essas classes permitem acessar os recursos avanados que o AIR oferece, incluindo:

Acesso ao sistema de arquivos Uso de bancos de dados SQL locais Controle de menus de janela e aplicativo Acesso a soquetes de rede Uso de classes e objetos definidos pelo usurio Recursos de som
Por exemplo, a API de arquivo do AIR inclui uma classe File, contida no pacote flash.filesystem. Voc pode criar um objeto File em JavaScript da seguinte forma:
var myFile = new window.runtime.flash.filesystem.File();

O objeto runtime um objeto JavaScript especial, disponvel para contedo HTML em execuo no AIR na caixa de proteo do aplicativo. Ele permite acessar as classes de tempo de execuo do JavaScript. A propriedade flash do objeto runtime oferece acesso ao pacote flash. Por sua vez, a propriedade flash.filesystem do objeto runtime oferece acesso ao pacote flash.filesystem (e esse pacote inclui a classe File). Os pacotes so uma maneira de organizar as classes usadas no ActionScript. Nota: A propriedade runtime no adicionada automaticamente aos objetos window de pginas carregadas em um frame ou iframe. No entanto, desde que o documento filho esteja na caixa de proteo do aplicativo, o filho poder acessar a propriedade runtime do pai. Como a estrutura de pacote das classes de tempo de execuo exigem que os desenvolvedores digitem longas seqncias de cdigo JavaScript para acessar cada classe (como em window.runtime.flash.desktop.NativeApplication), o AIR SDK inclui o arquivo AIRAliases.js, que permite acessar as classes de tempo de execuo mais facilmente (por exemplo, digitando simplesmente air.NativeApplication). As classes API do AIR so discutidas em todo este guia. Outras classes da API do Flash Player, que possam ser de interesse dos desenvolvedores HTML, so descritas no Adobe AIR API Reference for HTML Developers. ActionScript a linguagem usada em contedo SWF (Flash Player). No entanto, as sintaxes JavaScript e ActionScript so semelhantes. (ambas se baseiam nas verses da linguagem ECMAScript.) Todas as classes incorporadas esto disponveis em JavaScript (em contedo HTML) e ActionScript (em contedo SWF). Nota: O cdigo JavaScript no pode usar as classes Dictionary, XML e XMLList, que esto disponveis no ActionScript.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de HTML e JavaScript no AIR

975

Uso do arquivo AIRAliases.js

Adobe AIR 1.0 e posterior As classes de tempo de execuo so organizadas em uma estrutura de pacote, da seguinte forma:

window.runtime.flash.desktop.NativeApplication window.runtime.flash.desktop.ClipboardManager window.runtime.flash.filesystem.FileStream window.runtime.flash.data.SQLDatabase

No AIR SDK est includo o arquivo AIRAliases.js que oferece definies de "alias" que permitem acessar as classes de tempo de execuo com menos digitao. Por exemplo, voc pode acessar as classes listadas acima, bastando, para isso, digitar o seguinte:

air.NativeApplication air.Clipboard air.FileStream air.SQLDatabase

A lista apenas um pequeno subconjunto das classes no arquivo AIRAliases.js. A lista completa de classes e funes em nvel de pacote fornecida no Adobe AIR API Reference for HTML Developers. Alm das classes de tempo de execuo usadas normalmente, o arquivo AIRAliases.js inclui alias para as funes em nvel do pacote usadas com mais freqncia. window.runtime.trace(), window.runtime.flash.net.navigateToURL() e window.runtime.flash.net.sendToURL(), com alias air.trace(), air.navigateToURL() e air.sendToURL(). Para usar o arquivo AIRAliases.js, inclua a seguinte referncia de script em sua pgina HTML:
<script src="AIRAliases.js"></script>

Ajuste o caminho na referncia src, conforme necessrio. Importante: Exceto quando observado, o cdigo de exemplo JavaScript nesta documentao pressupe que voc incluiu o arquivo AIRAliases.js em sua pgina HTML.

Sobre URLs no AIR

Adobe AIR 1.0 e posterior No contedo HTML em execuo no AIR, voc pode usar qualquer um dos seguintes esquemas de URL na definio de atributos src para img, frame, iframe e tags de script, no atributo href de uma tag link ou qualquer outro local que voc possa fornecer uma URL.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de HTML e JavaScript no AIR

976

esquema de URL Descrio arquivo app Um caminho relativo raiz do sistema de arquivos. Um caminho relativo raiz do diretrio do aplicativo instalado. Um caminho relativo ao diretrio de armazenamento do aplicativo. Para cada aplicativo instalado, o AIR define um diretrio exclusivo de armazenamento do aplicativo, que um local til para armazenar dados especficos desse aplicativo. Uma solicitao HTTP padro. Uma solicitao HTTPS padro.

Exemplo
file:///c:/AIR Test/test.txt app:/images

app-storage

app-storage:/settings/prefs.xml

http https

http://www.adobe.com https://secure.example.com

Para obter mais informaes sobre o uso de esquemas de URL no AIR, consulte Esquemas de URI na pgina 803. Muitas das APIs do AIR, incluindo as classes File, Loader, URLStream e Sound, usam um objeto URLRequest em vez de uma string contendo a URL. O prprio objeto URLRequest inicializado com uma string, que pode usar qualquer um dos mesmos esquemas de URL. Por exemplo, a seguinte instruo cria um objeto URLRequest que pode ser usado para solicitar a home page da Adobe:
var urlReq = new air.URLRequest("http://www.adobe.com/");

Para obter informaes sobre objetos URLRequest, consulte Comunicao HTTP na pgina 801.

Como tornar objetos ActionScript disponveis para JavaScript

Adobe AIR 1.0 e posterior O JavaScript na pgina HTML carregada pelo objeto HTMLLoader pode chamar as classes, os objetos e as funes definidas no contexto de execuo do ActionScript, usando as propriedades window.runtime, window.htmlLoader e window.nativeWindow da pgina HTML. Voc tambm pode tornar objetos e funes ActionScript disponveis para cdigo JavaScript, criando referncias para eles no contexto de execuo do JavaScript.

Um exemplo bsico de como acessar objetos JavaScript do ActionScript

Adobe AIR 1.0 e posterior O seguinte exemplo ilustra como adicionar propriedades que fazem referncia a objetos ActionScript ao objeto window global de uma pgina HTML.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de HTML e JavaScript no AIR

977

var html:HTMLLoader = new HTMLLoader(); var foo:String = "Hello from container SWF." function helloFromJS(message:String):void { trace("JavaScript says:", message); } var urlReq:URLRequest = new URLRequest("test.html"); html.addEventListener(Event.COMPLETE, loaded); html.load(urlReq); function loaded(e:Event):void{ html.window.foo = foo; html.window.helloFromJS = helloFromJS; }

O contedo HTML (no arquivo chamado test.html), carregado no objeto HTMLLoader no exemplo anterior, pode acessar a propriedade foo e o mtodo helloFromJS() definidos no arquivo SWF pai:
<html> <script> function alertFoo() { alert(foo); } </script> <body> <button onClick="alertFoo()"> What is foo? </button> <p><button onClick="helloFromJS('Hi.')"> Call helloFromJS() function. </button></p> </body> </html>

Ao acessar o contexto JavaScript de um documento que est sendo carregado, voc pode usar o evento htmlDOMInitialize para criar objetos na seqncia de construo da pgina, cedo o bastante para que qualquer script definido na pgina possa acess-los. Se voc aguardar o evento complete, somente scripts da pgina executados depois do evento load da pgina podero acessar os objetos adicionados.

Como tornar as definies de classe disponveis para JavaScript

Adobe AIR 1.0 e posterior Para disponibilizar as classes ActionScript do aplicativo em JavaScript, voc pode atribuir o contedo HTML carregado ao domnio de aplicativo que contm as definies de classe. O domnio de aplicativo do contexto de execuo do JavaScript pode ser definido com a propriedade runtimeApplicationDomain do objeto HTMLLoader. Para definir o domnio de aplicativo como domnio de aplicativo primrio, por exemplo, defina runtimeApplicationDomain como ApplicationDomain.currentDomain, conforme mostra o cdigo a seguir:
html.runtimeApplicationDomain = ApplicationDomain.currentDomain;

Depois que a propriedade runtimeApplicationDomain for definida, o contexto JavaScript compartilha as definies de classe com o domnio atribudo. Para criar uma ocorrncia de classe personalizada em JavaScript, faa referncia definio de classe por meio da propriedade window.runtime e use o operador novo:
var customClassObject = new window.runtime.CustomClass();

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de HTML e JavaScript no AIR

978

O contedo HTML deve ser de um domnio de segurana compatvel. Se o contedo HTML for de um domnio de segurana diferente do domnio de aplicativo que voc atribuir, em vez disso a pgina usar um domnio de aplicativo padro. Por exemplo, se voc carregar uma pgina remota da Internet, no poder atribuir ApplicationDomain.currentDomain como domnio de aplicativo da pgina.

Remoo de ouvintes de eventos

Adobe AIR 1.0 e posterior Quando voc adiciona ouvintes de eventos JavaScript a objetos fora da pgina atual, incluindo objetos de tempo de execuo, objetos no contedo SWF carregado e at objetos JavaScript em execuo em outras pginas, deve sempre remover esses ouvintes de eventos quando a pgina for descarregada. Do contrrio, o ouvinte de evento despacha o evento para uma funo do manipulador que no existe mais. Se isso acontecer, voc ver a seguinte mensagem de erro: "O aplicativo tentou fazer referncia a um objeto JavaScript em uma pgina HTML que no mais carregada". A remoo de ouvintes de eventos desnecessrios tambm permite que o AIR recupere a memria associada. Para obter mais informaes, consulte Remoo de ouvintes de eventos nas pginas HTML que navegam na pgina 1014.

Acesso a objetos HTML DOM e JavaScript do ActionScript

Adobe AIR 1.0 e posterior Aps o objeto HTMLLoader despachar o evento complete, voc poder acessar todos os objetos no HTML DOM (modelo de objeto de documento) da pgina. Os objetos acessveis incluem os elementos de exibio (como os objetos div e p na pgina), bem como as variveis e funes JavaScript. O evento complete corresponde ao evento load da pgina em JavaScript. Antes que complete seja despachado, os elementos DOM, as variveis e as funes podero no ter sido analisados nem criados. Se possvel, aguarde o evento complete antes de acessar o HTML DOM. Por exemplo, considere a seguinte pgina HTML:
<html> <script> foo = 333; function test() { return "OK."; } </script> <body> <p id="p1">Hi.</p> </body> </html>

Essa pgina HTML simples define uma varivel JavaScript chamada foo e uma funo JavaScript chamada test(). As duas propriedades so propriedades do objeto window global da pgina. Alm disso, o objeto window.document inclui um elemento chamado P (com a ID p1), que voc pode acessar usando o mtodo getElementById(). Depois que a pgina for carregada (quando o objeto HTMLLoader despachar o evento complete), voc poder acessar cada um desses objetos do ActionScript, conforme mostra o seguinte cdigo ActionScript:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de HTML e JavaScript no AIR

979

var html:HTMLLoader = new HTMLLoader(); html.width = 300; html.height = 300; html.addEventListener(Event.COMPLETE, completeHandler); var xhtml:XML = <html> <script> foo = 333; function test() { return "OK."; } </script> <body> <p id="p1">Hi.</p> </body> </html>; html.loadString(xhtml.toString()); function completeHandler(e:Event):void { trace(html.window.foo); // 333 trace(html.window.document.getElementById("p1").innerHTML); // Hi. trace(html.window.test()); // OK. }

Para acessar o contedo de um elemento HTML, use a propriedade innerHTML. Por exemplo, o cdigo anterior usa html.window.document.getElementById("p1").innerHTML para obter o contedo do elemento HTML chamado p1. Voc tambm pode definir propriedades da pgina HTML do ActionScript. Por exemplo, o seguinte exemplo define o contedo do elemento p1 e o valor da varivel JavaScript foo na pgina, usando uma referncia ao objeto HTMLLoader que a contm:
html.window.document.getElementById("p1").innerHTML = "Goodbye"; html.window.foo = 66;

Incorporao de contedo SWF em HTML

Adobe AIR 1.0 e posterior Voc pode incorporar o contedo SWF em um contedo HTML do aplicativo AIR da mesma forma que em um navegador. Incorpore o contedo SWF usando a tag object, a tag embed ou as duas. Nota: Uma prtica comum de desenvolvimento usar tanto uma tag object quanto uma tag embed para exibir contedo SWF em uma pgina HTML. Essa prtica no tem nenhum benefcio no AIR. Voc pode usar a prpria tag object padro W3C no contedo para ser exibido no AIR. Ao mesmo tempo, voc pode continuar usando as tags object e embed juntas, se necessrio, para contedo HTML exibido tambm no navegador. Se voc habilitou a transparncia no objeto NativeWindow exibindo o contedo HTML e SWF, o AIR no exibe o contedo SWF quando o modo janela (wmode) utilizado para integrar o contedo estiver definido em: window. Para exibir o contedo do SWF em uma pgina HTML de uma janela transparente, configure o parmetro wmode para opaque ou transparent. window o valor padro para wmode, de forma que o contedo pode no ser exibido se voc no especificar o valor.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de HTML e JavaScript no AIR

980

O seguinte exemplo ilustra o uso da tag object HTML para exibir um arquivo SWF no contedo HTML. O parmetro wmode est definido para opaque de forma que o contedo exibido, mesmo quando o objeto base NativeWindow for transparente. O arquivo SWF carregado do diretrio do aplicativo, mas voc pode usar qualquer um dos esquemas de URL suportados pelo AIR. (O local do qual o arquivo SWF carregado determina a caixa de proteo de segurana em que o AIR coloca o contedo.)
<object type="application/x-shockwave-flash" width="100%" height="100%"> <param name="movie" value="app:/SWFFile.swf"></param> <param name="wmode" value="opaque"></param> </object>

Voc tambm pode usar um script para carregar contedo dinamicamente. O seguinte exemplo cria um n object para exibir o arquivo SWF especificado no parmetro urlString. O exemplo adiciona o n como filho do elemento de pgina com a ID especificada pelo parmetro elementID:
<script> function showSWF(urlString, elementID){ var displayContainer = document.getElementById(elementID); var flash = createSWFObject(urlString, 'opaque', 650, 650); displayContainer.appendChild(flash); } function createSWFObject(urlString, wmodeString, width, height){ var SWFObject = document.createElement("object"); SWFObject.setAttribute("type","application/x-shockwave-flash"); SWFObject.setAttribute("width","100%"); SWFObject.setAttribute("height","100%"); var movieParam = document.createElement("param"); movieParam.setAttribute("name","movie"); movieParam.setAttribute("value",urlString); SWFObject.appendChild(movieParam); var wmodeParam = document.createElement("param"); wmodeParam.setAttribute("name","wmode"); wmodeParam.setAttribute("value",wmodeString); SWFObject.appendChild(wmodeParam); return SWFObject; } </script>

O contedo SWF no exibido se o objeto HTMLLoader for dimensionado ou girado, ou se a propriedade alpha estiver definida para um valor diferente de 1.0. Antes do AIR 1.5.2, o contedo SWF no era exibido em uma janela transparente, no importando como o valor wmode estava definido. Nota: Quando um objeto SWF incorporado tentar carregar um ativo externo como um arquivo de vdeo, o contedo do SWF poder no ser renderizado adequadamente se no for fornecido um caminho absoluto para o vdeo no arquivo HTML. Contudo, um objeto SWF incorporado pode carregar um arquivo de imagem externo usando um caminho relativo. O exemplo a seguir demonstra como os ativos externos podem ser carregados por meio de um objeto SWF incorporado num contedo HTML:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de HTML e JavaScript no AIR

981

var imageLoader; function showSWF(urlString, elementID){ var displayContainer = document.getElementById(elementID); imageLoader = createSWFObject(urlString,650,650); displayContainer.appendChild(imageLoader); } function createSWFObject(urlString, width, height){ var SWFObject = document.createElement("object"); SWFObject.setAttribute("type","application/x-shockwave-flash"); SWFObject.setAttribute("width","100%"); SWFObject.setAttribute("height","100%"); var movieParam = document.createElement("param"); movieParam.setAttribute("name","movie"); movieParam.setAttribute("value",urlString); SWFObject.appendChild(movieParam); var flashVars = document.createElement("param"); flashVars.setAttribute("name","FlashVars"); //Load the asset inside the SWF content. flashVars.setAttribute("value","imgPath=air.jpg"); SWFObject.appendChild(flashVars); return SWFObject; } function loadImage() { showSWF("ImageLoader.swf", "imageSpot"); }

No exemplo de ActionScript a seguir, o caminho da imagem passado pelo arquivo HTML lido, e a imagem carregada no palco:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de HTML e JavaScript no AIR

982

package { import import import import import import

flash.display.Sprite; flash.display.LoaderInfo; flash.display.StageScaleMode; flash.display.StageAlign; flash.display.Loader; flash.net.URLRequest;

public class ImageLoader extends Sprite { public function ImageLoader() { var flashvars = LoaderInfo(this.loaderInfo).parameters; if(flashvars.imgPath){ var imageLoader = new Loader(); var image = new URLRequest(flashvars.imgPath); imageLoader.load(image); addChild(imageLoader); imageLoader.x = 0; imageLoader.y = 0; stage.scaleMode=StageScaleMode.NO_SCALE; stage.align=StageAlign.TOP_LEFT; } } } }

Uso de bibliotecas do ActionScript em uma pgina HTML

Adobe AIR 1.0 e posterior O AIR estende o elemento de script HTML para que a pgina possa importar classes ActionScript em um arquivo SWF compilado. Por exemplo, para importar uma biblioteca chamada myClasses.swf, localizada no subdiretrio lib da pasta raiz do aplicativo, inclua a seguinte tag de script no arquivo HTML:
<script src="lib/myClasses.swf" type="application/x-shockwave-flash"></script>

Importante: O atributo de tipo deve ser type="application/x-shockwave-flash" para que a biblioteca seja carregada corretamente. Se o contedo SWF for compilado como Flash Player 10 ou AIR 1.5 SWF, voc dever definir o namespace do descritor do aplicativo como namespace do AIR 1.5. O diretrio lib e o arquivo myClasses.swf tambm deve ser includo quando o arquivo AIR for empacotado. Acesse as classes importadas por meio da propriedade runtime do objeto da janela JavaScript:
var libraryObject = new window.runtime.LibraryClass();

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de HTML e JavaScript no AIR

983

Se as classes no arquivo SWF estiverem organizadas em pacotes, voc tambm dever incluir o nome do pacote. Por exemplo, se a definio LibraryClass estivesse em um pacote chamado utilities, voc deveria criar uma ocorrncia da classe com a seguinte instruo:
var libraryObject = new window.runtime.utilities.LibraryClass();

Nota: Para compilar uma biblioteca SWF do ActionScript para usar como parte da pgina HTML no AIR, use o compilador acompc. O utilitrio acompc parte do SDK do Flex e est descrito na _brDocumentao do SDK Flex.

Acesso aos objetos HTML DOM e JavaScript de um arquivo ActionScript importado

Adobe AIR 1.0 e posterior Para acessar objetos em uma pgina HTML do ActionScript em um arquivo SWF importado na pgina usando a tag <script>, passe uma referncia para um objeto JavaScript, como window ou document, em uma funo definida no cdigo do ActionScript. Use a referncia na funo para acessar o objeto JavaScript (ou outros objetos acessveis por meio da referncia passada). Por exemplo, considere a seguinte pgina HTML:
<html> <script src="ASLibrary.swf" type="application/x-shockwave-flash"></script> <script> num = 254; function getStatus() { return "OK."; } function runASFunction(window){ var obj = new runtime.ASClass(); obj.accessDOM(window); } </script> <body onload="runASFunction"> <p id="p1">Body text.</p> </body> </html>

Essa pgina HTML simples tem uma varivel JavaScript chamada num e uma funo JavaScript chamada getStatus(). As duas propriedades so propriedades do objeto window da pgina. Alm disso, o objeto window.document inclui um elemento chamado P (com a ID p1). A pgina carrega o arquivo ActionScript, "ASLibrary.swf," que contm a classe ASClass. A ASClass define a funo chamada accessDOM() que simplesmente rastreia os valores desses objetos JavaScript. O mtodo accessDOM() considera o objeto de janela JavaScript como um argumento. Ao usar essa referncia de janela, ele pode acessar outros objetos na pgina, incluindo variveis, funes e elementos DOM, conforme ilustrado na definio a seguir:
public class ASClass{ public function accessDOM(window:*):void { trace(window.num); // 254 trace(window.document.getElementById("p1").innerHTML); // Body text.. trace(window.getStatus()); // OK. } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de HTML e JavaScript no AIR

984

Voc pode obter e definir propriedades da pgina HTML de uma classe ActionScript importada. Por exemplo, a seguinte funo define o contedo do elemento p1 na pgina e define o valor da varivel de JavaScript foo na pgina:
public function modifyDOM(window:*):void { window.document.getElementById("p1").innerHTML = "Bye"; window.foo = 66;

Converso de objetos Date e RegExp

Adobe AIR 1.0 e posterior As linguagens JavaScript e ActionScript definem as classes Date e RegExp, mas os objetos desses tipos no so convertidos automaticamente entre os dois contextos de execuo. Voc deve converter os objetos Date e RegExp para o tipo equivalente antes de us-los para definir parmetros de propriedades ou funes no contexto de execuo alternativo. Por exemplo, o seguinte cdigo ActionScript converte o objeto Date de JavaScript chamado jsDate em um objeto Date do ActionScript:
var asDate:Date = new Date(jsDate.getMilliseconds());

Por exemplo, o seguinte cdigo ActionScript converte o objeto RegExp de JavaScript chamado jsRegExp em um objeto RegExp do ActionScript:
var flags:String = ""; if (jsRegExp.dotAll) flags += "s"; if (jsRegExp.extended) flags += "x"; if (jsRegExp.global) flags += "g"; if (jsRegExp.ignoreCase) flags += "i"; if (jsRegExp.multiline) flags += "m"; var asRegExp:RegExp = new RegExp(jsRegExp.source, flags);

Manipulao de folha de estilos HTML do ActionScript

Adobe AIR 1.0 e posterior Depois que o objeto HTMLLoader tiver despachado o evento complete, voc poder examinar e manipular estilos CSS na pgina. Por exemplo, considere o seguinte documento HTML simples:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de HTML e JavaScript no AIR

985

<html> <style> .style1A { font-family:Arial; font-size:12px } .style1B { font-family:Arial; font-size:24px } </style> <style> .style2 { font-family:Arial; font-size:12px } </style> <body> <p class="style1A"> Style 1A </p> <p class="style1B"> Style 1B </p> <p class="style2"> Style 2 </p> </body> </html>

Depois que o objeto HTMLLoader carregar esse contedo, voc poder manipular os estilos CSS da pgina, atravs da matriz cssRules da matriz window.document.styleSheets, como mostrado a seguir:
var html:HTMLLoader = new HTMLLoader( ); var urlReq:URLRequest = new URLRequest("test.html"); html.load(urlReq); html.addEventListener(Event.COMPLETE, completeHandler); function completeHandler(event:Event):void { var styleSheet0:Object = html.window.document.styleSheets[0]; styleSheet0.cssRules[0].style.fontSize = "32px"; styleSheet0.cssRules[1].style.color = "#FF0000"; var styleSheet1:Object = html.window.document.styleSheets[1]; styleSheet1.cssRules[0].style.color = "blue"; styleSheet1.cssRules[0].style.font-family = "Monaco"; }

Esse cdigo ajusta os estilos CSS para que o documento HTML resultante tenha a seguinte aparncia:

Lembre-se de que esse cdigo pode adicionar estilos pgina aps o objeto HTMLLoader despachar o evento complete.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de HTML e JavaScript no AIR

986

Contedo cross-scripting em caixas de proteo de segurana distintas

Adobe AIR 1.0 e posterior O modelo de segurana de tempo de execuo isola o cdigo de origens distintas. Cruzando scripts de contedo em caixas de proteo de segurana distintas, voc pode permitir que o contedo de uma caixa de proteo de segurana acesse as propriedades e os mtodos selecionados em outra caixa de proteo.

Caixas de proteo de segurana do AIR e cdigo JavaScript

Adobe AIR 1.0 e posterior O AIR aplica a poltica de mesma origem, que impede a interao de cdigo de um domnio com o contedo de outro domnio. Todos os arquivos so colocados em uma caixa de proteo com base nas respectivas origens. Normalmente, o contedo na caixa de proteo do aplicativo no pode violar o princpio de mesma origem e o contedo crossscripting, carregado de fora do diretrio de instalao do aplicativo. No entanto, o AIR oferece algumas tcnicas que permitem o cruzamento de scripts em contedo "no aplicativo". Uma das tcnicas usa frames ou iframes para mapear contedo de aplicativo em uma caixa de proteo de segurana distinta. Qualquer pgina carregada da rea com caixa de proteo do aplicativo se comporta como se tivesse sido carregada do domnio remoto. Por exemplo, mapeando o contedo do aplicativo para o domnio example.com, esse contedo pode fazer o cruzamento cross-scripting das pginas carregadas desse domnio. Como essa tcnica coloca o contedo do aplicativo em uma caixa de proteo distinta, o cdigo nesse contedo tambm no estar mais sujeito s restries na execuo de cdigo em strings avaliadas. Voc pode usar essa tcnica de mapeamento de caixa de proteo para para atenuar essas restries, mesmo quando no for necessrio fazer o cruzamento de scripts de contedo remoto. Mapear contedo dessa maneira pode ser muito til ao trabalhar com uma das vrias estruturas JavaScript ou com cdigo existente que dependa das strings de avaliao. No entanto, voc deve considerar e se proteger contra o risco adicional de que algum contedo no confivel possa ser injetado e executado quando o contedo for executado fora da caixa de proteo do aplicativo. Ao mesmo tempo, o contedo de aplicativo mapeado para uma outra caixa de proteo perde o acesso s APIs do AIR, portanto, a tcnica de mapeamento de caixa de proteo no pode ser usada para expor a funcionalidade do AIR ao cdigo executado fora da caixa de proteo do aplicativo. Outra tcnica de cruzamento de scripts permite criar uma interface chamada ponte de caixa de proteo entre o contedo de uma caixa de proteo "no aplicativo" e seu documento pai na caixa de proteo do aplicativo. A ponte permite que o contedo filho acesse as propriedades e os mtodos definidos pelo pai e o pai acesse as propriedades e os mtodos definidos pelo filho, ou ambos. Por fim, voc tambm pode executar XMLHttpRequests entre domnios da caixa de proteo do aplicativo e, opcionalmente, de outras caixas de proteo. Para obter mais informaes, consulte Elementos HTML frame e iframe na pgina 958, Segurana HTML no Adobe AIR na pgina 1067 e O objeto XMLHttpRequest na pgina 952.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de HTML e JavaScript no AIR

987

Carregamento de contedo do aplicativo em uma caixa de proteo "no aplicativo"

Adobe AIR 1.0 e posterior Para permitir que o contedo do aplicativo faa cruzamento de script de contedo carregado de fora do diretrio de instalao do aplicativo, voc pode usar os elementos frame ou iframe para carregar contedo do aplicativo na mesma caixa de proteo de segurana do contedo externo. Se voc no precisa fazer cruzamento de script de contedo remoto, mas ainda assim deseja carregar uma pgina do seu aplicativo fora da respectiva caixa de proteo, pode usar a mesma tcnica, especificando http://localhost/ ou algum outro valor incuo, como o domnio de origem. O AIR adiciona os novos atributos sandboxRoot e documentRoot ao elemento frame que permite especificar se o arquivo do aplicativo carregado no frame deve ser mapeado para uma caixa de proteo "no aplicativo". Arquivos que esto sendo resolvidos em um caminho abaixo da URL sandboxRoot so carregados, em vez do diretrio documentRoot. Para fins de segurana, o contedo do aplicativo carregado dessa maneira tratado como se na verdade tivesse sido carregado da URL sandboxRoot. A propriedade sandboxRoot especifica a URL que deve ser usada para determinar a caixa de proteo e o domnio em que o contedo do quadro deve ser colocado. Os esquemas de URL file:, http: ou https: devem ser usados. Se voc especificar uma URL relativa, o contedo permanecer na caixa de proteo do aplicativo. A propriedade documentRoot especifica o diretrio do qual o contedo do quadro deve ser carregado. Os esquemas de URL file:, app: ou app-storage: devem ser usados. O exemplo a seguir mapeia o contedo instalado no subdiretrio sandbox do aplicativo a ser executado na caixa de proteo remota e o domnio www.example.com:
<iframe src="http://www.example.com/local/ui.html" sandboxRoot="http://www.example.com/local/" documentRoot="app:/sandbox/"> </iframe>

A pgina ui.html pode carregar um arquivo javascript da pasta sandbox local, usando a seguinte tag de script:
<script src="http://www.example.com/local/ui.js"></script>

Ele tambm pode carregar contedo de um diretrio no servidor remoto usando uma tag de script como a que segue:
<script src="http://www.example.com/remote/remote.js"></script>

A URL sandboxRoot ir mascarar todo contedo na mesma URL do servidor remoto. No exemplo anterior, voc no podia acessar nenhum contedo remoto em www.example.com/local/ (ou qualquer um de seus subdiretrios), pois o AIR remapeia a solicitao para o diretrio local do aplicativo. As solicitaes so remapeadas, sejam elas derivadas de navegao de pgina, de uma XMLHttpRequest ou de qualquer outro meio de carregamento de contedo.

Configurao de interface de ponte de caixa de proteo

Adobe AIR 1.0 e posterior Voc pode usar uma ponte de caixa de proteo quando o contedo da caixa de proteo do aplicativo tiver que acessar propriedades ou mtodos definidos pelo contedo em uma caixa de proteo "no aplicativo" , ou quando o contedo "no aplicativo" tiver que acessar propriedades e mtodos definidos pelo contedo na caixa de proteo do aplicativo. Crie uma ponte com as propriedades childSandboxBridge e parentSandboxBridge do objeto window de algum documento filho.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de HTML e JavaScript no AIR

988

Estabelecimento de uma ponte de caixa de proteo filha

Adobe AIR 1.0 e posterior A propriedade childSandboxBridge permite que o documento filho exponha uma interface para o contedo do documento pai. Para expor uma interface, voc define a propriedade childSandbox como funo ou objeto no documento filho. Em seguida, voc pode acessar o objeto ou funo do contedo no documento pai. O exemplo a seguir mostra como um script que est sendo executado em um documento filho pode expor um objeto contendo uma funo e uma propriedade para o respectivo pai:
var interface = {}; interface.calculatePrice = function(){ return ".45 cents"; } interface.storeID = "abc" window.childSandboxBridge = interface;

Se esse filho foi carregado em um iframe com id "filho" atribuda, voc poder acessar a interface do contedo pai, lendo a propriedade childSandboxBridge do quadro:
var childInterface = document.getElementById("child").contentWindow.childSandboxBridge; air.trace(childInterface.calculatePrice()); //traces ".45 cents" air.trace(childInterface.storeID)); //traces "abc"

Estabelecimento de uma ponte de caixa de proteo pai

Adobe AIR 1.0 e posterior A propriedade parentSandboxBridge permite que o documento pai exponha uma interface para o contedo do documento filho. Para expor uma interface, o documento pai define a propriedade parentSandbox do documento filho como uma funo ou objeto definido no documento pai. Em seguida, voc pode acessar o objeto ou funo do contedo no filho. O exemplo a seguir mostra como um script que est sendo executado em um quadro pai pode expor um objeto contendo uma funo para um documento filho:
var interface = {}; interface.save = function(text){ var saveFile = air.File("app-storage:/save.txt"); //write text to file } document.getElementById("child").contentWindow.parentSandboxBridge = interface;

Ao usar essa interface, o contedo do quadro filho poder salvar texto em um arquivo chamado save.txt, mas no ter nenhum outro acesso ao sistema de arquivos. O contedo filho poder chamar a funo save da seguinte maneira:
var textToSave = "A string."; window.parentSandboxBridge.save(textToSave);

O contedo do aplicativo dever expor a interface mais estreita possvel para as outras caixas de proteo. O contedo "no aplicativo" deve ser considerado no confivel inerentemente, j que ele pode estar sujeito injeo de cdigo acidental ou mal-intencionado. Voc deve colocar as protees apropriadas no local para impedir o uso inadequado da interface exposta atravs da ponte da caixa de proteo pai.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de HTML e JavaScript no AIR

989

Acesso ponte de caixa de proteo pai durante o carregamento de pgina

Adobe AIR 1.0 e posterior Para que o script de um documento filho acesse uma ponte de caixa de proteo pai, a ponte deve ser configurada antes que o script seja executado. Os objetos window, frame e iframe despacham o evento dominitialize quando uma nova pgina DOM tiver sido criada, mas antes que qualquer script tenha sido analisado ou que elementos DOM tenham sido adicionados. Voc pode usar o evento dominitialize para estabelecer a ponte na seqncia de construo de pgina, cedo o bastante para que todos os scripts no documento filho possam acess-la. O exemplo a seguir ilustra como criar uma ponte de caixa de proteo pai em resposta ao evento dominitialize despachado do quadro filho:
<html> <head> <script> var bridgeInterface = {}; bridgeInterface.testProperty = "Bridge engaged"; function engageBridge(){ document.getElementById("sandbox").contentWindow.parentSandboxBridge = bridgeInterface; } </script> </head> <body> <iframe id="sandbox" src="http://www.example.com/air/child.html" documentRoot="app:/" sandboxRoot="http://www.example.com/air/" ondominitialize="engageBridge()"/> </body> </html>

O seguinte documento child.html ilustra como o contedo filho pode acessar a ponte de caixa de proteo pai:
<html> <head> <script> document.write(window.parentSandboxBridge.testProperty); </script> </head> <body></body> </html>

Para ouvir o evento dominitialize em uma janela filha, em vez de um quadro, voc deve adicionar o ouvinte ao novo objeto window filho criado pela funo window.open():
var childWindow = window.open(); childWindow.addEventListener("dominitialize", engageBridge()); childWindow.document.location = "http://www.example.com/air/child.html";

Nesse caso, no h como mapear o contedo do aplicativo para uma caixa de proteo "no aplicativo". Essa tcnica s til quando child.html carregado de fora do diretrio do aplicativo. Voc pode ainda mapear contedo do aplicativo na janela para uma caixa de proteo "no aplicativo", mas primeiramente, preciso carregar uma pgina intermediria que use ela mesma quadros para carregar o documento filho e mape-lo para a caixa de proteo desejada.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Programao de HTML e JavaScript no AIR

990

Se voc usar a funo createRootWindow() da classe HTMLLoader para criar uma janela, a nova janela no ser filha do documento do qual createRootWindow() ser chamado. Portanto, voc no pode criar uma ponte de caixa de proteo da janela que faz a chamada para um contedo "no aplicativo" carregado na nova janela. Em vez disso, voc deve carregar uma pgina intermediria na nova janela que use ela mesma quadros para carregar o documento filho. Em seguida, voc pode estabelecer a ponte do documento pai da nova janela para o documento filho carregado no quadro.

ltima atualizao em 29/3/2011

991

Captulo 57: Script no continer HTML do AIR

Adobe AIR 1.0 e posterior A classe HTMLLoader serve como continer do contedo HTML no Adobe AIR. A classe oferece vrias propriedades e mtodos, herdados da classe Sprite, para controlar o comportamento e a aparncia do objeto na lista de exibio do ActionScript 3.0. Alm disso, a classe define propriedades e mtodos de tarefas, como carregamento e interao com contedo HTML e gerenciamento de histrico. A classe HTMLHost define um conjunto de comportamentos de um HTMLLoader. Quando voc cria um objeto HTMLLoader, nenhuma implementao HTMLHost fornecida. Portanto, quando o contedo HTML aciona um dos comportamentos padro, como alterao de localizao da janela ou do ttulo da janela, no acontece nada. Voc pode estender a classe HTMLHost para definir os comportamentos desejados para o aplicativo. Uma implementao padro do HTMLHost fornecida para janelas HTML criadas pelo AIR. Voc pode atribuir a implementao HTMLHost padro a outro objeto HTMLLoader definindo a propriedade htmlHost do objeto, usando um novo objeto HTMLHost criado com o parmetro defaultBehavior definido como true. Nota: Na estrutura do Adobe Flex, o objeto HTMLLoader delimitado pelo componente mx:HTML. Use o componente HTML quando usar o Flex.

Exibio de propriedades de objetos HTMLLoader

Adobe AIR 1.0 e posterior O objeto HTMLLoader herda as propriedades de exibio da classe Sprite do Adobe Flash Player. Voc pode redimensionar, mover, ocultar e alterar a cor do plano de fundo, por exemplo. Ou, pode aplicar efeitos avanadas, como filtros, mscaras, dimensionamento e rotao. Ao aplicar efeitos, considere o impacto sobre a legibilidade. O contedo SWF e PDF carregado em uma pgina HTML no pode ser exibido quando alguns efeitos so aplicados. As janelas HTML contm um objeto HTMLLoader que processa contedo HTML. Esse objeto fica restrito dentro da rea da janela, portanto, alterar dimenses, posio, rotao ou fato de dimensionamento nem sempre produz os resultados desejados.

Propriedades bsicas de exibio

Adobe AIR 1.0 e posterior As propriedades bsicas de exibio do HTMLLoader permitem posicionar o controle no respectivo objeto de exibio pai para definir o tamanho e mostrar ou ocultar o controle. Voc no deve alterar essas propriedades do objeto HTMLLoader de uma janela HTML. As propriedades bsicas incluem:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Script no continer HTML do AIR

992

Propriedade
x, y width, height visible

Observaes Posiciona o objeto em seu continer pai. Altera as dimenses da rea de exibio. Controla a visibilidade do objeto e todo seu contedo.

Fora da janela HTML, as propriedades width e height do objeto HTMLLoader assumem o padro 0. Voc deve definir a largura e a altura para que o contedo HTML carregado possa ser visualizado. O contedo HTML desenhado no tamanho do HTMLLoader, disposto de acordo com as propriedades HTML e CSS do contedo. Alterar o tamanho do HTMLLoader redireciona o contedo. Ao carregar contedo em um novo objeto HTMLLoader (com width ainda definido como 0), pode ser tentador definir width e height de exibio do HTMLLoader usando as propriedades contentWidth e contentHeight. Essa tcnica funciona em pginas com largura mnima razovel quando disposta de acordo com as regras de fluxo de HTML e CSS. No entanto, algumas pginas resultam em um layout longo e estreito na ausncia de uma largura razovel fornecida pelo HTMLLoader. Nota: Quando voc altera a largura e a altura do objeto HTMLLoader, os valores scaleX e scaleY no so alterados, como ocorreria com a maioria dos demais tipos de objetos de exibio.

Transparncia de contedo HTMLLoader

Adobe AIR 1.0 e posterior A propriedade paintsDefaultBackground do objeto HTMLLoader, que true por padro, determina se o objeto HTMLLoader desenha um plano de fundo opaco. Quando paintsDefaultBackground for false, o plano de fundo ficar claro. O continer do objeto de exibio ou outros objetos de exibio abaixo do objeto HTMLLoader ficam visveis por trs dos elementos de primeiro plano do contedo HTML. Se o elemento body ou qualquer outro elemento do documento HTML especificar uma cor de plano de fundo (usando style="background-color:gray", por exemplo), o plano de fundo dessa parte do HTML ficar opaco e ser processado com a cor de plano de fundo especificada. Se voc definir a propriedade opaqueBackground do objeto HTMLLoader e paintsDefaultBackground for false, a cor definida para opaqueBackground ficar visvel. Nota: Voc pode usar um grfico com formato PNG transparente para dar ao elemento no documento HTML um plano de fundo de mesclagem de alfa. No h suporte para a configurao de estilo de opacidade de elemento HTML.

Dimensionamento de contedo HTMLLoader

Adobe AIR 1.0 e posterior Evite o dimensionamento do objeto HTMLLoader alm do fator de dimensionamento de 1.0. O texto no contedo HTMLLoader processado em uma resoluo especfica e aparecer pixelizado se o objeto HTMLLoader for dimensionado. Para evitar que o HTMLLoader, bem como o respectivo contedo, sejam dimensionados quando a janela for redimensionada, defina a propriedade scaleMode do Palco como StageScaleMode.NO_SCALE.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Script no continer HTML do AIR

993

Consideraes ao carregar contedo SWF ou PDF em uma pgina HTML

Adobe AIR 1.0 e posterior O contedo SWF e PDF carregado em um objeto HTMLLoader desaparece nas seguintes condies:

Se voc dimensionar o objeto HTMLLoader em um outro fator que no 1.0. Se voc definir a propriedade alfa do objeto HTMLLoader em um outro valor que no 1.0. Se voc girar o contedo HTMLLoader.
O contedo reaparecer se voc remover a configurao da propriedade ofensiva e os filtros ativos. Alm disso, o tempo de execuo no pode exibir o contedo de arquivos PDF em janelas transparentes. O tempo de execuo somente pode exibir contedo SWF integrado em uma pgina HTML quando o parmetro wmode do objeto ou da tag integrada estiver definido em opaque ou transparent. Como o valor padro de wmode window, o contedo SWF no exibido em janelas transparentes a no ser que voc especifique expressamente o parmetro wmode. Nota: Antes da verso 1.5.2 do AIR, o SWF integrado no HTML no podia ser exibido, no importando como o valor wmode era utilizado. Para obter mais informaes sobre o carregamento desses tipos de mdia no HTMLLoader, consulte Incorporao de contedo SWF em HTML na pgina 979 e Incluso de contedo em PDF no AIR na pgina 532.

Propriedades avanadas de exibio

Adobe AIR 1.0 e posterior A classe HTMLLoader herda vrios mtodos que podem ser usados em efeitos especiais. Em geral, esses efeitos tm limitaes quando usados com a exibio HTMLLoader, mas podem ser teis em transies ou outros efeitos temporrios. Por exemplo, se voc exibe uma janela de dilogo para coletar entradas de usurio, possvel desfocar a exibio da janela principal at que o usurio feche a caixa de dilogo. Da mesma forma, voc pode fazer a exibio desaparecer gradualmente ao fechar uma janela. As propriedades avanadas de exibio incluem:
Propriedade
alpha filters

Limitaes Pode reduzir a legibilidade do contedo HTML. Em uma Janela HTML, os efeitos exteriores so recortados pela borda da janela. As formas desenhadas com comandos grficos aparecem abaixo do contedo HTML, incluindo o plano de fundo padro. A propriedade paintsDefaultBackground deve ser false para que as formas do desenho estejam visveis. No altera a cor do plano de fundo padro. A propriedade paintsDefaultBackground deve ser false para que essa camada de cor esteja visvel.

graphics

opaqueBackground

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Script no continer HTML do AIR

994

Propriedade
rotation

Limitaes Os cantos da rea retangular do HTMLLoader podem ser recortados pela borda da janela. O contedo SWF e PDF carregado no contedo HTML no exibido. A exibio processada pode aparecer pixelizada em fatores de dimensionamento maiores que 1. O contedo SWF e PDF carregado no contedo HTML no exibido. Pode reduzir a legibilidade do contedo HTML. A exibio HTML pode ser recortada pela borda da janela. O contedo SWF e PDF carregado no contedo HTML no ser exibido se a transformao envolver rotao, dimensionamento ou inclinao.

scaleX e scaleY

transform

O exemplo a seguir ilustra como definir a matriz filters para desfocar a exibio HTML inteira:
var html:HTMLLoader = new HTMLLoader(); var urlReq:URLRequest = new URLRequest("http://www.adobe.com/"); html.load(urlReq); html.width = 800; html.height = 600; var blur:BlurFilter = new BlurFilter(8); var filters:Array = [blur]; html.filters = filters;

Rolagem de contedo HTML

Adobe AIR 1.0 e posterior A classe HTMLLoader inclui as seguintes propriedades que permitem controlar a rolagem de contedo HTML:
Propriedade
contentHeight

Descrio A altura, em pixels, do contedo HTML. A largura, em pixels, do contedo HTML. A posio da barra de rolagem horizontal do contedo HTML no objeto HTMLLoader. A posio da barra de rolagem vertical do contedo HTML no objeto HTMLLoader.

contentWidth scrollH scrollV

O cdigo a seguir define a propriedade scrollV, de modo que o contedo HTML seja rolado para a parte inferior da pgina:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Script no continer HTML do AIR

995

var html:HTMLLoader = new HTMLLoader(); html.addEventListener(Event.HTML_BOUNDS_CHANGE, scrollHTML); const SIZE:Number = 600; html.width = SIZE; html.height = SIZE; var urlReq:URLRequest = new URLRequest("http://www.adobe.com"); html.load(urlReq); this.addChild(html); function scrollHTML(event:Event):void { html.scrollV = html.contentHeight - SIZE; }

O HTMLLoader no inclui barras de rolagem horizontal e vertical. Voc pode implementar barras de rolagem no ActionScript ou usando um componente Flex. O componente HTML do Flex inclui automaticamente barras de rolagem para contedo HTML. Voc tambm pode usar o mtodo HTMLLoader.createRootWindow() para criar uma janela contendo um objeto HTMLLoader com barras de rolagem (consulte Criao de janelas com contedo HTML de rolagem na pgina 1007).

Acesso lista de histrico de HTML

Adobe AIR 1.0 e posterior medida que novas pginas so carregadas no objeto HTMLLoader, o tempo de execuo mantm uma lista de histrico do objeto. A lista de histrico corresponde ao objeto window.history na pgina HTML. A classe HTMLLoader inclui as seguintes propriedades e mtodos que permitem trabalhar com a lista de histrico de HTML:
Membro de classe
historyLength historyPosition

Descrio O comprimento geral da lista de histrico, incluindo entradas dianteiras e traseiras. A posio atual na lista de histrico. Os itens de histrico antes dessa posio representam navegao "para trs" e itens aps essa posio representam navegao para frente. Retorna o objeto URLRequest correspondente entrada de histrico na posio especificada na lista de histrico. Navega para trs na lista de histrico, se possvel. Navega para frente na lista de histrico, se possvel. Navega o nmero indicado de etapas no histrico do navegador. Navega para frente, se for positivo, e para trs, se for negativo. Navegar para zero recarrega a pgina. Especificar uma posio alm do final, navega para o final da lista.

getHistoryAt()

historyBack() historyForward() historyGo()

Itens na lista de histrico so armazenados como objetos do tipo HTMLHistoryItem. A classe HTMLHistoryItem possui as propriedades a seguir:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Script no continer HTML do AIR

996

Propriedade
isPost originalUrl ttulo url

Descrio Defina como true se a pgina HTML incluir dados POST. A URL original da pgina HTML antes de qualquer redirecionamento. O ttulo da pgina HTML. A URL da pgina HTML.

Definio do agente do usurio usado ao carregar contedo HTML

Adobe AIR 1.0 e posterior A classe HTMLLoader tem a propriedade userAgent, que permite definir a seqncia de agente do usurio usada pelo HTMLLoader. Defina a propriedade userAgent do objeto HTMLLoader antes de chamar o mtodo load(). Se voc definir esta propriedade na ocorrncia HTMLLoader, a propriedade userAgent do URLRequest passada para o mtodo load()no ser usada. Voc pode definir a string de agente do usurio padro usada por todos os objetos HTMLLoader em um domnio de aplicativo, configurando a propriedade URLRequestDefaults.userAgent. As propriedades URLRequestDefaults estticas aplicam-se como padro para todos os objetos URLRequest e no somente URLRequests usadas no mtodo load() de objetos HTMLLoader. Configurar a propriedade userAgent do HTMLLoader substitui a configurao URLRequestDefaults.userAgent padro. Se voc no definir um valor de agente do usurio para a propriedade userAgent do objeto HTMLLoader ou para URLRequestDefaults.userAgent, o valor de agente do usurio AIR padro ser usado. Esse valor padro varia em funo do sistema operacional do tempo de execuo (tal como Mac OS ou Windows), do idioma do tempo de execuo e da verso, como nos dois exemplos a seguir:

"Mozilla/5.0 (Macintosh; U; PPC Mac OS X; en) AppleWebKit/420+ (KHTML, como Gecko) AdobeAIR/1.0" "Mozilla/5.0 (Windows; U; en) AppleWebKit/420+ (KHTML, como Gecko) AdobeAIR/1.0"

Configurao de codificao de caractere para uso de contedo HTML.

Adobe AIR 1.0 e posterior A pgina HTML pode especificar a codificao de caractere por ela usado, incluindo a tag meta, como a seguir:
meta http-equiv="content-type" content="text/html" charset="ISO-8859-1";

Substitua a configurao da pgina para assegurar que a codificao de caractere especfica seja usada, configurando a propriedade textEncodingOverride do objeto HTMLLoader:
var html:HTMLLoader = new HTMLLoader(); html.textEncodingOverride = "ISO-8859-1";

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Script no continer HTML do AIR

997

Especifique a codificao de caractere do contedo HTMLLoader que dever ser usada quando a pgina HTML no especificar uma configurao com a propriedade textEncodingFallback do objeto HTMLLoader:
var html:HTMLLoader = new HTMLLoader(); html.textEncodingFallback = "ISO-8859-1";

A propriedade textEncodingOverride substitui a configurao da pgina HTML. E a propriedade textEncodingOverride e a configurao da pgina HTML substituem a propriedade textEncodingFallback. Defina a propriedade textEncodingOverride ou a propriedade textEncodingFallback antes de carregar contedo HTML.

Definio de interfaces do usurio como navegadores para contedo HTML

Adobe AIR 1.0 e posterior O JavaScript oferece diversas APIs para controlar a janela que exibe o contedo HTML. No AIR, essas APIs podem ser sobrescritas com a implementao de uma classe personalizada HTMLHost.

Sobre estender a classe HTMLHost

Adobe AIR 1.0 e posterior Se, por exemplo, o aplicativo apresentar vrios objetos HTMLLoader em uma interface com abas, talvez voc deseje que as alteraes feitas pelas pginas HTML carregadas alterem o rtulo da aba e no o ttulo da janela principal. Da mesma forma, o cdigo pode responder a uma chamada window.moveTo() reposicionando o objeto HTMLLoader no respectivo continer do objeto de exibio pai, movendo a janela que contm o objeto HTMLLoader, no fazendo exatamente nada ou fazendo alguma outra coisa por completo. A classe HTMLHost do AIR controla as seguintes propriedades e mtodos JavaScript:

window.status window.document.title window.location window.blur() window.close() window.focus() window.moveBy() window.moveTo() window.open() window.resizeBy() window.resizeTo()

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Script no continer HTML do AIR

998

Quando voc cria um objeto HTMLLoader usando new HTMLLoader(), as propriedades ou mtodos JavaScript listados no so ativados. A classe HTMLHost oferece uma implementao padro como navegador dessas APIs JavaScript. Voc tambm pode estender a classe HTMLHost para personalizar o comportamento. Para criar um objeto HTMLHost que oferea suporte ao comportamento padro, defina o parmetro defaultBehaviors como true no construtor HTMLHost:
var defaultHost:HTMLHost = new HTMLHost(true);

Quando voc cria uma janela HTML no AIR com o mtodo createRootWindow() da classe HTMLLoader, uma ocorrncia HTMLHost com suporte aos comportamentos padro atribuda automaticamente. Voc pode alterar o comportamento do objeto host atribuindo uma implementao HTMLHost diferente propriedade htmlHost do HTMLLoader ou, pode atribuir null para desativar os recursos completamente. Nota: O AIR atribui um objeto HTMLHost padro janela inicial criada para o aplicativo AIR baseado em HTML e qualquer janela criada pela implementao padro do mtodo window.open() de JavaScript.

Exemplo: Extenso da classe HTMLHost

Adobe AIR 1.0 e posterior O exemplo a seguir mostra como personalizar a maneira como o objeto HTMLLoader afeta a interface do usurio, estendendo a classe HTMLHost: Exemplo do Flex: 1 Crie uma classe que estenda a classe HTMLHost (uma subclasse).
2 Substitua os mtodos da nova classe para tratar alteraes nas configuraes relacionadas interface do usurio.

Por exemplo, a classe a seguir, CustomHost, define comportamentos de chamadas parawindow.open() e altera para window.document.title. As chamadas para window.open() abrem a pgina HTML em uma nova janela e alteraes em window.document.title (incluindo a configurao do elemento <title> da pgina HTML) definem o ttulo dessa janela.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Script no continer HTML do AIR

999

package { import import import import

flash.html.*; flash.display.StageScaleMode; flash.display.NativeWindow; flash.display.NativeWindowInitOptions;

public class CustomHost extends HTMLHost { import flash.html.*; override public function createWindow(windowCreateOptions:HTMLWindowCreateOptions):HTMLLoader { var initOptions:NativeWindowInitOptions = new NativeWindowInitOptions(); var bounds:Rectangle = new Rectangle(windowCreateOptions.x, windowCreateOptions.y, windowCreateOptions.width, windowCreateOptions.height); var htmlControl:HTMLLoader = HTMLLoader.createRootWindow(true, initOptions, windowCreateOptions.scrollBarsVisible, bounds); htmlControl.htmlHost = new HTMLHostImplementation(); if(windowCreateOptions.fullscreen){ htmlControl.stage.displayState = StageDisplayState.FULL_SCREEN_INTERACTIVE; } return htmlControl; } override public function updateTitle(title:String):void { htmlLoader.stage.nativeWindow.title = title; } } }

3 No cdigo que contm o HTMLLoader (no no cdigo da nova subclasse de HTMLHost), crie um objeto da nova

classe. Atribua o novo objeto propriedade htmlHost do HTMLLoader. O seguinte cdigo Flex usa a classe CustomHost definida na etapa anterior:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Script no continer HTML do AIR

1000

<?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical" applicationComplete="init()"> <mx:Script> <![CDATA[ import flash.html.HTMLLoader; import CustomHost; private function init():void { var html:HTMLLoader = new HTMLLoader(); html.width = container.width; html.height = container.height; var urlReq:URLRequest = new URLRequest("Test.html"); html.htmlHost = new CustomHost(); html.load(urlReq); container.addChild(html); } ]]> </mx:Script> <mx:UIComponent id="container" width="100%" height="100%"/> </mx:WindowedApplication>

Para testar o cdigo descrito aqui, inclua um arquivo HTML com o seguinte contedo no diretrio do aplicativo:
<html> <head> <title>Test</title> </head> <script> function openWindow() { window.runtime.trace("in"); document.title = "foo" window.open('Test.html'); window.runtime.trace("out"); } </script> <body> <a href="#" onclick="openWindow()">window.open('Test.html')</a> </body> </html>

Exemplo do Flash Professional: 1 Crie um arquivo Flash para o AIR. Defina a classe do documento como CustomHostExample e, em seguida, salve o arquivo como CustomHostExample.fla.
2 Crie um arquivo ActionScript chamado CustomHost.as contendo uma classe que estenda a classe HTMLHost

(uma subclasse). Essa classe substitui certos mtodos da nova classe para tratar alteraes nas configuraes relacionadas interface do usurio. Por exemplo, a classe a seguir, CustomHost, define comportamentos de chamadas parawindow.open() e altera para window.document.title. As chamadas para o mtodo window.open() abrem a pgina HTML em uma nova janela e alteraes na propriedade window.document.title (incluindo a configurao do elemento <title> da pgina HTML) definem o ttulo dessa janela.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Script no continer HTML do AIR

1001

package { import import import import import import import import import import

flash.display.StageScaleMode; flash.display.NativeWindow; flash.display.NativeWindowInitOptions; flash.events.Event; flash.events.NativeWindowBoundsEvent; flash.geom.Rectangle; flash.html.HTMLLoader; flash.html.HTMLHost; flash.html.HTMLWindowCreateOptions; flash.text.TextField;

public class CustomHost extends HTMLHost { public var statusField:TextField; public function CustomHost(defaultBehaviors:Boolean=true) { super(defaultBehaviors); } override public function windowClose():void { htmlLoader.stage.nativeWindow.close(); } override public function createWindow( windowCreateOptions:HTMLWindowCreateOptions ):HTMLLoader { var initOptions:NativeWindowInitOptions = new NativeWindowInitOptions(); var bounds:Rectangle = new Rectangle(windowCreateOptions.x, windowCreateOptions.y, windowCreateOptions.width, windowCreateOptions.height); var htmlControl:HTMLLoader = HTMLLoader.createRootWindow(true, initOptions, windowCreateOptions.scrollBarsVisible, bounds); htmlControl.htmlHost = new HTMLHostImplementation(); if(windowCreateOptions.fullscreen){ htmlControl.stage.displayState = StageDisplayState.FULL_SCREEN_INTERACTIVE; } return htmlControl; } override public function updateLocation(locationURL:String):void { trace(locationURL); } override public function set windowRect(value:Rectangle):void { htmlLoader.stage.nativeWindow.bounds = value;

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Script no continer HTML do AIR

1002

} override public function updateStatus(status:String):void { statusField.text = status; trace(status); } override public function updateTitle(title:String):void { htmlLoader.stage.nativeWindow.title = title + "- Example Application"; } override public function windowBlur():void { htmlLoader.alpha = 0.5; } override public function windowFocus():void { htmlLoader.alpha = 1; } } }

3 Crie outro arquivo ActionScript chamado CustomHostExample.as para conter a classe de documento do

aplicativo. Essa classe cria um objeto HTMLLoader e define a respectiva propriedade host como uma ocorrncia da classe CustomHost definida na etapa anterior:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Script no continer HTML do AIR

1003

package { import import import import

flash.display.Sprite; flash.html.HTMLLoader; flash.net.URLRequest; flash.text.TextField;

public class CustomHostExample extends Sprite { function CustomHostExample():void { var html:HTMLLoader = new HTMLLoader(); html.width = 550; html.height = 380; var host:CustomHost = new CustomHost(); html.htmlHost = host; var urlReq:URLRequest = new URLRequest("Test.html"); html.load(urlReq); addChild(html); var statusTxt:TextField = new TextField(); statusTxt.y = 380; statusTxt.height = 20; statusTxt.width = 550; statusTxt.background = true; statusTxt.backgroundColor = 0xEEEEEEEE; addChild(statusTxt); host.statusField = statusTxt; } } }

Para testar o cdigo descrito aqui, inclua um arquivo HTML com o seguinte contedo no diretrio do aplicativo:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Script no continer HTML do AIR

1004

<html> <head> <title>Test</title> <script> function openWindow() { document.title = "Test" window.open('Test.html'); } </script> </head> <body bgColor="#EEEEEE"> <a href="#" onclick="window.open('Test.html')">window.open('Test.html')</a> <br/><a href="#" onclick="window.document.location='http://www.adobe.com'"> window.document.location = 'http://www.adobe.com'</a> <br/><a href="#" onclick="window.moveBy(6, 12)">moveBy(6, 12)</a> <br/><a href="#" onclick="window.close()">window.close()</a> <br/><a href="#" onclick="window.blur()">window.blur()</a> <br/><a href="#" onclick="window.focus()">window.focus()</a> <br/><a href="#" onclick="window.status = new Date().toString()">window.status=new Date().toString()</a> </body> </html>

Tratamento de alteraes na propriedade window.location

Adobe AIR 1.0 e posterior Substitua o mtodo locationChange() para tratar alteraes da URL da pgina HTML. O mtodo locationChange() chamado quando o JavaScript em uma pgina altera o valor de window.location. O exemplo a seguir simplesmente carrega a URL solicitada:
override public function updateLocation(locationURL:String):void { htmlLoader.load(new URLRequest(locationURL)); }

Nota: Voc pode usar a propriedade htmlLoader do objeto HTMLHost para fazer referncia ao objeto HTMLLoader atual.

Tratamento de chamadas de JavaScript de window.moveBy(), window.moveTo(), window.resizeTo() e window.resizeBy()

Adobe AIR 1.0 e posterior Substitua o mtodo set windowRect() para tratar alteraes nos limites do contedo HTML. O mtodo set windowRect() chamado quando o JavaScript em uma pgina chama window.moveBy(), window.moveTo(), window.resizeTo() ou window.resizeBy(). O exemplo a seguir simplesmente atualiza os limites da janela da rea de trabalho:
override public function set windowRect(value:Rectangle):void { htmlLoader.stage.nativeWindow.bounds = value; }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Script no continer HTML do AIR

1005

Tratamento de chamadas JavaScript de window.open()

Adobe AIR 1.0 e posterior Substitui o mtodo createWindow() para tratar chamadas JavaScript de window.open(). As implementaes do mtodo createWindow() so responsveis pela criao e retorno de um novo objeto HTMLLoader. Normalmente voc exibe o HTMLLoader em uma nova janela, mas no necessrio criar uma nova janela. O exemplo a seguir ilustra como implementar a funo createWindow() usando HTMLLoader.createRootWindow() para criar a janela e o objeto HTMLLoader. Voc tambm pode criar o objeto NativeWindow separadamente e adicionar o HTMLLoader ao palco da janela.
override public function createWindow(windowCreateOptions:HTMLWindowCreateOptions):HTMLLoader{ var initOptions:NativeWindowInitOptions = new NativeWindowInitOptions(); var bounds:Rectangle = new Rectangle(windowCreateOptions.x, windowCreateOptions.y, windowCreateOptions.width, windowCreateOptions.height); var htmlControl:HTMLLoader = HTMLLoader.createRootWindow(true, initOptions, windowCreateOptions.scrollBarsVisible, bounds); htmlControl.htmlHost = new HTMLHostImplementation(); if(windowCreateOptions.fullscreen){ htmlControl.stage.displayState = StageDisplayState.FULL_SCREEN_INTERACTIVE; } return htmlControl; }

Nota: Esse exemplo atribui a implementao HTMLHost personalizada a qualquer janela nova criada com window.open(). Voc tambm pode usar uma implementao diferente ou definir a propriedade htmlHost como null em novas janelas, se desejar. O objeto passado como parmetro para o mtodo createWindow() um objeto HTMLWindowCreateOptions. A classe HTMLWindowCreateOptions inclui propriedades que informam os valores definidos na seqncia de parmetro features na chamada de window.open():
propriedade HTMLWindowCreateOptions Configurao correspondente na string de recursos na chamada JavaScript para window.open()
fullscreen height location menubar resizable scrollbars status toolbar width left ou screenX top ou screenY

fullscreen height locationBarVisible menuBarVisible resizeable scrollBarsVisible statusBarVisible toolBarVisible width x y

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Script no continer HTML do AIR

1006

A classe HTMLLoader no implementa todos os recursos que podem ser especificados na string de recursos. O aplicativo deve fornecer barras de rolagem, barras de localizao, barras de menu, barras de status e barras de ferramentas, quando apropriado. Os outros argumentos para o mtodo window.open() de JavaScript so tratados pelo sistema. A implementao createWindow() no deve carregar contedo no objeto HTMLLoader nem definir o ttulo da janela.

Tratamento de chamadas JavaScript de window.close()

Adobe AIR 1.0 e posterior Substitui o mtodo windowClose() para tratar chamadas JavaScript do mtodo window.close(). O exemplo a seguir fecha a janela da rea de trabalho quando o mtodo window.close() chamado:
override public function windowClose():void { htmlLoader.stage.nativeWindow.close(); }

As chamadas JavaScript de window.close() no tm que fechar as janelas que as contm. Voc pode, por exemplo, remover o HTMLLoader da lista de exibio, deixando a janela (que pode ter outro contedo) aberta, conforme o cdigo a seguir:
override public function windowClose():void { htmlLoader.parent.removeChild(htmlLoader); }

Tratamento de alteraes da propriedade windows.status

Adobe AIR 1.0 e posterior Substitua o mtodo updateStatus() para tratar alteraes JavaScript no valor de window.status. O exemplo a seguir rastreia o valor do status:
override public function updateStatus(status:String):void { trace(status); }

O status solicitado passado como string para o mtodo updateStatus(). O objeto HTMLLoader no oferece uma barra de status.

Tratamento de alteraes da propriedade window.document.title

Adobe AIR 1.0 e posterior Substitua o mtodo updateTitle() para tratar alteraes JavaScript no valor de window.document.title. O exemplo a seguir altera o ttulo da janela e acrescenta a seqncia, "Sample", ao ttulo:
override public function updateTitle(title:String):void { htmlLoader.stage.nativeWindow.title = title + " - Sample"; }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Script no continer HTML do AIR

1007

Quando document.title estiver definido em uma pgina HTML, o ttulo solicitado ser passado como string para o mtodo updateTitle(). As alteraes em document.title no devem alterar o ttulo da janela que contm o objeto HTMLLoader. Voc pode, por exemplo, alterar outro elemento de interface, como campo de texto.

Tratamento de chamadas JavaScript de window.blur() e window.focus()

Adobe AIR 1.0 e posterior Substitua os mtodos windowBlur() e windowFocus() para tratar chamadas JavaScript dewindow.blur() e window.focus(), conforme mostrado o exemplo a seguir:
override public function windowBlur():void { htmlLoader.alpha = 0.5; } override public function windowFocus():void { htmlLoader.alpha = 1.0; NativeApplication.nativeApplication.activate(htmlLoader.stage.nativeWindow); }

Nota: O AIR no fornece nenhuma API para desativar janela nem aplicativo.

Criao de janelas com contedo HTML de rolagem

Adobe AIR 1.0 e posterior A classe HTMLLoader inclui um mtodo esttico, HTMLLoader.createRootWindow(), que permite abrir uma nova janela (representada por um objeto NativeWindow) que contm um objeto HTMLLoader e define algumas configuraes da interface do usurio para essa janela. O mtodo tem quatro parmetros que permitem definir a interface do usurio:
Parmetro
visible windowInitOptions

Descrio Um valor booleano que especifica se a janela ficar inicialmente visvel (true) ou no (false). Um objeto NativeWindowInitOptions. A classe NativeWindowInitOptions define as opes de inicializao do objeto NativeWindow, incluindo o seguinte: se a janela minimizvel, maximizvel ou redimensionvel, se a janela tem cromo do sistema ou cromo personalizado, se a janela transparente ou no (para janelas que no usam o cromo do sistema) e o tipo de janela. Se h barras de rolagem (true) ou no (false). Um objeto Rectangle definindo a posio e as dimenses da nova janela.

scrollBarsVisible bounds

Por exemplo, o cdigo a seguir usa o mtodo HTMLLoader.createRootWindow() para criar uma janela com contedo HTMLLoader que usa barras de rolagem:
var initOptions:NativeWindowInitOptions = new NativeWindowInitOptions(); var bounds:Rectangle = new Rectangle(10, 10, 600, 400); var html2:HTMLLoader = HTMLLoader.createRootWindow(true, initOptions, true, bounds); var urlReq2:URLRequest = new URLRequest("http://www.example.com"); html2.load(urlReq2); html2.stage.nativeWindow.activate();

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Script no continer HTML do AIR

1008

Nota: Janelas criadas chamando createRootWindow() diretamente em JavaScript permanecem independentes da janela HTML aberta. As propriedades opener e parent da janela JavaScript, por exemplo, so null. No entanto, se voc chamar createRootWindow() indiretamente substituindo o mtodo createWindow() do HTMLHost para chamar createRootWindow(), opener e parent faro referncia janela HTML aberta.

Criao de subclasses da classe HTMLLoader

Adobe AIR 1.0 e posterior Voc pode criar uma subclasse da classe HTMLLoader para criar novos comportamentos. Por exemplo, voc pode criar uma subclasse que defina ouvintes de evento padro de eventos HTMLLoader (como os eventos despachados quando o HTML processado ou quando um usurio clica em um link). O exemplo a seguir estende a classe HTMLHost para apresentar comportamento normal quando o mtodo window.open() de JavaScript for chamado. O exemplo a seguir define uma subclasse do HTMLLoader que usa a classe personalizada de implementao HTMLHost:
package { import flash.html.HTMLLoader; public class MyHTMLHost extends HTMLHost { public function MyHTMLHost() { super(false); } override public function createWindow(opts:HTMLWindowCreateOptions):void { var initOptions:NativeWindowInitOptions = new NativeWindowInitOptions(); var bounds:Rectangle = new Rectangle(opts.x, opts.y, opts.width, opts.height); var html:HTMLLoader = HTMLLoader.createRootWindow(true, initOptions, opts.scrollBarsVisible, bounds); html.stage.nativeWindow.orderToFront(); return html } }

O seguinte define uma subclasse da classe HTMLLoader que atribui um objeto MyHTMLHost respectiva propriedade htmlHost:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Script no continer HTML do AIR

1009

package { import flash.html.HTMLLoader; import MyHTMLHost; import HTMLLoader; public class MyHTML extends HTMLLoader { public function MyHTML() { super(); htmlHost = new MyHTMLHost(); } } }

Para obter detalhes sobre a classe HTMLHost e o mtodo HTMLLoader.createRootWindow() usado nesse exemplo, consulte Definio de interfaces do usurio como navegadores para contedo HTML na pgina 997.

ltima atualizao em 29/3/2011

1010

Captulo 58: Tratamento de eventos relacionados a HTML no AIR

Adobe AIR 1.0 e posterior O sistema de tratamento de eventos permite que os programadores respondam s entradas de usurios e eventos do sistema de forma conveniente. O modelo de evento do Adobe AIR no apenas conveniente, mas tambm compatvel com os padres. Com base na Especificao de eventos DOM (Modelo de objeto de documento) de Nvel 3, uma arquitetura de tratamento de eventos padro do segmento, o modelo de evento oferece uma ferramenta de tratamento de eventos eficiente e intuitiva para programadores.

eventos HTMLLoader
Adobe AIR 1.0 e posterior O objeto HTMLLoader despacha os seguintes eventos do Adobe ActionScript3.0:
Evento
htmlDOMInitialize

Descrio Despachado quando o documento HTML criado, mas antes que qualquer script seja analisado ou que os ns DOM sejam adicionados pgina. Despachado quando o HTML DOM tiver sido criado em resposta operao de carregamento, logo aps o evento onload na pgina HTML. Despachado quando uma ou as duas propriedades contentWidth e contentHeight so alteradas. Despachado quando a propriedade location do HTMLLoader foi alterada. Despachado a sempre que o mecanismo HTML altera a posio de rolagem. Eventos de rolagem podem ocorrer devido navegao para ancorar links (n de links) na pgina ou devido s chamadas do mtodowindow.scrollTo(). Inserir texto em uma entrada de texto ou rea de texto tambm pode gerar um evento de rolagem. Despachado quando ocorre uma exceo JavaScript no HTMLLoader e a exceo no capturada no cdigo JavaScript.

complete

htmlBoundsChanged

locationChange scroll

uncaughtScriptException

Voc tambm pode registrar uma funo ActionScript para o evento JavaScript (como onClick). Para obter detalhes, consulte Tratamento de eventos DOM com o ActionScript na pgina 1010.

Tratamento de eventos DOM com o ActionScript

Adobe AIR 1.0 e posterior Voc pode registrar as funes do ActionScript para que respondam a eventos JavaScript. Por exemplo, considere o seguinte contedo HTML:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Tratamento de eventos relacionados a HTML no AIR

1011

<html> <body> <a href="#" id="testLink">Click me.</a> </html>

Voc pode registrar uma funo do ActionScript como manipulador de qualquer evento na pgina. Por exemplo, o cdigo a seguir adiciona a funo clickHandler() como o ouvinte do evento onclick do elemento testLink na pgina HTML:
var html:HTMLLoader = new HTMLLoader( ); var urlReq:URLRequest = new URLRequest("test.html"); html.load(urlReq); html.addEventListener(Event.COMPLETE, completeHandler); function completeHandler(event:Event):void { html.window.document.getElementById("testLink").onclick = clickHandler; } function clickHandler( event:Object ):void { trace("Event of type: " + event.type ); }

O objeto de evento despachado no do tipo flash.events.Event nem uma das subclasses Event. Use a classe Object para declarar um tipo para o argumento da funo de tratamento de evento. Voc tambm pode usar o mtodo addEventListener() para se registrar para esses eventos. Por exemplo, voc pode substituir o mtodo completeHandler() no exemplo anterior pelo seguinte cdigo:
function completeHandler(event:Event):void { var testLink:Object = html.window.document.getElementById("testLink"); testLink.addEventListener("click", clickHandler); }

Quando um ouvinte se refere a um elemento DOM especfico, bom aguardar que o HTMLLoader pai despache o evento complete antes de adicionar os ouvintes de evento. As pginas HTML com freqncia carregam vrios arquivos e o HTML DOM no criado totalmente at que todos os arquivos sejam carregados e analisados. O HTMLLoader despacha o evento complete quando todos os elementos tiverem sido criados.

Resposta a excees JavaScript no capturadas

Adobe AIR 1.0 e posterior Considere o seguinte HTML:
<html> <head> <script> function throwError() { var x = 400 * melbaToast; } </script> </head> <body> <a href="#" onclick="throwError()">Click me.</a> </html>

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Tratamento de eventos relacionados a HTML no AIR

1012

Ele contm uma funo JavaScript, throwError(), que faz referncia a uma varivel desconhecida, melbaToast:
var x = 400 * melbaToast;

Quando a operao de JavaScript encontra uma operao ilegal no capturada no cdigo JavaScript com uma estrutura try/catch, o objeto HTMLLoader que contm a pgina despacha um evento HTMLUncaughtScriptExceptionEvent. Voc pode registrar um manipulador para esse evento, como no cdigo a seguir:
var html:HTMLLoader = new HTMLLoader(); var urlReq:URLRequest = new URLRequest("test.html"); html.load(urlReq); html.width = container.width; html.height = container.height; container.addChild(html); html.addEventListener(HTMLUncaughtScriptExceptionEvent.UNCAUGHT_SCRIPT_EXCEPTION, htmlErrorHandler); function htmlErrorHandler(event:HTMLUncaughtJavaScriptExceptionEvent):void { event.preventDefault(); trace("exceptionValue:", event.exceptionValue) for (var i:int = 0; i < event.stackTrace.length; i++) { trace("sourceURL:", event.stackTrace[i].sourceURL); trace("line:", event.stackTrace[i].line); trace("function:", event.stackTrace[i].functionName); } }

No JavaScript, voc pode tratar o mesmo evento usando a propriedade window.htmlLoader:

<html> <head> <script language="javascript" type="text/javascript" src="AIRAliases.js"></script> <script> function throwError() { var x = 400 * melbaToast; } function htmlErrorHandler(event) { event.preventDefault(); var message = "exceptionValue:" + event.exceptionValue + "\n"; for (var i = 0; i < event.stackTrace.length; i++){ message += "sourceURL:" + event.stackTrace[i].sourceURL +"\n"; message += "line:" + event.stackTrace[i].line +"\n"; message += "function:" + event.stackTrace[i].functionName + "\n"; } alert(message); } window.htmlLoader.addEventListener("uncaughtScriptException", htmlErrorHandler); </script> </head> <body> <a href="#" onclick="throwError()">Click me.</a> </html>

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Tratamento de eventos relacionados a HTML no AIR

1013

O manipulador de eventos htmlErrorHandler() cancela o comportamento padro do evento (que enviar a mensagem de erro de JavaScript para a sada trace do AIR) e gera sua prpria mensagem de sada. Ele produz o valor do exceptionValue do objeto HTMLUncaughtScriptExceptionEvent. Ele produz as propriedades de cada objeto na matriz stackTrace:
exceptionValue: ReferenceError: Can't find variable: melbaToast sourceURL: app:/test.html line: 5 function: throwError sourceURL: app:/test.html line: 10 function: onclick

Tratamento de eventos de tempo de execuo com JavaScript

Adobe AIR 1.0 e posterior As classes de tempo de execuo oferecem suporte adio de manipuladores de eventos com o mtodo addEventListener(). Para adicionar uma funo do manipulador a um evento, chame o mtodo addEventListener() do objeto que despacha o evento, fornecendo o tipo de evento e a funo de tratamento. Por exemplo, para ouvir o evento closing despachado quando o usurio clica no boto Fechar da janela na barra de ttulo, use a seguinte instruo:
window.nativeWindow.addEventListener(air.NativeWindow.CLOSING, handleWindowClosing);

Criao de funo do manipulador de eventos

Adobe AIR 1.0 e posterior O cdigo a seguir cria um arquivo HTML simples que exibe informaes sobre a posio da janela principal. A funo do manipulador, chamada de moveHandler(), ouve o evento move (definido pela classe NativeWindowBoundsEvent) da janela principal.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Tratamento de eventos relacionados a HTML no AIR

1014

<html> <script src="AIRAliases.js" /> <script> function init() { writeValues(); window.nativeWindow.addEventListener(air.NativeWindowBoundsEvent.MOVE, moveHandler); } function writeValues() { document.getElementById("xText").value = window.nativeWindow.x; document.getElementById("yText").value = window.nativeWindow.y; } function moveHandler(event) { air.trace(event.type); // move writeValues(); } </script> <body onload="init()" /> <table> <tr> <td>Window X:</td> <td><textarea id="xText"></textarea></td> </tr> <tr> <td>Window Y:</td> <td><textarea id="yText"></textarea></td> </tr> </table> </body> </html>

Quando o usurio move a janela, os elementos da rea de texto exibem as posies X e Y atualizadas da janela: Observe que o objeto de evento passado como argumento para o mtodo moveHandler(). O parmetro event permite que a funo do manipulador examine o objeto de evento. Neste exemplo, voc usa a propriedade type do objeto de evento para informar que o evento um evento move.

Remoo de ouvintes de eventos

Adobe AIR 1.0 e posterior Voc pode usar o mtodo removeEventListener() para remover um ouvinte de evento que no seja mais necessrio. uma boa idia remover o ouvinte que no ser mais usado. Entre os parmetros obrigatrios esto eventName e listener, que so os mesmos parmetros obrigatrios no mtodo addEventListener().

Remoo de ouvintes de eventos nas pginas HTML que navegam

Adobe AIR 1.0 e posterior Quando o contedo HTML navegado ou quando descartado porque a janela que o contm fechada, os ouvintes de eventos que fazem referncia a objetos na pgina no carregada no so removidos automaticamente. Quando um objeto envia um evento para um manipulador que j foi descarregado, a mensagem de erro a seguir exibida: "O aplicativo tentou criar uma referncia a um objeto JavaScript e uma pgina HTML que no est mais carregada.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Tratamento de eventos relacionados a HTML no AIR

1015

Para evitar esse tipo de erro, remova os ouvintes de eventos JavaScript da pgina HTML antes que ele parta. No caso de navegao de pgina (em um objeto HTMLLoader), remova o ouvinte de evento durante o evento unload do objeto window. Por exemplo, o cdigo JavaScript a seguir remove um ouvinte de evento de um evento uncaughtScriptException:
window.onunload = cleanup; window.htmlLoader.addEventListener('uncaughtScriptException', uncaughtScriptException); function cleanup() { window.htmlLoader.removeEventListener('uncaughtScriptException', uncaughtScriptExceptionHandler); }

Para impedir que o erro ocorra ao fechar janelas que contm esse contedo HTML, chame uma funo de limpeza em resposta ao evento closing do objeto NativeWindow (window.nativeWindow). Por exemplo, o cdigo JavaScript a seguir remove um ouvinte de evento de um evento uncaughtScriptException:
window.nativeWindow.addEventListener(air.Event.CLOSING, cleanup); function cleanup() { window.htmlLoader.removeEventListener('uncaughtScriptException', uncaughtScriptExceptionHandler); }

Voc tambm pode impedir esse erro removendo um ouvinte de evento to logo seja executado (se o evento s precisar ser tratado uma vez). Por exemplo, o cdigo JavaScript a seguir cria uma janela html chamando o mtodo createRootWindow() da classe HTMLLoader e adiciona um ouvinte de evento ao evento complete. Quando o manipulador de eventos complete chamado, ele remove o prprio ouvinte de evento usando a funo removeEventListener():
var html = runtime.flash.html.HTMLLoader.createRootWindow(true); html.addEventListener('complete', htmlCompleteListener); function htmlCompleteListener() { html.removeEventListener(complete, arguments.callee) // handler code.. } html.load(new runtime.flash.net.URLRequest("second.html"));

Remover ouvintes de evento desnecessrios tambm permite que o coletor de lixo do sistema recupere qualquer memria associada a esses ouvintes.

Verificao da existncia de ouvintes de eventos

Adobe AIR 1.0 e posterior O mtodo hasEventListener() permite verificar a existncia de um ouvinte de evento em um objeto.

ltima atualizao em 29/3/2011

1016

Captulo 59: Exibio de contedo HTML em aplicativos mveis

Adobe AIR AIR 2.5 e posterior A classe StageWebView exibe contedo HTML usando o controle do navegador do sistema em dispositivos mveis e usando o controle Adobe AIR HTMLLoader padro em computadores desktop. Verifique a propriedade StageWebView.isSupported para determinar se a classe conta com suporte no dispositivo atual. O suporte no garantido para todos os dispositivos no perfil mvel. Em todos os perfis, a classe StageWebView oferece suporte somente interao limitada entre o contedo HTML e o resto do aplicativo. Voc pode controlar a navegao, mas scripts cruzados e a troca direta de dados no so permitidos. Voc pode carregar contedo de um URL local ou remoto ou pass-lo em uma string de HTML.

Mais tpicos da Ajuda

Mark Doherty: StageWebView demo - OAuth Support (Demonstrao do StageWebView - Suporte a OAuth) Jonathan Campos: HTML Web View in AIR for Android (Visualizao de HTML na Web no AIR para Android) Snke Rohde: AIR Mobile StageWebView UIComponent ( O Componente de Interface do Usurio StageWebView no AIR Mobile) Judah Frangipane: Using StageWebView within a UIComponent in Mobile (Usando o StageWebView em um Componente de Interface do Usurio em Dispositivos Mveis)

Objetos StageWebView
O objeto StageWebView no um objeto de exibio e no pode ser adicionado lista de exibio. Em vez disso, ele funciona como um viewport anexado diretamente ao palco. O contedo StageWebView desenha sobre qualquer contedo de lista de exibio. No h nenhum modo de controlar a ordem de desenho de diferentes objetos StageWebView. Para exibir um objeto StageWebView, atribua o palco em que o objeto se encontra de modo a ser exibido para a propriedade stage do StageWebView. Defina o tamanho da exibio usando a propriedade viewPort. Defina as coordenadas X e Y da propriedade viewPort entre -8192 e 8191. O valor mximo da altura e da largura do palco 8191. Se o tamanho exceder os valores mximos, uma exceo ser lanada. O seguinte exemplo cria um objeto StageWebView, define as propriedades stage e viewPort e exibe uma string de HTML:
var webView:StageWebView = new StageWebView(); webView.viewPort = new Rectangle( 0, 0, this.stage.stageWidth, this .stage.stageHeight); webView.stage = this.stage; var htmlString:String = "<!DOCTYPE HTML>" + "<html><body>" + "<p>King Philip could order five good steaks.</p>" + "</body></html>"; webView.loadString( htmlString );

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Exibio de contedo HTML em aplicativos mveis

1017

Para ocultar um objeto StageWebView, defina sua propriedade stage como null. Para destruir o objeto completamente, chame o mtodo dispose(). Chamar dispose() opcional, mas ajuda o coletor de lixo a recuperar mais cedo a memria usada pelo objeto.

Contedo
Voc pode carregar contedo em um objeto StageWebView usando dois mtodos: loadURL() e loadString(). O mtodo loadURL() carrega um recurso no URL especificado. Voc pode usar qualquer esquema de URI com suporte no controle de navegador da Web do sistema, inclusive: data:, file:, http:, https: e javascript:. Os esquemas app: e app-storage: no so compatveis. O AIR no valida a string do URL. O mtodo loadString() carrega uma string literal com contedo HTML. O local de uma pgina carregada com esse mtodo expresso como:

No desktop: sobre:em branco No iOS: htmlString No Android: o formato do URI dos dados do htmlString codificado
O esquema de URI determina as regras de carregamento de contedo ou dados incorporados.
Esquema de URI Recurso local local Recurso remoto local Sim Sim Sim Sim XMLHttpRequest local XMLHttpRequest remoto

dados: arquivo: http:, https: sobre: (mtodo loadString())

No Sim No No

No Sim No No

No Sim Mesmo domnio No

Nota: Se a propriedade displayState do palco for definida como FULL_SCREEN, no desktop, voc no poder digitar em um campo de texto exibido em StageWebView. No entanto, no iOS e no Android, voc pode digitar em uma campo de texto em StageWebView, mesmo que o displayState do palco seja FULL_SCREEN. O exemplo a seguir usa um objeto StageWebView para exibir o site da Adobe:
package { import flash.display.MovieClip; import flash.media.StageWebView; import flash.geom.Rectangle; public class StageWebViewExample extends MovieClip{ var webView:StageWebView = new StageWebView(); public function StageWebViewExample() { webView.stage = this.stage; webView.viewPort = new Rectangle( 0, 0, stage.stageWidth, stage.stageHeight ); webView.loadURL( "http://www.adobe.com" ); } } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Exibio de contedo HTML em aplicativos mveis

1018

Em dispositivos Android, preciso especificar a permisso INTERNET do Android para que o aplicativo carregue com sucesso os recursos remotos.

URI JavaScript
Voc pode usar um URI JavaScript para chamar uma funo definida na pgina HTML carregada pelo objeto StageWebView. A funo que voc chama usando o URI JavaScript URI executada no contexto da pgina da Web carregada. O exemplo a seguir usa um objeto StageWebView para chamar uma funo JavaScript:
package { import flash.display.*; import flash.geom.Rectangle; import flash.media.StageWebView; public class WebView extends Sprite { public var webView:StageWebView = new StageWebView(); public function WebView() { var htmlString:String = "<!DOCTYPE HTML>" + "<html><script type=text/javascript>" + "function callURI(){" + "alert(\"You clicked me!!\");"+ "}</script><body>" + "<p><a href=javascript:callURI()>Click Me</a></p>" + "</body></html>"; webView.stage = this.stage; webView.viewPort = new Rectangle( 0, 0, stage.stageWidth, stage.stageHeight ); webView.loadString( htmlString ); } } }

Mais tpicos da Ajuda

Sean Voisen: Making the Most of StageWebView (Aproveitando ao Mximo o StageWebView)

Eventos de navegao
Quando o usurio clica em um link no HTML, o objeto StageWebView despacha um evento locationChanging. Voc pode chamar o mtodo preventDefault() do objeto de evento para parar a navegao. Caso contrrio, o objeto StageWebView navegar para a nova pgina e despachar um evento locationChange. Quando o carregamento da pgina concludo, o StageWebView despacha um evento complete. Um evento locationChanging despachado a cada redirecionamento do HTML. Os eventos locationChange e
complete so despachados no momento oportuno.

No iOS, um evento locationChanging despachado antes de um evento locationChange, com exceo dos primeiros mtodos loadURL() ou loadString(). Um evento locationChange tambm despachado para alteraes de navegao por iFrames e Frames. O exemplo a seguir ilustra como voc pode evitar uma alterao local e, em vez disso, abrir abrir a nova pgina no navegador do sistema.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Exibio de contedo HTML em aplicativos mveis

1019

package { import import import import import import

flash.display.MovieClip; flash.media.StageWebView; flash.events.LocationChangeEvent; flash.geom.Rectangle; flash.net.navigateToURL; flash.net.URLRequest;

public class StageWebViewNavEvents extends MovieClip{ var webView:StageWebView = new StageWebView(); public function StageWebViewNavEvents() { webView.stage = this.stage; webView.viewPort = new Rectangle( 0, 0, stage.stageWidth, stage.stageHeight ); webView.addEventListener( LocationChangeEvent.LOCATION_CHANGING, onLocationChanging ); webView.loadURL( "http://www.adobe.com" ); } private function onLocationChanging( event:LocationChangeEvent ):void { event.preventDefault(); navigateToURL( new URLRequest( event.location ) ); } } }

Histrico
Quando o usurio clica em links no contedo exibido em um objeto StageWebView, o controle salva as pilhas de histrico de avano e de retrocesso. O exemplo a seguir ilustra como navegar pelas duas pilhas de histrico. O exemplo usa as teclas programveis Voltar e Pesquisar.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Exibio de contedo HTML em aplicativos mveis

1020

package { import import import import import

flash.display.MovieClip; flash.media.StageWebView; flash.geom.Rectangle; flash.events.KeyboardEvent; flash.ui.Keyboard;

public class StageWebViewExample extends MovieClip{ var webView:StageWebView = new StageWebView(); public function StageWebViewExample() { webView.stage = this.stage; webView.viewPort = new Rectangle( 0, 0, stage.stageWidth, stage.stageHeight ); webView.loadURL( "http://www.adobe.com" ); stage.addEventListener( KeyboardEvent.KEY_DOWN, onKey ); } private function onKey( event:KeyboardEvent ):void { if( event.keyCode == Keyboard.BACK && webView.isHistoryBackEnabled ) { trace("back"); webView.historyBack(); event.preventDefault(); } if( event.keyCode == Keyboard.SEARCH && webView.isHistoryForwardEnabled ) { trace("forward"); webView.historyForward(); } } } }

Foco
Embora no seja um objeto de exibio, a classe StageWebView contm membros que permitem gerenciar as transies do foco para um controle ou para fora dele. Quando o objeto StageWebView recebe o foco, despacha um evento focusIn. Use esse evento para gerenciar os elementos de foco no aplicativo, se necessrio. Quando o StageWebView abre mo do foco, despacha um evento focusOut. Uma ocorrncia de StageWebView pode abrir mo do foco quando o usurio usa a tabulao passando pelo primeiro ou pelo ltimo controle na pgina da Web usando o trackball ou as setas de direo de um dispositivo. A propriedade direction do objeto de evento permite saber se o fluxo do foco est subindo acima do topo da pgina ou descendo alm da parte inferior da pgina. Use estas informaes para atribuir o foco ao objeto de exibio apropriado acima ou abaixo de StageWebView. No iOS, o foco no pode ser definido programaticamente. O StageWebView despacha eventos focusIn e focusOut com a propriedade direction de FocusEvent definida como none. Se o usurio tocar dentro do StageWebView, o evento focusIn despachado. Se o usurio tocar fora do StageWebView, o evento focusOut despachado.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Exibio de contedo HTML em aplicativos mveis

1021

O exemplo a seguir ilustra como o foco passa do objeto StageWebView para objetos de exibio do Flash:
package { import import import import import import import import import import flash.display.MovieClip; flash.media.StageWebView; flash.geom.Rectangle; flash.events.KeyboardEvent; flash.ui.Keyboard; flash.text.TextField; flash.text.TextFieldType; flash.events.FocusEvent; flash.display.FocusDirection; flash.events.LocationChangeEvent;

public class StageWebViewFocusEvents extends MovieClip{ var webView:StageWebView = new StageWebView(); var topControl:TextField = new TextField(); var bottomControl:TextField = new TextField(); public function StageWebViewFocusEvents() { trace("Starting"); topControl.type = TextFieldType.INPUT; addChild( topControl ); topControl.height = 60; topControl.width = stage.stageWidth; topControl.background = true; topControl.text = "One control on top."; topControl.addEventListener( FocusEvent.FOCUS_IN, flashFocusIn ); topControl.addEventListener( FocusEvent.FOCUS_OUT, flashFocusOut ); webView.stage = this.stage; webView.viewPort = new Rectangle( 0, 60, stage.stageWidth, stage.stageHeight - 120 ); webView.addEventListener( FocusEvent.FOCUS_IN, webFocusIn ); webView.addEventListener(FocusEvent.FOCUS_OUT, webFocusOut ); webView.addEventListener(LocationChangeEvent.LOCATION_CHANGING, function( event:LocationChangeEvent ):void { event.preventDefault(); } ); webView.loadString("<form action='#'><input/><input/><input/></form>"); webView.assignFocus(); bottomControl.type = TextFieldType.INPUT; addChild( bottomControl ); bottomControl.y = stage.stageHeight - 60; bottomControl.height = 60; bottomControl.width = stage.stageWidth; bottomControl.background = true; bottomControl.text = "One control on the bottom."; bottomControl.addEventListener( FocusEvent.FOCUS_IN, flashFocusIn ); bottomControl.addEventListener( FocusEvent.FOCUS_OUT, flashFocusOut );} private function webFocusIn( event:FocusEvent ):void { trace("Web focus in");

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Exibio de contedo HTML em aplicativos mveis

1022

} private function webFocusOut( event:FocusEvent ):void { trace("Web focus out: " + event.direction); if( event.direction == FocusDirection.TOP ) { stage.focus = topControl; } else { stage.focus = bottomControl; } } private function flashFocusIn( event:FocusEvent ):void { trace("Flash focus in"); var textfield:TextField = event.target as TextField; textfield.backgroundColor = 0xff5566; } private function flashFocusOut( event:FocusEvent ):void { trace("Flash focus out"); var textfield:TextField = event.target as TextField; textfield.backgroundColor = 0xffffff; } } }

Captura de bitmap
Um objeto StageWebView renderizado acima de todo o contedo da lista de exibio. No possvel adicionar um contedo acima do objeto StageWebView. Por exemplo, no possvel expandir uma lista suspensa sobre o contedo de StageWebView. Para solucionar esse problema, faa a captura de um instantneio de StageWebView. Em seguida, oculte o StageWebView e adicione o instantneio em bitmap em seu lugar. O exemplo a seguir ilustra como capturar o instantneo de um objeto StageWebView usandop o mtodo drawViewPortToBitmapData. Ele oculta o objeto StageWebView definido o palco como null. Depois que a pgina da Web estiver totalmetne carregada, chame uma funo que captura o bitmap e o exibe. Quando executado, o cdigo exibe dois rtulos, Google e Facebook. Clicar no rtulo captura a pgina da Web correpondente e a exibe como um instantneo no palco.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Exibio de contedo HTML em aplicativos mveis

1023

package { import flash.display.Bitmap; import flash.display.BitmapData; import flash.display.Sprite; import flash.events.*; import flash.geom.Rectangle; import flash.media.StageWebView; import flash.net.*; import flash.text.TextField; public class stagewebview extends Sprite { public var webView:StageWebView=new StageWebView(); public var textGoogle:TextField=new TextField(); public var textFacebook:TextField=new TextField(); public function stagewebview() { textGoogle.htmlText="<b>Google</b>"; textGoogle.x=300; textGoogle.y=-80; addChild(textGoogle); textFacebook.htmlText="<b>Facebook</b>"; textFacebook.x=0; textFacebook.y=-80; addChild(textFacebook); textGoogle.addEventListener(MouseEvent.CLICK,goGoogle); textFacebook.addEventListener(MouseEvent.CLICK,goFaceBook); webView.stage = this.stage; webView.viewPort = new Rectangle(0, 0, stage.stageWidth, stage.stageHeight); } public function goGoogle(e:Event):void { webView.loadURL("http://www.google.com"); webView.stage = null; webView.addEventListener(Event.COMPLETE,handleLoad); } public function goFaceBook(e:Event):void { webView.loadURL("http://www.facebook.com"); webView.stage = null; webView.addEventListener(Event.COMPLETE,handleLoad); } public function handleLoad(e:Event):void { var bitmapData:BitmapData = new BitmapData(webView.viewPort.width, webView.viewPort.height); webView.drawViewPortToBitmapData(bitmapData); var webViewBitmap:Bitmap=new Bitmap(bitmapData); addChild(webViewBitmap); } } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Exibio de contedo HTML em aplicativos mveis

1024

Exibindo anncios
Voc pode usar a classe StageWebView para exibir anncios dos servios de anncio que fornecem uma interface para o JavaScript/HTML. Defina a porta de visualizao do objeto StageWebView para cobrir a rea do seu aplicativo na qual voc deseja exibir o anncio. Em seguida, carregue uma pgina HTML que contenha o cdigo para solicitar e exibir anncios. O exemplo a seguir mostra uma pgina HTML que carrega a biblioteca Admob JavaScript e solicita a exibio de um anncio. Um mecanismo semelhante funciona para outros servios de anncio. Para solicitar anncios de teste uniformes com este exemplo, primeiro voc deve se conectar a sua conta do Admob e atribuir o ID do seu publicador Admob varivel pubid.
<html> <head> <title>Ad jig</title> <script type="text/javascript"> var admob_vars = { pubid: 'admob_pubID', // change to your publisher id bgcolor: 'ffffff', // background color (hex) text: '000000', // font-color (hex) test: true, // test mode, set to false if non-test mode manual_mode: true }; function showAd() { _admob.fetchAd(document.getElementById('adspace')); } </script> <script type="text/javascript" src="http://mm.admob.com/static/iphone/iadmob.js"></script> <style type="text/css"> body { margin-left: 0px; margin-top: 0px; margin-right: 0px; margin-bottom: 0px; } </style> </head> <body onload="showAd()"> <div id="adspace"></div> </body> </html>

O seguinte cdigo do ActionScript exibe uma pgina de anncio num aplicativo mvel do AIR. O exemplo formatado para o uso em toda a vida til do Flash Professional. Se voc estiver usando o Flash Builder ou criando uma classe ter que adaptar o exemplo de cdigo acordemente. Quando o usurio tocar em um anncio, voc poder exibir a pgina de destino do anncio no seu aplicativo ou usar navigateToURL() para exibir a pgina de destino no navegador web do dispositivo. Este exemplo usa navigateToURL(), que funciona com os links http: e market:.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Exibio de contedo HTML em aplicativos mveis

1025

Nos dispositivos mveis, o controle da web subjacente processa as alteraes de local iniciadas por cdigo para conhecer os esquemas de URI sem despachar um evento locationChanging. Uma vez que a API Admob JavaScript API altera o local da pgina, o exemplo processa tanto o evento locationChanging quanto o evento locationChange para que o aplicativo possa tomar a ao adequada, independentemente do local das mudanas no objeto StageWebView. Um evento locationChanging pode ser cancelado, de modo que o exemplo chame o evento do mtodo preventDefault() e inicie o navegador web do dispositivo com base na propriedade location do evento. Um evento locationChange no pode ser cancelado. Nesse caso, o exemplo inicia o novo local usando navigateToURL() e recarrega a pgina de exibio do anncio.
//Set up web view object var webView:StageWebView = new StageWebView(); webView.stage = this.stage; var adViewPort = new Rectangle( 0, 0, this.stage.stageWidth, 60 ); webView.viewPort = adViewPort; webView.addEventListener(ErrorEvent.ERROR, onWebViewError ); webView.addEventListener(LocationChangeEvent.LOCATION_CHANGING, onWebViewLocChanging ); webView.addEventListener(LocationChangeEvent.LOCATION_CHANGE, onWebViewLocChange ); //Copy the html file outside the app directory var templateFile:File = File.applicationDirectory.resolvePath( "adview.html" ); var workingFile:File = File.createTempFile(); templateFile.copyTo( workingFile, true ); try { webView.loadURL( workingFile.url ); } catch (e:Error) { trace( e ); } function onWebViewLocChange( event:LocationChangeEvent ):void { trace( "Change to" + event.location ); if( event.location != workingFile.url ) { //Reset location back to our ad display page navigateToURL( new URLRequest( event.location ) ); try {

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Exibio de contedo HTML em aplicativos mveis

1026

webView.loadURL( workingFile.url ); } catch (e:Error) { trace( e ); } } } function onWebViewLocChanging( event:LocationChangeEvent ):void { trace( "Changing " + event.location ); event.preventDefault(); navigateToURL( new URLRequest( event.location ) ); } function onWebViewError( error:ErrorEvent ):void { trace( error ); }

Nota: O exemplo no funciona em aplicativos de desktop ou em testes de aplicativos mveis no desktop, devido a restries de segurana local-versus-remota. No desktop, o objeto StageWebView tem restries de segurana apropriadas a um sistema operacional de desktop. Nos dispositivos mveis, o objeto StageWebView usa o controle de web padro e as restries de segurana impostas pelo sistema operacional mvel. Nesse caso, um arquivo carregado localmente (adview.html) pode acessar recursos remotos o servio de anncio num dispositivo mvel, mas no no desktop.

ltima atualizao em 29/3/2011

1027

Captulo 60: Segurana

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Segurana uma preocupao principal da Adobe, dos usurios, dos proprietrios de site e dos desenvolvedores de contedo. Por esta razo, o Adobe Flash Player e o Adobe AIR incluem um conjunto de regras e controles de segurana para proteger o usurio, o proprietrio do site e o desenvolvedor do contedo. Esta discusso abrange o modelo de segurana dos arquivos SWF publicados com o ActionScript 3.0 e executados no Flash Player 9.0.124.0 ou posterior, alm de arquivos SWF, HTML e JavaScript executados no AIR 1.0 ou posterior, salvo indicado de outra forma. Esta discusso fornece uma viso geral de segurana; ele no tenta explicar de maneira abrangente todos os detalhes de implementao, cenrios de uso ou ramificaes do uso de determinadas APIs. Para obter uma discusso mais detalhada sobre conceitos de segurana do Flash Player, consulte o tpico Segurana do Centro de desenvolvedores do Flash Player, em www.adobe.com/go/devnet_security_br.

Viso geral da segurana da Plataforma Flash

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Uma boa parte do modelo de segurana utilizado pelos aplicativos Flash Player e AIR tem por base o domnio de origem dos arquivos SWF, HTML, mdias e outros recursos carregados. Cdigo executvel em um arquivo de um domnio especfico da Internet, como www.example.com, sempre pode acessar todos os dados daquele domnio. Esses ativos so colocados no mesmo agrupamento de segurana, conhecido como uma caixa de proteo de segurana. (Para obter mais informaes, consulte Caixas de proteo de segurana na pgina 1029.) Por exemplo, um cdigo do ActionScript em um arquivo SWF pode carregar arquivos SWF, bitmaps, udio, arquivos de texto e qualquer outro ativo do seu prprio domnio. Alm disso, o cruzamento de scripts entre dois arquivos do mesmo domnio sempre permitido, desde que os dois arquivos sejam escritos usando o ActionScript 3.0. O Crossscripting a capacidade do cdigo de um arquivo de usar o ActionScript para acessar propriedades, mtodos e objetos definidos pelo cdigo em outro arquivo SWF. O cross-scripting no suportado entre arquivos SWF escritos usando o ActionScript 3.0 e verses anteriores do ActionScript. No entanto esses arquivos podem se comunicar usando a classe LocalConnection. Alm disso, a capacidade de um arquivo SWF de executar cross-script de arquivos SWF do ActionScript 3.0 de outros domnios e de carregar dados de outros domnios proibida por padro. No entanto esse acesso pode ser concedido com uma chamada para o mtodo Security.allowDomain() no arquivo SWF carregado. Para obter mais informaes, consulte Cross-scripting na pgina 1048. Por padro, as seguintes regras bsicas de segurana sempre se aplicam:

Recursos na mesma caixa de proteo de segurana sempre podem acessar um ao outro. Cdigo executvel em arquivos em uma caixa de proteo remota nunca acessam arquivos e dados locais.
Os aplicativos Flash Player e AIR consideram o seguinte como domnios individuais, e criam caixas de proteo individuais para cada um:

http://example.com http://www.example.com

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1028

http://store.example.com https://www.example.com http://192.0.34.166

Mesmo que um domnio nomeado, como http://example.com, mapeie para um endereo IP especfico, como http://192.0.34.166, o aplicativo criar caixas de proteo de segurana separadas para cada um. Existem dois mtodos bsicos que podem ser usados por um desenvolvedor para conceder acesso a um arquivo SWF a ativos das caixas de proteo diferente daquela do arquivo SWF:

O mtodo Security.allowDomain() (consulte Controles de autor (desenvolvedor) na pgina 1041) O arquivo de poltica da URL (consulte Controles de site (arquivos de poltica) na pgina 1037)
Nos modelos de segurana do Flash Player e do aplicativo AIR, h uma distino entre carregamento de contedo e extrao ou acesso a dados. Content definido como mdia, incluindo mdia visual que o aplicativo pode exibir, udio, vdeo ou um arquivo SWF ou HTML que inclui mdia exibida. Data definido como algo que acessvel apenas ao cdigo Content e data so carregados de maneiras diferentes.

Carregamento de contedo Voc pode carregar contedos utilizando classes, tais como Loader, Sound e
NetStream; atravs de marcas MXML ao usar o Flex; ou atravs de marcas HTML em um aplicativo AIR.

Extrao de dados possvel extrair dados de contedo de mdia carregada usando objetos Bitmap, o mtodo
BitmapData.draw(), a propriedade Sound.id3 ou o mtodo SoundMixer.computeSpectrum().

Acesso a dados possvel acessar dados diretamente carregando-os de um arquivo externo (como um arquivo
XML) usando classes, como as classes URLStream, URLLoader, FileReference, Socket e XMLSocket. O AIR oferece mais classes para carregamento de dados, tais como FileStream e XMLHttpRequest. O modelo de segurana do Flash Player define diferentes regras para carregamento de contedo e acesso a dados. Em geral, h menos restries no carregamento de contedo do que no acesso a dados. Em geral, o contedo (arquivos SWF, bitmaps, arquivos mp3 e vdeos) pode ser carregado a partir de qualquer local, mas se o contedo for de um domnio diferente daquele do arquivo cdigo ou contedo carregado, ele ser particionado em uma caixa de proteo de segurana separada. H algumas barreiras no que diz respeito ao carregamento de contedo:

Por padro, arquivos SWF locais (carregados de um endereo que no seja da rede, como do disco rgido de um
usurio) so classificados na caixa de proteo local com sistema de arquivos. Esses arquivos no podem carregar contedo da rede. Para obter mais informaes, consulte Caixas de proteo locais na pgina 1029.

Servidores de protocolo RTMP podem limitar o acesso ao contedo. Para obter mais informaes,
consulteContedo entregue usando servidores RMTP na pgina 1048. Se a mdia carregada for uma imagem, udio ou vdeo, seus dados, como dados de pixel e dados de som, podero ser acessados por um arquivo SWF fora de sua caixa de proteo de segurana apenas se o domnio daquele arquivo SWF tiver sido includo em um arquivo de poltica de URL no domnio de origem da mdia. Para obter detalhes, consulte Acesso mdia carregada como dados na pgina 1052. Outras formas de dados carregados incluem arquivos de texto ou XML que so carregados com um objeto URLLoader. Novamente nesse caso, para acessar quaisquer dados de outra caixa de proteo de segurana, permisso deve ser concedida por meio de um arquivo de poltica de URL no domnio de origem. Para obter detalhes, consulte Uso de URLLoader e URLStream na pgina 1054. Nota: Os arquivos de Poltica nunca so obrigatrios para os cdigos executados na caixa de proteo do aplicativo AIR para carregar contedos ou dados remotos.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1029

Caixas de proteo de segurana

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os computadores clientes podem obter arquivos individuais que contm cdigo, contedo e dados de vrias fontes, como sites externos, um sistema local de arquivos ou de um aplicativo AIR instalado. Os aplicativos Flash Player e AIR atribuem arquivos de cdigo e outros recursos individualmente, como objetos compartilhados, bitmaps, sons, vdeos e arquivos de dados, a caixas de proteo de segurana com base em sua origem quando eles so carregadas. As sees a seguir descrevem as regras aplicadas pelos aplicativos que controlam o que um cdigo ou contedo dentro de uma determinada caixa de proteo pode acessar. Para obter mais informaes sobre a segurana do Flash Player, consulte o tpico Segurana do Centro de desenvolvedores do Flash Player, em www.adobe.com/go/devnet_security_br.

Caixas de proteo remotas

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Os aplicativos Flash Player e AIR classificam os recursos (inclusive arquivos SWF) da Internet em caixas de proteo separadas que correspondem ao seu domnio de origem. Por exemplo, os recursos carregados de example.com sero colocados em uma caixa de proteo diferente dos recursos carregados de foo.org. Por padro, esses arquivos tm permisso para acessar quaisquer recursos de seu prprio servidor. Arquivos SWF remotos podem receber permisso para acessar dados adicionais de outros domnios por permisses explcitas de autor e de site, como arquivos de poltica de URL e o mtodo Security.allowDomain(). Para obter detalhes, consulte Controles de site (arquivos de poltica) na pgina 1037 eControles de autor (desenvolvedor) na pgina 1041. Arquivos SWF remotos no podem carregar nenhum recurso ou arquivo local. Para obter mais informaes sobre a segurana do Flash Player, consulte o tpico Segurana do Centro de desenvolvedores do Flash Player, em www.adobe.com/go/devnet_security_br.

Caixas de proteo locais

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Arquivo local descreve qualquer arquivo que referenciado usando o protocolo file: ou um caminho UNC (Conveno de nomenclatura universal). Arquivos SWF locais so colocados em uma de quatro caixas de proteo locais:

A caixa de proteo local com sistema de arquivos Por motivo de segurana, os aplicativos Flash Player e AIR
colocam todos os arquivos locais na caixa de proteo local com sistema de arquivos (padro). Nessa caixa de proteo, os cdigos executveis podem ler arquivos locais (usando a classe URLLoader, por exemplo), mas no podem se comunicar com a rede de nenhuma maneira. Isso garante ao usurio que os dados locais no podem ser vazados para a rede ou, de outra forma, compartilhados de maneira inadequada.

A caixa de proteo local com a rede ao compilar um arquivo SWF, possvel especificar que ele tem acesso
rede quando executado como um arquivo local (consulte Configurao de tipo de caixa de proteo de arquivos SWF locais na pgina 1032). Esses arquivos so colocados na caixa de proteo local com a rede. Arquivos SWF que so atribudos caixa de proteo local com a rede perdem o acesso a seus arquivos locais. Em troca, os arquivos SWF tm permisso para acessar dados da rede. No entanto um arquivo SWF local com a rede ainda no tem permisso para ler nenhum dado derivado da rede a menos que permisses estejam presentes para aquela ao, por

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1030

meio de um arquivo de poltica de URL ou de uma chamada ao mtodo Security.allowDomain(). Para conceder essa permisso, um arquivo de poltica de URL deve conceder permisso a todos os domnios usando <allowaccess-from domain="*"/> ou usando Security.allowDomain("*"). Para obter informaes, consulteControles de site (arquivos de poltica) na pgina 1037 eControles de autor (desenvolvedor) na pgina 1041.

A caixa de proteo local confivel arquivos SWF locais que esto registrados como confiveis (pelos usurios
ou pelos programas instaladores) so colocados na caixa de proteo local confivel. Administradores do sistema e usurios tambm tm a capacidade de reatribuir (mover) um arquivo SWF local para ou de um caixa de proteo local confivel com base em consideraes de segurana (consulteControles de administrador na pgina 1034 e Controles de usurio na pgina 1035). Arquivos SWF atribudos caixa de proteo local confivel podem interagir com quaisquer outros arquivos SWF e carregar dados de qualquer lugar (remoto ou local).

A caixa de proteo do aplicativo AIR esta caixa de proteo contm contedo instalado com o aplicativo AIR
em execuo. Por padro, o cdigo executado na caixa de proteo do aplicativo AIR podem realizar o cruzamento de scripts de cdigos em qualquer domnio. No entanto, arquivos fora da caixa de proteo do aplicativo AIR no tm permisso para executar o cruzamento de scripts de cdigos na caixa de proteo do aplicativo. Por padro, o cdigo e o contedo na caixa de proteo do aplicativo AIR podem carregar contedo e dados de qualquer domnio. A comunicao entre as caixas de proteo local com rede e local com sistema de arquivos, bem como a comunicao entre as caixas de proteo remota e local com sistema de arquivos, estritamente proibida. Permisso para essa comunicao no pode ser concedida por um aplicativo executado no Flash Player ou por um usurio ou administrador. Script em qualquer direo entre arquivos HTML locais e arquivos SWF locais, por exemplo, usando a classe ExternalInterface, exige que tanto os arquivos HTML quanto os arquivos SWF envolvidos estejam na caixa de proteo local confivel. Isso ocorre porque os modelos de segurana locais de navegadores diferem do modelo de segurana local do Flash Player. Arquivos SWF na caixa de proteo local com rede no podem carregar arquivos SWF na caixa de proteo local com sistema de arquivos. Arquivos SWF na caixa de proteo local com sistema de arquivos no podem carregar arquivos SWF na caixa de proteo local com rede.

A caixa de proteo do aplicativo AIR

Adobe AIR 1.0 e posterior O aplicativo Adobe AIR acrescenta uma caixa de proteo a mais, chamada application, ao modelo de caixa de proteo de segurana do Flash Player. Os arquivos instalados como parte de um aplicativo AIR so carregados na caixa de proteo do aplicativo. Qualquer outro arquivo carregado pelo aplicativo ter restries de segurana correspondentes quelas especificadas pelo modelo normal de segurana do Flash Player. Quando um aplicativo for instalado, todos os arquivos includos em um pacote do AIR so instalados em um diretrio do aplicativo no computador do usurio. Os desenvolvedores podem fazer referncia a esse diretrio no cdigo por meio do esquema de URL app:/ (consulte Esquemas de URI na pgina 803). Todos os arquivos na rvore de diretrio do aplicativo so atribudos caixa de proteo do aplicativo quando o aplicativo executado. O contedo na caixa de proteo do aplicativo agraciado com os privilgios completos disponveis para o aplicativo AIR , incluindo interao com o sistema de arquivos local.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1031

Muitos dos aplicativos AIR s usam esses arquivos instalados localmente para executar o aplicativo. No entanto, os aplicativos AIR no esto restritos apenas aos arquivos no diretrio do aplicativo - eles podem carregar qualquer tipo de arquivo de qualquer fonte. Isso inclui arquivos locais do computador do usurio, bem como arquivos de fontes externas disponveis, como aqueles em uma rede local ou na Internet. O tipo de arquivo no tem nenhum impacto nas restries de segurana, os arquivos HTML carregados tm os mesmos privilgios de segurana dos arquivos SWF carregados da mesma fonte. O contedo na caixa de proteo de segurana do aplicativo tem acesso as APIs do AIR que o contedo de outras caixas de proteo no pode usar. Por exemplo, a propriedade air.NativeApplication.nativeApplication.applicationDescriptor, que retorna o contedo do arquivo descritor do aplicativo para o aplicativo, est restrita ao contedo na caixa de proteo de segurana do aplicativo. Outro exemplo de API restrita a classe FileStream, que contm mtodos de leitura e gravao no sistema de arquivos local. As APIs do ActionScript disponveis apenas para o contedo na caixa de proteo de segurana do aplicativo so indicadas com o logotipo do AIR na Referncia do ActionScript 3.0 para a plataforma Adobe Flash. Usar essas APIs em outras caixas de proteo faz com que o tempo de execuo lance uma exceo SecurityError. No contedo HTML (em um objeto HTMLLoader), todas as APIs JavaScript do AIR (aquelas que esto disponveis atravs da propriedade window.runtime ou atravs do objeto air durante o uso do arquivo AIRAliases.js) esto disponveis para o contedo na caixa de proteo de segurana do aplicativo. O contedo HTML de outra caixa de proteo no tem acesso propriedade window.runtime, portanto, esse contedo no pode acessar as APIs do AIR ou do Flash Player. Os contedos executados na caixa de proteo do aplicativo AIR tm as seguintes restries a mais:

Para contedo HTML na caixa de proteo de segurana do aplicativo, h limitaes de uso de APIs que possam
transformar dinamicamente as strings em cdigo executvel, aps o cdigo ser carregado. Isso para evitar que o aplicativo injete inadvertidamente (e execute) cdigo de fontes "no-aplicativo" (como domnios de rede potencialmente inseguros). Um exemplo o uso da funo eval(). Para obter detalhes, consulte Restries de cdigo de contedo em caixas de proteo distintas na pgina 1070.

Para evitar possveis ataques de phishing, as tags img de contedo HTML nos objetos TextField do ActionScript so
ignoradas no contedo SWF na caixa de proteo de segurana do aplicativo.

O contedo na caixa de proteo do aplicativo no pode usar o protocolo asfunction do contedo HTML nos
campos de texto do ActionScript 2.0.

O contedo SWF na caixa de proteo do aplicativo no pode usar o cache entre domnios, um recurso que foi
adicionado Atualizao 3 do Flash Player 9. Esse recurso permite que o Flash Player persista em colocar em cache o contedo de componente da plataforma Adobe e reutilize-o no contedo SWF carregado sob demanda (eliminando a necessidade de recarregar o contedo vrias vezes).

Restries a JavaScript dentro do AIR

Adobe AIR 1.0 e posterior Ao contrrio do contedo na caixa de proteo de segurana do aplicativo, o contedo JavaScript em uma caixa de proteo de segurana que no seja de aplicativo pode chamar a funo eval() para executar cdigo gerado dinamicamente a qualquer momento. Entretanto, existem restries a JavaScript executado em uma caixa de proteo de segurana que no seja de aplicativo dentro do AIR. Isso inclui:

O cdigo JavaScript em uma caixa de proteo "no-aplicativo" no tem acesso ao objeto window.runtime e,
portanto, esse cdigo no pode executar APIs do AIR.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1032

Por padro, o contedo em uma caixa de proteo de segurana "no-aplicativo" no pode usar chamadas
XMLHttpRequest para carregar dados de outros domnios diferentes do domnio que chama a solicitao. Entretanto, o cdigo do aplicativo pode conceder permisso para que o contedo "no-aplicativo" faa isso, definindo um atributo allowCrossdomainXHR no frame ou iframe que o contm. Para obter mais informaes, consulte Restries de cdigo de contedo em caixas de proteo distintas na pgina 1070.

H restries na chamada do mtodo window.open() de JavaScript. Para obter detalhes, consulte Restries na
chamada do mtodo window.open() de JavaScript na pgina 1073.

O contedo HTML nas caixas de proteo de segurana remota (rede) pode carregar apenas contedo CSS, frame,
iframe e img de domnios remotos (de URLs de rede).

O contedo HTML nas caixas de proteo local com sistema de arquivos, local com rede ou local confivel s
podem carregar contedo CSS, frame, iframe e img de caixas de proteo locais (e no de URLs de aplicativo ou de rede). Para obter detalhes, consulte Restries de cdigo de contedo em caixas de proteo distintas na pgina 1070.

Configurao de tipo de caixa de proteo de arquivos SWF locais

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Um usurio final ou o administrador de um computador pode especificar que um arquivo SWF local confivel, permitindo que ele carregue dados de todos os domnios, tanto locais quanto de rede. Isso especificado nos diretrios Global Flash Player Trust e User Flash Player Trust. Para obter mais informaes, consulte Controles de administrador na pgina 1034 e Controles de usurio na pgina 1035. Para obter mais informaes sobre caixas de proteo locais, consulte Caixas de proteo locais na pgina 1029. Adobe Flash Professional possvel configurar um arquivo SWF para a caixa de proteo local com sistema de arquivos ou a caixa de proteo local com rede definindo-se as configuraes de publicao do documento na Ferramenta de autoria.

Adobe Flex possvel configurar um arquivo SWF para a caixa de proteo local com sistema de arquivos ou a caixa de proteo local com rede configurando o sinalizador use-network no compilador do Adobe Flex. Para obter mais informaes, consulte Sobre as opes do compilador do aplicativo em Criao e implantao de aplicativos do Adobe Flex 3.

A propriedade Security.sandboxType
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Um autor de um arquivo SWF pode usar a propriedade esttica somente leitura Security.sandboxType para determinar o tipo de caixa de proteo qual o aplicativo Flash Player ou AIR atribuiu o arquivo SWF. A classe Security inclui constantes que representam valores possveis da propriedade Security.sandboxType, da seguinte maneira:

Security.REMOTE o arquivo SWF proveniente de uma URL da Internet e opera de acordo com as regras da

caixa de proteo com base em domnio.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1033

Security.LOCAL_WITH_FILE o arquivo SWF um arquivo local, mas no foi considerado como confivel pelo

usurio e no foi publicado com uma designao de rede. O arquivo SWF pode ler de fontes de dados locais, mas no pode se comunicar com a Internet.

Security.LOCAL_WITH_NETWORK o arquivo SWF um arquivo local e no foi considerado como confivel pelo

usurio, mas foi publicado com uma designao de rede. O arquivo SWF pode se comunicar com a Internet mas no pode ler de fontes de dados locais.

Security.LOCAL_TRUSTED o arquivo SWF um arquivo local e foi considerado como confivel pelo usurio, seja usando o Gerenciador de configuraes ou um arquivo de configurao de confiana do Flash Player. O arquivo SWF pode ler de fontes de dados locais e se comunicar com a Internet. Security.APPLICATION o arquivo SWF est em execuo em um aplicativo AIR e foi instalado com o pacote

(arquivo AIR) daquele aplicativo. Por padro, os arquivos na caixa de proteo do aplicativo AIR podem executar cross-script de qualquer arquivo em qualquer domnio. No entanto, arquivos fora da caixa de proteo do aplicativo AIR no tm permisso para executar cross-script no arquivo AIR. Por padro, os arquivos na caixa de proteo do aplicativo AIR podem carregar contedo e dados de qualquer domnio.

Controles de permisso
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O modelo de segurana de tempo de execuo do cliente Flash Player foi designado em torno de recursos que so objetos, como arquivos SWF, dados locais e URLs da Internet. Participantes so as partes que so as proprietrias ou que usam esses recursos. Os participantes podem exercer controles (configuraes de segurana) sobre seus prprios recursos e cada recurso tem quatro participantes. O Flash Player refora estritamente uma hierarquia de autoridade para esses controles, conforme mostrado na ilustrao a seguir:
Configuraes do administrador (Instituio do usurio)

Configuraes do usurio

Configuraes do site

Configuraes do autor

Hierarquia de controles de segurana

Isso significa, por exemplo, que se um administrador restringir o acesso a um recurso, nenhum outro participante poder substituir essa restrio. Nos aplicativos AIR, esses controles de permisso valem apenas para os contedos executados fora da caixa de proteo do aplicativo AIR.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1034

Controles de administrador
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Um usurio administrativo de um computador (um usurio que fez logon com direitos administrativos) pode aplicar configuraes de segurana do Flash Player que afetam todos os usurios do computador. Em um ambiente no empresarial, como em um computador domstico, normalmente h um usurio que tambm tem acesso administrativo. Mesmo em um ambiente empresarial, usurios individuais podem ter direitos administrativos no computador. H dois tipos de controles de usurio administrativo:

O arquivo mms.cfg O diretrio Global Flash Player Trust

O arquivo mms.cfg
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O arquivo mms.cfg um arquivo de texto que permite que os administradores ativem ou restrinjam o acesso a vrios recursos. Quando o Flash Player iniciado, l as configuraes de segurana desse arquivo e as usa para limitar a funcionalidade. O arquivo mms.cfg inclui configuraes que o administrador usa para gerenciar recursos, como controles de privacidade, segurana de arquivo local, conexes de soquete, entre outros. Um arquivo SWF pode acessar algumas informaes sobre capacidades que foram desativadas chamando as propriedades Capabilities.avHardwareDisable e Capabilities.localFileReadDisable. No entanto a maioria das configuraes no arquivo mms.cfg no podem ser consultadas no ActionScript. Para reforar as polticas de segurana e de privacidade independentemente do aplicativo para um computador, o arquivo mms.cfg deve ser modificado apenas por administradores do sistema. O arquivo mms.cfg no deve ser usado por instaladores de aplicativos. Embora um instalador que executa com privilgios administrativos possa modificar o contedo do arquivo mms.cfg, a Adobe considera esse uso como uma violao da confiana do usurio e recomenda que os criadores de instaladores nunca modifiquem o arquivo mms.cfg. O arquivo mms.cfg armazenado no seguinte local:

Windows: system\Macromed\Flash\mms.cfg
(por exemplo, C:\WINDOWS\system32\Macromed\Flash\mms.cfg)

Mac: app support/Macromedia/mms.cfg

(por exemplo, /Library/Application Support/Macromedia/mms.cfg) Para obter mais informaes sobre o arquivo mms.cfg, consulte o Guia de administrao do Flash Player, em www.adobe.com/go/flash_player_admin_br.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1035

O diretrio Global Flash Player Trust

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Usurios administrativos e aplicativos de instalador podem registrar arquivos SWF locais especificados como confiveis para todos os usurios. Esses arquivos SWF so atribudos caixa de proteo local confivel. Eles podem interagir com quaisquer outros arquivos SWF e podem carregar dados de qualquer lugar remoto ou local. Os arquivos so designados como confiveis no diretrio Global Flash Player Trust, no seguinte local:

Windows: system\Macromed\Flash\FlashPlayerTrust
(por exemplo, C:\WINDOWS\system32\Macromed\Flash\FlashPlayerTrust)

Mac: app support/Macromedia/FlashPlayerTrust

(por exemplo, /Library/Application Support/Macromedia/FlashPlayerTrust) O diretrio Flash Player Trust pode conter qualquer nmero de arquivos de texto, cada um dos quais lista caminhos confiveis, com um caminho por linha. Cada caminho pode ser um arquivo SWF individual, um arquivo HTML ou um diretrio. Linhas de comentrios comeam com o smbolo #. Por exemplo, um arquivo de configurao de confiana do Flash Player que contm o texto a seguir concede status confivel a todos os arquivos no diretrio especificado e em todos os subdiretrios:
# Trust files in the following directories: C:\Documents and Settings\All Users\Documents\SampleApp

Os caminhos listados em um arquivo de configurao de confiana devem sempre ser caminhos locais ou caminhos de rede SMB. Qualquer caminho HTTP em um arquivo de configurao confivel ignorado. Apenas arquivos locais podem ser confiveis. Para evitar conflitos, d a cada arquivo de configurao confivel um nome de arquivo correspondente ao aplicativo de instalao e use uma extenso de arquivo .cfg. Como um desenvolvedor que distribui um arquivo SWF executado localmente por meio de um aplicativo instalador, possvel fazer com que o aplicativo instalador adicione um arquivo de configurao ao diretrio Global Flash Player Trust, concedendo privilgios totais ao arquivo que voc est distribuindo. O aplicativo instalador deve ser executado por um usurio com direitos administrativos. Ao contrrio do arquivo ms.cfg, o diretrio Global Flash Player Trust includo com o objetivo de aplicativos instaladores concederem permisses de confiana. Os usurios administrativos e os aplicativos instaladores podem designar aplicativos locais confiveis usando o diretrio Global Flash Player Trust. Tambm h diretrios Flash Player Trust para usurios individuais (consulte Controles de usurio na pgina 1035).

Controles de usurio
Flash Player 9 e posterior O Flash Player fornece trs mecanismos diferentes em nvel de usurio para definir permisses: a UI de Configuraes, o Gerenciador de configuraes e o diretrio User Flash Player Trust.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1036

A UI de Configuraes e o Gerenciador de configuraes

Flash Player 9 e posterior A UI de Configuraes um mecanismo rpido e interativo para definir as configuraes de um domnio especfico. O Gerenciador de configuraes tem uma interface mais detalhada e permite fazer alteraes globais que afetam as permisses de muitos ou de todos os domnios. Alm disso, quando um arquivo SWG solicita uma nova permisso, exigindo a tomada de decises relativas a segurana ou privacidade durante a execuo, so exibidas caixas de dilogo nas quais os usurios podem ajustar algumas configuraes do Flash Player. O Gerenciador de Configuraes e a UI de Configuraes oferecem opes relacionadas a segurana, como configuraes de cmera e microfone, configuraes de armazenamento de objetos compartilhados, configuraes relacionadas a contedo pr-existente etc. Nem o Gerenciador de Configuraes, nem a UI de Configuraes esto disponveis para os aplicativos AIR. Nota: Qualquer configurao feita no arquivo mms.cfg (consulte Controles de administrador na pgina 1034) no refletida no Gerenciador de configuraes. Para obter detalhes sobre o Gerenciador de configuraes, consulte www.adobe.com/go/settingsmanager_br.

O diretrio User Flash Player Trust

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Usurios e aplicativos instaladores podem registrar arquivos SWF locais como confiveis. Esses arquivos SWF so atribudos caixa de proteo local confivel. Eles podem interagir com quaisquer outros arquivos SWF e podem carregar dados de qualquer lugar remoto ou local. Um usurio designa um arquivo como confivel no diretrio User Flash Player Trust, que est no mesmo diretrio que a rea de armazenamento de objetos compartilhados, nos seguintes locais (os locais so especficos do usurio atual):

Windows: app data\Macromedia\Flash Player\#Security\FlashPlayerTrust

(por exemplo, C:\Documents and Settings\JohnD\Application Data\Macromedia\Flash Player\#Security\FlashPlayerTrust no Windows XP ou C:\Users\JohnD\AppData\Roaming\Macromedia\Flash Player\#Security\FlashPlayerTrust no Windows Vista) No Windows, a pasta Application Data fica ocultada por padro. Para mostrar pastas e arquivos ocultos, selecione Meu computador para abrir o Windows Explorer, selecione Ferramentas > Opes de pasta e selecione a aba Exibir. Na aba Exibir, selecione o boto de opo Mostrar pastas e arquivos ocultos.

Mac: app data/Macromedia/Flash Player/#Security/FlashPlayerTrust

(por exemplo, /Users/JohnD/Library/Preferences/Macromedia/Flash Player/#Security/FlashPlayerTrust) Essas configuraes afetam apenas o usurio atual, no outros usurios que fazem logon no computador. Se um usurio sem direitos administrativos instalar um aplicativo em sua prpria parte do sistema, o diretrio User Flash Player Trust permitir que o instalador registre o aplicativo como confivel para aquele usurio. Como um desenvolvedor que distribui um arquivo SWF executado localmente por meio de um aplicativo instalador, voc pode fazer com que o aplicativo instalador adicione um arquivo de configurao ao diretrio User Flash Player Trust, concedendo privilgios totais ao arquivo que est distribuindo. Mesmo nessa situao, o arquivo do diretrio User Flash Player Trust considerado um controle de usurio, porque uma ao do usurio (instalao) o inicia. Tambm existe um diretrio Global Flash Player Trust, usado pelo usurio administrativo ou por instaladores para registrar um aplicativo para outros usurios de um computador (consulte Controles de administrador na pgina 1034).

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1037

Controles de site (arquivos de poltica)

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para disponibilizar dados do servidor Web para arquivos SWF de outros domnios, crie um arquivo de poltica do servidor. Um arquivo de poltica um arquivo XML colocado em um local especfico no servidor. arquivos de poltica afetam o acesso a vrios ativos, incluindo os seguintes:

Dados em bitmaps, sons e vdeos Carregamento de arquivos de texto e XML Importao de arquivos SWF de outros domnios de segurana no domnio de segurana do arquivo SWF que est
sendo carregado

Acesso a soquete e conexes de soquete XML

Objetos ActionScript instanciam dois tipos diferentes de conexes de servidor: conexes de servidor com base em documento e conexes de soquete. Os objetos do ActionScript, como Loader, Sound, URLLoader e URLStream instanciam conexes de servidor com base em documento e esses objetos carregam um arquivo de uma URL. Os objetos Socket e XMLSocket do ActionScript fazem conexes de soquete que funcionam com fluxos de dados, no com documentos carregados. Como o Flash Player oferece suporte a dois tipos de conexes de servidor, h dois tipos de arquivos de poltica: arquivos de poltica de URL e arquivos de poltica de soquete.

Conexes com base em documento exigem arquivos de poltica de URL. Esses arquivos permitem que o servidor
indique que seus dados e documentos esto disponveis para arquivos SWF servidos em determinados domnios ou em todos os domnios.

Conexes de soquete exigem arquivos de poltica de soquetes que ativam a rede diretamente no nvel inferior do
soquete TCP usando as classes Socket e XMLSocket. O Flash Player exige que arquivos de poltica sejam transmitidos usando o mesmo protocolo que a tentativa de conexo quer usar. Por exemplo, quando voc coloca um arquivo de poltica no servidor HTTP, os arquivos SWF de outros domnios recebem permisso para carregar dados dele como um servidor HTTP. No entanto, se no fornecer um arquivo de poltica de soquete no mesmo servidor, voc estar proibindo que arquivos SWF de outros domnios se conectem ao servidor no nvel de soquete. Em outras palavras, o meio pelo qual um arquivo de poltica recuperado deve corresponder ao meio de conexo. O uso e a sintaxe do arquivo de poltica so discutidos brevemente no restante desta seo, pois eles se aplicam aos arquivos SWF publicados para o Flash Player 10. A implementao do arquivo de poltica um pouco diferente em verses anteriores do Flash Player, uma vez que verses sucessivas reforaram a segurana do Flash Player. Para obter informaes mais detalhadas sobre arquivos de poltica, consulte o tpico Alteraes em arquivos de poltica do Flash Player 9 do Centro de desenvolvedores do Flash Player, em www.adobe.com/go/devnet_security_br. O cdigo executado na caixa de proteo do aplicativo AIR no exige um arquivo de polticas para acessar dados em uma URL ou um soquete. O cdigo em um aplicativo AIR executado em uma caixa de proteo que no seja de um aplicativo exige um arquivo de polticas.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1038

arquivos de poltica mestre

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Por padro, primeiro o Flash Player (e o contedo AIR que no est na caixa de proteo do aplicativo AIR) procura um arquivo de poltica de URL denominado crossdomain.xml no diretrio raiz do servidor e procura um arquivo de poltica de soquete na porta 843. Um arquivo em um desses locais chamado de arquivo de poltica mestre. No caso de conexes de soquete, o Flash Player tambm procura um arquivo de poltica de soquete na mesma porta que a conexo principal. No entanto, um arquivo de poltica encontrado naquela porta no considerado um arquivo de poltica mestre. Alm de especificar permisses de acesso, o arquivo de poltica mestre tambm pode conter uma instruo metapolicy. Uma metapoltica especifica quais locais podem conter arquivos de poltica. A metapoltica padro dos arquivos de poltica de URL somente mestre, o que significa que /crossdomain.xml o nico arquivo de poltica permitido no servidor. A metapoltica padro para arquivos de poltica de soquete all, o que significa que qualquer soquete no host pode servir um arquivo de poltica de soquete. Nota: No Flash Player 9 e anterior, a metapoltica padro de arquivos de poltica de URL era all, o que significa que qualquer diretrio pode conter um arquivo de poltica. Se voc implantou aplicativos que carregam arquivos de poltica de locais diferentes do arquivo padro /crossdomain.xml e se esses aplicativos estiverem executando agora no Flash Player 10, verifique se voc (ou outro administrador do servidor) modificou o arquivo de poltica mestre para permitir arquivos de poltica adicionais. Para obter informaes sobre como especificar uma metapoltica diferente, consulte o tpico Alteraes em arquivos de poltica do Flash Player 9 do Centro de desenvolvedores do Flash Player, em www.adobe.com/go/devnet_security_br. Um arquivo SWF pode verificar se existe um nome de arquivo de poltica diferente ou um local de diretrio diferente chamando o mtodo Security.loadPolicyFile(). No entanto, se o arquivo de poltica mestre no especificar que o local de destino pode servir arquivos de poltica, a chamada para loadPolicyFile() no ter nenhum efeito, mesmo que haja um arquivo de poltica naquele local. Chame loadPolicyFile() antes de tentar qualquer operao de rede que exija o arquivo de poltica. O Flash Player enfileira automaticamente solicitaes de rede por trs de tentativas do arquivo de poltica correspondente. Portanto, aceitvel, por exemplo, chamar Security.loadPolicyFile() imediatamente antes de iniciar uma operao de rede. Ao verificar um arquivo de poltica mestre, o Flash Player aguarda trs segundos por uma resposta do servidor. Se uma resposta no for recebida, o Flash Player assumir que no existe nenhum arquivo de poltica. No entanto no h nenhum valor de tempo limite padro para chamadas para loadPolicyFile(). O Flash Player assume que o arquivo que est chamando existe, e aguarda quanto tempo for necessrio para carreg-lo. Portanto, para verificar se um arquivo de poltica mestre est carregado, use loadPolicyFile() para cham-lo explicitamente. Mesmo que o mtodo seja denominado Security.loadPolicyFile(), um arquivo de poltica no ser carregado at que uma chamada de rede que exija um arquivo de poltica seja emitida. Chamadas para loadPolicyFile() simplesmente informam ao Flash Player onde procurar por arquivos de poltica quando eles so necessrios. No possvel receber notificao de quando uma solicitao de arquivo de poltica iniciada ou concluda e no h motivo para isso. O Flash Player executa verificaes de polticas assincronamente e aguarda automaticamente para iniciar conexes at aps o xito das verificaes do arquivo de poltica. As sees a seguir contm informaes que se aplicam apenas a arquivos de poltica de URL. Para obter mais informaes sobre arquivos de poltica de soquete, consulte Conexo a soquetes na pgina 1055.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1039

Escopo do arquivo de poltica de URL

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O arquivo de poltica de URL se aplica apenas ao diretrio do qual ele carregado e a seus diretrios filho. Um arquivo de poltica no diretrio raiz se aplica ao todo o servidor. Um arquivo de poltica carregado de um subdiretrio arbitrrio aplica-se apenas quele diretrio e a seus subdiretrios. Um arquivo de poltica afeta o acesso somente ao servidor especfico onde ele reside. Por exemplo, um arquivo de poltica localizado em https://www.adobe.com:8080/crossdomain.xml aplica-se apenas a chamadas de carregamento de dados feitas para www.adobe.com por HTTPS na porta 8080.

Especificao de permisses de acesso em um arquivo de poltica de URL

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Um arquivo de poltica contm uma nica tag <cross-domain-policy> que, por sua vez, contm zero ou mais tags <allow-access-from>. Cada tag <allow-access-from> contm um atributo, domain, que especifica um endereo IP exato, um domnio exato ou um domnio curinga (qualquer domnio). Os domnios curinga so indicados de duas maneiras:

Por um nico asterisco (*), que corresponde a todos os domnios e a todos os endereos IP. Por um asterisco seguido por um sufixo, que corresponde apenas aos domnios que terminam com o sufixo
especificado. Sufixos devem comear com um ponto. No entanto domnios curinga com sufixos podem corresponder a domnios que consistem apenas no sufixo sem o ponto inicial. Por exemplo, xyz.com considerado como parte de *.xyz.com. Curingas no so permitidos em especificaes de domnios IP. O exemplo a seguir mostra um arquivo de poltica de URL que permite acesso a arquivos SWF originados de *.example.com, www.friendOfExample.com e 192.0.34.166:
<?xml version="1.0"?> <cross-domain-policy> <allow-access-from domain="*.example.com" /> <allow-access-from domain="www.friendOfExample.com" /> <allow-access-from domain="192.0.34.166" /> </cross-domain-policy>

Se voc especificar um endereo IP, o acesso ser concedido somente a arquivos SWF carregados daquele endereo IP usando a sintaxe IP (por exemplo, http://65.57.83.12/flashmovie.swf). O acesso no concedido a arquivos SWF que usam a sintaxe de nome de domnio. O Flash Player no executa resoluo de DNS. possvel permitir acesso a documentos originrios de qualquer domnio, conforme mostrado no exemplo a seguir:
<?xml version="1.0"?> <!-- http://www.foo.com/crossdomain.xml --> <cross-domain-policy> <allow-access-from domain="*" /> </cross-domain-policy>

Cada tag <allow-access-from> tambm tem o atributo opcional secure que padronizado como true. Se o arquivo de poltica estiver em um servidor HTTPS e voc quiser permitir que arquivos SWF em um servidor no-HTTPS carreguem dados do servidor HTTPS, poder definir o atributo como false.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1040

A configurao do atributo secure como false pode comprometer a segurana oferecida pelo HTTPS. Especificamente, a configurao desse atributo como false abre contedo de segurana a ataques por falsificao. A Adobe recomenda enfaticamente que voc no defina o atributo secure como false. Se os dados a serem carregados estiverem em um servidor HTTPS, mas o carregamento do arquivo SWF estiver em um servidor HTTP, a Adobe recomenda mover o arquivo SWF que est sendo carregado para um servidor HTTPS. Fazer isso permite manter todas as cpias de seus dados seguras sob a proteo de HTTPS. No entanto, se voc decidir que deve manter o arquivo SWF que est sendo carregado em um servidor HTTP, adicione o atributo secure="false" tag <allow-access-from>, conforme mostrado no cdigo a seguir:
<allow-access-from domain="www.example.com" secure="false" />

Outro elemento que pode ser usado para permitir acesso a tag allow-http-request-headers-from. Esse elemento concede a um cliente, que hospeda contedo de outro domnio, permisso para enviar cabealhos definidos pelo usurio ao seu domnio. Enquanto a tag <allow-access-from> concede a outros domnios permisso para enviar dados ao seu domnio, a tag allow-http-request-headers-from concede a outros domnios permisso para enviar dados a seu domnio na forma de cabealhos. No exemplo a seguir, qualquer domnio tem permisso para enviar o cabealho SOAPAction ao domnio atual:
<cross-domain-policy> <allow-http-request-headers-from domain="*" headers="SOAPAction"/> </cross-domain-policy>

Se a instruo allow-http-request-headers-from estiver no arquivo de poltica mestre, ela ser aplicada a todos os diretrios no host. Caso contrrio, ela ser aplicada apenas ao diretrio e subdiretrios do arquivo de poltica que contm a instruo.

Pr-carregamento de arquivos de poltica

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O carregamento de dados de um servidor ou a conexo a um soquete uma operao assncrona. O Flash Player simplesmente aguarda que o download do arquivo de poltica seja concludo antes de iniciar a operao principal. No entanto, a extrao de dados de pixels de imagens ou a extrao de dados de amostra de sons uma operao sncrona. O arquivo de poltica deve ser carregado para que os dados possam ser extrados. Ao carregar a mdia, especifique que ela verifique a existncia de um arquivo de poltica:

Ao usar o mtodo Loader.load(), defina a propriedade checkPolicyFile do parmetro context, que um

objeto LoaderContext.

Ao incorporar uma imagem em um arquivo de texto usando a tag <img>, defina o atributo checkPolicyFile da
tag <img> como "true", da seguinte maneira:
<img checkPolicyFile = "true" src = "example.jpg">

Ao usar o mtodo Sound.load(), defina a propriedade checkPolicyFile do parmetro context, que um

objeto SoundLoaderContext.

Ao usar a classe NetStream, defina a propriedade checkPolicyFile do objeto NetStream.

Ao definir um desses parmetros, o Flash Player primeiro verifica se h qualquer arquivo de poltica que j foi baixado naquele domnio. Em seguida, ele procura o arquivo de poltica no local padro do servidor, verificando as instrues <allow-access-from> e a presena de uma metapoltica. Finalmente, ele considera quaisquer chamadas pendentes para o mtodo Security.loadPolicyFile() para verificar se elas esto em escopo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1041

Controles de autor (desenvolvedor)

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A API ActionScript principal usada para conceder privilgios de segurana o mtodo Security.allowDomain() que concede privilgios a arquivos SWF nos domnios especificados por voc. No exemplo a seguir, um arquivo SWF concede acesso a arquivos SWF servidos no domnio www.example.com:
Security.allowDomain("www.example.com")

Esse mtodo concede permisses para o seguinte:

Entre scritps entre arquivos SWF (consulte Cross-scripting na pgina 1048) Acesso lista de exibio (consulte Como percorrer a lista de exibio na pgina 1051) Deteco de eventos (consulte Segurana de eventos na pgina 1051) Acesso total propriedades e mtodos do objeto Stage (consultesegurana de Palco na pgina 1050)
O objetivo principal da chamada do mtodo Security.allowDomain() conceder permisso para arquivos SWF em um domnio externo para executar script do arquivo SWF chamando o mtodo Security.allowDomain(). Para obter mais informaes, consulte Cross-scripting na pgina 1048. Especificar um endereo IP como parmetro do mtodo Security.allowDomain() no permite acesso de todas as partes que se originam no endereo IP especificado. Ao contrrio, isso permite o acesso apenas de uma parte que contm o endereo IP especificado como sua URL, em vez de um nome de domnio mapeia para o endereo IP. Por exemplo, se o nome do domnio www.example.com for mapeado para o endereo IP 192.0.34.166, uma chamada para Security.allowDomain("192.0.34.166") no conceder acesso a www.example.com. possvel passar o curinga "*" para o mtodo Security.allowDomain() para permitir acesso a todos os domnios. Como ele concede permisso para arquivos SWF de todos os domnios para executarem script na chamada do arquivo, use o curinga "*" com cuidado. O ActionScript inclui uma segunda API de permisso, chamada Security.allowInsecureDomain(). Esse mtodo faz a mesma coisa que o mtodo Security.allowDomain(), exceto que, quando chamado de um arquivo SWF servido por uma conexo HTTPS segura, ele permite adicionalmente acesso ao arquivo SWF de chamada por outros arquivos SWF que so servidos em um protocolo inseguro, como HTTP. No entanto, no uma boa prtica de segurana permitir script entre arquivos de um protocolo seguro (HTTPS) e arquivos de protocolos inseguros (como HTTP). Isso pode abrir contedo seguro a ataques de falsificao. Esses ataques podem ocorrer da seguinte maneira: como o mtodo Security.allowInsecureDomain() permite acesso aos dados de HTTPS seguro por arquivos SWF servidos em conexes HTTP, um invasor situado entre o servidor HTTP e seus usurios pode substituir seu arquivo SWF de HTTP por um arquivo prprio, que pode ento acessar seus dados HTTPS. Importante: O cdigo executado na caixa de proteo do aplicativo AIR no tem permisso para chamar os mtodos allowDomain() ou allowInsecureDomain() da classe de Segurana. Outro mtodo importante relacionado segurana o mtodo Security.loadPolicyFile() que faz com que o Flash Player verifique se h um arquivo de poltica em um local no padro. Para obter mais informaes, consulte Controles de site (arquivos de poltica) na pgina 1037.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1042

Restrio de APIs de rede

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior APIs de rede podem ser restringidas de duas maneiras. Para impedir atividades mal-intencionadas, o acesso a portas comumente reservadas bloqueado. Voc no pode substituir esses bloqueios em seu cdigo. Para controlar o acesso de um arquivo SWF funcionalidade da rede com relao a outras portas, possvel usar a configurao allowNetworking.

Portas bloqueadas
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O Flash Player e o Adobe AIR tm restries sobre o acesso HTTP a determinadas portas, assim como navegadores. Solicitaes HTTP no so permitidas para determinadas portas padro que convencionalmente so usadas para tipos de servidores no-HTTP. Qualquer API que acesse uma URL da rede est sujeita a essas restries de bloqueio de porta. A nica exceo so APIs que chamam soquetes diretamente, como Socket.connect() eXMLSocket.connect(), ou chamadas para Security.loadPolicyFile() nas quais um arquivo de poltica de soquete est sendo carregado. Conexes de soquete so permitidas ou negadas por meio do uso de arquivos de poltica de soquete no servidor de destino. A lista a seguir mostra as APIs do ActionScript 3.0 s quais se aplica o bloqueio de portas:
FileReference.download(),FileReference.upload(), Loader.load(), Loader.loadBytes(), navigateToURL(), NetConnection.call(), NetConnection.connect(), NetStream.play(), Security.loadPolicyFile(), sendToURL(), Sound.load(), URLLoader.load(), URLStream.load()

O bloqueio de portas tambm se aplica importao da Biblioteca compartilhada, ao uso da tag <img> em campos de texto e ao carregamento de arquivos SWF em uma pgina HTML usando as tags <object> e<embed>. O bloqueio de portas tambm se aplica ao uso da tag <img> em campos de texto e ao carregamento de arquivos SWF em uma pgina HTML usando as tags <object> e<embed>. As listas a seguir mostram quais portas so bloqueadas: HTTP: 20 (dados ftp), 21 (controle ftp) HTTP e FTP: 1 (tcpmux), 7 (echo), 9 (discard), 11 (systat), 13 (daytime), 15 (netstat), 17 (qotd), 19 (chargen), 22 (ssh), 23 (telnet), 25 (smtp), 37 (time), 42 (name), 43 (nicname), 53 (domain), 77 (priv-rjs), 79 (finger), 87 (ttylink), 95 (supdup), 101 (hostriame), 102 (iso-tsap), 103 (gppitnp), 104 (acr-nema), 109 (pop2), 110 (pop3), 111 (sunrpc), 113 (auth), 115 (sftp), 117 (uucp-path), 119 (nntp), 123 (ntp), 135 (loc-srv / epmap), 139 (netbios), 143 (imap2), 179 (bgp), 389 (ldap), 465 (smtp+ssl), 512 (print / exec), 513 (login), 514 (shell), 515 (printer), 526 (tempo), 530 (courier), 531 (chat), 532 (netnews), 540 (uucp), 556 (remotefs), 563 (nntp+ssl), 587 (smtp), 601 (syslog), 636 (ldap+ssl), 993 (ldap+ssl), 995 (pop3+ssl), 2049 (nfs), 4045 (lockd), 6000 (x11)

Uso do parmetro allowNetworking

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior possvel controlar o acesso de um arquivo SWF funcionalidade da rede definindo o parmetro allowNetworking nas tags <object> e<embed> na pgina HTML que contm o contedo do SWF.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1043

Os valores possveis de allowNetworking so:

"all" (o padro) todas as APIs de rede tm permisso no arquivo SWF. "internal" o arquivo SWF no pode chamar APIs de interao de navegador ou navegao de navegador,

listadas posteriormente nesta seo, mas ele pode chamar quaisquer outras APIs de rede.
"none" o arquivo SWF no pode chamar APIs de interao de navegador ou de navegao de navegador, listadas posteriormente nesta seo, e no pode usar quaisquer APIs de comunicao SWF com SWF, tambm listadas posteriormente.

O parmetro allowNetworking foi projetado para uso principalmente quando o arquivo SWF e a pgina HTML que o delimita esto em domnios diferentes. O uso do valor de "internal" ou de "none" no recomendado quando o arquivo SWF que est sendo carregado do mesmo domnio que as pginas HTML que o delimitam, porque no possvel garantir que um arquivo SWF sempre seja carregado com a pgina HTML pretendida. Partes no confiveis podem carregar um arquivo SWF do seu domnio sem HTML delimitado, em cujo caso a restrio allowNetworking no funcionar como pretendido. A chamada de uma API impedida lana uma exceo SecurityError. Adicione o parmetro allowNetworking e defina seu valor nas tags <object> e <embed> da pgina HTML que contm uma referncia ao arquivo SWF, conforme mostrado neste exemplo:
<object classic="clsid:d27cdb6e-ae6d-11cf-96b8-444553540000" Code base="http://fpdownload.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,124, 0" width="600" height="400" ID="test" align="middle"> <param name="allowNetworking" value="none" /> <param name="movie" value="test.swf" /> <param name="bgcolor" value="#333333" /> <embed src="test.swf" allowNetworking="none" bgcolor="#333333" width="600" height="400" name="test" align="middle" type="application/x-shockwave-flash" pluginspage="http://www.macromedia.com/go/getflashplayer" /> </object>

Uma pgina HTML tambm pode usar um script para gerar tags de incorporao SWF. necessrio alterar o script para que ele insira as configuraes corretas de allowNetworking. As pginas HTML geradas pelo Adobe Flash Professional e pelo Adobe Flash Builder usam a funo AC_FL_RunContent() para incorporar referncias aos arquivos SWF. Adicione as configuraes do parmetro allowNetworking ao script, como no seguinte:
AC_FL_RunContent( ... "allowNetworking", "none", ...)

As seguintes APIs so impedidas quando allowNetworking est definido como "internal":

navigateToURL(), fscommand(), ExternalInterface.call()

Alm das APIs da lista anterior, as seguintes APIs tambm so impedidas quando o parmetro allowNetworking est definido como "none":
sendToURL(), FileReference.download(), FileReference.upload(), Loader.load(), LocalConnection.connect(), LocalConnection.send(), NetConnection.connect(), NetStream.play(), Security.loadPolicyFile(), SharedObject.getLocal(), SharedObject.getRemote(), Socket.connect(), Sound.load(), URLLoader.load(), URLStream.load(), XMLSocket.connect()

Mesmo que a configurao allowNetworking selecionada permita que um arquivo SWF use uma API de rede, pode haver outras restries com base nas limitaes da caixa de proteo de segurana (consulte Caixas de proteo de segurana na pgina 1029).

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1044

Quando allowNetworking est definido como "none", no possvel fazer referncia a mdia externa em uma tag <img> na propriedade htmlText de um objeto TextField (uma exceo SecurityError lanada). Quando allowNetworking est definido como "none", um smbolo de uma biblioteca compartilhada importada adicionado no Flash Professional (no no ActionScript) bloqueado em tempo de execuo.

Segurana de modo de tela cheia

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O Flash Player 9.0.27.0 e verses posteriores oferecem suporte ao modo de tela cheia, no qual o contedo executado no Flash Player pode ocupar toda a tela. Para entrar em modo de tela cheia, a propriedade displayState do Palco definida como a constante StageDisplayState.FULL_SCREEN. Para obter mais informaes, consulte Trabalho com o modo de tela cheia na pgina 161. Existem mais consideraes sobre segurana para arquivos SWF executados em uma rea de segurana remota. Para ativar o modo de tela cheia, nas tags <object> e <embed> na pgina HTML que contm uma referncia ao arquivo SWF, adicione o parmetro allowFullScreen com o valor definido como "true" (o valor padro "false"), conforme mostrado no exemplo a seguir:
<object classid="clsid:d27cdb6e-ae6d-11cf-96b8-444553540000" codebase="http://fpdownload.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0, 18,0" width="600" height="400" id="test" align="middle"> <param name="allowFullScreen" value="true" /> <param name="movie" value="test.swf" /> <param name="bgcolor" value="#333333" /> <embed src="test.swf" allowFullScreen="true" bgcolor="#333333" width="600" height="400" name="test" align="middle" type="application/x-shockwave-flash" pluginspage="http://www.macromedia.com/go/getflashplayer" /> </object>

Uma pgina HTML tambm pode usar um script para gerar tags de incorporao SWF. necessrio alterar o script para que ele insira as configuraes corretas de allowFullScreen. As pginas HTML geradas pelo Flash Professional e pelo Flash Builder usam a funo AC_FL_RunContent() para incorporar referncias a arquivos SWF e voc precisa adicionar as configuraes do parmetro allowFullScreen, conforme a seguir:
AC_FL_RunContent( ... "allowFullScreen", "true", ...)

O ActionScript que inicia o modo de tela cheia pode ser chamado apenas em resposta a um evento do mouse ou do teclado. Se ele for chamado em outras situaes, o Flash Player lanar uma exceo. Um mensagem exibida quando o contedo entra em modo de tela cheia, fornecendo ao usurio instrues sobre como sair e retornar ao modo normal. A mensagem exibida por alguns segundos e, em seguida, desaparece. No caso de contedo executado em um navegador, o uso do teclado fica restrito no modo de tela cheia. No Flash Player 9, s dado suporte para atalhos de teclado que retornam o aplicativo ao modo normal, como pressionar a tecla Escape. Os usurios no podem inserir texto em campos de texto ou navegar pela tela. No Flash Player 10 e em verses posteriores, h suporte para certas teclas que no so impressas (especificamente as teclas de seta, espao e Tab). No entanto, a entrada de texto ainda no permitida.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1045

O modo de tela cheia sempre permitido no player independente ou em um arquivo de projetor. Alm disso, o uso do teclado (inclusive para entrada de texto) totalmente suportado nesses ambientes. Chamar a propriedade displayState de um objeto Stage lana uma exceo para qualquer chamador que no esteja na mesma caixa de proteo de segurana que o proprietrio do Palco (o arquivo SWF principal). Para obter mais informaes, consulte segurana de Palco na pgina 1050. Os administradores podem desativar o modo de tela cheia de arquivos SWF em execuo em navegadores configurando FullScreenDisable = 1 no arquivo mms.cfg. Para obter detalhes, consulte Controles de administrador na pgina 1034. Em um navegador, um arquivo SWF deve ser contido em uma pgina HTML para permitir o modo de tela cheia.

Carregamento de contedo
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O contedo do Flash Player e do AIR pode carregar muitos outros tipos de contedos, entre eles o seguinte:

Arquivos SWF Imagens Som Vdeo Arquivos HTML (apenas AIR) JavaScript (apenas AIR)

Carregamento de arquivos SWF e imagens com a classe Loader

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Use a classe Loader para carregar arquivos SWF e imagens (arquivos JPG, GIF ou PNG). Qualquer arquivo SWF, a no ser um que esteja na caixa de proteo local com arquivos do sistema, pode carregar arquivos SWF e imagens de qualquer domnio de rede. Apenas arquivos SWF em caixas de proteo locais podem carregar arquivos SWF e imagens do sistema de arquivos local. No entanto arquivos na caixa de proteo local com rede podem carregar apenas arquivos SWF locais que estejam na mesma caixa de proteo confivel local ou local com rede. Os arquivos SWF na caixa de proteo local com rede carregam contedo local que no sejam arquivos SWF (como imagens), no entanto eles no podem acessar dados no contedo carregado. Ao carregar um arquivo SWF a partir de uma origem no confivel (como um domnio diferente daquele do arquivo SWF da raiz do objeto Loader), convm definir uma mscara para o objeto Loader para impedir que o contedo carregado (que filho do objeto Loader) seja desenhado em partes do Palco fora daquela mscara, conforme mostrado no cdigo a seguir:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1046

import flash.display.*; import flash.net.URLRequest; var rect:Shape = new Shape(); rect.graphics.beginFill(0xFFFFFF); rect.graphics.drawRect(0, 0, 100, 100); addChild(rect); var ldr:Loader = new Loader(); ldr.mask = rect; var url:String = "http://www.unknown.example.com/content.swf"; var urlReq:URLRequest = new URLRequest(url); ldr.load(urlReq); addChild(ldr);

Ao chamar o mtodo load() do objeto Loader, possvel especificar um parmetro context que um objeto LoaderContext. A classe LoaderContext inclui trs propriedades que permitem definir o contexto de como o contedo carregado pode ser usado:

checkPolicyFile: Use essa propriedade apenas ao carregar um arquivo de imagem (no um arquivo SWF).

Especifique-a para um arquivo de imagem de um domnio diferente daquele do arquivo que contm o objeto Loader. Se voc definir a propriedade como true, o Loader verificar o servidor de origem para obter um arquivo de poltica de URL (consulteControles de site (arquivos de poltica) na pgina 1037). Se o servidor conceder permisso ao domnio Loader, o ActionScript de arquivos SWF no domnio Loader poder acessar dados na imagem carregada. Em outras palavras, voc pode usar a propriedade Loader.content para obter uma referncia ao objeto Bitmap que representa a imagem carregada ou o mtodo BitmapData.draw() para acessar pixels da imagem carregada.

securityDomain: S use essa propriedade ao carregar um arquivo SWF (no uma imagem). Especifique-a para um

arquivo SWF de um domnio diferente daquele do arquivo que contm o objeto Loader. Apenas dois valores so suportados atualmente para a propriedade securityDomain: null (o padro) e SecurityDomain.currentDomain. Se voc especificar SecurityDomain.currentDomain, ele solicitar que o arquivo SWF carregado seja importado para a caixa de proteo do arquivo SWF que est sendo carregado, indicando que ele funcionar como se fosse carregado do prprio servidor do arquivo SWF que est sendo carregado. Isso ser permitido apenas se um arquivo de poltica de URL for encontrado no servidor do arquivo SWF carregado, permitindo acesso pelo domnio do arquivo SWF que est sendo carregado. Se o arquivo de poltica for encontrado, o carregador e o carregado podero executar script livremente um no outro assim que o carregamento for iniciado, uma vez que esto na mesma caixa de proteo. Observe que a importao da caixa de proteo pode ser substituda principalmente executando um carregamento comum e, em seguida, fazendo com que o arquivo SWF chame o mtodo Security.allowDomain(). Esse ltimo mtodo pode ser mais fcil de usar, pois o arquivo SWF carregado estar em sua prpria caixa de proteo natural e, portanto, capaz de acessar recursos de seu prprio servidor real.

applicationDomain: Use essa propriedade apenas ao carregar um arquivo SWF gravado no ActionScript 3.0 (no em uma imagem ou arquivo SWF gravado no ActionScript 1.0 ou no ActionScript 2.0). Ao carregar o arquivo, possvel especificar se ele ser colocado em um domnio de aplicativo especfico, em vez de ser colocado como padro em um novo domnio de aplicativo que filho do domnio do aplicativo do arquivo SWF que est sendo carregado. Observe que os domnios de aplicativos so subunidades de domnios de segurana e portanto voc poder especificar um domnio de aplicativo de destino apenas se o arquivo SWF que est sendo carregado for de seu prprio domnio de segurana, seja porque ele de seu prprio servidor ou porque voc o importou com xito em seu domnio de segurana usando a propriedade securityDomain. Se voc especificar um domnio de aplicativo, mas o arquivo SWF carregado fizer parte de um domnio de segurana diferente, o domnio especificado em applicationDomain ser ignorado. Para obter mais informaes, consulte Trabalhar com domnios de aplicativo na pgina 141.

Para obter detalhes, consulte Especificao do contexto do carregamento na pgina 194.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1047

Uma propriedade importante de um objeto Loader a propriedade contentLoaderInfo que um objeto LoaderInfo. Ao contrrio da maioria dos outros objetos, um objeto LoaderInfo compartilhado entre o arquivo SWF que est sendo carregado e o contedo carregado e sempre est acessvel para as duas partes. Quando o contedo carregado um arquivo SWF, ele pode acessar o objeto LoaderInfo por meio da propriedade DisplayObject.loaderInfo. Objetos LoaderInfo incluem informaes, como o progresso do carregamento, as URLs do carregador e do carregado, o relacionamento de confiana entre o carregador e o carregado e outras informaes. Para obter mais informaes, consulte Monitoramento do progresso do carregamento na pgina 193.

Carregamento de som e vdeo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Todos o contedo, alm dos que esto na rea de proteo local com o sistema de arquivos, tm permisso para carregar som e vdeo de origens da rede, usando os mtodos Sound.load(), NetConnection.connect() e NetStream.play() . Somente o contedo local com o sistema de arquivos e aplicativos AIR podem carregar mdia do sistema de arquivos local. Somente o contedo na rea de segurana local com o sistema de arquivos, a rea de segurana do aplicativo AIR ou a rea de segurana local confivel podem acessar dados nos arquivos carregados. H outras restries ao acessar dados de mdia carregada. Para obter detalhes, consulte Acesso mdia carregada como dados na pgina 1052.

Carregamento de arquivos SWF e de imagens usando a tag <img> em um campo de texto

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior possvel carregar arquivos SWF e bitmaps em um campo de texto usando a tag <img>, conforme mostrado no cdigo a seguir:
<img src = 'filename.jpg' id = 'instanceName' >

possvel carregar contedo carregado dessa maneira usando o mtodo getImageReference() da ocorrncia TextField, conforme mostrado no cdigo a seguir:
var loadedObject:DisplayObject = myTextField.getImageReference('instanceName');

No entanto observe que arquivos SWF e imagens carregados dessa maneira so colocados na caixa de proteo que corresponde a sua origem. Ao carregar um arquivo de imagem usando uma tag <img> em um campo de texto, o acesso aos dados da imagem pode ser permitido por um arquivo de poltica de URL. possvel verificar se h um arquivo de poltica adicionando um atributo checkPolicyFile tag <img>, como no cdigo a seguir:
<img src = 'filename.jpg' checkPolicyFile = 'true' id = 'instanceName' >

Ao carregar um SWF usando uma tag <img> em um campo de texto, possvel permitir acesso aos dados daquele arquivo SWF por meio de uma chamada ao mtodo Security.allowDomain().

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1048

Ao usar uma tag <img> em um campo de texto para carregar um arquivo externo (em vez de usar uma classe Bitmap incorporada em seu SWF), um objeto Loader criado automaticamente como um filho do objeto TextField, e o arquivo externo carregado naquele Loader exatamente como se voc tivesse usado um objeto Loader no ActionScript para carregar o arquivo. Nesse caso, o mtodo getImageReference() retorna o Loader que foi criado automaticamente. Nenhuma verificao de segurana necessria para acessar esse objeto Loader porque ele est na mesma caixa de proteo de segurana que o objeto de chamada. No entanto quando voc faz referncia propriedade content do objeto Loader para acessar a mdia carregada, regras de segurana so aplicadas. Se o contedo for uma imagem, ser necessrio implementar um arquivo de poltica de URL e, se o contedo for um arquivo SWF, voc precisar fazer com que o cdigo no arquivo SWF chame o mtodo allowDomain(). Adobe AIR Na caixa de proteo do aplicativo, as marcas <img> em um campo de texto so ignoradas para evitar ataques de phishing. Alm disso, o cdigo executado na caixa de proteo do aplicativo no pode chamar o mtodo de Segurana allowDomain().

Contedo entregue usando servidores RMTP

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O Flash Media Server usa o protocolo RTMP para servir dados, udio e vdeo. possvel carregar esta mdia usando o mtodo connect() da classe NetConnection, passando uma URL de RTMP como o parmetro. O Flash Media Server pode restringir conexes e impedir que contedo seja baixado, com base no domnio do arquivo solicitante. Para obter detalhes, consulte a documentao on-line do Flash Media Server em www.adobe.com/go/learn_fms_docs_br. Para utilizar os mtodos BitmapData.draw() e SoundMixer.computeSpectrum() para extrair grficos de tempo de execuo e dados de udio de fluxos RTMP, voc deve permitir o acesso no servidor. Utilize o ActionScript de lado do servidor Client.videoSampleAccess e as propriedades Client.audioSampleAccess para permitir acesso a diretrios especficos no Flash Media Server. Para obter mais informaes, consulte a Referncia de linguagem do ActionScript de lado do servidor.

Cross-scripting
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Se dois arquivos escritos com o ActionScript 3.0 , ou dois arquivos HTML executados no AIR, forem servidos no mesmo domnio, por exemplo, se a URL de um arquivo SWF for http://www.example.com/swfA.swf e a URL do outro for http://www.example.com/swfB.swf, o cdigo definido em um arquivo poder examinar e modificar variveis, objetos, propriedades, mtodos e assim por diante na ordem e vice-versa. Isso chamado de cross-scripting. Se dois arquivos forem servidos em domnios diferentes, por exemplo, http://siteA.com/swfA.swf e http://siteB.com/siteB.swf, por padro, o Flash Player e o AIR no permitiro que o swfA.swf execute script do swfB.swf nem que o swfB.swf execute script do swfA.swf. O arquivo SWF d permisso a arquivos SWF de outros domnios chamando Security.allowDomain(). Com a chamada de Security.allowDomain("siteA.com"), o swfB.swf concede aos arquivos SWF do siteA.swf permisso para executar script nele.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1049

O cross-scripting no suportado entre arquivos SWF AVM1 e SWF AVM2. Um arquivo SWF AVM1 criado usando o ActionScript 1.0 ou o ActionScript 2.0. (AVM1 e AVM2 se referem a ActionScript Virtual Machine.) No entanto possvel usar a classe LocalConnection para enviar dados entre o AVM1 e o AVM2. Em qualquer situao entre domnios, importante que as duas partes envolvidas sejam bem-definidas. Para fins desta discusso, o lado que executa o cross-scripting chamado de parte de acesso (normalmente o SWF que faz o acesso) e o outro lado chamado de a parte que est sendo acessada (normalmente o SWF que est sendo acessado). Quando o siteA.swf executa script no siteB.swf, o siteA.swf a parte que acessa e o siteB.swf a parte que est sendo acessada, conforme mostrado na ilustrao a seguir:
siteA.com / swfA.swf
SWF

var url:String = "http://siteB.com/swfB.swf"; var req:URLRequest = new URLRequest(url); myLoader.load(req);

myLoader.content.eggCount = 3; myLoader.content.DisplayEggs();

carregar

entre scripts

2 permisso

Security.allowDomain("siteA.com");

var eggCount:Number; function DisplayEggs() { ... }; siteB.com / swfB.swf

SWF

Permisses entre domnios estabelecidas com o mtodoSecurity.allowDomain() so assimtricas. No exemplo anterior, o siteA.swf pode executar script no siteB.swf, mas o siteB.swf no pode executar script no siteA.swf, pois o siteA.swf no chamou o mtodo Security.allowDomain() para conceder permisso aos arquivos SWF no siteB.com para executar script nele. possvel configurar permisses simtricas fazendo com que os dois arquivos SWF chamem o mtodo Security.allowDomain(). Alm de proteger arquivos SWF contra a execuo de script entre domnios originadas por outros arquivos SWF, o Flash Player protege arquivos SWF conta a execuo de script entre domnios originadas por arquivos HTML. A execuo de script de HTML para SWF pode ocorrer com retornos de chamada estabelecidos por meio do mtodo ExternalInterface.addCallback(). Quando a execuo de script de HTML para SWF cruza domnios, o arquivo SWF que est sendo acessado deve chamar o mtodo Security.allowDomain() exatamente como quando a parte que faz o acesso um arquivo SWF ou haver falha na operao. Para obter mais informaes, consulte Controles de autor (desenvolvedor) na pgina 1041. Alm disso, o Flash Player fornece controles de segurana para execuo de script de SWF para HTML. Para obter mais informaes, consulte Controle do acesso URL de sada na pgina 1059.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1050

segurana de Palco
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Algumas propriedades e mtodos do objeto Stage esto disponveis para qualquer entidade grfica ou clipe de filme na lista de exibio. No entanto o objeto Stage considerado como tendo um proprietrio: o primeiro arquivo SWF carregado. Por padro, as seguintes propriedades e mtodos do objeto Stage esto disponveis apenas para arquivos SWF na mesma caixa de proteo de segurana que o proprietrio do Palco:
Propriedades
alinhar

Mtodos
addChild() addChildAt() addEventListener() dispatchEvent() hasEventListener() setChildIndex() willTrigger()

displayState frameRate
height mouseChildren numChildren quality scaleMode showDefaultContextMenu stageFocusRect stageHeight stageWidth tabChildren textSnapshot width

Para que um arquivo SWF em uma caixa de proteo diferente daquela do proprietrio do Palco acesse essas propriedades e mtodos, o arquivo SWF do proprietrio do Palco deve chamar o mtodo Security.allowDomain() para permitir o domnio da caixa de proteo externa. Para obter mais informaes, consulte Controles de autor (desenvolvedor) na pgina 1041. A propriedade frameRate um caso especial, qualquer arquivo SWF pode ler a propriedade frameRate. No entanto, apenas aqueles que esto na caixa de proteo de segurana do proprietrio do Palco (ou aqueles que receberam permisso por uma chamada para o mtodo Security.allowDomain()) podem alterar a propriedade. Tambm h restries nos mtodos removeChildAt() e swapChildrenAt() do objeto Stage, mas essas so diferentes das outras restries. E vez de ser necessrio estar no mesmo domnio que o proprietrio do Palco para chamar esses mtodos, o cdigo deve estar no mesmo domnio que o proprietrio dos objetos filho afetados ou os objetos filho podem chamar o mtodo Security.allowDomain().

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1051

Como percorrer a lista de exibio

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A capacidade de um arquivo SWF acessar objetos de exibio carregados de outras caixas de proteo restrita. Para que um arquivo SWF acesse um objeto de exibio criado por outro arquivo SWF em uma caixa de proteo diferente, o arquivo SWF que est sendo acessado deve chamar o mtodo Security.allowDomain() para permitir acesso pelo domnio do arquivo SWF que est acessando. Para obter mais informaes, consulte Controles de autor (desenvolvedor) na pgina 1041. Para acessar um objeto Bitmap que foi carregado por um objeto Loader, um arquivo de poltica de URL deve existir no servidor de origem do arquivo de imagem, e esse arquivo de poltica deve conceder permisso ao domnio do arquivo SWF que est tentando acessar o objeto Bitmap (consulte Controles de site (arquivos de poltica) na pgina 1037). O objeto LoaderInfo que corresponde a um arquivo carregado (e ao objeto Loader) inclui as trs seguintes propriedades que definem o relacionamento entre o objeto carregado e o objeto Loader: childAllowsParent, parentAllowsChild e sameDomain.

Segurana de eventos
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Eventos relacionados lista de exibio tm limitaes de acesso de segurana com base na caixa de proteo do objeto de exibio est despachando o evento. Um evento na lista de exibio tem fases de bubbling e de captura (descritas em Manipulao de eventos na pgina 118). Durante as fases de bubbling e de captura, um evento migra do objeto de exibio de origem por meio de objetos de exibio pai na lista de exibio. Se um objeto pai estiver em uma caixa de proteo de segurana diferente do objeto de exibio de origem, a fase de captura e de bubble parar abaixo daquele objeto pai, a menos que haja confiana mtua entre o proprietrio do objeto pai e o proprietrio do objeto de origem. Essa confiana mtua pode ser obtida pelo seguinte:
1 O arquivo SWF que possui o objeto pai deve chamar o mtodo Security.allowDomain() para confiar no

domnio do arquivo SWF que possui o objeto de origem.

2 O arquivo SWF que possui o objeto de origem deve chamar o mtodo Security.allowDomain() para confiar no

domnio do arquivo SWF que possui o objeto pai. O objeto LoaderInfo que corresponde a um arquivo carregado (e ao objeto Loader) inclui as duas seguintes propriedades que definem o relacionamento entre o objeto carregado e o objeto Loader: childAllowsParent e parentAllowsChild. Para eventos despachados de objetos que no so objetos de exibio, no h verificaes de segurana ou implicaes relacionadas segurana.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1052

Acesso mdia carregada como dados

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para acessar dados de carga, utilize os mtodos BitmapData.draw() e SoundMixer.computeSpectrum(). Por padro, no possvel obter dados de pixel ou dados de udio a partir de objetos grficos ou de udio renderizados ou reproduzidos por mdia carregada em uma rea de segurana diferente. No entanto, possvel utilizar os mtodos a seguir para conceder permisses para acessar estes dados nos limites de reas de segurana:

No contedo renderizado ou que est reproduzindo os dados, crie uma chamada para o mtodo
Security.allowDomain() para conceder acesso de dados ao contedo em outros domnios.

Para uma imagem, som ou vdeo carregado, adicione um arquivo de poltica de URL no servidor do arquivo
carregado. Esse arquivo de poltica deve conceder acesso ao domnio do arquivo SWF que est tentando chamar os mtodos BitmapData.draw() ou SoundMixer.computeSpectrum() para extrair dados do arquivo. As sees a seguir fornecem detalhes sobre o acesso a dados de bitmap, som e vdeo.

Acesso a dados de bitmap

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O mtodo draw() de um objeto BitmapData permite desenhar os pixels exibidos atualmente de qualquer objeto de exibio para o objeto BitmapData. Isso pode incluir os pixels de um objeto MovieClip, de um objeto Bitmap ou de qualquer objeto de exibio. As seguintes condies devem ser atendidas para que o mtodo draw() desenhe pixels para o objeto BitmapData:

No caso de um objeto de origem diferente de um bitmap carregado, o objeto de origem e (no caso de um objeto
Sprite ou MovieClip) todos os seus objetos filho devem vir do mesmo domnio que o objeto que est chamando o mtodo draw(), ou devem estar em um arquivo SWF que possa ser acessado pelo chamador fazendo com que o mtodo Security.allowDomain() seja chamado.

No caso de um objeto de origem de bitmap Loaded, o objeto de origem deve vir do mesmo domnio que o objeto
que est chamando o mtodo draw(), ou seu servidor de origem deve incluir um arquivo de poltica de URL que conceda permisso ao domnio que est fazendo a chamada. Se essas condies no forem atendidas, uma exceo SecurityError ser lanada. Ao carregar a imagem usando o mtodo load() da classe Loader, voc pode especificar um parmetro context que um objeto SoundLoaderContext. Se voc definir a propriedade checkPolicyFile do objeto LoaderContext como true, o Flash Player verificar se h um arquivo de poltica de URL no servidor do qual a imagem carregada. Se houver um arquivo de poltica e o arquivo permitir que o domnio do arquivo SWF que est sendo carregado, o arquivo ter permisso para acessar os dados no objeto Bitmap. Caso contrrio, o acesso ser negado. Tambm possvel especificar uma propriedade checkPolicyFile em uma imagem carregada por meio de uma tag <img> em um campo de texto. Para obter detalhes, consulte Carregamento de arquivos SWF e de imagens usando a tag <img> em um campo de texto na pgina 1047

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1053

Acesso a dados de som

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior As seguintes APIs do ActionScript 3.0 relacionadas a som tm restries de segurana:

O mtodo

SoundMixer.computeSpectrum() sempre permitido para arquivos SWF que esto na mesma rea de proteo de segurana que o arquivo de som. Existem verificaes de segurana para o cdigo executado em outras reas de segurana.

O mtodo

SoundMixer.computeSpectrum() sempre permitido para cdigo sendo executado na mesma rea de segurana que o arquivo de som. Para arquivos em outras caixas de proteo, h verificaes de segurana.

A propriedade id3 da classe Sound sempre permitida para arquivos SWF que esto na mesma caixa de proteo
de segurana que o arquivo de som. Existem verificaes de segurana para o cdigo executado em outras reas de segurana. Todo evento tem dois tipos de caixas de proteo associadas a ele, uma caixa de proteo de contedo e uma caixa de proteo do proprietrio:

O domnio de origem do som determina a caixa de proteo de contedo e isso determina se os dados podem ser
extrados do som por meio da propriedade id3 do som e do mtodo SoundMixer.computeSpectrum().

O objeto que iniciou a reproduo do som determina a caixa de proteo do proprietrio e isso determina se o som
pode ser parado usando o mtodo SoundMixer.stopAll(). Ao carregar o som usando o mtodo load() da classe Sound, voc pode especificar um parmetro context que um objeto SoundLoaderContext. Se voc definir a propriedade checkPolicyFile do objeto SoundLoaderContext como true, o Flash Player verificar se h um arquivo de poltica de URL no servidor do qual o som carregado. Se houver um arquivo de poltica e o arquivo permitir o domnio do cdigo que est sendo carregado, o cdigo receber permisso para acessar a propriedade id do objeto Sound. Caso contrrio, no ter essa permisso. Alm disso, a configurao da propriedade checkPolicyFile pode ativar o mtodo SoundMixer.computeSpectrum() para sons carregados. possvel usar o mtodo SoundMixer.areSoundsInaccessible() para descobrir se uma chamada para o mtodo SoundMixer.stopAll() no parar todos os sons porque a caixa de proteo de um ou mais proprietrios de som est inacessvel para o chamador. A chamada do mtodo SoundMixer.stopAll() pra esses sons cuja caixa de proteo de proprietrio a mesma que a do chamador de stopAll(). Ela tambm pra aqueles sons cuja reproduo foi iniciada por arquivos SWF que chamaram o mtodo Security.allowDomain() para permitir acesso pelo domnio do arquivo SWF que est chamando o mtodo stopAll(). Qualquer outro som no parado e a presena desses sons pode ser revelada chamando o mtodo SoundMixer.areSoundsInaccessible(). A chamada do mtodo computeSpectrum() requer que todo som que esteja sendo reproduzido seja da mesma caixa de proteo que o objeto que est chamando o mtodo ou de uma origem que recebeu permisso para a caixa de proteo do chamador. Caso contrrio, uma exceo SecurityError lanada. Para sons que foram carregados de sons incorporados em uma biblioteca em um arquivo SWF, a permisso ser concedida com uma chamada para o mtodo Security.allowDomain() no arquivo SWF carregado. Para sons carregados de origens que no sejam arquivos SWF (originrios de arquivos mp3 carregados ou de arquivos de vdeo), um arquivo de poltica de URL no servidor de origem concede acesso a dados contidos na mdia carregada. Para obter mais informaes, consulteControles de autor (desenvolvedor) na pgina 1041 eControles de site (arquivos de poltica) na pgina 1037.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1054

Para acessar dados de som a partir de fluxos RTMP, necessrio conceder acesso no servidor. Utilize a propriedade ActionScript de lado do servidor Client.audioSampleAccess para permitir acesso a diretrios especficos no Flash Media Server. Para obter mais informaes, consulte a Referncia de linguagem do ActionScript de lado do servidor.

Acesso a dados de vdeo

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior possvel usar o mtodo BitmapData.draw() para capturar os dados de pixels do quadro atual de um vdeo. H dois tipos diferentes de vdeo:

Vdeo transmitido por meio de RTMP a partir do Flash Media Server Vdeo progressivo, carregado a partir de um arquivo FLV ou F4V
Para utilizar o mtodo BitmapData.draw() para extrair grficos de tempo em execuo de fluxos RTMP, necessrio conceder acesso no servidor. Utilize a propriedade ActionScript de lado do servidor Client.videoSampleAccess para permitir acesso a diretrios especficos no Flash Media Server. Para obter mais informaes, consulte a Referncia de linguagem do ActionScript de lado do servidor. Ao chamar o mtodo BitmapData.draw() com vdeo progressivo como o parmetro source, o chamador de
BitmapData.draw() deve estar na mesma caixa de proteo que o arquivo FLV, ou o servidor do arquivo FLV deve

ter um arquivo de poltica que conceda permisso para o domnio do arquivo SWF que est fazendo a chamada. possvel solicitar que o arquivo de poltica seja baixado configurando a propriedade checkPolicyFile do objeto NetStream como true.

Carregamento de dados
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O contedo do Flash Player e do AIR podem trocar dados com servidores. O carregamento de dados um tipo de operao diferente do carregamento de mdia porque as informaes carregadas aparecem como objetos em vez de serem exibidas como mdia. Geralmente, o contedo pode carregar dados do mesmo domnio de origem do contedo. No entanto, o contedo geralmente exige arquivos de poltica para carregar dados de outros domnios (consulte Controles de site (arquivos de poltica) na pgina 1037). Nota: O contedo executado na rea de segurana do AIR nunca servidor a partir de um domnio remoto (a no ser que o desenvolvedor importe intencionalmente o contedo remoto para a rea de segurana), de forma que ele no participe da proteo contra ataques fornecida pelos arquivos de poltica. O contedo do AIR na rea de segurana do aplicativo no est restrito a carregar dados por meio de arquivos de poltica. No entanto, o contedo AIR em outras reas de segurana est sujeito s restries descritas.

Uso de URLLoader e URLStream

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior possvel carregar dados, como um arquivo XML ou um arquivo de texto. Os mtodos load() das classes URLLoader e URLStream so governados pelas permisses do arquivo de poltica de URL.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1055

Se voc usar o mtodo load() para carregar contedo de um domnio diferente daquele do cdigo que est chamando o mtodo, o tempo de execuo verificar se existe um arquivo de poltica de URL no servidor dos ativos carregados. Se houver um arquivo de poltica e ele conceder acesso ao domnio do contedo que est sendo carregado, voc poder carregar os dados.

Conexo a soquetes
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Por padro, o tempo de execuo procura um arquivo de poltica de soquete servido na porta 843. Assim como os arquivos de poltica de URL, esse arquivo chamado de arquivo de poltica mestre. Quando arquivos de poltica foram introduzidos no Flash Player 6 pela primeira vez, no havia suporte para arquivos de poltica de soquete. Conexes a servidores de soquete eram autorizadas por um arquivo de poltica no local padro em um servidor HTTP na porta 80 do mesmo host que o servidor de soquete. O Flash Player 9 ainda oferece suporte a essa capacidade, mas o Flash Player 10 no oferece. No Flash Player 10, apenas arquivos de poltica de soquete podem autorizar conexes de soquete. Como os arquivos de poltica de URL, os arquivos de poltica de soquete oferecem suporte a uma instruo de metapoltica que especifica quais portas podem servir arquivos de poltica. No entanto, em vez de master-only, a metapoltica padro para arquivos de poltica de soquete all. Isto , a menos que o arquivo de poltica mestre especifique uma configurao mais restritiva, o Flash Player assumir que qualquer soquete no host pode servir um arquivo de poltica de soquete. O acesso a conexes de soquete XML e a soquete est desativado por padro, mesmo que o soquete que voc est conectando esteja no mesmo domnio que o arquivo SWF. possvel permitir acesso em nvel de soquete servindo um arquivo de poltica de segurana de qualquer um dos seguintes locais:

Porta 843 (o local do arquivo de poltica mestre) A mesma porta que a conexo de soquete principal Uma porta diferente da conexo de soquete principal
Por padro, o Flash Player procura um arquivo de poltica de soquete na porta 843 e na mesma porta que a conexo de soquete principal. Se desejar servir um arquivo de poltica de soquete em uma porta diferente, o arquivo SWF dever chamar Security.loadPolicyFile(). Um arquivo de poltica de soquete tem a mesma sintaxe que um arquivo de poltica de URL, exceto que ele tambm deve especificar as portas s quais ele concede acesso. Quando um arquivo de poltica de soquete servido em uma porta com nmero inferior a 1024, ele pode conceder acesso a qualquer porta. Quando um arquivo de poltica proveniente da porta 1024 ou superior ele s pode conceder acesso a portas 1024 e superiores. As portas permitidas so especificadas em um atributo to-ports na tag <allow-access-from>. Os valores de nmeros de portas nicos, intervalos de portas e curingas so aceitos. Este um exemplo de arquivo de poltica de soquete:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1056

<?xml version="1.0"?> <!DOCTYPE cross-domain-policy SYSTEM "http://www.adobe.com/xml/dtds/cross-domain-policy.dtd"> <!-- Policy file for xmlsocket://socks.mysite.com --> <cross-domain-policy> <allow-access-from domain="*" to-ports="507" /> <allow-access-from domain="*.example.com" to-ports="507,516" /> <allow-access-from domain="*.example.org" to-ports="516-523" /> <allow-access-from domain="adobe.com" to-ports="507,516-523" /> <allow-access-from domain="192.0.34.166" to-ports="*" /> </cross-domain-policy>

Para recuperar um arquivo de poltica de soquete da porta 843 ou da mesma porta como uma conexo de soquete principal, chame o mtodo Socket.connect() ou XMLSocket.connect(). O Flash Player primeiro verifica se h um arquivo de poltica mestre na porta 843. Se um arquivo de poltica mestre for localizado, ele verificar se o arquivo contm uma instruo de metapoltica que probe arquivos de poltica de soquete na porta de destino. Se o acesso no for proibido, o Flash Player primeiro procurar a instruo allow-access-from apropriada no arquivo de poltica mestre. Se uma instruo no for localizada, ele procurar um arquivo de poltica de soquete na mesma porta que a conexo de soquete principal. Para recuperar um arquivo de poltica de soquete de um local diferente, primeiro chame o mtodo
Security.loadPolicyFile() com a sintaxe especial "xmlsocket", como no seguinte: Security.loadPolicyFile("xmlsocket://server.com:2525");

Chame o mtodo Security.loadPolicyFile() antes de chamar o mtodo Socket.connect() ou XMLSocket.connect(). O Flash Player ento aguarda at que tenha atendido sua solicitao de arquivo de poltica antes de decidir se permite sua conexo principal. No entanto, se o arquivo de poltica mestre especificar que o local de destino no pode servir arquivos de poltica, a chamada para loadPolicyFile() no ter nenhum efeito, mesmo que haja um arquivo de poltica naquele local. Se estiver implementando um servidor de soquetes e precisar fornecer um arquivo de poltica de soquete, decida se o arquivo de poltica deve ser fornecido usando a mesma porta que aceita conexes principais ou usando uma porta diferente. Em qualquer dos casos, o servidor deve aguardar a primeira transmisso de seu cliente antes de enviar uma resposta. Quando o Flash Player solicita um arquivo de poltica, ele sempre transmite a string a seguir assim que a conexo estabelecida:
<policy-file-request/>

Quando o servidor recebe essa string, ele pode transmitir o arquivo de poltica. A solicitao do Flash Player sempre terminada por um byte nulo e a resposta do servidor tambm deve ser terminada por um byte nulo. No espere reutilizar a mesma conexo para uma solicitao de arquivo de poltica e para uma conexo principal. Feche a conexo depois de transmitir o arquivo de poltica. Se isso no for feito, o Flash Player fechar a conexo do arquivo de poltica antes de reconectar-se para configurar a conexo principal.

Protegendo dados
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para proteger o vazamento de dados e alteraes durante o transporte na Internet, possvel utilizar Transport Layer Security (TLS) ou Socket Layer Security (SSL) no servidor de origem dos dados. possvel estabelecer uma conexo com o servidor utilizando o protocolo HTTPS.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1057

Em aplicativos criados no AIR 2 ou superior, voc tambm pode proteger as comunicaes do soquete TCP. A classe SecureSocket permite que voc inicie uma conexo com um servidor de soquete que utiliza TLS verso 1 ou SSL verso 4.

Envio de dados
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O envio de dados ocorre quando o cdigo envia dados para um servidor ou recurso. O envio de dados sempre permitido para o contedo de uma domnio de rede. Um arquivo SWF local pode enviar dados a endereos de rede somente se estiver na rea de proteo local confivel, local com rede ou em uma rea de segurana AIR. Para obter mais informaes, consulte Caixas de proteo locais na pgina 1029. possvel usar a funo flash.net.sendToURL() para enviar dados a uma URL. Outros mtodos tambm enviam solicitaes a URLs. Esses incluem mtodos de carregamento, como Loader.load() e Sound.load(), mtodos de carregamento de dados, como URLLoader.load() e URLStream.load().

Upload e download de arquivos

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O mtodo FileReference.upload() inicia o upload de um arquivo selecionado por um usurio a um servidor remoto. necessrio chamar o mtodo FileReference.browse() ou FileReferenceList.browse() antes de chamar o mtodo FileReference.upload(). O cdigo que inicia o mtodo FileReference.browse() ou FileReferenceList.browse() somente pode ser chamado em resposta a um evento de mouse ou de teclado. Se ele for chamado em outras situaes, o Flash Player 10 e verses posteriores iro gerar uma exceo. No entanto, um evento iniciado por usurio no obrigatrio para chamar estes mtodos a partir da rea de segurana do aplicativo AIR. A chamada do mtodo FileReference.download() abre a caixa de dilogo na qual o usurio pode baixar um arquivo de um servidor remoto. Nota: Se o servidor exigir autenticao de usurio, apenas os aplicativos Flash em execuo em um navegador (ou seja, que utilizam plug-in para navegador ou controle ActiveX), podero fornecer uma caixa de dilogo para solicitar que o usurio insira um nome e uma senha para autenticao, e somente para downloads. O Flash Player no permite uploads para um servidor que exige autenticao de usurio. Uploads e downloads no sero permitidos se o arquivo SWF que est chamando estiver na caixa de proteo local com sistema de arquivos. Por padro, um arquivo SWF no pode iniciar um upload ou um download de um servidor que no seja seu prprio servidor. Um arquivo SWF pode carregar ou baixar de um servidor diferente se esse servidor fornecer um arquivo de poltica que conceda permisso ao domnio do arquivo SWF que est chamando.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1058

Carregamento de contedo incorporado de arquivos SWF importados em um domnio de segurana

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Ao carregar um arquivo SWF, voc pode definir o parmetro context do mtodo load() do objeto Loader usado para carregar o arquivo. Esse parmetro usa um objeto LoaderContext. Ao definir a propriedade securityDomain do objeto LoaderContext como Security.currentDomain, o Flash Player verificar se h um arquivo de poltica de URL no servidor do arquivo SWF carregado. Se houver um arquivo de poltica e ele conceder acesso ao domnio do arquivo SWF que est sendo carregado, voc poder carregar o arquivo SWF como mdia importada. Dessa maneira, o arquivo carregado pode obter acesso a objetos na biblioteca do arquivo SWF. Uma maneira alternativa de um arquivo SWF acessar classes no arquivo SWF carregado de uma caixa de proteo de segurana diferente fazer com que o arquivo SWF carregado chame o mtodo Security.allowDomain() para conceder acesso ao domnio do arquivo SWF que est chamando. possvel adicionar a chamada ao mtodo Security.allowDomain() ao mtodo construtor da classe principal do arquivo SWF carregado e fazer com que o arquivo SWF que est sendo carregado adicione um ouvinte de eventos para responder ao evento init despachado pela propriedade contentLoaderInfo do objeto Loader. Quando esse evento for despachado, o arquivo SWF carregado ter chamado o mtodo Security.allowDomain() no mtodo construtor e as classes no arquivo SWF carregado estaro disponveis para o arquivo SWF que est sendo carregado. O arquivo SWF que est sendo carregado pode recuperar classes do arquivo SWF carregado chamando Loader.contentLoaderInfo.applicationDomain.getDefinition().

Trabalho com contedo legado

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior No Flash Player 6, o domnio usado para determinadas configuraes do Flash Player se baseia na parte posterior do domnio do arquivo SWF. Essas configuraes incluem configuraes para permisses de cmera e microfone, quotas de armazenamento e armazenamento de objetos compartilhados persistentes. Se o domnio de um arquivo SWF incluir mais de dois segmentos, como www.example.com, o primeiro segmento do domnio (www) ser removido e a parte restante do domnio ser usada. Assim, no Flash Player 6, www.example.com e store.example.com usam example.com como domnio dessas configuraes. De modo semelhante, www.example.co.uk e store.example.co.uk usam example.co.uk como o domnio dessas configuraes. Isso pode resultar em problemas nos quais arquivos SWF de domnios no relacionados, como example1.co.uk e example2.co.uk, tm acesso aos mesmos objetos compartilhados. No Flash Player 7 e posterior, as configuraes do player so escolhidas por padro de acordo com o domnio exato de um arquivo SWF. Por exemplo, um arquivo SWF do www.example.com usa as configuraes do player para www.example.com. Um arquivo SWF do store.example.com usa as configuraes separadas do player para store.example.com. Em um arquivo SWF gravado com o ActionScript 3.0, quando Security.exactSettings definida como true (o padro), o Flash Player usa domnios exatos para configuraes do player. Quando est definido como false, o Flash Player usa as configuraes de domnio utilizadas no Flash Player 6. Se voc alterar exactSettings de seu valor padro, faa isso antes que ocorram quaisquer eventos que exigem que o Flash Player escolha as configuraes do player por exemplo, usando uma cmera ou microfone, ou recuperando um objeto compartilhado consistente.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1059

Se voc publicou um arquivo SWF da verso 6 e criou objetos compartilhados persistentes a partir dele, para recuperar esses objetos compartilhados persistentes de um SWF que usa o ActionScript 3.0, voc deve definir Security.exactSettings como false antes de chamar SharedObject.getLocal().

Configurao de permisses de LocalConnection

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior A classe LocalConnection permite enviar mensagens entre um Flash Player ou um aplicativo AIR. Objetos LocalConnection podem comunicar-se somente entre o contedo do Flash Player ou AIR executado no mesmo computador, mas eles podem executar aplicativos diferentespor exemplo, um arquivo SWF executado em um navegador, um arquivo SWF executado em um projetor e um aplicativo AIR podem se comunicar utilizando a classe LocalConnection. Para cada comunicao LocalConnection, existe um remetente e um ouvinte. Por padro, o Flash Player permite comunicao LocalConnection entre o cdigo executado no mesmo domnio. Para cdigo executado em diferentes reas de proteo, o ouvinte deve conceder a permisso de remetente, usando o mtodo LocalConnection.allowDomain(). A string passada como um argumento para o mtodo LocalConnection.allowDomain() pode conter qualquer um dos seguintes: nomes exatos do domnio, endereos IP e * asterisco. A forma do mtodo allowDomain() foi alterada desde o ActionScript 1.0 e 2.0. Nessas verses anteriores,
allowDomain() era um mtodo de retorno de chamada que voc implementava. No ActionScript 3.0, allowDomain() um mtodo embutido da classe LocalConnection que voc chama. Com essa alterao, allowDomain() funciona da mesma maneira que Security.allowDomain().

Um arquivo SWF usa a propriedade domain da classe LocalConnection para determinar seu domnio.

Controle do acesso URL de sada

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Script e acesso URL de sada (por meio do uso de URLs HTTP, mailto: etc.) so executados com o uso das seguintes APIs do

A funo flash.system.fscommand() O mtodo ExternalInterface.call() A funo flash.net.navigateToURL()

Para o contedo carregado a partir do sistema de arquivos local, as chamadas para estes mtodos so bem sucedidas se o cdigo e a pgina web (se houver uma) estiverem nas reas de segurana do aplicativo AIR. Haver falha em chamadas para esses mtodos se o contedo estiver na caixa de proteo local com rede ou local com sistema de arquivos. Para contedo no carregado localmente, todas essas APIs podem se comunicar com a pgina da Web na qual esto incorporados, dependendo do valor do parmetro AllowScriptAccess descrito a seguir. A funo flash.net.navigateToURL() tem a capacidade adicional de comunicao com qualquer janela ou quadro de navegador aberto, no apenas com a pgina na qual o arquivo SWF est incorporado. Para obter mais informaes sobre essa funcionalidade, consulte Uso da funo navigateToURL() na pgina 1060.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1060

O parmetro AllowScriptAccess no cdigo HTML que carrega um arquivo SWF controla a capacidade de executar acesso URL a partir do arquivo SWF. Defina esse parmetro dentro da tag PARAM ou EMBED. Se nenhum valor estiver definido para AllowScriptAccess, o arquivo SWF e a pgina HTML podero se comunicar apenas se os dois forem do mesmo domnio. O valor do parmetro AllowScriptAccess pode ser um destes trs valores possveis: "always", "sameDomain" ou "never".

Quando AllowScriptAccess "always", o arquivo SWF pode se comunicar com a pgina HTML na qual ele est
incorporado, mesmo quando o arquivo de um domnio diferente da pgina HTML.

Quando AllowScriptAccess "sameDomain", o arquivo SWF pode se comunicar com a pgina HTML na qual
ele est incorporado apenas quando o arquivo SWF est no mesmo domnio que a pgina HTML. Esse valor o padro de AllowScriptAccess. Use essa configurao, ou no defina um valor para AllowScriptAccess, para evitar que um arquivo SWF hospedado em um domnio acesse um script em uma pgina HTML proveniente de outro domnio.

Quando AllowScriptAccess est definido como "never", um arquivo SWF no pode se comunicar com
nenhuma pgina HTML. Usar este valor foi algo desaprovado deste o lanamento do Adobe Flash CS4 Professional. Ele no recomendado e no deveria ser necessrio se voc no disponibiliza arquivos SWF no confiveis de seu prprio domnio. Se for necessrio servir arquivos SWF no confiveis, a Adobe recomenda que seja criado um subdomnio diferente e que todo o contedo no confivel seja colocado nele. Este um exemplo de configurao da tag AllowScriptAccess em uma pgina HTML para permitir acesso URL de sada para um domnio diferente:
<object id='MyMovie.swf' classid='clsid:D27CDB6E-AE6D-11cf-96B8-444553540000' codebase='http://download.adobe.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,0,0' height='100%' width='100%'> <param name='AllowScriptAccess' value='always'/> <param name='src' value=''MyMovie.swf'/> <embed name='MyMovie.swf' pluginspage='http://www.adobe.com/go/getflashplayer' src='MyMovie.swf' height='100%' width='100%' AllowScriptAccess='never'/> </object>

Uso da funo navigateToURL()

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Alm da configurao de segurana especificada pelo parmetro allowScriptAccess discutido acima, a funo navigateToURL() tem um segundo parmetro - target. O parmetro target pode ser usado para especificar o nome de uma janela ou quadro HTML para o qual enviar a solicitao de URL. Restries de segurana adicionais se aplicam a essas solicitaes, e as restries variaro se navigateToURL() estiver sendo usado como uma instruo de script ou de no-script. Para instrues de script, como navigateToURL("javascript: alert('Hello from Flash Player.')"), as seguintes regras so aplicadas.

Se o arquivo SWF for um arquivo confivel localmente, a solicitao ter xito. Se o destino for a pgina HTML na qual o arquivo SWF est incorporado, as regras de allowScriptAccess
descritas acima sero aplicadas.

Se o destino contiver contedo carregado do mesmo domnio que o arquivo SWF, a solicitao ter xito. Se o destino contiver contedo carregado de um domnio diferente do arquivo SWF, e nenhuma das duas condies
anteriores for atendida, haver falha na solicitao.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1061

Para instrues de no-script (como HTTP, HTTPS e mailto:, haver falha na solicitao se todas as condies a seguir se aplicarem:

O destino uma das palavras-chave "_top" ou "_parent" e o arquivo SWF uma pgina da Web hospedada em um domnio diferente e o arquivo SWF est incorporado com um valor de allowScriptAccess diferente de "always".

Para obter mais informaes

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Para obter mais informaes sobre acesso de URL externas, consulte as entradas a seguir em Referncia do ActionScript 3.0 para a plataforma Adobe Flash:

A funo flash.system.fscommand() O mtodo da classe ExternalInterfacecall() A funo flash.net.navigateToURL()

Objetos compartilhados
Flash Player 9 e posterior, Adobe AIR 1.0 e posterior O Flash Player fornece a capacidade de usar objetos compartilhados que so objetos ActionScript que persistem fora de um arquivo SWF, seja localmente no sistema de arquivos de um usurio ou remotamente em um servidor RTP. Objetos compartilhados, como outras mdias no Flash Player, so particionados em caixas de proteo de segurana. No entanto o modelo de caixa de proteo para objetos compartilhados um pouco diferente porque objetos compartilhados no so recursos que podem ser acessados alm dos limites do domnio. Ao contrrio, os objetos compartilhados sempre so recuperados de um armazenamento de objetos compartilhados que especfico ao domnio de cada arquivo SWF que chama mtodos da classe SharedObject. Normalmente, um objeto compartilhado mais particular do que o domnio de um arquivo SWF: por padro, cada arquivo SWF usa um armazenamento de objetos compartilhados especfico a toda a sua URL de origem. Para obter mais informaes sobre objetos compartilhados, consulte Objetos compartilhados na pgina 687. Um arquivo SWF pode usar o parmetro localPath dos mtodos SharedObject.getLocal() e SharedObject.getRemote() para usar um armazenamento de objetos compartilhados com apenas uma parte de sua URL. Dessa maneira, o arquivo SWF pode permitir o compartilhamento com outros arquivos SWF de outras URLs. Mesmo que voc passe '/' como o parmetro localPath, ele ainda especifica um objeto compartilhado especfico a seu prprio domnio. Os usurios podem restringir o acesso a objetos compartilhados usando a caixa de dilogo Configuraes do Flash Player ou o Gerenciador de configuraes. Por padro, os objetos compartilhados podem ser criados at um mximo de 100 KB de dados por domnio. Usurios administrativos e usurios tambm podem aplicar restries quanto capacidade de gravar no sistema de arquivos. Para obter mais informaes, consulte Controles de administrador na pgina 1034 e Controles de usurio na pgina 1035.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1062

possvel especificar que um objeto compartilhado est protegido especificando true para o parmetro secure do mtodo SharedObject.getLocal() ou do mtodo SharedObject.getRemote(). Observe o seguinte sobre o parmetro secure:

Se esse parmetro for definido como true, o Flash Player criar um novo objeto compartilhado ou obter uma
referncia a um objeto compartilhado protegido existente. Esse objeto compartilhado protegido apenas poder ser lido ou gravado por arquivos SWF entregues via HTTPS que chamarem SharedObject.getLocal() com o parmetro protegido definido como true.

Se esse parmetro for definido como false, o Flash Player criar um novo objeto compartilhado ou obter uma
referncia a um objeto compartilhado existente que pode ser lido ou gravado por arquivos SWF entregues via conexes no-HTTPS. Se o arquivo SWF que faz a chamada no for de uma URL HTTPS, especificar true para o parmetro secure do mtodo SharedObject.getLocal() ou do mtodo SharedObject.getRemote() resultar em uma exceo SecurityError. A opo de armazenamento de um objeto compartilhado tem como base a URL de origem do arquivo SWF. Isso verdadeiro mesmo nas duas situaes em que um arquivo SWF no originrio de uma URL simples: carregamento de importao e carregamento dinmico. O carregamento de importao se refere situao em que voc carrega um arquivo SWF com a propriedade LoaderContext.securityDomain definida como SecurityDomain.currentDomain. Nessa situao, o arquivo SWF carregado ter uma pseudo-URL que comea com o domnio dou arquivo SWF carregado e especifica sua URL de origem real. O carregamento dinmico refere-se ao carregamento de um arquivo SWF usando o mtodo Loader.loadBytes(). Nesta situao, o arquivo SWF carregado ter um pseudo-URL que comea com o URL completo de seu arquivo SWF de carregamento, seguido por um ID de inteiro. Nos casos de carregamento dinmico e e de carregamento de importao, pode-se examinar o pseudo-URL do arquivo SWF usando a propriedade LoaderInfo.url. A pseudo-URL tratada exatamente como uma URL real para a escolha de um armazenamento de objetos compartilhados. possvel especificar o parmetro localPath de um objeto compartilhado que use parte ou toda a pseudo-URL. Usurios e administradores podem optar por desativar o uso de objetos compartilhados de terceiros. Esse o uso de objetos compartilhados por qualquer arquivo SWF que esteja em execuo em um navegador da Web, quando a URL de origem desse arquivo SWF for de um domnio diferente da URL mostrada na barra de endereo do navegador. Usurios e administradores podem optar por desativar o uso de objetos compartilhados de terceiros por motivos de privacidade, com o objetivo de impedir rastreamento entre domnios. Para evitar essa restrio, convm garantir que qualquer arquivo SWF que usa objetos compartilhados seja carregado apenas dentro de estruturas da pgina HTML que garantem que o arquivo SWF se origina do mesmo domnio mostrado na barra de endereo do navegador. Quando voc tenta usar objetos compartilhados de um arquivo SWF de terceiros, e o objeto compartilhado de terceiros est desativado, os mtodos SharedObject.getLocal() e SharedObject.getRemote() retornam null. Para obter mais informaes, consulte www.adobe.com/products/flashplayer/articles/thirdpartylso.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1063

Acesso a cmera, microfone, rea de transferncia, mouse e teclado

Flash Player 9 e posterior, Adobe AIR 1.0 e posterior Quando um arquivo SWF tenta acessar a cmera ou o microfone de um usurio usando os mtodos Camera.get() ou Microphone.get(), o Flash Player exibe a caixa de dilogo Privacidade na qual o usurio pode permitir ou negar acesso sua cmera e microfone. O usurio e o usurio administrativo tambm podem desativar o acesso cmera em uma base por site ou global, por meio de controles no arquivo mms.cfg, da UI de Configuraes e do Gerenciador de configuraes (consulte Controles de administrador na pgina 1034 e Controles de usurio na pgina 1035). Com restries de usurio, cada mtodo Camera.get() e Microphone.get() retorna um valor null. possvel usar a propriedade Capabilities.avHardwareDisable para determinar se a cmera e o microfone foram proibidos (true) ou permitidos (false) administrativamente. O mtodo System.setClipboard() permite que um arquivo SWF substitua o contedo da rea de transferncia por uma string de caracteres de texto simples. Isso no impe nenhum risco de segurana. Para proteo contra o risco imposto por recorte e cpia de senhas e outros dados confidenciais nas reas de transferncia, no h nenhum mtodo getClipboard() correspondente. Um aplicativo executado no Flash Player s pode monitorar eventos de teclado e de mouse que ocorrem dentro de seu foco. O contedo executado no Flash Player no consegue detectar eventos de teclado ou de mouse em outro aplicativo.

Segurana do AIR
Adobe AIR 1.0 e posterior

Noes bsicas de segurana do AIR

Adobe AIR 1.0 e posterior Os aplicativos AIR so executados com as mesmas restries de segurana dos aplicativos nativos. Em geral, aplicativos AIR, como aplicativos nativos, tm amplo acesso aos recursos do sistema operacional, como leitura e gravao de arquivos, inicializao de aplicativos, desenho na tela e comunicao com a rede. As restries do sistema operacional aplicadas aos aplicativos nativos, tais como privilgios especficos do usurio, so aplicadas da mesma forma aos aplicativos AIR. Embora o modelo de segurana do Adobe AIR seja uma evoluo do modelo de segurana do Adobe Flash Player, o contrato de segurana diferente daquele aplicado ao contedo em um navegador. Esse contrato oferece aos desenvolvedores um meio seguro de funcionalidade mais ampla para experincias enriquecedoras com uma liberdade que seria inadequada para um aplicativo baseado em navegador. Os Aplicativos AIR so gravados usando o cdigo de bytes compilado (contedo SWF) ou o script interpretado (JavaScript, HTML) para que o tempo de execuo fornea gerenciamento de memria. Isso minimiza as chances do aplicativo AIR ser afetado pelas vulnerabilidades relacionadas a gerenciamento de memria, como estouro de buffer e corrupo de memria. Essas so algumas das vulnerabilidades mais comuns que afetam os aplicativos de rea de trabalho gravados em cdigo nativo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1064

Instalao e atualizaes
Adobe AIR 1.0 e posterior Os aplicativos AIR so distribudos por arquivos de instalador do AIR que usam a extenso air ou por instaladores nativos, que usam o formato de arquivo e a extenso da plataforma nativa. Por exemplo, o formato do instalador nativo do Windows um arquivo EXE, enquanto o do Android um arquivo APK. Quando o Adobe AIR instalado e um arquivo de instalador do AIR aberto, o tempo de execuo do AIR administra o processo de instalao. Quando um instalador nativo usado, o sistema operacional administra o processo de instalao. Nota: Os desenvolvedores podem especificar um nome de verso e de aplicativo e a origem de editor, mas o prprio fluxo de trabalho inicial de instalao do aplicativo no pode ser modificado. Essa restrio vantajosa para os usurios, pois todos os aplicativos AIR compartilham um procedimento de instalao consistente, otimizado e seguro, administrado pelo tempo de execuo. Se for necessria a personalizao do aplicativo, ela poder ser feita quando o aplicativo for executado pela primeira vez.

Local de instalao do tempo de execuo

Adobe AIR 1.0 e posterior Os aplicativos AIR exigem que, primeiramente, o tempo de execuo esteja instalado no computador do usurio, assim como os arquivos SWF exigem que, primeiramente, o plug-in do navegador do Flash Player esteja instalado. O tempo de execuo instalado no seguinte local em computadores desktop:

Mac OS: /Library/Frameworks/ Windows: C:\Program Linux: /opt/Adobe

Files\Common Files\Adobe AIR

AIR/

No Mac OS, para instalar uma verso atualizada de um aplicativo, o usurio deve ter privilgios adequados do sistema para instalar no diretrio do aplicativo. No Windows e no Linux, um usurio precisa de privilgios administrativos. Nota: No iOS, o tempo de execuo do AIR no instalado separadamente. Cada aplicativo AIR um aplicativo autnomo. O tempo de execuo pode ser instalado de duas maneiras: usando o recurso de instalao direta (instalando diretamente do navegador da Web) ou por meio de instalao manual.

Instalao direta (tempo de execuo e aplicativo)

Adobe AIR 1.0 e posterior O recurso de instalao direta fornece aos desenvolvedores uma experincia de instalao aprimorada para os usurios que ainda no tm o Adobe AIR instalado. No mtodo de instalao direta, o desenvolvedor cria um arquivo SWF que apresenta o aplicativo de instalao. Quando o usurio clica no arquivo SWF para instalar o aplicativo, ele tenta detectar o tempo de execuo. Se o tempo de execuo no puder ser detectado, ele ser instalado e o tempo de execuo ser ativado imediatamente com o processo de instalao do aplicativo do desenvolvedor.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1065

Instalao manual
Adobe AIR 1.0 e posterior Se desejar, o usurio pode fazer o download e a instalao manual do tempo de execuo antes de abrir o arquivo AIR. Em seguida, o desenvolvedor pode distribuir o arquivo AIR por meios diversos (por exemplo, por e-mail ou link HTML em um site da Web). Quando o arquivo AIR aberto, o tempo de execuo inicia o processo de instalao do aplicativo.

Fluxo de instalao do aplicativo

Adobe AIR 1.0 e posterior O modelo de segurana do AIR permite que os usurios decidam se devem instalar o aplicativo AIR . A experincia de instalao do AIR oferece diversas melhorias sobre as tecnologias de instalao de aplicativo nativo, que tornam essa deciso de confiana mais fcil para usurios:

O tempo de execuo fornece uma experincia de instalao consistente em todos os sistemas operacionais, mesmo
quando o aplicativo AIR instalado de um link em um navegador da Web. A maioria das experincias de instalao de aplicativo nativo dependem do navegador ou de outro aplicativo para fornecer informaes de segurana, se de fato elas so fornecidas.

A experincia de instalao do aplicativo AIR identifica a fonte do aplicativo e as informaes sobre que privilgios
esto disponveis para o aplicativo (se o usurio permitir que a instalao continue).

O tempo de execuo administra o processo de instalao de um aplicativo AIR . O aplicativo AIR no pode
manipular o processo de instalao que o tempo de execuo usa. Em geral, os usurios no devem instalar nenhum aplicativo de rea de trabalho vindo de uma fonte no confivel ou que no possa ser verificada. O nus da prova de segurana de aplicativos nativos , da mesma forma, verdadeiro para aplicativos AIR, assim como para outros aplicativos instalveis.

Destino do aplicativo
Adobe AIR 1.0 e posterior O diretrio de instalao pode ser definido usando uma das duas opes a seguir:
1 O usurio personaliza o destino durante a instalao. O aplicativo instalado onde o usurio especificar. 2 Se o usurio no alterar o destino da instalao, o aplicativo ser instalado no caminho padro, conforme

determinado pelo tempo de execuo:

Mac OS: ~/Applications/ Windows XP e anterior: C:\Program Windows Vista: ~/Apps/ Linux: /opt/
Se o desenvolvedor especificar a configurao installFolder no arquivo descritor do aplicativo, o aplicativo ser instalado em um subcaminho desse diretrio.
Files\

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1066

O sistema de arquivos AIR

Adobe AIR 1.0 e posterior O processo de instalao de aplicativos AIR copia todos os arquivos que o desenvolvedor incluiu no arquivo do instalador do AIR para o computador local do usurio. O aplicativo instalado composto de:

Windows: Um diretrio contendo todos os arquivos includos no arquivo do instalador AIR. O tempo de execuo
tambm cria um arquivo exe durante a instalao do aplicativo AIR.

Linux: Um diretrio contendo todos os arquivos includos no arquivo do instalador do AIR. O tempo de execuo
tambm cria um arquivo bin durante a instalao do aplicativo AIR.

Mac OS: Um arquivo app que contm todo o contedo do arquivo do instalador AIR. Ele pode ser inspecionado
usando a opo "Mostrar contedo do pacote" do Localizador. O tempo de execuo cria esse arquivo app como parte da instalao do aplicativo AIR. O aplicativo AIR executado por:

Windows: Execuo do arquivo .exe na pasta de instalao ou um atalho que corresponda a esse arquivo (como um
atalho do menu Iniciar ou rea de trabalho).

Linux: Iniciar o arquivo .bin na pasta de instalao, selecionar o aplicativo no menu Aplicativos ou executar um
alias ou atalho da rea de trabalho.

Mac OS: Execuo do arquivo .app ou um alias que aponte para ele.
O sistema de arquivos do aplicativo tambm inclui subdiretrios relacionados funo do aplicativo. Por exemplo, as informaes gravadas no depsito local criptografado so salvas em um subdiretrio do diretrio nomeado depois do identificador de aplicativo do aplicativo.

Armazenamento de aplicativo AIR

Adobe AIR 1.0 e posterior Os aplicativos AIR tm privilgios de gravao em qualquer local do disco rgido do usurio, contudo, os desenvolvedores so incentivados a usar o caminho app-storage:/ para armazenamento local relacionado aos respectivos aplicativos. Os arquivos gravados em app-storage:/ de um aplicativo ficam localizados em um local padro, dependendo do sistema operacional do usurio:

No Mac OS: o diretrio de armazenamento do aplicativo <appData>/<appId>/Local

Store/ onde <appData>

a pasta "preferncias do usurio", geralmente: /Users/<user>/Library/Preferences

No Windows: o diretrio de armazenamento do aplicativo <appData>\<appId>\Local

Settings\<user>\Application Data

Store\ onde

<appData> a "pasta especial" CSIDL_APPDATA do usurio, geralmente: C:\Documents and

No Linux: <appData>/<appID>/Local

Store/ onde <appData> /home/<user>/.appdata

Voc pode acessar o diretrio de armazenamento do aplicativo atravs da propriedade air.File.applicationStorageDirectory. Voc pode acessar o respectivo contedo usando o mtodo resolvePath() da classe File. Para obter detalhes, consulteTrabalho com o sistema de arquivos na pgina 636.

Atualizao do Adobe AIR

Adobe AIR 1.0 e posterior Quando o usurio instala um aplicativo AIR que requer uma verso atualizada do tempo de execuo, ele instala automaticamente o tempo de execuo atualizado desejado.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1067

Para atualizar o tempo de execuo, o usurio deve ter privilgios administrativos no computador.

Atualizao de aplicativos AIR

Adobe AIR 1.0 e posterior O desenvolvimento e a implantao de atualizaes de software so alguns dos maiores desafios de segurana que os aplicativos de cdigo nativo enfrentam. A API do AIR oferece um mecanismo para melhorar isso: o mtodo Updater.update() pode ser chamado na inicializao para verificar o local remoto de um arquivo AIR. Se a atualizao for adequada, o arquivo AIR baixado, instalado e o aplicativo reiniciado. Os desenvolvedores podem usar essa classe no apenas para oferecer novas funcionalidades, mas tambm para responder a vulnerabilidades potenciais de segurana. A classe Updater pode ser usada somente para atualizar aplicativos distribudos como arquivos do AIR. Aplicativos distribudos como aplicativos nativos precisam usar os recursos de atualizao do sistema operacional nativo, se houver. Nota: Os desenvolvedores podem especificar a verso do aplicativo definindo a propriedade versionNumber do arquivo descritor do aplicativo.

Desinstalao do aplicativo AIR

Adobe AIR 1.0 e posterior Remover o aplicativo AIR remove tambm todos os arquivos no diretrio do aplicativo. No entanto, no remove todos os arquivos que o aplicativo possa ter gravado fora do diretrio do aplicativo. Remover aplicativos AIR no reverte as alteraes que o aplicativo fez nos arquivos fora do diretrio do aplicativo.

Configuraes de Registro do Windows para administradores

Adobe AIR 1.0 e posterior No Windows, os administradores podem configurar o computador para impedir (ou permitir) a instalao de aplicativo AIR e atualizaes do tempo de execuo. Essas configuraes esto contidas no Registro do Windows na seguinte chave: HKLM\Software\Policies\Adobe\AIR. Elas incluem o seguinte:
Configurao do Registro AppInstallDisabled Descrio Especifica se a instalao e a desinstalao do aplicativo AIR permitida. Defina como 0 para permitido, defina como 1 para no permitido. Especifica que ser permitida a instalao de aplicativos AIR no confiveis (aplicativos que no contm um certificado confivel). Defina como 0 para permitido, defina como 1 para no permitido. Especifica se a atualizao do tempo de execuo permitida como uma tarefa de plano de fundo ou como parte de uma instalao explcita. Defina como 0 para permitido, defina como 1 para no permitido.

UntrustedAppInstallDisabled

UpdateDisabled

Segurana HTML no Adobe AIR

Adobe AIR 1.0 e posterior Este tpico descreve a arquitetura de segurana HTML do AIR e como usar iframes, quadros e a ponte da caixa de proteo para configurar aplicativos baseados em HTML e integrar contedo HTML com segurana em aplicativos baseados em SWF.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1068

O tempo de execuo aplica regras e oferece mecanismos para dominar possveis vulnerabilidades de segurana em HTML e JavaScript. As mesmas regras so aplicadas se o aplicativo for gravado principalmente em JavaScript ou se voc carregar contedo HTML e JavaScript em um aplicativo baseado em SWF. Contedo na caixa de proteo do aplicativo e a caixa de proteo de segurana que no seja de aplicativo tm privilgios distintos. Ao carregar o contedo em um iframe ou frame, o tempo de execuo fornece um mecanismo de ponte de caixa de proteo seguro, que permite que o contedo frame ou iframe se comunique de maneira segura com o contedo na caixa de proteo de segurana do aplicativo. O SDK do AIR oferece trs classes para renderizao de contedo HTML. A classe HTMLLoader proporciona integrao entre o cdigo JavaScript e as APIs do AIR. A classe StageWebView uma classe de renderizao de HTML e tem integrao muito limitada com o aplicativo AIR host. O contedo carregado pela classe StageWebView nunca colocado na caixa de proteo de segurana do aplicativo e no pode acessar dados nem chamar funes no aplicativo AIR host. Em plataformas de desktop, a classe StageWebView usa o mecanismo HTML incorporado do AIR, com base no Webkit, que tambm usado pela classe HTMLLoader. Em plataformas mveis, a classe StageWebView usa o controle HTML fornecido pelo sistema operacional. Assim, em plataformas mveis, a classe StageWebView tem as mesmas consideraes e vulnerabilidades de segurana do navegador da Web do sistema. A classe TextField pode exibir strings de texto em HTML. Nenhum JavaScript pode ser executado, mas o texto pode incluir links e imagens carregadas externamente. Para obter mais informaes, consulte Como evitar erros JavaScript relacionados segurana na pgina 969.

Viso geral sobre a configurao de aplicativo baseado em HTML

Adobe AIR 1.0 e posterior Os Frames e iframes oferecem uma estrutura conveniente para organizar contedo HTML no AIR. Os frames oferecem um meio de manter a persistncia de dados e trabalhar de maneira segura com contedo remoto. Como o HTML no AIR retm sua organizao normal baseada em pgina, o ambiente HTML ser totalmente atualizado, caso o frame superior do contedo HTML "navegue" para uma pgina diferente. Voc pode usar frames e iframes para manter a persistncia de dados no AIR, da mesma maneira que em um aplicativo da Web em execuo em um navegador. Defina os objetos principais do aplicativo no frame superior e eles persistiro, desde que voc no permita que o frame navegue para uma nova pgina. Use frames ou iframes filhos para carregar e exibir as partes transitrias do aplicativo. (H diversas maneiras de manter a persistncia de dados, que podem ser usadas alm de ou em vez de frames. Isso inclui cookies, objetos locais compartilhados, armazenamento local de arquivos, depsito de arquivo criptografado e armazenamento de banco de dados local). Como o HTML no AIR retm sua linha desfocada normal entre o cdigo executvel e os dados, o AIR coloca o contedo no quadro superior do ambiente HTML, na caixa de proteo do aplicativo. Depois do evento load da pgina, o AIR restringe quaisquer operaes, como eval(), que possam converter uma seqncia de caracteres de texto em um objeto executvel. Essa restrio aplicada mesmo quando o aplicativo no carrega contedo remoto. Para permitir que o contedo em HTML execute essas operaes restritas, voc deve usar frames ou iframes para colocar o contedo em uma caixa de proteo no-aplicativo. (Executar contedo em um quadro filho de uma caixa de proteo pode ser necessrio ao usar algumas estruturas do aplicativo JavaScript que dependem da funo eval().) Para obter uma lista completa das restries JavaScript na caixa de proteo do aplicativo, consulte Restries de cdigo de contedo em caixas de proteo distintas na pgina 1070.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1069

Como o HTML no AIR mantm a capacidade de carregar contedo remoto possivelmente inseguro, o AIR aplica a poltica de mesma origem que impede que o contedo de um domnio interaja com o contedo de outro domnio. Para permitir a interao entre o contedo do aplicativo e o contedo de outro domnio, voc pode configurar uma ponte para servir como interface entre um frame pai e filho. Configurao de relacionamento pai-filho de caixa de proteo Adobe AIR 1.0 e posterior O AIR adiciona os atributos sandboxRoot e documentRoot aos elementos frame e iframe de HTML. Esses atributos permitem tratar o contedo do aplicativo como se ele tivesse vindo de outro domnio:
Atributo sandboxRoot Descrio A URL que deve ser usada para determinar a caixa de proteo e o domnio em que o contedo do frame deve ser colocado. Os esquemas de URL file:, http: ou https: devem ser usados. A URL da qual o contedo do frame deve ser carregado. Os esquemas de URL
file:, app: ou app-storage: devem ser usados.

documentRoot

O exemplo a seguir mapeia o contedo instalado no subdiretrio da caixa de proteo do aplicativo a ser executado na caixa de proteo remota e o domnio www.exemplo.com:
<iframe src="ui.html" sandboxRoot="http://www.example.com/local/" documentRoot="app:/sandbox/"> </iframe>

Configurao de ponte entre frames pai e filho em caixas de proteo ou domnios distintos Adobe AIR 1.0 e posterior O AIR adiciona as propriedades childSandboxBridge e parentSandboxBridge ao objeto window de qualquer frame filho. Essas propriedades permitem definir pontes para servir como interfaces entre um quadro pai e filho. Cada ponte segue em uma direo:
childSandboxBridge A propriedade childSandboxBridge permite que o frame filho exponha uma interface para o contedo do frame pai. Para expor uma interface, voc define a propriedade childSandbox como funo ou objeto no frame filho. Em seguida, voc pode acessar o objeto ou a funo do contedo no frame pai. O exemplo a seguir mostra como um script que est sendo executado em um frame filho pode expor um objeto contendo uma funo e uma propriedade para o respectivo pai: var interface = {}; interface.calculatePrice = function(){ return .45 + 1.20; } interface.storeID = "abc" window.childSandboxBridge = interface;

Se esse contedo filho estiver em um iframe com id de "child" atribuda, voc poder acessar a interface do contedo pai, lendo a propriedade childSandboxBridge do frame:
var childInterface = document.getElementById("child").childSandboxBridge; air.trace(childInterface.calculatePrice()); //traces "1.65" air.trace(childInterface.storeID)); //traces "abc"

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1070

parentSandboxBridge A propriedade parentSandboxBridge permite que o frame pai exponha uma interface para

o contedo do frame filho. Para expor uma interface, voc define a propriedade parentSandbox do frame filho como funo ou objeto no frame pai. Em seguida, voc pode acessar o objeto ou a funo do contedo no frame filho. O exemplo a seguir mostra como um script em execuo no frame pai pode expor um objeto contendo uma funo save para o filho:
var interface = {}; interface.save = function(text){ var saveFile = air.File("app-storage:/save.txt"); //write text to file } document.getElementById("child").parentSandboxBridge = interface;

Ao usar essa interface, o contedo no frame filho poder salvar texto em um arquivo chamado save.txt. No entanto, ele no ter nenhum outro acesso ao sistema de arquivos. Em geral, o contedo do aplicativo deve expor a interface mais estreita possvel para as outras caixas de proteo. O contedo filho poder chamar a funo save da seguinte maneira:
var textToSave = "A string."; window.parentSandboxBridge.save(textToSave);

Se o contedo filho tentar definir uma propriedade do objeto parentSandboxBridge, o tempo de execuo lanar uma exceo SecurityError. Se o contedo pai tentar definir uma propriedade do objeto childSandboxBridge, o tempo de execuo lanar uma exceo SecurityError.

Restries de cdigo de contedo em caixas de proteo distintas

Adobe AIR 1.0 e posterior Como discutido na introduo deste tpico, Segurana HTML no Adobe AIR na pgina 1067, o tempo de execuo aplica regras e fornece mecanismos para dominar possveis vulnerabilidades de segurana em HTML e JavaScript. Este tpico lista essas restries. Se o cdigo tentar chamar essas APIs restritas, o tempo de execuo lanar um erro com a mensagem "Violao de segurana de tempo de execuo do Adobe AIR para cdigo JavaScript na caixa de proteo de segurana do aplicativo". Para obter mais informaes, consulte Como evitar erros JavaScript relacionados segurana na pgina 969. Restries sobre o uso da funo eval() de JavaScript e tcnicas semelhantes Adobe AIR 1.0 e posterior Para contedo HTML na caixa de proteo de segurana do aplicativo h limitaes no uso das APIs que podem transformar dinamicamente as strings em cdigo executvel aps o carregamento do cdigo (aps o evento onload do elemento body ter sido despachado e o trmino de execuo da funo do manipulador onload). Isso para evitar que o aplicativo injete inadvertidamente (e execute) cdigo de fontes "no-aplicativo" (como domnios de rede potencialmente inseguros). Por exemplo, se o aplicativo usa strings de dados de uma fonte remota para gravar na propriedade innerHTML de um elemento DOM, a string pode incluir o cdigo (JavaScript) executvel que pode executar operaes inseguras. No entanto, enquanto o contedo estiver carregando, no h risco de inserir strings remotas no DOM.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1071

Uma restrio est no uso da funo eval() de JavaScript. Aps o cdigo na caixa de proteo do aplicativo tiver sido carregado e aps o processamento do manipulador de eventos onload, voc s poder usar a funo eval() de forma limitada. As seguintes regras se aplicam ao uso da funo eval()aps o cdigo ter sido carregado da caixa de proteo de segurana do aplicativo:

So permitidas expresses que envolvem literais. Por exemplo:

eval("null"); eval("3 + .14"); eval("'foo'");

As literais de objeto so permitidos da seguinte maneira:

{ prop1: val1, prop2: val2 }

As opes setter/getters de literal de objeto so proibidas, conforme segue:

{ get prop1() { ... }, set prop1(v) { ... } }

As literais de matriz so permitidas da seguinte maneira:

[ val1, val2, val3 ]

Expresses que envolvem leituras de propriedades so proibidas, conforme segue:

a.b.c

A chamada de funo proibida. Definies de funo so proibidas. A configurao de qualquer propriedade proibida. As literais de funo so proibidas.
No entanto, enquanto o cdigo estiver sendo carregado, antes do evento onload e durante a execuo da funo do manipulador de eventos onload, essas restries no sero aplicadas ao contedo na caixa de proteo de segurana do aplicativo. Por exemplo, aps o cdigo ser carregado, o cdigo a seguir resultar no lanamento de uma exceo pelo tempo de execuo.
eval("alert(44)"); eval("myFunction(44)"); eval("NativeApplication.applicationID");

O cdigo gerado dinamicamente, como o que feito durante a chamada da funo eval(), representaria um risco segurana se permitido na caixa de proteo do aplicativo. Por exemplo, um aplicativo pode executar inadvertidamente uma string carregada de um domnio de rede e essa string pode conter cdigo mal-intencionado. Por exemplo, esse pode ser um cdigo de excluso ou alterao de arquivos no computador do usurio. Ou pode ser um cdigo que informa o contedo de um arquivo local para um domnio de rede no confivel. As formas de gerar cdigo dinmico so as seguintes:

Chamando a funo eval(). Uso de propriedades innerHTML ou funes DOM para inserir tags de script que carregam um script de fora do
diretrio do aplicativo.

Uso de propriedades innerHTML ou funes DOM para inserir tags de scripts com cdigo inline (em vez de carregar
um script atravs do atributo src).

Configurao do atributo src para que a tag de script carregue um arquivo JavaScript que est fora do diretrio
do aplicativo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1072

Uso de esquema de URL javascript (como em href="javascript:alert('Test')"). Uso da funo setInterval() ou setTimout() em que o primeiro parmetro (que define a funo para ser
executada de forma assncrona) uma string (a ser avaliada) em vez de um nome de funo (como em setTimeout('x = 4', 1000)).

Chamada de document.write() ou document.writeln().

O cdigo na caixa de proteo de segurana do aplicativo s pode usar esses mtodos enquanto o contedo estiver sendo carregado. Essas restries no impedem o uso de eval() com literais do objeto JSON. Isso permite que o contedo do aplicativo trabalhe com a biblioteca JavaScript JSON. No entanto, voc no poder usar cdigo JSON sobrecarregado (com manipuladores de eventos) Em outras estruturas Ajax e bibliotecas de cdigo JavaScript, certifique-se de que o cdigo na estrutura ou biblioteca funciona dentro dessas restries em cdigo gerado dinamicamente. Se no funcionarem, inclua algum contedo que use a estrutura ou biblioteca em uma caixa de proteo de segurana "no-aplicativo". Consulte detalhes em Restries a JavaScript dentro do AIR na pgina 1031 e Script entre contedo de aplicativo e "no-aplicativo" na pgina 1080. O Adobe mantm uma lista das estruturas Ajax conhecidas por oferecer suporte caixa de proteo de segurana do aplicativo, em http://www.adobe.com/products/air/develop/ajax/features/. Ao contrrio do contedo na caixa de proteo de segurana do aplicativo, o contedo JavaScript em uma caixa de proteo de segurana "no-aplicativo" pode chamar a funo eval() para executar cdigo gerado dinamicamente a qualquer momento. Restries de acesso s APIs do AIR (para caixas de proteo que no so de aplicativo) Adobe AIR 1.0 e posterior O cdigo JavaScript em uma caixa de proteo "no-aplicativo" no tem acesso ao objeto window.runtime e, portanto, esse cdigo no pode executar APIs do AIR. Se o contedo em uma caixa de proteo de segurana "no-aplicativo" chamar o cdigo a seguir, o aplicativo lanar uma exceo TypeError:
try { window.runtime.flash.system.NativeApplication.nativeApplication.exit(); } catch (e) { alert(e); }

O tipo de exceo TypeError (valor indefinido), porque o contedo na caixa de proteo "no-aplicativo" no reconhece o objeto window.runtime, portanto, ele considerado como valor indefinido. Voc pode expor a funcionalidade de tempo de execuo ao contedo em uma caixa de proteo "no-aplicativo" usando uma ponte de script. Para obter detalhes, consulte Script entre contedo de aplicativo e "no-aplicativo" na pgina 1080. Restries no uso de chamadas XMLHttpRequest Adobe AIR 1.0 e posterior O contedo HTML na caixa de proteo de segurana do aplicativo no pode usar os mtodos XMLHttpRequest sncronos para carregar dados de fora da caixa de proteo do aplicativo enquanto o contedo HTML estiver sendo carregado e durante o evento onLoad.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1073

Por padro, o contedo HTML nas caixas de proteo de segurana "no-aplicativo" no tm permisso para usar o objeto XMLHttpRequest de JavaScript para carregar dados de outros domnios que no o domnio que est chamando a solicitao. A tag frame ou iframe pode incluir um atributo allowcrosscomainxhr. Configurar esse atributo com qualquer valor diferente de "null" permite que o contedo no frame ou iframe use o objeto XMLHttpRequest de Javascript para carregar dados de outros domnios que no sejam o domnio do cdigo que est chamando a solicitao:
<iframe id="UI" src="http://example.com/ui.html" sandboxRoot="http://example.com/" allowcrossDomainxhr="true" documentRoot="app:/"> </iframe>

Para obter mais informaes, consulte Script entre contedos em domnios distintos na pgina 1074. Restries no carregamento de elementos CSS, frame, iframe e img (para contedo em caixas de proteo que no so de aplicativo) Adobe AIR 1.0 e posterior O contedo HTML nas caixas de proteo de segurana remota (rede) pode carregar apenas contedo CSS, frame, iframe e img de caixas de proteo remotas (de URLs de rede). O contedo HTML nas caixas de proteo local com sistema de arquivos, local com rede ou local confivel s podem carregar contedo CSS, frame, iframe e img de caixas de proteo locais (e no de caixas de proteo de aplicativo ou remotas). Restries na chamada do mtodo window.open() de JavaScript Adobe AIR 1.0 e posterior Se a janela criada atravs de uma chamada para o mtodo window.open() de JavaScript exibir contedo de uma caixa de proteo de segurana "no-aplicativo", o ttulo da janela iniciar com o ttulo da janela principal (inicializada), seguido pelo caractere dois pontos. Voc no pode usar cdigo para remover da tela essa parte do ttulo da janela. O contedo nas caixas de proteo de segurana "no-aplicativo" s consegue chamar com xito o mtodo
window.open() de JavaScript em resposta a um evento acionado pelo mouse do usurio ou pela interao do teclado.

Isso evita que o contedo "no-aplicativo" crie janelas que possam ser usadas de maneira enganosa (por exemplo, em ataques de phishing). Alm disso, o manipulador de eventos do evento de mouse ou teclado no pode configurar o mtodo window.open() para ser executado aps um atraso (por exemplo, chamando a funo setTimeout()). O contedo nas caixas de proteo remotas (rede) s podem usar o mtodo window.open() para abrir o contedo nas caixas de proteo de rede remota. Ele no pode usar o mtodo window.open() para abrir o contedo das caixas de proteo locais ou do aplicativo. O contedo nas caixas de proteo local com sistema de arquivos, local com rede ou local confivel (consulte Caixas de proteo de segurana na pgina 1029 ) s pode usar o mtodo window.open() para abrir o contedo nas caixas de proteo locais. Ele no pode usar o mtodo window.open() para abrir o contedo das caixas de proteo remotas ou do aplicativo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1074

Erros na chamada de cdigo restrito Adobe AIR 1.0 e posterior Se voc chamar um cdigo com uso restrito em uma caixa de proteo, devido a essas restries de segurana, o tempo de execuo despachar um erro de JavaScript: "Violao de segurana de tempo de execuo do Adobe AIR para cdigo JavaScript na caixa de proteo de segurana do aplicativo." Para obter mais informaes, consulte Como evitar erros JavaScript relacionados segurana na pgina 969.

Proteo da caixa de proteo ao carregar contedo HTML de uma seqncia de caracteres

Adobe AIR 1.0 e posterior O mtodo loadString() da classe HTMLLoader permite criar contedo HTML no tempo de execuo. No entanto, os dados usados como contedo HTML podem ser corrompidos se forem carregados de uma fonte de Internet insegura. Por esse motivo, por padro, o HTML criado com o mtodo loadString() no colocado na caixa de proteo do aplicativo e no tem acesso s APIs do AIR. Entretanto, voc pode definir a propriedade placeLoadStringContentInApplicationSandbox de um objeto HTMLLoader como true para inserir o HTML criado usando o mtodo loadString() na caixa de proteo do aplicativo. Para obter mais informaes, consulte Carregamento de contedo HTML de uma sequncia de caracteres na pgina 968.

Script entre contedos em domnios distintos

Adobe AIR 1.0 e posterior Aplicativos AIR recebem privilgios especiais quando so instalados. fundamental que os mesmos privilgios no vazem para outro contedo, incluindo arquivos remotos e arquivos locais que no fazem parte do aplicativo.

Sobre a ponte de caixa de proteo do AIR

Adobe AIR 1.0 e posterior Normalmente, o contedo de outros domnios no pode chamar scripts de outros domnios. Para proteger os aplicativos AIR de vazamentos acidentais de informaes privilegiadas ou de controle, as restries a seguir so colocadas no contedo na caixa de proteo de segurana do aplicativo (contedo instalado com o aplicativo):

O cdigo na caixa de proteo de segurana do aplicativo no pode permitir que outras caixas de proteo chamem
o mtodo Security.allowDomain(). Chamar esse mtodo de uma caixa de proteo de segurana do aplicativo gerar um erro.

Evita-se importar contedo "no-aplicativo" da caixa de proteo do aplicativo, definindo a propriedade

LoaderContext.securityDomain ou LoaderContext.applicationDomain.

Ainda h casos em que o aplicativo principal do AIR requer que o contedo de um domnio remoto tenha acesso controlado a scripts no aplicativo principal do AIR ou vice-versa. Para fazer isso, o tempo de execuo oferece o mecanismo ponte de caixa de proteo, que serve como gateway entre as duas caixas de proteo. A ponte de caixa de proteo pode oferecer interao explcita entre as caixas de proteo de segurana do aplicativo e remota. A ponte de caixa de proteo expe dois objetos que os scripts, carregados e em carregamento, podem acessar:

O objeto parentSandboxBridge permite carregar propriedades e funes de exposio de contedo para scripts
no contedo carregado.

O objeto childSandboxBridge permite que o contedo carregado exponha propriedades e funes para scripts no
contedo que est em carregamento.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1075

Os objetos expostos atravs da ponte de caixa de proteo so passadas por valor e no por referncia. Todos os dados so serializados. Isso significa que os objetos expostos de um lado da ponte no podem ser definidos pelo outro lado da ponte e que os objetos expostos so todos sem categoria. Alm disso, voc pode expor objetos e funes simples, voc no pode expor objetos complexos. Se o contedo filho tentar definir uma propriedade do objeto parentSandboxBridge, o tempo de execuo lanar uma exceo SecurityError. Da mesma forma, se o contedo pai tentar definir uma propriedade do objeto childSandboxBridge, o tempo de execuo lanar uma exceo SecurityError.

Exemplo de ponte de caixa de proteo (SWF)

Adobe AIR 1.0 e posterior Suponhamos que um aplicativo de armazenamento de msica do AIR deseja permitir que arquivos remotos SWF transmitam preos de lbuns, mas no deseja que o arquivo remoto SWF divulgue se preo de venda. Para fazer isso, a classe StoreAPI oferece um mtodo para adquirir o preo, mas ocultar o preo de venda. Em seguida, atribuda uma ocorrncia dessa classe StoreAPI propriedade parentSandboxBridge do objeto LoaderInfo do objeto Loader que carrega o SWF remoto. A seguir est o cdigo para armazenamento de msica do AIR:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1076

<?xml version="1.0" encoding="utf-8"?> <mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" title="Music Store" creationComplete="initApp()"> <mx:Script> import flash.display.Loader; import flash.net.URLRequest; private var child:Loader; private var isSale:Boolean = false; private function initApp():void { var request:URLRequest = new URLRequest("http://[www.yourdomain.com]/PriceQuoter.swf") child = new Loader(); child.contentLoaderInfo.parentSandboxBridge = new StoreAPI(this); child.load(request); container.addChild(child); } public function getRegularAlbumPrice():String { return "$11.99"; } public function getSaleAlbumPrice():String { return "$9.99"; } public function getAlbumPrice():String { if(isSale) { return getSaleAlbumPrice(); } else { return getRegularAlbumPrice(); } } </mx:Script> <mx:UIComponent id="container" /> </mx:WindowedApplication>

O objeto StoreAPI chama o aplicativo principal para recuperar o preo regular do lbum, mas retorna "No disponvel" quando o mtodo getSaleAlbumPrice() chamado. O cdigo a seguir define a classe StoreAPI:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1077

public class StoreAPI { private static var musicStore:Object; public function StoreAPI(musicStore:Object) { this.musicStore = musicStore; } public function getRegularAlbumPrice():String { return musicStore.getRegularAlbumPrice(); } public function getSaleAlbumPrice():String { return "Not available"; } public function getAlbumPrice():String { return musicStore.getRegularAlbumPrice(); } }

O seguinte cdigo representa um exemplo de um arquivo PriceQuoter SWF que informa o preo da loja, mas no pode informar o preo de venda:
package { import flash.display.Sprite; import flash.system.Security; import flash.text.*; public class PriceQuoter extends Sprite { private var storeRequester:Object; public function PriceQuoter() { trace("Initializing child SWF"); trace("Child sandbox: " + Security.sandboxType); storeRequester = loaderInfo.parentSandboxBridge; var tf:TextField = new TextField(); tf.autoSize = TextFieldAutoSize.LEFT; addChild(tf); tf.appendText("Store price of album is: " + storeRequester.getAlbumPrice()); tf.appendText("\n"); tf.appendText("Sale price of album is: " + storeRequester.getSaleAlbumPrice()); } } }

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1078

Exemplo de ponte de caixa de proteo (HTML)

Adobe AIR 1.0 e posterior No contedo HTML, as propriedades parentSandboxBridge e childSandboxBridge so adicionados ao objeto de janela de JavaScript de um documento filho. Para obter um exemplo sobre como definir funes de ponte em contedo HTML, consulte Configurao de interface de ponte de caixa de proteo na pgina 987.

Limitao de exposio de API

Adobe AIR 1.0 e posterior Ao expor pontes de caixa de proteo, importante expor APIs de alto nvel que limitem o grau em que podem ser abusadas. Lembre-se de que o contedo que chama a implementao da ponte pode estar comprometido (por exemplo, atravs de uma injeo de cdigo). Portanto, por exemplo, expor um mtodo readFile(path:String) (que l o contedo de um arquivo arbitrrio) atravs de uma ponte, estar vulnervel a abusos. Talvez seja melhor expor uma API readApplicationSetting() que no siga um caminho e leia um arquivo especfico. A abordagem mais semntica limita o dano que o aplicativo pode causar, j que parte dele est comprometida.

Mais tpicos da Ajuda

Contedo cross-scripting em caixas de proteo de segurana distintas na pgina 986 A caixa de proteo do aplicativo AIR na pgina 1030

Gravao em disco
Adobe AIR 1.0 e posterior Os aplicativos em execuo em um navegador da Web s tm interao limitada com o sistema de arquivos local do usurio. Os navegadores da Web implementam polticas de segurana que garantem que o computador do usurio no pode ser comprometido como resultado do carregamento de contedo da Web. Por exemplo, os arquivos SWF executados por meio do Flash Player em um navegador no podem interagir diretamente com os arquivos existentes no computador do usurio. Os objetos compartilhados e os cookies podem ser gravados no computador do usurio com a finalidade de manter as preferncias do usurio e outros dados, mas esse o limite de interao do sistema de arquivos. Como os aplicativos AIR so instalados de forma nativa, eles tm contratos de segurana diferentes, um dos quais inclui a capacidade de leitura e gravao no sistema de arquivos local. Essa liberdade resulta em bastante responsabilidade para os desenvolvedores A falta de segurana acidental do aplicativo coloca em risco no apenas a funcionalidade do aplicativo, mas tambm a integridade do computador do usurio. Por esse motivo, os desenvolvedores devem ler as Prticas recomendadas de segurana para desenvolvedores na pgina 1081. Os desenvolvedores do AIR podem acessar e gravar arquivos no sistema de arquivos local usando diversas convenes de esquema de URL:

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1079

esquema de URL app:/

Descrio Um alias para o diretrio do aplicativo. Aos arquivos acessados desse caminho so atribudas caixas de proteo do aplicativo e eles tm todos os privilgios concedidos pelo tempo de execuo. Um alias para o diretrio de armazenamento local, padronizado pelo tempo de execuo. Aos arquivos acessados desse caminho atribuda uma caixa de proteo "no-aplicativo". Um alias que representa a raiz do disco rgido do usurio. Ao arquivo acessado desse caminho atribuda uma caixa de proteo do aplicativo, se o arquivo estiver no diretrio do aplicativo e, caso contrrio, uma caixa de proteo "no-aplicativo".

app-storage:/

file:///

Nota: Os aplicativos AIR no podem modificar o contedo que usa o app: esquema de URL. Alm disso, o diretrio do aplicativo pode ser lido somente devido s configuraes do administrador. A menos que haja restries do administrador para o computador do usurio, os aplicativos AIR tm privilgio de gravao em qualquer local no disco rgido do usurio, Recomenda-se que os desenvolvedores usem o caminho appstorage:/ para armazenamento local em relao ao aplicativo. Os arquivos gravados em app-storage:/ de um aplicativo so colocados em um local padro:

No Mac OS: o diretrio de armazenamento do aplicativo <appData>/<appId>/Local

Store/ onde <appData>

a pasta Preferncias do usurio, que normalmente /Users/<user>/Library/Preferences

No Windows: o diretrio de armazenamento do aplicativo <appData>\<appId>\Local

Settings\<userName>\Application Data

Store\ onde

<appData> a pasta especial CSIDL_APPDATA do usurio, que normalmente C:\Documents and

No Linux: <appData>/<appID>/Local

Store/ onde <appData> /home/<user>/.appdata

Se o aplicativo for desenvolvido para interagir com os arquivos existentes no sistema de arquivos do usurio, certifique-se de ler as Prticas recomendadas de segurana para desenvolvedores na pgina 1081.

Trabalho seguro com contedo no confivel

Adobe AIR 1.0 e posterior O contedo no atribudo caixa de proteo do aplicativo pode oferecer funcionalidade adicional de script ao aplicativo, mas somente se ele atender aos critrios de segurana do tempo de execuo. Este tpico explica o contrato de segurana do AIR com contedo "no-aplicativo".

Security.allowDomain()
Adobe AIR 1.0 e posterior Os aplicativos AIR restringem o acesso de script de contedo "no-aplicativo" com mais rigor do que o plug-in de navegador do Flash Player restringe o acesso de script de contedo no confivel. Por exemplo, no Flash Player, no navegador, quando um arquivo SWF atribudo caixa de proteo local-trusted chama o mtodo System.allowDomain(), todos os SWF carregados do domnio especificado recebero acesso de script. No permitida a abordagem anloga do contedo do aplicativo nos aplicativos AIR, j que ela concederia acesso excesso no razovel ao arquivo "no-aplicativo" no sistema de arquivos do usurio. Os arquivos remotos no podem acessar diretamente a caixa de proteo do aplicativo, independentemente das chamadas para o mtodoSecurity.allowDomain().

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1080

Script entre contedo de aplicativo e "no-aplicativo"

Adobe AIR 1.0 e posterior Os aplicativos AIR que fazem script entre contedo aplicativo e "no-aplicativo" tm organizaes de segurana mais complexas. Os arquivos que no esto na caixa de proteo do aplicativo s tm permisso para acessar propriedades e mtodos de aplicativos na caixa de proteo do aplicativo por meio do uso de uma ponte de caixa de proteo. A ponte da caixa de proteo atua como gateway entre o contedo do aplicativo e "no-aplicativo", oferecendo interao explcita entre os dois arquivos. Quando usadas corretamente, as pontes de caixa de proteo oferecem uma camada extra de segurana, impedindo o contedo "no-aplicativo" de acessar as referncias de objeto que fazem parte do contedo do aplicativo. O benefcio das pontes de caixa de proteo ilustrado melhor atravs do exemplo. Suponhamos que um aplicativo de armazenamento de msica do AIR deseja fornecer uma API para anunciantes que desejam criar seus prprios arquivos SWF, com o qual o aplicativo de armazenamento poder se comunicar em seguida. A loja deseja fornecer aos anunciantes mtodos de pesquisa de artistas e CDs, mas tambm deseja isolar alguns mtodos e propriedades do arquivo SWF terceirizado, por motivos de segurana. A ponte de caixa de proteo pode propiciar essa funcionalidade. Por padro, o contedo carregado externamente em um aplicativo AIR em tempo de execuo no tem acesso a nenhum mtodo ou propriedade no aplicativo principal. Com a implementao da ponte de caixa de proteo personalizada, o desenvolvedor pode fornecer servios ao contedo remoto sem expor esses mtodos ou propriedades. Considere a ponte de caixa de proteo como um caminho entre o contedo confivel e o no confivel, oferecendo comunicao entre o contedo carregado e o do carregador sem expor as referncias do objeto. Para obter mais informaes sobre como usar pontes de caixa de proteo de forma segura, consulte Script entre contedos em domnios distintos na pgina 1074.

Proteo contra contedo SWF inseguro gerado dinamicamente.

Adobe AIR 1.0 e posterior O mtodo Loader.loadBytes() oferece uma maneira de o aplicativo gerar contedo SWF de uma matriz de bytes. No entanto, ataques de injeo em dados carregados de fontes remotas podem causar dano grave ao carregar o contedo. Isso particularmente verdadeiro ao carregar dados na caixa de proteo do aplicativo, onde o contedo SWF gerado pode acessar o conjunto completo de APIs do AIR. H usos vlidos para a utilizao do mtodo loadBytes() sem gerar um cdigo SWF executvel. Voc pode usar o mtodo loadBytes() para gerar dados de imagem para controlar o tempo de exibio de imagem, por exemplo. H tambm usos vlidos que dependem do cdigo de execuo, como a criao dinmica de contedo SWF para reproduo de udio. No AIR, por padro, o mtodo loadBytes()no permite carregar contedo SWF, ele s permite carregar contedo de imagem. No AIR, a propriedade loaderContext do mtodo loadBytes() tem uma propriedade allowLoadBytesCodeExecution, que voc pode definir como true para permitir explicitamente que o aplicativo use loadBytes() para carregar o contedo SWF executvel. O cdigo a seguir mostra como usar esse recurso:
var loader:Loader = new Loader(); var loaderContext:LoaderContext = new LoaderContext(); loaderContext.allowLoadBytesCodeExecution = true; loader.loadBytes(bytes, loaderContext);

Se voc chamar loadBytes() para carregar contedo SWF e a propriedade allowLoadBytesCodeExecution do objeto LoaderContext estiver definida como false (o padro), o objeto Loader lanar uma exceo SecurityError.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1081

Nota: Em um lanamento futuro do Adobe AIR, essa API pode ser alterada. Quando isso ocorre, talvez seja necessrio recompilar o contedo que usa a propriedade allowLoadBytesCodeExecution da classe LoaderContext.

Prticas recomendadas de segurana para desenvolvedores

Adobe AIR 1.0 e posterior Embora os aplicativos AIR sejam criados usando tecnologias da Web, importante para os desenvolvedores observar que eles no trabalham na caixa de proteo de segurana do navegador. Isso significa que possvel criar aplicativos AIR que podem danificar o sistema local de maneira intencional ou no intencional. O AIR tenta minimizar esse risco, mais ainda h formas em que as vulnerabilidades podem ser introduzidas. Este tpico cobre faltas de segurana potenciais importantes.

Risco de importar arquivos para a caixa de proteo de segurana do aplicativo

Adobe AIR 1.0 e posterior Os arquivos existentes no diretrio do aplicativo esto atribudos caixa de proteo do aplicativo e tm privilgios completos de tempo de execuo. Recomenda-se aos aplicativos que gravam no sistema de arquivos local gravar no app-storage:/. Esse diretrio est separado dos arquivos do aplicativo no computador do usurio, por isso os arquivos no esto atribudos na caixa de proteo do aplicativo e representam risco reduzido de segurana. Recomenda-se aos desenvolvedores que considerem o seguinte:

Somente incluir um arquivo em um arquivo do AIR (no aplicativo instalado) se for necessrio. Somente incluir um arquivo em um arquivo do AIR (no aplicativo instalado) se o respectivo comportamento for
completamente compreensvel e confivel.

No grave nem modifique contedo no diretrio do aplicativo. O tempo de execuo impede que aplicativos
gravem ou modifiquem arquivos e diretrios que usam o esquema de URL app:/, lanando uma exceo SecurityError.

No use dados de uma fonte de rede como parmetros de mtodos da API do AIR que possam conduzir a execuo
de cdigo. Isso inclui o uso do mtodo Loader.loadBytes() e a funo eval() de JavaScript.

Risco de uso de fonte externa para determinar caminhos

Adobe AIR 1.0 e posterior O aplicativo AIR pode estar com o uso de dados ou contedo externo comprometido. Por esse motivo, tenha cuidado especial ao usar dados da rede ou do sistema de arquivos. O nus da confiana, depende em ltima anlise do desenvolvedor e das conexes de rede que eles fazem, mas carregar dados externos inerentemente arriscado e no deve ser usado em inseres de operaes confidenciais. Recomenda-se aos desenvolvedores o seguinte:

Usar dados de uma fonte de rede para determinar o nome de arquivo Usar dados de uma fonte de rede para construir uma URL que o aplicativo use para enviar informaes particulares

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1082

O risco de usar, armazenar ou transmitir credenciais no seguras

Adobe AIR 1.0 e posterior Armazenar credenciais do usurio no sistema de arquivos local do usurio introduz inerentemente o risco de que essas credenciais possam estar comprometidas. Recomenda-se aos desenvolvedores que considerem o seguinte:

Se credenciais devem ser armazenadas localmente, criptografe as credenciais ao grav-las no sistema de arquivos
local. O tempo de execuo oferece um armazenamento criptografado exclusivo para cada aplicativo instalado, atravs da classe EncryptedLocalStore. Para ver detalhes, consulte Armazenamento local criptografado na pgina 696.

No transmita credenciais do usurio no criptografadas em uma fonte de rede, a menos que essa fonte seja
confivel.

Nunca especifique uma senha padro na criao de credencial: deixe que os usurios criem suas prprias senhas.
Usurios que mantm o padro inalterado expem as respectivas credenciais ao invasor que j conhece a senha padro.

Risco de um ataque de downgrade

Adobe AIR 1.0 e posterior Durante a instalao do aplicativo, o tempo de execuo certifica-se de que no haja uma verso do aplicativo instalada atualmente. Se o aplicativo j estiver instalado, o tempo de execuo compara a string da verso em relao verso que est sendo instalada. Se essa string for diferente, o usurio poder optar por atualizar a instalao. O tempo de execuo no garante que a verso instalada recentemente seja mais recente que a verso anterior, apenas que seja diferente. O invasor pode distribuir uma verso anterior para o usurio, para contornar uma falha de segurana. Por esse motivo, recomenda-se que o desenvolvedor verifique as verses quando o aplicativo for executado. uma boa idia fazer com que os aplicativos verifiquem a rede em busca de atualizaes necessrias. Dessa maneira, mesmo se um invasor fizer com que o usurio execute uma verso anterior, essa verso anterior ir reconhecer que necessrio atualizar. Alm disso, usar um esquema de verso bem-definido no aplicativo torna mais difcil enganar os usurios para que instalem uma verso desatualizada.

Assinatura de cdigo
Adobe AIR 1.0 e posterior Todos os arquivos do instalador do AIR so obrigatrios para assinatura de cdigo. A assinatura de cdigo um processo criptogrfico para confirmar que a origem especificada do software precisa. Os aplicativos AIR podem ser assinados por um certificado emitido por uma autoridade de certificao (CA) externa ou por um certificado autoassinado que voc tenha criado. Recomenda-se fortemente um certificado comercial de uma CA bem conhecida que oferea segurana a seus usurios de que esto instalando o aplicativo original e no uma falsificao. No entanto, certificados auto-assinados podem ser criados com adt do SDK ou com o Flash, Flash Builder ou outro aplicativo que utilize adt para gerao de certificados. Os certificados autoassinados no garantem a legitimidade do aplicativo que estiver sendo instalado e devem ser usados apenas para testar um aplicativo antes da distribuio ao pblico.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1083

Segurana em dispositivos Android

Adobe AIR 2.5 e posterior No Android, como em todos os dispositivos de computao, o AIR se conforma com o modelo de segurana nativo. Ao mesmo tempo, o AIR mantm suas prprias regras de segurana, que se destinam a facilitar aos desenvolvedores a programao de aplicativos seguros conectados Internet. Visto que aplicativos AIR no Android usam o formato de pacote do Android, a instalao se ajusta ao modelo de segurana do Android. O instalador de aplicativo do AIR no usado. O modelo de segurana do Android tem trs aspectos principais:

Permisses Assinaturas do aplicativo IDs de usurio do aplicativo

Permisses do Android Muitos recursos do Android so protegidos pelo mecanismo de permisses do sistema operacional. A fim de usar um recurso protegido, o descritor do aplicativo AIR precisa declarar que o aplicativo requer a permisso necessria. Quando um usurio tenta instalar o aplicativo, o sistema operacional Android exibe todas as permisses solicitadas ao usurio antes de continuar com a instalao. A maioria dos aplicativos AIR precisam especificar as permisses do Android no descritor do aplicativo. Por padro, nenhuma permisso includa. As seguintes permisses so necessrias para recursos protegidos do Android expostos pelo tempo de execuo do AIR:
ACCESS_COARSE_LOCATION Permite ao aplicativo acessar dados de local de rede WIFI e celular por meio da classe

Geolocation.
ACCESS_FINE_LOCATION Permite ao aplicativo acessar dados GPS por meio da classe Geolocation. ACCESS_NETWORK_STATE and ACCESS_WIFI_STATE Permite ao aplicativo acessar informaes de rede por meio da

classe NetworkInfo.
CAMERA Permite ao aplicativo acessar a cmera. INTERNET Permite ao aplicativo fazer solicitaes de rede, alm de permitir a depurao remota. READ_PHONE_STATE Permite ao tempo de execuo do AIR silenciar o udio quando uma chamada recebida. RECORD_AUDIO Permite ao aplicativo acessar o microfone. WAKE_LOCK e DISABLE_KEYGUARD Permite ao aplicativo impedir que o dispositivo entre no modo de suspenso por meio do uso das configuraes da classe SystemIdleMode. WRITE_EXTERNAL_STORAGE Permite ao aplicativo gravar no carto de memria externo no dispositivo.

Assinaturas do aplicativo Todos os pacotes de aplicativos criados para a plataforma Android precisam ser assinados. Visto que os aplicativos AIR no Android so empacotados no formato APK nativo do Android, eles so assinados de acordo com as convenes do Android, e no com as convenes do AIR. Embora o Android e o AIR usem a assinatura de cdigo de forma semelhante, h trs diferenas significativas:

No Android, a assinatura verifica se o desenvolvedor est de posse da chave privada, mas no usada para verificar
a identidade do desenvolvedor.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Segurana

1084

Para aplicativos enviados ao Android Market, o certificado precisa ser vlido por pelo menos 25 anos. O Android no oferece suporte a migrao da assinatura do pacote para outro certificado. Se uma atualizao for
assinada por um certificado diferente, os usurios precisam instalar o aplicativo original para poderem instalar o aplicativo atualizado.

Dois aplicativos assinados com o mesmo certificado podem especificar uma ID compartilhada que permita a eles
acessar o cache e os arquivos de dados um do outro. (Esse compartilhamento no facilitado pelo AIR. ) IDs de usurio do aplicativo O Android usa um ncleo do Linux. A cada aplicativo instalado atribuda uma ID de usurio do tipo do Linux que determina suas permisses para operaes como acesso a arquivos. Os arquivos no aplicativo, o armazenamento do aplicativo e os diretrios temporrios so protegidos contra o acesso por permisses do sistema de arquivos. Arquivos programados para armazenamento externo (em outras palavras, o carto SD) podem ser lidos, modificados ou excludos por outros aplicativos ou pelo usurio quando o carto SD montado como dispositivo de armazenamento em massa em um computador. Cookies recebidos com solicitaes da Internet no so compartilhados entre aplicativos AIR.

Mais tpicos da Ajuda

Android: segurana e permisses

Dados criptografados no Android

Aplicativos AIR no Android podem usar as opes de criptografia disponveis no banco de dados SQL incorporado para salvar dados criptografados. No h suporte para a classe EncryptedLocalStore em dispositivos mveis.

Segurana em dispositivos iOS

No iOS, o AIR se adapta ao modelo de segurana nativo. Ao mesmo tempo, o AIR mantm suas prprias regras de segurana, que se destinam a facilitar aos desenvolvedores a programao de aplicativos seguros conectados Internet. Visto que os aplicativos do AIR no Android usam o formato de pacote do Android, a instalao se ajusta ao modelo de segurana do iOS. O instalador de aplicativo do AIR no usado. Alm disso, um tempo de execuo separado do AIR no usado em dispositivos iOS. Todos aplicativos do AIR contm todos os cdigos necessrios para funcionar. Assinaturas do aplicativo Todos os pacotes de aplicativos criados para a plataforma iOS precisam ser assinados. Uma vez que os aplicativos do AIR no iOS so empacotados no formato IPA do iOS nativo, eles so assinados de acordo com os requisitos do iOS, no de acordo com os requisitos do AIR. Embora o iOS e o AIR usem a assinatura de cdigo de forma semelhante, h trs diferenas significativas:

No iOS, o certificado usado para assinar um aplicativo deve ser emitido pela Apple; os certificados de outras
autoridades no podem ser usados.

No iOS, os certificados de distribuio emitidos pela Apple normalmente so vlidos por um ano.

ltima atualizao em 29/3/2011

1085

Captulo 61: Como Usar Exemplos do ActionScript

Execute um exemplo de cdigo para entender como determinadas classes e mtodos funcionam. Os tipos de exemplos de cdigo do ActionScript 3.0 so:

Exemplos de snippets de cdigo na pgina 1085 Exemplos com base em classes na pgina 1086 Exemplos prticos que contm mais de um arquivo de origem na pgina 1086
Para executar os exemplos de cdigo do ActionScript 3.0 na rea de trabalho, consulte o seguinte:

Execuo de exemplos do ActionScript 3.0 no Flash Professional na pgina 1086 Execuo de exemplos do ActionScript 3.0 no Flash Builder na pgina 1088
Usar instrues trace e outras ferramentas de depurao no Adobe Flash Professional ou no Adobe Flash Builder pode aumentar sua compreenso de um exemplo de cdigo. Voc pode executar os exemplos de cdigo do ActionScript 3.0 em dispositivos mveis com suporte a Flash Player 10.1 e verses posteriores. Para obter mais informaes, consulte Execuo de exemplos do ActionScript 3.0 em dispositivos mveis na pgina 1089. Se voc estiver desenvolvendo aplicativos para dispostivos de TV, tambm poder se beneficiar dos exemplos do ActionScript 3.0. Use o desktop para estudar os exemplos. Para obter informaes sobre o desenvolvimento para dispositivos de TV, consulte Plataforma Flash para TV no site Adobe Developer Connection.

Tipos de Exemplos
H trs tipos de exemplos de cdigo usados no Guia do desenvolvedor do ActionScript 3.0 e em outros livros, artigos e referncias lingusticas correspondentes:

Snippets de cdigo Exemplos com base em classes Exemplos prticos que contm mais de um arquivo de origem

Exemplos de snippets de cdigo

Um exemplo de snippet de cdigo tem o seguinte aspecto:
var x:int = 5; trace(x); // 5

Os snippets de cdigo contm apenas o cdigo suficiente para demonstrar uma nica idia. Normalmente, eles no contm instrues de pacote ou classe.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Como Usar Exemplos do ActionScript

1086

Exemplos com base em classes

Muitos exemplos mostram o cdigo-fonte de uma classe ActionScript completa. Um exemplo com base em classe tem o seguinte aspecto:
package { public class Example1 { public function Example1():void { var x:int = 5; trace(x); //5 } } }

O cdigo de um exemplo com base em classe contm uma instruo de pacote, uma declarao de classe e uma funo construtora.

Exemplos prticos que contm mais de um arquivo de origem

Muitos tpicos do Guia do desenvolvedor do ActionScript 3.0 terminam com exemplos prticos que mostram como usar determinados recursos do ActionScript em um contexto prtico e real. Normalmente, esses exemplos contm vrios arquivos, inclusive:

Um ou mais arquivos de origem do ActionScript Um arquivo .FLA para ser usado com o Flash Professional Um ou mais arquivos MXML para ser usado com o Flash Builder Arquivos de dados, arquivos de imagem, arquivos de som ou outros recursos usados pelo aplicativo de exemplo
(opcional). Exemplos prticos tambm so encontrados em muitos artigos do Quick Start no Flash Developer Center e no Flex Developer Center. Normalmente, os exemplos prticos so distribudos como arquivos ZIP.

Execuo de exemplos do ActionScript 3.0 no Flash Professional

Primeiramente, determine o tipo de exemplo do ActionScript 3.0 que deseja executar (conforme descrito em Tipos de Exemplos na pgina 1085). Em seguida, use um dos seguintes procedimentos para execut-lo utilizando o Flash Professional.

Executando um exemplo de snippet de cdigo no Flash Professional

Para executar um exemplo de snippet de cdigo no Flash Professional:
1 Selecione Arquivo > Novo. 2 Na caixa de dilogo Novo documento, selecione Documento Flash e clique em OK.

Uma nova janela do Flash ser exibida.

3 Clique no primeiro quadro da primeira camada do painel Linha de tempo. 4 No painel Aes, digite ou cole o exemplo de snippet de cdigo.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Como Usar Exemplos do ActionScript

1087

5 Selecione Arquivo > Salvar. Atribua um nome ao arquivo e clique em OK. 6 Para testar o exemplo, selecione Controlar > Testar filme.

Execuo de um exemplo com base em classe no Flash Professional

Para executar um exemplo com base em classe no Flash Professional:
1 Selecione Arquivo > Novo. 2 Na caixa de dilogo Novo documento, selecione Arquivo ActionScript e clique em OK. Uma nova janela do editor

ser exibida.
3 Copie o cdigo de exemplo com base em classe e cole-o na janela do editor.

Se a classe for a classe principal document do programa, ela dever estender a classe MovieClip:
import flash.display.MovieClip; public class Example1 extends MovieClip{ //... }

Certifique-se tambm de que todas as classes a que o exemplo faz referncia sejam declaradas com instrues import.
4 Selecione Arquivo > Salvar. D ao arquivo o mesmo nome que a classe no exemplo (por exemplo,

ContextMenuExample.as). Nota: Alguns dos exemplos com base em classe, como o exemplo de classe flashx.textLayout.container.ContainerController, incluem diversos nveis na declarao do pacote (package flashx.textLayout.container.examples {). Para esses exemplos, salve os arquivos em um subdiretrio correspondente declarao do pacote (flashx/textLayout/container/examples), ou remova o nome do pacote (de forma que o ActionScript inicie com package { somente) para que voc possa testar o arquivo a partir de qualquer local.
5 Selecione Arquivo > Novo. 6 Na caixa de dilogo Novo documento, selecione Documento Flash (ActionScript 3.0) e clique em OK. Uma nova

janela do Flash ser exibida.

7 No painel de Propriedades, campo Classe do documento, insira o nome da classe de exemplo, que deve

corresponder ao nome do arquivo de origem do ActionScript que voc acabou de salvar (por exemplo, ContextMenuExample).
8 Selecione Arquivo > Salvar. D ao arquivo FLA o mesmo nome que a classe no exemplo (por exemplo,

ContextMenuExample.fla).
9 Para testar o exemplo, selecione Controlar > Testar filme.

Execuo de um exemplo prtico no Flash Professional

Normalmente, os exemplos prticos so distribudos como arquivos ZIP. Para executar um exemplo prtico usando o Flash Professional:
1 Descompacte o arquivo ZIP em outra pasta de sua escolha. 2 No Flash Professional, selecione Arquivo > Abrir. 3 Navegue at a pasta em que voc descompactou o arquivo. Selecione o arquivo FLA nessa pasta e clique em Abrir. 4 Para testar o exemplo, selecione Controlar > Testar filme.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Como Usar Exemplos do ActionScript

1088

Execuo de exemplos do ActionScript 3.0 no Flash Builder

Primeiramente, determine o tipo de exemplo do ActionScript 3.0 que deseja executar (conforme descrito em Tipos de Exemplos na pgina 1085). Em seguida, use um dos seguintes procedimentos para execut-lo utilizando o Flash Builder (ou Flex Builder).

Execuo de um exemplo de snippet de cdigo no Flash Builder

Para executar um exemplo de snippet de cdigo no Flash Builder:
1 Crie um novo Projeto Flex (selecione Arquivo > Novo > Projeto Flex), ou, dentro de um projeto Flex existente, crie

um novo Aplicativo MXML (selecione Arquivo > Novo > Aplicativo MXML). D ao projeto ou aplicativo um nome descritivo (como ContextMenuExample).
2 Dentro do arquivo MXML gerado, adicione uma marca <mx:Script>. 3 Cole o contedo do exemplo do snippet de cdigo entre as marcas <mx:Script> e </mx:Script>. Salve o arquivo

MXML.
4 Para executar o exemplo, selecione a opo de menu Executar > Executar para o arquivo MXML principal (como

Executar > Executar ContextMenuExample).

Execuo de um exemplo com base em classe no Flash Builder

Para executar um exemplo com base em classe no Flash Builder:
1 Selecione Arquivo > Novo > Projeto ActionScript. 2 Insira o nome da classe primria (como ContextMenuExample) no campo Nome do Projeto. Use os valores padro

nos outros campos (ou altere-os de acordo com o seu ambiente especfico). Clique em Concluir para criar o projeto e o arquivo principal do ActionScript.
3 Apague todo o contedo gerado do arquivo ActionScript. Cole o cdigo de exemplo, incluindo os comandos de

pacote e importao, no arquivo ActionScript e salve o arquivo. Nota: Alguns dos exemplos com base em classe, como o exemplo de classe flashx.textLayout.container.ContainerController, incluem diversos nveis na declarao do pacote (package flashx.textLayout.container.examples {). Para esses exemplos, salve os arquivos em um subdiretrio correspondente declarao do pacote (flashx/textLayout/container/examples), ou remova o nome do pacote (de forma que o ActionScript inicie com package { somente) para que voc possa testar o arquivo a partir de qualquer local.
4 Para executar o exemplo, selecione a opo de menu Executar > Executar para o nome da classe do ActionScript

(como Executar > Executar ContextMenuExample).

Execuo de um exemplo prtico no Flash Builder

Normalmente, os exemplos prticos so distribudos como arquivos ZIP. Para executar um exemplo prtico usando o Flash Builder:
1 Descompacte o arquivo ZIP em outra pasta de sua escolha. D pasta um nome descritivo (como

ContextMenuExample).

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Como Usar Exemplos do ActionScript

1089

2 No Flash Builder, selecione Arquivo > Novo Projeto Flex. Na seo Local do Projeto, clique em Localizar e selecione

a pasta que contm os arquivos de exemplo. No campo Nome do Projeto, insira o nome da pasta (como ContextMenuExample). Use os valores padro nos outros campos (ou altere-os de acordo com o seu ambiente especfico). Clique em Avanar para continuar.
3 No painel Sada, clique em Avanar para aceitar o valor padro. 4 No painel Caminhos de Origem, clique no boto Localizar ao lado do campo Arquivo Principal do Aplicativo.

Selecione o arquivo MXML principal de exemplo na pasta de exemplo. Clique em Concluir para criar os arquivos do projeto.
5 Para executar o exemplo, selecione a opo de menu Executar > Executar para o arquivo MXML principal (como

Executar > Executar ContextMenuExample).

Execuo de exemplos do ActionScript 3.0 em dispositivos mveis

Voc pode executar os exemplos de cdigo do ActionScript 3.0 em dispositivos mveis que reconhecem o Flash Player 10.1. Entretanto, voc normalmente executa um exemplo de cdigo para aprender como funcionam determinadas classes e determinados mtodos. Nesse caso, execute o exemplo em um dispositivo que no seja mvel, como um computador de mesa. No computador de mesa, voc pode usar comandos de rastreamento e outras ferramentas de depurao no Flash Professional ou no Flash Builder para compreender melhor o exemplo de cdigo. Se quiser executar o exemplo em um dispositivo mvel, voc pode copiar os arquivos no dispositivo ou em um servidor Web. Para copiar arquivos no dispositivo e executar o exemplo no navegador, faa o seguinte:
1 Crie o arquivo SWF seguindo as instrues em Execuo de exemplos do ActionScript 3.0 no Flash Professional

na pgina 1086 ou em Execuo de exemplos do ActionScript 3.0 no Flash Builder na pgina 1088. No Flash Professional, crie o arquivo SWF quando selecionar Controlar > Testar Filme. No Flash Builder, crie o arquivo SWF quando executar, depurar ou criar o seu projeto do Flash Builder.
2 Copie o arquivo SWF em um diretrio no dispositivo mvel. Use o software que acompanha o dispositivo para

copiar o arquivo.
3 Na barra de endereos do navegador no dispositivo mvel, digite o arquivo:// URL para o arquivo SWF. Por

exemplo, digite file:://applications/myExample.swf. Para copiar arquivos em um servidor Web e executar o exemplo no navegador do dispositivo, faa o seguinte:
1 Crie um arquivo SWF e um arquivo HTML. Primeiro, siga as instrues em Execuo de exemplos do

ActionScript 3.0 no Flash Professional na pgina 1086 ou em Execuo de exemplos do ActionScript 3.0 no Flash Builder na pgina 1088. No Flash Professional, a seleo de Controlar > Testar Filme cria apenas o arquivo SWF. Para criar ambos os arquivos, primeiro selecione Flash e HTML na guia Formatos da caixa de dilogo Publicar Configuraes. Em seguida, selecione Arquivo > Publicar para criar os arquivos HTML e SWF. No Flash Builder, crie os arquivos SWF e HTML quando executar, depurar ou criar o seu projeto do Flash Builder.
2 Copie os arquivos SWF e HTML em um diretrio do servidor Web. 3 Na barra de endereos do navegador no dispositivo mvel, digite o endereo HTTP do arquivo SWF. Por exemplo,

digite http://www.myWebServer/examples/myExample.html. Antes de executar um exemplo em um dispositivo mvel, considere cada um dos seguintes aspectos.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Como Usar Exemplos do ActionScript

1090

Tamanho do palco
O tamanho do palco usado na execuo de um exemplo em um dispositivo mvel muito menor do que quando voc utiliza um dispositivo que no seja mvel. Muitos exemplos no exigem um tamanho especfico de palco. Ao criar o arquivo SWF, especifique um tamanho de palco adequado ao seu dispositivo. Por exemplo, especifique 176 x 208 pixels. A finalidade dos exemplos prticos no Guia de desenvolvimento do ActionScript 3.0 ilustrar diferentes conceitos e classes do ActionScript 3.0. Suas interfaces de usurio so criadas para ter uma boa aparncia e funcionar bem em um computador de mesa ou em um laptop. Embora os exemplos funcionem em dispositivos mveis, o tamanho do palco e o design da interface de usurio no so adequados tela pequena. A Adobe recomenda que voc execute os exemplos prticos em um computador para conhecer o ActionScript e, depois, use os snippets de cdigo pertinentes nos seus aplicativos mveis.

Campos de texto em vez de comandos de rastreamento.

Ao executar um exemplo em um dispositivo mvel, no possvel ver o resultado dos comandos de rastreamento do exemplo. Para ver o resultado, crie uma instncia da classe TextField. Depois, anexe o texto dos comandos de rastreamento propriedade text do campo de texto. Voc pode usar a seguinte funo para criar um campo de texto para usar no rastreamento:
function createTracingTextField(x:Number, y:Number, width:Number, height:Number):TextField { var tracingTF:TextField = new TextField(); tracingTF.x = x; tracingTF.y = y; tracingTF.width = width; tracingTF.height = height; // A border lets you more easily see the area the text field covers. tracingTF.border = true; // Left justifying means that the right side of the text field is automatically // resized if a line of text is wider than the width of the text field. // The bottom is also automatically resized if the number of lines of text // exceed the length of the text field. tracingTF.autoSize = TextFieldAutoSize.LEFT; // Use a text size that works well on the device. var myFormat:TextFormat = new TextFormat(); myFormat.size = 18; tracingTF.defaultTextFormat = myFormat; addChild(tracingTF); return tracingTF; }

Por exemplo, acrescente esta funo classe de documentos como uma funo privada. Em seguida, em outros mtodos da classe de documentos, rastreie os dados com cdigos como os seguintes:
var traceField:TextField = createTracingTextField(10, 10, 150, 150); // Use the newline character "\n" to force the text to the next line. traceField.appendText("data to trace\n"); traceField.appendText("more data to trace\n"); // Use the following line to clear the text field. traceField.appendText("");

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Como Usar Exemplos do ActionScript

1091

O mtodo appendText() aceita apenas um valor como parmetro. Esse valor uma sequncia de caracteres (uma instncia de String ou um literal de sequncia de caracteres). Para imprimir o valor de uma varivel que no seja uma sequncia de caracteres, primeiro necessrio converter o valor em uma String. A maneira mais fcil de fazer isso chamar o mtodo toString() do objeto:
var albumYear:int = 1999; traceField.appendText("albumYear = "); traceField.appendText(albumYear.toString());

Tamanho do texto
Muitos exemplos usam campos de texto para ajudar a ilustrar um conceito. s vezes, o ajuste do tamanho do texto no campo de texto melhora a legibilidade em um dispositivo mvel. Por exemplo, se um exemplo usar uma instncia de campo de texto chamado myTextField, altere o tamanho do texto com o seguinte cdigo:
// Use a text size that works well on the device. var myFormat:TextFormat = new TextFormat(); myFormat.size = 18; myTextField.defaultTextFormat = myFormat

Captura da entrada do usurio

O sistema operacional e o navegador mveis capturam alguns eventos de entrada do cliente que no so recebidos pelo contedo SWF. O comportamento especfico depende do sistema operacional e do navegador, mas pode causar comportamentos inesperados quando voc executar os exemplos em um dispositivo mvel. Para obter mais informaes, consulte Precedncia de KeyboardEvent na pgina 543. Alm disso, as interfaces de usurio de muitos exemplos foram criadas para computadores de mesa ou laptops. Por exemplo, a maioria dos exemplos prticos no Guia do desenvolvedor do ActionScript 3.0 adequada para visualizao em computadores de mesa. Portanto, s vezes, nem todo o palco pode ser visto na tela do dispositivo mvel. A capacidade de deslocamento horizontal pelo contedo do navegador depende do navegador. Alm disso, os exemplos no foram criados para capturar e tratar eventos de rolagem ou deslocamento horizontal. Portanto, as interfaces de usurio de alguns exemplos no so adequadas para execuo em telas pequenas. A Adobe recomenda que voc execute os exemplos em um computador para conhecer o ActionScript e, depois, use os snippets de cdigo pertinentes nos seus aplicativos mveis. Para obter mais informaes, consulte Viso panormica e rolagem de objetos de exibio na pgina 171.

Tratamento do foco
Alguns exemplos exigem que voc coloque o foco em um campo. Levando o foco a um campo, voc pode, por exemplo, inserir textos ou selecionar um boto. Para levar o foco a um campo, use o ponteiro do dispositivo mvel, como um utenslio de escrita ou o dedo. Voc tambm pode usar as teclas de navegao do dispositivo mvel para levar o foco a um campo. Para selecionar um boto no qual o foco est, use a tecla Selecionar do dispositivo mvel da mesma forma que usaria o Enter em um computador. Em alguns dispositivos, voc pode selecionar um boto batendo duas vezes nele. Para obter mais informaes sobre foco, consulte Gerenciamento do foco na pgina 538.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Como Usar Exemplos do ActionScript

1092

Tratamento de eventos do mouse

Muitos exemplos recebem eventos do mouse. Em um computador, esses eventos de mouse podem ocorrer, por exemplo, quando um usurio passa com o cursor sobre um objeto de exibio ou quando ele clica com o boto do mouse sobre esse objeto. Nos dispositivos mveis, os eventos gerados pelo uso de ponteiros (como um utenslio de escrita ou o dedo), so chamados eventos de toque. O Flash Player 10.1 correlaciona os eventos de toque aos eventos de mouse. Essa correlao garante que o contedo SWF desenvolvido antes do Flash Player 10.1 continue funcionando. Portanto, os exemplos funcionam quando voc utiliza um ponteiro ou arrasta um objeto de exibio.

Desempenho
Os dispositivos mveis tm menos capacidade de processamento que os computadores de mesa. Possivelmente, a velocidade de alguns exemplos que consomem muita CPU ser menor em dispositivos mveis. Por exemplo, o exemplo em Exemplo de API de desenho: gerador visual algortmico na pgina 225 faz muitos clculos e desenhos na entrada em cada quadro. A execuo desse exemplo em um computador ilustra vrias APIs de desenho. Entretanto, o exemplo no adequado em alguns dispositivos mveis devido s suas limitaes de velocidade. Para obter mais informaes sobre o desempenho em dispositivos mveis, consulte Otimizao do desempenho para a plataforma Flash.

Prticas Recomendadas
Os exemplos no levam em conta as prticas recomendadas de desenvolvimento de aplicativos para dispositivos mveis. As limitaes de memria e capacidade de processamento dos dispositivos mveis exigem uma ateno especial. Da mesma forma, a interface de usurio para telas pequenas tem necessidades diferentes em relao tela de um computador de mesa. Para obter mais informaes sobre o desenvolvimento de aplicativos para dispositivos mveis, consulte Otimizao do desempenho para a plataforma Flash.

ltima atualizao em 29/3/2011

1093

Captulo 62: Suporte SQL em bancos de dados locais

O Adobe AIR inclui um mecanismo de banco de dados SQL com suporte a bancos de dados locais SQL com diversos recursos padro SQL, usando o sistema de banco de dados de cdigo livre SQLite. O tempo de execuo no especifica como ou onde os dados do banco de dados esto armazenados no sistema de arquivos. Cada banco de dados armazenado totalmente em um nico arquivo. Um desenvolvedor pode especificar o local no sistema de arquivos em que o arquivo do banco de dados armazenado e um aplicativo AIR nico pode acessar um ou mais bancos de dados separados (ou seja, arquivos de banco de dados separados). Este documento descreve a sintaxe SQL e o suporte a tipo de dados para bancos de dados SQL locais do Adobe AIR. Este documento no deve servir como uma ampla referncia a SQL. Na verdade, ele descreve detalhes especficos do dialeto SQL aos quais o Adobe AIR oferece suporte. O tempo de execuo oferece suporte maior parte do dialeto SQL padro SQL-92. Como h muitas referncias, sites, livros e materiais de treinamento para aprender SQL, este documento no deve ser uma ampla referncia ou tutorial sobre SQL. Na verdade, este documento se concentra especialmente na sintaxe SQL para a qual o Apollo AIR oferece suporte, alm das diferenas entre o SQL-92 e o dialeto SQL para o qual h suporte. Convenes de definio de instrues SQL Nas definies de instruo deste documento, so usadas as seguintes convenes:

Uso de maisculas e minsculas UPPER CASE palavras-chave SQL literais so escritas todas em maisculas. lower case termos de alocador de espao ou nomes de clusula so escritos todos em minsculas. Caracteres de definio = indica uma definio de clusula ou instruo. Caracteres de agrupamento e alternativos o caractere de pipe usado entre opes e pode ser lido como "ou" [] - itens entre colchetes so opcionais; eles podem conter um nico item ou um conjunto de itens alternativos. () parnteses entre um conjunto de alternativas (um conjunto de itens separados por caracteres de pipe)
designam um grupo obrigatrio de itens, ou seja, um conjunto de itens que so valores possvel para um nico item obrigatrio.

Quantificadores
+ - um caractere de soma seguido de um item entre parnteses indica que o item anterior pode ocorrer uma ou mais vezes. pode ocorrer 0 ou mais vezes.

* - um caractere de asterisco seguido de um item entre colchetes indica que o item anterior (entre colchetes) Caracteres literais * um caractere de asterisco usado em um nome de coluna ou entre parnteses seguido de um nome de funo
significa um asterisco literal e no o quantificador "0 ou mais".

. . - Um caractere de ponto final representa um ponto final literal. , um caractere de vrgula representa uma vrgula literal.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Suporte SQL em bancos de dados locais

1094

() um par de parnteses entre uma nica clusula ou item indica que os parnteses so caracteres de parnteses
literais, obrigatrios.

Outros caracteres exceto quando indicado o contrrio, os demais caracteres representam esses caracteres
literais.

Sintaxe SQL para a qual h suporte

As seguintes litas de sintaxe SQL so suportadas pelo mecanismo de banco de dados SQL Adobe AIR. Essas listagens esto divididas em explicaes de tipos de instruo e clusula diferentes, expresses, funes internas e operadores. So abordados os tpicos a seguir:

Sintaxe SQL geral Instrues para manipulao de dados (SELECT, INSERT, UPDATE e DELETE) Instrues para definio de dados (instrues de CREATE, ALTER e DROP para tabelas, ndices, exibies e
disparadores)

Instrues especiais e clusulas Funes internas (agregada, escalar e funes de formatao de data/hora) Operadores Parmetros Recursos SQL para os quais no h suporte Recursos SQL adicionais

Sintaxe SQL geral

Alm da sintaxe especfica de vrias instrues e expresses, esto so as regras gerais da sintaxe SQL:
Diferenciao entre maisculas e minsculas Instrues SQL, inclusive nomes de objeto, no diferenciam maisculas e minsculas. No entanto, as instrues SQL costumam ser escritas com palavras-chave SQL em maisculas, e este documento usa essa conveno. Embora a sintaxe SQL no diferencie maisculas de minsculas, os valores de texto literal em SQL as diferenciam, e as operaes de classificao podem diferenci-las, conforme especificado pela sequncia de intercalao definida para uma coluna ou operao. Para obter mais informaes, consulte COLLATE. Espao em branco Um caractere de espao em branco (como, por exemplo, espao, tabulao, nova linha etc.) deve ser usado para separar palavras individuais em uma instruo SQL. No entanto, o espao em branco opcional entre palavras e smbolos. O tipo e a quantidade de caracteres espao em branco em uma instruo SQL no so significativos. possvel usar espao em branco como, por exemplo, recuos e quebras de linha para formatar as instrues SQL, tendo em vista maior legibilidade sem afetar o significado da instruo.

Instrues para manipulao de dados

As instrues para manipulao de dados so as instrues SQL mais usadas. Elas so usadas para recuperar, adicionar, modificar e remover dados das tabelas de banco de dados. Estas so as instrues para manipulao de dados para as quais h suporte: SELECT, INSERT, UPDATE e DELETE. SELECT

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Suporte SQL em bancos de dados locais

1095

A instruo SELECT usada para consultar o banco de dados. O resultado de uma instruo SELECT zero ou mais linhas de dados em que cada uma tem um nmero de colunas fixo. O nmero de colunas no resultado especificado pelo nome da coluna result ou pela lista de expresso entre as palavras-chave SELECT e as opcionais FROM.
sql-statement ::= SELECT [ALL | DISTINCT] result [FROM table-list] [WHERE expr] [GROUP BY expr-list] [HAVING expr] [compound-op select-statement]* [ORDER BY sort-expr-list] [LIMIT integer [( OFFSET | , ) integer]] result-column [, result-column]* * | table-name . * | expr [[AS] string] table [ join-op table join-args ]* table-name [AS alias] | ( select ) [AS alias] , | [NATURAL] [LEFT | RIGHT | FULL] [OUTER | INNER | CROSS] JOIN [ON expr] [USING ( id-list )] UNION | UNION ALL | INTERSECT | EXCEPT expr [sort-order] [, expr [sort-order]]* [COLLATE collation-name] [ASC | DESC] BINARY | NOCASE

result result-column table-list table join-op join-args compound-op sort-expr-list sort-order collation-name

::= ::= ::= ::= ::= ::= ::= ::= ::= ::=

Qualquer expresso arbitrria pode ser usada como resultado. Caso uma expresso de resultado seja *, todas as colunas de todas as tabelas sero substitudas por essa expresso. Caso a expresso seja o nome de uma tabela seguido de .*, o resultado ser igual a todas as colunas nessa nica tabela. A palavra-chave DISTINCT faz com que um subconjunto de linhas de resultado seja retornado, no qual cada linha de resultado diferente. Valores NULL no so tratados como distintos entre si. O comportamento padro de que todas as linhas de resultado sejam retornadas, as quais podem ser explicitadas com a palavra-chave ALL. A consulta executada em uma ou mais tabelas especificadas aps a palavra-chave FROM. Caso vrios nomes de tabela estejam separados por vrgulas, a consulta usa a juno cruzada das vrias tabelas. A sintaxe JOIN tambm pode ser usada para especificar como as tabelas so unidas. O nico tipo de juno externa para o qual h suporte LEFT OUTER JOIN. A expresso da clusula ON em join-args deve ser resolvida como um valor booleano. Uma subconsulta entre parnteses pode ser usada como uma tabela na clusula FROM. Toda a clusula FROM pode ser omitida, no caso de o resultado ser uma nica linha com os valores da lista de expresses result. A clusula WHERE usada para limitar o nmero de linhas recuperadas pela consulta. As expresses de clusula WHERE devem ser resolvidas como um valor booleano. Como a filtragem de clusula WHERE realizada antes de qualquer agrupamento, as expresses de clusula WHERE talvez no incluam funes agregadas. A clusula GROUP BY faz com que uma ou mais linhas do resultado sejam combinadas com uma nica linha de sada. Uma clusula GROUP BY especialmente til quando o resultado contm funes agregadas. As expresses na clusula GROUP BY no precisam ser expresses exibidas na lista de expresses SELECT. A clusula HAVING semelhante a WHERE ao limitar as linhas retornadas pela instruo. No entanto, a clusula HAVING se aplica aps a ocorrncia de qualquer agrupamento especificado por uma clusula GROUP BY. Consequentemente, a expresso HAVING pode se referir a valores que incluem funes agregadas. Uma expresso de clusula HAVING no precisa ser exibida na lista SELECT. Assim como uma expresso WHERE, uma expresso HAVING deve ser resolvida como um valor booleano.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Suporte SQL em bancos de dados locais

1096

A clusula ORDER BY faz com que as linhas de sada sejam classificadas. O argumento sort-expr-list da clusula ORDER BY uma lista de expresses usadas como chave da classificao. As expresses no precisam fazer parte do resultado de uma simples SELECT, mas em uma SELECT composta (uma SELECT usando um dos operadores compound-op), cada expresso de classificao deve corresponder exatamente a uma das colunas de resultado. Cada expresso de classificao pode ser seguida de uma clusula sort-order que consiste na palavra-chave COLLATE e no nome de uma funo de intercalao usada para classificar o texto e/ou a palavra-chave ASC ou DESC para especificar a ordem de classificao (crescente ou decrescente). A sort-order pode ser omitida e o padro (ordem crescente) usado. Para obter uma definio da clusula COLLATE e das funes de intercalao, consulte COLLATE. A sortorder pode ser omitida e o padro (ordem crescente) usado. Para obter uma definio da clusula COLLATE e das funes de intercalao, consulte COLLATE. A clusula LIMIT coloca um limite superior sobre o nmero de linhas retornadas no resultado. Uma LIMIT negativa no indica nenhum limite superior. A OFFSET opcional que segue LIMIT especifica quantas linhas ignorar no incio do conjunto de resultados. Em uma consulta SELECT composta, a clusula LIMIT talvez s seja exibida aps a instruo SELECT final, e o limite aplicado a toda a consulta. Observe que, caso a palavra-chave OFFSET seja usada na clusula LIMIT, o limite o primeiro inteiro e a distncia o segundo inteiro. Caso seja usada uma vrgula no lugar da palavra-chave OFFSET, a distncia o primeiro nmero e o limite, o segundo. Essa contradio aparente intencional ela maximiza a compatibilidade com sistemas de banco de dados SQL herdados. Uma SELECT composta formada por duas ou mais instrues SELECT simples conectadas por um dos operadores UNION, UNION ALL, INTERSECT ou EXCEPT. Em uma SELECT composta, todas as instrues SELECT constituintes devem especificar o mesmo nmero de colunas de resultado. S pode haver uma nica clusula ORDER BY aps a instruo SELECT final (e antes da nica clusula LIMIT, caso haja uma especificada). Os operadores UNION e UNION ALL integram os resultados das instrues SELECT anterior e posterior em uma nica tabela. A diferena que na UNION, todas as linhas de resultado so distintas, mas em UNION ALL talvez haja cpias. O operador INTERSECT usa a interseco dos resultados das instrues SELECT anterior e posterior. EXCEPT usa o resultado da SELECT anterior aps a remoo dos resultados da SELECT seguinte. Quando trs ou mais instrues SELECT esto conectadas a uma composta, elas so agrupadas da primeira ltima. Para obter uma definio das expresses permitidas, consulte Expresses A partir do AIR 2.5, o operador SQL CAST conta com suporte durante a leitura para converter dados BLOB em objetos ByteArray do ActionScript. Por exemplo, o cdigo a seguir l dados brutos que no esto armazenados no formato AMF e os armazena em um objeto ByteArray:
stmt.text = "SELECT CAST(data AS ByteArray) AS data FROM pictures;"; stmt.execute(); var result:SQLResult = stmt.getResult(); var bytes:ByteArray = result.data[0].data;

INSERT A instruo INSERT acompanha duas formas bsicas, sendo usada para preencher tabelas com dados.
sql-statement ::= INSERT [OR conflict-algorithm] INTO [database-name.] table-name [(columnlist)] VALUES (value-list) | INSERT [OR conflict-algorithm] INTO [database-name.] table-name [(columnlist)] select-statement REPLACE INTO [database-name.] table-name [(column-list)] VALUES (value-list) | REPLACE INTO [database-name.] table-name [(column-list)] select-statement

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Suporte SQL em bancos de dados locais

1097

A primeira forma (com a palavra-chave VALUES) cria uma nica linha nova em uma tabela existente. Caso nenhuma column-list seja especificada, o nmero de valores deve ser igual ao nmero de colunas na tabela. Caso uma columnlist seja especificada, o nmero de valores deve corresponder ao nmero de colunas especificadas. As colunas da tabela que no so exibidas na lista so preenchidas com o valor definido padro quando a tabela criada, ou com NULL caso nenhum valor padro seja definido. A segunda forma da instruo INSERT usa os dados de uma instruo SELECT. O nmero de colunas no resultado da SELECT deve corresponder exatamente ao nmero de colunas na tabela caso column-list no esteja especificada, ou deve corresponder ao nmero de colunas nomeadas na column-list. criada uma nova entrada na tabela para todas as linhas do resultado de SELECT. A SELECT pode ser simples ou composta. Para obter uma definio das instrues SELECT permitidas, consulte SELECT. A conflict-algorithm opcional permite a especificao de um algoritmo para resoluo de conflitos de restrio a ser usado durante esse comando nico. Para obter uma explicao e definio do conflito de algoritmos, consulte Instrues especiais e clusulas na pgina 1104. As duas formas REPLACE INTO da instruo so equivalentes ao uso da forma INSERT [OR conflict-algorithm] padro com o algoritmo de conflito REPLACE (ou seja, a forma INSERT OR REPLACE...). As duas formas REPLACE INTO da instruo so equivalentes ao uso da forma INSERT [OR conflict-algorithm] padro com o algoritmo de conflito REPLACE (ou seja, a forma INSERT OR REPLACE...). UPDATE O comando update altera os registros existentes em uma tabela.
sql-statement [WHERE expr] ::= UPDATE [database-name.] table-name SET column1=value1, column2=value2,...

O comando consiste na palavra-chave UPDATE seguida do nome do tabela cujos registros voc deseja atualizar. Depois da palavra-chave SET, fornea o nome da coluna e o valor para o qual a coluna deve ser alterada, como uma lista separada por vrgulas. A expresso da clusula WHERE indica a linha ou linhas em que os registros so atualizados. DELETE O comando de excluso usado para remover registros de uma tabela.
sql-statement ::= DELETE FROM [database-name.] table-name [WHERE expr]

O comando consiste nas palavras-chave DELETE FROM seguidas do nome da tabela da qual os registros devem ser removidos. Sem uma clusula WHERE, todas as linhas da tabela so removidas. Caso uma clusula WHERE seja fornecida, apenas essas linhas correspondentes expresso so removidas. A expresso da clusula WHERE deve ser resolvida como um valor booleano. Para obter uma definio das expresses permitidas, consulte Expresses

Instrues para definio de dados

As instrues para definio dos dados so usadas para criar, modificar e remover objetos de banco de dados como tabelas, exibies, ndices e disparadores. Estas so as instrues para definio de dados para as quais h suporte:

Tabelas: CREATE TABLE ALTER TABLE DROP TABLE

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Suporte SQL em bancos de dados locais

1098

ndices: CREATE INDEX DROP INDEX Exibies: CREATE VIEWS DROP VIEWS Disparadores: CREATE TRIGGERS DROP TRIGGERS
CREATE TABLE Uma instruo CREATE TABLE consiste nas palavras-chave CREATE TABLE seguidas do nome da nova tabela e, em seguida, de uma lista das definies e restries da coluna (entre parnteses). O nome da tabela pode ser um identificador ou uma string.
sql-statement name sql-statement statement column-def type column-constraint ::= CREATE [TEMP | TEMPORARY] TABLE [IF NOT EXISTS] [database-name.] table( column-def [, column-def]* [, constraint]* ) CREATE [TEMP | TEMPORARY] TABLE [database-name.] table-name AS select-

::= ::= ::= ::=

name [type] [[CONSTRAINT name] column-constraint]* typename | typename ( number ) | typename ( number , number ) NOT NULL [ conflict-clause ] | PRIMARY KEY [sort-order] [ conflict-clause ] [AUTOINCREMENT] | UNIQUE [conflict-clause] | CHECK ( expr ) | DEFAULT default-value | COLLATE collation-name constraint ::= PRIMARY KEY ( column-list ) [conflict-clause] | UNIQUE ( column-list ) [conflict-clause] | CHECK ( expr ) conflict-clause ::= ON CONFLICT conflict-algorithm conflict-algorithm ::= ROLLBACK | ABORT | FAIL | IGNORE | REPLACE default-value ::= NULL | string | number | CURRENT_TIME | CURRENT_DATE | CURRENT_TIMESTAMP sort-order ::= ASC | DESC collation-name ::= BINARY | NOCASE column-list ::= column-name [, column-name]*

Cada definio de coluna o nome da coluna seguido do tipo de dados da coluna e, em seguida, de uma ou mais restries de coluna opcionais. O tipo de dados da coluna restringe quais dados podem ser armazenados nessa coluna. Se for feita uma tentativa de armazenar um valor em uma coluna com um tipo de dados diferente, o tempo de execuo converter o valor no tipo apropriado, se possvel, ou apresentar um erro. Consulte Suporte ao tipo de dados para obter detalhes. A restrio de coluna NOT NULL indica que a coluna no pode conter valores NULL. Uma restrio UNIQUE faz com que seja criado um ndice na(s) coluna(s) especificada(s). Esse ndice deve conter chaves exclusivas duas linhas no podem conter valores duplicados ou combinaes de valores para a(s) coluna(s) especificada(s). Uma instruo CREATE TABLE pode ter vrias restries UNIQUE, inclusive vrias colunas com uma restrio UNIQUE na definio da coluna e/ou vrias restries UNIQUE no nvel da tabela.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Suporte SQL em bancos de dados locais

1099

Uma restrio CHECK define uma expresso avaliada e que deve ser verdadeira para que os dados de uma linha sejam inseridos ou atualizados. A expresso CHECK deve ser resolvida como um valor booleano. A expresso CHECK deve ser resolvida como um valor booleano. Por padro, a funo de intercalao BINARY usada. Para obter detalhes sobre a clusula COLLATE e as funes de intercalao, consulte COLLATE. A restrio DEFAULT especifica um valor padro a ser usado com INSERT. O valor pode ser NULL, uma constante de string ou um nmero. O valor padro tambm pode ser uma das palavras-chave especiais que no diferenciam maisculas de minsculas CURRENT_TIME, CURRENT_DATE ou CURRENT_TIMESTAMP. Caso o valor seja NULL, uma constante de string, ou um nmero, ele literalmente inserido na coluna sempre que uma instruo INSERT no especificar um valor da coluna. Caso o valor seja CURRENT_TIME, CURRENT_DATE ou CURRENT_TIMESTAMP, a data e/ou hora UTC atual inserida na coluna. Em CURRENT_TIME, o formato HH:MM:SS. Em CURRENT_DATE, o formato YYYY-MM-DD. O formato de CURRENT_TIMESTAMP YYYYMM-DD HH:MM:SS. Especificar uma PRIMARY KEY normalmente apenas cria um ndice UNIQUE na(s) coluna(s) correspondente(s). No entanto, caso a restrio PRIMARY KEY esteja em uma nica coluna cujo tipo de dados seja INTEGER (ou um de seus sinnimos, tais como int), essa coluna ser usada pelo banco de dados como a chave primria real da tabela. Isso significa que a coluna s pode manter valores de inteiro exclusivos. (Observe que, em muitas implementaes do SQLite, apenas o tipo de coluna INTEGER faz com que a coluna sirva como chave primria interna, mas, no Adobe AIR, os sinnimos de INTEGER, como int, tambm especificam esse comportamento). Se uma tabela no tiver uma coluna INTEGER PRIMARY KEY, uma chave de inteiro ser gerada automaticamente quando uma linha for inserida. A chave primria de uma linha pode ser sempre acessada usando um dos nomes especiais ROWID, OID ou _ROWID_. Esses nomes podem ser usados independentemente da declarao explcita de INTEGER PRIMARY KEY ou de um valor gerado internamente. Entretanto, caso a tabela tenha uma INTEGER PRIMARY KEY explcita, o nome da coluna nos dados de resultados o nome real da coluna e no o nome especial. Uma coluna INTEGER PRIMARY KEY tambm pode incluir a palavra-chave AUTOINCREMENT. Quando a palavra-chave AUTOINCREMENT for usada, o banco de dados gera automaticamente e insere uma chave inteira incrementada sequencialmente na coluna INTEGER PRIMARY KEY quando executa uma instruo INSERT que no especifica um valor explcito para a coluna. S pode haver uma restrio PRIMARY KEY em uma instruo CREATE TABLE. Ela pode fazer parte da definio de uma coluna ou de uma restrio PRIMARY KEY nica no nvel da tabela. Implicitamente, uma coluna de chave primria NOT NULL. A conflict-clause opcional que segue muitas restries permite a especificao de um algoritmo para resoluo de conflitos de restrio padro alternativo para essa restrio. O padro ABORT. Restries diferentes dentro da mesma tabela podem ter algoritmos para resoluo de conflitos padro diferentes. Caso uma instruo INSERT ou UPDATE especifique um algoritmo para resoluo de conflitos diferente, esse algoritmo usado em lugar do especificado na instruo CREATE TABLE. Consulte a seo ON CONFLICT de Instrues especiais e clusulas na pgina 1104 para obter informaes adicionais. Restries adicionais como, por exemplo, FOREIGN KEY no resultam em erro, mas o tempo de execuo as ignora. Caso ocorra palavra-chave TEMP ou TEMPORARY entre CREATE e TABLE, a tabela criada permanece visvel apenas dentro da mesma conexo de banco de dados (ocorrncia de SQLConnection). Ela excluda automaticamente quando a conexo de banco de dados fechada. Todos os ndices criados em uma tabela temporria tambm so temporrios. As tabelas e os ndices temporrios so armazenados em um arquivo separado distinto do arquivo de banco de dados principal.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Suporte SQL em bancos de dados locais

1100

Caso o prefixo opcional database-name seja especificado, a tabela criada em um banco de dados nomeado (um banco de dados conectado instncia de SQLConnection pela chamada do mtodo attach() com o nome do banco de dados especificado). um erro especificar um prefixo database-name e a palavra-chave TEMP, a menos que o prefixo database-name seja temp. Caso nenhum nome de banco de dados seja especificado e a palavra-chave TEMP no esteja presente, a tabela criada no banco de dados principal (o banco de dados conectado instncia de SQLConnection usando o mtodo open() ou openAsync()). No h nenhum limite arbitrrio quanto ao nmero de colunas ou ao nmero de restries em uma tabela. Tambm no existe nenhum limite arbitrrio quanto quantidade de dados em uma linha. A forma CREATE TABLE AS define a tabela como o conjunto de resultados de uma consulta. Os nomes das colunas da tabela so os nomes das colunas no resultado. Caso a clusula opcional IF NOT EXISTS esteja presente e j haja outra tabela com o mesmo nome, o banco de dados ignora o comando CREATE TABLE. Uma tabela pode ser removida usando a instruo DROP TABLE, e alteraes limitadas podem ser feitas usando a instruo ALTER TABLE. ALTER TABLE O comando ALTER TABLE permite ao usurio renomear ou adicionar uma nova coluna a uma tabela existente. No possvel remover uma coluna de uma tabela.
sql-statement ::= ALTER TABLE [database-name.] table-name alteration alteration ::= RENAME TO new-table-name alteration ::= ADD [COLUMN] column-def

A sintaxe RENAME TO usada para renomear a tabela identificada por [database-name.] table-name para new-tablename. Esse comando no pode ser usado para mover uma tabela entre bancos de dados anexados, e sim apenas para renomear uma tabela dentro do mesmo banco de dados. Caso a tabela que est sendo renomeada tenha disparadores ou ndices, eles permanecem anexados tabela depois que ela renomeada. No entanto, caso haja alguma definio ou instruo de exibio executada por disparadores referente tabela que est sendo renomeada, eles no sero modificados automaticamente para usar o novo nome da tabela. Caso uma tabela renomeada tenha exibies ou disparadores, voc deve ignorar e recriar manualmente os disparadores ou as definies de exibio usando o novo nome da tabela. A sintaxe ADD [COLUMN] usada para adicionar uma nova coluna a uma tabela existente. A nova coluna sempre acrescentada ao final da lista de colunas existentes. A clusula column-def pode assumir qualquer uma das formas permitidas em uma instruo CREATE TABLE, com as seguintes restries:

A coluna talvez no tenha uma restrio PRIMARY KEY ou UNIQUE. A coluna talvez no tenha um valor padro igual a CURRENT_TIME, CURRENT_DATE ou
CURRENT_TIMESTAMP.

Caso seja especificada uma restrio NOT NULL, a coluna deve ter um valor padro diferente de NULL.
O momento da execuo da instruo ALTER TABLE no afetado pela quantidade de dados na tabela. DROP TABLE A instruo DROP TABLE remove uma tabela adicionada com uma instruo CREATE TABLE. A tabela com a tablename especificada a tabela ignorada. Ela totalmente removida do banco de dados e do arquivo em disco. Ela no pode ser recuperada. Todos os ndices associados tabela tambm so excludos.
sql-statement ::= DROP TABLE [IF EXISTS] [database-name.] table-name

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Suporte SQL em bancos de dados locais

1101

Por padro, a instruo DROP TABLE no reduz o tamanho do arquivo de banco de dados. O espao livre no banco de dados mantido e usado em operaes INSERT subsequentes. Para remover o espao livre no banco de dados, use o mtodo SQLConnection.clean(). Caso o parmetro autoClean esteja definido como true quando o banco de dados for criado inicialmente, o espao automaticamente liberado. A clusula IF EXISTS opcional suprime o erro que normalmente aconteceria se a tabela no existisse. CREATE INDEX O comando CREATE INDEX consiste nas palavras-chave CREATE INDEX seguidas do nome do novo ndice, a palavra-chave ON, o nome de uma tabela criada anteriormente a ser indexada e uma lista entre parnteses dos nomes das colunas na tabela cujos valores so usados na chave de ndice.
sql-statement column-name ::= ::= CREATE [UNIQUE] INDEX [IF NOT EXISTS] [database-name.] index-name ON table-name ( column-name [, column-name]* ) name [COLLATE collation-name] [ASC | DESC]

Cada nome de coluna pode ser seguido das palavras-chave ASC ou DESC para indicar a ordem de classificao, embora a designao da ordem de classificao seja ignorada pelo tempo de execuo. A classificao sempre feita na ordem crescente. A clusula COLLATE que segue cada nome de coluna define uma sequncia de intercalao usada nos valores de texto da coluna. A sequncia de intercalao padro a definida para a coluna na instruo CREATE TABLE. Caso nenhuma seja especificada, usada a sequncia de intercalao BINARY. Para obter uma definio da clusula COLLATE e das funes de intercalao, consulte COLLATE. No h limites arbitrrios quanto ao nmero de ndices que podem ser anexados a uma nica tabela. Tambm no existem limites para o nmero de colunas em um ndice. DROP INDEX A instruo drop index remove um ndice adicionado com a instruo CREATE INDEX. O ndice especificado removido completamente do arquivo de banco de dados. A nica forma de recuperar o ndice digitar novamente o comando CREATE INDEX apropriado.
sql-statement ::= DROP INDEX [IF EXISTS] [database-name.] index-name

Por padro, a instruo DROP INDEX no reduz o tamanho do arquivo de banco de dados. O espao livre no banco de dados mantido e usado em operaes INSERT subsequentes. Para remover o espao livre no banco de dados, use o mtodo SQLConnection.clean(). Caso o parmetro autoClean esteja definido como true quando o banco de dados for criado inicialmente, o espao automaticamente liberado. CREATE VIEW O comando CREATE VIEW atribui um nome a uma instruo SELECT predefinida. Esse novo nome pode ser usado em uma clusula FROM de outra instruo SELECT em lugar do nome de uma tabela. As exibies costumam ser usadas para simplificar as consultas, integrando um conjunto complexo (e muito usado) de dados a uma estrutura que pode ser usada em outras operaes.
sql-statement ::= CREATE [TEMP | TEMPORARY] VIEW [IF NOT EXISTS] [database-name.] view-name AS select-statement

Caso ocorra a palavra-chave TEMP ou TEMPORARY entre CREATE e VIEW, a exibio criada s permanece visvel para a ocorrncia de SQLConnection que abriu o banco de dados, sendo excluda automaticamente quando ele fechado.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Suporte SQL em bancos de dados locais

1102

Caso seja especificada uma [database-name], a exibio criada no banco de dados nomeado (um banco de dados conectado instncia de SQLConnection usando o mtodo attach(), com o argumento name especificado). um erro especificar uma [database-name] e a palavra-chave TEMP, a menos que [database-name] seja temp. Caso nenhum nome de banco de dados seja especificado e a palavra-chave TEMP no esteja presente, a exibio criada no banco de dados principal (o banco de dados conectado instncia de SQLConnection usando o mtodo open() ou openAsync()). As exibies so somente leitura. Uma instruo DELETE, INSERT ou UPDATE no pode ser usada em uma exibio, a menos que haja pelo menos um disparador do tipo associado (INSTEAD OF DELETE, INSTEAD OF INSERT, INSTEAD OF UPDATE) definido. CREATE TRIGGER Uma exibio removida de um banco de dados usando a instruo DROP VIEW. DROP VIEW A instruo DROP VIEW remove uma exibio criada por uma instruo CREATE VIEW.
sql-statement ::= DROP VIEW [IF EXISTS] view-name

A view-name especificada o nome da exibio a ser ignorada. Ela removida do banco de dados, mas nenhum dado nas tabelas subjacentes modificado. CREATE TRIGGER A instruo create trigger usada para adicionar disparadores ao esquema do banco de dados. Um disparador uma operao do banco de dados (a trigger-action) que realizada automaticamente quando ocorre um evento de banco de dados especificado (o database-event).
sql-statement name ::= CREATE [TEMP | TEMPORARY] TRIGGER [IF NOT EXISTS] [database-name.] trigger[BEFORE | AFTER] database-event ON table-name trigger-action ::= CREATE [TEMP | TEMPORARY] TRIGGER [IF NOT EXISTS] [database-name.] triggerINSTEAD OF database-event ON view-name trigger-action DELETE | INSERT | UPDATE | UPDATE OF column-list [FOR EACH ROW] [WHEN expr] BEGIN trigger-step ; [ trigger-step ; ]* END update-statement | insert-statement | delete-statement | select-statement column-name [, column-name]*

sql-statement name

database-event

::=

trigger-action

::=

trigger-step

::=

column-list

::=

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Suporte SQL em bancos de dados locais

1103

O acionamento de um disparador especificado sempre que ocorre uma DELETE, INSERT ou UPDATE em uma determinada tabela de banco de dados, ou sempre que uma UPDATE de uma ou mais colunas especificadas de uma tabela so atualizadas. Os disparadores so permanentes, a menos que a palavra-chave TEMP ou TEMPORARY seja usada. Nesse caso, o disparador removido quando a conexo de banco de dados principal da instncia de SQLConnection fechada. Caso nenhum tempo seja especificado (BEFORE ou AFTER), o disparador assume o padro BEFORE. Como s h suporte para disparadores FOR EACH ROW, o texto FOR EACH ROW opcional. Com um disparador FOR EACH ROW, as instrues trigger-step so executadas para todas as linhas do banco de dados inserido, atualizado ou excludo pela instruo que faz com que o disparador seja acionado, caso a expresso de clusula WHEN seja avaliada como true. Caso uma clusula WHEN seja fornecida, as instrues SQL especificadas como etapas do disparador s so executadas em linhas para as quais a clusula WHEN verdadeira. Caso nenhuma clusula WHEN seja fornecida, as instrues SQL so executadas em todas as linhas. No corpo de um disparador, (a clusula trigger-action) os valores anteriores e posteriores alterao da tabela afetada esto disponveis usando os nomes de tabela especiais OLD e NEW. A estrutura das tabelas OLD e NEW corresponde estrutura da tabela na qual o disparador criado. A tabela OLD contm todas as linhas modificadas ou excludas pela instruo de acionamento, no estado anterior s operaes da instruo de acionamento. A tabela NEW contm todas as linhas modificadas ou criadas pela instruo de acionamento, no estado posterior s operaes da instruo de acionamento. A clusula WHEN e as instrues trigger-step podem acessar valores na linha que est sendo inserida, excluda ou atualizada usando referncias da forma NEW.column-name e OLD.column-name, em que column-name o nome de uma coluna da tabela qual o disparador est associado. A disponibilidade das referncias de tabela OLD e NEW depende do tipo de database-event tratado pelo disparador:

INSERT Referncias NEW so vlidas UPDATE Referncias NEW e OLD so vlidas DELETE Referncias OLD so vlidas
O tempo especificado (BEFORE, AFTER ou INSTEAD OF) determina quando as instrues trigger-step so executadas em relao insero, modificao ou remoo da linha associada. Uma clusula ON CONFLICT pode ser especificada como parte de uma instruo UPDATE ou INSERT em uma trigger-step. No entanto, caso uma clusula ON CONFLICT seja especificada como parte da instruo, o que faz com que o disparador seja acionado, usada essa poltica de tratamento de conflitos. Alm dos disparadores de tabela, um disparador INSTEAD OF pode ser criado em uma exibio. Caso um ou mais disparadores INSTEAD OF INSERT, INSTEAD OF DELETE ou INSTEAD OF UPDATE sejam definidos em uma exibio, isso no considerado erro para executar o tipo associado de instruo (INSERT, DELETE ou UPDATE) na exibio. Nesse caso, executar uma INSERT, DELETE ou UPDATE na exibio faz com que os disparadores associados sejam acionados. Como o disparador INSTEAD OF, as tabelas subjacentes exibio no so modificadas pela instruo que faz com que o disparador seja acionado. No entanto, os disparadores podem ser usados para realizar operaes de modificao nas tabelas subjacentes. H algo importante para se ter em mente durante a criao de um disparador em uma tabela com uma coluna INTEGER PRIMARY KEY. Caso um disparador BEFORE modifique a coluna INTEGER PRIMARY KEY de uma linha a ser atualizada pela instruo que faz com que o disparador seja acionado, a atualizao no ocorre. Uma soluo criar a tabela com uma coluna PRIMARY KEY e no uma coluna INTEGER PRIMARY KEY. Um disparador pode ser removido usando a instruo DROP TRIGGER. Quando uma tabela ou exibio ignorada, todos os disparadores associados tambm so ignorados automaticamente.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Suporte SQL em bancos de dados locais

1104

Funo RAISE() Uma funo SQL RAISE() especial pode ser usada em uma instruo trigger-step de um disparador. Essa funo tem a seguinte sintaxe:
raise-function ::= RAISE RAISE RAISE RAISE ( ( ( ( ABORT, error-message ) | FAIL, error-message ) | ROLLBACK, error-message ) | IGNORE )

Quando uma das trs primeiras formas chamada durante a execuo do disparador, a ao de processamento ON CONFLICT especificada (ABORT, FAIL ou ROLLBACK) realizada, e a execuo da instruo atual concluda. Como ROLLBACK considerada uma falha na execuo da instruo, a instncia de SQLStatement cujo mtodo execute() estava sendo realizado despacha um evento error (SQLErrorEvent.ERROR). O objeto SQLError na propriedade error do objeto do evento despachado tem o conjunto de propriedades details definido como a errormessage especificada na funo RAISE(). Quando RAISE(IGNORE) chamada, o restante do disparador atual, a instruo que fez com que o disparador fosse executado e todos os disparadores subsequentes que seriam executados so abandonados. Nenhuma alterao feita no banco de dados revertida. Caso a instruo que fez com que o disparador fosse executado seja ela prpria parte de um disparador, esse programa disparador reinicia a execuo no incio da prxima etapa. Para obter mais informaes sobre os algoritmos para resoluo de conflitos, consulte a seo ON CONFLICT (algoritmos em conflito). DROP TRIGGER A instruo DROP TRIGGER remove um disparador criado pela instruo CREATE TRIGGER.
sql-statement ::= DROP TRIGGER [IF EXISTS] [database-name.] trigger-name

O disparador excludo do banco de dados. Observe que os disparadores so ignorados automaticamente quando a tabela associada ignorada.

Instrues especiais e clusulas

Esta seo descreve vrias clusulas que so extenses do SQL fornecidas pelo tempo de execuo, bem como dois elementos de linguagem que podem ser usados em muitas instrues, comentrios e expresses. COLLATE A clusula COLLATE usada em instrues SELECT, CREATE TABLE e CREATE INDEX para especificar o algoritmo de comparao usado durante a comparao ou a classificao dos valores.
sql-statement collation-name ::= ::= COLLATE collation-name BINARY | NOCASE

O tipo de intercalao padro de colunas BINARY. Quando a intercalao BINARY usada com valores da classe de armazenamento TEXT, a intercalao binria realizada comparando-se os bytes na memria que representam o valor, independentemente da codificao do texto. A sequncia de intercalao NOCASE s aplicada a valores da classe de armazenamento TEXT. Quando usada, a intercalao NOCASE realiza uma comparao sem diferenciao entre maisculas e minsculas. Nenhuma sequncia de intercalao usada em classes de armazenamento do tipo NULL, BLOB, INTEGER ou REAL.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Suporte SQL em bancos de dados locais

1105

Para usar um tipo de intercalao que no seja BINARY com uma coluna, uma clusula COLLATE deve ser especificada como parte da definio da coluna na instruo CREATE TABLE. Sempre que dois valores TEXT so comparados, uma sequncia de intercalao usada para determinar os resultados da comparao de acordo com as seguintes regras:

Em operadores de comparao binria, caso um dos operandos seja uma coluna, o tipo de intercalao padro da
coluna determina a sequncia de intercalao usada na comparao. Caso ambos os operandos sejam colunas, o tipo de intercalao do operando esquerda determina a sequncia de intercalao usada. Caso nenhum dos operandos seja uma coluna, usada a sequncia de intercalao BINARY.

O operador BETWEEN...AND equivale ao uso de duas expresses com os operadores >= e <=. Por exemplo, a
expresso x BETWEEN y AND z equivalente a x >= y AND x <= z. Consequentemente, o operador BETWEEN...AND segue a regra anterior para determinar a sequncia de intercalao.

O operador IN se comporta como o operador = com o objetivo de determinar a sequncia de intercalao a ser
usada. Por exemplo, a sequncia de intercalao usada na expresso x IN (y, z) o tipo de intercalao padro x caso x seja uma coluna. Do contrrio, usada a intercalao BINARY.

Uma clusula ORDER BY que faz parte de uma instruo SELECT pode ser atribuda explicitamente a uma
sequncia de intercalao a ser usada na operao de classificao. Nesse caso, a sequncia de intercalao explcita usada sempre. Do contrrio, caso a expresso classificada por uma clusula ORDER BY seja uma coluna, o tipo de intercalao padro usado para determinar a ordem de classificao. Caso a expresso no seja uma coluna, usada a sequncia de intercalao BINARY. EXPLAIN O modificador de comando EXPLAIN uma extenso no padro do SQL.
sql-statement ::= EXPLAIN sql-statement

Caso a palavra-chave EXPLAIN seja exibida antes de qualquer outra instruo SQL, em vez de efetivamente executar o comando, o resultado informa a sequncia das instrues da mquina virtual que seriam usadas para executar o comando, se a palavra-chave EXPLAIN no estivesse presente. O recurso EXPLAIN um recurso avanado e permite aos desenvolvedores alterar o texto da instruo SQL em uma tentativa de otimizar o desempenho ou depurar uma instruo que no parece estar funcionando corretamente. ON CONFLICT (algoritmos em conflito) A clusula ON CONFLICT no um comando SQL separado. Trata-se de uma clusula no padro que pode ser exibida em muitos outros comandos SQL.
conflict-clause conflict-clause conflict-algorithm ::= ::= ::= ON CONFLICT conflict-algorithm OR conflict-algorithm ROLLBACK | ABORT | FAIL | IGNORE | REPLACE

A primeira forma da clusula ON CONFLICT, usando as palavras-chave ON CONFLICT, usada em uma instruo CREATE TABLE. Em uma instruo INSERT ou UPDATE, usada a segunda forma, com ON CONFLICT substituda por OR para fazer a sintaxe parecer mais natural. Por exemplo, em vez de INSERT ON CONFLICT IGNORE, a instruo se torna INSERT OR IGNORE. Embora as palavras-chave sejam diferentes, o significado da clusula o mesmo nas duas formas.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Suporte SQL em bancos de dados locais

1106

A clusula ON CONFLICT especifica o algoritmo usado para resolver conflitos de restrio. Os cinco algoritmos so ROLLBACK, ABORT, FAIL, IGNORE e REPLACE. O algoritmo padro ABORT. A seguir, uma explicao dos cinco algoritmos de conflito:
ROLLBACK Quando ocorre uma violao de restrio, ocorre uma ROLLBACK imediata, encerrando a transao

atual. O comando abortado e a ocorrncia de SQLStatement despacha um erro error. Caso no haja nenhuma transao ativa (outra que no seja a implcita criada em todos os comandos), esse algoritmo funciona da mesma forma que ABORT.
ABORT Quando ocorre uma violao de restrio, o comando restaura todas as alteraes anteriores que possa ter feito

e a ocorrncia de SQLStatement gera um evento error. Como nenhuma ROLLBACK executada, as alteraes feitas em comandos anteriores em uma transao so preservadas. ABORT o comportamento padro.
FAIL Quando ocorre uma violao de restrio, o comando abortado e a SQLStatement gera um evento error. No

entanto, todas as alteraes feitas no banco de dados pela instruo antes de encontrar a violao de restrio so preservadas, e no restauradas. Por exemplo, caso uma instruo UPDATE encontre uma violao de restrio na 100 linha que ela tenta atualizar, as alteraes iniciais feitas nas 99 linhas so preservadas, mas as feitas nas linhas 100 e posteriores no ocorrem.
IGNORE Quando ocorre uma violao de restrio, uma linha que contm a violao de restrio no inserida ou

alterada. Alm de essa linha ser ignorada, o comando continua sendo executado normalmente. Outras linhas anteriores e posteriores linha que apresentava a violao de restrio continuavam sendo inseridas ou atualizadas normalmente. Nenhum erro retornado.
REPLACE Quando ocorre uma violao de restrio UNIQUE, as linhas preexistentes que esto causando a violao de restrio so removidas antes de inserir ou atualizar a linha atual. Consequentemente, a insero ou a atualizao sempre ocorre e o comando continua sendo executado normalmente. Nenhum erro retornado. Caso ocorra uma violao de restrio NOT NULL, o valor NULL substitudo pelo valor padro da coluna. Caso a coluna no tenha nenhum valor padro, usado o algoritmo ABORT. Caso ocorra uma violao de restrio CHECK, usado o algoritmo IGNORE. Quando essa estratgia de resoluo de conflitos exclui linhas para atender a uma restrio, ela no invoca disparadores de excluso nessas linhas.

O algoritmo especificado na clusula OR de uma instruo INSERT ou UPDATE substitui todos os algoritmos especificados em uma instruo CREATE TABLE. Caso nenhum algoritmo seja especificado na instruo CREATE TABLE ou na instruo INSERT ou UPDATE em execuo, usado o algoritmo ABORT. REINDEX O comando REINDEX usado para excluir e recriar um ou mais ndices. Esse comando til quando a definio de uma sequncia de intercalao alterada.
sql-statement sql-statement ::= ::= REINDEX collation-name REINDEX [database-name .] ( table-name | index-name )

Na primeira forma, todos os ndices em todos os bancos de dados anexados que usam a sequncia de intercalao nomeada so recriados. Na segunda forma, quando especificada table-name, todos os ndices associados tabela so recriados. Caso uma index-name seja fornecida, apenas o ndice especificado excludo e recriado. COMMENTS Comentrios no so comandos SQL, mas podem ocorrer em consultas SQL. Eles so tratados como espao em brando pelo tempo de execuo. Eles podem comear em qualquer lugar onde haja um espao em branco, inclusive dentro de expresses que se estendam por vrias linhas.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Suporte SQL em bancos de dados locais

1107

comment

::=

single-line-comment ::= block-comment ::=

single-line-comment | block-comment -- single-line /* multiple-lines or block [*/]

Um comentrio com uma nica linha indicado por dois traos. Ele s se estende at o final da linha atual. Comentrios em bloco podem se estender por um nmero variado de linhas ou ser incorporados a uma nica linha. Caso no haja nenhum delimitador de encerramento, um comentrio em bloco se estende at o final da entrada. Essa situao no tratada como um erro. Uma nova instruo SQL pode comear em uma linha aps o trmino do comentrio em bloco. Os comentrios em bloco podem ser incorporados em qualquer lugar onde haja um espao em branco, inclusive expresses internas e no meio de outras instrues SQL. Os comentrios em bloco no so aninhados. Comentrios em linha nica dentro de um comentrio em bloco so ignorados. EXPRESSIONS As expresses so subcomandos dentro de outros blocos SQL. A seguir, a descrio da sintaxe vlida de uma expresso dentro de uma instruo SQL:
expr ::= expr binary-op expr | expr [NOT] like-op expr [ESCAPE expr] | unary-op expr | ( expr ) | column-name | table-name.column-name | database-name.table-name.column-name | literal-value | parameter | function-name( expr-list | * ) | expr ISNULL | expr NOTNULL | expr [NOT] BETWEEN expr AND expr | expr [NOT] IN ( value-list ) | expr [NOT] IN ( select-statement ) | expr [NOT] IN [database-name.] table-name | [EXISTS] ( select-statement ) | CASE [expr] ( WHEN expr THEN expr )+ [ELSE expr] END | CAST ( expr AS type ) | expr COLLATE collation-name LIKE | GLOB see Operators see Operators :param-name | @param-name | ? literal-value [, literal-value]* literal-string | literal-number | literal-boolean | literal-blob |

like-op ::= binary-op ::= unary-op ::= parameter ::= value-list ::= literal-value ::= literal-null literal-string ::= 'string value' literal-number ::= integer | number literal-boolean ::= true | false literal-blob ::= X'string of hexadecimal data' literal-null ::= NULL

Uma expresso uma combinao de valores e operadores que podem ser resolvidos como um valor nico. As expresses podem ser divididas em dois tipos gerais, dependendo de sua resoluo como um valor booleano (true ou false) ou como um valor no booleano.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Suporte SQL em bancos de dados locais

1108

Em vrias situaes comuns, inclusive em uma clusula WHERE, HAVING, a expresso ON em uma clusula JOIN e uma expresso CHECK, a expresso deve ser resolvida como um valor booleano. Os tipos de expresses a seguir atendem a essa condio:

ISNULL NOTNULL IN () EXISTS () LIKE GLOB Determinadas funes Determinados operadores (mais especificamente operadores de comparao)
Valores literais Um valor numrico literal escrito como um nmero inteiro ou um nmero de ponto flutuante. A notao cientfica suportada. O quantificador . (ponto final) sempre usado como a casa decimal. Uma string literal indicada colocando a string entre aspas simples '. Para incluir uma aspa simples dentro de uma string, coloque duas aspas simples em sequncia como este exemplo: Um literal booleano indicado pelo valor true ou false. Os valores booleanos literais so usados com o tipo de dados da coluna Booleana. Um literal de BLOB uma string literal contendo dados hexadecimais e aps um nico caractere x ou X como, por exemplo, X'53514697465'. Um valor literal tambm pode ser o token NULL. Nome da coluna Um nome de coluna pode ser qualquer um dos nomes definidos na instruo CREATE TABLE ou em um dos seguintes identificadores especiais: Esses identificadores especiais descrevem a chave de inteiro aleatria exclusiva (a chave de linha) associada a todas as linhas de cada tabela. Os identificadores especiais s se referem chave de linha caso a instruo CREATE TABLE no defina uma coluna real com o mesmo nome. As chaves de linha se comportam como colunas somente leitura. Uma chave de linha pode ser usada em qualquer lugar onde uma coluna normal possa ser usada, exceto pelo fato de no ser possvel alterar o valor de uma chave de linha em uma instruo UPDATE ou INSERT. A instruo SELECT * FROM table no inclui a chave de linha no conjunto de resultados. Instruo SELECT Uma instruo SELECT pode ser exibida em uma expresso como o operando direita do operador IN, como quantidade escalar (um nico valor de resultado), ou como o operando de um operador EXISTS. Quando usada como quantidade escalar ou o operando de um operador IN, a SELECT s pode ter uma nica coluna no resultado. Uma instruo SELECT composta (conectada com palavras-chave como UNION ou EXCEPT) permitida. Com o operador EXISTS, as colunas do conjunto de resultados de SELECT so ignoradas e a expresso retorna TRUE caso haja uma ou mais linhas e FALSE caso o conjunto de resultados seja vazio. Caso nenhum termo da expresso SELECT se refira ao valor na consulta, a expresso avaliada uma vez antes de qualquer outro processamento e o resultado reutilizado conforme necessrio. Caso a expresso SELECT no contenha variveis da consulta externa, conhecida como subconsulta correlacionada, a SELECT reavaliada sempre que necessrio.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Suporte SQL em bancos de dados locais

1109

Quando uma SELECT for o operando direita do operador IN, o operador IN retorna TRUE caso o resultado do operando esquerda seja igual a qualquer um dos valores no conjunto de resultados da instruo SELECT. O operador IN pode ser precedido pela palavra-chave NOT para inverter o sentido do teste. Quando uma SELECT exibida dentro de uma expresso, mas no operando direita de um operador IN, a primeira linha do resultado da SELECT se torna o valor usado na expresso. Caso a SELECT produza mais de uma linha de resultado, todas as linhas depois dela so ignoradas. Caso a SELECT no produza nenhuma linha, o valor da SELECT NULL. Expresso CAST Uma expresso CAST altera o tipo de dados do valor especificado para o especificado. O tipo especificado pode ser um nome de tipo no vazio vlido para o tipo em uma definio de coluna de uma instruo CREATE TABLE. Suporte ao tipo de dados Elementos de expresso adicionais Os elementos SQL a seguir tambm podem ser usados em expresses:

Funes internas: funes agregadas, funes escalares e funes de formatao de data/hora Operadores Parmetros

Funes internas
As funes internas se encaixam em trs categorias principais:

Funes agregadas Funes escalares Funes de data e hora

Alm dessas funes, existe uma funo especial RAISE() usada para fornecer a notificao de um erro na execuo de um disparador. Essa funo s pode ser usada no corpo de uma instruo CREATE TRIGGER. Para obter informaes sobre a funo RAISE(), consulte CREATE TRIGGER > RAISE(). Assim como todas as palavras-chave em SQL, os nomes da funo no diferenciam maisculas de minsculas. Funes agregadas As funes agregadas realizam operaes em valores de vrias linhas. Essas funes so especialmente usadas em instrues SELECT com a clusula GROUP BY.
AVG(X) Retorna o valor mdio de todo X que no seja NULL em um grupo. Os valores de string e BLOB que no se parecem com nmeros so interpretados como 0. O resultado de AVG() sempre um valor de ponto flutuante, mesmo que todas as entradas sejam inteiros. A primeira forma retorna uma contagem do nmero de vezes em que X no NULL em um grupo. A segunda forma (com o argumento *) retorna o nmero total de linhas no grupo. Retorna o valor mximo de todos os valores no grupo. A ordem de classificao comum usada para determinar o mximo. Retorna o valor mnimo que no seja NULL de todos os valores no grupo. A ordem de classificao comum usada para determinar o mnimo. Caso todos os valores no grupo sejam NULL, NULL retornado. Retorna a soma numrica de todos os valores que no sejam NULL no grupo. Caso todos os valores sejam NULL, SUM() retorna NULL e TOTAL() retorna 0.0. O resultado de SUM() um valor inteiro caso todas as entradas que no sejam NULL sejam inteiros. Caso alguma entrada SUM() no seja um inteiro e no NULL, SUM() retorna um valor de ponto flutuante. Esse valor pode ser uma aproximao da soma real.

COUNT(X) COUNT(*) MAX(X) MIN(X)

SUM(X) TOTAL(X)

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Suporte SQL em bancos de dados locais

1110

Em qualquer uma das funes agregadas anteriores que usam um nico argumento, esse argumento pode ser precedido pela palavra-chave DISTINCT. Nesse caso, os elementos duplicados so filtrados antes de serem passados para a funo agregada. Por exemplo, a chamada de funo COUNT(DISTINCT x) retorna o nmero de valores distintos da coluna X e no o nmero total de valores que no sejam NULL na coluna x. Funes escalares As funes escalares funcionam em valores uma linha por vez.
ABS(X) COALESCE(X, Y, ...) GLOB(X, Y) IFNULL(X, Y) HEX(X) LAST_INSERT_ROWID( ) LENGTH(X) LIKE(X, Y [, Z]) Retorna o valor absoluto do argumento X. Retorna uma cpia do primeiro argumento que no seja NULL. Caso todos os argumentos sejam NULL, NULL retornado. Deve haver pelo menos dois argumentos. Essa funo usada para implementar a sintaxe X GLOB Y. Retorna uma cpia do primeiro argumento que no seja NULL. Caso ambos os argumentos sejam NULL, NULL retornado. Essa funo se comporta da mesma forma que COALESCE(). O argumento interpretado como um valor do tipo de armazenamento BLOB. O resultado um processamento hexadecimal do contedo desse valor. Retorna o identificador de linha (chave primria gerada) da ltima linha inserida no banco de dados pela SQLConnection atual. Este valor o mesmo valor retornado pela propriedade SQLConnection.lastInsertRowID. Retorna o comprimento da string de X em caracteres. Essa funo usada para implementar a sintaxe X LIKE Y [ESCAPE Z] de SQL. Caso a clusula ESCAPE opcional esteja presente, a funo invocada com trs argumentos. Do contrrio, ela invocada com apenas dois argumentos. Retorna uma cpia da string X com todos os caracteres convertidos em minsculas. Retorna uma string formada pela remoo dos espaos esquerda de X. Caso um argumento Y seja especificado, a funo remove todos os caracteres em Y esquerda de X. Retorna o argumento com o valor mximo. Alm de nmeros, os argumentos podem ser strings. O valor mximo determinado pela ordem de classificao definida. Observe que MAX() uma funo simples quando tem 2 ou mais argumentos, mas uma funo agregada quando tem um nico argumento. Retorna o argumento com o valor mnimo. Alm de nmeros, os argumentos podem ser strings. O valor mnimo determinado pela ordem de classificao definida. Observe que MIN() uma funo simples quando tem 2 ou mais argumentos, mas uma funo agregada quando tem um nico argumento. Retorna o primeiro argumento caso os argumentos sejam diferentes; do contrrio, ele retorna NULL. Essa rotina retorna uma string que o valor do argumento apropriado incluso em outra instruo SQL. As strings so colocadas entre aspas simples com escapes em aspas internas conforme necessrio. As classes de armazenamento BLOB so codificadas como literais hexadecimais. A funo til durante a criao de disparadores para implementar a funcionalidade desfazer/refazer. Gera um inteiro pseudoaleatrio entre -9223372036854775808 e 9223372036854775807. Esse valor aleatrio no criptogrfico. Retorna um BLOB de N bytes que contm bytes pseudo-aleatrios. N deve ser um inteiro positivo. Esse valor aleatrio no criptogrfico. Caso o valor de N seja negativo, retornado um nico byte. Arredonda o nmero X para Y dgitos direita da casa decimal. Caso o argumento Y seja omitido, usado 0. Retorna uma string formada pela remoo dos espaos direita de X. Caso um argumento Y seja especificado, a funo remove todos os caracteres em Y direita de X. Gera uma subsequncia de caractares da sequncia de entrada X que comea com o Y caractere e que tem Z caracteres de comprimento. O caractere mais esquerda de X a posio de ndice 1. Se Y for negativo, o primeiro caractere da subsequncia de caracteres encontrado contando-se a partir da direita e no da esquerda. Retorna uma string formada pela remoo dos espaos direita de X. Caso um argumento Y seja especificado, a funo remove todos os caracteres em Y direita de X. Retorna o tipo da expresso X. Os valores de retorno possveis so 'null', 'integer', 'real', 'text' e 'blob'. Suporte ao tipo de dados Retorna uma cpia da string de entrada X convertida em letras todas em maisculas. Retorna um BLOB que contm N bytes de 0x00.

LOWER(X) LTRIM(X) LTRIM(X, Y) MAX(X, Y, ...)

MIN(X, Y, ...)

NULLIF(X, Y) QUOTE(X)

RANDOM(*) RANDOMBLOB(N)

ROUND(X) ROUND(X, Y) RTRIM(X) SUBSTR(X, Y, Z)

TRIM(X) TRIM(X, Y) TYPEOF(X) UPPER(X) ZEROBLOB(N)

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Suporte SQL em bancos de dados locais

1111

Funes de formatao de data e hora As funes de formatao de data e hora so um grupo de funes escalares usadas para criar dados de data e hora formatados. Observe que essas funes operam e retornam valores de string e nmero. Essas funes no devem ser usadas com o tipo de dados DATE. Caso voc use essas funes nos dados de uma coluna cujo tipo de dados declarado DATE, elas no se comportam como esperado.
DATE(T, ...) A funo DATE() retorna uma string contendo a data neste formato: YYYY-MM-DD. O primeiro parmetro (T) especifica uma string de hora do formato encontrado em Formatos de hora. possvel especificar um nmero qualquer de modificadores aps a string de hora. Esses modificadores podem ser encontrados em Modificadores. A funo TIME() retorna uma string que contm a hora como HH:MM:SS. O primeiro parmetro (T) especifica uma string de hora do formato encontrado em Formatos de hora. possvel especificar um nmero qualquer de modificadores aps a string de hora. Esses modificadores podem ser encontrados em Modificadores. A funo DATETIME() retorna uma string que contm a data e a hora no formato YYYY-MM-DD HH:MM:SS. O primeiro parmetro (T) especifica uma string de hora do formato encontrado em Formatos de hora. possvel especificar um nmero qualquer de modificadores aps a string de hora. Esses modificadores podem ser encontrados em Modificadores. A funo JULIANDAY()retorna um nmero que indica quantos dias em relao a Greenwich em 24 de novembro de 4714 A.C. e a data fornecida. O primeiro parmetro (T) especifica uma string de hora do formato encontrado em Formatos de hora. possvel especificar um nmero qualquer de modificadores aps a string de hora. Esses modificadores podem ser encontrados em Modificadores. A rotina STRFTIME() retorna a data formatada de acordo com a string do formato especificado como o primeiro argumento F. A string do formato oferece suporte s seguintes substituies: %d - dia do ms %f - segundos fracionrios SS.SSS %H - hora 00-24 %j - dia do ano 001-366 %J - nmero do dia Juliano %m - ms 01-12 %M - minuto 00-59 %s - segundos desde 1970-01-01 %S - segundo 00-59 %w - dias da semana 0-6 (domingo = 0) %W - semana do ano 00-53 %Y - ano 0000-9999 %% - % O segundo parmetro (T) especifica uma string de hora do formato encontrado em Formatos de hora. possvel especificar um nmero qualquer de modificadores aps a string de hora. Esses modificadores podem ser encontrados em Modificadores.

TIME(T, ...)

DATETIME(T, ...)

JULIANDAY(T, ...)

STRFTIME(F, T, ...)

Formatos de hora Uma string de hora pode estar em qualquer um dos seguintes formatos:
YYYY-MM-DD YYYY-MM-DD HH:MM YYYY-MM-DD HH:MM:SS YYYY-MM-DD HH:MM:SS.SSS YYYY-MM-DDTHH:MM YYYY-MM-DDTHH:MM:SS YYYY-MM-DDTHH:MM:SS.SSS 2007-06-15 2007-06-15 07:30 2007-06-15 07:30:59 2007-06-15 07:30:59.152 2007-06-15T07:30 2007-06-15T07:30:59 2007-06-15T07:30:59.152

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Suporte SQL em bancos de dados locais

1112

HH:MM HH:MM:SS HH:MM:SS.SSS Fazer agora DDDD.DDDD

07:30 (a data 2000-01-01) 07:30:59 (a data 2000-01-01) 07:30:59:152 (a data 2000-01-01) Data e hora atuais em Universal Coordinated Time (UTC). Nmero do dia Juliano como nmero de ponto flutuante.

O caractere V nesses formatos um caractere literal "T" que separa a data e a hora. Os formatos que s incluem uma hora pressupem a data 2001-01-01. Modificadores A string de hora pode ser seguida de zero ou mais modificadores que alteram a data ou a interpretao da data. Os modificadores disponveis so os seguintes:
NNN days NNN hours NNN minutes NNN.NNNN seconds NNN months NNN years start of month start of year start of day weekday N localtime utc Nmero de dias a serem adicionados hora. Nmero de horas a serem adicionadas hora. Nmero de minutos a serem adicionados hora. Nmero de segundos e milsimos de segundo a serem adicionados hora. Nmero de meses a serem adicionados hora. Nmero de anos a serem adicionados hora. Alterne a hora para o comeo do ms. Alterne a hora para o comeo do ano. Alterne a hora para o comeo do dia. Avana a hora para o dia da semana especificado. (0 = domingo, 1 = segunda-feira e assim por diante) Converte a data em hora local. Converte a data em UTC

Operadores
SQL oferece suporte a uma ampla seleo de operadores, inclusive operadores comuns existentes na maior parte das linguagens de programao, bem como vrios operadores exclusivos do SQL. Operadores comuns Os seguintes operadores binrios so permitidos em um bloco SQL, estando listados da maior para a menor precedncia:
* / % + << >> & | < >= > >= = == != AND OR

<> IN

Os operadores de prefixo unrios para os quais h suporte so:

! ~ NOT

O operador COLLATE pode ser considerado um operador de sufixo unrio. O operador COLLATE apresenta a maior precedncia. Ele sempre mais vinculado do que qualquer operador unrio de prefixo ou operador binrio. Observe que existem duas variaes dos operadores de igualdade e de no-igualdade. A igualdade pode ser = ou ==. O operador de no-igualdade pode ser != ou <>.= ou <>. O operador || o operador de concatenao da stringele une as duas strings dos operandos.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Suporte SQL em bancos de dados locais

1113

O operador % fornece o restante do mdulo do operando esquerda no operando direita. O resultado de qualquer operador binrio um valor numrico, exceto pelo operador de concatenao || que fornece um resultado de string. Operadores SQL LIKE O operador LIKE realiza uma comparao de padres.
expr pattern ::= ::= (column-name | expr) LIKE pattern '[ string | % | _ ]'

O operando direita do operador LIKE contm o padro e o operando esquerda contm a string de acordo com o padro. Um smbolo de porcentagem (%) no padro um caractere curingaele corresponde a qualquer sequncia de zero ou mais caracteres na string. Um sublinhado (_) no padro corresponde a um nico caractere da string. Qualquer outro caractere se compara ou o equivalente em maisculas/minsculas, ou seja, so feitas as correspondncias de maneira sem diferenciao de maisculas e minsculas. o mecanismo de banco de dados s compreende maisculas/minsculas em caracteres Latinos de 7 bits. Consequentemente, o operador LIKE diferencia maisculas e minsculas para caracteres iso8859 de 8 bits ou caracteres UTF-8. Por exemplo, a expresso 'a' LIKE 'A' TRUE, mas '' LIKE '' FALSE). A diferenciao entre maisculas e minsculas para caracteres Latin pode ser alterada usando a propriedade SQLConnection.caseSensitiveLike. Caso a clusula opcional ESCAPE esteja presente, a expresso aps a palavra-chave ESCAPE deve ser avaliada como uma string que consiste em um nico caractere. Esse caractere pode ser usado no padro LIKE para corresponder aos caracteres de porcentagem literal ou sublinhado. O caractere de escape seguido de um smbolo de porcentagem, sublinhado ou ele prprio compara um smbolo de porcentagem, sublinhado ou caractere de escapa na string, respectivamente. GLOB O operador GLOB semelhante a LIKE, mas usa a sintaxe globbing do arquivo Unix nos curingas. Diferentemente de LIKE, GLOB diferencia maisculas de minsculas. IN O operador IN calcula se o operando esquerda igual a um dos valores no operando direita (um conjunto de valores entre parnteses).
in-expr ::= expr [NOT] IN expr [NOT] IN expr [NOT] IN literal-value ( value-list ) | ( select-statement ) | [database-name.] table-name [, literal-value]*

value-list

::=

O operando direita pode ser um conjunto de valores literais separados por vrgulas ou o resultado de uma instruo SELECT. Consulte as instrues SELECT em expresses para obter uma explicao e saber as limitaes quanto ao uso de uma instruo SELECT como operando direita do operador IN. BETWEEN...AND O operador BETWEEN...AND equivale ao uso de duas expresses com os operadores >= e <=. Por exemplo, a expresso x BETWEEN y AND z equivalente a x >= y AND x <= z. NOT NOT um operador de negao. Os operadores GLOB, LIKE, e IN podem ser precedidos pela palavra-chave NOT para inverter o sentido do teste (em outras palavras, para verificar se um valor no corresponde ao padro indicado).

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Suporte SQL em bancos de dados locais

1114

Parmetros
Um parmetro especifica um alocador de espao na expresso para um valor literal preenchido durante o tempo de execuo atribuindo um valor matriz associativa SQLStatement.parameters. Os parmetros podem ter trs formas:
Um ponto de interrogao indica um parmetro indexado. Os parmetros recebem valores de ndice numrico (com base em zero) de acordo com a ordem na instruo. Uma vrgula seguida de um nome de identificador mantm um ponto no parmetro nomeado com o nome AAAA. Os parmetros nomeados tambm so numerados de acordo com sua ordem na instruo SQL. Para evitar confuso, melhor evitar a mistura de parmetros nomeados e numerados. Um sinal de arroba equivalente a uma vrgula.

:AAAA

@AAAA

Recursos SQL para os quais no h suporte

Esta uma lista dos elementos SQL padro para os quais no h suporte no Adobe AIR:
Restries de FOREIGN KEY As restries de FOREIGN KEY so analisadas, mas no so exigidas. Disparadores Os disparadores FOR EACH STATEMENT no so permitidos (todos os disparadores devem ser FOR

EACH ROW). Os disparadores INSTEAD OF no podem ser usados em tabelas (os disparadores INSTEAD OF s podem ser usados em modos de exibio). Disparadores recursivos disparadores que se acionam automaticamente no so suportados.
ALTER TABLE Apenas as variantes RENAME TABLE e ADD COLUMN do comando ALTER TABLE podem ser usadas. Outros tipos de operaes ALTER TABLE como, por exemplo, DROP COLUMN, ALTER COLUMN, ADD CONSTRAINT etc. so ignorados. Transaes aninhadas Apenas uma nica transao ativa permitida. RIGHT e FULL OUTER JOIN RIGHT OUTER JOIN ou FULL OUTER JOIN no so permitidos. VIEW Atualizvel Um modo de exibio exclusivo para leitura. Voc talvez no execute uma instruo DELETE,

INSERT ou UPDATE em uma exibio. H suporte para um disparador INSTEAD OF acionado diante de uma tentativa de uso de DELETE, INSERT ou UPDATE em uma exibio, podendo ser usado para atualizar tabelas de suporte no corpo do disparador.
GRANT e REVOKE m banco de dados um arquivo em disco comum; as nicas permisses de acesso que podem ser aplicadas so as permisses normais de acesso ao arquivo do sistema operacional subjacente. Os comandos GRANT e REVOKE normalmente encontrados em RDBMSs de cliente/servidor no so implementados.

H suporte aos seguintes elementos SQL e os recursos do SQLite em algumas implementaes de SQLite, mas no no Adobe AIR. Grande parte dessa funcionalidade est disponvel por meio de mtodos da classe SQLConnection:
Elementos SQL relacionados transao (BEGIN, END, COMMIT, ROLLBACK) Essa funo disponibilizada pelos mtodos relacionados transao da classe SQLConnection: SQLConnection.begin(), SQLConnection.commit() e SQLConnection.rollback(). ANALYZE Essa funo disponibilizada pelo mtodo SQLConnection.analyze(). ATTACH ssa funo disponibilizada pelo mtodo SQLConnection.attach(). COPY Esta instruo no suportada. CREATE VIRTUAL TABLE Esta instruo no suportada. DETACH Essa funo disponibilizada pelo mtodo SQLConnection.detach(). PRAGMA Esta instruo no suportada. VACUUM Essa funo disponibilizada pelo mtodo SQLConnection.compact().

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Suporte SQL em bancos de dados locais

1115

O acesso tabela do sistema no est disponvel As tabelas do sistema, inclusive sqlite_master e outras com o prefixo sqlite_, no esto disponveis nas instrues SQL. O tempo de execuo inclui uma API de esquema que fornece uma forma orientada a objetos para acessar os dados do esquema. Para obter mais informaes, consulte o mtodo SQLConnection.loadSchema(). Funes de expresso regular (MATCH() e REGEX()) Essas funes no esto disponveis em instrues SQL.

A seguinte funcionalidade diferente em relao s muitas implementaes do SQLite e do Adobe AIR:

Parmetros de instruo indexados Em muitas implementaes, os parmetros de instruo indexados se baseiam em

um. No entanto, nos parmetros de instruo indexados do Adobe AIR se baseiam em zero (ou seja, o primeiro parmetro recebe o ndice 0, o segundo parmetro recebe o ndice 1 e assim por diante.
Definies da coluna INTEGER PRIMARY KEY Em muitas implementaes, apenas as colunas definidas exatamente

como INTEGER PRIMARY KEY so usadas como a coluna real de chave primria de uma tabela. Nessas implementaes, usar outro tipo de dados que normalmente sinnimo de INTEGER (como int) no faz com que a coluna seja usada como chave primria interna. Entretanto, no Adobe AIR, o tipo de dados int (e outros sinnimos de INTEGER) considerado exatamente equivalente a INTEGER. Portanto, uma coluna definida como int PRIMARY KEY usada como chave primria interna de uma tabela. Para obter mais informaes, consulte as sees CREATE TABLE e Afinidade de colunas.

Recursos SQL adicionais

Os seguintes tipos de afinidade de colunas no podem ser usados por padro no SQLite, mas so reconhecidos pelo Adobe AIR (perceba que, como todas as palavras-chaves do SQL, esses nomes de tipos de dados no fazem distino entre maisculas e minsculas):
Booleano correspondente classe Boolean. Date correspondente classe Date. int correspondente classe int (equivalente afinidade de coluna INTEGER). Number correspondente classe Number (equivalente afinidade de coluna REAL). Objeto correspondente classe Object ou a qualquer subclasse que possa ser serializada e desserializada usando AMF3. (Isso inclui a maioria das classes, inclusive classes personalizadas, mas exclui algumas, dentre elas objetos de exibio e objetos que incluem objetos de exibio como propriedades.) String correspondente classe String (equivalente afinidade de coluna TEXT). XML correspondente classe XML do ActionScript (E4X). XMLList correspondente classe XMLList do ActionScript (E4X).

Por padro, no h suporte aos valores literais no SQLite, embora haja no Adobe AIR:
true usado para representar o valor booleano literal true, para trabalhar com colunas BOOLEAN. false usado para representar o valor booleano literal false, para trabalhar com colunas BOOLEAN.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Suporte SQL em bancos de dados locais

1116

Suporte ao tipo de dados

Ao contrrio da maioria dos bancos de dados SQL, o mecanismo SQL do Adobe AIR no exige ou impe que essas colunas de tabela contenham valores de um determinado tipo. Na verdade, o tempo de execuo usa dois conceitos, classes de armazenamento e afinidade de coluna, para controlar tipos de dados. Esta seo descreve as classes de armazenamento e a afinidade de coluna, bem como a forma com que as diferenas no tipo de dados so resolvidas em vrias condies:

Classes de armazenamento na pgina 1116 Afinidade de coluna na pgina 1117 Tipos de dados e operadores de comparao na pgina 1119 Tipos de dados e operadores matemticos na pgina 1120 Tipos de dados e classificao na pgina 1120 Tipos de dados e agrupamento na pgina 1120 Tipos de dados e instrues SELECT compostas na pgina 1120

Classes de armazenamento
As classes de armazenamento representam os tipos de dados reais usados para armazenar valores em um banco de dados. As seguintes classes de armazenamento so usadas pelo banco de dados:
NULL O valor um valor NULL. INTEGER O valor um inteiro assinado. REAL O valor um nmero de ponto flutuante. TEXT O valor uma string de texto (limitada a 256 MB). BLOB O valor um BLOB (objeto binrio grande); em outras palavras, dados binrios brutos (limitados a 256 MB).

Todos os valores fornecidos ao banco de dados como literais incorporados em uma instruo SQL ou valores associados usando parmetros a uma instruo SQL preparada so atribudos a uma classe de armazenamento antes da execuo da instruo SQL. Os literais que fazem parte de uma instruo SQL so atribudos classe de armazenamento TEXT, caso estejam entre aspas simples ou duplas, INTEGER caso o literal seja especificado como um nmero sem aspas e casa decimal ou expoente, REAL caso o literal seja um nmero sem aspas com casa decimal ou expoente e NULL caso o valor seja NULL. Os literais com um BLOB da classe de armazenamento so especificados usando a notao X'ABCD'. Para obter mais informaes, consulte Valores literais em expresses. Valores fornecidos como parmetros usando a matriz associativa SQLStatement.parameters so atribudos classe de armazenamento que mais corresponda ao tipo de dados nativos associado. Por exemplo, os valores int so associados como uma classe de armazenamento INTEGER, os valores Number recebem a classe de armazenamento REAL, os valores String recebem a classe de armazenamento TEXT e os objetos ByteArray recebem a classe de armazenamento BLOB.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Suporte SQL em bancos de dados locais

1117

Afinidade de coluna
A afinidade de uma coluna o tipo recomendado para dados armazenados nessa coluna. Quando um valor armazenado em uma coluna (por meio de uma instruo INSERT ou UPDATE), o tempo de execuo tenta converter esse valor do tipo de dados na afinidade especificada. Por exemplo, caso um valor Date (uma ocorrncia de Date em ActionScript ou JavaScript) seja inserido em uma coluna cuja afinidade TEXT, o valor Date convertido na representao String (equivalente chamada do mtodo toString() do objeto) antes do armazenamento no banco de dados. Caso o valor no possa ser convertido na afinidade especificada, ocorre um erro e a operao no realizada. Quando um valor recuperado do banco de dados usando uma instruo SELECT, ele retornado como uma instncia da classe correspondente afinidade, independentemente de ser convertido de um tipo de dados diferente quando armazenado. Caso uma coluna aceite valores NULL, o valor ActionScript ou JavaScript null pode ser usado como um valor de parmetro para armazenar NULL na coluna. Quando um valor da classe de armazenamento NULL recuperado em uma instruo SELECT, ele sempre retornado como o valor de ActionScript ou JavaScript null, independentemente da afinidade da coluna. Caso uma coluna aceite valores NULL, sempre verifique valores recuperados da coluna para determinar se eles so null antes de tentar projetar os valores como um tipo que no possa ser nulo (como, por exemplo, Number ou Boolean). Cada coluna do banco de dados atribuda a uma das seguintes afinidades de tipo:

TEXT (ou String) NUMERIC INTEGER (ou int) REAL (ou Number) Booleano Date XML XMLLIST Objeto NONE
TEXT (ou String) Uma coluna com afinidade TEXT ou String armazena todos os dados que usam classes de armazenamento NULL, TEXT ou BLOB. Caso sejam inseridos dados numricos em uma coluna com afinidade TEXT, eles so convertidos em forma de texto antes de serem armazenados. NUMERIC Uma coluna com afinidade NUMERIC contm valores que usam classes de armazenamento NULL, REAL ou INTEGER. Quando dados de texto so inseridos em uma coluna NUMERIC, feita uma tentativa de convert-los em um inteiro ou nmero real antes de serem armazenados. Caso haja xito na converso, o valor armazenado usando a classe de armazenamento INTEGER ou REAL (por exemplo, um valor igual a '10.05' convertido na classe de armazenamento REAL antes de ser armazenado). Caso a converso no possa ser realizada, ocorre um erro. No feita nenhuma tentativa de converter um valor NULL. Um valor recuperado de uma coluna NUMERIC retornado como uma ocorrncia do tipo numrico mais especfico no qual o valor se encaixa. Em outras palavras, caso o valor seja um inteiro positivo ou 0, ele retornado como uma ocorrncia de unit. Caso seja um inteiro negativo, ele retornado como uma ocorrncia de int. Por fim, caso tenha um componente de ponto flutuante (no um inteiro), ele retornado como uma ocorrncia de Number.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Suporte SQL em bancos de dados locais

1118

INTEGER (ou int) Uma coluna que usa afinidade INTEGER se comporta da mesma forma que uma coluna com afinidade NUMERIC, exceto por uma coisa. Caso o valor a ser armazenado seja um valor real (como, por exemplo, uma ocorrncia de Number) sem nenhum componente de ponto flutuante ou caso o valor seja um valor de texto que possa ser convertido em um valor real sem nenhum componente de ponto flutuante, ele convertido em um inteiro e armazenado usando a classe de armazenamento INTEGER. Caso seja feita uma tentativa de armazenar um valor real com um componente de ponto flutuante, ocorre um erro. REAL (ou Number) Uma coluna com afinidade REAL ou NUMBER se comporta como uma coluna com afinidade NUMERIC, exceto pelo fato de forar valores inteiros na representao de ponto flutuante. Um valor em uma coluna REAL sempre retornado do banco de dados como uma ocorrncia de Number. Booleano Uma coluna com afinidade Boolean armazena valores true ou false. Uma coluna Boolean aceita um valor que uma ocorrncia de Boolean em ActionScript ou JavaScript. Caso o cdigo tente armazenar um valor String, String com comprimento maior que zero considerada verdadeira e uma String vazia, falsa. Caso o cdigo tente armazenar dados numricos, qualquer valor que no seja zero armazenado como true e 0, como false. Quando um valor Boolean recuperado usando uma instruo SELECT, ele retornado como uma ocorrncia de Boolean. Valores que no sejam NULL so armazenados usando a classe de armazenamento INTEGER (0 para false e 1 para true), sendo convertidos em objetos Boolean quando os dados so recuperados. Date Uma coluna com afinidade Date armazena valores de data e hora. Uma coluna Date projetada para aceitar valores que sejam ocorrncias de Date em ActionScript ou JavaScript. Caso seja feita uma tentativa de armazenar um valor String em uma coluna Date, o tempo de execuo tenta convert-lo em uma data do calendrio Juliano. Em caso de falha na converso, ocorre um erro. Caso o cdigo tente armazenar um valor de Number, int ou uint, no feita nenhuma tentativa de validar os dados, pressupondo que ele seja um valor de data do calendrio Juliano vlido. Um valor Date recuperado usando uma instruo SELECT convertido automaticamente em uma ocorrncia de Date. Como os valores de Date so armazenados como valores de data do calendrio Juliano usando a classe de armazenamento REAL, as operaes de classificao e comparao funcionam da forma como voc espera. XML ou XMLList Uma coluna que usa afinidade XML ou XMLList armazena estruturas XML. Quando o cdigo tenta armazenar dados em uma coluna XML usando um parmetro SQLStatement, o tempo de execuo tenta converter e validar o valor usando a funo XML() ou XMLList() em ActionScript. Caso o valor no possa ser convertido em um XML vlido, ocorre um erro. Caso a tentativa de armazenar os dados use um valor de texto SQL literal (por exemplo, INSERT INTO (col1) VALUES ('Invalid XML (no closing tag)'), o valor no analisado ou validado pressupe-se que esteja bemformado. Caso um valor invlido seja armazenado, quando recuperado, ele retornado como um objeto XML vazio. Dados XML e XMLList so armazenados usando a classe de armazenamento TEXT ou NULL. Objeto Uma coluna com afinidade Object armazena objetos complexos em ActionScript ou JavaScript, inclusive ocorrncias da classe Object, bem como ocorrncias das subclasses de Object como, por exemplo, ocorrncias de Array e at mesmo ocorrncias de classe personalizada. Os dados da coluna Object so serializados no formato AMF3 e armazenados usando a classe de armazenamento BLOB. Quando recuperado, um valor desserializado do AMF3 e retornado como uma instncia da classe como foi armazenado. Observe que algumas classes ActionScript, mais notadamente objetos de exibio, no podem ser desserializadas como ocorrncias do tipo de dados original. Antes de armazenar uma ocorrncia de classe personalizada, voc deve registrar um alias para a classe usando o mtodo

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Suporte SQL em bancos de dados locais

1119

flash.net.registerClassAlias() (ou em Flex, adicionando metadados [RemoteObject] declarao da classe). Alm disso, antes de recuperar esses dados, voc deve registrar o mesmo alias para a classe. Qualquer dado que no possa ser serializado corretamente porque a classe no pode ser desserializada inerentemente ou por conta de um alias de classe ausente ou no correspondente retornado como um objeto annimo (uma ocorrncia de classe Object) com propriedades e valores correspondentes ocorrncia original de acordo com o armazenamento. NONE Uma coluna com afinidade NONE no prefere nenhuma classe de armazenamento em detrimento de outra. Ela no faz nenhuma tentativa de converter dados antes de serem inseridos. Determinao da afinidade A afinidade de tipo de uma coluna determinada pelo tipo declarativo da coluna na instruo CREATE TABLE. Quando o tipo determinado, as seguintes regras (sem distino de caixa) se aplicam:

Caso o tipo de dados da coluna contenha uma das strings CHAR, CLOB, STRI, ou TEXT essa coluna ter afinidade
com TEXT/String. Observe que o tipo VARCHAR contm a string CHAR e, por isso, atribudo afinidade TEXT.

Caso o tipo de dados da coluna contenha a string BLOB ou caso nenhum tipo de dados seja especificado, a afinidade
da coluna NONE.

Caso o tipo de dados da coluna contenha a string XMLL, a coluna tem afinidade XMLList. Caso o tipo de dados seja a string XML, a coluna tem afinidade XML. Caso o tipo de dados contenha a string OBJE, a coluna tem afinidade Object. Caso o tipo de dados contenha a string BOOL, a coluna tem afinidade Boolean. Caso o tipo de dados contenha a string DATE, a coluna tem afinidade Date. Caso o tipo de dados contenha a string INT (inclusive UINT), ele atribudo afinidade INTEGER/int. Caso o tipo de dados da coluna contenha uma das strings REAL, NUMB, FLOA ou DOUBa coluna apresenta
afinidade REAL/Number.

Do contrrio, a afinidade NUMERIC. Caso uma tabela seja criada usando uma instruo CREATE TABLE t AS SELECT..., todas as colunas no tm
nenhum tipo de dados especificado, sendo todas atribudas afinidade NONE.

Tipos de dados e operadores de comparao

H suporte para estes operadores de comparao binria =, <, <=, >= e !=, alm de uma operao para testar a associao do conjunto, IN e operador de comparao ternrio BETWEEN. Para obter detalhes sobre esses operadores, consulte Operadores. Os resultados de uma comparao dependem das classes de armazenamento dos dois valores que esto sendo comparados. Durante a comparao entre duas regras, se aplicam as seguintes regras:

Um valor com classe de armazenamento NULL considerado inferior a qualquer outro valor (inclusive outro valor
com classe de armazenamento NULL).

Um valor INTEGER ou REAL inferior a qualquer valor TEXT ou BLOB. Quando INTEGER ou REAL
comparado com outro INTEGER ou REAL, realizada uma comparao numrica.

Um valor TEXT inferior a um valor BLOB. Quando dois valores TEXT so comparados, realizada uma
comparao binria.

Quando dois valores BLOB so comparados, o resultado sempre determinado usando uma comparao binria.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

Suporte SQL em bancos de dados locais

1120

O operador ternrio BETWEEN sempre reprojetado como a expresso binria equivalente. Por exemplo, a BETWEEN b AND c reprojetado como a >= b AND a <= c, mesmo que isso signifique a aplicao de afinidades diferentes a a em cada uma das comparaes necessrias avaliao da expresso. Expresses do tipo a IN (SELECT b ....) so tratadas pelas trs regras enumeradas anteriormente para as comparaes binrias, ou seja, de maneira semelhante a a = b. Por exemplo, caso b seja um valor de coluna e a seja uma expresso, a afinidade b aplicada a a antes da realizao de qualquer outra comparao. A expresso a IN (x, y, z) reprojetada como a = +x OR a = +y OR a = +z. Os valores direita do operador IN (os valores x, y e z nesse exemplo) so considerados expresses, mesmo que sejam valores de coluna. Caso o valor esquerda do operador IN seja uma coluna, usada a afinidade dessa coluna. Caso o valor seja uma expresso, no ocorre nenhuma converso. A forma como as comparaes so realizadas tambm pode ser afetada pelo uso de uma clusula COLLATE. Para obter mais informaes, consulte COLLATE.

Tipos de dados e operadores matemticos

Para cada um dos operadores matemticos para os quais h suporte, *, /, %, + e -, a afinidade numrica aplicada a cada operando antes da avaliao da expresso. Caso nenhum operando possa ser convertido na classe de armazenamento NUMERIC com xito, a expresso avaliada como NULL. Quando o operador de concatenao || usado, cada operando convertido na classe de armazenamento TEXT antes da avaliao da expresso. Caso nenhum operando possa ser convertido na classe de armazenamento TEXT, o resultado da expresso NULL. A impossibilidade de converso do valor pode acontecer em duas situaes: caso o valor do operando seja NULL ou caso ele seja um BLOB que contenha uma classe de armazenamento que no seja TEXT.

Tipos de dados e classificao

Quando os valores so classificados por uma clusula ORDER BY, os valores com uma classe de armazenamento NULL vm primeiro. Eles so seguidos dos valores INTEGER e REAL dispostos em ordem numrica, seguidos dos valores TEXT em ordem binria ou com base na intercalao especificada (BINARY ou NOCASE). Por fim, vm os valores BLOB na ordem binria. No ocorre nenhuma converso de classe antes da classificao.

Tipos de dados e agrupamento

Durante o agrupamento de valores com a clusula GROUP BY, valores com classes de armazenamento diferentes so consideradas distintas. Uma exceo a isso so os valores INTEGER e REAL, que so considerados iguais caso sejam numericamente equivalentes. Nenhuma afinidade aplicada a nenhum valor por conta de uma clusula GROUP BY.

Tipos de dados e instrues SELECT compostas

Os operadores SELECT compostos UNION, INTERSECT e EXCEPT realizam comparaes implcitas entre valores. Para que essas comparaes sejam realizadas, uma afinidade pode ser aplicada a cada valor. A mesma afinidade, caso haja alguma, aplicada a todos os valores que podem ser retornados em uma nica coluna do conjunto de resultados SELECT. A afinidade aplicada a afinidade da coluna retornada pela instruo SELECT do primeiro componente que apresenta um valor de coluna (e no outro tipo de expresso) nessa posio. Se, para uma determinada coluna SELECT composta, nenhuma das instrues SELECT do componente retornem um valor de coluna, nenhuma afinidade ser aplicada aos valores dessa coluna antes de serem comparados.

ltima atualizao em 29/3/2011

1121

Captulo 63: ID, argumentos e mensagens detalhadas de erro SQL

A classe SQLError representa vrios erros que podem ocorrer em meio ao trabalho com um banco de dados SQL local Adobe AIR. Em qualquer exceo, a ocorrncia SQLError tem uma propriedade detailsque contm uma mensagem de erro em ingls. Alm disso, cada mensagem de erro tem um identificador exclusivo associado disponvel na propriedade detailID do objeto SQLError. Com a propriedade detailID um aplicativo pode identificar a mensagem de erro details especfica. O aplicativo pode fornecer texto alternativo para o usurio final no idioma do local. Os valores de argumento da matriz detailArguments podem ser substitudos na posio apropriada da string da mensagem de erro. Isso til para aplicativos que precisam exibir a mensagem de erro de propriedade details relativa a um erro diretamente para os usurios finais em um local especfico. A tabela a seguir contm uma lista dos valores detailID e o texto da mensagem de erro em ingls associado. O texto do alocador de espao nas mensagens indica onde os valores detailArguments so substitudos pelo tempo de execuo. Essa lista pode ser usada como uma origem para localizar as mensagens de erro que podem ocorrer em operaes do banco de dados SQL.
SQLError detailID 1001 1102 1003 1004 Mensagem de erro detalhada em ingls e parmetros Conexo fechada. O banco de dados deve estar aberto para realizar a operao. %s [,|and %s] nome(s) de parmetro encontrado(s) na propriedade parameters, mas no no SQL especificado. Incompatibilidade na contagem de parmetros. Encontrados valor(es) %d no SQL especificado e %d definido(s) na propriedade parameters. Esperavam-se valores para %s [,|and %s]. No foi possvel ativar a compactao automtica. No foi possvel definir o valor pageSize. O objeto de esquema de nome %s e tipo %s no banco de dados %s no foi encontrado. O objeto do esquema de nome %s no banco de dados %s no foi encontrado. No foi encontrado nenhum objeto do esquema de tipo %s no banco de dados %s. No foi encontrado nenhum objeto do esquema no banco de dados %s. Estouro de pilha do analisador. Muitos argumentos na funo %s prximo a '%s': erro de sintaxe j existe outra tabela ou ndice com este nome: '%s' No h permisso para PRAGMA no SQL. No um diretrio gravvel Tipo de juno desconhecido ou incompatvel: No momento no h suporte a RIGHT e FULL OUTER JOINs. Uma juno NATURAL talvez no tenha uma clusula ON ou USING No possvel ter clusulas ON e USING na mesma juno No possvel unir usando a coluna %s - a coluna no est presente em ambas as tabelas. Apenas um nico resultado permitido para SELECT que parte de uma expresso Nenhuma tabela deste tipo: '[%s.]%s' Nenhuma tabela especificada. Muitas colunas no conjunto de resultados|muitas colunas em %s. %s Termo ORDER|GROUP BY fora do intervalo - deve estar entre 1 e %d Muitos termos na clusula ORDER BY. %s Termo ORDER BY fora do intervalo - deve estar entre 1 e %d. O termo ORDER BY %r no corresponde a nenhuma coluna do conjunto de resultados.

1005 1006 1007 1008 1009 1010 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

ID, argumentos e mensagens detalhadas de erro SQL

1122

2020 2021 2022 2023 2024 2025 2026 2027 2028 2030 2032 2033 2034 2035 2036 2037 2043 2044 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2058 2060 2061 2062 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2080 2081 2082 2083 2084 2085 2086 2087 2088

A clusula ORDER BY deve vir depois de %s e no antes. A clusula LIMIT deve vir depois de %s e no antes. SELECTs esquerda e direita de %s no tm o mesmo nmero de colunas de resultado. Uma clusula GROUP BY obrigatria antes de HAVING. No so permitidas funes agregadas na clusula GROUP BY. DISTINCT em agregao deve ser seguida de uma expresso. Muitos termos em SELECT composta. muitos termos na clusula ORDER|GROUP BY. O disparador temporrio talvez no tenha nome qualificado Disparador %s j existente. No possvel criar o disparador BEFORE|AFTER na exibio: '%s'. No possvel criar o disparador INSTEAD OF na tabela: '%s'. Nenhum disparador deste tipo: '%s'. No h suporte para disparadores recursivos (%s). Nenhuma coluna deste tipo:%s[.%s[.%s]] No h permisso para VACUUM do SQL. Tabela '%s': a funo de indexao retornou um plano invlido. Mximo de %d tabelas em uma juno. No possvel adicionar uma coluna PRIMARY KEY. No possvel adicionar uma coluna UNIQUE. No possvel adicionar uma coluna NOT NULL com o valor NULL padro. No possvel adicionar uma coluna com um padro que no seja constante. No possvel adicionar uma coluna a uma exibio. No h permisso para ANALYZE no SQL. Nome invlido: '%s' No h permisso para ATTACH do SQL. %s '%s' no pode fazer referncia a objetos do banco de dados '%s' Proibido o acesso a '[%s.]%s.%s' No autorizado. nenhuma exibio deste tipo: '[%s.]%s' O nome da tabela temporria deve ser no qualificado. Tabela %s j existente. J existe um ndice chamado: '%s' Nome da coluna duplicado: '%s' A tabela %s tem mais de uma chave primria. S h permisso para AUTOINCREMENT em INTEGER PRIMARY KEY. Nenhuma seqncia de intercalao deste tipo: '%s' No h permisso para parmetros em exibies. A exibio %s est definida de maneira circular. No possvel descartar a tabela '%s'. Use DROP VIEW para excluir a exibio %s Use DROP TABLE para excluir a tabela %s A chave externa em %s deve referenciar apenas uma coluna da tabela %s O nmero de colunas na chave externa no corresponde ao nmero de colunas na tabela referenciada. Coluna desconhecida %s na definio da chave externa. No possvel indexar a tabela %s No possvel indexar exibies. Clusulas ON CONFLICT em conflito especificadas. Nenhum ndice deste tipo: '%s'. No possvel ignorar ndice associado restrio UNIQUE ou PRIMARY KEY. No h permisso para BEGIN no SQL. No h permisso para COMMIT no SQL. No h permisso para ROLLBACK no SQL. No foi possvel abrir um arquivo de banco de dados temporrio para armazenar tabelas temporrias. No foi possvel identificar o objeto a ser reindexado. No possvel modificar a tabela %s.

ltima atualizao em 29/3/2011

GUIA DO DESENVOLVEDOR DO ACTIONSCRIPT 3.0

ID, argumentos e mensagens detalhadas de erro SQL

1123

2089 2090 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2108 2200 2201 2202 2203 2204 2205 2206 2207 2208 2209 2300 2301 2302 2303 2304 2305 2306 2307 2309 2400 2401 2402 2403 2404 2405 2406 2407 2408 2409 2501 2508 2510 2511

Mo possvel modificar %s por se tratar de uma exibio. O nmero da varivel deve estar entre ?0 e ?%d. Uso inadequado do agregado %s com suavizao. Nome da coluna ambguo: '[%s.[%s.]]%s' Nenhuma funo deste tipo: '%s' Nmero errado de argumentos para a funo %s. Subconsultas proibidas em restries CHECK. Parmetros proibidos em restries CHECK. A rvore de expresses muito grande (profundidade mxima %d). RAISE() talvez s possa ser usada em um programa disparador. A tabela '%s' tem %d colunas, mas foram fornecidos %d valores. O esquema do banco de dados est bloqueado: '%s' Instruo muito longa. No foi possvel excluir/modificar a seqncia de intercalao por causa de instrues ativas. Muitos bancos de dados anexados - mximo %d No possvel usar ATTACH no banco de dados dentro da transao. O banco de dados %s j est em uso. Os bancos de dados anexados devem usar a mesma codificao de texto do banco de dados principal. Sem memria. No foi possvel abrir um banco de dados. No possvel usar DETACH no banco de dados dentro da transao. No possvel desanexar um banco de dados: '%s' O banco de dados %s est bloqueado. No foi possvel obter um bloqueio de leitura no banco de dados. [column|columns] '%s'[,'%s'] no so [unique|is] no exclusivas. Esquema do banco de dados malformado. No h suporte para o formato de arquivo. Token no reconhecido: '%s' No foi possvel converter o valor de texto em valor numrico. No foi possvel converter valor da string em data No foi possvel o converter valor em ponto flutuante em inteiro sem perda de dados. No possvel reverter a transao instrues SQL em andamento No possvel confirmar a transao instrues SQL em andamento. Tabela do banco de dados bloqueada: '%s' Tabela somente leitura. String ou blob muito grande. No possvel abrir coluna indexada para gravao. No possvel abrir valor de tipo %s Nenhuma rowid deste tipo: %s Nome do objeto reservado para uso interno: '%s' No possvel alterar a exibio %s O valor padro da coluna %s no constante. No autorizado a usar a funo %s Uso inadequado da funo agregada %s Uso inadequado da agregao: '%s' Nenhum banco de dados deste tipo: '%s' A tabela %s no tem uma coluna chamada %s nenhum mdulo deste tipo: '%s' Nenhum ponto de recuperao deste tipo: '%s' No possvel reverter no h transaes ativas. No possvel confirmar no h transaes ativas.

ltima atualizao em 29/3/2011