Come abbiamo visto nell'articolo introduttivo a BulkLoader sono disponibili tre tipi di evento, ovvero:
- COMPLETE;
- PROGRESS;
- ERROR.
L'evento COMPLETE viene lanciato quando tutti i file sono stati caricati: è bene notare che nel caso in cui anche un solo file non venga caricato correttamente, l'evento COMPLETE non verrà lanciato, per cui, qualora il nostro progetto dovesse avviarsi anche in mancanza di uno o più file, potrebbe essere buona idea affidarsi principalmente all'evento PROGRESS; solitamente la funzione associata all'evento COMPLETE si occupa solamente di avviare l'applicazione, eventualmente caricando i primi contenuti necessari al progetto.
Per quanto riguarda l'evento PROGRESS, potremmo utilizzarlo come "alternativa" all'evento COMPLETE, nel caso in cui non fossimo certi che tutti i file inseriti nel BulkLoader vengano caricati correttamente: potremo infatti controllare in ogni momento il numero di file caricati e il numero di file totali grazie alle proprietà itemsLoaded e itemTotal; ovviamente tali proprietà ci consentono anche la realizzazione di un preload, così da mostrare all'utente a che punto sia il caricamento dei file.
L'evento ERROR viene lanciato quando un file non viene caricato correttamente: possiamo sfruttare questo evento per sapere precisamente quale file dà problemi, grazie alla proprietà errors dell'evento.
Eventi per i singoli elementi
Gli stessi eventi possono essere associati anche ad un singolo elemento, inoltre per i singoli oggetti possiamo anche utilizzare gli eventi HttpStatus (BulkLoader.HTTP_STATUS), anch'esso lanciato se un file fallisce il caricamento, e Open (BulkLoader.OPEN) che viene lanciato all'apertura di un file, e per i contenuti in streaming, come possono essere audio e video, coincide con la possibilità di avviare il file; c'è poi un evento relativo ai soli video, CAN_BEGIN_PLAYING (BulkLoader.CAN_BEGIN_PLAYING) che indica quando di un file video sono state scaricate abbastanza parti da poterlo riprodurre senza interruzioni.
Per aggiungere un evento a un singolo file è necessario utilizzare il metodo get, che permette di utilizzare come parametro l'id associato al file oppure il suo percorso, in questo modo:
caricatore.get(id_file).addEventListener(BulkLoader.OPEN, file_aperto)
caricatore.get(percorso_del_file).addEventListener(BulkLoader.OPEN, file_aperto)
La necessità di usare eventi per un singolo file è abbastanza rara, dato che l'utilità del BulkLoader è quella di organizzare in maniera semplice il caricamento di una grande quantità di file, per cui è più frequente eseguire le operazioni una volta finito il caricamento di tutti gli elementi, tuttavia potremmo voler far partire la nostra applicazione dopo il caricamento di un determinato file senza dover attendere il caricamento di tutti gli altri, in questo caso può essere utile l'evento COMPLETE associato al singolo elemento.
Recuperare i contenuti caricati
Ora che abbiamo visto una panoramica pressoché completa del caricamento degli oggetti e degli eventi che è possibile utilizzare per monitorare lo stato del caricamento, sia globale che a livello di singolo file, possiamo vedere come recuperare i contenuti caricati: per questo la classe BulkLoader mette a disposizione metodi specifici per il tipo di contenuto da recuperare, oltre ad un generico metodo getContent che permette di recuperare anche contenuti di cui magari non conosciamo la tipologia.
La sintassi è molto semplice, basta utilizzare la variabile che fa riferimento al BulkLoader seguita dal comando getContent (o da quello specifico per il contenuto che stiamo cercando), specificando come parametro l'identificativo associato al file oppure il suo path, in questo modo:
// getContent generico
var file:* = caricatore.getContent(id_file)
var file:* = caricatore.getContent(path_del_file)
// Comando specifico (in questo caso per ricavare un oggetto Bitmap)
var file:Bitmap = caricatore.getBitmap(id_file)
var file:Bitmap = caricatore.getBitmap(path_del_file)
Notiamo come nel caso in cui utilizzassimo il comando generico getContent sia bene impostare come tipo della variabile il valore *, ovvero qualsiasi tipo, questo perché non conosciamo il tipo di oggetto che verrà creato; qualora invece lo conoscessimo, allora è più corretto usare i comandi specifici per quel tipo, come nell'esempio abbiamo usato getBitmap per caricare un'immagine e abbiamo di conseguenza impostato il tipo della variabile su Bitmap.
I comandi specifici disponibili con la classe BulkLoader sono i seguenti:
- getBitmap: restituisce un ogetto di tipo Bitmap; utilizzabile con i file di immagine;
- getBitmapData: restituisce un oggetto di tipo BitmapData; utilizzabile con i file di immagine;
- getXML: restituisce un oggetto XML; utilizzabile con i file xml;
- getText: restituisce un oggetto Stringa; utilizzabile con i file di testo;
- getMovieClip: restituisce un oggetto Movieclip; utilizzabile con i file SWF;
- getSound: restituisce un oggetto Sound, utilizzabile con i file MP3;
- getNetStream: restituisce un oggetto NetStream, utilzzabile con i file di tipo video;
- getNetStreamMetaData: restituisce un oggetto con le proprietà dei meta data dell'oggetto NetStream, anch'esso lavora con file di tipo video.
Attenzione all'uso del file di tipo SWF: il comando getMovieClip funziona sia con SWF esportati per Actiosncript 3 che con SWF esportati per versioni precedenti, ma soltanto quelli creati in formato AS3 saranno poi controllabili tramite azioni, altrimenti verrà restituito un oggetto di tipo AMV1Movie che non può invece essere controllato e potremo quindi solo limitarci a riprodurlo, senza peraltro poter sfruttare i normali comandi di riproduzione quali play, stop, gotoAndPlay e gotoAndStop. Se i file che verranno caricati dal BulkLoader saranno di nostra produzione ricordiamoci quindi di crearli come file Actionscript 3.
Due note sui file di tipo video: intanto il tipo di dato restituito dal BulkLoader è un oggetto NetStream, per cui non possiamo ad esempio associarlo direttamente al componente FLVPlayback, ma dovremo utilizzare le classi Video e appunto NetStream per visualizzarlo; altro aspetto importante, i file FLV caricati nel BulkLoader partiranno appena caricati, anche se non li avremo ancora recuperati: per evitare questo inconveniente, è sufficiente sfruttare il parametro pausedAdStart quando aggiungiamo il video al BulkLoader, in questo modo:
caricatore.add("video.flv",{pausedAtStart:true})
Gli oggetti di tipo Bitmap e MovieClip, una volta rilevati, possono essere aggiunti allo stage tramite il comando addChild, possiamo anche impostarne le varie proprietà quali posizionamento, trasparenza e altro:
// ricavo l'oggetto dal BulkLoader
var clip:MovieClip = caricatore.getMovieClip("file.swf")
// ne imposto la posizione
clip.x = 400
clip.y = 300
// e lo aggiungo al filmato
addChild(clip)
Gli oggetti di tipo XML potranno essere letti o manipolati grazie all'omonima classe, mentre gli oggetti di tipo String sono dei semplici testi che possiamo quindi inserire in un campo di testo (eventualmente dopo averli manipolati grazie alle apposite funzioni offerte da Flash); infine, gli oggetti di tipo Sound possono essere direttamente riprodotti grazie al comando play, associandoli eventualmente ad un SoundChannel, come di seguito:
var suono:Sound = caricatore.getSound("file.mp3")
var canale_suono:SoundChannel = suono.play()
Liberare memoria dopo il caricamento di un oggetto
Se l'oggetto che andiamo a caricare dalla classe BulkLoader non fosse più necessario in un secondo momento, sarebbe sicuramente utile eliminare il suo riferimento nel BulkLoader, così da liberare memoria per il player. Il comando getContent, così come gli specifici comandi per i vari tipi di file, offrono come secondo parametro opzionale cleanMemory, un valore booleano che permette proprio di eliminare il riferimento all'oggetto che ricaviamo; di default tale valore è impostato su false, ma basterà usare il seguente codice:
var clip:MovieClip = caricatore.getMovieClip("clip.swf",true)
per poter rimuovere l'oggetto clip.swf dalla memoria; ovviamente ne consegue che eventuali successivi tentativi di chiamata all'oggetto clip.swf falliranno, in quanto non sarà più presente nella memoria del player. Possiamo ottenere un risultato analogo usando il comando remove, in questo modo:
caricatore.remove("clip.swf")
Se invece volessimo rimuovere tutti gli elementi presenti in "caricatore", basterà usare il comando removeAll.
caricatore.removeAll()
Volendo è anche possibile eliminare tutti i BulkLoader presenti nella propria applicazione con il comando BulkLoader.removeAllLoaders()
Ricavare più copie di un elemento
Si potrebbe pensare che per ricavare due istanze di uno stesso SWF basti questo procedimento:
Listato {n}. {descrizione}
var clip1:MovieClip = caricatore.getMovieClip("clip.swf")
clip1.x = 100
var clip2:MovieClip = caricatore.getMovieClip("clip.swf")
clip2.x = 400
addChild(clip1)
addChild(clip2)
Non è così: con questo codice vedremo solo la clip posizionata alla posizione 400, questo perché anche più chiamate distinte dirette verso uno stesso file presente nel BulkLoader si tradurranno in chiamate al medesimo elemento, che verrà quindi magari aggiornato (come nell'esempio, dove passerà alla posizione x=400 da quella di x=100), ma non ne verranno create nuove istanze.
Qualora volessimo inserire nel nostro filmato più oggetti uilizzando come sorgente un file caricato dalla classe BulkLoader sarà necessario sfruttare la proprietà constructor dopo aver convertito il nostro elemento (per esempio un movieclip) in oggetto, in questo modo potremo ricavarne il costruttore e quindi creare quante istanze vorremo.
var clip:MovieClip = caricatore.getMovieClip("clip.swf")
var costruttore:Class = Object(clip).constructor
A questo punto possiamo utilizzare il costruttore ricavato per creare più istanze del nostro oggetto, per esempio in questo modo:
var c1:MovieClip = new costruttore()
c1.x = 100
var c2:MovieClip = new costruttore()
c2.x = 400
addChild(c1)
addChild(c2)
