Utilisation de l'API CellRenderer

Vous devez écrire une classe avec quatre méthodes (CellRenderer.getPreferredHeight(), CellRenderer.getPreferredWidth(), CellRenderer.setSize() et CellRenderer.setValue()) que le composant basé sur des listes utilisera pour communiquer avec la cellule (si la classe étend les fonctions de la classe UIObject, vous pouvez utiliser size() et non CellRenderer.setSize()). La classe doit être définie dans le champ de texte Classe de la boîte de dialogue Propriétés de liaison d'un symbole de clip dans votre application Flash.

A titre d'exemple, observez la classe CheckCellRenderer qui implémente l'API CellRenderer. Elle est située dans /Documents and Settings/utilisateur/Local Settings/Application Data/Adobe/Flash CS3/en/Configuration/Classes/mx/controls/cells. Reportez-vous également à la documentation du composant DataGrid pour consulter les informations sur CellRenderer, notamment Stratégies de performance DataGrid.

Deux méthodes et une propriété (CellRenderer.getCellIndex(), CellRenderer.getDataLabel() et CellRenderer.listOwner) sont automatiquement attribuées à une cellule pour lui permettre de communiquer avec le composant de listes. Supposons par exemple qu'une cellule contienne une case à cocher qui, lorsqu'elle est activée, entraîne la sélection d'une ligne. CellRenderer a besoin d'une référence au composant basé sur des listes qui le contient pour appeler la propriété selectedIndex de ce composant.
De même, cette API doit connaître l'élément d'index actuellement rendu pour pouvoir définir la propriété selectedIndex sur le nombre correct. Pour ce faire, elle peut utiliser les méthodes CellRenderer.listOwner et CellRenderer.getCellIndex(). Il n'est pas nécessaire d'implémenter ces éléments ActionScript car la cellule les reçoit automatiquement lorsqu'elle est placée dans le composant de listes.

Exemple simple de CellRenderer

Cette section présente un exemple de CellRenderer qui affiche plusieurs lignes de texte dans une cellule.

Le didacticiel suivant montre comment créer une classe CellRenderer affichant plusieurs lignes de texte dans les cellules d'un composant DataGrid.

Les fichiers complets, MultiLineCell.as et CellRenderer_tutorial.fla sont disponibles en ligne à l'adresse www.adobe.com/go/learn_fl_samples_fr.

Création de la classe CellRenderer MultiLineCell

Une classe CellRenderer doit implémenter les méthodes suivantes :

CellRenderer.getPreferredHeight()
CellRenderer.getPreferredWidth()
La méthode CellRenderer.getPreferredWidth() est nécessaire uniquement pour les composants Menu ou DataGrid ; sinon, commentez-la hors code, comme indiqué dans l'exemple.
CellRenderer.setSize()
Si une classe CellRenderer étend les fonctions de la classe UIObject, utilisez à la place implement size(), comme indiqué dans l'exemple.
CellRenderer.setValue()

Une classe CellRenderer doit également déclarer les méthodes et la propriété reçues de la classe List :

Les étapes suivantes montrent comment créer un fichier de classe CellRenderer ActionScript 2, nommé MultiLineCell.as, et comment le lier à un nouveau symbole de clip dans un nouveau document Flash. Vous pouvez ensuite ajouter un composant DataGrid à la bibliothèque de document Flash. Sur la première image, ajoutez le code ActionScript qui crée de façon dynamique le composant DataGrid et affecte la classe MultiLineCell comme CellRenderer pour l'une de ses colonnes :

Pour créer la classe CellRenderer MultiLineCell :

Sélectionnez Fichier > Nouveau, puis choisissez Fichier ActionScript.
Enregistrez le fichier sous le nom MultiLineCell.as.

Entrez le code suivant dans le fichier MultiLineCell.as :

// ActionScript 2.0 class.
class MultiLineCell extends mx.core.UIComponent
{
    private var multiLineLabel; // Etiquette à utiliser pour le texte.
    private var owner; // Ligne qui contient cette cellule.
    private var listOwner; // Composant List, DataGrid ou Tree contenant
// cette cellule.

    // Décalage de la hauteur de cellule par rapport à la hauteur totale 
// de la ligne et largeur de cellule préférée.
    private static var PREFERRED_HEIGHT_OFFSET = 4; 
    private static var PREFERRED_WIDTH = 100;
    // Profondeur de départ.
    private var startDepth:Number = 1;

    // Constructeur. Doit être vide.
    public function MultiLineCell()
    {
    }

