Paramétrage des interfaces utilisateur de type navigateur pour un contenu HTML

Adobe AIR 1.0 et les versions ultérieures

A propos de l’extension de la classe HTMLHost
Exemple : Extension de la classe HTMLHost
Traitement des changements apportés à la propriété window.location
Traitement des appels JavaScript à window.moveBy(), window.moveTo(), window.resizeTo(), window.resizeBy()
Traitement des appels JavaScript à window.open()
Traitement des appels JavaScript à window.close()
Traitement des changements dans la propriété de l’état de la fenêtre
Traitement des changements dans la propriété window.document.title
Traitement des appels JavaScript à window.blur() et window.focus()
Création de fenêtres avec défilement de contenu HTML

JavaScript propose plusieurs interfaces de programmation pour contrôler la fenêtre qui affiche le contenu HTML. Dans AIR, vous pouvez annuler ces API en implémentant une classe HTMLHost personnalisée.

A propos de l’extension de la classe HTMLHost

Si, par exemple, votre application présente plusieurs objets HTMLLoader dans une interface à onglets, vous pourriez souhaiter changer le libellé d’un onglet à l’aide des pages HTML chargées, sans toucher au titre de la fenêtre principale. De même, votre code pourrait répondre à un appel window.moveTo() en repositionnant l’objet HTMLLoader dans son conteneur d’objet d’affichage parent, en déplaçant la fenêtre qui contient l’objet HTMLLoader, en ne faisant rien du tout ou en faisant tout autre chose.

La classe HTMLHost d’AIR contrôle les méthodes et propriétés JavaScript suivantes :

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

Lorsque vous créez un objet HTMLLoader à l’aide de new HTMLLoader() , les propriétés ou méthodes répertoriées ne sont pas activées. La classe HTMLHost fournit par défaut une implémentation de ces interfaces de programmation JavaScript, similaire à celle des navigateurs. Vous pouvez aussi étendre la classe HTMLHost pour personnaliser le comportement. Pour créer un objet HTMLHost qui prenne en charge le comportement par défaut, définissez le paramètre defaultBehaviors sur true dans le constructeur HTMLHost.

var defaultHost:HTMLHost = new HTMLHost(true);

Lorsque vous créez une fenêtre HTML dans AIR à l’aide de la méthode createRootWindow() de la classe HTMLLoader, une occurrence de HTMLHost qui prend en charge les comportements est automatiquement affectée. Vous pouvez changer le comportement de l’objet hôte en affectant une implémentation HTMLLoader différente à la propriété htmlHost du HTMLLoader ou bien vous pouvez affecter null pour désactiver complètement les fonctions.

Remarque : AIR affecte un objet HTMLHost par défaut à la fenêtre initiale créée pour une application AIR à base d’HTML et à toute fenêtre créée par l’implémentation par défaut de la méthode window.open()) JavaScript.

Exemple : Extension de la classe HTMLHost

L’exemple ci-dessous montre comment personnaliser l’affectation de l’interface utilisateur par un objet HTMLLoader en étendant la classe HTMLLoader :

Exemple Flex :

Créez une classe qui étend la classe HTMLHost (une sous-classe).

Remplacez les méthodes de la nouvelle classe pour gérer les changements dans les paramètres de l’utilisateur liés à l’interface. Par exemple, la classe suivante, CustomHost, définit les comportements pour les appels à window.open() et les changements à window.document.title . Les appels à window.open() ouvrent la page HTML dans une nouvelle fenêtre et les changements à window.document.title , y compris le paramétrage de l’élément <title> d’une page HTML, définissent le titre de cette fenêtre.

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

Dans le code qui contient le HTMLLoader (pas le code de la nouvelle sous-classe de HTMLHost), créez un objet de la nouvelle classe. Affectez le nouvel objet à la propriété htmlHost du HTMLLoader. Le code Flex ci-dessous utilise la classe CustomHost définie à l’étape précédente :

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

Pour tester le code décrit ici, incluez un fichier HTML qui ait le contenu suivant dans le répertoire de l’application :

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

Exemple Flash Professional :

