Adobe^® Flex^™ Tutorial

Il y a quelques jours, je vous présentais la "ToasterLib", une librairie que j'ai crée permettant d'afficher facilement des notifications dans vos applications Flex. Par notification, j'entends les petits messages que l'on reçoit souvent dans les logiciels bureautiques type MSN, GTalk, avast! et autres.

Pour ceux qui ont raté un épisode, un petit rappel:

ToasterLib – Affichez des notifications dans vos applications Flex

ToasterLib sur Google Code

Pendant ces longues soirées/nuits de code, j'ai pensé au fonctionnement dont j'avais besoin (affichage de notifications en bas à droite), mais aussi à tout ce que les développeurs Flex qui vont télécharger cette librairie (oui, vous) vont pouvoir demander comme fonctionnalités, qu'elles soient utiles ou juste fun. Je n'ai bien sûr pas pensé à tout ou pas tout réaliser à la perfection mais tout comme la DataFilterLib, le projet est open source en licence "vous-en-faites-ce-que-bon-vous-semble". N'hésitez donc pas à demander des améliorations ou à proposer des patchs!

Bref, ce billet va exposer les fonctionnalités "avancées" déjà développées de la librairie. Je vais essayer d'accompagner les explications avec un maximum de code et d'exemples.

Comprendre l'architecture globale de la ToasterLib

Les sources du projet sont disponibles sur la page Google Code de la ToasterLib, en libre accès. Je vais résumer rapidement comment j'ai construit cette librairie.

Alors tout en haut, on a le composant Toaster qui est le composant graphique principal mais aussi la classe d'accès pour pouvoir envoyer de toasts. Le Toaster contient des ToastContainer.

Un ToastContainer est lui aussi un objet graphique qui dérive au moins de la classe ToastContainerBase. Un ToastContainer représente un emplacement dans lequel les toasts vont s'afficher. Pour faire simple, un ToastContainer est "un coin" dans lequel on a les toasts (même si on peut afficher les toasts dans les 9 directions). Chaque ToastContainer peut être configuré comme on le verra plus loin. Un ToastContainer va contenir des ToastMessage.

Un ToastMessage est un composant visuel lui aussi qui est en fait la notification affichée à l'écran. Pour faire simple, un ToastMessage est un composant qui hérite de ToastMessageBase. On verra donc que pour créer ses propres notifications, il suffit de créer un composant qui hérite de cette classe.

2 modes de fonctionnement: Par instance ou en Singleton

Les notifications peuvent être lancées pour de très nombreuses manières. Vous pourriez donc en avoir besoin un peu partout dans votre application. Au lieu de devoir référencer votre composant Toaster dans toutes les classes de votre applications, vous pouvez y accéder en tant que Singleton:

Toaster.toast(toastMessage, position);

Alors bien sûr, dans ce cas, vous ne pouvez avoir qu'un seul Toaster dans votre application ce qui va être le cas pour la plupart des applications. Mais je n'ai pas bridé la ToasterLib, vous pouvez donc en avoir plusieurs si vous le souhaitez. Cette fois, vous devrez y accéder directement par l'instance, les méthodes static (Singleton) et les méthodes classique (par instance) ont les mêmes signatures. C'est simplement le comportement derrière qui est spécifique.

Pour accéder aux instances de Toaster, pas de mystère:

<mx:Script>
 <![CDATA[
myToaster.toast(toastMessage, position);

 ]]>
 </mx:Script>
<fnicollet:Toaster id="myToaster" width="100%" height="100%" />

Configuration globale du Toaster

Vous avez accès à des propriétés globales sur le Toaster, pour une utilisation simplifiée en Singleton. Par exemple, si vous ne voulez pas spécifier tout le temps de "position" dans la méthode toast (Bottom-Right par défaut), vous pouvez utiliser la propriété "globalPosition":

Toaster.globalPosition = ToasterPosition.BOTTOM_LEFT;

