Bestanden neerzetten in niet-toepassingssandboxen in HMTL Inhoud die niet van de toepassing afkomstig is, heeft geen toegang tot File-objecten die worden gemaakt wanneer bestanden naar een AIR-toepassing worden gesleept. Het is ook niet mogelijk een van deze File-objecten aan inhoud van de toepassing door te geven via een sandboxbridge. (De objecteigenschappen moeten worden benaderd tijdens het serialiseren.) U kunt echter wel bestanden in uw toepassing neerzetten door te luisteren naar de nativeDragDropgebeurtenissen van AIR voor het HTMLLoader-object. Als een gebruiker een bestand neerzet in een frame dat inhoud bevat die niet van de toepassing afkomstig is, wordt de neerzetgebeurtenis gewoonlijk niet van het onderliggende naar het bovenliggende item doorgevoerd. Omdat de gebeurtenissen die door de HTMLLoader (die de container is voor alle HTML-inhoud in een AIR-toepassing) worden verzonden geen deel uitmaken van de HTML-gebeurtenissenstroom, kunt u de neerzetgebeurtenis echter nog steeds ontvangen in inhoud van de toepassing. Om de gebeurtenis voor het neerzetten van een bestand te ontvangen, voegt het bovenliggende document een gebeurtenislistener aan het HTMLLoader-object toe met de verwijzing die is geleverd door window.htmlLoader: window.htmlLoader.addEventListener("nativeDragDrop",function(event){ var filelist = event.clipboard.getData(air.ClipboardFormats.FILE_LIST_FORMAT); air.trace(filelist[0].url); });

In het volgende voorbeeld laadt een bovenliggend document een onderliggende pagina in een externe sandbox (http://localhost/). Het bovenliggende document luistert naar de gebeurtenis nativeDragDrop van het HTMLLoaderobject en haalt hier de bestands-URL uit op.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 146 Slepen en neerzetten

<script language="javascript" type="text/javascript" src="AIRAliases.js"> <script language="javascript"> window.htmlLoader.addEventListener("nativeDragDrop",function(event){ var filelist = event.clipboard.getData(air.ClipboardFormats.FILE_LIST_FORMAT); air.trace(filelist[0].url); }); <iframe src="child.html" sandboxRoot="http://localhost/" documentRoot="app:/" frameBorder="0" width="100%" height="100%">

Het onderliggende document moet een geldig neerzetdoel zijn. Hiervoor moet de methode preventDefault() van het Event-object in handlers van de HTML-gebeurtenissen dragenter en dragover worden voorkomen, anders kan de neerzetgebeurtenis niet plaatsvinden. <script language="javascript" type="text/javascript"> function preventDefault(event){ event.preventDefault(); }

Zie “Programmeren in HTML en JavaScript” op pagina 221 voor meer informatie.

147

Hoofdstuk 16: kopiëren en plakken Gebruik de klassen in de klembord-API om informatie van en naar het systeemklembord te kopiëren. De volgende gegevensindelingen kunnen worden gebruikt om informatie van en naar een Adobe® AIR™-toepassing te kopiëren:

• Bitmaps • Bestanden • Tekst • Tekst met HTML-opmaak • RTF-gegevens • URL-tekenreeksen • Geserialiseerde objecten • Objectverwijzingen (alleen geldig binnen de brontoepassing)

Aanvullende online informatie over kopiëren en plakken Meer informatie over kopiëren en plakken vindt u in deze bronnen: Snelstarthandleidingen (Adobe AIR Developer Connection) • Ondersteuning voor slepen en neerzetten en voor kopiëren en plakken Language Reference • Clipboard

• ClipboardFormats • ClipboardTransferMode Meer informatie • Adobe AIR Developer Connection for Flash (zoek naar 'AIR copy and paste')

Basisbeginselen van kopiëren en plakken De kopiëren-en-plakken-API bevat de volgende klassen.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 148 kopiëren en plakken

Pakket

Klassen

flash.desktop

•

clipboard

•

ClipboardFormats

•

ClipboardTransferMode

Constanten voor gebruik met de kopiëren-en-plakken-API worden in de volgende klassen gedefinieerd:

•

ClipboardFormats

•

ClipboardTransferMode

De statische eigenschap Clipboard.generalClipboard vertegenwoordigt het klembord van het besturingssysteem. De klasse Clipboard biedt methoden voor het lezen en schrijven van gegevens van en naar klembordobjecten. U kunt ook nieuwe klembordobjecten creëren om gegevens over te brengen via de kopiëren-en-plakken-API. De HTML-omgeving biedt een alternatieve API voor kopiëren en plakken. Code die binnen de toepassingssandbox wordt uitgevoerd, kan een willekeurige van deze twee API's gebruiken maar alleen de HTML-API kan in niettoepassingsinhoud worden gebruikt. (Zie “HTML kopiëren en plakken” op pagina 149.) De klassen HTMLLoader en TextField passen standaardgedrag toe op de normale sneltoetsen voor kopiëren en plakken. Als u kopiëren en plakken in aangepaste componenten wilt gebruiken, kunt u rechtstreeks op deze toetsaanslagen wachten. U kunt ook native menuopdrachten met andere sneltoetsen creëren om onrechtstreeks op de toetsaanslagen te reageren. U kunt in één klembordobject meerdere voorstellingen van dezelfde informatie beschikbaar maken om het andere toepassingen makkelijker te maken de gegevens te begrijpen en te gebruiken. Een afbeelding kan bijvoorbeeld als grafische gegevens, een geserialiseerd bitmapobject en een bestand worden opgenomen. Het omzetten van gegevens naar een indeling kan worden uitgesteld zodat de indeling pas wordt gecreëerd nadat de gegevens in de desbetreffende indeling zijn gelezen. Opmerking: Er is geen garantie dat de gegevens die naar het klembord zijn geschreven, beschikbaar blijven nadat een AIR-toepassing is afgesloten.

Lezen van en schrijven naar het systeemklembord Als u de inhoud van het klembord van het besturingssysteem wilt lezen, roept u de methode getData() van het object Clipboard.generalClipboard op, waarbij u de naam opgeeft van de indeling die u wilt lezen: import flash.desktop.Clipboard; import flash.desktop.ClipboardFormats; if(Clipboard.generalClipboard.hasFormat(ClipboardFormats.TEXT_FORMAT)){ var text:String = Clipboard.generalClipboard.getData(ClipboardFormats.TEXT_FORMAT); }

Als u naar het klembord wilt schrijven, voegt u de gegevens in een of meer indelingen toe aan het object Clipboard.generalClipboard. Bestaande gegevens in dezelfde indeling worden automatisch overschreven. Het is echter aan te raden het systeemklembord te wissen voordat u nieuwe gegevens naar het klembord schrijft om te zorgen dat ook niet-verwante gegevens in andere indelingen worden gewist.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 149 kopiëren en plakken

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);

Opmerking: Alleen code die in de toepassingssandbox wordt uitgevoerd, heeft rechtstreeks toegang tot het systeemklembord. Bij niet-toepassings HTML-inhoud hebt u alleen toegang tot het klembord via de eigenschap clipboardData van een gebeurtenisobject dat is verzonden door een van de HTML kopiëren-en-plakkengebeurtenissen.

HTML kopiëren en plakken De HTML-omgeving heeft een eigen set van gebeurtenissen en standaardgedrag voor kopiëren en plakken. Alleen code die in de toepassingssandbox wordt uitgevoerd, heeft rechtstreeks toegang tot het systeemklembord via het AIRobject Clipboard.generalClipboard. JavaScript-code in een niet-toepassingssandbox heeft toegang tot het klembord via het gebeurtenisobject dat is verzonden als reactie op een van de kopiëren-en-plakken-gebeurtenissen die zijn verzonden door een element in een HTML-document. Kopiëren-en-plakken-gebeurtenissen zijn onder andere: copy, cut en paste. Het object dat voor deze gebeurtenissen is verzonden, biedt toegang tot het klembord via de eigenschap clipboardData.

Standaardgedrag Als reactie op de kopieeropdracht worden de geselecteerde items standaard door AIR gekopieerd. Deze opdracht kan via een sneltoets of een snelmenu worden gegenereerd. In bewerkbare zones wordt tekst als reactie op de knipopdracht door AIR geknipt, of als reactie op de plakopdracht door AIR geplakt op de cursorpositie of de geselecteerde tekst. Als u een ander gedrag wenst, kan uw gebeurtenishandler de methode preventDefault() van het verzonden gebeurtenisobject oproepen.

Eigenschap clipboardData van gebeurtenisobject gebruiken Met de eigenschap clipboardData van het gebeurtenisobject dat als reactie op een van de kopieer- of plakgebeurtenissen is verzonden, kunt u klembordgegevens lezen en schrijven. Als u naar het klembord wilt schrijven bij het werken met een kopieer- of knipgebeurtenis, gebruikt u de methode setData() van het object clipboardData, waarbij u de te kopiëren gegevens en het MIME-type opgeeft: function customCopy(event){ event.clipboardData.setData("text/plain", "A copied string."); }

Als u toegang wilt tot de gegevens die worden geplakt, gebruikt u de methode getData() van het object clipboardData, waarbij u het MIME-type van de gegevensindeling opgeeft. De beschikbare indelingen worden weergegeven door de eigenschap types. function customPaste(event){ var pastedData = event.clipboardData("text/plain"); }

De methode getData() en de eigenschap types zijn alleen toegankelijk in het gebeurtenisobject dat is verzonden door de gebeurtenis paste.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 150 kopiëren en plakken

Het volgende voorbeeld geeft aan hoe u het standaardgedrag bij kopiëren en plakken in een HTML-pagina kunt wijzigen. De gebeurtenishandler copy maakt de gekopieerde tekst cursief en kopieert deze als HTML-tekst naar het klembord. De gebeurtenishandler cut kopieert de geselecteerde gegevens naar het klembord en verwijdert deze uit het document. De gebeurtenishandler paste voegt de inhoud van het klembord als HTML in en maakt de ingevoegde tekst vet. <script language="javascript" type="text/javascript"> function onCopy(event){ var selection = window.getSelection(); event.clipboardData.setData("text/html","" + selection + ""); event.preventDefault(); } function onCut(event){ var selection = window.getSelection(); event.clipboardData.setData("text/html","" + selection + ""); 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(); }

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.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 151 kopiëren en plakken

Menuopdrachten en toetsaanslagen voor kopiëren en plakken De kopiëren-en-plakken-functionaliteit wordt doorgaans geactiveerd door menuopdrachten en sneltoetsen. In OS X maakt het besturingssysteem automatisch een bewerkingsmenu met de opdrachten Kopiëren en Plakken. U moet echter listeners aan deze menuopdrachten toevoegen om uw eigen functies eraan te koppelen. In Windows kunt u een native bewerkingsmenu toevoegen aan elk venster dat de systeeminterface gebruikt. (U kunt ook niet-native menu's maken met Flex en ActionScript of - bij HTML-inhoud - DHTML gebruiken, maar dat valt niet binnen het kader van deze handleiding.) De kopiëren-en-plakken-functionaliteit wordt doorgaans geactiveerd door menuopdrachten en sneltoetsen. In OS X maakt het besturingssysteem automatisch een bewerkingsmenu met de opdrachten Kopiëren en Plakken. U moet echter listeners aan deze menuopdrachten toevoegen om uw eigen functies eraan te koppelen. In Windows kunt u een native bewerkingsmenu toevoegen aan elk venster dat de systeeminterface gebruikt. (U kunt ook niet-native menu's maken met ActionScript of - bij HTML-inhoud - DHTML gebruiken, maar dat valt niet binnen het kader van deze handleiding.) Als u de opdrachten Kopiëren en Plakken wilt laten activeren door sneltoetsen, kunt u toetsencombinaties aan de overeenkomstige opdrachten toewijzen in een native toepassing of venstermenu, of rechtstreeks op de toetsaanslagen wachten.

Kopieer- of plakbewerking starten met een menuopdracht Als u een kopieer- of plakbewerking wilt laten activeren door een menuopdracht, moet u listeners voor de gebeurtenis select toevoegen aan de menu-items die uw handlerfuncties oproepen. Wanneer uw handlerfunctie wordt opgeroepen, kunt u het object waarvan moet worden gekopieerd of waarnaar moet worden geplakt, vinden met behulp van de eigenschap focus van de fase. Vervolgens kunt u de overeenkomstige methode voor het object met focus (of een algemene alternatieve methode als geen enkel object focus heeft) oproepen om de logica voor kopiëren, knippen of plakken uit te voeren. De volgende gebeurtenishandler copy controleert bijvoorbeeld of het object met focus het juiste type is (in dit geval de klasse Scrap) en roept vervolgens de methode doCopy() voor het object op. function copyCommand(event:Event):void{ if(NativeApplication.nativeApplication.activeWindow.stage.focus is Scrap){ Scrap(NativeApplication.nativeApplication.activeWindow.stage.focus).doCopy(); } else { NativeApplication.nativeApplication.copy(); } }

Als copyCommand() in het voorbeeld de klasse van het object met focus niet herkent, wordt de NativeApplicationmethode copy() opgeroepen. De NativeApplication-methode copy() verzendt een interne opdracht Kopiëren naar het object met focus. De interne opdracht wordt alleen door de objecten TextArea en HTMLLoader herkend. Er zijn soortgelijke opdrachten beschikbaar voor Knippen, Plakken, Alles selecteren en (alleen voor TextArea) Wissen, Ongedaan maken en Opnieuw. Opmerking: Er is geen API beschikbaar om op deze interne opdrachten te reageren in een aangepaste component. U moet de klasse TextArea of HTMLLoader uitbreiden of een van deze objecten opnemen in uw aangepaste component. Als u een TextArea- of HTMLLoader-object opneemt, moet uw component de focus zo beheren dat het TextArea- of HTMLLoader-object altijd focus behoudt wanneer de component zelf focus heeft.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 152 kopiëren en plakken

Bij HTML-inhoud kunt u het standaardgedrag voor kopiëren en plakken activeren met behulp van de NativeApplication-bewerkingsopdrachten. In het volgende voorbeeld wordt een bewerkingsmenu voor een bewerkbaar HTML-document gemaakt: In het vorige voorbeeld wordt het toepassingsmenu voor Mac OS X vervangen. U kunt echter ook het standaard bewerkingsmenu gebruiken door de bestaande menuopdrachten te zoeken en er gebeurtenislisteners aan toe te voegen. Als u een snelmenu gebruikt om een kopieer- of plakopdracht op te roepen, kunt u de eigenschap contextMenuOwner gebruiken van het ContextMenuEvent-object dat wordt verzonden bij het openen van het menu of het selecteren van een menuopdracht, om te bepalen welk object de juiste bestemming van de kopieer- of plakopdracht is.

Standaard menuopdrachten zoeken in Mac OS X U kunt het standaard bewerkingsmenu en de specifieke kopieer-, knip- en plakopdrachten in het toepassingsmenu voor Mac OS X zoeken door de menuhiërarchie te doorzoeken met behulp van de eigenschap label van de NativeMenuItem-objecten. Met de volgende functie neemt u bijvoorbeeld een naam en zoekt u de opdracht met het overeenkomstige label in het menu: private function findItemByName(menu:NativeMenu, name:String, recurse:Boolean = false):NativeMenuItem{ var searchItem:NativeMenuItem = null; for each (var item:NativeMenuItem in menu.items){ if(item.label == name){ searchItem = item; break; } if((item.submenu != null) && recurse){ searchItem = findItemByName(item.submenu, name, recurse); } if(searchItem != null){ break; } } return searchItem; }

U kunt de parameter recurse instellen op true als u submenu's in de zoekactie wilt opnemen, of op false als u alleen de opdrachten van hetzelfde niveau wilt zoeken.

Kopieer- of plakopdracht starten met een toetsaanslag Als uw toepassing native venster- of toepassingsmenu's voor kopiëren en plakken gebruikt, kunt u toetsencombinaties aan de menuopdrachten toewijzen die als sneltoetsen reageren. U kunt echter ook zelf naar de overeenkomstige toetsaanslagen luisteren, zoals in het volgende voorbeeld wordt geïllustreerd:

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 153 kopiëren en plakken

private function init():void{ stage.addEventListener(KeyboardEvent.KEY_DOWN, keyListener); } private function keyListener(event:KeyboardEvent):void{ if(event.ctrlKey){ event.preventDefault(); switch(String.fromCharCode(event.charCode)){ case "c": NativeApplication.nativeApplication.copy(); break; case "x": NativeApplication.nativeApplication.cut(); break; case "v": NativeApplication.nativeApplication.paste(); break; case "a": NativeApplication.nativeApplication.selectAll(); break; case "z": NativeApplication.nativeApplication.undo(); break; case "y": NativeApplication.nativeApplication.redo(); break; } } }

Bij HTML-inhoud worden standaard de sneltoetsen voor kopieer- en plakopdrachten toegepast. Het is niet mogelijk om met een toetsgebeurtenislistener alle toetsaanslagen te detecteren die doorgaans voor kopiëren en plakken worden gebruikt. Als u het standaardgedrag wilt wijzigen, wordt u aangeraden naar de gebeurtenissen copy en paste zelf te luisteren.

Klembordgegevensindelingen Klembordindelingen beschreven de gegevens die in een klembordobject zijn geplaatst. AIR zet de standaard gegevensindelingen automatisch om van ActionScript-gegevenstypen in systeemklembordindelingen, en omgekeerd. Bovendien kunnen toepassingsobjecten worden overgebracht binnen en tussen AIR-toepassingen met behulp van toepassingsspecifieke indelingen. Een klembordobject kan dezelfde informatie in meerdere indelingen bevatten. Een klembordobject dat een sprite representeert, kan bijvoorbeeld een referentie-indeling bevatten voor gebruik in dezelfde toepassing, een geserialiseerde indeling voor gebruik door een andere AIR-toepassing, een bitmapindeling voor gebruik door een grafische editor en een bestandenlijstindeling, mogelijk met uitgestelde rendering om een PNG-bestand te coderen, voor het kopiëren of slepen van een representatie van de sprite naar het bestandssysteem.

Standaard gegevensindelingen De constanten die de standaard indelingsnamen definiëren, staan in de klasse ClipboardFormats:

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 154 kopiëren en plakken

Constante

Beschrijving

TEXT_FORMAT

Gegevens met tekstindeling worden omgezet in de ActionScript-klasse String, en omgekeerd.

HTML_FORMAT

Tekst met HTML-markeringen.

RICH_TEXT_FORMAT

RTF-gegevens worden omgezet in de ActionScript-klasse ByteArray, en omgekeerd. De RTF-markeringen worden op geen enkele manier geïnterpreteerd of omgezet.

BITMAP_FORMAT

Gegevens met bitmapindeling worden omgezet in de ActionScript-klasse BitmapData, en omgekeerd.

FILE_LIST_FORMAT

Gegevens met bestandenlijstindeling worden omgezet in een array van ActionScript File-objecten, en omgekeerd.

URL_FORMAT

Gegevens met URL-indeling worden omgezet in de ActionScript-klasse String, en omgekeerd.

Opmerking: Flash-tekstbesturingselementen en -componenten bieden momenteel nog geen ondersteuning voor RTFgegevens. Als u RTF-gegevens in een besturingselement wilt plakken, zet u eerst de RTF-markering om in een HTMLmarkering (of tekst zonder opmaak). Op dezelfde manier moet u om RTF-gegevens naar het klembord te kopiëren, een tekst- of HTML-tekenreeks omzetten in een ByteArray-object met de juiste RTF-markeringen. Flash biedt geen hulpprogrammaklasse voor de conversie van RTF-gegevens naar een andere indeling. Bij het kopiëren en plakken van gegevens als reactie op een copy-, cut- of paste- gebeurtenis in HTML-inhoud, moet u MIME-typen gebruiken in plaats van ClipboardFormat-tekenreeksen. De volgende MIME-typen zijn geldig voor gegevens: MIME-type

Beschrijving

Tekst

"text/plain"

URL

"text/uri-list"

Bitmap

"image/x-vnd.adobe.air.bitmap"

Bestandenlijst

"application/x-vnd.adobe.air.file-list"

Opmerking: RTF-gegevens zijn niet beschikbaar via de eigenschap clipboardData van het gebeurtenisobject dat is verzonden als reactie op een paste-gebeurtenis in HTML-inhoud.

Aangepaste gegevensindelingen U kunt toepassingsspecifieke, aangepaste indelingen gebruiken om objecten als verwijzingen of geserialiseerde kopieën over te brengen. Verwijzingen zijn alleen geldig binnen dezelfde AIR-toepassing. Geserialiseerde objecten kunnen tussen Adobe AIR-toepassingen worden overgebracht maar kunnen alleen worden gebruikt met objecten die geldig blijven nadat ze zijn geserialiseerd en gedeserialiseerd. Objecten kunnen doorgaans worden geserialiseerd als hun eigenschappen van een eenvoudig type zijn of als de objecten serialiseerbaar zijn. Als u een geserialiseerd object aan een klembordobject wilt toevoegen, stelt u de serialiseerbare parameter in op true wanneer u de methode Clipboard.setData() oproept. De naam van de indeling kan die van een standaardindeling zijn, of een willekeurige tekenreeks die door uw toepassing wordt gedefinieerd.

Overdrachtsmodi Wanneer u een object in een aangepaste gegevensindeling naar het klembord schrijft, kunnen de objectgegevens als verwijzing of als geserialiseerde kopie van het oorspronkelijke object worden gelezen van het klembord. AIR definieert vier overdrachtsmodi die bepalen of objecten als verwijzingen of als geserialiseerde kopieën worden overgebracht:

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 155 kopiëren en plakken

Overdrachtsmodus

Beschrijving

ClipboardTransferModes.ORIGINAL_ONLY

Er wordt alleen een verwijzing geretourneerd. Als er geen verwijzing beschikbaar is, wordt een nulwaarde geretourneerd.

ClipboardTransferModes.ORIGINAL_PREFERRED

Als er een verwijzing beschikbaar is, wordt deze geretourneerd. Als dat niet het geval is, wordt een geserialiseerde kopie geretourneerd.

ClipboardTransferModes.CLONE_ONLY

Er wordt alleen een geserialiseerde kopie geretourneerd. Als er geen geserialiseerde kopie beschikbaar is, wordt een nulwaarde geretourneerd.

ClipboardTransferModes.CLONE_PREFERRED

Als er een geserialiseerde kopie beschikbaar is, wordt deze geretourneerd. Als dat niet het geval is, wordt een verwijzing geretourneerd.

Aangepaste gegevensindelingen lezen en schrijven Wanneer u een object naar het klembord schrijft, kunt u een willekeurige tekenreeks gebruiken die niet begint met het gereserveerde voorvoegsel air: voor de indelingsparameter. Gebruik dezelfde tekenreeks als indeling voor het lezen van het object. De volgende voorbeelden illustreren hoe u objecten leest van en schrijft naar het klembord: public function createClipboardObject(object:Object):Clipboard{ var transfer:Clipboard = new Clipboard(); transfer.setData("object", object, true); }

Als u een geserialiseerd object uit het klembordobject wilt halen (na een neerzet- of plakbewerking), gebruikt u dezelfde indelingsnaam en de overdrachtsmodus cloneOnly of clonePreferred. var transfer:Object = clipboard.getData("object", ClipboardTransferMode.CLONE_ONLY);

Er wordt altijd een verwijzing toegevoegd aan het klembordobject. Als u de verwijzing - en niet de geserialiseerde kopie - uit het klembordobject wilt halen (na een neerzet- of plakbewerking), gebruikt u de overdrachtsmodus originalOnly of originalPreferred: var transferredObject:Object = clipboard.getData("object", ClipboardTransferMode.ORIGINAL_ONLY);

Verwijzingen zijn alleen geldig als het klembordobject afkomstig is uit de actuele AIR-toepassing. Gebruik de overdrachtsmodus originalPreferred om toegang te verkrijgen tot de verwijzing als deze beschikbaar is, of tot de geserialiseerde kopie als de verwijzing niet beschikbaar is.

Uitgestelde rendering Als het maken van een gegevensindeling de processor zwaar belast, kunt u uitgestelde rendering toepassen door een functie in te stellen die de gegevens op aanvraag levert. Deze functie wordt alleen opgeroepen als een ontvanger van de neerzet- of plakbewerking om gegevens in de uitgestelde indeling vraagt. De renderfunctie wordt met de methode setDataHandler() aan een klembordobject toegevoegd. De functie moet de gegevens in de juiste indeling retourneren. Als u bijvoorbeeld setDataHandler(ClipboardFormat.TEXT_FORMAT, writeText) hebt opgeroepen, moet de functie writeText() een tekenreeks retourneren. Als een gegevensindeling van hetzelfde type met de methode setData() aan een klembordobject wordt toegevoegd, hebben die gegevens voorrang op de uitgestelde versie (de renderfunctie wordt nooit opgeroepen). Als dezelfde klembordgegevens een tweede keer worden benaderd, wordt de renderfunctie mogelijk (opnieuw) opgeroepen. Opmerking: In Mac OS X treedt geen uitgestelde rendering op bij het gebruik van de standaard AIR-klembordindelingen. De renderfunctie wordt onmiddellijk opgeroepen.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 156 kopiëren en plakken

