Loader  - AS3

Contiene el objeto de visualización raíz del archivo SWF o el archivo de imagen (JPG, PNG o GIF) que se cargó empleando los métodos load() o loadBytes().

Elementos de API relacionados

Devuelve un objeto LoaderInfo que corresponde al objeto que se está cargando. Los objetos LoaderInfo se comparten entre el objeto Loader y el objeto de contenido cargado. El objeto LoaderInfo proporciona información de progreso de carga y estadísticas sobre el archivo cargado.

Los eventos relacionados con la carga se distribuyen mediante el objeto LoaderInfo al que hace referencia la propiedad contentLoaderInfo del objeto Loader. La propiedad contentLoaderInfo se establece como un objeto LoaderInfo válido, antes incluso de que se cargue el contenido, de modo que se puedan añadir detectores de eventos al objeto antes de la carga.

Para detectar errores no capturados producidos en un archivo SWF cargado, utilice la propiedad Loader.uncaughtErrorEvents no la propiedad Loader.contentLoaderInfo.uncaughtErrorEvents.

Elementos de API relacionados

var url:String = "http://www.helpexamples.com/flash/images/image2.jpg";
var urlRequest:URLRequest = new URLRequest(url);
var loader:Loader = new Loader();
loader.contentLoaderInfo.addEventListener(Event.COMPLETE, loader_complete);
loader.load(urlRequest);
addChild(loader);
 
function loader_complete(evt:Event):void {
    var target_mc:Loader = evt.currentTarget.loader as Loader;
    target_mc.x = (stage.stageWidth - target_mc.width) / 2;
    target_mc.y = (stage.stageHeight - target_mc.height) / 2;
}

Un objeto que distribuye un evento uncaughtError cuando se produce un error no gestionado en el archivo SWF cargado por este objeto Loader. Un error sin capturar se produce cuando se emite un error fuera de los bloques try..catch o cuando un objeto ErrorEvent se distribuye sin ningún detector registrado.

Observe que una propiedad uncaughtErrorEvents del objeto Loader distribuye eventos que se propagan a través de él, no eventos que distribuyen directamente. Nunca distribuye un evento uncaughtErrorEvent en la fase de destino. Sólo distribuye el evento en las fases de captura y propagación. Para detectar un error sin capturar en el SWF actual (el archivo SWF en el que el objeto Loader está definido), utilice la propiedad LoaderInfo.uncaughtErrorEvents en su lugar.

Si el contenido cargado por el objeto Loader es un archivo SWF AVM1 (ActionScript 2), los errores no detectados en el archivo SWF AVM1 no producen un evento uncaughtError.

Elementos de API relacionados

package
{
    import flash.display.Loader;
    import flash.display.Sprite;
    import flash.events.ErrorEvent;
    import flash.events.UncaughtErrorEvent;
    import flash.net.URLRequest;

    public class LoaderUncaughtErrorEventExample extends Sprite
    {
        private var ldr:Loader;
        
        public function LoaderUncaughtErrorEventExample()
        {
            ldr = new Loader();
            ldr.load(new URLRequest("child.swf"));
            ldr.uncaughtErrorEvents.addEventListener(UncaughtErrorEvent.UNCAUGHT_ERROR, uncaughtErrorHandler);
        }
        
        private function uncaughtErrorHandler(event:UncaughtErrorEvent):void
        {
            if (event.error is Error)
            {
                var error:Error = event.error as Error;
                // do something with the error
            }
            else if (event.error is ErrorEvent)
            {
                var errorEvent:ErrorEvent = event.error as ErrorEvent;
                // do something with the error
            }
            else
            {
                // a non-Error, non-ErrorEvent type was thrown and uncaught
            }
        }
    }
}

Crea un objeto Loader que puede utilizar para cargar archivos como, por ejemplo, archivos SWF, JPEG, GIF o PNG. Llame al método load() para cargar el activo como elemento secundario de la instancia de Loader. Posteriormente, puede añadir el objeto Loader a la lista de visualización (por ejemplo, empleando el método addChild() de una instancia de DisplayObjectContainer). El activo aparece en el escenario conforme se va cargando.

