Definizione di interfacce simili a browser per il contenuto HTML

Adobe AIR 1.0 e versioni successive

Informazioni sull'estensione della classe HTMLHost
Esempio: estensione della classe HTMLHost
Gestione delle modifiche alla proprietà window.location
Gestione delle chiamate JavaScript a window.moveBy(), window.moveTo(), window.resizeTo(), window.resizeBy()
Gestione delle chiamate JavaScript a window.open()
Chiamate Handling JavaScript a window.close()
Gestione delle modifiche alla proprietà window.status
Gestione delle modifiche alla proprietà window.document.title
Gestione delle chiamate JavaScript a window.blur() e window.focus()
Creazione di finestra con contenuto HTML scorrevole

JavaScript include diverse API per il controllo della finestra in cui è visualizzato il contenuto HTML. In AIR, queste API possono essere ignorate mediante l'implementazione di una classe HTMLHost personalizzata.

Informazioni sull'estensione della classe HTMLHost

Se, ad esempio, la vostra applicazione presenta più oggetti HTMLLoader in un'interfaccia a schede, può essere utile che le modifiche apportate dalle pagine HTML caricate si riflettano nella modifica dell'etichetta della scheda, anziché del titolo della finestra principale. In modo analogo, il codice potrebbe rispondere a una chiamata a window.moveTo() riposizionando l'oggetto HTMLLoader nel relativo contenitore di oggetti di visualizzazione principale, spostando la finestra che contiene l'oggetto HTMLLoader, non eseguendo alcuna operazione o effettuando una qualsiasi altra operazione.

La classe AIR HTMLHost controlla i seguenti metodi e proprietà JavaScript:

window.status
window.document.title
window.location
window.blur()
window.close()
window.focus()
window.moveBy()
window.moveTo()
window.open()
window.resizeBy()
window.resizeTo()

Quando create un oggetto HTMLLoader usando new HTMLLoader() , i metodi o le proprietà JavaScript non vengono abilitati. La classe HTMLHost fornisce un'implementazione predefinita simile a un browser di queste API JavaScript. Potete anche estendere la classe HTMLHost per personalizzare il comportamento. Per creare un oggetto HTMLHost che supporta il comportamento predefinito, impostate il parametro defaultBehaviors su true nella funzione di costruzione HTMLHost:

var defaultHost:HTMLHost = new HTMLHost(true);

Quando create una finestra HTML in AIR con il metodo createRootWindow() della classe HTMLLoader, viene assegnata automaticamente un'istanza HTMLHost che supporta i comportamenti predefiniti. Potete modificare il comportamento dell'oggetto host assegnando una diversa implementazione di HTMLHost alla proprietà htmlHost di HTMLLoader, oppure potete assegnare null per disabilitare completamente le funzioni.

Nota: AIR assegna un oggetto HTMLHost predefinito alla finestra iniziale creata per un'applicazione AIR basata su HTML e a qualsiasi finestra creata dall'implementazione predefinita del metodo JavaScript window.open() .

Esempio: estensione della classe HTMLHost

Il seguente esempio mostra come personalizzare il modo in cui un oggetto HTMLLoader ha effetto sull'interfaccia utente, mediante l'estensione della classe HTMLHost:

Esempio Flex:

Create una classe che estende la classe HTMLHost (una sottoclasse).

Sostituite i metodi della nuova classe in modo da gestire le modifiche nelle impostazioni correlate all'interfaccia utente. La seguente classe CustomHost, ad esempio, definisce i comportamenti per le chiamate a window.open() e le modifiche a window.document.title . Le chiamate a window.open() aprono la pagina HTML in una nuova finestra e le modifiche a window.document.title (inclusa l'impostazione dell'elemento <title> di una pagina HTML) impostano il titolo di tale finestra.