Tekst plakken met behulp van uitgestelde rendering Het volgende voorbeeld illustreert hoe u uitgestelde rendering toepast. Wanneer in dit voorbeeld op de knop Copy wordt geklikt, wist de toepassing het systeemklembord om te zorgen dat er geen gegevens van vorige klembordbewerkingen meer aanwezig zijn. Vervolgens wordt de functie renderData() op het klembord geplaatst met de klembordmethode setDataHandler(). Wanneer op de knop Paste wordt geklikt, haalt de toepassing de tekst op uit het klembord en wordt de doeltekst ingevoegd. Aangezien de tekstgegevensindeling op het klembord is ingesteld met een functie en niet met een tekenreeks, roept het klembord de functie renderData() op. De functie renderData() retourneert de tekst in de brontekst, waarna deze aan de doeltekst wordt toegewezen. Let op: als u brontekst bewerkt voordat u op de knop Paste klikt, worden de bewerkingen opgenomen in de geplakte tekst, zelfs als de bewerking plaatsvindt nadat u op de knop Copy hebt geklikt. De renderfunctie kopieert de brontekst namelijk pas nadat op de knop Paste is geklikt. (Wanneer u uitgestelde rendering in een echte toepassing gebruikt, kunt u het best de brongegevens opslaan of vergrendelen om dit probleem te voorkomen.) package { import import import import import

flash.desktop.Clipboard; flash.desktop.ClipboardFormats; flash.display.Sprite; flash.text.TextField; flash.events.MouseEvent;

public class DeferredRenderingExample extends Sprite { var sourceTxt:TextField; var destinationTxt:TextField; public function DeferredRenderingExample():void { sourceTxt = createTextField(10, 10, 210, 380, false); addChild(sourceTxt); sourceTxt.text = "Neque porro quisquam est qui dolorem " + "ipsum quia dolor sit amet, consectetur, adipisci velit." destinationTxt = createTextField(330, 10, 210, 380, false); addChild(destinationTxt); var copyBtn:TextField = createTextField(230, 50, 90, 20, true); copyBtn.text = "Copy"; addChild(copyBtn); copyBtn.addEventListener(MouseEvent.CLICK, onCopy); var pasteBtn:TextField = createTextField(230, 80, 90, 20, true); pasteBtn.text = "Paste"; addChild(pasteBtn); pasteBtn.addEventListener(MouseEvent.CLICK, onPaste); } private function createTextField(x:Number, y:Number, width:Number, height:Number, isBtn:Boolean = false):TextField { var newTxt:TextField = new TextField(); newTxt.x = x; newTxt.y = y;

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 157 kopiëren en plakken

newTxt.height = height; newTxt.width = width; newTxt.border = true; newTxt.background = true; if (isBtn) { newTxt.backgroundColor = 0xDDDDDDEE; newTxt.selectable = false; } else { newTxt.multiline = true; newTxt.wordWrap = true; newTxt.backgroundColor = 0xEEEEEEEE; } return newTxt; } public function onCopy(event:MouseEvent):void { Clipboard.generalClipboard.clear(); Clipboard.generalClipboard.setDataHandler(ClipboardFormats.TEXT_FORMAT, renderData); } public function onPaste(event:MouseEvent):void { destinationTxt.text = Clipboard.generalClipboard.getData(ClipboardFormats.TEXT_FORMAT) as String; } public function renderData():String { trace("Rendering data"); var sourceStr:String = sourceTxt.text; if (sourceTxt.selectionEndIndex > sourceTxt.selectionBeginIndex) { // something is selected return sourceStr.substring(sourceTxt.selectionBeginIndex, sourceTxt.selectionEndIndex); } else { return sourceStr; } } } }

158

Hoofdstuk 17: Werken met bytearrays Met de klasse ByteArray kunt u een binaire gegevensstroom, die in feite een array met bytes is, lezen en schrijven. Met deze klasse krijgt u toegang tot gegevens op het meest elementaire niveau. Omdat computergegevens bestaan uit bytes, of groepen van 8 bits, kunt u door het lezen van gegevens in bytes toegang krijgen tot gegevens waarvoor geen klassen en toegangsmethoden bestaan. Met de klasse ByteArray kunt u elke gegevensstroom, van een bitmap tot een gegevensstroom die via het netwerk wordt verzonden, parseren op byteniveau. Met de methode writeObject() kunt u een object in geserialiseerde AMF-indeling (Action Message Format) schrijven naar een bytearray, terwijl u met de methode readObject() een geserialiseerd object uit een bytearray kunt inlezen in een variabele van het oorspronkelijke gegevenstype. U kunt alle objecten serialiseren, behalve weergaveobjecten (objecten die op de weergavelijst kunnen worden geplaatst). U kunt geserialiseerde objecten ook opnieuw aan aangepaste klasse-instanties toewijzen als de aangepaste klasse beschikbaar is voor de runtime. Nadat een object naar AMF is geconverteerd, kunt u het verzenden via een netwerkverbinding of opslaan in een bestand. In de Adobe® AIR™-voorbeeldtoepassing die hier wordt beschreven, wordt een ZIP-bestand gelezen als voorbeeld van het verwerken van een bytestroom; de lijst met bestanden in het ZIP-bestand wordt uitgepakt en naar de desktop geschreven.

Bytearrays lezen en schrijven De klasse ByteArray is een onderdeel van het pakket flash.utils. Als u een ByteArray-object wilt maken in ActionScript 3.0, importeert u de klasse ByteArray en roept u de constructor op, zoals weergegeven in het volgende voorbeeld: import flash.utils.ByteArray; var stream:ByteArray = new ByteArray();

ByteArray, methoden Elke zinvolle gegevensstroom wordt geordend in een indeling waarin u de gewenste informatie kunt zoeken. Een record in een eenvoudig werknemersbestand kan bijvoorbeeld een id-nummer, een naam, een adres, een telefoonnummer enzovoort bevatten. Een MP3-geluidsbestand bevat een ID3-code met de titel, de auteur, het album, de publicatiedatum en het genre van het bestand dat wordt gedownload. Door deze indeling weet u in welke volgorde de gegevens in de gegevensstroom zijn opgenomen. U kunt de bytestroom daardoor op een intelligente manier lezen. De klasse ByteArray bevat diverse methoden waarmee u een gegevensstroom eenvoudiger kunt lezen of schrijven. Enkele van deze methoden zijn: readBytes() en writeBytes(), readInt() en writeInt(), readFloat() en writeFloat(), readObject() en writeObject(), en readUTFBytes() en writeUTFBytes(). Met deze methoden kunt u gegevens uit een gegevensstroom inlezen in variabelen van bepaalde gegevenstypen en vanuit bepaalde gegevenstypen rechtstreeks naar de binaire gegevensstroom schrijven. Met de volgende code wordt bijvoorbeeld een eenvoudige array met tekenreeksen en getallen met een drijvende komma gelezen en wordt elk element naar een bytearray geschreven. Door de indeling van de array kan de code de juiste ByteArray-methoden (writeUTFBytes() en writeFloat()) oproepen voor het schrijven van de gegevens. Door het herhaalde gegevenspatroon wordt het mogelijk de array in een lus te lezen.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 159 Werken met bytearrays

// 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

De eigenschap position In de eigenschap position wordt de huidige positie opgeslagen van de pointer die de index van de bytearray bepaalt tijdens het lezen of schrijven. De initiële waarde van de eigenschap position is 0 (nul), zoals wordt weergegeven in de volgende code: var bytes:ByteArray = new ByteArray(); trace("bytes.position is initially: " + bytes.position); // 0

Wanneer u een bytearray leest of er naar schrijft, wordt de eigenschap position bijgewerkt met de methode die u gebruikt, zodat wordt verwezen naar de locatie die volgt op de laatste byte die is gelezen of geschreven. Met de volgende code wordt bijvoorbeeld een tekenreeks naar een bytearray geschreven en verwijst de eigenschap position daarna naar de byte die volgt op de tekenreeks in de bytearray: 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

Bij een leesbewerking wordt de eigenschap position verhoogd met het aantal gelezen bytes. 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!

U kunt de eigenschap position instellen op een specifieke locatie in de bytearray om vanaf dat punt te lezen of te schrijven.

De eigenschappen bytesAvailable en length De eigenschappen length en bytesAvailable geven aan hoe lang een bytearray is en hoeveel bytes er aanwezig zijn vanaf de huidige positie tot het einde. In het volgende voorbeeld ziet u hoe u deze eigenschappen kunt gebruiken. In het voorbeeld wordt een tekenreeks met tekst naar de bytearray geschreven en worden vervolgens alle bytes in de array een voor een gelezen totdat het teken ‘a’ of het einde (bytesAvailable <= 0) wordt aangetroffen.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 160 Werken met bytearrays

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 }

De eigenschap endian Getallen die uit meerdere bytes bestaan (getallen die in meer dan 1 byte geheugen worden opgeslagen), kunnen op verschillende manieren op computers worden opgeslagen. Een geheel getal kan bijvoorbeeld 4 bytes (32 bits) geheugen in beslag nemen. Op sommige computers wordt de meest significante byte van het getal eerst opgeslagen, op het laagste geheugenadres, en op andere wordt de minst significante byte eerst opgeslagen. Dit kenmerk van een computer (de bytevolgorde) wordt big endian (meest significante byte eerst) of little endian (minst significante byte eerst) genoemd. Het getal 0x31323334 wordt bijvoorbeeld als volgt opgeslagen bij de bytevolgorde big endian en little endian, waarbij a0 het laagste geheugenadres van de 4 bytes is en a3 het hoogste: Big Endian

Big Endian

Big Endian

Big Endian

a0

a1

a2

a3

31

32

33

34

Little Endian

Little Endian

Little Endian

Little Endian

a0

a1

a2

a3

34

33

32

31

Met de eigenschap endian van de klasse ByteArray kunt u deze bytevolgorde aangeven voor getallen die uit meerdere bytes bestaan. De geaccepteerde waarden voor deze eigenschap zijn "bigEndian" en "littleEndian" en in de klasse Endian zijn de constanten BIG_ENDIAN en LITTLE_ENDIAN gedefinieerd om deze tekenreeksen in te stellen voor de eigenschap endian.

De methoden compress() en uncompress() Met de methode compress() kunt u een bytearray comprimeren volgens een compressiealgoritme die u opgeeft als een parameter. Met de methode uncompress() kunt u een bytearray decomprimeren volgens een compressiealgoritme. Nadat u compress() en uncompress() hebt opgeroepen, wordt de lengte van de bytearray ingesteld op de nieuwe lengte en wordt de eigenschap position ingesteld op het einde. In de klasse CompressionAlgorithm zijn constanten gedefinieerd waarmee u de compressiealgoritme kunt opgeven. In AIR worden zowel de Deflate- als de ZLIB-algoritme ondersteund. De Deflate-compressiealgoritme wordt gebruikt in diverse compressie-indelingen, zoals ZLIB, GZIP en enkele ZIP-implementaties. De gecomprimeerde ZLIBgegevensindeling wordt beschreven in http://www.ietf.org/rfc/rfc1950.txt en de Deflate-compressiealgoritme wordt beschreven in http://www.ietf.org/rfc/rfc1951.txt. In het volgende voorbeeld wordt een bytearray met de naam bytes gecomprimeerd met de Deflate-algoritme:

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 161 Werken met bytearrays

bytes.compress(CompressionAlgorithm.DEFLATE);

In het volgende voorbeeld wordt een gecomprimeerde bytearray gedecomprimeerd met de Deflate-algoritme: bytes.uncompress(CompressionAlgorithm.DEFLATE);

Objecten lezen en schrijven Met de methoden readObject() en writeObject() leest u een object in een bytearray en schrijft u een object naar een bytearray, gecodeerd in geserialiseerde AMF-indeling (Action Message Format). AMF is een berichtenprotocol dat door Adobe is gemaakt en wordt gebruikt door diverse ActionScript 3.0-klassen, zoals Netstream, NetConnection, NetStream, LocalConnection en Shared Objects. Een typemarkering van één byte bevat de beschrijving van het type van de gecodeerde gegevens die volgen. AMF gebruikt de volgende 13 gegevenstypen: 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

De gecodeerde gegevens volgen op de typemarkering, tenzij de markering één mogelijke waarde bevat, zoals null of true of false, zodat verder niets wordt gecodeerd. Er zijn twee versies van AMF: AMF0 en AMF3. AMF 0 ondersteunt het verzenden van complexe objecten via verwijzingen en staat eindpunten toe voor het herstellen van objectrelaties. AMF 3 is verbeterd ten opzichte van AMF 0 doordat naast objectverwijzingen ook objectkenmerken en tekenreeksen kunnen worden verzonden en nieuwe gegevenstypen worden ondersteund die in ActionScript 3.0 zijn geïntroduceerd. De eigenschap ByteArray.objectEcoding geeft aan welke versie van AMF wordt gebruikt om de objectgegevens te coderen. In de klasse flash.net.ObjectEncoding zijn constanten gedefinieerd waarmee de AMF-versie wordt opgegeven: ObjectEncoding.AMF0 en ObjectEncoding.AMF3. import flash.filesystem.*; import flash.utils.ByteArray; // Label component must be in Library import fl.controls.Label;

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 162 Werken met bytearrays

var bytes:ByteArray = new ByteArray(); var myLabel:Label = new Label(); myLabel.move(150, 150); myLabel.width = 200; addChild(myLabel); var myXML:XML = <menuName>burger <price>3.95 <menuName>fries <price>1.45 // Write XML object to ByteArray bytes.writeObject(myXML); bytes.position = 0;//reset position to beginning bytes.compress(CompressionAlgorithm.DEFLATE);// compress ByteArray outFile("order", bytes); myLabel.text = "Wrote order file to desktop!"; 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(); }

Met de methode readObject() wordt een object in geserialiseerde AMF-indeling ingelezen vanuit een bytearray en opgeslagen in een object van het opgegeven type. In het volgende voorbeeld wordt het bestand order vanaf de desktop ingelezen in een bytearray (inBytes). Vervolgens wordt het bestand gedecomprimeerd en wordt readObject() opgeroepen om het op te slaan in het XML-object orderXML. In het voorbeeld wordt elk knooppunt in een lusconstructie for each() toegevoegd aan een tekstgebied voor weergave. In het voorbeeld wordt ook de waarde van de eigenschap objectEncoding weergegeven, evenals een header voor de inhoud van het bestand order. import flash.filesystem.*; import flash.utils.ByteArray; // TextArea component must be in Library import fl.controls.TextArea;

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 163 Werken met bytearrays

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(); //for each node in orderXML for each(var child:XML in orderXML) { // append child node to text area myTxt.text += child + "\n"; } // 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(); }

Voorbeeld van een bytearray: een ZIP-bestand lezen In dit voorbeeld ziet u hoe een eenvoudig ZIP-bestand wordt gelezen dat verschillende typen bestanden bevat. Hiervoor worden relevante gegevens uit de metagegevens van elk bestand opgehaald, waarbij elk bestand in een bytearray wordt gedecomprimeerd en naar de desktop wordt geschreven. De algemene structuur van een ZIP-bestand is gebaseerd op de specificatie van PKWARE Inc., die u kunt vinden op http://www.pkware.com/documents/casestudies/APPNOTE.TXT. Eerst staan er een bestandsheader en bestandsgegevens voor het eerste bestand in het ZIP-bestand, gevolgd door een combinatie van een bestandsheader en bestandsgegevens voor elk ander bestand. (De structuur van de bestandsheader wordt later beschreven.) Daarna bevat het ZIP-bestand eventueel een record met een gegevensdescriptor (gewoonlijk wanneer het ZIP-bestand in het geheugen is gemaakt in plaats van opgeslagen op een schijf). Hierna volgen diverse optionele elementen: decoderingsheader van archief, extra gegevensrecord voor archief, centrale mapstructuur, Zip64-einde van centrale maprecord, Zip64-einde van centrale maplocator en het einde van de centrale maprecord. De code in dit voorbeeld is alleen geschreven om ZIP-bestanden te parseren die geen mappen bevatten en er worden geen records met een gegevensdescriptor verwacht. Alle informatie na de laatste bestandsgegevens wordt genegeerd. De bestandsheader voor elk bestand heeft de volgende indeling:

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 164 Werken met bytearrays

handtekening van bestandsheader

4 bytes

vereiste versie

2 bytes

algemene bitvlag

2 bytes

compressiemethode

2 bytes (8=DEFLATE; 0=UNCOMPRESSED)

tijd van laatste bestandswijziging

2 bytes

datum van laatste bestandswijziging

2 bytes

crc-32

4 bytes

gecomprimeerde grootte

4 bytes

ongecomprimeerde grootte

4 bytes

lengte van bestandsnaam

2 bytes

lengte van extra veld

2 bytes

bestandsnaam

variabele

extra veld

variabele

Na de bestandsheader volgen de werkelijke bestandsgegevens die gecomprimeerd of niet kunnen zijn, afhankelijk van de vlag voor de compressiemethode. De vlag is 0 (nul) als de bestandsgegevens niet zijn gecomprimeerd, 8 als de gegevens zijn gecomprimeerd met de Deflate-algoritme of een andere waarde voor andere compressiealgoritmen. De gebruikersinterface voor dit voorbeeld bestaat uit een label en een tekstgebied (taFiles). De toepassing schrijft de volgende informatie naar het tekstgebied voor elk bestand dat in het ZIP-bestand wordt aangetroffen: bestandsnaam, gecomprimeerde grootte en niet-gecomprimeerde grootte. Aan het begin van het programma worden de volgende taken uitgevoerd:

• De vereiste klassen worden geïmporteerd. import flash.filesystem.*; import flash.utils.ByteArray; import flash.events.Event;

• De gebruikersinterface wordt gedefinieerd. 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);

• De bytearray bytes wordt gedefinieerd. var bytes:ByteArray = new ByteArray();

• Er worden variabelen gedefinieerd voor het opslaan van metagegevens uit de bestandsheader.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 165 Werken met bytearrays

// 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;

• De objecten File (zfile) en FileStream (zStream) worden gedefinieerd voor het ZIP-bestand en de locatie wordt opgegeven van het ZIP-bestand waaruit de bestanden worden opgehaald: een bestand met de naam “HelloAIR.zip” in de desktopmap. // File variables for accessing .zip file var zfile:File = File.desktopDirectory.resolvePath("HelloAIR.zip"); var zStream:FileStream = new FileStream();

Het programma begint met het openen van het ZIP-bestand in de leesmodus. zStream.open(zfile, FileMode.READ);

Vervolgens wordt de eigenschap endian van bytes op LITTLE_ENDIAN ingesteld om aan te geven dat de minst significante byte eerst wordt aangegeven in de bytevolgorde van numerieke velden. bytes.endian = Endian.LITTLE_ENDIAN;

Vervolgens wordt met de instructie while() een lus gestart die wordt uitgevoerd tot de huidige positie in de bestandsstroom groter is dan of gelijk is aan de grootte van het bestand. while (zStream.position < zfile.size) {

Met de eerste instructie in de lus worden de eerste 30 bytes van de bestandsstroom ingelezen in de bytearray bytes. De eerste 30 bytes bevatten het gedeelte van de eerste bestandsheader dat een vaste grootte heeft. // read fixed metadata portion of local file header zStream.readBytes(bytes, 0, 30);

Vervolgens wordt een geheel getal (signature) gelezen uit de eerste bytes van de header die uit 30 bytes bestaat. In de definitie van de ZIP-indeling is opgegeven dat de handtekening voor elke bestandsheader de hexadecimale waarde 0x04034b50 heeft; als de handtekening anders is, betekent dit dat het einde van het bestandsgedeelte van het ZIPbestand is bereikt en dat er geen bestanden meer zijn om uit te pakken. In dat geval wordt de while-lus onmiddellijk beëindigd en wordt niet gewacht tot het einde van de bytearray is bereikt. bytes.position = 0; signature = bytes.readInt(); // if no longer reading data files, quit if (signature != 0x04034b50) { break; }

In het volgende deel van de code wordt de headerbyte op positie 8 gelezen en wordt de waarde opgeslagen in de variabele compMethod. Deze byte bevat een waarde die aangeeft met welke compressiemethode dit bestand is gecomprimeerd. Er zijn diverse compressiemethoden toegestaan, maar in de praktijk gebruiken bijna alle ZIPbestanden de Deflate-compressiealgoritme. Als het huidige bestand is gecomprimeerd met Deflate-compressie, is compMethod 8; als het bestand niet is gecomprimeerd, is compMethod 0.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 166 Werken met bytearrays

bytes.position = 8; compMethod = bytes.readByte();

// store compression method (8 == Deflate)

Na de eerste 30 bytes volgt een gedeelte van de header met een variabele lengte dat de bestandsnaam en eventueel een extra veld bevat. In de variabele offset is de grootte van dit gedeelte opgeslagen. De grootte wordt berekend door de lengte van de bestandsnaam en de lengte van het extra veld op te tellen. Deze waarden worden ingelezen uit de header op positie 26 en 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

Vervolgens wordt uit het gedeelte van de bestandsheader met variabele lengte het aantal bytes ingelezen dat is opgeslagen in de variabele offset. // read variable length bytes between fixed-length header and compressed file data zStream.readBytes(bytes, 30, offset);

De bestandsnaam wordt ingelezen vanuit het gedeelte van de header met variabele lengte en samen met de gecomprimeerde en niet-gecomprimeerde (oorspronkelijke) grootte van het bestand weergegeven in het tekstgebied. 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');

In het voorbeeld wordt de rest van het bestand vanuit de bestandsstroom ingelezen in bytes voor de lengte die is opgegeven door de gecomprimeerde grootte, waarbij de bestandsheader in de eerste 30 bytes wordt overschreven. De gecomprimeerde grootte is nauwkeurig, zelfs als het bestand niet is gecomprimeerd, omdat de gecomprimeerde grootte in dat geval gelijk is aan de niet-gecomprimeerde grootte van het bestand. // read compressed file to offset 0 of bytes; for uncompressed files // the compressed and uncompressed size is the same zStream.readBytes(bytes, 0, compSize);

Vervolgens wordt het gecomprimeerde bestand gedecomprimeerd en wordt de functie outfile() opgeroepen om het naar de uitvoerstroom te schrijven. De bestandsnaam en de bytearray die de bestandsgegevens bevat, worden doorgegeven aan outfile(). if (compMethod == 8) // if file is compressed, uncompress { bytes.uncompress(CompressionAlgorithm.DEFLATE); } outFile(fileName, bytes); // call outFile() to write out the file

De accolade-sluiten geeft het einde van de while-lus en van de toepassingscode aan, maar niet van de methode outFile(). De while-lus wordt opnieuw gestart en de volgende bytes in het ZIP-bestand worden verwerkt: er wordt een ander bestand uitgepakt of de verwerking van het ZIP-bestand wordt beëindigd als het laatste bestand is verwerkt. } // end of while loop

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 167 Werken met bytearrays

Met de functie outfile() wordt in de schrijfmodus op de desktop een uitvoerbestand geopend dat de naam krijgt die is opgegeven met de parameterfilename. Vervolgens wordt het gegevensbestand vanuit de parameter data naar de uitvoerstroom (outStream) geschreven en wordt het bestand gesloten. 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(); }

168

Hoofdstuk 18: Werken met lokale SQLdatabases Adobe AIR biedt de mogelijkheid om lokale SQL-databases te maken en te gebruiken. De runtime bevat een SQLdatabase-engine met ondersteuning voor vele standaardfuncties van SQL via het open-source databasesysteem SQLite. U kunt een lokale SQL-database gebruiken om lokale, niet-vluchtige gegevens op te slaan, bijvoorbeeld toepassingsgegevens, gebruikersinstellingen voor toepassingen, documenten of een willekeurig ander gegevenstype dat uw toepassing lokaal moet opslaan.

Aanvullende online informatie over lokale SQLdatabases In deze bronnen vindt u meer informatie over het werken met lokale SQL-databases: Snelstarthandleidingen (Adobe AIR Developer Connection) Language Reference • SQLCollationType

• SQLColumnNameStyle • SQLColumnSchema • SQLConnection • SQLError • SQLErrorEvent • SQLErrorOperation • SQLEvent • SQLIndexSchema • SQLMode • SQLResult • SQLSchema • SQLSchemaResult • SQLStatement • SQLTableSchema • SQLTransactionLockType • SQLTriggerSchema • SQLUpdateEvent • SQLViewSchema

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 169 Werken met lokale SQL-databases

Adobe Developer Connection - Artikels en voorbeelden • Adobe AIR Developer Connection for Flash (zoek naar ‘AIR SQL’)

Informatie over lokale SQL-databases Adobe AIR bevat een op SQL gebaseerde engine voor relationele databases die binnen de runtime wordt uitgevoerd. De gegevens worden lokaal opgeslagen in databasebestanden op de computer waarop de AIR-toepassing wordt uitgevoerd (bijvoorbeeld de vaste schijf van de computer). Aangezien de database lokaal wordt uitgevoerd en de gegevensbestanden lokaal worden opgeslagen, kan een database altijd door een AIR-toepassing worden gebruikt, ongeacht of een netwerkverbinding aanwezig is. Dit betekent dat de lokale SQL-database-engine van de runtime een handige manier is om niet-vluchtige, lokale toepassingsgegevens op te slaan, met name als u ervaring hebt met SQLen relationele databases.

Toepassingen voor lokale SQL-databases De AIR-functies voor lokale SQL-databases kunnen worden gebruikt voor willekeurige toepassingen waarbij toepassingsgegevens moeten worden opgeslagen op de lokale computer van de gebruiker. Adobe AIR biedt verschillende manieren om gegevens lokaal op te slaan, waarbij elke manier andere voordelen heeft. Hieronder ziet u een aantal mogelijke toepassingen voor een lokale SQL-database in uw AIR-toepassing:

• Voor een op gegevens gebaseerde toepassing (bijvoorbeeld een adresboek) kunt u een database gebruiken om de hoofdtoepassingsgegevens op te slaan.

• Voor een op documenten gebaseerde toepassing (waarbij gebruikers documenten creëren om ze op te slaan en mogelijk te delen) kan elk document als een databasebestand worden opgeslagen op een door de gebruiker opgegeven locatie. (Let op: aangezien een willekeurige AIR-toepassing het databasebestand kan openen, wordt u aangeraden codering te gebruiken voor mogelijk vertrouwelijke documenten.)

• Voor een toepassing met netwerkverbindingen kunt u een database gebruiken om toepassingsgegevens op te slaan in een lokale cache, of om gegevens tijdelijk op te slaan wanneer er geen netwerkverbinding beschikbaar is. U kunt desgewenst een procedure creëren om de lokale database te synchroniseren met de netwerklocatie voor gegevensopslag.

• Voor alle toepassingen kunt u een database gebruiken om de toepassingsinstellingen van individuele gebruikers op te slaan, bijvoorbeeld gebruikersopties of toepassingsinformatie zoals venstergrootte en -positie.

Informatie over AIR-databases en databasebestanden Een individuele, lokale SQL-database van Adobe AIR wordt als één bestand opgeslagen in het bestandssysteem van de computer. De runtime bevat de SQL-database-engine die het creëren en indelen van databasebestanden, en het bewerken en ophalen van gegevens in een databasebestand beheert. De runtime geeft niet aan hoe of waar de databasegegevens worden opgeslagen in het bestandssysteem - elke database bestaat uit één bestand. U geeft de locatie voor het databasebestand in het bestandssysteem op. Eén AIR-toepassing kan een of meer databases (met andere woorden aparte databasebestanden) benaderen. Aangezien de runtime elke database als één bestand opslaat in het bestandssysteem, kunt u de locatie van uw database afstemmen op het ontwerp van uw toepassing en de toegangsbeperkingen van het besturingssysteem. Iedere gebruiker kan een apart databasebestand voor zijn/haar specifieke gegevens hebben, of u kunt één databasebestand voor alle gebruikers van de toepassing op één computer plaatsen zodat de gegevens kunnen worden gedeeld. Aangezien de gegevens zich lokaal op één computer bevinden, worden de gegevens niet automatisch gedeeld met gebruikers op andere computers. De lokale SQL-database-engine biedt geen mogelijkheid om SQL-instructies uit te voeren in een externe of servergebaseerde database.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 170 Werken met lokale SQL-databases

Informatie over relationele databases Een relationele database is een mechanisme voor het opslaan (en ophalen) van gegevens op een computer. De gegevens zijn verdeeld in tabellen: rijen geven records of items weer, en kolommen (worden ook soms “velden” genoemd) verdelen elke record in individuele waarden. Een adresboektoepassing kan bijvoorbeeld een tabel met de naam “vrienden” bevatten. Elke rij van de tabel is dan één vriend die in de database is opgeslagen. De kolommen van de tabel bevatten gegevens zoals voornaam, achternaam, geboortedatum enzovoort. Voor iedere vriendrij van de tabel slaat de database een aparte waarde voor elke kolom op. Relationele databases zijn ontworpen voor de opslag van complexe gegevens, waarbij een item is gekoppeld of gerelateerd aan items van een ander type. In een relationele database worden gegevens met een één-op-vele-relatie (waarbij één record kan zijn gekoppeld aan meerdere records van een ander type) doorgaans verdeeld over verschillende tabellen. Als u bijvoorbeeld uw adresboektoepassing wilt gebruiken om voor iedere vriend meerdere telefoonnummers op te slaan, is dat een één-op-vele-relatie. De tabel “vrienden” bevat in dat geval alle persoonlijke gegevens van iedere vriend. Een andere tabel, “telefoonnummers”, kan dan alle telefoonnummers van alle vrienden bevatten. In de database worden niet alleen de gegevens van vrienden en telefoonnummers opgeslagen. Elke tabel heeft ook een gegevensitem nodig om de relatie tussen de twee tabellen bij te houden, met andere woorden om individuele vriendrecords te koppelen aan de overeenkomstige telefoonnummers. Dit gegevensitem wordt een primaire sleutel genoemd, een unieke identificator die elke tabelrij verschillend maakt van alle overige rijen uit die tabel. De primaire sleutel kan een “natuurlijke sleutel” zijn, waarbij de sleutel een van de gegevensitems is die elke record uit een tabel op een natuurlijke manier uniek maken. Als u in de tabel “vrienden” bijvoorbeeld weet dat al uw vrienden een andere geboortedatum hebben, kunt u de kolom voor de geboortedatum instellen als primaire sleutel (een natuurlijke sleutel) voor de tabel “vrienden”. Als er geen natuurlijke sleutel is, maakt u een aparte kolom voor de primaire sleutel, zoals “id_vriend”, dit is een kunstmatige waarde die door de toepassing wordt gebruikt om de rijen van elkaar te onderscheiden. Met behulp van een primaire sleutel kunt u relaties tussen meerdere tabellen definiëren. De tabel “vrienden” kan bijvoorbeeld een kolom met de naam “id_vriend” hebben, die voor elke rij (iedere vriend) een uniek nummer bevat. De gerelateerde tabel “telefoonnummers” kan in twee kolommen worden verdeeld, één met de “id_vriend” van de vriend die het desbetreffende telefoonnummer heeft, en één met het daadwerkelijke telefoonnummer. Op die manier kunnen alle telefoonnummers, ongeacht het aantal telefoonnummers per vriend, worden opgeslagen in de tabel “telefoonnummers” en via de primaire sleutel “id_vriend” worden gekoppeld aan de overeenkomstige vriend. Wanneer de primaire sleutel van een tabel wordt gebruikt in een gerelateerde tabel om de relatie tussen de records aan te geven, wordt de waarde in de gerelateerde tabel een externe sleutel genoemd. In tegenstelling tot vele databases biedt de lokale database-engine van AIR niet de mogelijkheid om beperkingen voor externe sleutels in te stellen. Deze beperkingen controleren automatisch of een ingevoegde of bijgewerkte externe-sleutelwaarde overeenkomt met een rij in de tabel met de primaire sleutel. Relaties op basis van externe sleutels vormen echter een belangrijk onderdeel van de structuur van een relationele database, en u wordt aangeraden externe sleutels te gebruiken wanneer u relaties tussen de tabellen van uw database definieert.

Informatie over SQL SQL (Structured Query Language) wordt bij relationele databases gebruikt om gegevens te bewerken en te zoeken. SQL is een beschrijvende en geen proceduretaal. Een SQL-instructie beschrijft de gegevensset die u zoekt maar geeft de computer geen instructies over hoe de gegevens moeten worden gezocht. De database-engine bepaalt hoe de gegevens worden gezocht.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 171 Werken met lokale SQL-databases

De taal SQL is gestandaardiseerd door het ANSI (American National Standards Institute). De lokale SQL-database van Adobe AIR ondersteunt het grootste deel van de standaard SQL-92. Zie de bijlage "SQL support in local databases" (SQL-ondersteuning in lokale databases) in ActionScript 3.0 Language and Components Reference voor een specifieke beschrijving van de SQL-onderdelen die worden ondersteund in Adobe AIR.

Informatie over klassen van SQL-databases Als u met lokale SQL-databases wilt werken in ActionScript 3.0, moet u instanties van deze klassen uit het pakket flash.data gebruiken: Klasse

Beschrijving

flash.data.SQLConnection

Biedt de mogelijkheid om databases (databasebestanden) te creëren en te openen, evenals methoden voor het uitvoeren van bewerkingen op databaseniveau en het besturen van databasetransacties.

flash.data.SQLStatement

Vertegenwoordigt één SQL-instructie (één query of opdracht) die op een database wordt uitgevoerd, inclusief het definiëren van de instructietekst en het instellen van parameterwaarden.

flash.data.SQLResult

Biedt een manier om informatie over of het resultaat van de uitvoering van een instructie op te vragen, zoals de resulterende rijen na een SELECT-instructie, het aantal rijen dat wordt beïnvloed door een UPDATE- of DELETE-instructie enzovoort.

Als u schema-informatie met een beschrijving van de structuur van een database wilt verkrijgen, moet u deze klassen uit het pakket flash.data gebruiken: Klasse

Beschrijving

flash.data.SQLSchemaResult

Fungeert als container voor databaseschemaresultaten die worden gegenereerd door het oproepen van de methode SQLConnection.loadSchema().

flash.data.SQLTableSchema

Biedt informatie over één tabel van een database.

flash.data.SQLViewSchema

Biedt informatie over één weergave van een database.

flash.data.SQLIndexSchema

Biedt informatie over één kolom van een tabel of één weergave van een database.

flash.data.SQLTriggerSchema Biedt informatie over één trigger van een database.

Andere klassen uit het pakket flash.data bieden constanten die worden gebruikt met de klassen SQLConnection en SQLColumnSchema: Klasse

Beschrijving

flash.data.SQLMode

Definieert een set van constanten voor de mogelijke waarden van de parameter openMode van de methoden SQLConnection.open() en SQLConnection.openAsync().

flash.data.SQLColumnNameStyle

Definieert een set van constanten voor de mogelijke waarden van de eigenschap SQLConnection.columnNameStyle.

flash.data.SQLTransactionLockType

flash.data.SQLCollationType

Definieert een set van constanten voor de mogelijke waarden van de optieparameter van de methode SQLConnection.begin(). Definieert een set van constanten voor de mogelijke waarden van de eigenschap SQLColumnSchema.defaultCollationType en de parameter defaultCollationType van de constructor SQLColumnSchema().

Daarnaast vertegenwoordigen de volgende klassen uit het pakket flash.events de gebeurtenissen (en ondersteunende constanten) die u gebruikt:

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 172 Werken met lokale SQL-databases

Klasse

Beschrijving

flash.data.SQLEvent

Definieert de gebeurtenissen die door een SQLConnection- of SQLStatement-instantie worden verzonden wanneer een of meer bewerkingen uit de instantie met succes zijn uitgevoerd. Voor elke bewerking is een gekoppelde gebeurtenistypeconstante gedefinieerd in de klasse SQLEvent.

flash.data.SQLErrorEvent

Definieert de gebeurtenis die door een SQLConnection- of SQLStatement-instantie wordt verzonden wanneer een of meer bewerkingen uit de instantie een fout opleveren.

flash.data.SQLUpdateEvent

Definieert de gebeurtenis die door een SQLConnection-instantie wordt verzonden wanneer tabelgegevens in een van de gekoppelde databases veranderen door de uitvoering van de SQL-instructie INSERT, UPDATE of DELETE.

Ten slotte bieden de volgende klassen uit het pakket flash.errors informatie over bewerkingsfouten in de database: Klasse

Beschrijving

flash.data.SQLError

Biedt informatie over een bewerkingsfout in de database, zoals de bewerking die is mislukt en de oorzaak van de fout.

flash.data.SQLErrorEvent

Definieert een set van constanten voor de mogelijke waarden van de eigenschap operation van de klasse SQLError, die de databasebewerking aangeeft waarbij de fout is opgetreden.

Informatie over synchrone en asynchrone uitvoeringsmodi Wanneer u code schrijft om met een lokale SQL-database te werken, selecteert u een van de twee beschikbare uitvoeringsmodi voor bewerkingen in de database: synchroon of asynchroon. De codevoorbeelden tonen op algemene manier hoe u elke bewerking op beide manieren kunt uitvoeren zodat u het voorbeeld kunt gebruiken dat het meest geschikt is voor uw behoeften. In asynchrone uitvoeringsmodus geeft u de runtime een instructie, waarna de runtime een gebeurtenis verzendt wanneer de desbetreffende bewerking is voltooid of mislukt. Eerst geeft u de database-engine de opdracht een bewerking uit te voeren. De database-engine werkt op de achtergrond terwijl de toepassing verderwerkt. Wanneer ten slotte de bewerking is voltooid (of mislukt), verzendt de database-engine een gebeurtenis. Uw code, geactiveerd door de gebeurtenis, voert indien nodig daarop volgende bewerkingen uit. Deze procedure heeft een groot voordeel: de runtime voert de databasebewerkingen op de achtergrond uit terwijl de hoofdtoepassingscode verder wordt uitgevoerd. Als de databasebewerking lange tijd duurt, blijft de toepassing verderwerken. En het belangrijkste is dat interactie met de gebruiker mogelijk blijft omdat het scherm niet bevriest. Het nadeel is dat asynchrone bewerkingscode soms complexer is om te schrijven. Dit is doorgaans het geval wanneer meerdere afhankelijke bewerkingen moeten worden verdeeld tussen verschillende gebeurtenislistenermethoden. Conceptueel is het eenvoudiger om bewerkingen als één sequentie van stappen (een set van synchrone bewerkingen) te beschrijven in plaats van als een set van bewerkingen verdeeld in meerdere gebeurtenislistenermethoden. Naast asynchrone databasebewerkingen is met Adobe AIR ook het synchroon uitvoeren van databasebewerkingen mogelijk. In de synchrone uitvoeringsmodus worden de bewerkingen niet op de achtergrond uitgevoerd. In plaats daarvan worden ze uitgevoerd volgens dezelfde uitvoeringssequentie als alle andere toepassingscode. U geeft de databaseengine de opdracht een bewerking uit te voeren. Vervolgens wordt de code op dat punt onderbroken terwijl de database-engine zijn werk doet. Nadat de bewerking is voltooid, gaat de uitvoering verder vanaf de volgende regel van uw code.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 173 Werken met lokale SQL-databases

U bepaalt op SQLConnection-niveau welke uitvoeringsmodus (synchroon of asynchroon) voor bewerkingen wordt gebruikt. Het is niet mogelijk om via één enkele databaseverbinding bepaalde bewerkingen of instructies synchroon en andere asynchroon uit te voeren. U bepaalt welke uitvoeringsmodus (synchroon of asynchroon) voor een SQLConnection wordt gebruikt door een SQLConnection-methode op te roepen om de database te openen. Als u SQLConnection.open() oproept, werkt de verbinding in synchrone uitvoeringsmodus. Roept u SQLConnection.openAsync() op, dan werkt de verbinding in asynchrone uitvoeringsmodus. Nadat een SQLConnection-instantie met een database is verbonden met behulp van open() of openAsync(), wordt deze in synchrone of asynchrone uitvoeringsmodus vergrendeld, tenzij u de verbinding met de database sluit en weer opent. Elke uitvoeringsmodus heeft specifieke voordelen. De meeste aspecten van beide modi zijn identiek. Er zijn echter bepaalde verschillen waarmee u het best rekening houdt terwijl u in een bepaalde modus werkt. Zie “Synchrone en asynchrone databasebewerkingen gebruiken” op pagina 194 voor meer informatie over deze onderwerpen en suggesties voor het werken in elke modus.

Databases creëren en wijzigen Voordat uw toepassing gegevens kan toevoegen of ophalen, moet er een database met gedefinieerde tabellen aanwezig zijn en moet de database toegankelijk zijn voor uw toepassing. Hieronder wordt beschreven hoe u een database creëert en de gegevensstructuur binnen een database definieert. Deze taken zijn weliswaar minder vaak nodig dan het invoegen en ophalen van gegevens maar zijn toch noodzakelijk voor de meeste toepassingen.

Database creëren Voordat u een databasebestand kunt creëren, moet u een SQLConnection-instantie creëren. Roep de methode open() op om de instantie in synchrone uitvoeringsmodus te openen, of roep de methode openAsync() op om de instantie in asynchrone uitvoeringsmodus te openen. De methoden open() en openAsync() worden gebruikt om een verbinding met een database te openen. Als u een File-instantie gebruikt die verwijst naar een niet-bestaande bestandslocatie voor de parameter reference (de eerste parameter), creëert de methode open() of openAsync() een databasebestand op die bestandslocatie en wordt een verbinding met de zojuist gecreëerde database geopend. De naam van het databasebestand mag altijd een willekeurige geldige bestandsnaam met een willekeurige bestandsextensie zijn, ongeacht de methode die u oproept (open() of openAsync()). Als u de methode open() of openAsync() oproept met de instelling null voor de parameterreference, wordt een nieuwe database in het geheugen gecreëerd in plaats van een databasebestand op de vaste schijf. De volgende code illustreert het creëren van een databasebestand (een nieuwe database) via de asynchrone uitvoeringsmodus. In dit geval wordt het databasebestand met de bestandsnaam “DBSample.db” opgeslagen in de opslagdirectory van de toepassing:

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 174 Werken met lokale SQL-databases

import flash.data.SQLConnection; import flash.events.SQLErrorEvent; import flash.events.SQLEvent; import 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"); 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); }

Als u bewerkingen synchroon wilt uitvoeren, roept u de methode open() op wanneer u een databaseverbinding opent met de SQLConnection-instantie. In het volgende voorbeeld ziet u hoe u een SQLConnection-instantie creëert en opent die de bewerkingen synchroon uitvoert: import flash.data.SQLConnection; import flash.events.SQLErrorEvent; import flash.events.SQLEvent; import flash.filesystem.File; var conn:SQLConnection = new SQLConnection(); var dbFile:File = File.applicationStorageDirectory.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); }

Databasetabellen creëren Als u een tabel in een database wilt creëren, moet u een SQL-instructie op de desbetreffende database uitvoeren via dezelfde procedure als voor het uitvoeren van een SQL-instructie zoals SELECT, INSERT enzovoort. U creëert een tabel met behulp van de instructie CREATE TABLE, waarbij u kolomdefinities en beperkingen voor de nieuwe tabel opgeeft. Zie “Werken met SQL-instructies” op pagina 177 voor meer informatie over het uitvoeren van SQL-instructies. In het volgende voorbeeld ziet u hoe u een tabel met de naam “employees” in een bestaand databasebestand creëert via de asynchrone uitvoeringsmodus. Let op: deze code gaat ervan uit dat een SQLConnection-instantie met de naam conn al is gedefinieerd en met een database is verbonden.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 175 Werken met lokale SQL-databases

import flash.data.SQLConnection; import flash.data.SQLStatement; import flash.events.SQLErrorEvent; import 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); }

In het volgende voorbeeld ziet u hoe u een tabel met de naam “employees” in een bestaand databasebestand creëert via de synchrone uitvoeringsmodus. Let op: deze code gaat ervan uit dat een SQLConnection-instantie met de naam conn al is gedefinieerd en met een database is verbonden. import flash.data.SQLConnection; import flash.data.SQLStatement; import flash.events.SQLErrorEvent; import 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; try { createStmt.execute(); trace("Table created"); } catch (error:SQLError) { trace("Error message:", error.message); trace("Details:", error.details); }

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 176 Werken met lokale SQL-databases

Werken met SQL-databasegegevens Bij het werken met lokale SQL-databases voert u regelmatig dezelfde taken uit, zoals het verbinden met een database, en het toevoegen van gegevens aan en ophalen van gegevens uit tabellen in een database. Bij het uitvoeren van deze taken moet u een aantal aspecten in acht nemen, zoals het werken met gegevenstypen en het verhelpen van fouten. Daarnaast zijn er verschillende databasetaken die u niet zo vaak zult uitvoeren maar doorgaans wel voordat u de veel voorkomende taken kunt uitvoeren. U moet bijvoorbeeld een database creëren en de structuur van de tabellen in de database definiëren voordat u kunt verbinden met de database en gegevens uit tabellen kunt ophalen. Deze minder frequente, initiële setuptaken worden besproken in “Databases creëren en wijzigen” op pagina 173. U kunt kiezen om databasebewerkingen asynchroon uit te voeren, wat betekent dat de database-engine op de achtergrond wordt uitgevoerd en deze u meldt wanneer de bewerking is voltooid (of mislukt) door een gebeurtenis te verzenden. U kunt deze bewerkingen echter ook synchroon uitvoeren. In dat geval worden de databasebewerkingen na elkaar uitgevoerd en wacht de hele toepassing (ook het vernieuwen van het scherm) tot de bewerkingen zijn voltooid voordat andere code wordt uitgevoerd. In de voorbeelden in deze sectie ziet u hoe u de bewerkingen synchroon en asynchroon kunt laten uitvoeren. Zie “Synchrone en asynchrone databasebewerkingen gebruiken” op pagina 194 voor meer informatie over het werken in synchrone of asynchrone uitvoeringsmodus.