También puede utilizar una instancia "offlist" de Loader, es decir, sin añadirla a un contenedor de objeto de visualización de la lista de visualización. En este modo, la instancia de Loader podría utilizarse para cargar un archivo SWF que contuviera módulos adicionales de una aplicación.

Para detectar cuándo termina de cargarse el archivo SWF, puede utilizar los eventos del objeto LoaderInfo asociado a la propiedad contentLoaderInfo del objeto Loader. Al llegar a ese punto, puede ejecutarse el código del archivo SWF de módulo para inicializar e iniciar el módulo. En el modo offlist (fuera de la lista), una instancia de Loader podría utilizarse para cargar un archivo SWF que contuviera componentes o elementos multimedia adicionales. Una vez más, puede utilizar las notificaciones de eventos de objeto LoaderInfo para detectar cuándo terminan de cargarse los componentes. Al llegar a este punto, la aplicación puede comenzar a utilizar los componentes y elementos multimedia de la biblioteca del archivo SWF mediante la creación de instancias de las clases de ActionScript 3.0 que representan a dichos componentes y elementos.

Para determinar el estado de un objeto Loader, controle los siguientes eventos del objeto LoaderInfo asociado a la propiedad contentLoaderInfo del objeto Loader:

• El evento open se distribuye cuando comienza la carga.
• El evento ioError o securityError se distribuye si el archivo no se puede cargar o si se produce un error durante el proceso de carga.
• El evento progress se activa continuamente mientras se está cargando el archivo.
• El evento complete se distribuye cuando finaliza la descarga de un archivo, pero antes de que estén disponibles los métodos y propiedades del clip de película cargado.
• El evento init se distribuye una vez que estén accesibles las propiedades y los métodos del archivo SWF cargado, de manera que pueda comenzar a manipular el archivo SWF cargado. Se distribuye este evento antes que el controlador complete. Al transmitir mediante flujo archivos SWF, el evento init puede tener lugar bastante antes que el evento complete. En la mayoría de los casos, utilice el controlador init.

Notas (solo iOS): En aplicaciones de AIR en iOS, solo se puede cargar desde el paquete de la aplicación un archivo SWF con ActionScript. Esta restricción incluye cualquier ActionScript, incluidos los activos con nombres de clase exportados para ActionScript. Para cargar un archivo SWF debe usar el mismo dominio de aplicación que el del archivo SWF principal correspondiente.

En versiones anteriores a AIR 3.6 solo se pueden cargar archivos SWF que no contengan código de bytes ActionScript, tanto si se cargan desde el paquete de la aplicación como a través de una red. En lugar de usar un archivo SWF externo con ActionScript, puede crear una biblioteca de SWC y vincularla al SWF principal.

Estas restricciones no afectan a casos en que la aplicación se ejecuta en el simulador de iOS (ipa-test-interpreter-simulator o ipa-debug-interpreter-simulator) o en modo de intérprete (ipa-test-interpreter o ipa-debug-interpreter.)

Elementos de API relacionados

Cancela una operación de método load() que está actualmente en curso para la instancia de Loader.

Elementos de API relacionados

Carga un archivo SWF, JPEG, JPEG progresivo, GIF sin animar o PNG en un objeto que es un elemento secundario de este objeto Loader. Si carga un archivo GIF animado, sólo aparece el primer fotograma. Dado que el objeto Loader sólo puede contener un único elemento secundario, la emisión de una petición load() posteriormente pone fin a la petición anterior, si ésta continúa pendiente, y comienza una nueva carga.

Nota: en AIR 1.5 y en Flash Player 10, el tamaño máximo de una imagen cargada es 8,191 píxeles de ancho o de largo, y el número total máximo de píxeles es 16.777.215. (De modo que si una imagen cargada tiene una anchura de 8.191 píxeles, sólo puede tener 2.048 píxeles de alto.) En Flash Player 9 y versiones anteriores y en AIR 1.1 y versiones anteriores, el límite es 2.880 píxeles de alto y 2.880 píxeles de ancho.

Un archivo SWF o imagen cargada en un objeto Loader hereda las propiedades de posición, giro y escala de los objetos de visualización principales del objeto Loader.

Utilice el método unload() para eliminar películas o imágenes cargadas con este método o cancelar una operación de carga que se encuentra en curso.

Asimismo, se puede impedir que un archivo SWF utilice este método si define el parámetro allowNetworking de las etiquetas object y embed de la página HTML que aloja el contenido SWF.

Notas sobre iOS

En aplicaciones de AIR en iOS, solo se puede cargar desde el paquete de la aplicación un archivo SWF con ActionScript. Esta restricción incluye cualquier ActionScript, incluidos los activos con nombres de clase exportados para ActionScript. Para cargar un archivo SWF debe usar el mismo dominio de aplicación que el del archivo SWF principal correspondiente, como se muestra en este ejemplo:

     var loader:Loader = new Loader();
     var url:URLRequest = new URLRequest("swfs/SecondarySwf.swf");
     var loaderContext:LoaderContext = new LoaderContext(false, ApplicationDomain.currentDomain, null);
     loader.load(url, loaderContext);

Además, en iOS no puede cargar un archivo SWF que contenga código de bytes ActionScript (ABC), descargarlo y volver a cargarlo. Si intenta hacerlo, el motor de ejecución emite el error 3764.

En versiones anteriores a AIR 3.6 solo se pueden cargar archivos SWF que no contengan código de bytes ActionScript, tanto si se cargan desde el paquete de la aplicación como a través de una red. En lugar de usar un archivo SWF externo con ActionScript, puede crear una biblioteca de SWC y vincularla al SWF principal.

Estas restricciones no afectan a casos en que la aplicación se ejecuta en el simulador de iOS (ipa-test-interpreter-simulator o ipa-debug-interpreter-simulator) o en modo de intérprete (ipa-test-interpreter o ipa-debug-interpreter.)

Seguridad de Loader

Cuando utilice este método, considere el modelo de seguridad de Flash Player (consulte la descripción de la clase Loader).

En Flash Player 10 y versiones posteriores, si utiliza una estructura Content-Type de varias partes (por ejemplo, "multipart/form-data") con una acción de carga (indicada por un parámetro "filename" en un encabezado "content-disposition" dentro del cuerpo POST), la operación POST está sujeta a las reglas de seguridad aplicadas a las cargas:

• Es preciso realizar una operación POST como respuesta a una acción iniciada por el usuario, por ejemplo, un clic de ratón o la pulsación de una tecla.
• Si la operación POST afecta a varios dominios (el destino POST no se encuentra en el mismo servidor que el archivo SWF que envía la petición POST), el servidor de destino debe proporcionar un archivo de política URL que permita el acceso a varios dominios.

Asimismo, en cualquier estructura Content-Type de varias partes, la sintaxis debe ser válida (de acuerdo con la norma RFC2046). Si la sintaxis no es válida, la operación POST está sujeta a las reglas de seguridad que se aplican a las cargas.

Para obtener más información, consulte el tema del Centro de desarrollo de Flash Player Seguridad.

Parámetros

Elementos de API relacionados

Se carga a partir de datos binarios almacenados en un objeto ByteArray.

El método loadBytes() es asíncrono. Se debe esperar al evento "init" antes de acceder a las propiedades de un objeto cargado.

Cuando utilice este método, considere el modelo de seguridad de Flash Player (consulte la descripción de la clase Loader).

Nota (solo iOS): En aplicaciones de AIR en iOS, solo se puede cargar desde el paquete de la aplicación un archivo SWF con ActionScript. Esta restricción incluye cualquier ActionScript, incluidos los activos con nombres de clase exportados para ActionScript. Para cargar un archivo SWF debe usar el mismo dominio de aplicación que el del archivo SWF principal correspondiente.