    /* UIObject attend que vous renseigniez createChildren en instanciant tous les actifs du clip dont vous pouvez avoir besoin après l'initialisation. Dans ce cas, nous créons une étiquette*/
    public function createChildren():Void
    {
        // La méthode createLabel est une méthode utile de la classe
// UIObject et constitue un
        // moyen pratique pour créer des étiquettes dans des composants.
        var c = multiLineLabel = this.createLabel("multiLineLabel", startDepth);
        // Lie le style de l'étiquette à celui de la grille.
        c.styleName = listOwner;
        c.selectable = false;
        c.tabEnabled = false;
        c.background = false;
        c.border = false;
        c.multiline = true;
        c.wordWrap = true;
    }

    public function size():Void
    {
/* En étendant UIComponent qui importe UIObject, vous obtenez automatiquement la méthode setSize ; cependant UIComponent attend que vous implémentiez size(). Supposons que __width et __height soient définis. Vous allez élargir la cellule pour l'adapter à rowHeight. rowHeight est une propriété du composant de type List dans lequel nous rendons une cellule. Dans la mesure où nous souhaitons que rowHeight s'adapte sur deux lignes, lors de la création du composant de type List à l'aide de cette classe CellRenderer, vérifiez que la propriété rowHeight est suffisamment large pour que deux lignes de texte puissent être rendues dedans.*/
    
/*__width et __height sont les variables sous-jacentes de lecture/définition .width et .height.*/
        var c = multiLineLabel;
        c.setSize(__width, __height);
    }

    // Indique la hauteur préférée de la cellule. Méthode héritée.
    public function getPreferredHeight():Number
    {
/* La cellule reçoit la propriété « owner », qui référence la ligne. 
Il est toujours préférable que la cellule corresponde à la hauteur de la ligne. Dans ce cas, nous conservons la cellule d'une taille légèrement inférieure.*/
        return owner.__height - PREFERRED_HEIGHT_OFFSET;
    }

    // Appelé par le propriétaire pour définir la valeur 
// de la cellule. Méthode héritée.
    public function setValue(suggestedValue:String, item:Object, selected:Boolean):Void
    {
/* Si l'élément n'est pas défini, rien ne doit être rendu dans la cellule. Définissez donc l'étiquette comme étant invisible. Remarque : pour faire défiler des composants de type List comme un composant DataGrid, les cellules doivent être vides dans la mesure où elles défilent hors de vue, puis elles sont réutilisées et définies sur une nouvelle valeur, ce qui produit un effet animé de défilement. C'est pourquoi, vous ne pouvez pas utiliser de cellule disposant toujours de données ou d'une même valeur.*/
        if (item==undefined){
            multiLineLabel.text._visible = false;
        }
        multiLineLabel.text = suggestedValue;
    }
    // fonction getPreferredWidth : uniquement pour les menus et 
// les en-têtes DataGrid
    // fonction getCellIndex : non utilisée pour cette classe CellRenderer
    // fonction getDataLabel : non utilisée pour cette classe CellRenderer
}

Création d'une application pour tester la classe de rendu de cellule MultiLineCell

Dans la procédure suivante, vous allez créer l'occurrence DataGrid et implémenter la classe MultiLineCell.

Pour créer une application avec un composant DataGrid utilisant la classe MultiLineCell :

Sélectionnez Fichier > Nouveau, puis choisissez Fichier Flash (ActionScript 2.0).
Choisissez Fichier > Enregistrer sous, nommez le fichier cellRender_tutorial.fla, puis enregistrez-le dans le dossier qui contient le fichier MultiLineCell.as.
Pour créer un symbole movieClip à lier à la classe MultiLineCell, choisissez Insertion > Nouveau symbole.
Dans la zone de texte Nom, tapez MultiLineCell.
La valeur par défaut du Type est Animation. Laissez cette valeur sélectionnée.
Si l'écran des paramètres avancés n'est pas affiché, cliquez sur le bouton Avancé.
Dans la section Liaison, activez la case à cocher Exporter pour ActionScript.
L'activation de cette option vous permet de joindre dynamiquement des occurrences de ce symbole à vos documents Flash pendant l'exécution. La zone de texte Identifiant affiche automatiquement MultiLineCell.
Définissez la Classe ActionScript 2.0 sur MultiLineCell (pour faire correspondre le nom de la classe MultiLineCell que vous avez créée précédemment).

Assurez-vous que l'option Exporter dans la première image est bien activée, puis cliquez sur OK.

REMARQUE

Si vous devez modifier les propriétés de liaison du symbole du clip MultiLineCell, cliquez avec le bouton droit sur le symbole dans la bibliothèque du document, puis sélectionnez Propriétés ou Liaison dans le menu contextuel.