Verbinden met een database Voordat u databasebewerkingen kunt uitvoeren, moet u een verbinding met het databasebestand tot stand brengen. Er wordt een SQLConnection-instantie gebruikt om de verbinding met een of meer databases te vertegenwoordigen. De eerste database waarmee u via een SQLConnection-instantie verbinding maakt, wordt de “hoofd”database genoemd. Met deze database maakt u verbinding via de methode open() (voor de synchrone uitvoeringsmodus) of openAsync() (voor de asynchrone uitvoeringsmodus). Als u een database opent via de bewerking openAsync(), moet u de gebeurtenis open van de SQLConnectioninstantie registreren zodat u een melding ontvangt wanneer de bewerking openAsync() is voltooid. Deze registratie is nodig als u wilt dat de gebeurtenis error van de SQLConnection-instantie controleert of de bewerking is voltooid/mislukt. In het volgende voorbeeld ziet u hoe u een bestaand databasebestand opent voor asynchrone uitvoering. Het databasebestand heeft de naam “DBSample.db” en bevindt zich in de toepassingsopslagdirectory van de gebruiker. import flash.data.SQLConnection; import flash.data.SQLMode; import flash.events.SQLErrorEvent; import flash.events.SQLEvent; import 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"); 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); }

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 177 Werken met lokale SQL-databases

In het volgende voorbeeld ziet u hoe u een bestaand databasebestand opent voor synchrone uitvoering. Het databasebestand heeft de naam “DBSample.db” en bevindt zich in de toepassingsopslagdirectory van de gebruiker. import flash.data.SQLConnection; import flash.data.SQLMode; import flash.events.SQLErrorEvent; import flash.events.SQLEvent; import flash.filesystem.File; var conn:SQLConnection = new SQLConnection(); var dbFile:File = File.applicationStorageDirectory.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); }

Let op: bij het oproepen van de methode openAsync() in het asynchrone voorbeeld en het oproepen van de methode open() in het synchrone voorbeeld is het tweede argument de constante SQLMode.UPDATE. Als u SQLMode.UPDATE opgeeft voor de tweede parameter (openMode), treedt een fout op als het opgegeven bestand niet bestaat. Als u SQLMode.CREATE opgeeft voor de parameter openMode (of als u geen waarde opgeeft voor de parameter openMode), probeert de runtime een databasebestand te creëren als het opgegeven bestand niet bestaat. U kunt ook SQLMode.READ opgeven voor de parameter openMode als u een bestaande database in alleen-lezen modus wilt openen. In dat geval kunnen gegevens uit de database worden opgehaald maar niet worden toegevoegd, verwijderd of gewijzigd.

Werken met SQL-instructies Een individuele SQL-instructie (een query of opdracht) wordt in de runtime vertegenwoordigd door een SQLStatement-object. Ga als volgt te werk om een SQL-instructie te creëren en uit te voeren: Creëer een SQLStatement-instantie. Het SQLStatement-object vertegenwoordigt de SQL-instructie in uw toepassing. var selectData:SQLStatement = new SQLStatement();

Geef de database op waarop u de query wilt toepassen. Hiervoor stelt u de eigenschap sqlConnection van het SQLStatement-object in op de SQLConnection-instantie die met de gewenste database is verbonden. // A SQLConnection named "conn" has been created previously selectData.sqlConnection = conn;

Geef de daadwerkelijke SQL-instructie op. Creëer de instructietekst als een tekenreeks (String) en wijs deze toe aan de eigenschap text van de SQLStatementinstantie. selectData.text = "SELECT col1, col2 FROM my_table WHERE col1 = :param1";

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 178 Werken met lokale SQL-databases

Definieer functies om het resultaat van de uitvoeringsbewerking (alleen asynchrone uitvoeringsmodus) te verwerken. Gebruik de methode addEventListener() om functies als listeners voor de gebeurtenissen result en error van de SQLStatement-instantie te registreren. // 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 }

U kunt ook listenermethoden opgeven met behulp van een Responder-object. In dat geval creëert u de Responderinstantie en koppelt u de listenermethoden aan die instantie. // 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 }

Als de instructietekst parameterdefinities bevat, wijst u waarden toe aan de desbetreffende parameters. U wijst parameterwaarden toe via de associatieve-array-eigenschap parameters van de SQLStatement-instantie. selectData.parameters[":param1"] = 25;

Voer de SQL-instructie uit. Roep de methode execute() van de SQLStatement-instantie op. // using synchronous execution mode // or listener methods in asynchronous execution mode selectData.execute();

Als u een Responder in plaats van gebeurtenislisteners gebruikt in asynchrone uitvoeringsmodus, moet u ook de Responder-instantie opgeven voor de methode execute(). // using a Responder in asynchronous execution mode selectData.execute(-1, selectResponder);

Zie de volgende onderwerpen voor specifieke voorbeelden die deze procedurestappen illustreren: “Gegevens ophalen uit een database” op pagina 181 “Gegevens invoegen” op pagina 187 “Gegevens wijzigen of verwijderen” op pagina 190

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 179 Werken met lokale SQL-databases

Parameters gebruiken in instructies Met een SQL-instructieparameter kunt u een herbruikbare SQL-instructie creëren. Bij het gebruik van instructieparameters kunnen waarden binnen de instructie wijzigen (zoals waarden die worden toegevoegd met een instructie van het type INSERT) maar blijft de basistekst van de instructie ongewijzigd. Dit verbetert de prestaties en vergemakkelijkt het schrijven van code voor een toepassing.

Instructieparameters Een toepassing gebruikt vaak dezelfde SQL-instructie meerdere keren, met slechts een kleine wijziging. Bijvoorbeeld: een voorraadbeheertoepassing waarmee een gebruiker nieuwe voorraaditems kan toevoegen aan de database. De toepassingscode die een voorraaditem toevoegt aan de database voert de SQL-instructie INSERT uit, waarmee de gegevens daadwerkelijk worden toegevoegd aan de database. Elke keer dat de instructie wordt uitgevoerd, is er echter een kleine wijziging. Met name de daadwerkelijke waarden die worden ingevoegd in de tabel, verschillen omdat ze specifiek zijn voor het voorraaditem dat wordt toegevoegd. Als een SQL-instructie meerdere keren maar met verschillende waarden wordt gebruikt, wordt u aangeraden een SQLinstructie te gebruiken die met parameters werkt en niet met literale waarden in de SQL-tekst. Een parameter is een placeholder in de instructietekst die door een daadwerkelijke waarde wordt vervangen elke keer dat de instructie wordt uitgevoerd. Als u parameters in een SQL-instructie wilt gebruiken, creëert u de SQLStatement-instantie op de gewone manier. Voor de daadwerkelijke SQL-instructie die aan de eigenschap text wordt toegewezen, gebruikt u parameterplaceholders in plaats van literale waarden. Vervolgens definieert u de waarde voor elke parameter door de waarde van een element in de eigenschap parameters van de SQLStatement-instantie in te stellen. Aangezien de eigenschap parameters een associatieve array is, stelt u een specifieke waarde in met de volgende syntaxis: statement.parameters[parameter_identifier] = value;

parameter_identifier is een tekenreeks als u een benoemde parameter gebruikt, of een index van gehele getallen als u een onbenoemde parameter gebruikt.

Benoemde parameters gebruiken Een parameter kan benoemd zijn. Een benoemde parameter heeft een specifieke naam die door de database wordt gebruikt om de parameterwaarde te koppelen aan de overeenkomstige placeholderlocatie in de instructietekst. De naam van een parameter bestaat uit het teken “:” of “@” gevolgd door een naam, zoals in de volgende voorbeelden wordt geïllustreerd: :itemName @firstName

De volgende code illustreert het gebruik van benoemde parameters: 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();

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 180 Werken met lokale SQL-databases

Onbenoemde parameters gebruiken Als alternatief voor het gebruik van benoemde parameters kunt u ook onbenoemde parameters gebruiken. Als u een onbenoemde parameter wilt gebruiken, geeft u een parameter in een SQL-instructie aan met een “?” (vraagteken). Aan elke parameter wordt een numerieke index toegewezen, afhankelijk van de volgorde van de parameters in de instructie, te beginnen bij index 0 voor de eerste parameter. In het volgende voorbeeld ziet u een variatie van het vorige voorbeeld, nu met onbenoemde parameters: 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();

Voordelen van het gebruik van parameters Het gebruik van parameters in een SQL-instructie biedt verschillende voordelen: Betere prestaties Een SQLStatement-instantie die parameters gebruikt, kan efficiënter werken dan een instantie die

de SQL-tekst dynamisch genereert bij elke uitvoering. De prestatieverbetering is te danken aan het feit dat de instructie één keer wordt voorbereid en vervolgens meerdere keren met verschillende parameterwaarden kan worden uitgevoerd zonder dat de SQL-instructie opnieuw hoeft te worden gecompileerd. Type toewijzen aan expliciete gegevens Parameters worden gebruikt voor het omzetten van waarden in een toegewezen type als de daadwerkelijke waarden niet bekend zijn op het moment dat de SQL-instructie wordt geschreven. Het gebruik van parameters is de enige manier om de opslagklasse te garanderen van een waarde die in de database wordt opgenomen. Als geen parameters worden gebruikt, probeert de runtime alle waarden om te zetten van hun tekstvorm in een opslagklasse op basis van het type van de overeenkomstige kolom. Zie de sectie "Data type support" (Ondersteuning van gegevenstypen) in de bijlage "SQL support in local databases" (SQL-ondersteuning in lokale databases) in ActionScript 3.0 Language and Components Reference voor meer informatie over opslagklassen en het type van waarden in een kolom. Betere beveiliging Het gebruik van parameters helpt een schadelijke techniek die SQL-injectieaanval wordt genoemd,

onmogelijk te maken. Bij een SQL-injectieaanval voert de gebruiker SQL-code in via een voor de gebruiker toegankelijke locatie (zoals een gegevensinvoerveld). Als toepassingscode een SQL-instructie genereert door gebruikersinvoer rechtstreeks samen te voegen tot SQL-tekst, wordt de door de gebruiker ingevoerde SQL-code uitgevoerd op de database. De volgende code is een voorbeeld van het samenvoegen van gebruikersinvoer tot SQLtekst. Gebruik deze techniek niet: // 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;

Door instructieparameters in plaats van door de gebruiker ingevoerde waarden samen te voegen tot de tekst voor een instructie, maakt u een SQL-injectieaanval onmogelijk. Er kan geen SQL-injectie plaatsvinden omdat de

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 181 Werken met lokale SQL-databases

parameterwaarden expliciet als vervangen waarden worden verwerkt, en niet als waarden die een onderdeel van de literale instructietekst worden. Dit is het aanbevolen alternatief voor de bovenstaande code: // 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;

Gegevens ophalen uit een database Het ophalen van gegevens uit een database bestaat uit twee stappen. Eerst voert u de SQL-instructie SELECT uit om de gegevensset te beschrijven die u uit de database wilt ophalen. Vervolgens benadert u de opgehaalde gegevens, en geeft u ze weer of bewerkt u ze, afhankelijk van de toepassing.

SELECT-instructies uitvoeren Voor het ophalen van bestaande gegevens uit een database gebruikt u een SQLStatement-instantie. Wijs de juiste SQLinstructie SELECT toe aan de eigenschap text van de instantie en roep vervolgens de methode execute() op. Zie voor meer informatie over de syntaxis van de instructie SELECT de bijlage "SQL support in local databases" (SQLondersteuning in lokale databases) in ActionScript 3.0 Language and Components Reference. In het volgende voorbeeld ziet u hoe u de instructie SELECT uitvoert om via de asynchrone uitvoeringsmodus gegevens op te halen uit de tabel “products”: var selectStmt:SQLStatement = new SQLStatement(); // A SQLConnection named "conn" has been created previously selectStmt.sqlConnection = conn; selectStmt.text = "SELECT itemId, itemName, price FROM products"; // The resultHandler and errorHandler are listener methods are // described in a subsequent code listing selectStmt.addEventListener(SQLEvent.RESULT, resultHandler); selectStmt.addEventListener(SQLErrorEvent.ERROR, errorHandler); selectStmt.execute();

In het volgende voorbeeld ziet u hoe u de instructie SELECT uitvoert om via de asynchrone uitvoeringsmodus gegevens op te halen uit de tabel “products”:

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 182 Werken met lokale SQL-databases

var selectStmt:SQLStatement = new SQLStatement(); // A SQLConnection named "conn" has been created previously selectStmt.sqlConnection = conn; selectStmt.text = "SELECT itemId, itemName, price FROM products"; // This try..catch block is fleshed out in // a subsequent code listing try { selectStmt.execute(); // accessing the data is shown in a subsequent code listing } catch (error:SQLError) { // error handling is shown in a subsequent code listing }

Nadat in de asynchrone uitvoeringsmodus de uitvoering van de instructie is voltooid, verzendt de SQLStatementinstantie de gebeurtenis result (SQLEvent.RESULT) om aan te geven dat de instructie correct is uitgevoerd. Als u echter een Responder-object hebt opgegeven als argument bij de oproep execute(), wordt de resultaathandlerfunctie van het Responder-object opgeroepen. In de synchrone uitvoeringsmodus wordt de uitvoering onderbroken tot de bewerking execute() is voltooid. Daarna gaat de uitvoering verder vanaf de volgende coderegel.

Resultaatgegevens van SELECT-instructie benaderen Nadat de uitvoering van de instructie SELECT is voltooid, kunnen de opgehaalde gegevens worden benaderd. Elke gegevensrij in de resultaatset SELECT wordt een Object-instantie. Het desbetreffende object heeft eigenschappen waarvan de naam overeenkomt met de naam van de kolommen in de resultaatset. De eigenschappen bevatten de waarden uit de kolommen in de resultaatset. De instructie SELECT geeft bijvoorbeeld een resultaatset met drie kolommen op: “itemId”, “itemName” en “price”. Voor elke rij van de resultaatset wordt een Object-instantie gecreëerd met de eigenschapnamen itemId, itemName en price. Deze eigenschappen bevatten de waarden uit de overeenkomstige kolommen. De volgende code is een vervolg van de vorige code voor het ophalen van gegevens in de asynchrone uitvoeringsmodus. In de code ziet u hoe u de opgehaalde gegevens benadert met de gebeurtenislistenermethode voor resultaatsets. 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. }

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 183 Werken met lokale SQL-databases

De volgende code is een uitbreiding van de vorige code voor het ophalen van gegevens in de synchrone uitvoeringsmodus. De code breidt het blok try..catch uit het vorige voorbeeld voor de synchrone uitvoeringsmodus uit om te illustreren hoe u de opgehaalde gegevens benadert. 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. }

Uit de vorige codevoorbeelden blijkt dat de resultaatobjecten zich bevinden in een array die beschikbaar is als de eigenschap data van een SQLResult-instantie. Als u de asynchrone uitvoeringsmodus met een gebeurtenislistener gebruikt, roept u de methode getResult() van de SQLStatement-instantie op om die SQLResult-instantie op te halen. Als u een Responder-argument hebt opgegeven bij de oproep execute(), wordt de SQLResult-instantie opgegeven als argument bij de resultaathandlerfunctie. In de synchrone uitvoeringsmodus roept u de methode getResult() van de SQLStatement-instantie op een willekeurig moment na het oproepen van de methode execute() op. In elk geval hebt u via de array-eigenschap data toegang tot de resultaatrijen nadat u het SQLResultobject hebt verkregen. De volgende code definieert een SQLStatement-instantie waarvan de tekst een SELECT-instructie is. De instructie haalt rijen op die de waarden uit de kolommen firstNamelastName bevatten op alle rijen uit de tabel employees. Dit voorbeeld gebruikt de asynchrone uitvoeringsmodus. Nadat de uitvoering is voltooid, wordt de methode selectResult() opgeroepen en worden de resultaatrijen met gegevens benaderd met SQLStatement.getResult() en weergegeven via de methode trace(). Let op: deze code gaat ervan uit dat een SQLConnection-instantie met de naam conn al is gedefinieerd en met de database is verbonden. De code gaat er ook van uit dat de tabel “employees” al is gecreëerd en gegevens bevat.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 184 Werken met lokale SQL-databases

import flash.data.SQLConnection; import flash.data.SQLResult; import flash.data.SQLStatement; import flash.events.SQLErrorEvent; import 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); }

De volgende code illustreert dezelfde technieken als de vorige code maar in de synchrone uitvoeringsmodus. Het voorbeeld definieert een SQLStatement-instantie waarvan de tekst een SELECT-instructie is. De instructie haalt rijen op die de waarden uit de kolommen firstNamelastName bevatten op alle rijen uit de tabel employees. De resultaatrijen met gegevens worden benaderd met SQLStatement.getResult() en weergegeven via de methode trace(). Let op: deze code gaat ervan uit dat een SQLConnection-instantie met de naam conn al is gedefinieerd en met de database is verbonden. De code gaat er ook van uit dat de tabel “employees” al is gecreëerd en gegevens bevat.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 185 Werken met lokale SQL-databases

import flash.data.SQLConnection; import flash.data.SQLResult; import flash.data.SQLStatement; import flash.events.SQLErrorEvent; import 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; 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); }

Het gegevenstype van SELECT-resultaatgegevens definiëren Elke rij die het resultaat is van een SELECT-instructie, wordt standaard gegenereerd als een Object-instantie met eigenschappen die zijn benoemd volgens de naam van de kolommen in de resultaatset en met de waarde van elke kolom als de waarde van de overeenkomstige eigenschap. Voordat u echter de SQL-instructie SELECT uitvoert, kunt u de eigenschap itemClass van de SQLStatement-instantie instellen op een klasse. Als u de eigenschap itemClass instelt, wordt elke rij die het resultaat is van de instructie SELECT gegenereerd als een instantie van de opgegeven klasse. De runtime wijst de waarden van resultaatkolommen aan eigenschapwaarden toe door de naam van de kolommen in de resultaatset van SELECT te baseren op de naam van de eigenschappen in de klasse itemClass. Elke klasse die is toegewezen als een itemClass-eigenschapwaarde, moet een constructor hebben waarvoor geen parameters nodig zijn. Bovendien moet de klasse één eigenschap hebben voor elke kolom die het resultaat is van de instructie SELECT. Als een kolom in de lijst SELECT geen gekoppelde eigenschapnaam in de klasse itemClass heeft, wordt dit als een fout beschouwd.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 186 Werken met lokale SQL-databases

SELECT-resultaten in delen ophalen Bij de uitvoering van een SELECT-instructie worden standaard alle rijen van de resultaatset tegelijk opgehaald. Nadat de instructie is voltooid, verwerkt u doorgaans de opgehaalde gegevens, bijvoorbeeld door objecten te creëren of de gegevens op het scherm weer te geven. Als de instructie een groot aantal rijen genereert, kan het verwerken van alle gegevens tegelijk een grote belasting voor de computer zijn, waardoor de gebruikersinterface niet wordt vernieuwd. U kunt de zichtbare prestaties van uw toepassing verbeteren door te zorgen dat de runtime slechts een bepaald aantal resultaatrijen tegelijk weergeeft. Hierdoor worden de initiële resultaatgegevens sneller weergegeven. Op deze manier kunt u ook de resultaatrijen in sets verdelen zodat de gebruikersinterface wordt bijgewerkt telkens wanneer een set rijen is verwerkt. Let op: deze techniek is alleen nuttig in asynchrone uitvoeringsmodus. Als u de resultaten van SELECT in delen wilt ophalen, geeft u een waarde op voor de eerste parameter van de methode SQLStatement.execute() (de parameter prefetch). De parameter prefetch geeft het aantal rijen aan dat u wilt ophalen de eerste keer dat de instructie wordt uitgevoerd. Als u de methode execute() van een SQLStatementinstantie oproept, geeft u een waarde voor de parameter prefetch op zodat alleen dat aantal rijen wordt opgehaald: 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

De instructie verzendt de gebeurtenis result wanneer de eerste set resultaatrijen beschikbaar is. De resultaateigenschap data van de SQLResult-instantie bevat de gegevensrijen en de eigenschap complete ervan geeft aan of er nog op te halen resultaatrijen resteren. Als u de volgende set gegevensrijen wilt ophalen, roept u de methode next() van de SQLStatement-instantie op. Net als bij de methode execute() wordt de eerste parameter van de methode next() gebruikt om aan te geven hoeveel rijen moeten worden opgehaald de volgende keer dat de gebeurtenis result wordt verzonden. 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); } } }

De SQLStatement verzendt de gebeurtenis result elke keer dat de methode next() een volgende set resultaatrijen weergeeft. Dit betekent dat dezelfde listenerfunctie kan worden gebruikt om verder te gaan met het verwerken van resultaten (op basis van next()-oproepen) tot alle rijen zijn opgehaald. Zie de taalverwijzingsbeschrijvingen voor de methode SQLStatement.execute() (de parameterbeschrijving prefetch) en de methode SQLStatement.next().

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 187 Werken met lokale SQL-databases

Gegevens invoegen Voor het ophalen van gegevens uit een database moet de SQL-instructie INSERT worden uitgevoerd. Nadat de instructie is uitgevoerd, hebt u toegang tot de primaire sleutel voor de zojuist ingevoegde rij als de sleutel door de database is gegenereerd.

INSERT-instructies uitvoeren Als u gegevens wilt toevoegen aan een tabel in een database, moet u een SQLStatement-instantie creëren en uitvoeren waarvan de tekst de SQL-instructie INSERT is. In het volgende voorbeeld ziet u hoe u een SQLStatement-instantie gebruikt om een gegevensrij toe te voegen aan de bestaande tabel “employees”. Dit voorbeeld illustreert het invoegen van gegevens in asynchrone uitvoeringsmodus. Let op: deze code gaat ervan uit dat een SQLConnection-instantie met de naam conn al is gedefinieerd en met een database is verbonden. De code gaat er ook van uit dat de tabel “employees” al is gecreëerd. import flash.data.SQLConnection; import flash.data.SQLResult; import flash.data.SQLStatement; import flash.events.SQLErrorEvent; import 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); }

In het volgende voorbeeld ziet u hoe u een gegevensrij toevoegt aan de bestaande tabel “employees” in synchrone uitvoeringsmodus. Let op: deze code gaat ervan uit dat een SQLConnection-instantie met de naam conn al is gedefinieerd en met een database is verbonden. De code gaat er ook van uit dat de tabel “employees” al is gecreëerd.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 188 Werken met lokale SQL-databases

import flash.data.SQLConnection; import flash.data.SQLResult; import flash.data.SQLStatement; import flash.events.SQLErrorEvent; import 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; try { // execute the statement insertStmt.execute(); trace("INSERT statement succeeded"); } catch (error:SQLError) { trace("Error message:", error.message); trace("Details:", error.details); }

De door de database gegenereerde primaire sleutel van een ingevoegde rij ophalen Vaak moet uw code na het invoegen van een gegevensrij in een tabel de door de database gegenereerde primaire sleutel of de rij-identificatiewaarde voor de zojuist ingevoegde rij weten. Nadat u een rij in één tabel hebt ingevoegd, wilt u bijvoorbeeld rijen toevoegen aan een gerelateerde tabel. In dat geval kunt u het best de waarde van de primaire sleutel als vreemde sleutel in de gerelateerde tabel invoegen. De primaire sleutel van de zojuist ingevoegde rij kan worden opgehaald via het SQLResult-object dat door het uitvoeren van de instructie is gegenereerd. Dit object wordt ook gebruikt om resultaatgegevens te benaderen nadat de instructie SELECT is uitgevoerd. Net als bij alle andere SQLinstructies creëert de runtime na het voltooien van de instructie INSERT een SQLResult-instantie. U benadert de SQLResult-instantie door de methode getResult() van het SQLStatement-object op te roepen als u een gebeurtenislistener of de synchrone uitvoeringsmodus gebruikt. Als u echter de asynchrone uitvoeringsmodus gebruikt en u een Responder-instantie opgeeft voor de oproep execute(), wordt de SQLResult-instantie opgegeven als argument bij de resultaathandlerfunctie. In elk geval heeft de SQLResult-instantie de eigenschap lastInsertRowID, die de rij-identificator van de laatst ingevoegde rij bevat als de uitgevoerde SQL-instructie de instructie INSERT is. In het volgende voorbeeld ziet u hoe u de primaire sleutel van een ingevoegde rij benadert in asynchrone uitvoeringsmodus: insertStmt.text = "INSERT INTO ..."; insertStmt.addEventListener(SQLEvent.RESULT, resultHandler); insertStmt.execute(); private 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 }

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 189 Werken met lokale SQL-databases

In het volgende voorbeeld ziet u hoe u de primaire sleutel van een ingevoegde rij benadert in synchrone uitvoeringsmodus: insertStmt.text = "INSERT INTO ..."; insertStmt.addEventListener(SQLEvent.RESULT, resultHandler); 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 }

Let op: mogelijk heeft de rij-identificator de waarde van de kolom die in de tabeldefinitie is opgegeven als de kolom met de primaire sleutel. Hierbij geldt de volgende regel:

• Als voor de tabel een kolom met de primaire sleutel is gedefinieerd waarbij de kolomgegevens van het type INTEGER zijn, bevat de eigenschap lastInsertRowID de waarde die in de desbetreffende rij is ingevoegd (of de waarde die door de runtime is gegenereerd als het een kolom van het type AUTOINCREMENT betreft).

• Als voor de tabel meerdere kolommen met de primaire sleutel zijn gedefinieerd (een samengestelde sleutel) of één kolom met de primaire sleutel waarbij de kolomgegevens niet van het type INTEGER zijn, genereert de database een onzichtbare rij-identificatiewaarde voor de rij. Die gegenereerde waarde is de waarde van de eigenschap lastInsertRowID.

• De waarde is altijd de rij-identificator van de laatst ingevoegde rij. Als de instructie INSERT een trigger activeert waardoor vervolgens een rij wordt ingevoegd, bevat de eigenschap lastInsertRowID de rij-identificator van de rij die het laatst door de trigger is ingevoegd en niet van de rij die door de instructie INSERT is gecreëerd. Dit betekent dat als u een kolom met een expliciet gedefinieerde primaire sleutel wilt waarvan de waarde beschikbaar is na de opdracht INSERT via de eigenschap SQLResult.lastInsertRowID, u de kolom moet definiëren als een kolom van het type INTEGER PRIMARY KEY. Let op: zelfs als uw tabel geen expliciete kolom van het type INTEGER PRIMARY KEY bevat, is het perfect acceptabel om de door de database gegenereerde rij-identificator als primaire sleutel voor uw tabel te gebruiken voor het definiëren van relaties met gerelateerde tabellen. De waarde van de kolom met de rij-identificator is in alle SQL-instructies beschikbaar door het gebruik van een van de speciale kolomnamen: ROWID, _ROWID_ of OID. U kunt in een gerelateerde tabel een kolom met een vreemde sleutel creëren en de rijidentificatiewaarde gebruiken als waarde voor de kolom met de vreemde sleutel, zoals bij een expliciet gedefinieerde kolom van het type INTEGER PRIMARY KEY. Als u dus een willekeurige primaire sleutel gebruikt in plaats van een natuurlijke sleutel en u het niet erg vindt dat de runtime de waarde van de primaire sleutel voor u genereert, is er geen groot verschil tussen het gebruik van een kolom van het type INTEGER PRIMARY KEY of van de door het systeem gegenereerde rij-identificator als primaire sleutel van de tabel bij het definiëren van een relatie met vreemde sleutel tussen twee tabellen. Zie de secties "CREATE TABLE" en "Expressions" (Expressies) in de bijlage "SQL support in local databases" (SQLondersteuning in lokale databases) in ActionScript 3.0 Language and Components Reference voor meer informatie over primaire sleutels en gegenereerde rij-identificatoren.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 190 Werken met lokale SQL-databases

Gegevens wijzigen of verwijderen Voor het uitvoeren van andere gegevensbewerkingen gebruikt u dezelfde procedure als voor het uitvoeren van de SQLinstructie SELECT of INSERT. Vervang gewoon de SQL-instructie in de eigenschap text van de SQLStatementinstantie:

• Als u bestaande gegevens in een tabel wilt wijzigen, gebruikt u de instructie UPDATE. • Als u een of meer gegevensrijen uit een tabel wilt verwijderen, gebruikt u de instructie DELETE. Zie de bijlage "SQL support in local databases" (SQL-ondersteuning in lokale databases) in ActionScript 3.0 Language and Components Reference voor een beschrijving van deze instructies.

Werken met meerdere databases Gebruik de methode SQLConnection.attach() om een verbinding met een andere database te openen voor een SQLConnection-instantie waarmee al een open database is verbonden. Geef de verbonden database een naam met behulp van de parameter “name” via het oproepen van de methode attach(). Wanneer u vervolgens instructies voor het bewerken van de desbetreffende database schrijft, kunt u die naam in een voorvoegsel gebruiken (met de syntaxis databasenaam.tabelnaam) om eventuele tabelnamen in uw SQL-instructies te definiëren, zodat de runtime weet dat de tabel zich in de opgegeven database bevindt. U kunt werken met één SQL-instructie die verwijst naar tabellen uit meerdere databases die zijn verbonden met dezelfde SQLConnection-instantie. Als een transactie voor de SQLConnection-instantie wordt gecreëerd, geldt de desbetreffende transactie voor alle SQL-instructies die met behulp van de SQLConnection-instantie worden uitgevoerd. Deze regel geldt altijd, ongeacht de database waarop de instructie wordt uitgevoerd. U kunt echter ook meerdere SQLConnection-instanties in een toepassing creëren, waarbij elke instantie is verbonden met een of meer databases. Als u echter meerdere verbindingen met dezelfde database gebruikt, mag u niet vergeten dat databasetransacties niet worden gedeeld over SQLConnection-instanties. Dit betekent dat als u via meerdere SQLConnection-instanties verbinding maakt met hetzelfde databasebestand, u er niet op mag vertrouwen dat de wijzigingen in de gegevens van beide verbindingen op de verwachte manier worden doorgevoerd. Als bijvoorbeeld twee UPDATE- of DELETE-instructies op dezelfde database maar via verschillende SQLConnection-instanties worden uitgevoerd en er een toepassingsfout optreedt na één bewerking, bevinden de databasegegevens zich mogelijk in een onomkeerbare tussenfase, waardoor de integriteit van de database (en dus ook van de toepassing) in gevaar kan komen.

Databasefouten verhelpen Over het algemeen verloopt het verhelpen van databasefouten zoals het verhelpen van andere runtimefouten. U wordt aangeraden code te schrijven die is voorbereid op het optreden van mogelijke fouten en deze kan verhelpen, in plaats van dit door de runtime te laten doen. Databasefouten worden doorgaans in drie categorieën verdeeld: verbindingsfouten, SQL-syntaxisfouten en beperkingsfouten.

Verbindingsfouten De meeste databasefouten zijn verbindingsfouten. Deze kunnen tijdens alle bewerkingen optreden. Er zijn weliswaar strategieën voor het voorkomen van verbindingsfouten maar er is slechts zelden een eenvoudige manier om zonder problemen van een verbindingsfout te herstellen als de database een belangrijk deel is van uw toepassing.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 191 Werken met lokale SQL-databases

De meeste verbindingsfouten worden veroorzaakt door de manier waarop de runtime interageert met het besturingssysteem, het bestandssysteem en het databasebestand. Er treedt bijvoorbeeld een verbindingsfout op als de gebruiker geen toestemming heeft om een databasebestand te creëren op een bepaalde locatie van het bestandssysteem. De volgende strategieën helpen verbindingsfouten te voorkomen: Gebruik gebruikersspecifieke databasebestanden Geef iedere gebruiker zijn of haar eigen databasebestand, in plaats van één databasebestand te gebruiken voor alle gebruikers die de toepassing op één computer gebruiken. Plaats het bestand in een directory die aan de account van de gebruiker is gekoppeld. Dit kan bijvoorbeeld de opslagdirectory van de toepassing, de documentenmap van de gebruiker of het bureaublad van de gebruiker zijn. Houd rekening met verschillende soorten gebruikers Test uw toepassing met verschillende soorten gebruikersaccounts in verschillende besturingssystemen. Ga er niet van uit dat de gebruiker beheerdersrechten heeft voor de computer. Ga er ook niet van uit dat de persoon die de toepassing heeft geïnstalleerd, de gebruiker is die de toepassing uitvoert. Houd rekening met verschillende bestandslocaties Als u een gebruiker toestaat de opslaglocatie van een

databasebestand te bepalen of het te openen bestand te selecteren, moet u rekening houden met de mogelijke bestandslocaties die de gebruikers kunnen selecteren. Bovendien kunt u het best de lijst van mogelijke opslaglocaties (of bronlocaties voor het openen) voor databasebestanden beperken. U kunt bijvoorbeeld gebruikers alleen toestaan bestanden te openen die zich binnen de opslaglocatie van hun gebruikersaccount bevinden. Als een verbindingsfout optreedt, is dit doorgaans bij de eerste poging om de database te creëren of te openen. Dit betekent dat de gebruiker geen enkele databasegerelateerde bewerking in de toepassing kan uitvoeren. Voor bepaalde soorten fouten, zoals alleen-lezen of toegangsrechtfouten, is een van de mogelijke hersteltechnieken het kopiëren van het databasebestand naar een andere locatie. De toepassing kan het databasebestand kopiëren naar een locatie waarvoor de gebruiker wel toegangsrechten heeft om bestanden te creëren en te wijzigen, en vervolgens die nieuwe locatie gebruiken.

Syntaxisfouten Een syntaxisfout treedt op als de toepassing een SQL-instructie probeert uit te voeren die niet goed is geformuleerd. Aangezien SQL-instructies voor lokale databases als tekenreeksen zijn gecreëerd, is het niet mogelijk om de SQLsyntaxis tijdens het compileren te controleren. Alle SQL-instructies moeten worden uitgevoerd om hun syntaxis te controleren. Pas de volgende strategieën toe om SQL-syntaxisfouten te voorkomen: Voer een grondige test uit van alle SQL-instructies Indien mogelijk moet u uw SQL-instructies tijdens de

ontwikkeling van uw toepassing apart testen voordat u ze als instructietekst in de toepassingscode codeert. Bovendien wordt u aangeraden een codetestfase in te plannen (zoals het testen per eenheid) om een set van tests te creëren die elke mogelijke optie en codevariatie testen. Gebruik instructieparameters en vermijd het samenvoegen (dynamisch genereren) van SQL Parameters gebruiken,

en dynamisch gegenereerde SQL-instructies vermijden, betekent dat dezelfde SQL-instructietekst wordt gebruikt elke keer dat een instructie wordt uitgevoerd. Hierdoor is het veel eenvoudiger om uw instructies te testen en de mogelijke variaties te beperken. Als u een SQL-instructie dynamisch moet genereren, moet u de dynamische delen van de instructie tot het minimum beperken. Ga ook zorgvuldig te werk bij het valideren van gegevensinvoer om te zorgen dat deze geen syntaxisfouten veroorzaakt. Een toepassing die van een syntaxisfout moet herstellen, heeft complexe logica nodig om een SQL-instructie te controleren en de syntaxis te corrigeren. Door de volgende richtlijnen voor het voorkomen van syntaxisfouten in acht te nemen, kan uw code mogelijke runtimebronnen van SQL-syntaxisfouten (zoals gebruikersinvoer in een instructie) identificeren. Zorg dat de gebruiker over richtlijnen beschikt als een syntaxisfout optreedt. Geef aan wat de gebruiker moet corrigeren om te zorgen dat de instructie correct wordt uitgevoerd.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 192 Werken met lokale SQL-databases

Beperkingsfouten Beperkingsfouten treden op wanneer de instructie INSERT of UPDATE gegevens aan een kolom probeert toe te voegen. De fout treedt op als de nieuwe gegevens een van de vooraf gedefinieerde beperkingen voor de tabel of kolom schenden. U kunt onder andere de volgende beperkingen instellen: Beperking ‘uniek’ Geeft aan dat geen enkele rij van de tabel een al bestaande waarde mag bevatten binnen een