En versiones anteriores a AIR 3.6, este método no tiene efecto en iOS.

Parámetros

Elementos de API relacionados

Carga una instancia de IFilePromise.

El método loadFilePromise ) toma un objeto IFilePromise y carga los datos binarios. Si los datos son un flujo progresivo, como una espera de vídeo para los eventos "init" o progress antes de acceder a las propiedades del objeto cargado. De lo contrario, espera al evento complete para asegurarse de que los datos se han cargado por completo.

Cuando utilice este método, considere el modelo de seguridad de Flash Player (consulte la descripción de la clase Loader).

Parámetros

Elementos de API relacionados

Elimina un elemento secundario del objeto Loader que se cargó utilizando el método load(). El elemento property (propiedad) del objeto LoaderInfo asociado se restablece con el valor null. El elemento secundario no se destruye necesariamente, ya que otros objetos pueden contener referencias a él; sin embargo, deja de ser elemento secundario del objeto Loader.

Al llamar al método unload(), la propiedad de objeto Loader contentLoaderInfo se establece en null. Los activos visuales que se hayan cargado con el archivo SWF se descargan y se quitan de la memoria. Las definiciones de clase de ActionScript en el SWF cargado permanecen en la memoria y el código en el mismo dominio de aplicación que el SWF cargado puede acceder a instancias de esas clases y crear instancias nuevas.

Nota (solo iOS): en versiones anteriores a AIR 3.6, este método no tiene efecto en iOS.

La práctica más recomendable consiste en cerrar explícitamente los flujos de los objetos de un archivo SWF secundario como, por ejemplo, los objetos LocalConnection, NetConnection, NetStream y Sound, antes de descargar dicho archivo SWF secundario. En caso contrario, podría continuar reproduciéndose el sonido del archivo SWF secundario aunque se hubiera descargado el archivo SWF secundario. Para cerrar los flujos del archivo SWF secundario, añada un detector de eventos al elemento secundario que detecte el evento unload. Cuando el elemento principal llame a Loader.unload(), se distribuirá el evento unload al elemento secundario. En el ejemplo siguiente, se muestra cómo puede lograr esto:

function closeAllStreams(evt:Event) { 
    myNetStream.close();
    mySound.close();
    myNetConnection.close();
    myLocalConnection.close();
}

myMovieClip.loaderInfo.addEventListener(Event.UNLOAD, closeAllStreams);

Elementos de API relacionados

Intenta anular la carga del contenido de archivos SWF secundarios y detiene la ejecución de los comandos de los archivos SWF cargados. Este método intenta anular la carga de archivos SWF que se cargaron con Loader.load() o con Loader.loadBytes() eliminando referencias de objetos EventDispatcher, NetConnection, Timer, Sound o Video del archivo SWF secundario. Como resultado, ocurre lo siguiente en el archivo SWF secundario y en la lista de visualización del archivo SWF secundario:

• Se detienen los sonidos.
• Se quitan los detectores de eventos del escenario.
• Se quitan los detectores de eventos de enterFrame, frameConstructed, exitFrame, activate y deactivate.
• Se detienen los temporizadores.
• Se separan las instancias de Camera y Microphone.
• Se detienen los clips de película.

Al llamar al método unloadAndStop(), la propiedad de objeto Loader contentLoaderInfo se establece en null. Los activos visuales que se hayan cargado con el archivo SWF se descargan y se quitan de la memoria. Las definiciones de clase de ActionScript en el SWF cargado permanecen en la memoria y el código en el mismo dominio de aplicación que el SWF cargado puede acceder a instancias de esas clases y crear instancias nuevas.

Nota (solo iOS): en versiones anteriores a AIR 3.6, este método no tiene efecto en iOS.

Parámetros

Elementos de API relacionados

