Flash ScrollBar API

Les ScrollBar dans Flash ne sont pas façiles à gérer. D'autant plus que le composant fournit par Macromédia n'est pas toujours efficace. Dans le but de combler cette petite partie, l'équipe de Media-Box vous livre un petit package vous permettant de créer une (ou plusieurs) ScrollBar avec la plupart des fonctionnalités en quelques lignes de code ! Ce framework se base sur les mêmes concepts que le tutorial ”Scroller des MovieClip”.

Voici ce que vous pouvez faire très facilement avec ce package (scrollbarapi19.zip)

Avant tout, téléchargez les sources au bas de ce document. Dézippez ensuite le contenu au même endroit que votre .fla ou dans un des dossiers définis par votre classpath. Vérifiez que vos paramètres de publications soient définis sur Flash Player 7 ou 8.

Afin de pouvoir créer une ScrollBar, il vous faut les clips suivants :

• Un clip possédant le contenu (clipTarget)
• Un clip en tant que masque de ce contenu (clipMask)
• Un clip flèche haut (clipUp) et flèche bas (clipDown)
• Un clip rectangulaire représentant le scroller (clipScroller)
• Un 2ème clip rectangulaire, plus long que le premier (clipBcg)

Voici un exemple :

• PS : pour que la ScrollBar fonctionne normalement, il faut le le _y du clipTarget soit exactement la même que le _y du clipMask (cela n'est plus nécessaire depuis la 1.5) !
• PS2 : afin que tout fonctionne correctement, pensez bien à positionner vos éléments sur des pixels entiers ⇒ les valeur _x et _y doivent être entières !

Tout d'abord, nous allons créer le modèle de notre ScrollBar (MVC Pattern). Cela se fait très simplement :

import ch.component.scrollbar.*;
 
var sc:ScrollBar = ScrollBar.create(this.clipTarget, //le clip avec le contenu
                                    this.clipMask, //le clip masquant le contenu
                                    ScrollType.VERTICAL, //on indique que l'on veut scroller le contenu verticalement
                                    false //on ne fait pas de clipTarget.setMask(clipMask). (paramètre optionnel, false par défaut)
                                    );

et hop ! Notre ScrollBar est déjà prête à fonctionner. Il nous suffit dès lors de mettre en place les boutons qui vont gérer le scrolling.

Grâce à la ScrollBar créée ci-dessus, il nous suffit de définir que nous voulons les bouton up et down liés à celle-ci :

import ch.component.scrollbar.*;
 
var sc:ScrollBar = ScrollBar.create(this.clipTarget, this.clipMask, ScrollType.VERTICAL);
var up:ScrollClickButton = sc.getUpButton(this.clipUp);
var dn:ScrollClickButton = sc.getDownButton(this.clipDown);

et hop ! Nos flèches fonctionnent !

Il nous suffit maintenant d'ajouter la gestion du scroller. Pour ce faire, rien de plus simple :

import ch.component.scrollbar.*;
 
var sc:ScrollBar = ScrollBar.create(this.clipTarget, this.clipMask, ScrollType.VERTICAL);
var up:ScrollClickButton = sc.getUpButton(this.clipUp);
var dn:ScrollClickButton = sc.getDownButton(this.clipDown);
 
var dr:ScrollDragButton = sc.getScroller(this.clipScroller, //on indique le clip qui fait office de scroller
                                         this.clipBcg, //on indique le clip qui fait le background du scroller
                                         ScrollType.VERTICAL, //on défini que ce scroller est vertical (vous pouvez gérer un contenu verticalement avec un scroller horizontal)
                                         0 //on indique que le scroller va directement à la position de la souris (0 ou valeur négative), sinon la vitesse de scroll
                                         );

et hop ! Notre scroller fonctionne !

• PS1 : pour que le scroller fonctionne correctement, il faut que le clipScroller (petit rectangle) soit exactement à la même position _x et _y que le clipBcg (arrière-plan) ⇒ ceci est du au fait que le drag & drop du scroller prend le clipBcg comme délimiteur (cela n'est plus nécessaire depuis la version 1.5)
• PS2 : prenez garde à ce que votre clipBcg soit plus large (et plus long ) que votre clipScroller
  

Depuis la version 1.8, vous pouvez également faire en sorte que votre scroller se resize automatiquement lorsque le contenu change (cf l'exemple fourni avec les sources) :

import ch.component.scrollbar.*;
 
var sc:ScrollBar = ScrollBar.create(this.clipTarget, this.clipMask, ScrollType.VERTICAL);
var up:ScrollClickButton = sc.getUpButton(this.clipUp);
var dn:ScrollClickButton = sc.getDownButton(this.clipDown);
var dr:ScrollDragButton = sc.getScroller(this.clipScroller, this.clipBcg, ScrollType.VERTICAL, 0);
dr.autoAdjust = true; //ajustement automatique
dr.minimalSize = 5; //taille minimum (v1.9)
dr.maximalSize = 15; //taille maximum (v1.9)

On ajoute à tout cela la gestion de la molette :

import ch.component.scrollbar.*;
 
var sc:ScrollBar = ScrollBar.create(this.clipTarget, this.clipMask, ScrollType.VERTICAL);
var up:ScrollClickButton = sc.getUpButton(this.clipUp);
var dn:ScrollClickButton = sc.getDownButton(this.clipDown);
var dr:ScrollDragButton = sc.getScroller(this.clipScroller, this.clipBcg, ScrollType.VERTICAL, 0);
var sr:ScrollWheelButton = sc.getWheelButton(this.clipTarget, true);

Un peu plus dur à comprendre : on défini l'écouteur de la molette par rapport à un MovieClip. En effet, lorsque la méthode onMouseWheel est appelée, elle passe un MovieClip en paramètre. Cela signifie que si le clip reçu en paramètre fait partie du clip défini dans la méthode getWheelButton, la ScrollBar sera affectée. Le boolean sert à définir si la valeur de scroll par défaut sera utilisée (cf classe ScrollBar), sinon, c'est le delta qui sera pris en compte (cf Mouse.onMouseWheel) !

• PS : afin que la molette fonctionne correctement, pensez à ce que votre clip soit “plein”. S'il y a des parties de votre clip à scroller qui ne contient rien (aucun élément), celui-ci ne sera pas passé en paramètre à Mouse.onMouseWheel, ce qui aura pour effet de ne rien faire fonctionner. Pour éviter cela, mettez par exemple un rectangle avec _alpha à 0% en fond.

Depuis la version 1.6 du package, vous avez la possibilité de permettre à l'utilisateur de déplacer directement le contenu (ou autre) et de maintenir les ScrollBar à jour. Par défaut, la classe ScrollBar vous offre la possibilité de déplacer le contenu :

import ch.component.scrollbar.*;
 
var sc:ScrollBar = ScrollBar.create(this.clipTarget, this.clipMask, ScrollType.VERTICAL);
var up:ScrollClickButton = sc.getUpButton(this.clipUp);
var dn:ScrollClickButton = sc.getDownButton(this.clipDown);
var dr:ScrollDragButton = sc.getScroller(this.clipScroller, this.clipBcg, ScrollType.VERTICAL, 0);
var sr:ScrollWheelButton = sc.getWheelButton(this.clipTarget, true);
var sh:ScrollHandButton = sc.getHandButton();

Aucun paramètre n'a besoin d'être passé, ce sera le contenu (clipTarget dans notre cas) qui sera pris en compte. Bien entendu, vous pouvez aller bien plus loin avec la gestion de ce contenu (typiquement si vous avez plusieurs scrollbar sur le même clip). Des exemples sont fournis dans la documentation !

La dernière version du framework permet aussi de gérer les marges (haut/bas - gauche/droite) du contenu. Par défaut les marges sont à zéro, mais vous pouvez les changer très facilement. Nous allons mettre une marge de 5 pixels en haut et de 10 pixels en bas :

import ch.component.scrollbar.*;
 
var sc:ScrollBar = ScrollBar.create(this.clipTarget, this.clipMask, ScrollType.VERTICAL);
var up:ScrollClickButton = sc.getUpButton(this.clipUp);
var dn:ScrollClickButton = sc.getDownButton(this.clipDown);
var dr:ScrollDragButton = sc.getScroller(this.clipScroller, this.clipBcg, ScrollType.VERTICAL, 0);
var sr:ScrollWheelButton = sc.getWheelButton(this.clipTarget, true);
 
sc.getModel().setMargins(5, 10);

Depuis la version 1.9, vous pouvez gérer un ContentPane / ScrollPane grace à la classe ch.component.scrollbar.ScrollPane :

import ch.component.scrollbar.*;
var sp:ScrollPane = new ScrollPane(this.clipContent, this.clipMask);
var vs:ScrollBar = sp.getVerticalScrollBar();
var hs:ScrollBar = sp.getHorizontalScrollBar();
//...

Voici un exemple mixant plusieurs fonctionnalités offertes par la ScrollBar API :

Voici une liste des principales fonctionnalités fournies par ce framework :

• gestion des boutons de scrolls (flèches haut et bas)
• gestion d'un scroller (partie centrale)
• gestion de la molette de la souris
• gestion de contenu à scroller verticalement ou horizontalement
• gestion de ScrollBar horizontales et verticales
• gestion de plusieurs contenus multiples via une seule ScrollBar
• gestion de plusieurs ScrollBar avec un seul contenu
• gestion des marges
• gestion de déplacement direct du contenu
• gestion inverse d'une ScrollBar horizontale ou verticale
• gestion d'un contentpane / scrollpane

Ce framework est compatible Flash MX 2004 (7) et Flash 8. Il n'est pas supporté par Flash MX (6) à cause de la gestion des exceptions !

A noter que pour être compatible Flash MX 2004, 2 lignes sont à changer dans la classe ScrollBarModel :

super.addListener(listener);
 
//à remplacer par
super.addListener(Object(listener));

super.removeListener(listener);
 
//à remplacer par
super.removeListener(Object(listener));

Bien sur, le package est pensé de manière à ce que vous puissiez facilement ajouter des effets sur vos scroll, gérer du contenu horizontalement, gérer plusieurs ScrollBar très facilement.
La documentation des sources vous permettra déjà de comprendre la plupart des fonctionnalités. N'hésitez pas à nous faire part de vos questions/suggestions sur le forum !

Version actuelle : 1.9 (25.04.2007)

Sources, documentation, exemples : télécharger / Documentation en ligne (générée avec as2api)