bepaalde kolom. Of u kunt aangeven dat wanneer meerdere kolommen worden gecombineerd in één beperking, de combinatie van waarden in de desbetreffende kolommen niet mag worden gedupliceerd. Met andere woorden, elke rij moet verschillend zijn op het gebied van de opgegeven unieke kolom(men). Beperking ‘primaire sleutel’ Wat de gegevens betreft die een beperking (niet) toestaat, is een beperking ‘primaire

sleutel’ hetzelfde als een beperking ‘uniek’. Beperking ‘niet leeg’ Geeft aan dat een bepaalde kolom niet de waarde NULL mag bevatten, met andere woorden, dat

alle rijen in de desbetreffende kolom een waarde moeten hebben. Beperking ‘controle’ Biedt u de mogelijkheid om een willekeurige beperking in te stellen voor een of meer tabellen.

Een veel voorkomende beperking van het ‘controle’ is een regel die bepaalt dat de waarde in een kolom zich binnen een bepaald bereik moet bevinden (bijvoorbeeld dat de waarde in een numerieke kolom groter moet zijn dan 0). Een andere veel voorkomende beperking van het type ‘controle’ definieert relaties tussen kolomwaarden (bijvoorbeeld dat de waarde in een kolom moet verschillen van de waarde in een andere kolom op dezelfde rij). Beperking ‘gegevenstype’ De runtime legt het gegevenstype voor de kolomwaarden op en er treedt een fout op als

wordt geprobeerd om een waarde op te slaan die niet het juiste type heeft voor de kolom. In vele situaties worden waarden echter omgezet zodat ze het gegevenstype hebben dat is ingesteld voor de kolom. Zie “Werken met gegevenstypen” op pagina 193 voor meer informatie. De runtime legt geen beperkingen op voor vreemde-sleutelwaarden. Met andere woorden, vreemde-sleutelwaarden hoeven niet overeen te komen met een bestaande primaire-sleutelwaarde. Naast de vooraf gedefinieerde typen beperkingen ondersteunt de SQL-runtime-engine het gebruik van triggers. Een trigger is vergelijkbaar met een gebeurtenishandler. Het is een vooraf gedefinieerde instructieset die worden uitgevoerd wanneer zich een bepaalde actie voordoet. U kunt bijvoorbeeld een trigger definiëren die worden geactiveerd wanneer gegevens worden ingevoegd in of verwijderd uit een bepaalde tabel. Een voorbeeld van het gebruik van een trigger is het controleren van wijzigingen in gegevens en het weergeven van een foutmelding als niet wordt voldaan aan de opgegeven voorwaarden. Dit betekent dat een trigger hetzelfde doel kan hebben als een beperking, en dat de strategieën voor het voorkomen en herstellen van beperkingsfouten ook gelden voor fouten die door een trigger worden gegenereerd. De fout-id voor fouten die door een trigger worden gegenereerd, verschilt echter van de fout-id voor beperkingsfouten. De set van beperkingen die gelden voor een bepaalde tabel wordt gedefinieerd terwijl u een toepassing ontwikkelt. Door goed na te denken bij het definiëren van beperkingen vergemakkelijkt u het voorkomen en herstellen van beperkingsfouten in uw toepassingen. Beperkingsfouten zijn echter moeilijk systematisch te voorspellen en te voorkomen. Het voorspellen is moeilijk omdat beperkingsfouten pas optreden wanneer toepassingsgegevens worden toegevoegd. Beperkingsfouten treden op wanneer gegevens aan een database worden toegevoegd nadat deze is gecreëerd. Deze fouten zijn vaak het resultaat van de relatie tussen nieuwe gegevens en gegevens die al in de database aanwezig zijn. De volgende strategieën kunnen u helpen veel voorkomende beperkingsfouten te voorkomen: Plan de databasestructuur en de beperkingen zorgvuldig Het doel van beperkingen is toepassingsregels op te leggen en te helpen de integriteit van de databasegegevens te beschermen. Denk tijdens het plannen van uw toepassing na over de structuur van uw database zodat deze uw toepassing kan ondersteunen. Hierbij identificeert u regels voor de gegevens, zoals of bepaalde waarden vereist zijn, een waarde een standaardinstelling heeft, dubbele waarden zijn toegestaan enzovoort. Deze regels helpen u bij het definiëren van databasebeperkingen.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 193 Werken met lokale SQL-databases

Geef expliciet kolomnamen op U kunt de instructie INSERT gebruiken zonder expliciet de kolommen op te geven

waarin waarden zullen worden ingevoegd. Dit is echter een onnodig risico. Door expliciet de kolommen te benoemen waarin waarden zullen worden ingevoegd, kunt u automatisch gegenereerde waarden, kolommen met standaardwaarden en kolommen met de waarde NULL gebruiken. Bovendien zorgt u hierdoor dat in alle kolommen van het type NOT NULL een expliciete waarde wordt ingevoegd. Gebruik standaardwaarden Wanneer u de beperking NOT NULL voor een kolom opgeeft, geeft u wanneer mogelijk een

standaardwaarde in de kolomdefinitie op. Ook toepassingscode kan in standaardwaarden voorzien. Uw code kan bijvoorbeeld controleren of een tekenreeksvariabele de waarde null heeft en er een waarde aan toewijzen voordat de variabele wordt gebruikt om de waarde van een instructieparameter in te stellen. Valideer gebruikersinvoer Controleer gebruikersinvoer voordat de gegevens daadwerkelijk in de database worden ingevoegd om te zorgen dat de invoer aan de beperkingen voldoet, met name in het geval van de beperkingen NOT NULL en CHECK. De beperking UNIQUE is uiteraard moeilijker te controleren omdat een SELECT-query moet worden uitgevoerd om te bepalen of de gegevens uniek zijn. Gebruik triggers U kunt een trigger schrijven die ingevoegde gegevens verifieert (en mogelijk vervangt) of andere

acties uitvoert om ongeldige gegevens te corrigeren. Deze verificatie- en correctieacties kunnen beperkingsfouten voorkomen. In vele opzichten zijn beperkingsfouten moeilijker te voorkomen dan andere fouttypen. Gelukkig zijn er verschillende strategieën om van beperkingsfouten te herstellen zonder dat de toepassing instabiel of onbruikbaar wordt: Gebruik conflictalgoritmen Als u een beperking voor een kolom definieert en als u de instructie INSERT of UPDATE

creëert, kunt u desgewenst een conflictalgoritme opgeven. Een conflictalgoritme definieert de actie die de database uitvoert als een beperkingsfout optreedt. De database-engine kan verschillende mogelijke acties uitvoeren. De database-engine kan één instructie of een complete transactie beëindigen. De engine kan de fout negeren. Of zelfs oude gegevens verwijderen en deze vervangen door de gegevens die de code probeert op te slaan. Zie de sectie "ON CONFLICT (conflict algorithms)" (Conflictalgoritmen) in de bijlage "SQL support in local databases" (SQL-ondersteuning in lokale databases) in ActionScript 3.0 Language and Components Reference voor meer informatie. Geef feedback met een oplossing De set van beperkingen die een bepaalde SQL-opdracht kunnen beïnvloeden, kan

van tevoren worden geïdentificeerd. Dit betekent dat u beperkingsfouten die door een instructie kunnen worden veroorzaakt, kunt voorspellen. Op die kennis kunt u toepassingslogica baseren die op een beperkingsfout reageert. Een toepassing bevat bijvoorbeeld een formulier voor het invoeren van nieuwe producten. Als de kolom met de productnaam in de database is gedefinieerd met een beperking van het type UNIQUE, kan het invoegen van een nieuwe productrij in de database een beperkingsfout veroorzaken. Daarom wordt de toepassing zo ontwikkeld dat deze van tevoren rekening houdt met een beperkingsfout. Als de fout optreedt, waarschuwt de toepassing de gebruiker dat de opgegeven productnaam al bestaat en dat een andere naam moet worden gekozen. Een andere mogelijke reactie is dat informatie over het andere product met dezelfde naam wordt weergegeven.

Werken met gegevenstypen Bij het creëren van een tabel in een database definieert de SQL-instructie voor het creëren van de tabel het gegevenstype voor elke kolom van de tabel. Het toewijzen van typen is weliswaar niet vereist maar u wordt toch aangeraden het kolomtype expliciet op te geven in uw SQL-instructies CREATE TABLE. Normaliter wordt elk object dat u in een database opslaat met de instructie INSERT, weergegeven als een instantie van hetzelfde gegevenstype wanneer u de instructie SELECT uitvoert. De opgehaalde waarde kan echter een ander gegevenstype hebben, afhankelijk van de toewijzing van het type aan de databasekolom waarin de waarde is opgeslagen. Als het gegevenstype van een waarde die in een kolom wordt opgeslagen, niet overeenkomt met het type dat aan de kolom is toegewezen, probeert de database de waarde om te zetten in het type dat aan de kolom is

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 194 Werken met lokale SQL-databases

toegewezen. Als bijvoorbeeld het gegevenstype NUMERIC aan een databasekolom is toegewezen, probeert de database ingevoegde gegevens om te zetten in een numerieke opslagklasse (INTEGER of REAL) voordat de gegevens worden opgeslagen. De database genereert een foutmelding als de gegevens niet kunnen worden omgezet. Als de tekenreeks “12345” wordt ingevoegd in een kolom van het type NUMERIC, zet de database op basis van deze regel de tekenreeks automatisch om in het geheel getal 12345 voordat de waarde in de database wordt opgeslagen. Wanneer de waarde wordt opgehaald met de instructie SELECT, wordt deze weergegeven als een instantie van een numeriek gegevenstype (bijvoorbeeld Number) in plaats van een tekenreeksinstantie. De beste manier om ongewenste omzetting van het gegevenstype te voorkomen, is het in acht nemen van twee regels. Ten eerste: definieer elke kolom met het type dat overeenkomt met het type gegevens dat u wilt opslaan. Ten tweede: voeg alleen waarden in waarvan het gegevenstype overeenkomt met het toegewezen type. Het in acht nemen van deze regels biedt twee voordelen. Wanneer u de gegevens invoegt, worden deze niet onbedoeld omgezet (waardoor mogelijk de bedoelde betekenis verloren zou gaan). Bovendien worden de gegevens bij het ophalen weergegeven met het oorspronkelijke gegevenstype. Zie de sectie "Data type support" (Ondersteuning van gegevenstypen) in de bijlage "SQL support in local databases" (SQL-ondersteuning in lokale databases) in ActionScript 3.0 Language and Components Reference voor meer informatie over de beschikbare gegevenstypen voor kolommen en het gebruik van gegevenstypen in SQL-instructies.

Synchrone en asynchrone databasebewerkingen gebruiken In de vorige secties zijn veel voorkomende databasebewerkingen besproken, zoals het ophalen, invoegen, updaten en verwijderen van gegevens, evenals het creëren van een databasebestand en tabellen en andere objecten binnen een database. In de voorbeelden hebt u gezien hoe u deze bewerkingen synchroon en asynchroon kunt laten uitvoeren. Ter herinnering: in asynchrone uitvoeringsmodus geeft u de database-engine de opdracht om een bewerking uit te voeren. De database-engine werkt vervolgens op de achtergrond terwijl de toepassing verderwerkt. Nadat de bewerking is voltooid, verzendt de database-engine een gebeurtenis om u dit te melden. Het belangrijkste voordeel van asynchrone uitvoering is dat de runtime de databasebewerkingen op de achtergrond uitvoert terwijl de hoofdtoepassingscode verder wordt uitgevoerd. Dit is vooral belangrijk wanneer het uitvoeren van de bewerking lang duurt. In de synchrone uitvoeringsmodus echter worden de bewerkingen niet op de achtergrond uitgevoerd. U geeft de database-engine de opdracht een bewerking uit te voeren. De code wordt op dat punt onderbroken terwijl de databaseengine zijn werk doet. Nadat de bewerking is voltooid, gaat de uitvoering verder vanaf de volgende regel van uw code. Het is niet mogelijk om via één enkele databaseverbinding bepaalde bewerkingen of instructies synchroon en andere asynchroon uit te voeren. U bepaalt welke uitvoeringsmodus (synchroon of asynchroon) voor een SQLConnection wordt gebruikt wanneer u verbinding maakt met de database. Als u SQLConnection.open() oproept, werkt de verbinding in synchrone uitvoeringsmodus. Roept u SQLConnection.openAsync() op, dan werkt de verbinding in asynchrone uitvoeringsmodus. Nadat een SQLConnection-instantie met een database is verbonden met behulp van open() of openAsync(), wordt deze in synchrone of asynchrone uitvoeringsmodus vergrendeld.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 195 Werken met lokale SQL-databases

Synchrone databasebewerkingen gebruiken Op het gebied van de daadwerkelijke code die u gebruikt om bewerkingen uit te voeren en erop te reageren, is er niet veel verschil tussen de synchrone en asynchrone uitvoeringsmodus. De belangrijkste verschillen tussen beide modi liggen in twee gebieden. Het eerste verschil is de uitvoering van een bewerking die afhankelijk is van een andere bewerking (bijvoorbeeld rijen die het resultaat zijn van SELECT of de primaire sleutel van de rij die is toegevoegd door de instructie INSERT). Het tweede verschil is de verwerking van fouten.

Code schrijven voor synchrone bewerkingen Het belangrijkste verschil tussen synchrone en asynchrone uitvoering is dat u in de synchrone modus de code als één reeks van stappen schrijft. In de asynchrone modus registreert u gebeurtenislisteners en verdeelt u vaak bewerkingen over verschillende listenermethoden. Als een database in de synchrone uitvoeringsmodus is verbonden, kunt u een reeks van opeenvolgende databasebewerkingen binnen één codeblok laten uitvoeren. Deze techniek wordt in het volgende voorbeeld getoond: var conn:SQLConnection = new SQLConnection(); var dbFile:File = File.applicationStorageDirectory.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();

Zoals u ziet, roept u dezelfde methoden op om databasebewerkingen uit te voeren, ongeacht de modus die u gebruikt (synchroon of asynchroon). De belangrijkste verschillen tussen beide modi zijn de uitvoering van een bewerking die afhankelijk is van een andere bewerking, en de verwerking van fouten.

Bewerkingen uitvoeren die afhankelijk zijn van een andere bewerking In de synchrone uitvoeringsmodus hoeft u geen code te schrijven die op een gebeurtenis wacht om te bepalen wanneer een bewerking is voltooid. U mag ervan uitgaan dat als een bewerking op een bepaalde regel van de code is voltooid, de uitvoering verdergaat met de volgende regel. Dit betekent dat als u een bewerking wilt uitvoeren die afhankelijk is van de voltooiing van een andere bewerking, u gewoon de afhankelijke code onmiddellijk na de bewerking schrijft waarvan deze afhankelijk is. Als u bijvoorbeeld wilt dat een toepassing een transactie start, de instructie INSERT uitvoert, de primaire sleutel van de ingevoegde rij ophaalt, die primaire sleutel op een andere rij van een andere tabel invoegt en ten slotte de transactie bevestigt, kunt u de complete code als een reeks van instructies schrijven. In het volgende voorbeeld ziet u het gebruik van deze bewerkingen:

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 196 Werken met lokale SQL-databases

var conn:SQLConnection = new SQLConnection(); var dbFile:File = File.applicationStorageDirectory.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();

Fouten verwerken in synchrone uitvoeringsmodus In de synchrone uitvoeringsmodus wacht u niet op een foutgebeurtenis om te bepalen of een bewerking is mislukt. In plaats daarvan plaatst u code die fouten kan veroorzaken in een set codeblokken van het type try..catch..finally. Plaats de code die de fout kan genereren in het blok try. Schrijf de acties die als reactie op de verschillende fouttypen moeten worden uitgevoerd in aparte blokken van het type catch. Plaats eventuele code die u altijd wilt uitvoeren ongeacht het resultaat (bijvoorbeeld het sluiten van een databaseverbinding die u niet meer nodig hebt) in een blok van het type finally. In het volgende voorbeeld ziet u hoe u blokken van het type try..catch..finally voor foutverwerking gebruikt. Dit voorbeeld is gebaseerd op het vorige voorbeeld maar voegt code voor foutverwerking toe:

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 197 Werken met lokale SQL-databases

var conn:SQLConnection = new SQLConnection(); var dbFile:File = File.applicationStorageDirectory.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(); }

De asynchrone uitvoeringsmodus Veel ontwikkelaars gebruiken de asynchrone uitvoeringsmodus liever niet omdat ze denken dat de uitvoering van een SQLStatement-instantie niet kan worden gestart als al een andere SQLStatement wordt uitgevoerd via dezelfde databaseverbinding. Dit is niet juist. U kunt de eigenschap text van een SQLStatement-instantie niet wijzigen terwijl de instructie wordt uitgevoerd. Als u echter een aparte SQLStatement-instantie gebruikt voor elke verschillende SQLinstructie die u wilt uitvoeren, kunt u de methode execute() van een SQLStatement oproepen terwijl een andere SQLStatement-instantie wordt uitgevoerd, zonder dat een fout optreedt. Wanneer u databasebewerkingen uitvoert in de asynchrone uitvoeringsmodus, heeft elke databaseverbinding (elke SQLConnection-instantie) een eigen interne wachtrij of lijst van bewerkingen die de verbinding moet uitvoeren. De runtime voert de bewerkingen één voor één uit in de volgorde waarin ze aan de wachtrij zijn toegevoegd. Wanneer u een SQLStatement-instantie creëert en de overeenkomstige methode execute() oproept, wordt de desbetreffende bewerking voor het uitvoeren van de instructie toegevoegd aan de wachtrij van de verbinding. Als er momenteel geen bewerking wordt uitgevoerd voor de desbetreffende SQLConnection-instantie, wordt de uitvoering van de instructie op de achtergrond gestart. U kunt bijvoorbeeld binnen hetzelfde codeblok een andere SQLStatement-instantie creëren

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 198 Werken met lokale SQL-databases

en ook de methode execute() van de desbetreffende methode oproepen. Die tweede bewerking voor het uitvoeren van de instructie wordt na de eerste instructie in de wachtrij geplaatst. Zodra de eerste instructie is voltooid, voert de runtime de volgende bewerking uit de wachtrij uit. De verwerking van daarop volgende bewerkingen uit de wachtrij vindt op de achtergrond plaats, zelfs wanneer de gebeurtenis result voor de eerste bewerking wordt verzonden in de hoofdtoepassingscode. In de volgende code wordt deze techniek geïllustreerd: // 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.

Er is een belangrijk neveneffect: de database voert automatisch daarop volgende instructies uit de wachtrij uit. Als een instructie afhankelijk is van het resultaat van een andere bewerking, kunt u de instructie niet toevoegen aan de wachtrij (met andere woorden, u kunt de methode execute() van de instructie niet oproepen) voordat de eerste bewerking is voltooid. De reden hiervoor is dat nadat u de methode execute() van de tweede instructie hebt opgeroepen, u de eigenschap text of parameters van de instructie niet meer kunt wijzigen. In dat geval kunt u de volgende bewerking pas starten nadat de gebeurtenis is verzonden die aangeeft dat de eerste bewerking is voltooid. Als u bijvoorbeeld een instructie in het kader van een transactie wilt uitvoeren, is de uitvoering van de instructie afhankelijk van het openen van de transactie. Nadat u de methode SQLConnection.begin() hebt opgeroepen om de transactie te openen, moet u wachten tot de SQLConnection-instantie de gebeurtenis begin verzendt. Pas daarna kunt u de methode execute() van de SQLStatement-instantie oproepen. In dit voorbeeld is de eenvoudigste manier om de toepassing zo te structureren dat de bewerkingen correct worden uitgevoerd, het creëren van een methode die als listener voor de gebeurtenis begin is geregistreerd. De code die de methode SQLStatement.execute() oproept, wordt binnen die listenermethode geplaatst.

Strategieën voor het werken met SQL-databases Er zijn verschillende manieren waarop een toepassing een lokale SQL-database kan benaderen en ermee kan werken. Het ontwerp van de toepassing kan variëren op het gebied van de structuur van de toepassingscode, de sequentie en timing van de uitvoering van de bewerkingen enzovoort. De technieken die u kiest, kunnen een invloed hebben op het gemak waarmee uw toepassing kan worden ontwikkeld. Ze kunnen een invloed hebben op het gemak waarmee de toepassing in de toekomst kan worden aangepast. Ze kunnen ook een invloed hebben op de prestaties van de toepassing voor de gebruiker.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 199 Werken met lokale SQL-databases

Niet-lege databases distribueren Als u een lokale SQL-database van AIR in uw toepassing gebruikt, verwacht de toepassing een database met een bepaalde structuur (tabellen, kolommen enzovoort). Sommige toepassingen verwachten ook bepaalde gegevens in het databasebestand. U kunt op verschillende manieren zorgen dat de database de juiste structuur heeft, onder andere door de database binnen de toepassingscode te creëren. Wanneer de toepassing wordt geladen, controleert deze of het gekoppelde databasebestand zich op een bepaalde locatie bevindt. Als dat niet het geval is, voert de toepassing een reeks opdrachten uit om het databasebestand te creëren, de databasestructuur toe te passen en de tabellen te vullen met de initiële gegevens. De code die de database en de overeenkomstige tabellen creëert, is vaak complex. Hoewel deze code doorgaans slechts één keer tijdens de levensduur van de geïnstalleerde toepassing wordt gebruikt, wordt de toepassing er groter en complexer door. Een alternatief voor het programmamatig creëren van de database, structuur en gegevens is uw toepassing te distribueren met een niet-lege database. Hiervoor neemt u het databasebestand op in het AIR-pakket van de toepassing. Net als alle bestanden die in een AIR-pakket worden opgenomen, wordt een gebundeld databasebestand geïnstalleerd in de toepassingsmap (de map die wordt ingesteld door de eigenschap File.applicationDirectory). Bestanden in die map zijn echter alleen-lezen. Gebruik het bestand uit het AIR-pakket als “sjabloon”database. De eerste keer dat een gebruiker de toepassing uitvoert, kopieert u het oorspronkelijke databasebestand naar de toepassingsopslagdirectory van de gebruiker (of een andere locatie). Vervolgens wordt die database in de toepassing gebruikt.

Databaseprestaties verbeteren Adobe AIR biedt meerdere technieken om de prestaties van databasebewerkingen in uw toepassing te verbeteren. Naast de hier beschreven technieken kan ook de manier waarop een SQL-instructie is geschreven, de databaseprestaties beïnvloeden. Er zijn doorgaans meerdere manieren om de SQL-instructie SELECT te schrijven om een specifieke resultaatset op te halen. In sommige gevallen is de belasting op de database-engine afhankelijk van de techniek die u gebruikt. Dit aspect van het verbeteren van de databaseprestaties (het ontwerpen van SQL-instructies voor prestatieverbetering) wordt niet besproken in de documentatie bij Adobe AIR.

Gebruik één SQLStatement-instantie per SQL-instructie Voordat een SQL-instructie wordt uitgevoerd, wordt deze door de runtime voorbereid (gecompileerd) om de stappen te bepalen die intern moeten worden uitgevoerd om de instructie uit te voeren. Als u SQLStatement.execute() oproept voor een SQLStatement-instantie die nog niet heeft uitgevoerd, wordt de instructie automatisch voorbereid voordat deze wordt uitgevoerd. De volgende keren dat u de methode execute() oproept, is de instructie al voorbereid mits de eigenschap SQLStatement.text niet is gewijzigd. Als gevolg daarvan wordt deze sneller uitgevoerd. Als u maximaal wilt profiteren van het opnieuw gebruiken van instructies maar waarden moeten worden gewijzigd vóór of na de uitvoering van een instructie, gebruikt u instructieparameters om uw instructie aan te passen. (U geeft instructieparameters op via de associatieve-array-eigenschap SQLStatement.parameters.) Bij het wijzigen van de eigenschap text van de SQLStatement-instantie moet de runtime de instructie opnieuw voorbereiden. Als u de waarden van instructieparameters wijzigt, is dit niet het geval. Zie “Parameters gebruiken in instructies” op pagina 179 voor meer informatie over het gebruik van parameters in instructies. Aangezien het voorbereiden en uitvoeren van een instructie voor een grote belasting van de database-engine kan zorgen, wordt u aangeraden de initiële gegevens vooraf te laden en vervolgens andere instructies op de achtergrond uit te voeren. Laad de gegevens die de toepassing het eerst nodig heeft. Nadat het initiële opstarten van uw toepassing is voltooid, of tijdens een andere periode van inactiviteit binnen de toepassing, voert u andere instructies uit. Als uw toepassing bijvoorbeeld de database helemaal niet nodig heeft om het beginscherm weer te geven, wacht u tot het

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 200 Werken met lokale SQL-databases

beginscherm verschijnt, opent u vervolgens de databaseverbinding, en creëert u ten slotte de SQLStatement-instanties en voert u alle mogelijke instanties uit. Het is echter ook mogelijk dat uw toepassing bij het opstarten onmiddellijk bepaalde gegevens weergeeft, zoals het resultaat van een query. In dat geval voert u de SQLStatement-instantie voor de desbetreffende query uit. Nadat de initiële gegevens zijn geladen en weergegeven, creëert u SQLStatement-instanties voor andere databasebewerkingen en voert u indien mogelijk later andere instructies uit die nodig zijn. Als u een SQLStatement-instantie opnieuw gebruikt, moet uw toepassing een verwijzing naar de SQLStatementinstantie bijhouden nadat deze is voorbereid. Hiervoor definieert u de variabele als een variabele van het type ‘klasse’ en niet van het type ‘functie’. Een goede manier hiervoor is uw toepassing zo te structureren dat een SQL-instructie aan één klasse wordt toegewezen. U kunt ook een groep van instructies die gecombineerd worden uitgevoerd, toewijzen aan één klasse. Wanneer u de SQLStatement-instantie(s) als lidvariabelen van de klasse definieert, blijven ze bestaan zolang de instantie van de klasse waaraan ze zijn toegewezen, in de toepassing bestaat. Als minimale oplossing kunt u gewoon een variabele definiëren die de SQLStatement-instantie buiten een functie bevat zodat de instantie in het geheugen blijft bestaan. Definieer de SQLStatement-instantie bijvoorbeeld als een lidvariabele in een ActionScriptklasse of als een niet-functievariabele in een JavaScript-bestand. Vervolgens kunt u de parameterwaarden van de instructie instellen en de methode execute() van de instructie oproepen wanneer u de query daadwerkelijk wilt uitvoeren.

Meerdere bewerkingen in een transactie groeperen U voert bijvoorbeeld een groot aantal SQL-instructies uit die gegevens toevoegen of wijzigen (instructies van het type INSERT of UPDATE). U kunt een aanzienlijke prestatieverbetering verkrijgen door alle instructies binnen een expliciete transactie uit te voeren. Als u niet expliciet een transactie begint, wordt elke instructie binnen zijn eigen, automatisch gegenereerde transactie uitgevoerd. Nadat elke transactie (elke instructie) is voltooid, schrijft de runtime de resultaatgegevens naar het databasebestand op de schijf. Anderzijds moet u rekening houden met wat er gebeurt als u expliciet een transactie genereert en de instructies in het kader van die transactie uitvoert. De runtime voert alle wijzigingen in het geheugen uit en schrijft ze vervolgens alle tegelijk naar het databasebestand wanneer de transactie wordt bevestigd. Het naar schijf schrijven van gegevens is doorgaans het meest tijdsintensieve deel van de bewerking. Dit betekent dat u de prestaties aanzienlijk kunt verbeteren door de gegevens alle tegelijk naar schijf te schrijven in plaats van één keer per SQL-instructie.

Runtimeverwerking tot het minimum beperken Met behulp van de volgende technieken kunt u onnodige belasting van de database-engine voorkomen en toepassingen sneller maken:

• Geef altijd expliciet database- en tabelnamen op in een instructie. (Gebruik ‘main’ voor de hoofddatabase.) Gebruik bijvoorbeeld SELECT id_werknemer FROM main.werknemers in plaats van SELECT id_werknemer FROM werknemers. Door de databasenaam expliciet op te geven zorgt u dat de runtime niet elke database hoeft te

doorzoeken om de vereiste tabel te vinden. Bovendien kan de runtime niet de verkeerde database kiezen. Neem altijd deze regel in acht, zelfs als een SQLConnection met maar één database is verbonden. De SQLConnection is namelijk op de achtergrond ook verbonden met een tijdelijke database die toegankelijk is via SQL-instructies.

• Geef altijd expliciet kolomnamen op in een instructie van het type SELECT of INSERT. • Verdeel de rijen die worden weergegeven door een instructie van het type SELECT die een groot aantal rijen ophaalt. Zie “SELECT-resultaten in delen ophalen” op pagina 186 voor meer informatie.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 201 Werken met lokale SQL-databases

Wijzig het schema niet Wijzig indien mogelijk het schema (de tabelstructuur) van een database niet meer nadat u gegevens hebt toegevoegd aan de tabellen van de database. In een databasebestand bevinden de tabeldefinities zich doorgaans aan het begin van het bestand. Wanneer u verbinding maakt met een database, worden deze definities door de runtime geladen. Wanneer u gegevens toevoegt aan databasetabellen, worden deze gegevens na de tabeldefinitiegegevens geplaatst. Als u echter schemawijzigingen aanbrengt, zoals het toevoegen van een kolom aan een tabel of het toevoegen van een nieuwe tabel, worden de nieuwe tabeldefinitiegegevens gemengd met de tabelgegevens in het databasebestand. Als niet alle tabeldefinitiegegevens zich aan het begin van het databasebestand bevinden, duurt het langer om verbinding te maken met de database omdat de runtime de tabeldefinitiegegevens op verschillende plaatsen in het bestand moet zoeken. Roep voor het uitvoeren van schemawijzigingen de methode SQLConnection.compact() op nadat de wijzigingen zijn voltooid. Hierdoor wordt het databasebestand opnieuw ingedeeld zodat alle tabeldefinitiegegevens zich aan het begin van het bestand bevinden. Het uitvoeren van de bewerking compact() kan echter lang duren, met name bij grote databasebestanden.

Aanbevolen procedures voor het werken met lokale SQL-databases Hieronder volgt een lijst van suggesties voor technieken die u kunt toepassen om de prestaties, de beveiliging en het onderhoudsgemak van uw toepassingen te verhogen bij het werken met lokale SQL-databases. Zie “Databaseprestaties verbeteren” op pagina 199 voor nog meer technieken voor het verbeteren van uw databasetoepassingen.

Creëer vooraf databaseverbindingen Zelfs als uw toepassing geen instructies uitvoert wanneer deze wordt geladen, maakt u een instantie van een SQLConnection-object en roept u de methode open() of openAsync() van de instantie zo vroeg mogelijk op (bijvoorbeeld onmiddellijk nadat de toepassing is gestart) om vertraging bij het uitvoeren van instructies te voorkomen. Zie “Verbinden met een database” op pagina 176.

Gebruik databaseverbindingen opnieuw Als u tijdens de uitvoering van uw toepassing een bepaalde database benadert, zorgt u voor een verwijzing naar de SQLConnection-instantie en gebruikt u deze altijd opnieuw in de hele toepassing zodat u de verbinding niet elke keer hoeft te sluiten en weer te openen. Zie “Verbinden met een database” op pagina 176.

Gebruik bij voorkeur de asynchrone uitvoeringsmodus Bij het schrijven van code voor het benaderen van gegevens kan het verleidelijk zijn om bewerkingen synchroon in plaats van asynchroon te laten uitvoeren omdat het gebruik van synchrone bewerkingen vaak kortere en minder complexe code vereist. Zoals is beschreven in “Synchrone en asynchrone databasebewerkingen gebruiken” op pagina 194 kunnen synchrone bewerkingen de prestaties echter zo verminderen dat de gebruiker dit merkt, zodat het werken met uw toepassing minder aantrekkelijk wordt. De tijd die nodig is om één bewerking uit te voeren, is afhankelijk van de bewerking en met name van de hoeveelheid gegevens die moet worden verwerkt. Bijvoorbeeld: een SQL-instructie van het type INSERT die maar één rij aan de database toevoegt, heeft minder tijd nodig dan een instructie van het type SELECT die duizenden rijen gegevens moet ophalen. Wanneer u echter de synchrone modus gebruikt om meerdere bewerkingen uit te voeren, worden de bewerkingen doorgaans samengeperst. Zelfs als elke bewerking slechts een korte uitvoeringstijd heeft, blokkeert de toepassing tot alle synchrone bewerkingen zijn voltooid. Hierdoor is de totale uitvoeringstijd van meerdere samengeperste bewerkingen mogelijk lang genoeg om uw toepassing onbruikbaar te maken.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 202 Werken met lokale SQL-databases

Gebruik daarom standaard de asynchrone modus, met name voor bewerkingen met een groot aantal rijen. Er bestaat een techniek om de verwerking van grote resultaatsets van de instructie SELECT te verdelen. Zie hiervoor “SELECTresultaten in delen ophalen” op pagina 186. Deze techniek kan echter alleen in de asynchrone uitvoeringsmodus worden gebruikt. Gebruik synchrone bewerkingen alleen wanneer u bepaalde functies niet kunt uitvoeren met asynchrone programmering, wanneer u de nadelen op het gebied van prestaties voor de gebruikers van uw toepassing in acht hebt genomen en wanneer u uw toepassing hebt getest zodat u weet hoe de prestaties van uw toepassing worden beïnvloed. Het gebruik van de asynchrone uitvoeringsmodus kan het coderen van de toepassing complexer maken. Vergeet echter niet dat u de code maar één hoeft te schrijven maar de gebruikers van uw toepassing deze vele keren moeten gebruiken, traag of snel. In vele gevallen kan een groot aantal SQL-bewerkingen tegelijk in de wachtrij worden geplaatst wanneer u een aparte SQLStatement-instantie voor elke uit te voeren SQL-instructie gebruikt, waardoor asynchrone code op ongeveer dezelfde manier als synchrone code wordt geschreven. Zie “De asynchrone uitvoeringsmodus” op pagina 197 voor meer informatie.

Gebruik aparte SQL-instructies en wijzig de eigenschap ‘text’ van de SQLStatement niet Creëer voor elke SQL-instructie die meer dan één keer in de toepassing wordt uitgevoerd, een aparte SQLStatementinstantie voor elke SQL-instructie. Gebruik die SQLStatement-instantie elke keer dat de overeenkomstige SQLopdracht wordt uitgevoerd. Als u bijvoorbeeld een toepassing schrijft met vier verschillende SQL-bewerkingen die meerdere keren worden uitgevoerd. In dat geval creëert u vier aparte SQLStatement-instanties en roept u de methode execute() van elke instructie op om deze uit te voeren. U kunt ook één SQLStatement-instantie voor alle SQLinstructies gebruiken, waarbij de eigenschap text van de instantie elke keer opnieuw wordt gedefinieerd voordat de instructie wordt uitgevoerd. Deze techniek wordt echter afgeraden. Zie “Gebruik één SQLStatement-instantie per SQL-instructie” op pagina 199 voor meer informatie.

Gebruik instructieparameters Gebruik SQLStatement-parameters en voeg gebruikersinvoer niet samen tot instructietekst. Het gebruik van parameters maakt uw toepassing veiliger omdat het SQL-injectieaanvallen onmogelijk maakt. Hierdoor kunt u objecten gebruiken in query’s (in plaats van alleen literale SQL-waarden). Bovendien worden de instructies efficiënter uitgevoerd omdat ze opnieuw kunnen worden gebruikt zonder dat ze opnieuw hoeven te worden gecompileerd elke keer dat ze worden uitgevoerd. Zie “Parameters gebruiken in instructies” op pagina 179 voor meer informatie.

Gebruik constanten voor kolom- en parameternamen Als u geen itemClass voor een SQLStatement opgeeft, moet u om spelfouten te voorkomen tekenreeksconstanten definiëren die de naam van de kolommen in een tabel bevatten. Gebruik deze constanten in de instructietekst en voor de eigenschapnamen bij het ophalen van waarden van resultaatobjecten. Gebruik ook voor parameternamen constanten.

