Définition des propriétés de la scène

Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures

La classe Stage annule la plupart des propriétés et méthodes de la classe DisplayObject. Si vous appelez l’une de ces propriétés ou méthodes annulées, Flash Player et AIR renvoient une exception. Par exemple, l’objet Stage ne possède pas de propriété x ou y car, en tant que conteneur principal de l’application, sa position est fixe. Or, les propriétés x et y indiquent la position d’un objet d’affichage par rapport à son conteneur, et puisque la scène ne se trouve pas dans un autre conteneur d’objets d’affichage, ces propriétés seraient inapplicables.

Remarque : certaines propriétés et méthodes de la classe Stage sont réservées aux objets d’affichage appartenant au même sandbox de sécurité que le premier fichier SWF chargé. Pour plus d’informations, voir Sécurité de la scène.

Contrôle de la cadence de lecture

La propriété framerate de la classe Stage permet de définir la cadence de tous les fichiers SWF chargés dans l’application. Pour plus d’informations, voir le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash.

Contrôle de la mise à l’échelle de la scène

Lorsque la portion de l’écran qui représente Flash Player ou AIR est redimensionnée, le moteur d’exécution ajuste automatiquement le contenu de la scène en conséquence. La propriété scaleMode de la classe Stage détermine comment le contenu de la scène est ajusté. Cette propriété peut être réglée sur quatre valeurs distinctes, définies en tant que constantes dans la classe flash.display.StageScaleMode :

  • StageScaleMode.EXACT_FIT met à l’échelle le fichier SWF de sorte à occuper les nouvelles dimensions de la scène sans tenir compte du format d’origine du contenu. Etant donné que les facteurs d’échelle ne sont pas nécessairement identiques en largeur et en hauteur, le contenu risque de sembler écrasé ou étiré en cas de modification du format de la scène.

  • StageScaleMode.SHOW_ALL met à l’échelle le fichier SWF de sorte à occuper les nouvelles dimensions de la scène sans modifier le format du contenu. Ce mode de mise à l’échelle affiche la totalité du contenu, mais risque de donner lieu à des bordures de type « boîte aux lettres » similaires aux barres noires qui entourent un film grand écran sur une télévision standard.

  • StageScaleMode.NO_BORDER met à l’échelle le fichier SWF de sorte à occuper totalement les nouvelles dimensions de la scène sans modifier le format du contenu. Ce mode de mise à l’échelle exploite pleinement la zone d’affichage de la scène, mais risque d’engendrer un recadrage.

  • StageScaleMode.NO_SCALE : ne met pas à l’échelle le fichier SWF. Si les nouvelles dimensions de la scène sont inférieures aux dimensions d’origine, le contenu est recadré. Si elles leur sont supérieures, l’espace ajouté est vide.

    Dans le mode de mise à l’échelle StageScaleMode.NO_SCALE uniquement, les propriétés stageWidth et stageHeight de la classe Stage permettent de déterminer les dimensions réelles de la scène redimensionnée, exprimées en pixels. (Dans les autres modes, les propriétés stageWidth et stageHeight renvoient toujours la largeur et la hauteur d’origine du fichier SWF.) De plus, lorsque la propriété scaleMode est définie sur StageScaleMode.NO_SCALE et que le fichier SWF est redimensionné, l’événement resize de la classe Stage est distribué, ce qui vous permet d’effectuer des ajustements en conséquence.

    Définir scaleMode sur StageScaleMode.NO_SCALE permet donc de mieux contrôler l’ajustement du contenu en cas de redimensionnement de la fenêtre. Par exemple, si un fichier SWF contient une vidéo et une barre de contrôle, il peut s’avérer utile de conserver la taille de la barre de contrôle en cas de redimensionnement de la scène et de ne modifier que la taille de la fenêtre de vidéo en fonction du changement de taille de la scène. Ce cas de figure est illustré dans l’exemple suivant :

    // mainContent is a display object containing the main content; 
    // it is positioned at the top-left corner of the Stage, and 
    // it should resize when the SWF resizes. 
     
    // controlBar is a display object (e.g. a Sprite) containing several 
    // buttons; it should stay positioned at the bottom-left corner of the 
    // Stage (below mainContent) and it should not resize when the SWF 
    // resizes. 
     
    import flash.display.Stage; 
    import flash.display.StageAlign; 
    import flash.display.StageScaleMode; 
    import flash.events.Event; 
     
    var swfStage:Stage = mainContent.stage; 
    swfStage.scaleMode = StageScaleMode.NO_SCALE; 
    swfStage.align = StageAlign.TOP_LEFT; 
    swfStage.addEventListener(Event.RESIZE, resizeDisplay); 
     
    function resizeDisplay(event:Event):void 
    { 
        var swfWidth:int = swfStage.stageWidth; 
        var swfHeight:int = swfStage.stageHeight; 
     
        // Resize the main content area 
        var newContentHeight:Number = swfHeight - controlBar.height; 
        mainContent.height = newContentHeight; 
        mainContent.scaleX = mainContent.scaleY; 
         
        // Reposition the control bar. 
        controlBar.y = newContentHeight; 
    }