Faites glisser le composant DataGrid du panneau Composants jusqu'à la bibliothèque.
L'occurrence DataGrid est créée de façon dynamique par ActionScript à l'étape suivante.
Sélectionnez la première image du scénario principal (vérifiez que vous n'êtes pas encore en mode édition du clip MultiLineCell).

Dans le panneau Actions de la première image, entrez le code suivant pour créer de façon dynamique un composant DataGrid, lui affecter des données et affecter votre nouvelle classe CellRenderer :

// Création d'une occurrence du composant DataGrid. 
this.createClassObject(mx.controls.DataGrid, "myGrid_dg", 1);

// Création d'un fournisseur de données pour la grille de 
// données comportant quatre colonnes.
myDP = new Array();
var aLongString:String = "An example of a cell renderer class that displays a multiple line TextField";
myDP.addItem({firstName:"Winston", lastName:"Elstad", note:aLongString, item:100});
myDP.addItem({firstName:"Ric", lastName:"Dietrich", note:aLongString, item:101});   
myDP.addItem({firstName:"Ewing", lastName:"Canepa", note:aLongString, item:102});   
myDP.addItem({firstName:"Kevin", lastName:"Wade", note:aLongString, item:103});   
myDP.addItem({firstName:"Kimberly", lastName:"Dietrich", note:aLongString, item:104});   
myDP.addItem({firstName:"AJ", lastName:"Bilow", note:aLongString, item:105});   
myDP.addItem({firstName:"Chuck", lastName:"Yushan", note:aLongString, item:106});
myDP.addItem({firstName:"John", lastName:"Roo", note:aLongString, item:107});

/* Affectation du fournisseur de données au composant DataGrid pour le remplir. Remarque : vous devez effectuer cette procédure avant d'appliquer CellRenderer. */
myGrid_dg.dataProvider = myDP;

/* Définition de certaines propriétés de grille basiques. Remarque : La hauteur de ligne de la grille de données doit refléter le nombre de lignes que vous souhaitez dans la classe CellRenderer MultiLineCell. Elle s'adapte à la hauteur de ligne. Pour la taille du texte par défaut, elle doit être approximativement de 40 pour 2 lignes ou 60 pour 3 lignes.*/
myGrid_dg.setSize(430,200);
myGrid_dg.move(40,40);
myGrid_dg.rowHeight = 40; // Définition de 2 lignes de texte comme 
// taille du texte par défaut.
myGrid_dg.getColumnAt(0).width = 70;
myGrid_dg.getColumnAt(1).width = 70;
myGrid_dg.getColumnAt(2).width = 220;
myGrid_dg.resizableColumns = true;
myGrid_dg.vScrollPolicy = "auto";
myGrid_dg.setStyle("backgroundColor", 0xD5D5FF); 

// Affectation de la classe CellRenderer.
myGrid_dg.getColumnAt(2).cellRenderer = "MultiLineCell";

Enregistrez le document Flash, puis choisissez Contrôle > Tester l'animation.
Une grille de données s'affiche. Sa troisième colonne contient une cellule à plusieurs lignes.

Exemple de classe MultiLineCell complète.

Autres exemples de classes CellRenderer

D'autres exemples de classes CellRenderer affichant un composant ComboBox et un composant CheckCell sont également fournis. Les exemples sont disponibles en ligne à l'adresse www.adobe.com/go/learn_fl_samples_fr.

Autre exemple installé, nommé CellRenderers_Sample, et affichant un composant ComboBox et un composant CheckBox.

Méthodes à implémenter pour l'API CellRenderer

Pour que les composants List, DataGrid, Tree ou Menu puissent communiquer avec la cellule, vous devez écrire une classe avec les méthodes suivantes.

Méthode	Description
CellRenderer.getPreferredHeight()	Renvoie la hauteur préférée d'une cellule.
CellRenderer.getPreferredWidth()	Renvoie la largeur préférée d'une cellule.
CellRenderer.setSize()	Définit la largeur et la hauteur d'une cellule.
CellRenderer.setValue()	Définit le contenu à afficher dans la cellule.

Méthodes fournies par l'API CellRenderer

Les composants List, DataGrid, Tree et Menu fournissent les méthodes suivantes à la cellule lors de sa création dans l'un de ces composants. Il n'est donc pas nécessaire de les implémenter.

Méthode	Description
CellRenderer.getCellIndex()	Renvoie un objet avec deux champs, `columnIndex` et `itemIndex`, qui indiquent la position de la cellule.
CellRenderer.getDataLabel()	Renvoie une chaîne contenant le nom du champ de données du composant CellRenderer.

Propriétés fournies par l'API CellRenderer

Les composants List, DataGrid, Tree et Menu fournissent les propriétés suivantes à la cellule lors de sa création dans le composant. Il n'est donc pas nécessaire de les implémenter.

Propriété	Description
CellRenderer.listOwner	Référence au composant List contenant la cellule.
CellRenderer.owner	Référence à la ligne contenant la cellule.