203

Hoofdstuk 19: Gecodeerde gegevens opslaan De Adobe® AIR™-runtime beschikt over een permanente gecodeerde lokale opslag voor elke AIR-toepassing die op de computer van een gebruiker is geïnstalleerd. Hier kunt u gegevens opslaan en ophalen die op de lokale vaste schijf van de gebruikers zijn opgeslagen in een gecodeerde indeling die niet gemakkelijk kan worden ontcijferd door andere toepassingen of gebruikers. Voor elke AIR-toepassing wordt een afzonderlijke gecodeerde lokale opslag gebruikt en elke AIR-toepassing gebruikt een afzonderlijke gecodeerde lokale opslag voor elke gebruiker. In de gecodeerde lokale opslag kunt u informatie opslaan die moet worden beveiligd, zoals aanmeldingsgegevens voor webservices. AIR maakt in Windows van DPAPI en in Mac OS van KeyChain gebruik om de gecodeerde lokale opslag te koppelen aan elke toepassing en gebruiker. De gecodeerde lokale opslag gebruikt AES-CBC 128-bits codering. Informatie in de gecodeerde lokale opslag is alleen beschikbaar voor de inhoud van een AIR-toepassing in de toepassingsbeveiligingssandbox. Gebruik de statische methoden setItem() en removeItem() van de klasse EncryptedLocalStore om gegevens in de lokale opslag op te slaan en op te halen. De gegevens worden opgeslagen in een hashtabel, waarbij tekenreeksen worden gebruikt als sleutels en de gegevens worden opgeslagen als bytearrays. Met de volgende code wordt bijvoorbeeld een tekenreeks opgeslagen in de gecodeerde lokale opslag: var str:String = "Bob"; var bytes:ByteArray = new ByteArray(); bytes.writeUTFBytes(str); EncryptedLocalStore.setItem("firstName", bytes); var storedValue:ByteArray = EncryptedLocalStore.getItem("firstName"); trace(storedValue.readUTFBytes(storedValue.length)); // "Bob"

De derde parameter van de methode setItem(), de parameter stronglyBound, is optioneel. Wanneer deze parameter op true is ingesteld, is de gecodeerde lokale opslag beter beveiligd doordat het opgeslagen item wordt gebonden aan de digitale handtekening en bits van de opslaande AIR-toepassing en aan de uitgevers-id van de toepassing, wanneer: var str:String = "Bob"; var bytes:ByteArray = new ByteArray(); bytes.writeUTFBytes(str); EncryptedLocalStore.setItem("firstName", bytes, true);

Voor een item dat is opgeslagen terwijl stronglyBound op true is ingesteld, zullen volgende oproepen van getItem() alleen slagen als de oproepende AIR-toepassing identiek is aan de opslaande toepassing (als er geen gegevens in bestanden in de toepassingsmap zijn gewijzigd). Als de oproepende AIR-toepassing niet identiek is aan de opslaande toepassing, genereert de toepassing een uitzonderingsfout wanneer u getItem() oproept voor een sterk gebonden item. Als u uw toepassing bijwerkt, kan deze geen sterk gebonden gegevens lezen die eerder in de gecodeerde lokale opslag zijn geschreven.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 204 Gecodeerde gegevens opslaan

Standaard kan een AIR-toepassing de gecodeerde lokale opslag van een andere toepassing niet lezen. Met de instelling stronglyBound zijn items extra sterk gebonden (aan de gegevens in de toepassingsbits) waardoor wordt voorkomen dat een schadelijke toepassing gegevens in de gecodeerde lokale opslag van uw toepassing kan lezen door de uitgeversid van uw toepassing te kapen. Als u een toepassing bijwerkt voor het gebruik van een ander handtekeningcertificaat (met een migratiehandtekening), heeft de bijgewerkte versie geen toegang tot de items in de oorspronkelijke opslag, zelfs niet als de parameter stronglyBound op false was ingesteld. Zie “Certificaten wijzigen” op pagina 309 voor meer informatie. U kunt een waarde uit de gecodeerde lokale opslag verwijderen met de methode EncryptedLocalStore.removeItem(), zoals in het volgende voorbeeld: EncryptedLocalStore.removeItem("firstName");

U kunt alle gegevens in de gecodeerde lokale opslag wissen door de methode EncryptedLocalStore.reset() op te roepen, zoals in het volgende voorbeeld: EncryptedLocalStore.reset();

Bij het opsporen van fouten in een toepassing in ADL (AIR Debug Launcher) gebruikt de toepassing een andere gecodeerde lokale opslag dan de opslag die wordt gebruikt in de geïnstalleerde versie van de toepassing. De gecodeerde lokale opslag kan langzamer werken als de opgeslagen hoeveelheid gegevens groter is dan 10 MB. Wanneer u een AIR-toepassing verwijdert, worden de gegevens die in de gecodeerde lokale opslag zijn opgeslagen, niet verwijderd. De gegevens van de gecodeerde lokale opslag worden in een submap van de map met toepassingsgegevens van de gebruiker geplaatst; het pad van deze submap is Adobe/AIR/ELS/ gevolgd door de toepassings-id.

205

Hoofdstuk 20: Informatie over de HTMLomgeving Adobe®AIR™ maakt gebruik van WebKit (www.webkit.org), dat ook wordt gebruikt door de webbrowser Safari, om HTML- en JavaScript-inhoud te parseren, in te delen en weer te geven. Het gebruik van de AIR API's in HTML-inhoud is optioneel. U kunt de inhoud van een HTMLLoader-object of HTML-venster geheel in HTML en JavaScript programmeren. De meeste bestaande HTML-pagina's en -toepassingen kunnen normaal gesproken met weinig wijzigingen worden uitgevoerd (mits ze gebruikmaken van HTML-, CSS-, DOM- en JavaScript-functies die compatibel zijn met WebKit). Aangezien AIR-toepassingen rechtstreeks op de desktopcomputer worden uitgevoerd, met volledige toegang tot het bestandssysteem, is het beveiligingsmodel voor HTML-inhoud strenger dan het beveiligingsmodel van een typische webbrowser. In AIR wordt alleen inhoud die wordt geladen uit de installatiemap van de toepassing geplaatst in de toepassingssandbox. De toepassingssandbox heeft het hoogste machtigingsniveau en biedt toegang tot de AIR API's. AIR plaatst andere inhoud in geïsoleerde sandboxen op basis van de locatie waar deze inhoud vandaan komt. Bestanden die zijn geladen uit het bestandssysteem, gaan naar een lokale sandbox. Bestanden die zijn geladen van het netwerk met behulp van het protocol http: of https:, gaan naar een sandbox op basis van het domein van de externe server. Inhoud in deze niet-toepassingssandboxen krijgt geen toegang tot AIR API's en wordt uitgevoerd op dezelfde manier als bij een normale webbrowser. AIR maakt gebruik van WebKit (www.webkit.org), dat ook wordt gebruikt door de webbrowser Safari, om HTML- en JavaScript-inhoud te parseren, in te delen en weer te geven. De ingebouwde hostklassen en -objecten van AIR bieden een API voor functies die traditioneel worden gekoppeld aan desktoptoepassingen. Het gaat hierbij bijvoorbeeld over het lezen en schrijven van bestanden en het beheer van vensters. Adobe AIR neemt ook de API's over van Adobe® Flash® Player. Het gaat hierbij bijvoorbeeld over functies als geluid en binaire sockets. HTML-inhoud in AIR geeft geen SWF- of PDF-inhoud weer wanneer alfa-, schaal- of transparantie-instellingen worden toegepast. Meer informatie kunt u vinden in Belangrijke opmerkingen voor het laden van SWF- of PDFinhoud in een HTML-pagina en “Venstertransparantie” op pagina 62.

Overzicht van de HTML-omgeving Adobe AIR biedt een volledige browserachtige JavaScript-omgeving met een HTML-renderer, documentobjectmodel en JavaScript-interpreter. De JavaScript-omgeving wordt vertegenwoordigd door de AIR-klasse HTMLLoader. In HTML-vensters bevat een HTMLLoader-object alle HTML-inhoud. Dit object bevindt zich op zijn beurt weer in een NativeWindow-object. In SWF-inhoud kan de klasse HTMLLoader, die een uitbreiding vormt van de klasse Sprite, worden toegevoegd aan de weergavelijst van een stage, net als ieder ander weergaveobject. De ActionScript™eigenschappen van de klasse worden beschreven in “Scripts schrijven voor de HTML-container” op pagina 246 en ook in Flex 3 ActionScript Language Reference.

Informatie over de JavaScript-omgeving en de relatie met AIR In het volgende diagram wordt de relatie geïllustreerd tussen de JavaScript-omgeving en de AIR-runtimeomgeving. Er wordt maar één native venster weergegeven. Een AIR-toepassing kan echter meerdere vensters bevatten. (En een venster kan meerdere HTMLLoader-objecten bevatten.)

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 206 Informatie over de HTML-omgeving

AIR-runtime-omgeving

NativeWindow

HTMLLoader venster JavaScriptomgeving venster

venster

hoofdtekst

htmlLoader

kop

native4Window

runtime h1

div

tabel

p

De JavaScript-omgeving heeft zijn eigen Document- en Window-objecten. JavaScript-code kan interageren met de AIR-runtimeomgeving via de eigenschappen runtime, nativeWindow en htmlLoader. ActionScript-code kan interageren met de JavaScript-omgeving via de eigenschap window van een HTMLLoader-object, dat een referentie vormt naar het JavaScript Window-object. Verder kunnen zowel ActionScript- als JavaScript-objecten luisteren naar gebeurtenissen die zijn verzonden door zowel AIR- als JavaScript-objecten.

De eigenschap runtime geeft toegang tot AIR API-klassen zodat u nieuwe AIR-objecten en ook toegangsklasseleden (statische leden) kunt maken. Als u een AIR API wilt openen, voegt u de naam van de klasse (met pakket) toe aan de eigenschap runtime. Als u bijvoorbeeld een File-object wilt maken, gebruikt u de volgende opdracht: var file = new window.runtime.filesystem.File();

Opmerking: De AIR SDK bevat een JavaScript-bestand, AIRAliases.js, waarin aanvullende handige aliassen voor de meestgebruikte AIR-klassen worden gedefinieerd. Als u dit bestand importeert, kunt u de korte vorm air.Class gebruiken in plaats van window.runtime.package.Class. U kunt bijvoorbeeld het File-object maken met new air.File(). Het NativeWindow-object bevat eigenschappen voor het beheer van het bureaubladvenster. Vanuit een HTMLpagina kunt u toegang krijgen tot het omvattende NativeWindow-object met behulp van de eigenschap window.nativeWindow. Het HTMLLoader-object bevat eigenschappen, methoden en gebeurtenissen voor het beheer van de manier waarop inhoud wordt geladen en weergegeven. Vanuit een HTML-pagina kunt u toegang krijgen tot het bovenliggende HTMLLoader-object met behulp van de eigenschap window.htmlLoader.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 207 Informatie over de HTML-omgeving

Belangrijk: Alleen pagina's die zijn geïnstalleerd als onderdeel van een toepassing, hebben de eigenschap htmlLoader, nativeWindow of runtime. Ze hebben deze eigenschappen alleen wanneer ze zijn geladen als document van het hoogste niveau. Deze eigenschappen worden niet toegevoegd wanneer een document wordt geladen in een frame of iframe. (Een onderliggend document kan toegang krijgen tot deze eigenschappen van het bovenliggende document, zolang het onderliggende document zich bevindt in dezelfde beveiligingssandbox. Een document dat bijvoorbeeld is geladen in een frame, kan toegang krijgen tot de eigenschap runtime van het bovenliggende document met behulp van parent.runtime.)

Informatie over beveiliging AIR voert alle code binnen een beveiligingssandbox uit op basis van het brondomein. Toepassingsinhoud, die beperkt is tot inhoud die is geladen uit de installatiemap van de toepassing, wordt geplaatst in de toepassingssandbox. Toegang tot de runtimeomgeving en de AIR API's is alleen beschikbaar voor HTML en JavaScript die worden uitgevoerd binnen deze sandbox. Tegelijkertijd wordt de meeste dynamische evaluatie en uitvoering van JavaScript geblokkeerd in de toepassingssandbox nadat alle handlers voor de paginagebeurtenis load zijn geretourneerd. U kunt een toepassingspagina toewijzen in een niet-toepassingssandbox door de pagina te laden in een frame of iframe en de AIR-specifieke kenmerken sandboxRoot en documentRoot van het frame in te stellen. Door de waarde sandboxRoot in te stellen op een werkelijk extern domein, kunt u de sandboxinhoud inschakelen zodat u inhoud in dat domein kunt cross-scripten. Het toewijzen van pagina's op deze manier kan nuttig zijn bij het laden en scripten van externe inhoud, bijvoorbeeld in een mash-up-toepassing. Een andere manier om toepassings- en niet-toepassingsinhoud in staat te stellen om elkaar te cross-scripten, en de enige manier om niet-toepassingsinhoud toegang te geven tot AIR API's, is het maken van een sandboxbridge. Een bovenliggende-onderliggende bridge maakt het mogelijk voor inhoud in een onderliggend frame, iframe of venster om toegang te krijgen tot speciaal aangewezen methoden en eigenschappen die zijn gedefinieerd in de toepassingssandbox. Een onderliggende-bovenliggende bridge daarentegen maakt het toepassingsinhoud mogelijk om toegang te krijgen tot bepaalde methoden en eigenschappen die zijn gedefinieerd in de sandbox van de onderliggende. Sandboxbridges worden gecreëerd door de eigenschappen parentSandboxBridge en childSandboxBridge van het Window-object in te stellen. Zie “Beveiliging in HTML” op pagina 31 en “Frame- en iframe-elementen in HTML” op pagina 215 voor meer informatie.

Informatie over invoegtoepassingen en ingesloten objecten AIR ondersteunt de invoegtoepassing Adobe ® Acrobat®. Gebruikers moeten beschikken over Acrobat of Adobe® Reader® 8.1 (of hoger) om PDF-inhoud te kunnen weergeven. Het HTMLLoader-object biedt een eigenschap waarmee kan worden gecontroleerd of het systeem van een gebruiker PDF kan weergeven. SWF-bestandsinhoud kan ook worden weergegeven binnen de HTML-omgeving. Deze functie is echter ingebouwd in AIR en maakt geen gebruik van een externe invoegtoepassing. Er worden geen andere Webkit-invoegtoepassingen ondersteund in AIR.

Zie ook “Beveiliging in HTML” op pagina 31 “Sandboxen in HTML” op pagina 208 “Frame- en iframe-elementen in HTML” op pagina 215 “JavaScript-object Window” op pagina 214 “XMLHttpRequest-objecten” op pagina 209 “PDF-inhoud toevoegen” op pagina 260

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 208 Informatie over de HTML-omgeving

AIR- en Webkit-extensies Adobe AIR maakt gebruik van de open source Webkit-engine, die ook wordt gebruikt in de webbrowser Safari. AIR voegt verschillende extensies toe waarmee toegang tot de runtimeklassen en -objecten mogelijk is. Deze extensies hebben ook een functie bij de beveiliging. Verder voegt Webkit zelf functies toe die niet zijn opgenomen in de W3Cstandaarden voor HTML, CSS en JavaScript. Alleen de AIR-toevoegingen en de belangrijkste Webkit-extensies worden hier behandeld. Documentatie over nietstandaard HTML, CSS en JavaScript vindt u in www.webkit.org en developer.apple.com. Informatie over standaarden vindt u op de W3C-website. Mozilla biedt ook een waardevolle algemene referentie over HTML-, CSS- en DOMonderwerpen (de Webkit-engine is niet identiek aan de Mozilla-engine). Opmerking: AIR ondersteunt niet de volgende standaard en uitgebreide WebKit-functies: de JavaScript Window objectmethode print(), invoegtoepassingen, behalve Acrobat of Adobe Reader 8.1+, SVG (Scalable Vector Graphics) en de CSS-eigenschap opacity.

JavaScript in AIR AIR brengt een aantal wijzigingen aan in het normale gedrag van veelgebruikte JavaScript-objecten. Veel van deze wijzigingen worden aangebracht om het gemakkelijker te maken veilige toepassingen in AIR te schrijven. Deze verschillen in gedrag betekenen echter ook dat bepaalde veelgebruikte JavaScript-coderingspatronen en bestaande webtoepassingen die gebruikmaken van die patronen, niet altijd zoals verwacht zullen worden uitgevoerd in AIR. Zie “JavaScript-beveiligingsfouten voorkomen” op pagina 222 voor meer informatie over het corrigeren van dit soort problemen.

Sandboxen in HTML AIR plaatst inhoud in geïsoleerde sandboxen afhankelijk van de oorsprong van de inhoud. De sandboxregels zijn consistent met het zelfde-oorsprongbeleid dat wordt geïmplementeerd door de meeste webbrowsers. Ze zijn ook consistent met de regels voor sandboxen die worden geïmplementeerd door Adobe Flash Player. Verder biedt AIR het nieuwe sandboxtype toepassing, waarmee toepassingsinhoud kan worden opgeslagen en beveiligd. Zie “Sandboxen” op pagina 28 voor meer informatie over de typen sandboxen die u kunt tegenkomen bij de ontwikkeling van AIRtoepassingen. Toegang tot de runtimeomgeving en de AIR API's is alleen beschikbaar voor HTML en JavaScript die worden uitgevoerd binnen de toepassingssandbox. Tegelijkertijd wordt dynamische evaluatie en uitvoering van de verschillende vormen van JavaScript uit veiligheidsoverwegingen voor een groot deel beperkt binnen de toepassingssandbox. Deze beperkingen gelden altijd, ongeacht of de toepassing rechtstreeks informatie van een server laadt. (Zelfs bestandsinhoud, geplakte tekenreeksen en gegevens die rechtstreeks door de gebruiker worden ingevoerd, kunnen onbetrouwbaar zijn.) De oorsprong van de inhoud in een pagina bepaalt de sandbox waaraan deze wordt toegewezen. Alleen inhoud die is geladen vanuit de toepassingsmap (de installatiemap waarnaar wordt verwezen door het URL-schema app:) wordt in de toepassingssandbox geplaatst. Inhoud die wordt geladen vanuit het bestandssysteem, wordt in de lokaal-metbestandssysteem of lokaal-vertrouwde sandbox geplaatst, waarmee toegang tot en interactie met het lokale bestandssysteem mogelijk is, maar niet met externe inhoud. Inhoud die wordt geladen vanaf het netwerk, wordt in een externe sandbox geplaatst die correspondeert met het brondomein.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 209 Informatie over de HTML-omgeving

Als een toepassingspagina toestemming moet hebben om desgewenst te interageren met inhoud in een externe sandbox, kan die pagina worden toegewezen aan hetzelfde domein als de externe inhoud. Als u bijvoorbeeld een toepassing schrijft waarin kaartgegevens uit een internetservice worden weergegeven, kan de pagina van deze toepassing waarin inhoud van de service wordt geladen en weergegeven, worden toegewezen aan het servicedomein. De kenmerken voor het toewijzen van pagina's aan externe sandboxen en domeinen zijn nieuwe kenmerken die worden toegevoegd aan de frame- en iframe-elementen in HTML. Als u inhoud in een niet-toepassingssandbox wilt toestaan om veilig AIR-functies te gebruiken, kunt u een bovenliggende sandboxbridge instellen. Als u toepassingsinhoud wilt toestaan om veilig methoden en toegangseigenschappen van inhoud in andere sandboxen te benaderen, kunt u een onderliggende sandboxbridge instellen. Veilig betekent hier dat externe inhoud niet per ongeluk verwijzingen kan ophalen naar objecten, eigenschappen of methoden die niet expliciet beschikbaar zijn gemaakt. Alleen eenvoudige gegevenstypen, functies en anonieme objecten kunnen via de bridge worden doorgegeven. U moet echter nog steeds voorkomen dat potentieel gevaarlijke functies expliciet beschikbaar worden gemaakt. Als u bijvoorbeeld een interface beschikbaar hebt gemaakt waarmee externe inhoud bestanden op iedere willekeurige locatie in het systeem van een gebruiker kan lezen en schrijven, biedt u externe inhoud mogelijk kans om uw gebruikers grote schade te berokkenen.

De JavaScript-functie eval() Het gebruik van de functie eval() is beperkt binnen de toepassingssandbox als een pagina eenmaal is geladen. Sommige vormen van gebruik zijn toegestaan, zodat gegevens met JSON-indeling veilig kunnen worden geparseerd. Een evaluatie die uitvoerbare instructies als gevolg heeft, resulteert echter altijd in een fout. “Codebeperkingen voor de inhoud van verschillende sandboxen” op pagina 33 beschrijft het toegestane gebruik van de functie eval().

Functieconstructors In de toepassingssandbox kunnen functieconstructors worden gebruikt voordat een pagina geheel is geladen. Nadat alle handlers voor de paginagebeurtenis load zijn voltooid, kunnen geen nieuwe functies meer worden gemaakt.

Externe scripts laden HTML-pagina's in de toepassingssandbox kunnen geen scripttags gebruiken om JavaScript-bestanden te laden van buiten de toepassingsmap. Als een pagina in uw toepassing een script van buiten de toepassingsmap moet laden, moet die pagina worden toegewezen aan een niet-toepassingssandbox.

XMLHttpRequest-objecten AIR is voorzien van een XHR-object (XMLHttpRequest), waarmee toepassingen gegevens kunnen aanvragen. In het volgende voorbeeld ziet u een eenvoudige gegevensaanvraag: 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);

In tegenstelling tot een browser is het bij AIR mogelijk dat inhoud die wordt uitgevoerd in de toepassingssandbox, gegevens uit elk willekeurig domein aanvraagt. Het resultaat van een XHR die een JSON-tekenreeks bevat, kan worden geëvalueerd in gegevensobjecten, behalve als het resultaat ook uitvoerbare code bevat. Als het XHR-resultaat ook uitvoerbare instructies bevat, treedt er een fout op en mislukt de evaluatiepoging.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 210 Informatie over de HTML-omgeving

Om te voorkomen dat code uit externe bronnen per ongeluk wordt ingebracht, retourneren synchrone XHR's een leeg resultaat als ze zijn gemaakt voordat een pagina geheel is geladen. Asynchrone XHR's worden altijd geretourneerd nadat een pagina is geladen. AIR blokkeert standaard domeinoverschrijdende XMLHttpRequests in niet-toepassingssandboxen. Een bovenliggend venster in de toepassingssandbox kan ervoor kiezen domeinoverschrijdende aanvragen in een onderliggend frame dat inhoud in een niet-toepassingssandbox bevat, toe te staan door het kenmerk allowCrossDomainXHR, dat wordt toegevoegd door AIR, in te stellen op true in het omvattende frame- of iframe-element: <iframe id="mashup" src="http://www.example.com/map.html" allowCrossDomainXHR="true"

Opmerking: Desgewenst kan de AIR-klasse URLStream ook worden gebruikt om gegevens te downloaden. Als u een XMLHttpRequest naar een externe server stuurt vanuit een frame of iframe dat toepassingsinhoud bevat die is toegewezen aan een externe sandbox, moet u ervoor zorgen dat de toewijzende URL het serveradres dat in de XHR wordt gebruikt, niet maskeert. Bekijk bijvoorbeeld de volgende iframe-definitie, die toepassingsinhoud toewijst in een externe sandbox voor het domein example.com: <iframe id="mashup" src="http://www.example.com/map.html" documentRoot="app:/sandbox/" sandboxRoot="http://www.example.com/" allowCrossDomainXHR="true"

Omdat het kenmerk sandboxRoot de basis-URL van het adres www.example.com opnieuw toewijst, worden alle aanvragen geladen vanuit de toepassingsmap en niet vanaf de externe server. Aanvragen worden altijd opnieuw toegewezen, ongeacht of ze afkomstig zijn van paginanavigatie of een XMLHttpRequest. Om te voorkomen dat gegevensaanvragen naar de externe server per ongeluk worden geblokkeerd, wijst u sandboxRoot toe aan een submap van de externe URL en niet aan de hoofdmap. Die map hoeft niet echt te bestaan.

Als u bijvoorbeeld wilt toestaan dat aanvragen naar www.example.com gegevens laden vanaf de externe server en niet uit de toepassingsmap, verandert u het vorige iframe-element in de volgende: <iframe id="mashup" src="http://www.example.com/map.html" documentRoot="app:/sandbox/" sandboxRoot="http://www.example.com/air/" allowCrossDomainXHR="true"

In dit geval wordt alleen de inhoud van de submap air lokaal geladen. Zie “Frame- en iframe-elementen in HTML” op pagina 215 en “Beveiliging in HTML” op pagina 31 voor meer informatie over de toewijzing van sandboxen.

Canvas-objecten Het Canvas-object definieert een API voor het tekenen van geometrische vormen zoals lijnen, bogen, ellipsen en veelhoeken. Als u de API voor Canvas wilt gebruiken, voegt u eerst een Canvas-element toe aan het document en tekent u daar vervolgens in met behulp van de JavaScript-API voor Canvas. In de meeste andere opzichten gedraagt het Canvas-object zich als een afbeelding. In het volgende voorbeeld ziet u hoe u een driehoek tekent met behulp van een Canvas-object:

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 211 Informatie over de HTML-omgeving

<script> var canvas = document.getElementById("triangleCanvas"); var context = canvas.getContext("2d"); context.lineWidth = 3; context.strokeStyle = "#457232"; context.beginPath(); context.moveTo(5,5); context.lineTo(35,5); context.lineTo(20,35); context.lineTo(5,5); context.lineTo(6,5); context.stroke();

Zie de Safari JavaScript Reference van Apple voor meer informatie over de API voor Canvas. Het Webkit-project is onlangs begonnen met het aanpassen van de API voor Canvas ten einde deze te standaardiseren volgens de HTML 5 Working Draft die is voorgesteld door WHATWG (Web Hypertext Application Technology Working Group) en W3C. Als gevolg daarvan kan een deel van de documentatie in de Safari JavaScript Reference inconsistent zijn met de Canvas-versie die wordt gepresenteerd in AIR.

Cookies In AIR-toepassingen kan alleen inhoud in externe sandboxen (inhoud die is geladen vanaf bronnen van het type http: en https:) gebruikmaken van cookies (de eigenschap document.cookie). In de toepassingssandbox bieden AIR API's andere manieren om permanente gegevens op te slaan (zoals de klassen EncryptedLocalStore en FileStream).

Clipboard-objecten De WebKit-API voor Clipboard wordt aangestuurd door de volgende gebeurtenissen: copy, cut en paste. Het gebeurtenisobject dat bij deze gebeurtenissen wordt doorgegeven, geeft via de eigenschap clipboardData toegang tot het klembord. Gebruik de volgende methoden van het object clipboardData om klembordgegevens te lezen of te schrijven: Methode

Beschrijving

clearData(mimeType)

Hiermee wist u de klembordgegevens. Stel de parameter mimeType in op het MIME-type van de gegevens die u wilt wissen.

getData(mimeType)

Hiermee haalt u de klembordgegevens op. Deze methode kan alleen worden opgeroepen in een handler voor de gebeurtenis paste. Stel de parameter mimeType in op het MIME-type van de gegevens die u wilt retourneren.

setData(mimeType, data)

Hiermee kopieert u gegevens naar het klembord. Stel de parameter mimeType in op het MIME-type van de gegevens.

JavaScript-code buiten de toepassingssandbox kan alleen via deze gebeurtenissen toegang krijgen tot het klembord. Inhoud in de toepassingssandbox kan echter rechtstreeks toegang krijgen tot het systeemklembord via de AIR-klasse Clipboard. U kunt bijvoorbeeld de volgende opdracht gebruiken om gegevens over tekstopmaak op het klembord te krijgen: var clipping = air.Clipboard.generalClipboard.getData("text/plain", air.ClipboardTransferMode.ORIGINAL_ONLY);

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 212 Informatie over de HTML-omgeving

De volgende MIME-typen zijn geldig voor gegevens: MIME-type

Waarde

Tekst

"text/plain"

HTML

"text/html"

URL

"text/uri-list"

Bitmap

"image/x-vnd.adobe.air.bitmap"

Bestandenlijst

"application/x-vnd.adobe.air.file-list"

Belangrijk: Alleen inhoud in de toepassingssandbox kan toegang krijgen tot bestandsgegevens die aanwezig zijn op het klembord. Als niet-toepassingsinhoud probeert toegang te krijgen tot een bestandsobject vanaf het klembord, wordt een beveiligingsfout veroorzaakt. Zie “kopiëren en plakken” op pagina 147 en Using the Pasteboard from JavaScript (Apple Developer Center) voor meer informatie over het gebruik van het klembord.

Slepen en neerzetten: Het slepen en neerzetten in en uit HTML produceert de volgende DOM-gebeurtenissen: dragstart, drag, dragend, dragenter, dragover, dragleave en drop. Het gebeurtenisobject dat bij deze gebeurtenissen wordt doorgegeven, geeft via de eigenschap dataTransfer toegang tot de gesleepte gegevens. De eigenschap dataTransfer verwijst naar een object dat dezelfde methoden biedt als het clipboardData-object dat is gekoppeld aan een gebeurtenis van het type clipboard. U kunt bijvoorbeeld de volgende functie gebruiken om tekstopmaakgegevens van de gebeurtenis drop te krijgen: function onDrop(dragEvent){ return dragEvent.dataTransfer.getData("text/plain", air.ClipboardTransferMode.ORIGINAL_ONLY); }

Het dataTransfer-object heeft de volgende belangrijke leden: Lid

Beschrijving

clearData(mimeType)

Hiermee wist u de gegevens. Stel de parameter mimeType in op het MIME-type van de gegevensrepresentatie die u wilt wissen.

getData(mimeType)

Hiermee haalt u de gesleepte gegevens op. Deze methode kan alleen worden opgeroepen in een handler voor de gebeurtenis drop. Stel de parameter mimeType in op het MIME-type van de gegevens die u wilt ophalen.

setData(mimeType, data)

Hiermee stelt u de gegevens in die moeten worden gesleept. Stel de parameter mimeType in op het MIMEtype van de gegevens.

types

Een array van tekenreeksen die de MIME-typen bevat van alle gegevensrepresentaties die nu beschikbaar zijn in het dataTransfer-object.

effectsAllowed

Hiermee geeft u aan of de gesleepte gegevens kunnen worden gekopieerd, verplaatst, gekoppeld of een combinatie daarvan. Stel de eigenschap effectsAllowed in de handler voor de gebeurtenis dragstart in.

dropEffect

Hiermee geeft u aan welke van de toegestane neerzeteffecten (drop) worden ondersteund door een sleepdoel (drag). Stel de eigenschap dropEffect in de handler voor de gebeurtenis dragEnter in. Tijdens het slepen verandert de cursor van vorm. Deze geeft aan wat voor effect er zou optreden als de gebruiker de muis loslaat. Als er geen dropEffect is opgegeven, wordt een eigenschapseffect uit effectsAllowed gekozen. Het kopieereffect (copy) heeft prioriteit over het verplaatsingseffect (move), en dat heeft weer prioriteit over het koppelingseffect (link). De gebruiker kan de standaardprioriteit wijzigen met behulp van het toetsenbord.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 213 Informatie over de HTML-omgeving

Zie “Slepen en neerzetten” op pagina 131 en Using the Drag-and-Drop from JavaScript (Apple Developer Center) voor meer informatie over het toevoegen van ondersteuning voor slepen en neerzetten aan een AIR-toepassing.

De eigenschappen innerHTML en outerHTML AIR stelt beveiligingsbeperkingen in voor het gebruik van de eigenschappen innerHTML en outerHTML voor het uitvoeren van inhoud in de toepassingssandbox. Voordat de paginagebeurtenis load optreedt en terwijl eventuele gebeurtenishandlers voor load worden uitgevoerd, gelden er geen beperkingen voor het gebruik van de eigenschappen innerHTML en outerHTML. Als de pagina echter is geladen, kunt u de eigenschap innerHTML of outerHTML alleen gebruiken om statische inhoud toe te voegen aan het document. Eventuele opdrachten die zich bevinden in de tekenreeks die is toegewezen aan innerHTML of outerHTML en die worden geëvalueerd naar uitvoerbare code, worden genegeerd. Als u bijvoorbeeld een kenmerk om een gebeurtenis terug te roepen (callback) opneemt in een elementdefinitie, wordt de gebeurtenislistener niet toegevoegd. Op dezelfde manier worden ingesloten tags van het type <script> niet geëvalueerd. Zie “Beveiliging in HTML” op pagina 31 voor meer informatie.

De methoden Document.write() en Document.writeln() Het gebruik van de methoden write()en writeln() is niet beperkt in de toepassingssandbox vóór de paginagebeurtenis load. Als de pagina echter is geladen, wordt bij het oproepen van een van deze methoden de pagina niet gewist en wordt er ook geen nieuwe pagina gemaakt. In een niet-toepassingssandbox wordt, net zoals bij de meeste webbrowsers, door het oproepen van document.write() of writeln() nadat een pagina geheel is geladen, de huidige pagina gewist en wordt een nieuwe lege pagina geopend.

De eigenschap Document.designMode Hiermee stelt u de eigenschap document.designMode in op de waarde on als u alle elementen in het document bewerkbaar wilt maken. Met de ingebouwde editor kunt u tekst bewerken, kopiëren, plakken, slepen en neerzetten. Het instellen van designMode op on is equivalent met het instellen van de eigenschap contentEditable van het element body op true. U kunt de eigenschap contentEditable voor de meeste HTML-elementen gebruiken om te definiëren welke secties van een document kunnen worden bewerkt. Zie “Het HTML-kenmerk contentEditable” op pagina 218 voor meer informatie.

unload-gebeurtenissen (voor body- en frameset-objecten) In de tag frameset of body van het bovenste niveau van een venster (inclusief het hoofdvenster van de toepassing), mag u de gebeurtenis unload niet gebruiken om te reageren op het venster dat of de toepassing die wordt gesloten. In plaats daarvan gebruikt u de gebeurtenis exiting van het NativeApplication-object (om te bepalen wanneer een toepassing wordt gesloten). U kunt ook de gebeurtenis closing van het NativeApplication-object gebruiken (om te bepalen wanneer een toepassing wordt gesloten). De volgende JavaScript-code geeft bijvoorbeeld het bericht "Goodbye" weer wanneer de gebruiker de toepassing sluit: var app = air.NativeApplication.nativeApplication; app.addEventListener(air.Event.EXITING, closeHandler); function closeHandler(event) { alert("Goodbye."); }

Scripts kunnen echter wel succesvol reageren op de gebeurtenis unload die wordt veroorzaakt door navigatie van een frame, iframe of vensterinhoud van het bovenste niveau. Opmerking: In een volgende versie van Adobe AIR worden deze beperkingen mogelijk verwijderd.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 214 Informatie over de HTML-omgeving

JavaScript-object Window Het Window-object blijft het globale object binnen de JavaScript-uitvoeringscontext. In de toepassingssandbox voegt AIR nieuwe eigenschappen toe aan het JavaScript-object Window ten einde toegang te geven tot de ingebouwde AIRklassen en belangrijke hostobjecten. Verder vertonen bepaalde methoden en eigenschappen binnen de toepassingssandbox ander gedrag dan daarbuiten. De eigenschap Window.runtime De eigenschap runtime stelt u in staat om de ingebouwde runtimeklassen te

instantiëren en te gebruiken vanuit de toepassingssandbox. Deze klassen omvatten de AIR- en Flash Player-API's (maar bijvoorbeeld niet het Flex-framework). Met de volgende opdracht maakt u bijvoorbeeld een AIRbestandsobject: var preferencesFile = new window.runtime.flash.filesystem.File();