Définition du mode de mise à l’échelle de la scène pour les fenêtres AIR

La propriété scaleMode de la scène indique comment celle-ci met à l’échelle et écrête les objets d’affichage enfant lors d’un redimensionnement de fenêtre. N’utilisez que le mode noScale dans AIR. Lorsque ce mode est activé, la scène n’est pas mise à l’échelle. La taille de la scène est modifiée directement en fonction des limites de la fenêtre. Les objets risquent d’être écrêtés si la taille de la fenêtre est inférieure à sa taille initiale.

Les modes de mise à l’échelle de la scène sont adaptés aux environnements tels qu’un navigateur Web qui ne permet pas nécessairement de contrôler la taille ou le format de la scène. Grâce aux modes, vous pouvez sélectionner le cas de figure le moins inadapté lorsque la scène ne correspond pas à la taille ou au format idéal défini par l’application. Dans AIR, vous contrôlez toujours la scène. Par conséquent, modifier la disposition du contenu ou redimensionner la fenêtre assure un meilleur résultat que l’activation de la mise à l’échelle de la scène.

Dans le navigateur et la fenêtre AIR initiale, la relation entre la taille de fenêtre et le facteur d’échelle initial est extraite du fichier SWF chargé. Toutefois, lorsque vous créez un objet NativeWindow, AIR choisit une relation arbitraire définie sur 72:1 entre la taille de fenêtre et le facteur d’échelle. Par conséquent, si la fenêtre mesure 72x72 pixels, un rectangle de 10x10 pixels ajouté à la fenêtre est dessiné à la taille correcte (soit 10x10 pixels). Par contre, si la fenêtre mesure 144x144 pixels, un rectangle de 10x10 pixels est mis à l’échelle (soit 20x20 pixels). Si vous préférez utiliser une propriété scaleMode autre que noScale pour une scène de fenêtre, vous pouvez compenser le résultat en définissant le facteur d’échelle de tout objet d’affichage de la fenêtre sur le rapport 72 pixels/largeur et hauteur actuelles de la scène. Le code suivant calcule par exemple le facteur d’échelle requis de l’objet d’affichage client :

if(newWindow.stage.scaleMode != StageScaleMode.NO_SCALE){ 
client.scaleX = 72/newWindow.stage.stageWidth; 
client.scaleY = 72/newWindow.stage.stageHeight; 
}
Remarque : les fenêtres Flex et HTML définissent automatiquement la propriété scaleMode de la scène sur noScale. Modifier la propriété scaleMode entrave le fonctionnement des mécanismes de mise en forme automatique utilisés dans ces types de fenêtres.

Utilisation du mode Plein écran

Le mode plein écran permet de définir la scène d’un film de sorte à remplir totalement le moniteur sans bordure ou menu. La propriété displayState de la classe Stage permet d’activer ou désactiver ce mode pour un fichier SWF. La propriété displayState peut être réglée sur l’une des valeurs définies par les constantes de la classe flash.display.StageDisplayState. Pour activer le mode plein écran, définissez la propriété displayState sur StageDisplayState.FULL_SCREEN :