D'autres propriétés sont disponibles, qui vont être propagées à tous les ToastContainer. Par exemple useLocalPosition (voir explication plus loin).

Définition d'un composant parent pour votre Toaster

De base, si vous ne définissez pas cette propriété, le Toaster va prendre 100% de la taille de l'application. Les notifications apparaîtront donc par dessous tout. Seulement, vous pouvez restreindre cette zone en donnant une référence vers un composant visuel de votre application. Par exemple, pour mon application cartographique, il a fallut que je n'affiche les notifications que sur la zone réservée à a carte. Il ne fallait pas que les notifications empiètent sur le bandeau de l'application ou sur les copyrights.

Pour utiliser un parent, votre code doit se présenter comme ceci:

<fnicollet:Toaster width="100%" height="100%" toastContainerParent="{myComponent}" />

Pour des raisons qui me sont parfois inconnues, vous aurez peut-être à mettre la propriété "useLocalPosition" à true. Si des décalages apparaissent, essayez cela

Configuration des "ToasterContainer" (temps d'affichage, bloquage au rollOver, ...)

Vous pouvez configurer les ToasterContainer (les coins) avec diverses options. Tout cela se passe de manière déclarative, en MXML, dans la déclaration du Toaster.

Au moment où vous allez afficher une notification, disons dans le coin "BR" (Bottom-Right). Si aucune instance n'a été définie en MXML, le Toaster va en créer une automatiquement avec des paramètres de base. Si une instance est définie en MXML, le Toaster utilisera cette instance (une sorte de "lazy-instanciation").

Comme vous pouvez utiliser plusieurs ToastContainer, il faut les identifier par leur position (pas d'id). Exemple, pour instancier le ToastContainer "BR":

<fnicollet:Toaster width="100%" height="100%">
 <fnicollet:containers>
  <fnicollet:ToasterContainerBase position="{ToasterPosition.BOTTOM_RIGHT}"/>
 </fnicollet:containers>
</fnicollet:Toaster>

Propriété lockOnRollOver (Boolean true par défaut)

Ce Boolean indique s'il faut ou non arrêter la disparition du Toaster au rollOver. En effet, de base, un ToastMessage à une durée de vie de 8 secondes. Après cela, il va se cacher automatiquement. En mettant lockOnRollOver à true, vous indiquez au conteneur qu'il ne faut pas cacher les ToastMessage quand vous laissez la souris dessus. Cela est pratique pour laisser à l'utilisateur le temps de voir le message s'il en a envie. C'est comme cela que fonctionnent les notifications MSN.

Propriété useLocalPosition (Boolean false par défaut)

Cette propriété est utile si vous utilisez un "toastContainerParent" sur votre Toaster. Il va indiquer au calcul de position des messages s'il doit utiliser une position locale au composant ou à l'application. En gros, si vous trouvez un décalage dans votre application et que vous utilisez un toastContainerParent, essayez de mettre useLocalPosition à true et cela peut résoudre le problème (j'avoue, parfois cela fonctionne, parfois pas et je ne sais pas vraiment pourquoi mais l'option est là!).

Propriété effectDescriptor (type IToasterEffectDescriptor, new ToasterEffectDescriptorBase par défaut)

La propriété effectDescriptor permet de spécifier pour un ToastContainer, une classe qui va gérer les effets appliqués aux messages. Vous l'avez sûrement remarqué, quand ils arrivent/repartent/se stackent, les messages ont des effets qui leur sont appliqué (Fade, Blur, Move, ...). Ces effets sont décrits dans une classe nommée ToasterEffectDescriptorBase qui implémente IToasterEffectDescriptor.

Si vous voulez avoir vos propres effets (avec easing par exemple), vous pouvez soit créer une classe qui implémente IToasterEffectDescriptor, soit une classe qui hérite de ToasterEffectDescriptorBase et surcharger les méthodes que vous souhaitez.

Il vous suffit ensuite de passer une référence vers une instance de votre classe d'effet et le tour est joué. Pour des exemples d'IToasterEffectDescriptor, inspirez vous du code de ToasterEffectDescriptorBase

Evènements "onToastAdded" (ToastEvent.ON_TOAST_ADDED) et "onToastRemoved" (ToastEvent.ON_TOAST_REMOVED)

Si vous en avez envie, les ToastContainer dispatchent des évènements à l'ajout / suppression de ToastMessage dans leur stack.

Exemple:

<fnicollet:Toaster width="100%" height="100%" toastContainerParent="{mainApplication}">
 <fnicollet:containers>
 <fnicollet:ToasterContainerBase position="{ToasterPosition.BOTTOM_RIGHT}" onToastAdded="onToastAddedHandler(event)"/>
 </fnicollet:containers>
 </fnicollet:Toaster>

Créer des notifications au look personnalisé

La ToasterLib ne vous contraint pas dans le choix de ce que vous pouvez toaster. Toutes les classes qui héritent de ToastMessageBase peuvent être toastées. Sachant que ToastMessageBase hérite de Box, vous pouvez vous autorisez tous les délires de composants et de skin possibles.

Notez que comme vous héritez de ToastMessageBase, vous avez accès à certaines méthodes de cette classe comme la méthode "close()" qui fait faire disparaitre la notification sans attendre.

Voici un exemple pour la skin GTalk:

<?xml version="1.0" encoding="utf-8"?>
<ToastMessageBase xmlns="com.fnicollet.toaster.message.*" xmlns:mx="http://www.adobe.com/2006/mxml"
                  width="264" height="88" borderThickness="2" borderColor="#7B96C6"
                  borderStyle="solid" backgroundColor="white">

  <mx:Script>
    <![CDATA[
      [Bindable]
      public var sampleCaption:String = "Test de texte sur 2 lignes\ncar trop long";
      [Bindable]
      public var imageSource:String = null;
    ]]>
  </mx:Script>
  <mx:Canvas width="100%" height="100%" horizontalScrollPolicy="off" verticalScrollPolicy="off">
    <mx:Button upSkin="@Embed('/com/fnicollet/toaster/skin/gtalk/assets/closeButton.gif')"
               overSkin="@Embed('/com/fnicollet/toaster/skin/gtalk/assets/closeButton.gif')"
               downSkin="@Embed('/com/fnicollet/toaster/skin/gtalk/assets/closeButton.gif')"
               click="close()" useHandCursor="true" buttonMode="true" right="5" top="5"/>
    <mx:Image id="avatar" x="9" y="17" width="64" height="48" source="{imageSource}"/>
    <mx:Label id="userName" fontWeight="bold" fontSize="12" x="80" y="15" text="Monsieur X"
              fontFamily="Arial"/>
    <mx:Text id="caption" x="80" y="30" fontSize="12" fontFamily="Arial" text="{sampleCaption}"
             width="160" height="40" selectable="false"/>
  </mx:Canvas>

</ToastMessageBase>

Notez que des exemples sont disponibles dans la librairie (skin avast!, GTalk et Ubuntu).

Pour toaster ce message, rien de plus simple:

var toastMessage:ToastMessageGTalk = new ToastMessageGTalk;
toastMessage.imageSource = "assets/avatar1.png";
toastMessage.sampleCaption = "Encore un test!";
Toaster.toast(toastMessage);

D'autres exemples des capacités de la ToasterLib...

• ToasterLib – Affichez des notifications dans vos applications Flex
• ToasterLib – Gestion du resize en v1.0.2
• Flex UIComponent – Instances et Propriétés génériques des UIComponent
• Flex / Air – Centrer une fenêtre Air (Window ou WindowedApplication)
• Flex Skin: Utilisation des Skins Graphiques (jpg, png …) et Scale-9