Het bestand AIRAliases.js, dat zich bevindt in de AIR SDK, bevat aliasdefinities waarmee u dergelijke verwijzingen kunt verkorten. Als AIRAliases.js bijvoorbeeld in een pagina wordt geïmporteerd, kan een File-object worden gemaakt met de volgende opdracht: var preferencesFile = new air.File();

De eigenschap window.runtime is alleen gedefinieerd voor inhoud binnen de toepassingssandbox en alleen voor het bovenliggende document van een pagina met frames of iframes. Zie “Het bestand AIRAliases.js gebruiken” op pagina 227. De eigenschap Window.nativeWindow De eigenschap nativeWindow biedt een verwijzing naar het onderliggende

native Window-object. Met deze eigenschap kunt u vensterfuncties en eigenschappen zoals schermpositie, grootte en zichtbaarheid in een script opnemen. Ook kunt u venstergebeurtenissen zoals sluiten, grootte wijzigen en verplaatsen hiermee verwerken. Met de volgende opdracht sluit u bijvoorbeeld het venster: window.nativeWindow.close();

Opmerking: De functies voor vensterbesturing die worden geboden door het NativeWindow-object, overlappen de functies die worden geboden door het JavaScript-object Window. In dergelijke gevallen kunt u de methode gebruiken die u het handigst vindt. De eigenschap window.nativeWindow is alleen gedefinieerd voor inhoud binnen de toepassingssandbox en alleen voor het bovenliggende document van een pagina met frames of iframes. De eigenschap Window.htmlLoader De eigenschap htmlLoader biedt een referentie voor het AIR-object

HTMLLoader dat de HTML-inhoud bevat. Met deze eigenschap kunt u het uiterlijk en het gedrag van de HTMLomgeving in een script opnemen. U kunt bijvoorbeeld de eigenschap htmlLoader.paintsDefaultBackground gebruiken om te bepalen of het besturingselement een standaard witte achtergrond gebruikt: window.htmlLoader.paintsDefaultBackground = false;

Opmerking: Het HTMLLoader-object zelf heeft een eigenschap window die verwijst naar het JavaScript-object Window van de HTML-inhoud die het bevat. U kunt deze eigenschap gebruiken om toegang te krijgen tot de JavaScript-omgeving via een verwijzing naar de bevattende HTMLLoader. De eigenschap window.htmlLoader is alleen gedefinieerd voor inhoud binnen de toepassingssandbox en alleen voor het bovenliggende document van een pagina met frames of iframes. De eigenschappen Window.parentSandboxBridge en Window.childSandboxBridge Met de eigenschappen parentSandboxBridge en childSandboxBridge kunt u een interface definiëren tussen een bovenliggend en een onderliggend frame. Zie “Cross-scripting van inhoud in verschillende beveiligingssandboxen” op pagina 235 voor meer informatie.

De functies Window.setTimeout() en Window.setInterval() AIR past beveiligingsbeperkingen toe op het gebruik van

de functies setTimeout() en setInterval() binnen de toepassingssandbox. U kunt de code die moet worden

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 215 Informatie over de HTML-omgeving

uitgevoerd, niet definiëren als tekenreeks bij het oproepen van setTimeout() of setInterval(). U moet hiervoor een functieverwijzing gebruiken. Zie “setTimeout() en setInterval()” op pagina 225 voor meer informatie. De functie Window.open() Wanneer de methode open() wordt opgeroepen door code die wordt uitgevoerd in een niet-toepassingssandbox, wordt er als gevolg van gebruikersinteractie (bijvoorbeeld een muisklik of het indrukken van een toets) alleen een venster geopend. Verder staat de toepassingstitel vóór de venstertitel (om te verhinderen dat vensters die worden geopend door externe inhoud, zich voordoen als vensters die worden geopend door de toepassing). Zie “Beperkingen betreffende het oproepen van de JavaScript-methode window.open()” op pagina 36 voor meer informatie.

Het object air.NativeApplication Het NativeApplication-object biedt informatie over de toepassingsstatus, verzendt verschillende belangrijke gebeurtenissen op toepassingsniveau en biedt nuttige functies voor het beheer van het gedrag van de toepassing. Er wordt automatisch één instantie van het NativeApplication-object gemaakt. Deze kan worden benaderd via de door de klasse gedefinieerde eigenschap NativeApplication.nativeApplication. Om vanuit JavaScript-code toegang te krijgen tot het object, kunt u het volgende gebruiken: var app = window.runtime.flash.desktop.NativeApplication.nativeApplication;

Als het script AIRAliases.js is geïmporteerd, kunt u ook de kortere vorm gebruiken: var app = air.NativeApplication.nativeApplication;

U kunt het NativeApplication-object alleen benaderen vanuit de toepassingssandbox. Interactie met het besturingssysteem: “Werken met runtime- en besturingssysteeminformatie” op pagina 284 beschrijft het NativeApplication-object in detail.

Het JavaScript URL-schema Uitvoering van code die is gedefinieerd in een JavaScript URL-schema (zoals in href="javascript:alert('Test')"), wordt geblokkeerd binnen de toepassingssandbox. Er treedt geen fout op.

Extensies voor HTML AIR en WebKit definiëren een aantal niet-standaard HTML-elementen en -kenmerken, zoals: “Frame- en iframe-elementen in HTML” op pagina 215 “Het HTML-element Canvas” op pagina 217 “Gebeurtenishandlers voor HTML-elementen” op pagina 218

Frame- en iframe-elementen in HTML AIR voegt nieuwe kenmerken toe aan de frame- en iframe-elementen van inhoud in de toepassingssandbox: Het kenmerk sandboxRoot Het kenmerk sandboxRoot geeft een alternatief, niet-toepassingsbrondomein op voor het

bestand dat wordt opgegeven door het framekenmerk src. Het bestand wordt geladen in de niet-toepassingssandbox die correspondeert met het opgegeven domein. Inhoud in het bestand en inhoud die wordt geladen van het opgegeven domein, kan onderling cross-scripten. Belangrijk: Als u de waarde van sandboxRoot instelt op de basis-URL van het domein, worden alle aanvragen voor inhoud van dat domein geladen uit de toepassingsmap en niet vanaf de externe server (of die aanvraag nu resulteert uit paginanavigatie, uit een XMLHttpRequest of uit een andere manier om inhoud te laden).

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 216 Informatie over de HTML-omgeving

Het kenmerk documentRoot Het kenmerk documentRoot geeft de lokale map op waaruit URL's moeten worden

geladen die worden omgezet in bestanden in de locatie die wordt opgegeven door sandboxRoot. Bij het omzetten van URL's, of dit nu gebeurt bij het framekenmerk src dan wel in inhoud die in het frame wordt geladen, wordt het deel van de URL dat overeenkomt met de waarde die wordt opgegeven in sandboxRoot, vervangen door de waarde die wordt opgegeven in documentRoot. Bij de volgende frametag geldt dus: <iframe

src="http://www.example.com/air/child.html" documentRoot="app:/sandbox/" sandboxRoot="http://www.example.com/air/"/>

child.html wordt geladen uit de submap sandbox van de toepassingsinstallatiemap. Relatieve URL's in child.html

worden omgezet op basis van de map sandbox. Merk op dat bestanden op de externe server op www.example.com/airniet toegankelijk zijn in het frame, omdat AIR zou proberen ze te laden uit de map

app:/sandbox/. Het kenmerk allowCrossDomainXHR Neem de code allowCrossDomainXHR="allowCrossDomainXHR" op in de

openingsframetag als u wilt toestaan dat inhoud in het frame XMLHttpRequests uitvoert naar een willekeurig extern domein. Standaard kan niet-toepassingsinhoud dergelijke aanvragen alleen uitvoeren binnen het eigen brondomein. Het toestaan van XHR's naar andere domeinen heeft ernstige gevolgen voor de beveiliging. Code in de pagina kan gegevens uitwisselen met een willekeurig domein. Als er op de een of andere manier kwaadaardige inhoud in de pagina wordt ingebracht, kunnen alle gegevens die toegankelijk zijn voor code in de huidige sandbox, worden aangetast. Schakel alleen XHR's die andere domeinen kunnen bereiken in voor pagina's die u zelf maakt en beheert, en alleen als het laden van gegevens uit andere domeinen absoluut noodzakelijk is. Ook moet u alle externe gegevens die door de pagina worden geladen zorgvuldig valideren om te voorkomen dat code wordt ingebracht of dat andere aanvallen worden uitgevoerd. Belangrijk: Als het kenmerk allowCrossDomainXHR is opgenomen in een frame- of iframe-element, zijn XHR's naar andere domeinen ingeschakeld (behalve als de toegewezen waarde "0" is of begint met de letter "f" of "n"). Als u bijvoorbeeld allowCrossDomainXHR instelt op "deny" (weigeren), zijn XHR's naar andere domeinen nog steeds toegestaan. Laat het kenmerk helemaal weg uit de elementdeclaratie als u aanvragen naar andere domeinen niet wilt inschakelen. ondominitialize, kenmerk Geeft een gebeurtenishandler op voor de framegebeurtenis dominitialize. Dit is een

AIR-specifieke gebeurtenis die wordt geactiveerd wanneer de window- en document-objecten van het frame zijn gemaakt, maar voordat er scripts zijn geparseerd of documentelementen zijn gemaakt. Het frame verzendt de gebeurtenis dominitialize zo vroeg tijdens de uitvoering van de laadsequentie, dat eventuele scripts in de onderliggende pagina kunnen verwijzen naar objecten, variabelen en functies die door de handler dominitialize zijn toegevoegd aan het onderliggende document. De bovenliggende pagina kan alleen rechtstreeks objecten toevoegen aan of toegang krijgen tot objecten in een onderliggend document, als de bovenliggende pagina zich bevindt in dezelfde sandbox als de onderliggende. Een bovenliggende pagina in de toepassingssandbox kan echter wel een sandboxbridge tot stand brengen voor communicatie met inhoud in een niet-toepassingssandbox. In de volgende voorbeelden ziet u hoe u de iframe-tag in AIR gebruikt: Plaats child.html in een externe sandbox zonder toewijzing aan een werkelijk domein op een externe server: <iframe

src="http://localhost/air/child.html" documentRoot="app:/sandbox/" sandboxRoot="http://localhost/air/"/>

Plaats child.html in een externe sandbox, waarbij XMLHttpRequests alleen zijn toegestaan voor www.example.com: <iframe

src="http://www.example.com/air/child.html" documentRoot="app:/sandbox/" sandboxRoot="http://www.example.com/air/"/>

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 217 Informatie over de HTML-omgeving

Plaats child.html in een externe sandbox, waarbij XMLHttpRequests zijn toegestaan voor een willekeurig extern domein: <iframe

src="http://www.example.com/air/child.html" documentRoot="app:/sandbox/" sandboxRoot="http://www.example.com/air/" allowCrossDomainXHR="allowCrossDomainXHR"/>

Plaats child.html in een lokaal-met-bestandssysteem sandbox: <iframe

src="file:///templates/child.html" documentRoot="app:/sandbox/" sandboxRoot="app-storage:/templates/"/>

Plaats child.html in een externe sandbox waarbij de gebeurtenis dominitialize wordt gebruikt om een sandboxbridge tot stand te brengen. <script> var bridgeInterface = {}; bridgeInterface.testProperty = "Bridge engaged"; function engageBridge(){ document.getElementById("sandbox").parentSandboxBridge = bridgeInterface; } <iframe id="sandbox" src="http://www.example.com/air/child.html" documentRoot="app:/" sandboxRoot="http://www.example.com/air/" ondominitialize="engageBridge()"/>

Het volgende document, child.html, illustreert hoe onderliggende inhoud de bovenliggende sandboxbridge kan benaderen: <script> document.write(window.parentSandboxBridge.testProperty);

Zie “Cross-scripting van inhoud in verschillende beveiligingssandboxen” op pagina 235 en “Beveiliging in HTML” op pagina 31 voor meer informatie.

Het HTML-element Canvas Hiermee definieert u een tekengebied voor gebruik met de Webkit-API voor Canvas. Opdrachten met betrekking tot afbeeldingen kunnen niet worden opgegeven in de tag zelf. Als u op het canvas wilt tekenen, roept u de canvastekenmethoden aan via JavaScript.

Zie “Canvas-objecten” op pagina 210 voor meer informatie.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 218 Informatie over de HTML-omgeving

Gebeurtenishandlers voor HTML-elementen DOM-objecten in AIR en Webkit verzenden bepaalde gebeurtenissen die niet aanwezig zijn in het standaard DOMgebeurtenismodel. In de volgende tabel worden de verwante gebeurteniskenmerken aangegeven die u kunt gebruiken om handlers voor deze gebeurtenissen op te geven: Naam callbackkenmerk

Beschrijving

oncontextmenu

Wordt opgeroepen wanneer een contextmenu wordt opgeroepen, bijvoorbeeld door met de rechtermuisknop op geselecteerde tekst te klikken of de Command-toets ingedrukt te houden tijdens het klikken.

oncopy

Wordt opgeroepen wanneer een selectie in een element wordt gekopieerd.

oncut

Wordt opgeroepen wanneer een selectie in een element wordt geknipt.

ondominitialize

Wordt opgeroepen wanneer het DOM wordt gemaakt van een document dat is geladen in een frame of iframe, maar voordat eventuele DOM-elementen worden gemaakt of scripts geparseerd.

ondrag

Wordt opgeroepen wanneer een element wordt gesleept.

ondragend

Wordt opgeroepen wanneer een gesleept element wordt losgelaten.

ondragenter

Wordt opgeroepen wanneer een sleepbeweging de grenzen van een element bereikt.

ondragleave

Wordt opgeroepen wanneer een sleepbeweging de grenzen van een element verlaat.

ondragover

Wordt continu opgeroepen zolang een sleepbeweging zich binnen de grenzen van een element bevindt.

ondragstart

Wordt opgeroepen wanneer een sleepbeweging begint.

ondrop

Wordt opgeroepen wanneer een sleepbeweging wordt losgelaten boven een element.

onerror

Wordt opgeroepen wanneer er een fout optreedt bij het laden van een element.

oninput

Wordt opgeroepen wanneer er tekst wordt ingevoerd in een formulierelement.

onpaste

Wordt opgeroepen wanneer een item wordt geplakt in een element.

onscroll

Wordt opgeroepen wanneer de inhoud van een schuifbaar element wordt geschoven.

onsearch

Wordt opgeroepen wanneer een element wordt gekopieerd (? Apple docs correct ?)

onselectstart

Wordt opgeroepen wanneer een selectie begint.

Het HTML-kenmerk contentEditable U kunt het kenmerk contentEditable aan een willekeurig HTML-element toevoegen om gebruikers toe te staan de inhoud van het element te bewerken. Met de volgende HTML-voorbeeldcode wordt het gehele document ingesteld als bewerkbaar, behalve het eerste p-element:

de Finibus Bonorum et Malorum

Sed ut perspiciatis unde omnis iste natus error.

At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 219 Informatie over de HTML-omgeving

Opmerking: Als u de eigenschap document.designMode instelt op on, zijn alle elementen in het document bewerkbaar, ongeacht de instelling van contentEditable voor een individueel element. Als u echter designModeinstelt op off, kunnen elementen waarvoor contentEditable is ingesteld op true, nog steeds worden bewerkt. Zie “De eigenschap Document.designMode” op pagina 213 voor meer informatie.

Extensies voor CSS WebKit ondersteunt verschillende uitgebreide CSS-eigenschappen. In de volgende tabel worden de uitgebreide eigenschappen aangegeven die worden ondersteund. Aanvullende niet-standaardeigenschappen zijn beschikbaar in WebKit maar worden niet volledig ondersteund in AIR omdat ze in WebKit nog worden ontwikkeld of omdat het experimentele functies zijn die mogelijk in de toekomst worden verwijderd. Naam CSS-eigenschap

Waarden

Beschrijving

-webkit-border-horizontal-spacing

Niet-negatieve lengte-eenheid

Geeft de horizontale component van de randafstand op.

-webkit-border-vertical-spacing

Niet-negatieve lengte-eenheid

Geeft de verticale component van de randafstand op.

-webkit-line-break

after-white-space, normal

Geeft de regel voor het afbreken van tekst op die moet worden gebruikt voor CJK-tekst (Chinees, Japans en Koreaans).

-webkit-margin-bottom-collapse

collapse, discard, separate

Bepaalt hoe de ondermarge van een tabelcel wordt samengevouwen.

-webkit-margin-collapse

collapse, discard, separate

Bepaalt hoe de boven- en ondermarge van een tabelcel worden samengevouwen.

-webkit-margin-start

Een willekeurige lengte-eenheid.

De breedte van de beginmarge. Voor tekst die van links naar rechts wordt geschreven, overschrijft deze eigenschap de linkermarge. Voor tekst die van rechts naar links wordt geschreven, overschrijft deze eigenschap de rechtermarge.

-webkit-margin-top-collapse

collapse, discard, separate

Bepaalt hoe de bovenmarge van een tabelcel wordt samengevouwen.

-webkit-nbsp-mode

normal, space

Bepaalt het gedrag van vaste spaties binnen de ingesloten inhoud.

-webkit-padding-start

Een willekeurige lengte-eenheid.

Geeft aan met welke breedte de opvulling moet worden gestart. Voor tekst die van links naar rechts wordt geschreven, overschrijft deze eigenschap de linkeropvulling. Voor tekst die van rechts naar links wordt geschreven, overschrijft deze eigenschap de rechteropvulling.

-webkit-rtl-ordering

logical, visual

Overschrijft de standaardverwerking van tekst die gedeeltelijk van links naar rechts en gedeeltelijk van rechts naar links wordt geschreven.

-webkit-text-fill-color

Een willekeurige benoemde kleur of numerieke kleurwaarde

Geeft de tekstvulkleur op.

-webkit-text-security

circle, disc, none, square

Geeft de vervangende vorm op die moet worden gebruikt in een invoerveld voor wachtwoorden.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 220 Informatie over de HTML-omgeving

Naam CSS-eigenschap

Waarden

Beschrijving

-webkit-user-drag

•

auto - standaardgedrag

Overschrijft het gedrag dat automatisch wordt toegepast bij slepen.

•

element - het gehele element wordt gesleept

•

none - het element kan niet worden gesleept

-webkit-user-modify

read-only, read-write, read-write-plaintextonly

Geeft aan of de inhoud van een element kan worden bewerkt.

-webkit-user-select

•

auto - standaardgedrag

Geeft aan of een gebruiker de inhoud van een element kan selecteren.

•

none - het element kan niet worden geselecteerd

•

text - alleen tekst in het element kan worden geselecteerd

Zie de handleiding Apple Safari CSS Reference (http://developer.apple.com/documentation/AppleApplications/Reference/SafariCSSRef/) voor meer informatie.

221

Hoofdstuk 21: Programmeren in HTML en JavaScript Een aantal programmeeraspecten zijn uniek voor de ontwikkeling van Adobe® AIR™-toepassingen met HTML en JavaScript. De volgende informatie is belangrijk, ongeacht of u een HTML-gebaseerde AIR-toepassing programmeert, of dat u een SWF-gebaseerde AIR-toepassing programmeert die HTML en JavaScript uitvoert met behulp van de klasse HTMLLoader (of de Flex™-component mx:HTML).

Informatie over de klasse HTMLLoader De klasse HTMLLoader van Adobe AIR definieert het weergaveobject dat HTML-inhoud kan weergeven in een AIRtoepassing. SWF-gebaseerde toepassingen kunnen een HTMLLoader-besturingselement aan een bestaand venster toevoegen of een HTML-venster maken dat automatisch een HTMLLoader-object bevat met HTMLLoader.createRootWindow(). Het HTMLLoader-object kan vanuit de geladen HTML-pagina worden opgeroepen met de JavaScript-eigenschap window.htmlLoader.

HTML-inhoud laden vanuit een URL De volgende code laadt een URL in een HTMLLoader-object en stelt het object in als een onderliggend object van een Sprite-object: var container:Sprite; var html:HTMLLoader = new HTMLLoader; html.width = 400; html.height = 600; var urlReq:URLRequest = new URLRequest("http://www.adobe.com/"); html.load(urlReq); container.addChild(html);

De eigenschappen width en height van een HTMLLoader-object zijn standaard allebei ingesteld op 0. U wordt aangeraden deze afmetingen in te stellen als u een HTMLLoader-object aan het Stage-object toevoegt. De HTMLLoader verstuurt verschillende gebeurtenissen terwijl een pagina wordt geladen. Op basis van deze gebeurtenissen kunt u bepalen wanneer het veilig is om met de geladen pagina te interageren. Deze gebeurtenissen worden beschreven in “HTML-gerelateerde gebeurtenissen afhandelen” op pagina 240. U kunt HTML-tekst ook renderen met behulp van de klasse TextField, maar de mogelijkheden hiervan zijn beperkt. De klasse TextField van Adobe® Flash® Player ondersteunt een subset van de HTML-markeringen, maar vanwege de groottebeperkingen zijn de mogelijkheden hiervan beperkt. (De klasse HTMLLoader die in Adobe AIR is opgenomen, is niet beschikbaar in Flash Player.)

HTML-inhoud laden vanuit een tekenreeks De methode loadString() van een HTMLLoader-object laadt een tekenreeks met HTML-inhoud in het HTMLLoader-object: var html:HTMLLoader = new HTMLLoader(); var htmlStr:String = "Hello world."; html.loadString(htmlStr);

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 222 Programmeren in HTML en JavaScript

Inhoud die is geladen met de methode loadString(), wordt in de toepassingsbeveiligingssandbox geplaatst, zodat deze volledige toegang heeft tot de API's van AIR.

Belangrijke veiligheidsregels bij gebruik van HTML in AIR-toepassingen De bestanden die u met de AIR-toepassing installeert, hebben toegang tot de API's van AIR. Om veiligheidsredenen heeft de inhoud van andere bronnen geen toegang tot deze API's. Voorbeeld: deze beperking voorkomt dat inhoud van een extern domein (bijvoorbeeld http://example.com) de inhoud van de bureaubladmap van de gebruiker (of nog erger) kan lezen. Omdat beveiligingshiaten kunnen worden gebruikt door de functie eval() (en verwante API's) op te roepen, kan inhoud die met de toepassing wordt geïnstalleerd, deze methoden standaard niet gebruiken. Bepaalde Ajaxframeworks gebruiken echter de functie eval() en verwante API's. Om inhoud goed te structureren zodat deze kan werken in een AIR-toepassing, moet u rekening houden met de beveiligingsbeperkingen voor inhoud van verschillende bronnen. Inhoud van verschillende bronnen wordt geplaatst in afzonderlijke beveiligingsclassificaties, die sandboxen worden genoemd (zie “Sandboxen” op pagina 28). Inhoud die met de toepassing wordt geïnstalleerd, wordt standaard in een sandbox geïnstalleerd die de toepassingssandbox wordt genoemd. Deze verleent toegang tot de API's van AIR. De toepassingssandbox is de veiligste sandbox, aangezien beperkingen voorkomen dat niet-vertrouwde code wordt uitgevoerd. U kunt inhoud die met uw toepassing is geïnstalleerd, ook in een andere sandbox plaatsen. Inhoud in niettoepassingssandboxen werkt in een beveiligde omgeving, zoals in een webbrowser. Voorbeeld: code in niettoepassingssandboxen kan eval() en verwante methoden gebruiken (maar anderzijds heeft deze code geen toegang tot de API's van AIR). De runtime voorziet in manieren om inhoud in verschillende sandboxen veilig te laten communiceren (zonder bijvoorbeeld API's van AIR toegankelijk te maken voor niet-toepassingsinhoud). Zie “Crossscripting van inhoud in verschillende beveiligingssandboxen” op pagina 235 voor meer informatie. Als u code oproept die niet in een sandbox kan worden gebruikt vanwege beveiligingsbeperkingen, geeft de runtime de foutmelding weer dat er in de runtime van Adobe AIR een beveiligingsfout betreffende JavaScript-code in de toepassingsbeveiligingssandbox is opgetreden. Om deze fout te voorkomen, volgt u de coderingsrichtlijnen in de volgende sectie, “JavaScript-beveiligingsfouten voorkomen” op pagina 222. Zie “Beveiliging in HTML” op pagina 31 voor meer informatie.

JavaScript-beveiligingsfouten voorkomen Als u code oproept die niet in een sandbox kan worden gebruikt vanwege deze beveiligingsbeperkingen, geeft de runtime de foutmelding weer dat er in de runtime van Adobe AIR een beveiligingsfout betreffende JavaScript-code in de toepassingsbeveiligingssandbox is opgetreden. Ga als volgt te werk om deze fout te voorkomen.

Oorzaken van JavaScript-beveiligingsfouten Code die wordt uitgevoerd in de toepassingssandbox, is uitgesloten van de meeste bewerkingen waarbij tekenreeksen worden geëvalueerd en uitgevoerd nadat de documentgebeurtenis load is geactiveerd en eventuele handlers voor de gebeurtenis load zijn afgesloten. Als u de volgende typen JavaScript-instructies gebruikt die potentieel onveilige tekenreeksen evalueren en uitvoeren, worden JavaScript-fouten gegenereerd:

• De functie eval() • setTimeout() en setInterval()

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 223 Programmeren in HTML en JavaScript

• Functieconstructor Bovendien mislukken de volgende typen JavaScript-instructies zonder een Javascript-fout voor onveilige inhoud te genereren:

• javascript: URL's • Gebeurteniscallbacks die via onevent-kenmerken in innerHTML- en outerHTML-instructies zijn toegewezen • JavaScript-bestanden laden van buiten de installatiemap van de toepassing • document.write() en document.writeln() • Synchrone XMLHttpRequests vóór de gebeurtenis load of tijdens de gebeurtenishandler load • Dynamisch gecreëerde scriptelementen Opmerking: In enkele beperkte gevallen is de evaluatie van tekenreeksen toegestaan. Zie “Codebeperkingen voor de inhoud van verschillende sandboxen” op pagina 33 voor meer informatie. Adobe houdt een lijst bij van Ajax-frameworks die de toepassingsbeveiligingssandbox ondersteunen. Deze lijst vindt u op http://www.adobe.com/go/airappsandboxframeworks_nl. In de volgende secties vindt u informatie om scripts zo aan te passen, dat deze JavaScript-fouten voor onveilige inhoud en stille defecten worden voorkomen voor code die in de toepassingssandbox wordt uitgevoerd.

Toepassingsinhoud toewijzen aan een andere sandbox In de meeste gevallen kunt u een toepassing aanpassen of opnieuw structureren, zodat JavaScript-beveiligingsfouten worden voorkomen. Als aanpassen of opnieuw structureren echter niet mogelijk is, kunt u de inhoud van de toepassing in een andere sandbox laden met de techniek die is beschreven in “Toepassingsinhoud laden in een niettoepassingssandbox” op pagina 236. Als deze inhoud ook toegang moet hebben tot de API's van AIR, kunt u een sandboxbridge maken, zoals beschreven in “Sandboxbridge-interface instellen” op pagina 237.

De functie eval() In de toepassingssandbox kunt u de functie eval() alleen gebruiken vóór de gebeurtenis load van de pagina of tijdens de gebeurtenishandler load. Nadat de pagina is geladen, wordt geen code uitgevoerd als eval() wordt opgeroepen. In de volgende gevallen kunt u uw code echter aanpassen om het gebruik van eval() te voorkomen.

Eigenschappen toewijzen aan een object In plaats van een tekenreeks te parseren om de eigenschapsaccessor te bouwen: eval("obj." + propName + " = " + val);

roep eigenschappen op met haakjesnotering: obj[propName] = val;

Functies maken met variabelen die beschikbaar zijn in de context Vervang instructies zoals deze: function compile(var1, var2){ eval("var fn = function(){ this."+var1+"(var2) }"); return fn; }

door:

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 224 Programmeren in HTML en JavaScript

function compile(var1, var2){ var self = this; return function(){ self[var1](var2) }; }

Objecten maken met de naam van de klasse als tekenreeksparameter Bekijken we een hypothetische JavaScript-klasse die met de volgende code is gedefinieerd: var CustomClass = { Utils: { Parser: function(){ alert('constructor') } }, Data: { } }; var constructorClassName = "CustomClass.Utils.Parser";

De eenvoudigste manier om een instantie te maken, is met behulp van eval(): var myObj; eval('myObj=new ' + constructorClassName +'()')

U kunt het oproepen van eval() echter voorkomen door elke component van de klassenaam te parseren en het nieuwe object op te bouwen met behulp van de haakjesnotering: function getter(str) { var obj = window; var names = str.split('.'); for(var i=0;i
Om de instantie te maken, gebruikt u: try{ var Parser = getter(constructorClassName); var a = new Parser(); }catch(e){ alert(e); }

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 225 Programmeren in HTML en JavaScript

setTimeout() en setInterval() Vervang de tekenreeks die als handlerfunctie is opgegeven, door een functieverwijzing of een object. Voorbeeld: vervang een instructie zoals: setTimeout("alert('Timeout')", 10);

door: setTimeout(alert('Timeout'), 10);

Of, als de functie vereist dat het object this wordt ingesteld door de oproeper, vervangt u een instructie zoals: this.appTimer = setInterval("obj.customFunction();", 100);

door het volgende: var _self = this; this.appTimer = setInterval(function(){obj.customFunction.apply(_self);}, 100);

Functieconstructor Oproepen van new Function(param, body) kunnen worden vervangen door een inline functiedeclaratie of alleen worden gebruikt voordat de gebeurtenis load van de pagina is afgehandeld.

javascript: URL's De code die in een koppeling met behulp van het URL-schema javascript: is gedefinieerd, wordt in de toepassingssandbox genegeerd. Er wordt geen JavaScript-fout voor onveilige inhoud gegenereerd. U kunt koppelingen vervangen die gebruikmaken van URL's van het type javascript:, zoals: Click Me

door: Click Me

Gebeurteniscallbacks die via onevent-kenmerken in innerHTML- en outerHTML-instructies zijn toegewezen Als u innerHTML of outerHTML gebruikt om elementen toe te voegen aan de DOM van een document, worden gebeurteniscallbacks die in de instructie zijn toegewezen, zoals onclick of onmouseover, genegeerd. Er wordt geen beveiligingsfout gegenereerd. In plaats daarvan kunt u het kenmerk id aan de nieuwe elementen toewijzen en de callbackfuncties van de gebeurtenishandler instellen met de methode addEventListener(). U hebt bijvoorbeeld een doelelement in een document, zoals:

Vervang instructies zoals: document.getElementById('container').innerHTML = 'Click Me.';

door: document.getElementById('container').innerHTML = 'Click Me.'; document.getElementById('smith').addEventListener("click", function() { code(); });

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 226 Programmeren in HTML en JavaScript

JavaScript-bestanden laden van buiten de installatiemap van de toepassing Scriptbestanden kunnen niet van buiten de toepassingssandbox worden geladen. Er wordt geen beveiligingsfout gegenereerd. Alle scriptbestanden die in de toepassingssandbox worden uitgevoerd, moeten in de toepassingsmap zijn geïnstalleerd. Als u externe scripts in een pagina wenst te gebruiken, moet u de pagina toewijzen aan een andere sandbox. Zie “Toepassingsinhoud laden in een niet-toepassingssandbox” op pagina 236.

document.write() en document.writeln() Oproepen van document.write() of document.writeln() worden genegeerd nadat de gebeurtenis load van de pagina is afgehandeld. Er wordt geen beveiligingsfout gegenereerd. Als alternatief kunt u een nieuw bestand laden of de hoofdtekst van het document vervangen met behulp van DOM-manipulatietechnieken.

Synchrone XMLHttpRequests vóór de gebeurtenis load of tijdens de gebeurtenishandler load Synchrone XMLHttpRequests die worden gestart vóór de gebeurtenis load van de pagina of tijdens de handler voor de gebeurtenis load, retourneren geen inhoud. Asynchrone XMLHttpRequests kunnen worden gestart maar retourneren pas na de gebeurtenis load. Nadat de gebeurtenis load is afgehandeld, gedragen synchrone XMLHttpRequests zich op de normale manier.

Dynamisch gecreëerde scriptelementen Scriptelementen die dynamisch zijn gecreëerd, bijvoorbeeld met innerHTML of de methode document.createElement(), worden genegeerd.

API-klassen van AIR oproepen vanuit JavaScript Naast de standaardelementen en de uitgebreide elementen van Webkit, heeft HTML- en JavaScript-code toegang tot de hostklassen die door de runtime worden geboden. Met deze klassen hebt u toegang tot de geavanceerde functies van AIR, zoals:

• Toegang tot het bestandssysteem • Gebruik van lokale SQL-databases • Besturing van toepassings- en venstermenu's • Toegang tot netwerksockets • Gebruik van door de gebruiker gedefinieerde klassen en objecten • Geluidsmogelijkheden Voorbeeld: de AIR API voor het bestandssysteem bevat de klasse File, die in het pakket flash.filesystem is opgenomen. U kunt als volgt een File-object in JavaScript maken: var myFile = new window.runtime.flash.filesystem.File();

Het runtime-object is een speciaal JavaScript-object, dat beschikbaar is voor HTML-inhoud die in AIR in de toepassingssandbox wordt uitgevoerd. Hiermee hebt u vanuit JavaScript toegang tot runtimeklassen. De eigenschap flash van het runtime-object biedt toegang tot het pakket flash. De eigenschap flash.filesystem van het runtime-object biedt toegang tot het pakket flash.filesystem (dit pakket bevat de klasse File). Pakketten zijn een manier om klassen te organiseren die in ActionScript worden gebruikt.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 227 Programmeren in HTML en JavaScript

Opmerking: De eigenschap runtime wordt niet automatisch toegevoegd aan de vensterobjecten van pagina's die in een frame of iframe zijn geladen. Zolang het onderliggende document zich echter in de toepassingssandbox bevindt, heeft het onderliggende element toegang tot de eigenschap runtime van het bovenliggende element. Vanwege de pakketstructuur van de runtimeklassen zou een ontwikkelaar lange reeksen JavaScript-code moeten typen om toegang te krijgen tot elke klasse (bijvoorbeeld window.runtime.flash.desktop.NativeApplication). Daarom omvat de SDK van AIR het bestand AIRAliases.js, waarmee u veel makkelijker toegang hebt tot runtimeklassen (door bijvoorbeeld gewoon air.NativeApplication te typen). De API-klassen van AIR worden in deze handleiding besproken. Andere klassen van de API voor Flash Player die interessant kunnen zijn voor HTML-ontwikkelaars, worden beschreven in Adobe AIR Language Reference for HTML Developers. ActionScript is de taal die wordt gebruikt in SWF-inhoud (Flash Player). De syntaxis van JavaScript en die van ActionScript zijn echter bijna identiek. (Ze zijn allebei gebaseerd op versies van de taal ECMAScript.) Alle ingebouwde klassen zijn zowel in JavaScript (in HTML-inhoud) als in ActionScript (in SWFinhoud) beschikbaar. Opmerking: JavaScript-code kan geen gebruik maken van de klassen Dictionary, XML en XMLList, die wel beschikbaar zijn in ActionScript. Opmerking: Zie Klassen, pakketten en naamruimten in ActionScript 3.0 en Basisinformatie over ActionScript voor JavaScript-ontwikkelaars voor meer informatie.

Het bestand AIRAliases.js gebruiken De runtimeklassen zijn georganiseerd in een pakketstructuur, zoals hierna wordt geïllustreerd:

•

window.runtime.flash.desktop.NativeApplication

•

window.runtime.flash.desktop.ClipboardManager

•

window.runtime.flash.filesystem.FileStream

•

window.runtime.flash.data.SQLDatabase

In de SDK van AIR is ook het bestand AIRAliases.js opgenomen, dat "alias"-definities bevat waarmee u runtimeklassen kunt oproepen zonder omslachtig typewerk. Voorbeeld: u kunt de klassen die hierboven zijn vermeld, oproepen door gewoon het volgende te typen:

•

air.NativeApplication

•

air.Clipboard

•

air.FileStream

•

air.SQLDatabase

Deze lijst is slechts een kort fragment van de klassen in het bestand AIRAliases.js. De volledige lijst van klassen en functies op pakketniveau vindt u in Adobe AIR Language Reference for HTML Developers. Naast de vaak gebruikte runtimeklassen bevat het bestand AIRAliases.js ook aliassen voor vaak gebruikte functies op pakketniveau: window.runtime.trace(), window.runtime.flash.net.navigateToURL() en window.runtime.flash.net.sendToURL(), met als alias air.trace(), air.navigateToURL() en air.sendToURL(). Als u het bestand AIRAliases.js wilt gebruiken, neemt u de volgende script-verwijzing op in uw HTML-pagina: <script src="AIRAliases.js">

Pas indien nodig het pad aan in de src-verwijzing.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 228 Programmeren in HTML en JavaScript

Belangrijk: Tenzij anders is aangegeven, gaat de JavaScript-voorbeeldcode in deze documentatie ervan uit dat u het bestand AIRAliases.js hebt opgenomen in uw HTML-pagina.

Informatie over URL's in AIR In HTML-inhoud die in AIR wordt uitgevoerd, kunt u een van de volgende URL-schema's gebruiken om srckenmerken te definiëren voor de tags img, frame, iframe en script, in het kenmerk href van de tag link, of op een willekeurige plaats waar u een URL kunt opgeven. URL-schema

Beschrijving

Voorbeeld

file

Het pad op basis van de hoofdmap van het bestandssysteem. file:///c:/AIR Test/test.txt

app

Het pad op basis van de hoofdmap van de geïnstalleerde toepassing.

app:/images

app-storage

Het pad op basis van de opslagmap van de toepassing. Voor elke geïnstalleerde toepassing definieert AIR een unieke opslagmap. Dit is de plaats waar gegevens worden opgeslagen die eigen zijn aan die toepassing.

app-storage:/settings/prefs.xml

http

Een standaard HTTP-aanvraag.

http://www.adobe.com

https

Een standaard HTTPS-aanvraag.

https://secure.example.com

Zie “URL-schema's van AIR gebruiken in URL's” op pagina 292 voor meer informatie over het gebruik van URLschema's in AIR. API's van AIR, zoals de klassen File, Loader, URLStream en Sound, maken vaak gebruik van een URLRequest-object in plaats van een tekenreeks waarin de URL is opgenomen. Het URLRequest-object zelf wordt geïnitialiseerd met een tekenreeks, die dezelfde URL-schema's kan gebruiken. Voorbeeld: de volgende instructie creëert een URLRequestobject waarmee de startpagina van Adobe kan worden opgevraagd: var urlReq = new air.URLRequest("http://www.adobe.com/");

Zie “URL-aanvragen en netwerken” op pagina 290 voor meer informatie over URLRequest-objecten.

ActionScript-objecten beschikbaar maken voor JavaScript JavaScript in de HTML-pagina die door een HTMLLoader-object is geladen, kan de klassen, objecten en functies oproepen die in de ActionScript-uitvoeringscontext zijn gedefinieerd. Daartoe wordt gebruikgemaakt van de eigenschappen window.runtime, window.htmlLoader en window.nativeWindow van de HTML-pagina. U kunt ook ActionScript-objecten en -functies beschikbaar maken voor JavaScript-code door verwijzingen naar die objecten en functies op te nemen in de JavaScript-uitvoeringscontext.

Basisvoorbeeld om JavaScript-objecten op te roepen vanuit ActionScript In het volgende voorbeeld ziet u hoe u eigenschappen kunt toevoegen die ActionScript-objecten verwijzen naar het algemene vensterobject van een HTML-pagina:

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 229 Programmeren in HTML en JavaScript

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; }

De HTML-inhoud (in een bestand met de naam test.html), die in het vorige voorbeeld in het HTMLLoader-object is geladen, kan de eigenschap foo oproepen, evenals de methode helloFromJS(), die in het bovenliggende SWFbestand is gedefinieerd: <script> function alertFoo() { alert(foo); } What is foo?

Call helloFromJS() function.

Als u de JavaScript-context oproept van een document dat op dat moment wordt geladen, kunt u met de gebeurtenis htmlDOMInitialize al vroeg in de constructiesequentie van de pagina objecten maken, zodat ze toegankelijk zijn voor scripts die in de pagina zijn gedefinieerd. Als u wacht op de gebeurtenis complete, kunnen alleen scripts die na de gebeurtenis load van de pagina worden uitgevoerd, toegang krijgen tot de toegevoegde objecten.

Klassedefinities beschikbaar maken voor JavaScript Als u de ActionScript-klassen van uw toepassing beschikbaar wilt maken in JavaScript, kunt u de geladen HTMLinhoud toewijzen aan het toepassingsdomein waarin zich de klassedefinities bevinden. Het toepassingsdomein van de JavaScript-uitvoeringscontext kan worden ingesteld met de eigenschap runtimeApplicationDomain van het HTMLLoader-object. Als u het toepassingsdomein bijvoorbeeld wilt instellen op het primaire toepassingsdomein, stelt u runtimeApplicationDomain in op ApplicationDomain.currentDomain, zoals in de volgende code: html.runtimeApplicationDomain = ApplicationDomain.currentDomain;

Nadat de eigenschap runtimeApplicationDomain is ingesteld, deelt de JavaScript-context klassedefinities met het toegewezen domein. Als u een instantie van een aangepaste klasse in JavaScript wilt maken, verwijst u naar de klassedefinitie via de eigenschap window.runtime en gebruikt u de operator new: var customClassObject = new window.runtime.CustomClass();

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 230 Programmeren in HTML en JavaScript

De HTML-inhoud moet afkomstig zijn van een compatibel beveiligingsdomein. Als de HTML-inhoud afkomstig is van een ander beveiligingsdomein dan dat van het toepassingsdomein dat u toewijst, gebruikt de pagina in plaats daarvan een standaard toepassingsdomein. Voorbeeld: als u een externe pagina van internet laadt, kunt u ApplicationDomain.currentDomain niet toewijzen als het toepassingsdomein van de pagina.

Gebeurtenislisteners verwijderen Als u gebeurtenislisteners voor JavaScript toevoegt aan objecten buiten de huidige pagina, inclusief runtimeobjecten, objecten in de geladen SWF-inhoud en zelfs JavaScript-objecten die in andere pagina's worden uitgevoerd, moet u deze gebeurtenislisteners altijd verwijderen als de pagina niet meer is geladen. Anders verzendt de gebeurtenislistener de gebeurtenis naar een handlerfunctie die niet meer bestaat. In dit geval wordt er een foutmelding weergegeven dat de toepassing heeft geprobeerd te verwijzen naar een JavaScript-object in een HTML-pagina die niet meer is geladen. Wanneer u overbodige gebeurtenislisteners verwijdert, kan AIR ook het overeenkomstige geheugen opnieuw gebruiken. Zie “Gebeurtenislisteners verwijderen in HTML-pagina's die navigeren” op pagina 244 voor meer informatie.

HTML DOM- en JavaScript-objecten oproepen vanuit ActionScript Nadat het HTMLLoader-object de gebeurtenis complete heeft verzonden, hebt u toegang tot alle objecten in het HTML DOM (Document Object Model) voor de pagina. Toegankelijke objecten zijn onder andere weergaveelementen (zoals de objecten div en p in de pagina), evenals JavaScript-variabelen en -functies. De gebeurtenis complete komt overeen met de JavaScript-gebeurtenis load van de pagina. Vóór complete wordt verzonden, mogen variabelen, functies en DOM-elementen niet zijn geparseerd of gecreëerd. Indien mogelijk wacht u op de gebeurtenis complete vóór u het HTML DOM benadert. Bekijken we als voorbeeld de volgende HTML-pagina: <script> foo = 333; function test() { return "OK."; }

Hi.

Deze eenvoudige HTML-pagina definieert een JavaScript-variabele met de naam foo en een JavaScript-functie met de naam test(). Beide zijn eigenschappen van het algemene object window van de pagina. Bovendien bevat het object window.document een element met de naam P (met de id p1), dat u kunt oproepen met de methode getElementById(). Nadat de pagina is geladen (wanneer het HTMLLoader-object de gebeurtenis complete verzendt), kunt u al deze objecten benaderen vanuit ActionScript, zoals wordt geïllustreerd met de volgende ActionScript-code:

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 231 Programmeren in HTML en JavaScript

var html:HTMLLoader = new HTMLLoader(); html.width = 300; html.height = 300; html.addEventListener(Event.COMPLETE, completeHandler); var xhtml:XML = <script> foo = 333; function test() { return "OK."; }

Hi.

; 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. }

Als u de inhoud van een HTML-element wilt oproepen, gebruikt u de eigenschap innerHTML. De vorige code gebruikt bijvoorbeeld html.window.document.getElementById("p1").innerHTML om de inhoud van het HTML-element p1 op te halen. U kunt ook eigenschappen voor de HTML-pagina instellen vanuit ActionScript. Het volgende voorbeeld stelt de inhoud van het element p1 en de waarde van de JavaScript-variabele foo op de pagina in met behulp van een verwijzing naar het bevattende HTMLLoader-object: html.window.document.getElementById("p1").innerHTML = "Goodbye"; html.window.foo = 66;

SWF-inhoud insluiten in HTML In een AIR-toepassing kunt u SWF-inhoud insluiten in HTML-inhoud, net zoals in een browser. Sluit de SWF-inhoud in met behulp van de tag object, de tag embed of beide. Opmerking: Vaak wordt zowel de tag object als de tag embed gebruikt om SWF-inhoud weer te geven in een HTMLpagina. Deze techniek biedt echter geen voordelen in AIR. U kunt de W3C-standaard tag object op zichzelf gebruiken in inhoud die in AIR moet worden weergegeven. U kunt ook desgewenst de tags object en embed samen blijven gebruiken voor HTML-inhoud die ook in een browser wordt weergegeven. In het volgende voorbeeld ziet u hoe u de HTML-tag object gebruikt om een SWF-bestand in HTML-inhoud weer te geven. Het SWF-bestand wordt vanuit de toepassingsmap geladen maar u kunt een willekeurig URL-schema gebruiken dat door AIR wordt ondersteund. (De bronlocatie van het SWF-bestand bepaalt de beveiligingssandbox waarin AIR de inhoud plaatst.)

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 232 Programmeren in HTML en JavaScript

U kunt ook een script gebruiken om inhoud dynamisch te laden. In het volgende voorbeeld ziet u hoe u een objectknooppunt maakt om het SWF-bestand weer te geven dat is opgegeven in de parameter urlString. Het voorbeeld voegt het knooppunt toe als onderliggend element van het pagina-element met de id die is opgegeven met de parameter elementID: <script> function showSWF(urlString, elementID){ var displayContainer = document.getElementById(elementID); displayContainer.appendChild(createSWFObject(urlString,650,650)); } 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); return SWFObject; }