package 
{ 
    import flash.html.*; 
    import flash.display.StageScaleMode; 
    import flash.display.NativeWindow; 
    import flash.display.NativeWindowInitOptions; 
 
    public class CustomHost extends HTMLHost 
    { 
        import flash.html.*; 
        override public function 
            createWindow(windowCreateOptions:HTMLWindowCreateOptions):HTMLLoader 
        { 
            var initOptions:NativeWindowInitOptions = new NativeWindowInitOptions(); 
            var bounds:Rectangle = new Rectangle(windowCreateOptions.x, 
                                            windowCreateOptions.y, 
                                            windowCreateOptions.width, 
                                            windowCreateOptions.height); 
            var htmlControl:HTMLLoader = HTMLLoader.createRootWindow(true, initOptions, 
                                        windowCreateOptions.scrollBarsVisible, bounds); 
            htmlControl.htmlHost = new HTMLHostImplementation(); 
            if(windowCreateOptions.fullscreen){ 
                htmlControl.stage.displayState = 
                    StageDisplayState.FULL_SCREEN_INTERACTIVE; 
            } 
            return htmlControl; 
        } 
        override public function updateTitle(title:String):void 
        { 
            htmlLoader.stage.nativeWindow.title = title; 
        } 
    } 
}

Nel codice che contiene la sottoclasse HTMLLoader (non il codice della nuova sottoclasse di HTMLHost), create un oggetto della nuova classe. Assegnate il nuovo oggetto alla proprietà htmlHost di HTMLLoader. Il seguente codice Flex usa la classe CustomHost definita nel passaggio precedente:

<?xml version="1.0" encoding="utf-8"?> 
<mx:WindowedApplication 
    xmlns:mx="http://www.adobe.com/2006/mxml" 
    layout="vertical" 
    applicationComplete="init()"> 
    <mx:Script> 
        <![CDATA[ 
            import flash.html.HTMLLoader; 
            import CustomHost; 
            private function init():void 
            { 
                var html:HTMLLoader = new HTMLLoader(); 
                html.width = container.width; 
                html.height = container.height; 
                var urlReq:URLRequest = new URLRequest("Test.html"); 
                html.htmlHost = new CustomHost(); 
                html.load(urlReq); 
                container.addChild(html); 
            } 
        ]]> 
    </mx:Script> 
    <mx:UIComponent id="container" width="100%" height="100%"/> 
</mx:WindowedApplication>

Per verificare il codice qui descritto, includete un file HTML con il seguente contenuto nella directory dell'applicazione:

<html> 
    <head> 
        <title>Test</title> 
    </head> 
    <script> 
        function openWindow() 
        { 
            window.runtime.trace("in"); 
            document.title = "foo" 
            window.open('Test.html'); 
            window.runtime.trace("out"); 
        } 
    </script> 
    <body> 
        <a href="#" onclick="openWindow()">window.open('Test.html')</a> 
    </body> 
</html>

Esempio Flash Professional:

Create un file Flash per AIR. Impostate la classe document su CustomHostExample, quindi salvate il file come CustomHostExample.fla.

Create un file con nome CustomHost.as contenente una classe che estende la classe HTMLHost (una sottoclasse). Questa classe sostituisce determinati metodi della nuova classe per gestire le modifiche nelle impostazioni correlate all'interfaccia utente. La seguente classe CustomHost, ad esempio, definisce i comportamenti per le chiamate a window.open() e le modifiche a window.document.title . Le chiamate al metodo window.open() aprono la pagina HTML in una nuova finestra e le modifiche alla proprietà window.document.title (inclusa l'impostazione dell'elemento <title> di una pagina HTML) impostano il titolo di tale finestra.

package 
{ 
    import flash.display.StageScaleMode; 
    import flash.display.NativeWindow; 
    import flash.display.NativeWindowInitOptions; 
    import flash.events.Event; 
    import flash.events.NativeWindowBoundsEvent; 
    import flash.geom.Rectangle; 
    import flash.html.HTMLLoader; 
    import flash.html.HTMLHost; 
    import flash.html.HTMLWindowCreateOptions; 
    import flash.text.TextField; 
 
    public class CustomHost extends HTMLHost 
    { 
        public var statusField:TextField; 
         
        public function CustomHost(defaultBehaviors:Boolean=true) 
        { 
            super(defaultBehaviors); 
        } 
        override public function windowClose():void 
        { 
            htmlLoader.stage.nativeWindow.close(); 
        } 
        override public function createWindow( 
                                windowCreateOptions:HTMLWindowCreateOptions ):HTMLLoader 
        { 
            var initOptions:NativeWindowInitOptions = new NativeWindowInitOptions(); 
            var bounds:Rectangle = new Rectangle(windowCreateOptions.x, 
                                            windowCreateOptions.y, 
                                            windowCreateOptions.width, 
                                            windowCreateOptions.height); 
            var htmlControl:HTMLLoader = HTMLLoader.createRootWindow(true, initOptions, 
                                        windowCreateOptions.scrollBarsVisible, bounds); 
            htmlControl.htmlHost = new HTMLHostImplementation(); 
            if(windowCreateOptions.fullscreen){ 
                htmlControl.stage.displayState = 
                    StageDisplayState.FULL_SCREEN_INTERACTIVE; 
            } 
            return htmlControl; 
        } 
        override public function updateLocation(locationURL:String):void 
        { 
            trace(locationURL); 
        } 
        override public function set windowRect(value:Rectangle):void 
        { 
            htmlLoader.stage.nativeWindow.bounds = value; 
        } 
        override public function updateStatus(status:String):void 
        { 
            statusField.text = status; 
            trace(status); 
        } 
        override public function updateTitle(title:String):void 
        { 
            htmlLoader.stage.nativeWindow.title = title + "- Example Application"; 
        } 
        override public function windowBlur():void 
        { 
            htmlLoader.alpha = 0.5; 
        } 
        override public function windowFocus():void 
        { 
            htmlLoader.alpha = 1; 
        } 
    } 
}

Create un altro file ActionScript con nome CustomHostExample.as per contenere la classe document dell'applicazione. Questa classe crea un oggetto HTMLLoader e imposta la relativa proprietà host su un'istanza della classe CustomHost definita nel passaggio precedente:

package 
{ 
    import flash.display.Sprite; 
    import flash.html.HTMLLoader; 
    import flash.net.URLRequest; 
    import flash.text.TextField; 
 
    public class CustomHostExample extends Sprite 
    { 
        function CustomHostExample():void 
        { 
            var html:HTMLLoader = new HTMLLoader(); 
            html.width = 550; 
            html.height = 380; 
            var host:CustomHost = new CustomHost(); 
            html.htmlHost = host; 
             
            var urlReq:URLRequest = new URLRequest("Test.html"); 
            html.load(urlReq); 
             
            addChild(html); 
             
            var statusTxt:TextField = new TextField(); 
            statusTxt.y = 380; 
            statusTxt.height = 20; 
            statusTxt.width = 550; 
            statusTxt.background = true; 
            statusTxt.backgroundColor = 0xEEEEEEEE; 
            addChild(statusTxt); 
             
            host.statusField = statusTxt; 
        } 
    } 
}

Per verificare il codice qui descritto, includete un file HTML con il seguente contenuto nella directory dell'applicazione:

<html> 
     <head> 
     <title>Test</title> 
     <script> 
     function openWindow() 
     { 
     document.title = "Test" 
     window.open('Test.html'); 
     } 
     </script> 
     </head> 
     <body bgColor="#EEEEEE"> 
     <a href="#" onclick="window.open('Test.html')">window.open('Test.html')</a> 
     <br/><a href="#" onclick="window.document.location='http://www.adobe.com'"> 
     window.document.location = 'http://www.adobe.com'</a> 
     <br/><a href="#" onclick="window.moveBy(6, 12)">moveBy(6, 12)</a> 
     <br/><a href="#" onclick="window.close()">window.close()</a> 
     <br/><a href="#" onclick="window.blur()">window.blur()</a> 
     <br/><a href="#" onclick="window.focus()">window.focus()</a> 
     <br/><a href="#" onclick="window.status = new Date().toString()">window.status=new Date().toString()</a> 
     </body> 
</html>

Gestione delle modifiche alla proprietà window.location

Sostituite il metodo locationChange() per gestire le modifiche dell'URL della pagina HTML. Il metodo locationChange() viene chiamato quando il codice JavaScript in una pagina modifica il valore di window.location . Il seguente esempio carica semplicemente l'URL richiesto:

override public function updateLocation(locationURL:String):void 
{ 
    htmlLoader.load(new URLRequest(locationURL)); 
}

Nota: potete usare la proprietà htmlLoader dell'oggetto HTMLHost per fare riferimento all'oggetto HTMLLoader corrente.

Gestione delle chiamate JavaScript a window.moveBy(), window.moveTo(), window.resizeTo(), window.resizeBy()

Sostituite il metodo set windowRect() per gestire le modifiche nei limiti del contenuto HTML. Il metodo set windowRect() viene chiamato quando il codice JavaScript in una pagina chiama window.moveBy() , window.moveTo() , window.resizeTo() o window.resizeBy() . Il seguente esempio aggiorna semplicemente i limiti della finestra del desktop:

override public function set windowRect(value:Rectangle):void 
{ 
    htmlLoader.stage.nativeWindow.bounds = value; 
}

Gestione delle chiamate JavaScript a window.open()

Sostituite il metodo createWindow() per gestire le chiamate JavaScript a window.open() . Le implementazioni del metodo createWindow() hanno il compito di creare e restituire un nuovo oggetto HTMLLoader. In genere, l'oggetto HTMLLoader viene visualizzato in una nuova finestra, tuttavia non è obbligatorio creare una nuova finestra.

L'esempio seguente illustra come implementare la funzione createWindow() usando HTMLLoader.createRootWindow() per creare sia la finestra che l'oggetto HTMLLoader. Potete anche creare separatamente un oggetto NativeWindow e aggiungere HTMLLoader allo stage della finestra.

override public function createWindow(windowCreateOptions:HTMLWindowCreateOptions):HTMLLoader{ 
    var initOptions:NativeWindowInitOptions = new NativeWindowInitOptions(); 
    var bounds:Rectangle = new Rectangle(windowCreateOptions.x, windowCreateOptions.y,  
                                windowCreateOptions.width, windowCreateOptions.height); 
    var htmlControl:HTMLLoader = HTMLLoader.createRootWindow(true, initOptions, 
                                    windowCreateOptions.scrollBarsVisible, bounds); 
    htmlControl.htmlHost = new HTMLHostImplementation(); 
    if(windowCreateOptions.fullscreen){ 
        htmlControl.stage.displayState = StageDisplayState.FULL_SCREEN_INTERACTIVE; 
    } 
    return htmlControl; 
}

Nota: questo esempio assegna l'implementazione personalizzata di HTMLHost a tutte le nuove finestre create con window.open() . Potete anche usare un'implementazione diversa o impostare la proprietà htmlHost su null per le nuove finestre, se necessario.

L'oggetto passato come parametro al metodo createWindow() è un oggetto HTMLWindowCreateOptions . La classe HTMLWindowCreateOptions include delle proprietà che riportano i valori impostati nella stringa del parametro features nella chiamata a window.open() :

Proprietà HTMLWindowCreateOptions	Impostazione corrispondente nella stringa features nella chiamata JavaScript a window.open()
`fullscreen`	`fullscreen`
`height`	`height`
`locationBarVisible`	`location`
`menuBarVisible`	`menubar`
`resizeable`	`resizable`
`scrollBarsVisible`	`scrollbars`
`statusBarVisible`	`status`
`toolBarVisible`	`toolbar`
`width`	`width`
`x`	`left` o `screenX`
`y`	`top` o `screenY`

La classe HTMLLoader non implementa tutte le funzioni che possono essere specificate nella stringa delle funzioni. La vostra applicazione deve contenere le barre di scorrimento, dell'indirizzo, dei menu, di stato e degli strumenti appropriate.

Gli altri argomenti del metodo JavaScript window.open() sono gestiti dal sistema. Un'implementazione di createWindow() non deve caricare contenuto nell'oggetto HTMLLoader o impostare il titolo della finestra.

Chiamate Handling JavaScript a window.close()

Sostituite windowClose() per gestire le chiamate JavaScript al metodo window.close() . Il seguente esempio chiude la finestra del desktop quando viene chiamato il metodo window.close() :

override public function windowClose():void 
{ 
    htmlLoader.stage.nativeWindow.close(); 
}

Le chiamate JavaScript a window.close() non devono chiudere la finestra contenitore. Potete, ad esempio, rimuovere HTMLLoader dall'elenco di visualizzazione, lasciando aperta la finestra (che può avere altro contenuto), come nel codice seguente:

override public function windowClose():void 
{ 
    htmlLoader.parent.removeChild(htmlLoader); 
}

Gestione delle modifiche alla proprietà window.status

Sostituite il metodo updateStatus() per gestire le modifiche JavaScript al valore di window.status . Il seguente esempio traccia il valore dello stato:

override public function updateStatus(status:String):void 
{ 
    trace(status); 
}

Lo stato richiesto viene passato come stringa al metodo updateStatus() .

L'oggetto HTMLLoader non fornisce una barra di stato.

Gestione delle modifiche alla proprietà window.document.title

Sostituite il metodo updateTitle() per gestire le modifiche JavaScript al valore di window.document.title . Il seguente esempio modifica il titolo della finestra e aggiunge la stringa "Sample" al titolo:

override public function updateTitle(title:String):void 
{ 
    htmlLoader.stage.nativeWindow.title = title + " - Sample"; 
}

Quando document.title è impostata su una pagina HTML, il titolo richiesto viene passato come stringa al metodo updateTitle() .

Le modifiche a document.title non devono modificare il titolo della finestra che contiene l'oggetto HTMLLoader. Potreste, ad esempio, modificare un altro elemento dell'interfaccia, ad esempio un campo di testo.

Gestione delle chiamate JavaScript a window.blur() e window.focus()

Sostituite i metodi windowBlur() e windowFocus() in modo da gestire le chiamate JavaScript a window.blur() e window.focus() , come illustrato nel seguente esempio:

override public function windowBlur():void 
{ 
    htmlLoader.alpha = 0.5; 
} 
override public function windowFocus():void 
{ 
    htmlLoader.alpha = 1.0; 
    NativeApplication.nativeApplication.activate(htmlLoader.stage.nativeWindow); 
}

Nota: AIR non fornisce un'API per la disattivazione di una finestra o un'applicazione.

Creazione di finestra con contenuto HTML scorrevole

La classe HTMLLoader include un metodo statico, HTMLLoader.createRootWindow() , che consente di aprire una nuova finestra (rappresentata da un oggetto NativeWindow) che contiene un oggetto HTMLLoader e definisce alcune impostazioni dell'interfaccia utente per quella finestra. Il metodo accetta quattro parametri, che consentono di definire l'interfaccia utente:

Parametro	Descrizione
`visible`	Valore booleano che specifica se la finestra è inizialmente visibile ( `true` ) o non visibile ( `false` ).
`windowInitOptions`	Un oggetto NativeWindowInitOptions . La classe NativeWindowInitOptions definisce le opzioni di inizializzazione per un oggetto NativeWindow, incluse le seguenti: se la finestra può essere ridotta a icona, ingrandita o ridimensionata, se dispone di un chrome di sistema o personalizzato, se è trasparente o meno (per quelle che non usano chrome di sistema, oltre al tipo di finestra.
`scrollBarsVisible`	Se sono presenti bare di scorrimento ( `true` ) o non sono presenti ( `false` ).
`bounds`	Un oggetto Rectangle che definisce la posizione e le dimensioni di una nuova finestra.

Il seguente codice, ad esempio, utilizza il metodo HTMLLoader.createRootWindow() per creare una finestra con contenuto HTMLLoader che utilizza barre di scorrimento:

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

Nota: le finestre create mediante una chiamata a createRootWindow() direttamente in JavaScript rimangono indipendenti dalla finestra HTML che viene aperta. Le proprietà JavaScript Window opener e parent , ad esempio, sono null . Tuttavia, se chiamate createRootWindow() indirettamente mediante la sostituzione del metodo createWindow() di HTMLHost per chiamare createRootWindow() , le proprietà opener e parent fanno riferimento alla finestra HTML che viene aperta.