Créez un fichier Flash pour AIR. Définissez sa classe de document sur CustomHostExample, puis enregistrez le fichier sous CustomHostExample.fla.

Créez un fichier ActionScript appelé CustomHost.as contenant une classe qui étend la classe HTMLHost (une sous-classe). Cette classe remplace certaines méthodes de la nouvelle classe pour traiter les changements dans les paramètres de l’utilisateur liés à l’interface. Par exemple, la classe suivante, CustomHost, définit les comportements pour les appels à window.open() et les changements à window.document.title . Les appels à la méthode window.open() ouvrent la page HTML dans une nouvelle fenêtre et les changements à la propriété window.document.title , y compris le paramétrage de l’élément <title> d’une page HTML, définissent le titre de cette fenêtre.

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

Créez un autre fichier ActionScript appelé CustomHostExample.as pour contenir la classe document pour cette application. Cette classe crée un objet HTMLLoader et définit sa propriété hôte sur une occurrence de la classe CustomHost définie à l’étape précédente.

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

Pour tester le code décrit ici, incluez un fichier HTML qui ait le contenu suivant dans le répertoire de l’application :

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

Traitement des changements apportés à la propriété window.location

Remplacez la méthode locationChange() pour traiter les changements apportés à l’URL de la page HTML. La méthode locationChange() est appelée lorsque JavaScript dans une page change la valeur de window.location . L’exemple ci-dessous charge tout simplement l’URL demandée :

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

Remarque : vous pouvez utiliser la propriété HTMLLoader de l’objet HTMLHost pour faire référence à l’objet HTMLLoader actuel.

Traitement des appels JavaScript à window.moveBy(), window.moveTo(), window.resizeTo(), window.resizeBy()

Remplacez la méthode set windowRect() pour traiter les changements dans les limites du contenu HTML. La méthode set windowRect() est appelée lorsque JavaScript dans une page appelle window.moveBy() , window.moveTo() , window.resizeTo() ou window.resizeBy() . L’exemple ci-dessous met simplement à jour les limites de la fenêtre de l’ordinateur de bureau :

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

Traitement des appels JavaScript à window.open()

Remplacez la méthode createWindow() pour traiter les appels JavaScript à window.open() . Les implémentations de la méthode createWindow() sont responsables de la création d’un objet HTMLLoader et de son renvoi. Vous afficheriez généralement le HTMLLoader dans une nouvelle fenêtre, mais la création d’une fenêtre n’est pas nécessaire.

L’exemple suivant décrit comment implémenter la fonction createWindow() à l’aide du HTMLLoader.createRootWindow() pour créer à la fois la fenêtre et l’objet HTMLLoader. Vous pouvez aussi créer un objet NativeWindow à part et ajouter le HTMLLoader à la scène de la fenêtre.

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

Remarque : cet exemple affecte l’implémentation personnalisée de HTMLHost à toute fenêtre créée avec window.open() . Vous pouvez également utiliser une implémentation différente ou définir la propriété htmlHost sur "null" pour de nouvelles fenêtres, si vous le souhaitez.

L’objet transmis en tant que paramètre à la méthode createWindow() est un objet HTMLWindowCreateOptions . La classe HTMLWindowCreateOptions inclut des propriétés qui signalent les valeurs définies dans la chaîne du paramètre features , dans l’appel à window.open() :

Propriété HTMLWindowCreateOptions	Paramètre correspondant dans la chaîne des fonctions se trouvant dans l’appel JavaScript à window.open()
`fullscreen`	`fullscreen`
`height`	`height`
`locationBarVisible`	`location`
`menuBarVisible`	`menubar`
`resizeable`	`resizable`
`scrollBarsVisible`	`scrollbars`
`statusBarVisible`	`status`
`toolBarVisible`	`toolbar`
`width`	`width`
`x`	`left` ou `screenX`
`y`	`top` ou `screenY`

La classe HTMLLoader n’implémente pas toutes les fonctions susceptibles d’être spécifiées dans la chaîne de fonctions. Votre application doit fournir des barres de défilement, des barres d’adresses, des barres de menus, des barres d’état et des barres d’outils lorsque cela convient.

Les autres arguments pour la méthode window.open() de JavaScript sont traités par le système. Une implémentation createWindow() ne devrait pas charger de contenu dans l’objet HTMLLoader ou définir le titre de la fenêtre.

Traitement des appels JavaScript à window.close()

Remplacez window.close() pour que les appels JavaScript soient traités par la méthode window.close() . L’exemple ci-dessous ferme la fenêtre de l’ordinateur de bureau lorsque la méthode window.close() est appelée :

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

Les appels JavaScript à window.close() n’ont pas besoin de fermer la fenêtre de contenu. Vous pourriez, par exemple, retirer HTMLLoader de la liste d’affichage en laissant la fenêtre (qui peut avoir un autre contenu) ouverte, comme dans le code suivant :

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

Traitement des changements dans la propriété de l’état de la fenêtre

Remplacez la méthode updateStatus() pour traiter les changements JavaScript à la valeur de window.status . L’exemple ci-dessous assure le suivi de la valeur d’état :

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

L’état demandé est transmis en tant que chaîne à la méthode updateStatus() .

L’objet HTMLLoader ne fournit pas de barre d’état.

Traitement des changements dans la propriété window.document.title

Remplacez la méthode updateTitle() pour traiter les changements JavaScript à la valeur de window.document.title . L’exemple ci-dessous change le titre de la fenêtre et ajoute la chaîne "Sample" au titre :

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

Lorsque document.title est défini sur une page HTML, le titre demandé est transmis en tant que chaîne à la méthode updateTitle() .

Il n’est pas nécessaire que les changements à document.title modifient le titre de la fenêtre contenant l’objet HTMLLoader. Vous pourriez, par exemple, changer un autre élément d’interface, tel qu’un champ de texte.

Traitement des appels JavaScript à window.blur() et window.focus()

Remplacez les méthodes windowBlur() et windowFocus() pour traiter les appels JavaScript à window.blur() et window.focus() , comme le montre l’exemple ci-dessous :

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

Remarque : AIR ne fournit pas d’interface de programmation pour désactiver une fenêtre ou une application.

Création de fenêtres avec défilement de contenu HTML

La classe HTMLLoader inclut une méthode statique, HTMLLoader.createRootWindow() , vous permettant d’ouvrir une nouvelle fenêtre (représentée par un objet NativeWindow) qui contient un object HTMLLoader et qui définit quelques paramètres d’interface utilisateur pour cette fenêtre. Il faut à cette méthode quatre paramètres pour vous permettre de définir l’interface utilisateur.

Paramètre	Description
`visible`	Une valeur booléenne indiquant si la fenêtre est initialement visible ( `true` ) ou non ( `false` ).
`windowInitOptions`	Un objet NativeWindowInitOptions . La classe NativeWindowInitOptions définit les options d’initialisation pour un objet NativeWindow, y compris ce qui suit : si on peut réduire la fenêtre au minimum, la développer au maximum ou la redimensionner, si la fenêtre possède un chrome système ou un chrome personnalisable, si la fenêtre est transparente ou non (pour les fenêtres qui n’utilisent pas de chrome système) et le type de fenêtre.
`scrollBarsVisible`	Indique s’il existe des barres de défilement ( `true` ) ou non ( `false` ).
`bounds`	Un objet Rectangle qui définit la position et la taille de la nouvelle fenêtre.

Par exemple, le code ci-dessous fait appel à la méthode HTMLLoader.createRootWindow() pour créer une fenêtre dans laquelle figure le contenu HTMLLoader qui utilise des barres de défilement :

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

Remarque : les fenêtres créées par un appel direct de createRootWindow() dans JavaScript demeurent indépendantes de la fenêtre HTML d’ouverture. Les propriétés JavaScript Window opener et parent , par exemple, sont null . Toutefois, si vous appelez createRootWindow() indirectement en remplaçant la méthode HTMLHost createWindow() pour appeler createRootWindow() , opener et parent font effectivement référence à la fenêtre HTML d’ouverture.