ActionScript-bibliotheken in een HTML-pagina gebruiken AIR breidt het HTML-scriptelement uit, zodat een pagina ActionScript-klassen kan importeren in een gecompileerd SWF-bestand. Stel dat de bibliotheek myClasses.swf zich in de submap lib van de hoofdtoepassingsmap bevindt. Als u deze bibliotheek wilt importeren, neemt u de volgende scripttag op in een HTML-bestand: <script src="lib/myClasses.swf" type="application/x-shockwave-flash">

Belangrijk: Het kenmerk type moet type="application/x-shockwave-flash" zijn, anders wordt de bibliotheek niet goed geladen. De map lib en het bestand myClasses.swf moeten ook worden opgenomen wanneer het AIR-bestand in een pakket wordt geplaatst. Benader de geïmporteerde klassen via de eigenschap runtime van het JavaScript-object Window: var libraryObject = new window.runtime.LibraryClass();

Als de klassen in het SWF-bestand zijn verdeeld in pakketten, moet u ook de pakketnaam opnemen. Als de definitie LibraryClass zich bijvoorbeeld in een pakket met de naam utilities bevindt, maakt u met de volgende instructie een instantie van de klasse: var libraryObject = new window.runtime.utilities.LibraryClass();

Opmerking: Als u in AIR een ActionScript SWF-bibliotheek wilt compileren als onderdeel van een HTML-pagina, gebruikt u de compiler acompc. Het hulpprogramma acompc maakt deel uit van de SDK van Flex 3 en wordt beschreven in de Flex 3 SDK-documentatie.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 233 Programmeren in HTML en JavaScript

HTML DOM- en JavaScript-objecten oproepen vanuit een geïmporteerd ActionScript-bestand Als u objecten in een HTML-pagina wenst op te roepen vanuit ActionScript in een SWF-bestand dat in de pagina is geïmporteerd met behulp van de tag <script>, geeft u een verwijzing naar een JavaScript-object zoals window of document op aan een functie die in de ActionScript-code is gedefinieerd. Gebruik de verwijzing binnen de functie om het JavaScript-object op te roepen (of andere objecten die toegankelijk zijn via de doorgegeven verwijzing). Bekijken we als voorbeeld de volgende HTML-pagina: <script src="ASLibrary.swf" type="application/x-shockwave-flash"> <script> num = 254; function getStatus() { return "OK."; } function runASFunction(window){ var obj = new runtime.ASClass(); obj.accessDOM(window); }

Body text.

Deze eenvoudige HTML-pagina heeft een JavaScript-variabele met de naam num en een JavaScript-functie met de naam getStatus(). Beide zijn eigenschappen van het object window van de pagina. Bovendien bevat het object window.document een element met de naam P (met de id p1). De pagina laadt het ActionScript-bestand "ASLibrary.swf", waarin zich de klasse ASClass bevindt. ASClass definieert de functie accessDOM(), die de waarden van deze JavaScript-objecten bijhoudt. De methode accessDOM() gebruikt het JavaScript-object Window als argument. Op basis van deze Window-verwijzing kunnen andere objecten in de pagina worden benaderd, zoals variabelen, functies en DOM-elementen, zoals wordt geïllustreerd in de volgende definitie: public class ASClass{ public function accessDOM(window:*):void { trace(window.num); // 254 trace(window.document.getElementById("p1").innerHTML); // Body text.. trace(window.getStatus()); // OK. } }

U kunt eigenschappen van de HTML-pagina ophalen en instellen op basis van een geïmporteerde ActionScript-klasse. De volgende functie stelt bijvoorbeeld de inhoud van het element p1 op de pagina in, evenals de waarde van de JavaScript-variabele foo op de pagina: public function modifyDOM(window:*):void { window.document.getElementById("p1").innerHTML = "Bye"; window.foo = 66;

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 234 Programmeren in HTML en JavaScript

Date- en RegExp-objecten converteren De talen JavaScript en ActionScript definiëren allebei de klassen Date en RegExp, maar objecten van deze typen worden niet automatisch geconverteerd tussen de twee uitvoeringscontexten. U moet de Date- en RegExp-objecten naar het equivalente type converteren vóór u ze gebruikt om eigenschappen of functieparameters in de andere uitvoeringscontext in te stellen. Voorbeeld: de volgende ActionScript-code converteert het JavaScript-object Date met de naam jsDate naar het ActionScript-object Date: var asDate:Date = new Date(jsDate.getMilliseconds());

De volgende ActionScript-code converteert het JavaScript-object RegExp met de naam jsRegExp naar het ActionScript-object RegExp: 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);

HTML-opmaakmodellen bewerken vanuit ActionScript Nadat het HTMLLoader-object de gebeurtenis complete heeft verzonden, kunt u CSS-stijlen in een pagina onderzoeken en bewerken. Bekijken we als voorbeeld het volgende eenvoudige HTML-document: <style> .style1A { font-family:Arial; font-size:12px } .style1B { font-family:Arial; font-size:24px } <style> .style2 { font-family:Arial; font-size:12px }

Style 1A

Style 1B

Style 2

Nadat een HTMLLoader-object deze inhoud heeft geladen, kunt u de CSS-stijlen in de pagina als volgt bewerken via de array cssRules van de array window.document.styleSheets:

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 235 Programmeren in HTML en JavaScript

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"; }

Deze code past de CSS-stijlen zo aan, dat het resulterende HTML-document er als volgt uitziet:

Let op: code kan stijlen aan de pagina toevoegen nadat het HTMLLoader-object de gebeurtenis complete heeft verzonden.

Cross-scripting van inhoud in verschillende beveiligingssandboxen Het beveiligingsmodel van de runtime isoleert code op basis van de oorsprong. Door cross-scripting van de inhoud in verschillende beveiligingssandboxen kunt u inhoud in een bepaalde beveiligingssandbox toegang bieden tot bepaalde eigenschappen en methoden in een andere sandbox.

AIR-beveiligingssandboxen en JavaScript-code AIR past een zelfde-oorsprongbeleid toe, dat voorkomt dat code in een bepaald domein kan interageren met inhoud in een ander domein. Alle bestanden worden in een sandbox geplaatst op basis van hun oorsprong. Inhoud in de toepassingssandbox kan normaal gesproken niet het zelfde-oorsprongprincipe schenden en inhoud die van buiten de installatiemap van de toepassing is geladen, cross-scripten. AIR biedt echter een aantal technieken waarmee u crossscripting kunt toepassen op niet-toepassingsinhoud. Eén techniek maakt gebruik van frames of iframes om toepassingsinhoud aan een andere beveiligingssandbox toe te wijzen. Pagina's die vanaf de sandboxzone van de toepassing zijn geladen, gedragen zich alsof ze vanaf het externe domein zijn geladen. Voorbeeld: als u toepassingsinhoud toewijst aan het domein example.com, kan die inhoud pagina's cross-scripten die vanaf example.com zijn geladen. Deze techniek plaatst de toepassingsinhoud in een andere sandbox, zodat code binnen die inhoud niet langer is onderworpen aan de uitvoeringsbeperkingen voor code in geëvalueerde tekenreeksen. U kunt deze techniek van sandboxtoewijzing gebruiken om deze beperkingen te verminderen, zelfs als u geen cross-scripting van externe inhoud hoeft uit te voeren. Inhoud op die manier toewijzen, kan met name interessant zijn als u met een van de vele JavaScriptframeworks werkt, of met bestaande code die is gebaseerd op de evaluatie van tekenreeksen. Neem echter het extra risico in acht dat onvertrouwde inhoud kan worden geïnjecteerd en uitgevoerd als inhoud buiten de toepassingssandbox wordt uitgevoerd. Pas hiervoor de nodige voorzorgsmaatregelen toe.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 236 Programmeren in HTML en JavaScript

Anderzijds verliest toepassingsinhoud die aan een andere sandbox is toegewezen, de toegangsrechten voor de API's van AIR, zodat de techniek van sandboxtoewijzing niet kan worden gebruikt om AIR-functionaliteit toegankelijk te maken voor code die buiten de toepassingssandbox wordt uitgevoerd. Met een andere cross-scriptingtechniek kunt u een interface (sandboxbridge) maken tussen inhoud in een niettoepassingssandbox en het bovenliggende document in de toepassingssandbox. Dankzij deze bridge heeft de onderliggende inhoud toegang tot eigenschappen en methoden die door de bovenliggende inhoud worden gedefinieerd, en omgekeerd. Beide situaties kunnen zich ook tegelijk voordoen. Ten slotte kunt u ook domeinoverschrijdende XMLHttpRequests uitvoeren vanuit de toepassingssandbox en optioneel vanuit andere sandboxen. Zie “Frame- en iframe-elementen in HTML” op pagina 215, “Beveiliging in HTML” op pagina 31 en het “XMLHttpRequest-objecten” op pagina 209 voor meer informatie.

Toepassingsinhoud laden in een niet-toepassingssandbox Om toepassingsinhoud veilig te cross-scripten met inhoud die van buiten de installatiemap van de toepassing is geladen, kunt u het element frame of iframe gebruiken om toepassingsinhoud in dezelfde beveiligingssandbox als de externe inhoud te laden. Als u geen cross-scripting van de externe inhoud nodig hebt maar toch een pagina van uw toepassing buiten de toepassingssandbox wilt laden, kunt u dezelfde techniek gebruiken, waarbij u http://localhost/ of een andere onschuldige waarde opgeeft als het domein of de oorsprong. AIR voegt de nieuwe kenmerken sandboxRoot en documentRoot toe aan het element frame, zodat u kunt bepalen of een toepassingsbestand dat in het frame is geladen, moet worden toegewezen aan een niet-toepassingssandbox. Bestanden met een pad onder de URL sandboxRoot worden in plaats daarvan geladen vanuit de map documentRoot. Om veiligheidsredenen wordt de toepassingsinhoud die op die manier wordt geladen, behandeld alsof deze vanaf de URL sandboxRoot is geladen. De eigenschap sandboxRoot geeft de URL op die moet worden gebruikt om de sandbox en het domein te bepalen waarin de frame-inhoud moet worden geplaatst. Het URL-schema file:, http: of https: moet worden gebruikt. Als u een relatieve URL opgeeft, blijft de inhoud in de toepassingssandbox. De eigenschap documentRoot bepaalt de map waaruit de frame-inhoud moet worden geladen. Het URL-schema file:, app: of app-storage: moet worden gebruikt. In het volgende voorbeeld ziet u hoe u inhoud die in de submap sandbox van de toepassing is geïnstalleerd, toewijst voor uitvoering in de externe sandbox en het domein www.example.com: <iframe src="http://www.example.com/local/ui.html" sandboxRoot="http://www.example.com/local/" documentRoot="app:/sandbox/">

De pagina ui.html kan met behulp van de volgende scripttag een JavaScript-bestand laden vanuit de lokale map sandbox: <script src="http://www.example.com/local/ui.js">

Deze pagina kan ook inhoud laden vanuit een map op de externe server met bijvoorbeeld de volgende scripttag: <script src="http://www.example.com/remote/remote.js">

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 237 Programmeren in HTML en JavaScript

De URL sandboxRoot maskeert alle inhoud op dezelfde URL op de externe server. In het vorige voorbeeld hebt u geen toegang tot externe inhoud op www.example.com/local/ (of een van de submappen) omdat AIR de aanvraag omleidt naar de lokale toepassingsmap. Alle aanvragen worden omgeleid, ongeacht of ze afkomstig zijn van paginanavigatie, een XMLHttpRequest of een andere manier om inhoud te laden.

Sandboxbridge-interface instellen U kunt een sandboxbridge gebruiken als inhoud in de toepassingssandbox toegang moet hebben tot eigenschappen of methoden die zijn gedefinieerd door inhoud in een niet-toepassingssandbox, of als niet-toepassingsinhoud toegang moet hebben tot eigenschappen en methoden die zijn gedefinieerd door inhoud in de toepassingssandbox. Creëer een bridge met de eigenschappen childSandboxBridge en parentSandboxBridge van het object window van een willekeurig onderliggend document.

Onderliggende sandboxbridges creëren Met de eigenschap childSandboxBridge kan het onderliggende document een interface toegankelijk kan maken voor inhoud in het bovenliggende document. Als u een interface toegankelijk wilt maken, moet u de eigenschap childSandbox instellen op een functie of object in het onderliggende document. Vervolgens hebt u toegang tot het object of de functie vanuit de inhoud van het bovenliggende document. In het volgende voorbeeld ziet u hoe een script dat in een onderliggend document wordt uitgevoerd, een object dat een functie en eigenschap bevat, toegankelijk kan maken voor het bovenliggende document: var interface = {}; interface.calculatePrice = function(){ return ".45 cents"; } interface.storeID = "abc" window.childSandboxBridge = interface;

Als deze onderliggende inhoud wordt geladen in een iframe met de id "child", kunt u de interface vanuit de bovenliggende inhoud benaderen door de eigenschap childSandboxBridge van het frame te lezen: var childInterface = document.getElementById("child").contentWindow.childSandboxBridge; air.trace(childInterface.calculatePrice()); //traces ".45 cents" air.trace(childInterface.storeID)); //traces "abc"

Bovenliggende sandboxbridges creëren Met de eigenschap parentSandboxBridge kan het bovenliggende document een interface toegankelijk kan maken voor inhoud in een onderliggend document. Als u een interface toegankelijk wilt maken, stelt het bovenliggende document de eigenschap parentSandbox van een onderliggend document in op een functie of object dat in het bovenliggende document wordt gedefinieerd. Vervolgens hebt u toegang tot het object of de functie vanuit de inhoud van het onderliggende document. In het volgende voorbeeld ziet u hoe een script dat in een bovenliggend document wordt uitgevoerd, een object dat een functie bevat, toegankelijk kan maken voor een onderliggend document: var interface = {}; interface.save = function(text){ var saveFile = air.File("app-storage:/save.txt"); //write text to file } document.getElementById("child").contentWindow.parentSandboxBridge = interface;

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 238 Programmeren in HTML en JavaScript

Via deze interface kan inhoud in het onderliggende frame tekst opslaan in een bestand met de naam save.txt. Er is echter geen andere toegang tot het bestandssysteem. De onderliggende inhoud kan bijvoorbeeld de functie Save als volgt oproepen: var textToSave = "A string."; window.parentSandboxBridge.save(textToSave);

De toepassingsinhoud moet de kleinst mogelijke interface toegankelijk maken voor andere sandboxen. Niettoepassingsinhoud moet standaard als onbetrouwbaar worden beschouwd omdat deze inhoud kan blootstaan aan toevallige of kwaadwillige injectie van code. U moet de nodige veiligheidsmaatregelen nemen om misbruik te voorkomen van de interface die u via de bovenliggende sandboxbridge toegankelijk maakt.

Bovenliggende sandboxbridges benaderen tijdens het laden van een pagina Als een script in een onderliggend document toegang moet hebben tot een bovenliggende sandboxbridge, moet de bridge worden ingesteld voordat het script wordt uitgevoerd. Window-, frame- en iframe-objecten verzenden de gebeurtenis dominitialize nadat een nieuw pagina-DOM is gemaakt maar voordat scripts zijn geparseerd of DOMelementen zijn toegevoegd. U kunt de gebeurtenis dominitialize gebruiken om de bridge al vroeg in de constructiesequentie van de pagina te creëren, zodat alle scripts in het onderliggende document toegang hebben tot de bridge. In het volgende voorbeeld ziet u hoe u een bovenliggende sandboxbridge kunt maken als reactie op de gebeurtenis dominitialize die vanuit het onderliggende frame is verzonden: <script> var bridgeInterface = {}; bridgeInterface.testProperty = "Bridge engaged"; function engageBridge(){ document.getElementById("sandbox").contentWindow.parentSandboxBridge = bridgeInterface; } <iframe id="sandbox" src="http://www.example.com/air/child.html" documentRoot="app:/" sandboxRoot="http://www.example.com/air/" ondominitialize="engageBridge()"/>

Het volgende document, child.html, illustreert hoe onderliggende inhoud de bovenliggende sandboxbridge kan benaderen: <script> document.write(window.parentSandboxBridge.testProperty);

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 239 Programmeren in HTML en JavaScript

Om zeker te zijn dat u naar de gebeurtenis dominitialize in een onderliggend venster luistert en niet naar een frame, moet u de listener aan het nieuwe onderliggende Window-object toevoegen, dat u creëert met de functie window.open(): var childWindow = window.open(); childWindow.addEventListener("dominitialize", engageBridge()); childWindow.document.location = "http://www.example.com/air/child.html";

In dit geval bestaat er geen mogelijkheid om toepassingsinhoud toe te wijzen aan een niet-toepassingssandbox. Deze techniek is alleen nuttig als child.html van buiten de toepassingsmap wordt geladen. U kunt toepassingsinhoud in het venster nog altijd aan een niet-toepassingssandbox toewijzen, maar in dat geval moet u eerst een tussenpagina laden die zelf frames gebruikt om het onderliggende document te laden, en deze pagina toewijzen aan de gewenste sandbox. Als u de functie createRootWindow() van de klasse HTMLLoader gebruikt om een venster te maken, is het nieuwe venster geen onderliggend element van het document waaruit createRootWindow() wordt opgeroepen. U kunt dus geen sandboxbridge maken tussen het oproepende venster en niet-toepassingsinhoud die in het nieuwe venster is geladen. In plaats daarvan moet u in het nieuwe venster een tussenpagina laden die zelf frames gebruikt om het onderliggende document te laden. U kunt vervolgens de bridge creëren tussen het bovenliggende document van het nieuwe venster en het onderliggende document dat in het frame is geladen.

240

Hoofdstuk 22: HTML-gerelateerde gebeurtenissen afhandelen Met een systeem voor gebeurtenisafhandeling kunnen programmeurs op een gemakkelijke manier reageren op gebruikersinvoer en systeemgebeurtenissen. Het Adobe® AIR™-gebeurtenismodel is heel handig in het gebruik en voldoet aan alle standaarden. Het gebeurtenismodel is gebaseerd op de DOM (Document Object Model) Level 3 Events Specification, een industriestandaard voor de gebeurtenisafhandelingsarchitectuur, en bevat een krachtig en toch intuïtief gebeurtenisafhandelingsmechanisme voor programmeurs.

HTMLLoader-gebeurtenissen Een HTMLLoader-object verzendt de volgende ActionScript™-gebeurtenissen: Gebeurtenis

Beschrijving

htmlDOMInitialize

Wordt verzonden wanneer het HTML-document wordt gemaakt, maar voordat scripts worden geparseerd of DOM-knooppunten worden toegevoegd aan de pagina.

complete

Wordt verzonden wanneer het HTML DOM is gemaakt als reactie op een laadbewerking onmiddellijk na de gebeurtenis onload in de HTML-pagina.

htmlBoundsChanged

Wordt verzonden wanneer een van de eigenschappen contentWidth of contentHeight (of allebei) is gewijzigd.

locationChange

Wordt verzonden wanneer de eigenschap location van de HTMLLoader is gewijzigd.

scroll

Wordt altijd verzonden wanneer de HTML-engine de scrollpositie wijzigt. Scroll-gebeurtenissen kunnen plaatsvinden vanwege navigatie naar ankerkoppelingen (#-koppelingen) op de pagina of vanwege het oproepen van de methode window.scrollTo(). De gebeurtenis scroll kan ook worden veroorzaakt door het invoeren van tekst in een tekstinvoergebied of tekstgebied.

uncaughtScriptException

Wordt verzonden wanneer in de HTMLLoader een JavaScript-uitzondering optreedt waarvoor geen voorziening is getroffen in de JavaScript-code.

U kunt ook een ActionScript-functie registreren voor een JavaScript-gebeurtenis (zoals onClick). Zie “DOMgebeurtenissen afhandelen met ActionScript” op pagina 240 voor meer informatie.

DOM-gebeurtenissen afhandelen met ActionScript U kunt ActionScript-functies registreren zodat ze reageren op JavaScript-gebeurtenissen. Kijk bijvoorbeeld naar de volgende HTML-inhoud: Click me.

U kunt een ActionScript-functie registreren als handler voor een willekeurige gebeurtenis in de pagina. Met de volgende code voegt u bijvoorbeeld de functie clickHandler() toe als listener voor de gebeurtenis onclick van het element testLink in de HTML-pagina:

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 241 HTML-gerelateerde gebeurtenissen afhandelen

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():void { trace("You clicked it!"); }

U kunt ook de methode addEventListener() gebruiken om te registreren voor deze gebeurtenissen. U kunt bijvoorbeeld de methode completeHandler() in het vorige voorbeeld vervangen door de volgende code: function completeHandler(event:Event):void { var testLink:Object = html.window.document.getElementById("testLink"); testLink.addEventListener("click", clickHandler); }

Wanneer een listener verwijst naar een specifiek DOM-element, is het aan te raden te wachten totdat de bovenliggende HTMLLoader de gebeurtenis complete heeft verzonden alvorens de gebeurtenislisteners toe te voegen. HTMLpagina's laden vaak meerdere bestanden en het HTML DOM wordt pas volledig samengesteld als alle bestanden zijn geladen en geparseerd. De HTMLLoader verzendt de gebeurtenis complete wanneer alle elementen zijn gemaakt.

Reageren op niet-onderschepte JavaScriptuitzonderingen Bekijk de volgende HTML-code: <script> function throwError() { var x = 400 * melbaToast; } Click me.

Deze bevat de JavaScript-functie throwError(), die verwijst naar de onbekende variabele melbaToast: var x = 400 * melbaToast;

Als een JavaScript-bewerking een ongeldige bewerking tegenkomt die niet in de JavaScript-code wordt onderschept via een try/catch-structuur, verzendt het HTMLLoader-object dat de pagina bevat, de gebeurtenis HTMLUncaughtScriptExceptionEvent. U kunt een handler voor deze gebeurtenis registreren, zoals in de volgende code:

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 242 HTML-gerelateerde gebeurtenissen afhandelen

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); } }

Binnen JavaScript kunt u dezelfde gebeurtenis afhandelen via de eigenschap window.htmlLoader: <script language="javascript" type="text/javascript" src="AIRAliases.js"> <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); Click me.

De gebeurtenishandler htmlErrorHandler() annuleert het standaardgedrag van de gebeurtenis (dat wil zeggen, het verzenden van een JavaScript-foutbericht naar de AIR trace-output) en genereert een eigen outputbericht. Deze output bevat de waarde van de exceptionValue van het HTMLUncaughtScriptExceptionEvent-object. De output bevat de eigenschappen van ieder object in de stackTrace-array:

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 243 HTML-gerelateerde gebeurtenissen afhandelen

exceptionValue: ReferenceError: Can't find variable: melbaToast sourceURL: app:/test.html line: 5 function: throwError sourceURL: app:/test.html line: 10 function: onclick

Runtimegebeurtenissen afhandelen met JavaScript De runtimeklassen ondersteunen het toevoegen van gebeurtenishandlers met de methode addEventListener(). Om een handlerfunctie voor een gebeurtenis toe te voegen, roept u de methode addEventListener() op van het object dat de gebeurtenis verzendt. U geeft hierbij het gebeurtenistype en de afhandelingsfunctie op. Als u bijvoorbeeld wilt luisteren naar de gebeurtenis closing die wordt verzonden wanneer een gebruiker op het sluitvak van een venster op de titelbalk klikt, gebruikt u de volgende opdracht: window.nativeWindow.addEventListener(air.NativeWindow.CLOSING, handleWindowClosing);

Gebeurtenishandlerfuncties maken Met de volgende code maakt u een eenvoudig HTML-bestand dat informatie weergeeft over de positie van het hoofdvenster. Een handlerfunctie met de naam moveHandler() luistert naar een verplaatsingsgebeurtenis (gedefinieerd door de klasse NativeWindowBoundsEvent) van het hoofdvenster. <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(); }

Window X:
Window Y:

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 244 HTML-gerelateerde gebeurtenissen afhandelen

Wanneer een gebruiker het venster verplaatst, geven de textarea-elementen de bijgewerkte X- en Y-positie van het venster weer: Het gebeurtenisobject wordt als argument doorgegeven aan de methode moveHandler(). Met de parameter event kan uw handlerfunctie het gebeurtenisobject onderzoeken. In dit voorbeeld gebruikt u de eigenschap type van het gebeurtenisobject om te rapporteren dat de gebeurtenis van het type move is.

Gebeurtenislisteners verwijderen U kunt de methode removeEventListener() gebruiken om een gebeurtenislistener te verwijderen die u niet meer nodig hebt. Het is raadzaam om alle listeners die niet meer worden gebruikt, te verwijderen. Vereiste parameters zijn onder meer de parameters eventName en listener. Dit zijn dezelfde vereiste parameters als voor de methode addEventListener().