1. Se crea una propiedad url, que es la ubicación y el nombre del archivo de imagen.
2. En el constructor LoaderExample, se crea un nuevo objeto Loader denominado loader que, a continuación, se transfiere al método configureListeners(), descrito en el paso 3.
3. El constructor crea una nueva instancia de un objeto URLRequest, request, con url para que se conozcan el nombre del archivo y la ubicación.
4. El objeto request se transfiere seguidamente al método loader del objeto load(), que carga la imagen en la lista de visualización.
5. Se registra un detector de eventos clickHandler para el evento click en el cargador. Tras un clic del ratón, se descarga la imagen cargada.
6. El método configureListeners() añade siete detectores de eventos con los siguientes métodos:
   • El método completeHandler() se ejecuta cuando termina de cargarse la imagen.
   • El método httpStatusHandler() se ejecuta si la imagen no se carga localmente y sólo si la petición de red queda disponible y Flash Player puede detectarla.
   • El método initHandler() se ejecuta antes del método completeHandler() y después del método progressHandler(). Normalmente, el evento init resulta más útil al cargar los archivos SWF.
   • El método ioErrorHandler() se ejecuta si el archivo de imagen no se encuentra disponible o no está accesible.
   • El método openHandler() se ejecuta cuando se abre por primera vez el archivo de imagen.
   • El método progressHandler() se ejecuta cuando el archivo de imagen comienza a cargarse y de nuevo cuando la imagen termina de cargarse.
   • El método unLoadHandler() se ejecuta cuando la imagen se descarga con el método unload() al hacer el usuario clic en la imagen.

Recuerde los siguientes requisitos:

• este ejemplo requiere que coloque un archivo denominado Image.gif en el mismo directorio que el archivo SWF compilado. Utilice una imagen que tenga un área que se ajuste a las dimensiones del archivo SWF principal.
• Aunque en este ejemplo se utilizan todos los eventos disponibles en el objeto LoaderInfo, en la mayoría de los casos sólo se requiere un subconjunto. En especial, al cargar sólo un archivo de imagen, el evento complete (y quizás el evento ioError) son suficientes al cargar una imagen local.

package {
    import flash.display.Loader;
    import flash.display.Sprite;
    import flash.events.*;
    import flash.net.URLRequest;

    public class LoaderExample extends Sprite {
        private var url:String = "Image.gif";

        public function LoaderExample() {
            var loader:Loader = new Loader();
            configureListeners(loader.contentLoaderInfo);
            loader.addEventListener(MouseEvent.CLICK, clickHandler);

            var request:URLRequest = new URLRequest(url);
            loader.load(request);

            addChild(loader);
        }

        private function configureListeners(dispatcher:IEventDispatcher):void {
            dispatcher.addEventListener(Event.COMPLETE, completeHandler);
            dispatcher.addEventListener(HTTPStatusEvent.HTTP_STATUS, httpStatusHandler);
            dispatcher.addEventListener(Event.INIT, initHandler);
            dispatcher.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
            dispatcher.addEventListener(Event.OPEN, openHandler);
            dispatcher.addEventListener(ProgressEvent.PROGRESS, progressHandler);
            dispatcher.addEventListener(Event.UNLOAD, unLoadHandler);
        }

        private function completeHandler(event:Event):void {
            trace("completeHandler: " + event);
        }

        private function httpStatusHandler(event:HTTPStatusEvent):void {
            trace("httpStatusHandler: " + event);
        }

        private function initHandler(event:Event):void {
            trace("initHandler: " + event);
        }

        private function ioErrorHandler(event:IOErrorEvent):void {
            trace("ioErrorHandler: " + event);
        }

        private function openHandler(event:Event):void {
            trace("openHandler: " + event);
        }

        private function progressHandler(event:ProgressEvent):void {
            trace("progressHandler: bytesLoaded=" + event.bytesLoaded + " bytesTotal=" + event.bytesTotal);
        }

        private function unLoadHandler(event:Event):void {
            trace("unLoadHandler: " + event);
        }

        private function clickHandler(event:MouseEvent):void {
            trace("clickHandler: " + event);
            var loader:Loader = Loader(event.target);
            loader.unload();
        }
    }
}