stage.displayState = StageDisplayState.FULL_SCREEN; 

Pour activer le mode interactif plein écran (nouveauté dans Flash Player 11.3), définissez la propriété displayState sur StageDisplayState.FULL_SCREEN_INTERACTIVE :

stage.displayState = StageDisplayState.FULL_SCREEN_INTERACTIVE; 

Dans Flash Player, le mode plein écran ne peut être activé que via ActionScript en réponse à un clic de souris (clic de bouton droit inclus) ou une frappe de touche. Le contenu AIR qui s’exécute dans le sandbox de sécurité de l’application ne nécessite pas que le mode plein écran soit activé en réponse à une action de l’utilisateur.

Pour quitter le mode plein écran, définissez la propriété displayState sur StageDisplayState.NORMAL.

stage.displayState = StageDisplayState.NORMAL; 

Un utilisateur peut également désactiver le mode plein écran en plaçant le focus sur une autre fenêtre ou en utilisant l’une des combinaisons de touches suivantes : la touche Echap (toutes les plates-formes), Contrôle-W (Windows), Commande-W (Mac) ou Alt-F4 (Windows).

Activation du mode plein écran dans Flash Player

Pour activer le mode plein écran d’un fichier SWF intégré à une page HTML, le code HTML requis pour intégrer Flash Player doit comprendre une balise param et un attribut embed, associés au nom allowFullScreen et à la valeur true, comme suit :

<object> 
    ... 
    <param name="allowFullScreen" value="true" /> 
    <embed ... allowFullScreen="true" /> 
</object>

Dans l’outil de programmation Flash, choisissez Fichier -> Paramètres de publication, puis dans la boîte de dialogue Paramètres de publication, cliquez sur l’onglet HTML et sélectionnez le modèle Flash seulement - Autorisation du Plein écran.

Dans Flex, assurez-vous que le modèle HTML inclut les balises <object> et <embed> qui prennent en charge le plein écran.

Si vous utilisez JavaScript dans une page Web pour générer les balises d’intégration de SWF, vous devez modifier le code JavaScript pour ajouter la balise et l’attribut allowFullScreen param. Par exemple, si votre page HTML fait appel à la fonction AC_FL_RunContent() (utilisée par les pages HTML générées par Flash Professional et Flash Builder), vous devez ajouter le paramètre allowFullScreen à cet appel de fonction, comme suit :

AC_FL_RunContent( 
    ... 
    'allowFullScreen','true', 
    ... 
    ); //end AC code

Ce cas de figure ne s’applique pas aux fichiers SWF qui s’exécutent dans la version autonome de Flash Player.

Remarque : si vous définissez le Mode fenêtre (wmode dans le code HTML) sur Opaque sans fenêtre (opaque) ou Transparent sans fenêtre (transparent), la fenêtre plein écran est toujours opaque.

Il existe également des restrictions liées à la sécurité lors de l’utilisation du mode plein écran avec Flash Player dans un navigateur. Ces restrictions sont décrites dans le chapitre Sécurité.

Activation du mode interactif plein écran dans Flash Player 11.3 et les versions ultérieures

Flash Player 11.3 et les versions ultérieures prennent en charge le mode interactif plein écran, qui permet une prise en charge totale de toutes les touches du clavier (à l’exception de la touche Echap, qui permet de quitter le mode interactif plein écran). Le mode interactif plein écran est utile pour les jeux (par exemple pour activer la fonction de dialogue en ligne dans un jeu multijoueurs ou les commandes du clavier WASD dans un jeu de tir subjectif.)

Pour activer le mode interactif plein écran d’un fichier SWF intégré à une page HTML, le code HTML requis pour intégrer Flash Player doit comprendre une balise param et un attribut embed, associés au nom allowFullScreenInteractive et à la valeur true, comme suit :

<object> 
    ... 
    <param name="allowFullScreenInteractive" value="true" /> 
    <embed ... allowFullScreenInteractive="true" /> 
</object>