Gebeurtenislisteners verwijderen in HTML-pagina's die navigeren Wanneer HTML-inhoud navigeert, of wanneer HTML-inhoud wordt verwijderd omdat een venster dat deze inhoud bevat wordt gesloten, worden de gebeurtenislisteners die verwijzen naar objecten op de ongeladen pagina, niet automatisch verwijderd. Wanneer een object een gebeurtenis verzendt naar een handler die al is verwijderd, wordt er een foutmelding weergegeven dat de toepassing heeft geprobeerd te verwijzen naar een JavaScript-object in een HTML-pagina die niet meer is geladen. Om deze fout te voorkomen, verwijdert u JavaScript-gebeurtenislisteners in een HTML-pagina voordat deze verdwijnt. In het geval van paginanavigatie (binnen een HTMLLoader-object) verwijdert u de gebeurtenislistener tijdens de gebeurtenis unload van het window-object. De volgende JavaScript-code verwijdert bijvoorbeeld een gebeurtenislistener voor de gebeurtenis uncaughtScriptException: window.onunload = cleanup; window.htmlLoader.addEventListener('uncaughtScriptException', uncaughtScriptException); function cleanup() { window.htmlLoader.removeEventListener('uncaughtScriptException', uncaughtScriptExceptionHandler); }

Om te voorkomen dat de fout optreedt wanneer vensters met HTML-inhoud worden gesloten, roept u een opschoningsfunctie op als reactie op de gebeurtenis closing van het NativeWindow-object (window.nativeWindow). De volgende JavaScript-code verwijdert bijvoorbeeld een gebeurtenislistener voor de gebeurtenis uncaughtScriptException: window.nativeWindow.addEventListener(air.Event.CLOSING, cleanup); function cleanup() { window.htmlLoader.removeEventListener('uncaughtScriptException', uncaughtScriptExceptionHandler); }

U kunt ook voorkomen dat deze fout optreedt door een gebeurtenislistener te verwijderen zodra deze is uitgevoerd. De volgende JavaScript-code maakt bijvoorbeeld een HTML-venster door de methode createRootWindow() van de klasse HTMLLoader op te roepen; hier wordt een gebeurtenislistener voor de gebeurtenis complete toegevoegd. Wanneer de gebeurtenishandler complete wordt opgeroepen, verwijdert deze zijn eigen gebeurtenislistener met behulp van de functie removeEventListener():

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 245 HTML-gerelateerde gebeurtenissen afhandelen

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"));

Door overbodige gebeurtenislisteners te verwijderen, kan de opschoonfunctie van het systeem ook het geheugen vrijmaken dat is gekoppeld aan die listeners.

Controleren op bestaande gebeurtenislisteners Met de methode hasEventListener() kunt u controleren op de aanwezigheid van gebeurtenislisteners op een object.

246

Hoofdstuk 23: Scripts schrijven voor de HTML-container De klasse HTMLLoader fungeert als container voor HTML-inhoud in Adobe® AIR™. De klasse biedt talrijke eigenschappen en methoden, die zijn overgenomen van de klasse Sprite en waarmee u het gedrag en de weergave van het object in de ActionScript™ 3.0-weergavelijst kunt bepalen. Daarnaast definieert de klasse eigenschappen en methoden voor taken zoals het laden van en interageren met HTML-inhoud en het beheren van het historisch overzicht. De klasse HTMLHost definieert een set van standaardgedragingen voor een HTMLLoader. Wanneer u een HTMLLoader-object maakt, wordt niet voorzien in HTMLHost-implementatie. Dit betekent dat er niets gebeurt wanneer HTML-inhoud een van de standaardgedragingen activeert, zoals het wijzigen van de vensterlocatie of -titel. U kunt de klasse HTMLHost zo uitbreiden dat deze de gewenste gedragingen voor uw toepassing definieert. Voor HTML-vensters die met AIR worden gemaakt, is voorzien in een standaardimplementatie van de HTMLHost. U kunt deze standaard HTMLHost-implementatie aan een ander HTMLLoader-object toewijzen door de eigenschap htmlHost van het object in te stellen met een nieuw HTMLHost-object dat is gemaakt met de parameter defaultBehavior op true.

Eigenschappen van HTMLLoader-objecten weergeven Een HTMLLoader-object neemt de weergave-eigenschappen van de Adobe® Flash® Player-klasse Sprite. U kunt bijvoorbeeld vergroten, verkleinen, verplaatsen, verbergen en een andere achtergrondkleur selecteren. U kunt ook geavanceerde effecten toepassen, zoals filters, maskers, schaalinstelling en roteren. Houd bij het toepassen van effecten rekening met invloed op de leesbaarheid. SWF- en PDF-inhoud in een HTML-pagina kan niet worden weergegeven bij het toepassen van bepaalde effecten. HTML-vensters bevatten een HTMLLoader-object dat de HTML-inhoud rendert. Aangezien dit object beperkt is tot het venstergebied, heeft het wijzigen van de afmetingen of positie, roteren of schalen niet altijd het gewenste resultaat.

Basisweergave-eigenschappen Met de basisweergave-eigenschappen van de HTMLLoader kunt u het besturingselement binnen het hoofdweergaveobject positioneren, de afmetingen instellen en weergeven/verbergen. U wordt aangeraden deze eigenschappen niet te wijzigen voor het HTMLLoader-object van een HTML-venster. Dit zijn de basiseigenschappen: Eigenschap

Opmerkingen

x, y

Positioneert het object binnen zijn hoofdcontainer.

width, height

Wijzigt de afmetingen van het weergavegebied.

visible

Regelt de zichtbaarheid van het object en eventuele inhoud ervan.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 247 Scripts schrijven voor de HTML-container

Aan de buitenkant van een HTML-venster zijn de eigenschappen width en height van een HTMLLoader-object standaard ingesteld op 0. U moet de breedte en hoogte instellen om de geladen HTML-inhoud zichtbaar te maken. HTML-inhoud is gekoppeld aan de HTMLLoader-afmetingen. De opmaak is afhankelijk van de HTML- en CSSeigenschappen van de inhoud. Wanneer u de HTMLLoader-afmetingen wijzigt, wordt de loop van de inhoud aangepast. Bij het laden van inhoud in een nieuw HTMLLoader-object (waarbij width nog altijd op 0 staat), kan het verleidelijk zijn om de waarden width en height voor de weergave van de HTMLLoader in te stellen met behulp van de eigenschappen contentWidth en contentHeight. Deze techniek werkt bij pagina's met een redelijke minimumbreedte die worden opgemaakt volgens de HTML- en CSS-regels voor de tekstloop. Sommige pagina's hebben echter een lange, smalle loop omdat er geen redelijke breedte is opgegeven door de HTMLLoader. Opmerking: Wanneer u de breedte en hoogte van een HTMLLoader-object wijzigt, veranderen de waarden scaleX en scaleY niet, wat wel het geval is bij de meeste andere typen van weergaveobjecten.

Transparantie van HTMLLoader-inhoud De eigenschap paintsDefaultBackground van een HTMLLoader-object, die standaard op true is ingesteld, bepaalt of het HTMLLoader-object een ondoorzichtige achtergrond heeft. Als paintsDefaultBackground is ingesteld op false, is de achtergrond doorzichtig. De weergaveobjectcontainer of andere weergaveobjecten onder het HTMLLoader-object zijn zichtbaar achter de voorgrondelementen van de HTML-inhoud. Als het hoofdelement of een ander element van het HTML-document een achtergrondkleur opgeeft (bijvoorbeeld via style="background-color:gray"), is de achtergrond van het desbetreffende deel van de HTML-inhoud

ondoorzichtig en wordt het gerenderd met de opgegeven achtergrondkleur. Als u de eigenschap opaqueBackground van het HTMLLoader-object instelt en paintsDefaultBackground op false staat, is de kleur van opaqueBackground zichtbaar. Opmerking: U kunt een transparante afbeelding met PNG-indeling gebruiken om een achtergrond met alfa-overvloeiing te bieden voor een element in een HTML-document. Het instellen van de doorzichtigheidsstijl van een HTML-element wordt niet ondersteund.

HTMLLoader-inhoud schalen Het wordt niet aangeraden een HTMLLoader-object met een factor van meer dan 1,0 te schalen. Tekst in HTMLLoader-inhoud wordt naar een specifieke resolutie gerenderd en vertoont pixels als het HTMLLoader-object te veel wordt geschaald. Als u wilt voorkomen dat het HTMLLoader-object en zijn inhoud worden geschaald bij het vergroten/verkleinen van een venster, stelt u de eigenschap scaleMode van de stage in op StageScaleMode.NO_SCALE.

Belangrijke opmerkingen voor het laden van SWF- of PDF-inhoud in een HTML-pagina In de volgende gevallen verdwijnt SWF- en PDF-inhoud die in een HTMLLoader-object is geladen:

• als u het HTMLLoader-object schaalt met een andere factor dan 1.0; • als u de alfa-eigenschap van het HTMLLoader-object instelt op een andere waarde dan 1,0; • als u de HTMLLoader-inhoud roteert. De inhoud verschijnt weer als u de conflicterende eigenschapinstelling en de actieve filters verwijdert. Opmerking: Het runtime-programma kan geen SWF- of PDF-inhoud in transparante vensters weergeven.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 248 Scripts schrijven voor de HTML-container

Zie SWF-inhoud laden in een HTML-pagina en “PDF-inhoud toevoegen” op pagina 260voor meer informatie over het laden van deze mediatypen in een HTMLLoader.

Geavanceerde weergave-eigenschappen De klasse HTMLLoader neemt verschillende methoden over die voor speciale effecten kunnen worden gebruikt. Normaliter hebben deze effecten weliswaar beperkingen wanneer ze worden gebruikt voor HTMLLoader-weergave, maar ze kunnen nuttig zijn voor overgangen of andere tijdelijke effecten. Als u bijvoorbeeld een dialoogvenster weergeeft om gebruikersinvoer op te halen, kunt u de weergave van het hoofdvenster vaag maken tot de gebruiker het dialoogvenster heeft gesloten. Evenzo kunt u de weergave uitfaden bij het sluiten van een venster. Dit zijn de geavanceerde weergave-eigenschappen: Eigenschap

Beperkingen

alpha

Kan de leesbaarheid van HTML-inhoud verminderen.

filters

In een HTML-venster worden buiteneffecten bijgesneden door de vensterrand.

graphics

Vormen die met grafische opdrachten worden getekend, verschijnen onder HTML-inhoud, inclusief de standaardachtergrond. Als de getekende vormen zichtbaar moeten zijn, moet de eigenschap paintsDefaultBackground op 'false' staan.

opaqueBackground

De kleur van de standaardachtergrond wordt niet gewijzigd. Als deze kleurlaag zichtbaar moet zijn, moet de eigenschap paintsDefaultBackground op 'false' staan.

rotation

De hoeken van het rechthoekige HTMLLoader-gebied kan door de vensterrand worden bijgesneden. SWF- en PDF-inhoud die in de HTML-inhoud wordt geladen, is niet zichtbaar.

scaleX, scaleY

De gerenderde weergave kan pixels vertonen bij een schaalfactor van meer dan 1. SWF- en PDF-inhoud die in de HTML-inhoud wordt geladen, is niet zichtbaar.

transform

Kan de leesbaarheid van HTML-inhoud verminderen. De HTML-weergave kan door de vensterrand worden bijgesneden. SWF- en PDF-inhoud die in de HTML-inhoud wordt geladen, is niet zichtbaar als roteren, schalen of scheeftrekken wordt toegepast tijdens de transformatie.

In het volgende voorbeeld ziet u hoe u de array filters instelt om de volledige HTML-weergave vaag te maken: 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;

HTML-inhoud schuiven De klasse HTMLLoader bevat de volgende eigenschappen waarmee u het schuiven van HTML-inhoud kunt bepalen:

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 249 Scripts schrijven voor de HTML-container

Eigenschap

Beschrijving

contentHeight

De hoogte van de HTML-inhoud in pixels.

contentWidth

De breedte van de HTML-inhoud in pixels.

scrollH

De horizontale schuifpositie van de HTML-inhoud binnen het HTMLLoader-object.

scrollV

De verticale schuifpositie van de HTML-inhoud binnen het HTMLLoader-object.

De volgende code stelt de eigenschap scrollV zo in dat de HTML-inhoud naar de onderkant van de pagina wordt geschoven: 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; }

Het HTMLLoader-object bevat geen horizontale en verticale schuifbalken. U kunt deze desgewenst toevoegen met ActionScript. U kunt ook de methode HTMLLoader.createRootWindow() gebruiken om een venster te maken dat een HTMLLoader-object met schuifbalken bevat (zie “Vensters met schuivende HTML-inhoud maken” op pagina 258).

Historisch overzicht van HTML openen Wanneer nieuwe pagina's in een HTMLLoader-object worden geladen, worden deze geregistreerd in het historisch overzicht van het object. Dit overzicht komt overeen met het object window.history op de HTML-pagina. De klasse HTMLLoader bevat de volgende eigenschappen en methoden waarmee u met het historisch overzicht van HTML kunt werken: Lid van klasse

Beschrijving

historyLength

De totale lengte van het historisch overzicht, inclusief vooruit- en achteruit-items.

historyPosition

De huidige positie in het historisch overzicht. Items die vóór deze positie in het overzicht staan, vertegenwoordigen navigatie “achteruit”, items na deze positie geven navigatie “vooruit” aan.

historyAt()

Geeft het URLRequest-object weer dat overeenkomt met het item op de opgegeven positie in het historisch overzicht.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 250 Scripts schrijven voor de HTML-container

Lid van klasse

Beschrijving

historyBack()

Keert indien mogelijk terug in het historisch overzicht.

historyForward()

Keert indien mogelijk terug in het historisch overzicht.

historyGo()

Gaat het opgegeven aantal stappen vooruit of achteruit in het historisch overzicht. Gaat vooruit als de waarde positief is, en keert terug als de waarde negatief is. Wanneer nul wordt bereikt, wordt de pagina opnieuw geladen. Als u een positie verder dan het einde opgeeft, wordt het einde van het overzicht weergegeven.

De items uit het overzicht worden opgeslagen als objecten van het type HistoryListItem. De klasse HistoryListItem heeft de volgende eigenschappen: Eigenschap

Beschrijving

isPost

Zet op true als de HTML-pagina POST-gegevens bevat.

originalUrl

De oorspronkelijke URL van de HTML-pagina, vóór eventueel doorsturen.

title

De titel van de HTML-pagina.

url

De URL van de HTML-pagina.

Gebruikersagent voor het laden van HTML-inhoud instellen De klasse HTMLLoader heeft een eigenschap userAgent, waarmee u de gebruikersagent-tekenreeks kunt instellen die door de HTMLLoader wordt gebruikt. Stel de eigenschap userAgent van het HTMLLoader-object in voordat u de methode load() oproept. Als u deze eigenschap op de HTMLLoader-instantie instelt, wordt de eigenschap userAgent van de URLRequest die wordt verzonden naar de methode load(), niet gebruikt. U kunt de standaard gebruikersagent-tekenreeks die door alle HTMLLoader-objecten in een toepassingsdomein wordt gebruikt, instellen via de eigenschap URLRequestDefaults.userAgent. De statische URLRequestDefaultseigenschappen gelden als standaardinstellingen voor alle URLRequest-objecten, niet alleen voor URLRequests die worden gebruikt met de methode load() van HTMLLoader-objecten. Wanneer u de eigenschap userAgent van een HTMLLoader-object instelt, overschrijft u de standaardinstelling URLRequestDefaults.userAgent. Als u geen gebruikersagent instelt voor de eigenschap userAgent van het HTMLLoader-object of voor URLRequestDefaults.userAgent, wordt de standaardwaarde van de AIR-gebruikersagent gebruikt. Deze standaardwaarde is afhankelijk van het runtime-besturingssysteem (bijvoorbeeld Mac OS of Windows), de runtimetaal en de runtime, zoals in de volgende twee voorbeelden wordt geïllustreerd:

•

"Mozilla/5.0 (Macintosh; U; PPC Mac OS X; en) AppleWebKit/420+ (KHTML, like Gecko) AdobeAIR/1.0"

•

"Mozilla/5.0 (Windows; U; en) AppleWebKit/420+ (KHTML, like Gecko) AdobeAIR/1.0"

Tekencodering voor HTML-inhoud instellen Een HTML-pagina kan de te gebruiken tekencodering instellen door de tag meta op te nemen, zoals in het volgende voorbeeld: meta http-equiv="content-type" content="text/html" charset="ISO-8859-1";

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 251 Scripts schrijven voor de HTML-container

Overschrijf de pagina-instelling om te zorgen dat een specifieke tekencodering wordt gebruikt. Stel hiervoor de eigenschap textEncodingOverride van het HTMLLoader-object in: var html:HTMLLoader = new HTMLLoader(); html.textEncodingOverride = "ISO-8859-1";

Geef de tekencodering voor HTMLLoader-inhoud op die moet worden gebruikt wanneer een HTML-pagina geen instelling opgeeft. Stel hiervoor de eigenschap textEncodingFallback van het HTMLLoader-object in: var html:HTMLLoader = new HTMLLoader(); html.textEncodingFallback = "ISO-8859-1";

De eigenschap textEncodingOverride overschrijft de instelling in de HTML-pagina. En de eigenschap textEncodingOverride en de instelling in de HTML-pagina overschrijven de eigenschap textEncodingFallback. Stel de eigenschap textEncodingOverride of de eigenschap textEncodingFallback in voordat de HTML-inhoud wordt geladen.

Gebruikersinterfaces van het type browser definiëren voor HTML-inhoud JavaScript biedt meerdere API's waarmee u bepaalt in welk venster de HTML-inhoud wordt weergegeven. In AIR kunt u deze API's negeren door een aangepaste HTMLHost-klasse te implementeren.

Informatie over het uitbreiden van de klasse HTMLHost Als uw toepassing bijvoorbeeld meerdere HTMLLoader-objecten in een venster met tabbladen weergeeft, kunt u zorgen dat titelwijzigingen door de geladen HTML-pagina's worden doorgevoerd in het label van het tabblad, en niet in de titel van het hoofdvenster. Zo kan uw code bijvoorbeeld op een oproep window.moveTo() reageren door het HTMLLoader-object in de hoofdweergaveobjectcontainer opnieuw te positioneren door het venster met het HTMLLoader-object te verplaatsen, door niets te doen of door iets helemaal anders te doen. De AIR-klasse HTMLHost regelt de volgende JavaScript-eigenschappen en -methoden:

•

window.status

•

window.document.title

•

window.location

•

window.blur()

•

window.close()

•

window.focus()

•

window.moveBy()

•

window.moveTo()

•

window.open()

•

window.resizeBy()

•

window.resizeTo()

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 252 Scripts schrijven voor de HTML-container

Wanneer u een HTMLLoader-object met behulp van new HTMLLoader() maakt, zijn de weergegeven JavaScripteigenschappen of -methoden niet ingeschakeld. De klasse HTMLHost biedt een standaardimplementatie van deze JavaScript-API's in de vorm van een browser. U kunt ook de klasse HTMLHost uitbreiden om het gedrag aan te passen. Als u een HTMLHost-object wilt maken dat het standaardgedrag ondersteunt, stelt u de parameter defaultBehaviors in op 'true' in de HTMLHost-constructor: var defaultHost:HTMLHost = new HTMLHost(true);

Als u in AIR een HTML-venster maakt via de methode createRootWindow() van de klasse HTMLLoader, wordt automatisch een HTMLHost-instantie toegewezen die de standaardgedragingen ondersteunt. U kunt het gedrag van het hostobject wijzigen door een andere HTMLHost-implementatie toe te wijzen aan de eigenschap htmlHost van de HTMLLoader, of u kunt null instellen om de voorzieningen volledig uit te schakelen. Opmerking: AIR wijst een standaard HTMLHost-object toe aan het beginvenster dat voor een op HTML gebaseerde AIRtoepassing is gemaakt, evenals aan alle vensters die zijn gemaakt via de standaardimplementatie van de JavaScriptmethode window.open().

Voorbeeld: de klasse HTMLHost uitbreiden In het volgende voorbeeld ziet u hoe u door het uitbreiden van de klasse HTMLHost de manier wijzigt waarop een HTMLLoader-object de gebruikersinterface beïnvloedt: 1 Maak een Flash-bestand voor AIR. Stel de documentklasse in op CustomHostExample en sla het bestand op als

CustomHostExample.fla. 2 Maak een ActionScript-bestand met de naam CustomHost.as en zorg dat het een klasse bevat die de klasse

HTMLHost uitbreidt (een subklasse). Deze klasse negeert bepaalde methoden van de nieuwe klasse om wijzigingen in de instellingen van de gebruikersinterface te verwerken. De volgende klasse, CustomHost, definieert bijvoorbeeld gedragingen voor oproepen van window.open() en wijzigingen in window.document.title. Oproepen van de methode window.open() openen de HTML-pagina in een nieuw venster en wijzigingen in de eigenschap window.document.title (zoals de instelling van het element <script> function openWindow() { document.title = "Test" window.open('Test.html'); } window.open('Test.html')
window.document.location = 'http://www.adobe.com'
moveBy(6, 12)
window.close()
window.blur()
window.focus()
window.status=new Date().toString()

Wijzigingen in de eigenschap window.location verwerken Hef de methode locationChange() op om wijzigingen in de URL van de HTML-pagina te verwerken. De methode locationChange() wordt opgeroepen wanneer JavaScript in een pagina de waarde van window.location wijzigt. In het volgende voorbeeld wordt gewoon de gevraagde URL geladen: override public function updateLocation(locationURL:String):void { htmlLoader.load(new URLRequest(locationURL)); }

Opmerking: U kunt de eigenschap htmlLoader van het HTMLHost-object gebruiken om naar het huidige HTMLLoaderobject te verwijzen.

JavaScript-oproepen van window.moveBy(), window.moveTo(), window.resizeTo() of window.resizeBy() afhandelen Hef de methode set windowRect() op om wijzigingen in de grenzen van de HTML-inhoud af te handelen. De methode set windowRect() wordt opgeroepen wanneer JavaScript in een pagina window.moveBy(), window.moveTo(), window.resizeTo() of window.resizeBy() oproept. In het volgende voorbeeld worden gewoon de grenzen van het bureaubladvenster bijgewerkt: override public function set windowRect(value:Rectangle):void { htmlLoader.stage.nativeWindow.bounds = value; }

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 256 Scripts schrijven voor de HTML-container

JavaScript-oproepen van window.open() afhandelen Hef de methode createWindow() op om JavaScript-oproepen van window.open() af te handelen. Implementaties van de methode createWindow() zijn verantwoordelijk voor het maken en retourneren van een nieuw HTMLLoader-object. U geeft de HTMLLoader doorgaans in een nieuw venster weer maar het is niet nodig om een venster te maken. In het volgende voorbeeld ziet u hoe u de functie createWindow() implementeert met behulp van HTMLLoader.createRootWindow() om zowel het venster als het HTMLLoader-object te maken. U kunt ook afzonderlijk een NativeWindow-object maken en het HTMLLoader-object toevoegen aan de vensterfase. 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; }

Opmerking: In dit voorbeeld wordt de aangepaste HTMLHost-implementatie toegewezen aan eventuele nieuwe vensters die met window.open() zijn gemaakt. U kunt desgewenst ook een andere implementatie gebruiken of de eigenschap htmlHost op 'null' instellen voor nieuwe vensters. Het object dat als een parameter aan de methode createWindow() wordt toegewezen, is een HTMLWindowCreateOptions-object. De klasse HTMLWindowCreateOptions bevat eigenschappen die de waarden rapporteren die zijn ingesteld in de parametertekenreeks features voor het oproepen van window.open(): HTMLWindowCreateOptions-eigenschap

Overeenkomstige instelling in de functietekenreeks in de JavaScript-oproep van window.open()

fullscreen

fullscreen

height

height

locationBarVisible

location

menuBarVisible

menubar

resizeable

resizable

scrollBarsVisible

scrollbars

statusBarVisible

status

toolBarVisible

toolbar

width

width

x

left of screenX

y

top of screenY

De klasse HTMLLoader implementeert niet alle functies die in de functietekenreeks kunnen worden opgegeven. Uw toepassing moet wanneer nodig schuif-, locatie-, menu-, status- en werkbalken definiëren.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 257 Scripts schrijven voor de HTML-container

De overige argumenten voor de methode JavaScript window.open() worden door het systeem verwerkt. Een implementatie van createWindow() laadt normaliter geen inhoud in het HTMLLoader-object en stelt de venstertitel niet in.

JavaScript-oproepen van window.close() afhandelen Hef windowClose() op om JavaScript-oproepen van de methode window.close() af te handelen. In het volgende voorbeeld wordt het bureaubladvenster gesloten wanneer de methode window.close() wordt opgeroepen: override public function windowClose():void { htmlLoader.stage.nativeWindow.close(); }

JavaScript-oproepen van window.close() hoeven het inhoudsvenster niet te sluiten. U kunt bijvoorbeeld het HTMLLoader-object uit de weergavelijst verwijderen zonder het venster (dat nog andere inhoud kan bevatten) te sluiten. Dit wordt geïllustreerd door de volgende code: override public function windowClose():void { htmlLoader.parent.removeChild(htmlLoader); }

Wijzigingen in de eigenschap window.status verwerken Hef de methode updateStatus() op om JavaScript-wijzigingen in de waarde van window.status te verwerken. In het volgende voorbeeld wordt de statuswaarde getraceerd: override public function updateStatus(status:String):void { trace(status); }

De gevraagde status wordt als een tekenreeks verzonden naar de methode updateStatus(). Het HTMLLoader-object zorgt niet voor een statusbalk.

Wijzigingen in de eigenschap window.document.title verwerken Hef de methode updateTitle() op om JavaScript-wijzigingen in de waarde van window.document.title te verwerken. In het volgende voorbeeld wordt de venstertitel gewijzigd en de tekenreeks "Sample," toegevoegd aan de titel: override public function updateTitle(title:String):void { htmlLoader.stage.nativeWindow.title = title + " - Sample"; }

Als document.title is ingesteld op een HTML-pagina, wordt de gevraagde titel als een tekenreeks verzonden naar de methode updateTitle(). Wijzigingen in document.title hoeven de titel van het venster met het HTMLLoader-object niet te wijzigen. U kunt bijvoorbeeld een ander interface-element wijzigen, zoals een tekstveld.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 258 Scripts schrijven voor de HTML-container

JavaScript-oproepen van window.blur() en window.focus() afhandelen Hef de methoden windowBlur() en windowFocus() op om JavaScript-oproepen van window.blur() en window.focus() af te handelen, zoals in het volgende voorbeeld wordt geïllustreerd: override public function windowBlur():void { htmlLoader.alpha = 0.5; } override public function windowFocus():void { htmlLoader.alpha = 1.0; NativeApplication.nativeApplication.activate(htmlLoader.stage.nativeWindow); }

Opmerking: AIR biedt geen API voor het uitschakelen van een venster of toepassing.

Vensters met schuivende HTML-inhoud maken De klasse HTMLLoader bevat de statische methode HTMLLoader.createRootWindow(), waarmee u een nieuw venster (vertegenwoordigd door een NativeWindow-object) kunt openen dat een HTMLLoader-object bevat en waarmee u bepaalde gebruikersinterface-instellingen voor het desbetreffende venster kunt definiëren. De methode vereist het instellen van vier parameters, waarmee u de gebruikersinterface kunt definiëren: Parameter

Beschrijving

visible

Een Booleaanse waarde die bepaalt of het venster in eerste instantie zichtbaar is (true) of niet (false).

windowInitOptions

Een NativeWindowInitOptions-object. De klasse NativeWindowInitOptions definieert initialisatieopties voor een NativeWindow-object, zoals de volgende opties: of het venster kan worden geminimaliseerd/gemaximaliseerd of vergroot/verkleind, of het venster de systeeminterface of een aangepaste interface gebruikt, of het venster transparant is (bij vensters die niet de systeeminterface gebruiken), en het type van het venster.

scrollBarsVisible

Bepaalt of er schuifbalken zijn (true) of niet (false).

bounds

Een rechthoekig object dat de positie en afmetingen van het nieuwe venster definieert.

De volgende code bijvoorbeeld gebruikt de methode HTMLLoader.createRootWindow() om een venster te maken dat schuifbalken gebruikt en HTMLLoader-inhoud bevat: 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();

Opmerking: Vensters die zijn gemaakt door het rechtstreeks in JavaScript oproepen van createRootWindow(), blijven onafhankelijk van het HTML-venster dat wordt geopend. De JavaScript-venstereigenschappen opener en parent bijvoorbeeld staan op null. Als u createRootWindow() echter onrechtstreeks oproept door de HTMLHost-methode createWindow() op te heffen om createRootWindow() op te roepen, verwijzen opener en parent naar het HTMLvenster dat wordt geopend.

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 259 Scripts schrijven voor de HTML-container

Subklassen van de klasse HTMLLoader maken U kunt een subklasse van de klasse HTMLLoader maken om nieuwe gedragingen te creëren. U kunt bijvoorbeeld een subklasse maken die standaardlisteners voor HTMLLoader-gebeurtenissen definieert (zoals de gebeurtenissen die worden verzonden bij het renderen van HTML of wanneer de gebruiker op een koppeling klikt). In het volgende voorbeeld wordt de klasse HTMLHost uitgebreid om normaal gedrag te vertonen wanneer de JavaScript-methode window.open() wordt opgeroepen. Vervolgens wordt in het voorbeeld een subklasse van HTMLLoader gedefinieerd die de aangepaste HTMLHost-implementatieklasse gebruikt: 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 } }

De volgende code definieert een subklasse van de klasse HTMLLoader die een MyHTMLHost-object toewijst aan zijn eigenschap htmlHost: package { import flash.html.HTMLLoader; import MyHTMLHost; import HTMLLoader; public class MyHTML extends HTMLLoader { public function MyHTML() { super(); htmlHost = new MyHTMLHost(); } } }

Zie Gebruikersinterfaces van het type browser definiëren voor HTML-inhoud voor meer informatie over de klasse HTMLHost en de methode “Gebruikersinterfaces van het type browser definiëren voor HTML-inhoud” op pagina 251die in dit voorbeeld wordt gebruikt.

260

Hoofdstuk 24: PDF-inhoud toevoegen Toepassingen die in Adobe® AIR™ worden uitgevoerd, kunnen niet alleen SWF- en HTML-inhoud renderen, maar ook PDF-inhoud. AIR-toepassingen renderen PDF-inhoud met behulp van de klasse HTMLLoader, de WebKit-engine en de Adobe® Reader® plug-in voor de browser. In een AIR-toepassing kan PDF-inhoud gelden voor de volledige hoogte en breedte van uw toepassing of slechts voor een deel van de interface. De Adobe Reader plug-in voor de browser regelt de weergave van PDF-bestanden in een AIR-toepassing, zodat wijzigingen in de werkbalkinterface van Adobe Reader (bijvoorbeeld voor positionering, verankering en zichtbaarheid) ook gelden wanneer de PDF-bestanden later in AIRtoepassingen en in de browser worden bekeken. Belangrijk: Om PDF-inhoud in AIR te renderen, moet Adobe Reader of Adobe® Acrobat® versie 8.1 of hoger op de computer van de gebruiker zijn geïnstalleerd.

PDF-mogelijkheden detecteren Als Adobe Reader of Adobe Acrobat 8.1 of hoger niet op de computer van de gebruiker is geïnstalleerd, wordt PDFinhoud niet weergegeven in een AIR-toepassing. Om na te gaan of een gebruiker PDF-inhoud kan renderen, moet u eerst de eigenschap HTMLLoader.pdfCapability controleren. Deze eigenschap is ingesteld op een van de volgende constanten uit de klasse HTMLPDFCapability. Constante

Beschrijving

HTMLPDFCapability.STATUS_OK

Een geschikte versie (8.1 of hoger) van Adobe Reader is gedetecteerd en PDF-inhoud kan in een HTMLLoader-object worden geladen.

HTMLPDFCapability.ERROR_INSTALLED_READER_NOT_FOUND

Geen versie van Adobe Reader gedetecteerd. HTMLLoader-objecten kunnen geen PDF-inhoud weergeven.

HTMLPDFCapability.ERROR_INSTALLED_READER_TOO_OLD

Adobe Reader is gedetecteerd maar de versie is te oud. HTMLControl-objecten kunnen geen PDF-inhoud weergeven.

HTMLPDFCapability.ERROR_PREFERRED_READER_TOO_OLD

Een geschikte versie (8.1 of hoger) van Adobe Reader is gedetecteerd maar de versie van Adobe Reader die is ingesteld om PDF-inhoud af te handelen, is ouder dan Reader 8.1. HTMLControl-objecten kunnen geen PDF-inhoud weergeven.

Opmerking: Als Adobe Acrobat of Adobe Reader versie 7.x of hoger momenteel op het Windows-systeem van de gebruiker wordt uitgevoerd, wordt die versie gebruikt, zelfs als een recentere versie is geïnstalleerd die het laden van PDFinhoud ondersteunt. Als in dit geval de waarde van de eigenschap pdfCampability is ingesteld op HTMLPDFCapability.STATUS_OK en een AIR-toepassing PDF-inhoud probeert te laden, geeft de oudere versie van Acrobat of Reader een waarschuwing weer (er wordt geen uitzondering gegenereerd in de AIR-toepassing). Als deze situatie zich bij uw eindgebruikers kan voordoen, kunt u instructies opgeven om Acrobat te sluiten terwijl uw toepassing wordt uitgevoerd. U wordt aangeraden deze instructies weer te geven als de PDF-inhoud niet binnen een aanvaardbare tijd wordt geladen. De volgende code controleert of een gebruiker PDF-inhoud in een AIR-toepassing kan weergeven. Als dit niet het geval is, wordt de foutcode getraceerd die overeenkomt met het HTMLPDFCapability-foutobject:

ONTWIKKELING VAN ADOBE AIR 1.1-TOEPASSINGEN MET FLASH CS4 PROFESSIONAL 261 PDF-inhoud toevoegen

if(HTMLLoader.pdfCapability == HTMLPDFCapability.STATUS_OK) { trace("PDF content can be displayed"); } else { trace("PDF cannot be displayed. Error code:", HTMLLoader.pdfCapability); }

PDF-inhoud laden U kunt een PDF toevoegen aan een AIR-toepassing door een HTMLLoader-instantie te maken, de afmetingen ervan in te stellen en het pad van een PDF te laden. In het volgende voorbeeld ziet u hoe u een PDF vanaf een externe site laadt. Vervang de URLRequest door het pad naar een beschikbare externe PDF. 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);

U kunt ook inhoud laden vanaf bestands-URL's en AIR-specifieke URL-schema's, zoals app en app-storage. Voorbeeld: de volgende code laadt het bestand test.pdf naar de PDF-submap van de toepassingsmap: app:/js_api_reference.pdf Zie “URL-schema's van AIR gebruiken in URL's” op pagina 292 voor meer informatie over URL-schema's van AIR.

Scripting van PDF-inhoud U kunt JavaScript gebruiken om PDF-inhoud te besturen, net zoals in een webpagina in de browser. JavaScript-extensies voor Acrobat bieden onder andere de volgende mogelijkheden:

• Paginanavigatie en vergroting regelen • Formulieren in het document verwerken • Multimediagebeurtenissen besturen Meer informatie over JavaScript-extensies voor Adobe Acrobat vindt u in Adobe Acrobat Developer Connection op http://www.adobe.com/devnet/acrobat/javascript.html.

Basisinformatie over PDF-communicatie in HTML JavaScript in een HTML-pagina kan een bericht naar JavaScript in PDF-inhoud versturen door de methode postMessage() op te roepen van het DOM-object dat de PDF-inhoud voorstelt. U hebt bijvoorbeeld de volgende ingesloten PDF-inhoud: