API ActiveX Flash

Méthodes globales

Liste des méthodes globales mises à disposition par le contrôle ActiveX Shockwave Flash.

• SetZoomRect
• Zoom
• Pan
• Play
• Stop
• StopPlay
• Back
• Forward
• Rewind
• GotoFrame
• CurrentFrame
• IsPlaying
• PercentLoaded
• FrameLoaded
• FlashVersion
• LoadMovie
• SetVariable
• GetVariable

Les méthodes listées sur cette page sont destinées à affecter le comportement de l'animation entière.

SetZoomRect

• [in] long xMin
• [in] long yMin
• [in] long xMax
• [in] long yMax
• Accessible dés la création de l'objet.

Cette méthode propre au contrôle ActiveX Shockwave Flash permet de redéfinir les coordonées de la vue définie par défaut pour lire l'animation en y affectant les quatres coordonées passées en arguments. Il est ainsi possible de produire un effet de zoom ou d'éloignement de la vue appliquée sur la scène en rapport à la vue de départ. C'est d'ailleurs la même méthode que celle utilisée par le menu contextuel de navigation du player Flash. A tel point que lorsque cette méthode est appliqué à l'animation, le curseur prend automatiquement la forme de l'icone qui permet à l'utilisateur de déplacer l'animation dans la vue. (par défaut c'est une main qui s'ouvres et se ferme sous Windows) C'est à dire exactement de la même façon que le ferait le zoom du menu contextuel.

Les quatre arguments sont des nombre définis en twips qui est l'unité de calcul utilisée par les scripts internes au contrôle ActiveX depuis toujours.
Un twips représente 1/20 pixel, il faut donc multiplier chaque valeur en pixels par 20 avant de la passer en arguments à cette méthode pour obtenir la correspondance.

Le changement de vue se fera de façon à respecter le mode d'étirement de l'animation défini par les paramètres sAlign et AlignMode. En conséquence, selon la valeur portée par ces propriétés, la vue obtenue par l'application de la méthode SetZoomRect ne donnera jamais le même résultat.

Exemple d'appel à la méthode depuis Jscript:

window.onTest = function(oAnimation)
{

    oAnimation.ScaleMode = "noBorder";

    //COORDONEES EN PIXELS DU RECTANGLE QUE REPRESENTE 
    //UNE IMAGE POSEE DIRECTEMENT SUR LA SCENE
    var bdMyPhoto = 
    {
        xMin : 100, 
        yMin : 100, 
        xMax : 400, 
        yMax : 400
    }

    //LA VUE NE PORTERA QUE SUR L'IMAGE
    oAnimation.SetZoomRect
    (
        bdMyPhoto.xMin * 20,
        bdMyPhoto.yMin * 20,
        bdMyPhoto.xMax * 20,
        bdMyPhoto.yMax * 20
    );
}

Il faut signaler qu'il existe un bug avec l'utilisation de cette méthode en corrélation avec une animation dont la propriété Scale ou ScaleMode fixant le mode d'étirement est passée à noScale. Le problème consiste en la persistence du curseur déplacer objet alors que la vue sur l'animation ne peut-être déplacée.
Pour fixer ce problème, mais aussi pour permettre à l'animation de revenir à sa vue par défaut, il est possible d'appliquer le code suivant :

window.onTest = function(oAnimation)
{
    //LA VUE SERA REINITIALISEE A SA VALEUR PAR DEFAUT
    oAnimation.SetZoomRect
    (
        0,
        0,
        0,
        0
    );
}

Zoom

• [in] long Factor
• Accessible dés la création de l'objet.

Effectue un zoom sur l'animation de la même manière que le ferais la fonctionnalité zoom du menu contectuel de navigation. Le facteur de zoom s'exprime en pourcentage de la vue actuelle portée sur l'animation, et non pas en pourcentage de celle portée sur la scène.

Le facteur de zoom porte en fait sur la taille de la vue portée sur l'animation et pas sur la taille de l'animation elle-même. C'est pourquoi un facteur de 50% vas diviser par deux le champ de vision portée sur l'animation, mais donner l'impression d'un zoom sur l'animation. Inversement, un facteur de zoom de 200% vas multiplier par deux le champ de vision porté sur l'animation et donc donner une impression de réduction de la taille de l'animation.

Il est à noter que la propriété d'étirement de l'animation n'impose aucune restriction à l'appel à cette fonction et que la nouvelle taille de la vue portée sur l'animation sera quand même affectée. (il existe cependant un problème)

Exemple d'appel à la méthode depuis Jscript:

window.onTest = function(oAnimation)
{
    //LA TAILLE DE L'ANIMATION DANS LA FENETRE EST MULTIPLIEE PAR DEUX
    oAnimation.Zoom(50);

    //LA TAILLE DE L'ANIMATION DANS LA FENETRE SERA MAINTENANT MULTIPLIEE PAR QUATRE
    oAnimation.Zoom(50);  
}

Pan

• [in] long x
• [in] long y
• [in] int mode
• Accessible dés la création de l'objet

Cette méthode sert à redéfinir la position de la vue sur l'animation quand elle n'est pas dans sa configuration par défaut. Il n'est donc pas possible de l'utiliser si l'animation n'est pas zoomée depuis le menu contextuel de navigation ou par la méthode SetZoomRect. Les arguments de cette méthode peuvent être passés en pixels ou en pourcentage.

Passés en pixels ou en pourcentage, la longueur du déplacement se définit en rapport à la fenêtre du lecteur et non à la scène de l'animation.

Valeurs possibles pour l'argument mode:

Le changement de position de la vue ne pourra jamais permettre de faire apparaitre une zone hors des limites de la scène de l'animation. Il s'agit donc du comportement par défaut utilisé par un zoom effectué à partir du menu contextuel.

Exemple d'appel à la méthode depuis Jscript:

window.onTest = function(oAnimation)
{

    oAnimation.Scale = "showAll";

    oAnimation.SetZoomRect
    (
        200 * 20,
        200 * 20,
        300 * 20,
        300 * 20
    );

    // DEPLACES LE CENTRE DE LA VUE DE L'ANIMATION DE
    // 150 pixels VERS LA DROITE ET DE 50 pixels VERS LE HAUT
    oAnimation.Pan
    (
        150,
        -50,
        0
    );
}

Play

• Accessible dés la création de l'objet

Lances la lecture de l'animation lorsque celle-ci est arrêtée. Cette méthode est l'équivalent de la fonction ActionScript  play().

Exemple d'appel à la méthode depuis Jscript:

window.onTest = function(oAnimation)
{
    oAnimation.Play();
}

Stop

• Accessible dés la création de l'objet

Arrêtes la lecture de l'animation lorsque celle-ci est en cours de lecture. Cette méthode est l'équivalent de la méthode ActionScript stop().

Exemple d'appel à la méthode depuis Jscript:

window.onTest = function(oAnimation)
{
    oAnimation.Stop();
}

StopPlay

• Accessible dés la création de l'objet

Action équivalente à la méthode Stop.

Arrêtes la lecture de l'animation lorsque celle-ci est en cours de lecture. Cette méthode est l'équivalent de la méthode ActionScript stop().

Exemple d'appel à la méthode depuis Jscript:

window.onTest = function(oAnimation)
{
    oAnimation.StopPlay();
}

Back

• Accessible dés la création de l'objet

Déplaces la tête de lecture d'une frame dans le sens opposé de la lecture et arrêtes la lecture de l'animation lorsque celle-ci est en cours. Cette méthode est l'équivalent de la méthode ActionScript MovieClip.prevFrame.

Exemple d'appel à la méthode depuis Jscript:

window.onTest = function(oAnimation)
{
    oAnimation.Back();
}

Forward

• Accessible dés la création de l'objet

Déplaces la tête de lecture d'une frame dans le sens de la lecture et arrêtes la lecture de l'animation lorsque celle-ci est en cours. Cette méthode est l'équivalent de la méthode ActionScript nextFrame().

Exemple d'appel à la méthode depuis Jscript:

window.onTest = function(oAnimation)
{
    oAnimation.Forward();
}

Rewind

• Accessible dés la création de l'objet

Déplaces la tête de lecture au début de l'animation et arrêtes la lecture lorsque celle-ci est en cours.

Exemple d'appel à la méthode depuis Jscript:

window.onTest = function(oAnimation)
{
    oAnimation.Rewind();
}

GotoFrame

• [in] long FrameNum
• Accessible dés la création de l'objet

Déplaces la tête de lecture sur la frame désignée par l'entier FrameNum , et arrêtes la lecture de l'animation lorsque celle-ci est en cours. Si la frame en question n'existe pas ou qu'elle n'est pas encore chargée, la tête de lecture se déplace sur la dernière frame accessible de l'animation et s'y arrête.

Important: Les frames sont zéro indexées contrairement à l'argument utilisé avec la méthode Actionscript MovieClip.gotoAndStop à laquelle elle est identique.

Exemple d'appel à la méthode depuis Jscript:

window.onTest = function(oAnimation)
{
    oAnimation.GotoFrame(145);
}

CurrentFrame

• [out, retval] long* FrameNum
• Accessible dés la création de l'objet

Retournes le numéro de la frame sur laquelle se situe actuellement la tête de lecture.

Exemple d'appel à la méthode depuis Jscript:

window.onTest = function(oAnimation)
{
    if(oAnimation.CurrentFrame() == 0)
        alert("L'animation est sur sa première frame.");
    else
        alert("L'animation est sur la frame n°" + oAnimation.CurrentFrame() + " .");
}

Important: Le numéro de la frame retourné est zéro indexé.

IsPlaying

• [out, retval] VARIANT_BOOL* Playing
• Accessible dés la création de l'objet

Retournes l'état de la lecture de l'animation.

Exemple d'appel à la méthode depuis Jscript:

window.onTest = function(oAnimation)
{
    if(oAnimation.IsPlaying())
        alert("La lecture de l'animation est en cours.");
    else
        alert("La lecture de l'animation est arrêtée.");
}

PercentLoaded

• [out, retval] long* percent
• Accessible dés la création de l'objet

Précises l'état d'avancement du téléchargement du fichier SWF rattaché à l'animation par défaut avec la propriété Movie. La valeur est retournée en pourcentage du nombre d'octets téléchargés sur le nombre d'octets total représentés par l'animation. La valeur retournée sera toujours un nombre entier qui variera de 0 à 100.

Exemple d'appel à la méthode depuis Jscript:

window.onButtonTest = function()
{
    var oAnimation = document.getElementById('animation');

    if(oAnimation.PercentLoaded() <100)
        alert("Le téléchargement de l'animation est en cours.");
    else
        alert("Le téléchargement de l'animation est terminé.");
}

FrameLoaded

• [in] long FrameNum,
• [out, retval] VARIANT_BOOL* loaded

Indique si la frame du fichier SWF rattaché à l'animation par défaut avec la propriété Movie demandée est actuellement téléchargée. La frame à tester est passée en argument par son numéro, un entier positif et le résultat est retourné sous forme d'un booléen.

Exemple d'appel à la méthode depuis Jscript:

window.onButtonTest = function()
{
    var document.getElementById('animation');

    if(oAnimation.FrameLoaded(54))
        oAnimation.GotoFrame(54);
}

FlashVersion

• [out, retval] long* version

Retournes la version du contrôle ActiveX actuellement installé et utilisé pour lire l'animation. Le chiffre retourné ne respecte aucune sémantique relative aux versions que les internautes ont l'habitude de rencontrer sur Internet. De plus, il ne précise en rien la sous-version du lecteur Flash et se contente de retourner le même chiffre pour tous les lecteurs d'une même version principale.

Cependant son utilité se révèle être capitale puisque cette méthode existe sur les lecteurs Flash de version 2 ou 3 et par conséquent permet de se substituer à l'appel à la variable _level0.$version par oAnimation.GetVariable('$version') qui n'existait justement pas avant la distribution du lecteur de version 4.

Exemple d'appel à la méthode depuis Jscript:

window.onTest = function(oAnimation)
{

    var sVersion;

    switch ( oAnimation.FlashVersion() )
    {
        case 393216 :
            sVersion = '6';
        break;

        case 327723 :
            sVersion = '5';
        break;

        case 262172 :
            sVersion = '4';
        break;

        case 196616 :
            sVersion = '3';
        break;

        case 131083 :
            sVersion = '2';     
        break;
        
        default :
            sVersion = 'indéterminée';  
        break;
    }

    alert( "Le lecteur Flash est de version : " + sVersion );
}

LoadMovie

• [in] int layer
• [in] BSTR url

Ordonnes au lecteur Flash de charger une nouvelle animation à partir de l'URL d'un fichier SWF dans un calque de niveau supérieur à celui déjà existant. En clair, les deux animations seront superposées, la deuxième ayant une couleur de fond transparente laissant transparaitre la première en dessous d'elle. Si le framerate des deux animations est fixé par le framerate de la première, leur timeline ne sont pas forcemment les même et une animation peut se trouver sur un numéro de frame précis tandis que la deuxième est sur un autre. L'animation chargée par cette méthode commence donc à être jouée dés qu'elle est chargée.

Cette méthode est l'équivalent de la méthode ActionScript loadMovieNum("url",level).

Il est possible de charger plusieurs animations en précisant à chaque fois un calque de numéro différent. Une animation chargée dans un calque contenant déjà une animation la remplacera. Cependant aucun appel à cette méthode sur le calque de niveau 0 ne sera pris en compte.

Exemple d'appel à la méthode depuis Jscript:

window.onTest = function(oAnimation)
{
    oAnimation.LoadMovie(54, 'http://www.monsite.com/03_calque.swf');
    oAnimation.LoadMovie(2, 'http://www.monsite.com/01_calque.swf');
    oAnimation.LoadMovie(35, 'http://www.monsite.com/02_calque.swf');
}

GetVariable

• [in] BSTR name
• [out, retval] BSTR* pVal

Retournes une valeur "pVal" obtenue d'une variable Actionscript de nom "name" sur le _level0 de l'animation. Il s'agit de la première méthode permettant réellement de faire communiquer JScript et l'Actionscript, puisqu'il est possible d'avoir accés à des variables Actionscript depuis la page HTML qui héberges le script JScript.

Affectation d'une variable en Actionscript:

myVar = 'Hello World !!!'

Evaluation de la variable depuis JScript :

window.onTest = function(oAnimation)
{
    var sArr;

    sArr = oAnimation.getVariable('myVar');
    alert(myVar); //=> Hello World !!!
}

Il faut noter cependant que malgré la proximité des langages, l'interface de dispatch du contrôle d'ActiveX Shockwave Flash n'est pas faite seulement pour JScript, et retournes donc toutes les variables sous forme de chaîne aprés les avoir évaluées. L'évaluation d'un tableau Actionscript imposera donc ce résultat par exemple:

Affectation du tableau en Actionscript:

myArr = new Array();
myArr[0] = 'A';
myArr[1] = 'B';
myArr[2] = 'C';
myArr[3] = 'D';

Evaluation du tableau depuis JScript :

window.onTest = function(oAnimation)
{
    var sArr,JSarr;

    JSarr = new Array();
    JSarr[0] = 'A';
    JSarr[1] = 'B';
    JSarr[2] = 'C';
    JSarr[3] = 'D';

    sArr = oAnimation.getVariable('myArr');
    if( sArr == JSarr.toString() )
        alert( typeof sArr + ': ' + sArr ); //=> String: A,B,C,D
}

Attention également que la variable Actionscript évaluée soit préalablement déclarée, car le contraire amènes irrémédiablement à une erreur JScript du type :

Il est possible de remédier à ce problème en utilisant ce type de code :

window.onTest = function(oAnimation)
{
    try
    {
        oAnimation.getVariable('myVar');
    }
    catch()
    {
        return alert("La variable Actionscript myVar n\'est pas déclarée");
    }
}

Attention: La syntaxe d'évaluation des variables conserve les propriétés de la syntaxe d'écriture du code Actionscript de la version 4 du lecteur Flash:

/*
POUR UNE VARIABLE ACTIONSCRIPT FLASH 5 ou 6 DECLAREE PAR:
_root.myClip.myClip.myValue;

ON APPLIQUERAS LE CODE JScript SUIVANT
*/
window.onTest = function(oAnimation)
{
    oAnimation.getVariable('/myClip/myClip:myValue');
}

SetVariable

• [in] BSTR name
• [in] BSTR value

Affectes une valeur "value" à une variable Actionscript de nom "name" sur le _level0 de l'animation.

Affectation et évaluation d'une variable Actionscript depuis JSscript:

window.onTest = function(oAnimation)
{
    oAnimation.setVariable('myVar','Hello World !!!');
    alert( oAnimation.getVariable('myVar') ); //=> Hello World !!!
}

De la même manière qu'avec la méthode GetVariable la valeur de la variable sera déclarée sous sa forme de type chaîne en Actionscript aprés avoir été évaluée.

Affectation du tableau en JSscript:

window.onTest = function(oAnimation)
{
    myArr = new Array();
    myArr[0] = 'A';
    myArr[1] = 'B';
    myArr[2] = 'C';
    myArr[3] = 'D';
    oAnimation.setVariable('myArr',myArr);
}

Evaluation du tableau depuis ActionScript :

ASarr = new Array();
ASarr[0] = 'A';
ASarr[1] = 'B';
ASarr[2] = 'C';
ASarr[3] = 'D';
 
if( myArr == ASarr.toString() )
    trace( typeof myArr + ': ' + myArr ); //=> String: A,B,C,D

Attention: La syntaxe d'affectation des variables conserve les propriétés de la syntaxe d'écriture du code Actionscript de la version 4 du lecteur Flash:

/*
POUR UNE VARIABLE ACTIONSCRIPT FLASH 5 ou 6 DECLAREE PAR:
_root.myClip.myClip.myValue;

ON APPLIQUERAS LE CODE JScript SUIVANT
*/
window.onTest = function(oAnimation)
{
    oAnimation.setVariable('/myClip/myClip:myValue','value');
}