Dans l’outil de création de Flash, cliquez sur Fichier -> Paramètres de publication, puis, dans l’onglet HTML de la boîte de dialogue Paramètres de publication, sélectionnez le modèle Flash seulement - Autorisation du Plein écran interactif.

Dans Flash Builder et Flex, vérifiez que les modèles HTML incluent les balises <object> et <embed> qui prennent en charge le mode interactif plein écran.

Si vous utilisez JavaScript dans une page Web pour générer les balises d’intégration de SWF, vous devez modifier le code JavaScript pour ajouter la balise et l’attribut allowFullScreenInteractive param. Par exemple, si votre page HTML fait appel à la fonction AC_FL_RunContent() (utilisée par les pages HTML générées par Flash Professional et Flash Builder), vous devez ajouter le paramètre allowFullScreenInteractive à cet appel de fonction, comme suit :

AC_FL_RunContent( 
    ... 
    'allowFullScreenInteractive','true', 
    ... 
    ); //end AC code

Ce cas de figure ne s’applique pas aux fichiers SWF qui s’exécutent dans la version autonome de Flash Player.

Mise à l’échelle et taille de la scène en mode plein écran

Les propriétés Stage.fullScreenHeight et Stage.fullScreenWidth renvoient la hauteur et la largeur de l’écran utilisé lors de l’activation du mode plein écran, lorsque le passage à cet état est immédiat. Ces valeurs risquent d’être incorrectes si l’utilisateur déplace le navigateur d’un écran à un autre après avoir récupéré ces valeurs, mais avant de passer au mode plein écran. Si l’utilisateur récupère ces valeurs dans le gestionnaire d’événement dans lequel il a défini la propriété Stage.displayState sur StageDisplayState.FULL_SCREEN, celles-ci sont correctes. Pour les utilisateurs qui utilisent plusieurs écrans, le contenu du fichier SWF s’étend pour n’occuper qu’un seul écran. Flash Player et AIR utilisent une mesure pour identifier le moniteur contenant la portion la plus élevée du fichier SWF et activent le mode plein écran sur celui-ci. Les propriétés fullScreenHeight et fullScreenWidth ne reflètent que la taille du moniteur utilisé en mode plein écran. Pour plus d’informations, voir Stage.fullScreenHeight et Stage.fullScreenWidth dans le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash.

En mode plein écran, le comportement de mise à l’échelle de la scène est identique à celui du mode normal. Cette mise à l’échelle est contrôlée par la propriété scaleMode de la classe Stage. Si la propriété scaleMode est définie sur StageScaleMode.NO_SCALE, les propriétés stageWidth et stageHeight de la classe Stage sont modifiées pour répercuter la taille de la zone de l’écran occupée par le fichier SWF (soit, dans ce cas, l’écran entier). Dans un navigateur, le paramètre HTML correspondant contrôle le réglage.

L’événement fullScreen de la classe Stage permet de détecter et répondre à l’activation ou à la désactivation du mode plein écran. Par exemple, il peut être nécessaire de repositionner, d’ajouter ou de supprimer des éléments lors d’un changement d’état du mode plein écran, comme illustré par cet exemple :

import flash.events.FullScreenEvent; 
 
function fullScreenRedraw(event:FullScreenEvent):void 
{ 
    if (event.fullScreen) 
    { 
        // Remove input text fields. 
        // Add a button that closes full-screen mode. 
    } 
    else 
    { 
        // Re-add input text fields. 
        // Remove the button that closes full-screen mode. 
    } 
} 
 
mySprite.stage.addEventListener(FullScreenEvent.FULL_SCREEN, fullScreenRedraw);

Comme l’indique ce code, l’objet associé à l’événement fullScreen est une occurrence de la classe flash.events.FullScreenEvent, dont la propriété fullScreen indique si le mode plein écran est activé (true) ou non (false).

Prise en charge du clavier en mode plein écran

Lorsque Flash Player est exécuté dans un navigateur, l’ensemble du code ActionScript lié au clavier (événements de clavier et saisie de texte dans des occurrences de TextField, entre autres), est désactivé en mode plein écran. Les exceptions (c’est-à-dire les touches qui restent actives) sont les suivantes :

  • Les touches hors impression sélectionnées, notamment les touches fléchées, la barre d’espacement et la touche de tabulation

  • Les raccourcis clavier qui désactivent le mode plein écran : touche Echap (Windows et Mac), Contrôle-W (Windows), Commande-W (Mac) et Alt-F4

Ces restrictions ne sont pas présentes pour le contenu SWF s’exécutant dans l’application Flash Player autonome ou dans AIR. AIR prend en charge un mode plein écran interactif qui permet la saisie clavier.

Prise en charge de la souris en mode plein écran

Par défaut, les événements de souris fonctionnent de la même façon en mode plein écran que dans un autre mode d’affichage. Néanmoins, le mode plein écran permet également de définir la propriété Stage.mouseLock en vue de verrouiller la souris. Le verrouillage de la souris désactive le curseur et permet de déplacer la souris sans aucune limite.

Remarque : vous pouvez verrouiller la souris uniquement sur des applications de bureau en mode plein écran. Le verrouillage de la souris sur des applications dans un autre mode d’affichage ou sur des applications mobiles renvoie une exception.

Le verrouillage de la souris est automatiquement désactivé et le curseur de la souris est à nouveau visible lorsque :

  • l’utilisateur quitte le mode plein écran en appuyant sur la touche Echap (toutes les plates-formes), ou sur les touches Ctrl-W (Windows), Cmd-W (Mac) ou Alt-F4 (Windows) ;

  • la fenêtre de l’application perd le focus ;

  • une interface de paramétrage est visible, notamment une boîte de dialogue de confidentialité ;

  • une boîte de dialogue native s’affiche, notamment une boîte de dialogue de téléchargement d’un fichier.

Les événements associés au mouvement de la souris, tels que l’événement mouseMove, font appel à la classe MouseEvent pour représenter l’objet de l’événement. Lorsque le verrouillage de la souris est désactivé, utilisez les propriétés MouseEvent.localX et MouseEvent.localY pour déterminer l’emplacement de la souris. Lorsque le verrouillage de la souris est activé, utilisez les propriétés MouseEvent.movementX et MouseEvent.movementY pour déterminer l’emplacement de la souris. Les propriétés movementX et movementY contiennent les changements de position de la souris depuis le dernier événement plutôt que les coordonnées absolues de l’emplacement de la souris.

Mise à l’échelle matérielle en mode plein écran

La propriété fullScreenSourceRect de la classe Stage permet d’utiliser Flash Player ou AIR pour mettre à l’échelle une zone déterminée de la scène en mode plein écran. Dans Flash Player et AIR, la mise à l’échelle matérielle, si elle est disponible, s’effectue à l’aide de la carte graphique et de la carte vidéo de l’ordinateur, et permet généralement d’afficher le contenu plus rapidement que la mise à l’échelle logicielle.

Pour tirer parti de la mise à l’échelle matérielle, définissez l’ensemble ou une partie de la scène sur le mode plein écran. Le code suivant ActionScript 3.0 définit l’ensemble de la scène en mode plein écran :

import flash.geom.*;  
{ 
    stage.fullScreenSourceRect = new Rectangle(0,0,320,240); 
    stage.displayState = StageDisplayState.FULL_SCREEN; 
}

Lorsque cette propriété est définie sur un rectangle valide et la propriété displayState sur le mode plein écran, Flash Player et AIR redimensionnent la zone spécifiée. La taille réelle de la scène en pixels dans ActionScript ne change pas. Flash Player et AIR imposent une taille limite au rectangle en fonction de la taille du message standard « Appuyez sur la touche Echap pour quitter le mode plein écran ». Cette limite est généralement d’environ 260 sur 30 pixels, mais peut varier en fonction de la plate-forme et de la version de Flash Player.

La propriété fullScreenSourceRect ne peut être définie que lorsque Flash Player ou AIR ne sont pas en mode plein écran. Pour utiliser correctement cette propriété, vous devez tout d’abord la définir, puis définir la propriété displayState sur le mode plein écran.

Pour activer la mise à l’échelle, définissez la propriété fullScreenSourceRect sur un objet rectangle.

stage.fullScreenSourceRect = new Rectangle(0,0,320,240);

Pour désactiver la mise à l’échelle, définissez la propriété fullScreenSourceRect sur null.

stage.fullScreenSourceRect = null;

Pour tirer parti de toutes les fonctions d’accélération matérielle avec Flash Player, activez cette fonction dans la boîte de dialogue des paramètres de Flash Player. Pour afficher cette boîte de dialogue, cliquez avec le bouton droit de la souris (Windows) ou cliquez tout en appuyant sur la touche Ctrl (Mac) dans le contenu Flash Player dans votre navigateur. Cliquez sur le premier onglet, Affichage, puis cochez la case Activer l’accélération matérielle.

Modes Fenêtre direct et composition GPU

Flash Player 10 propose deux modes de fenêtre, direct et composition GPU, que vous pouvez activer dans les paramètres de publication de l’outil de programmation Flash. Ces modes ne sont pas pris en charge par AIR. Pour tirer parti de ces modes, vous devez activer l’accélération matérielle pour Flash Player.

Le mode direct utilise le chemin le plus rapide et le plus direct pour placer des graphismes sur l’écran, ce qui est pratique pour la lecture vidéo.

La composition GPU utilise l’unité de traitement graphique sur la carte vidéo pour accélérer la composition. La composition vidéo consiste à créer des images multi-couches pour aboutir à une seule image vidéo. Lorsque la composition est accélérée par la GPU, les performances de la conversion YUV, la correction des couleurs, la rotation, le redimensionnement et le fondu sont nettement améliorés. La conversion YUV se réfère à la conversion des couleurs de signaux analogiques composites, qui sont utilisées pour la transmission, au modèle de couleurs RVB (rouge-vert-bleu) que les caméras vidéo et les écrans utilisent. Le recours à la GPU pour accélérer la composition réduit la demande en mémoire et en puissance de calcul qui affectera les performances de l’unité centrale. Il en résulte une lecture vidéo plus régulière en définition standard.

Soyez vigilant lorsque vous implémentez ces modes Fenêtre. Fenêtre L’utilisation de la composition GPU peut s’avérer coûteuse en mémoire et en ressources de l’unité centrale. Si certaines opérations (comme les modes fondu, le filtrage, l’écrêtage ou le masquage) ne peuvent pas être exécutées dans la GPU, c’est le logiciel qui s’en charge. Adobe vous recommande de vous limiter à un fichier SWF par page HTML lorsque vous utilisez ces modes. Il ne faudrait pas les utiliser pour des bandeaux. La Flash Test Movie facility ne fait pas appel à l’accélération matérielle mais vous pouvez l’utiliser par le biais de l’option Aperçu avant publication.

Il est inutile de fixer une cadence supérieure à 60 (c’est la fréquence de régénération d’écran maximale) dans votre fichier SWF. Une cadence entre 50 et 55 débouche sur des images perdues, ce qui peut se produire de temps à autre pour des raisons diverses.

Le mode direct requiert Microsoft DirectX 9 avec une mémoire virtuelle RAM de 128 Mo sous Windows et OpenGL pour Apple Macintosh, Mac OS X version 10.2 ou ultérieure. La composition GPU requiert Microsoft DirectX 9 et la prise en charge de Pixel Shader 2.0 sous Windows avec une mémoire virtuelle RAM de 128 Mo. Sous Mac OS X et Linux, la composition GPU requiert OpenGL 1.5 et plusieurs extensions d’OpenGL (objet framebuffer, objets multitexture et shader, langage d’ombrage, shader de fragments).

Vous pouvez activer les modes d’accélération direct et gpu pour chaque SWF par le biais de la boîte de dialogue Paramètres de publication de Flash, à l’aide du menu d’accélération matérielle sur l’onglet Flash. Si vous choisissez Aucun, le mode Fenêtre revient à défaut, transparent ou opaque, selon le paramètre du Mode Fenêtre de l’onglet HTML.