Loader  - AS3

Contém o objeto de exibição raiz do arquivo SWF ou do arquivo de imagem (JPEG, PNG ou GIF) que foi carregado com o uso do método load() ou loadBytes().

Elementos da API relacionados

Retorna um objeto LoaderInfo correspondente ao objeto que está sendo carregado. Objetos LoaderInfo são compartilhados entre o objeto Loader e o objeto de conteúdo carregado. O objeto LoaderInfo fornece informações sobre o progresso do carregamento e estatísticas sobre o arquivo carregado.

Os eventos relacionados ao carregamento são despachados pelo objeto LoaderInfo referenciado pela propriedade contentLoaderInfo do objeto Loader. A propriedade contentLoaderInfo é definida como um objeto LoaderInfo válido, antes de o conteúdo ser carregado, para que você possa adicionar ouvintes de eventos a esse objeto antes do carregamento.

Para descobrir erros não capturados que acontecem em um SWF carregado, use a propriedade Loader.uncaughtErrorEvents, não a propriedade Loader.contentLoaderInfo.uncaughtErrorEvents.

Elementos da 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;
}

Um objeto que despacha um evento uncaughtError quando um erro não manipulado ocorre no SWF que é carregado por este objeto Carregador. Um erro não capturado acontece quando um erro é lançado fora de qualquer try..catch ou quando um objeto ErrorEvent é despachado sem ouvintes registrados.

Observe que a propriedade uncaughtErrorEvents de um objeto Carregador despacha eventos que surgem em balões por ele, não eventos que são despachados diretamente. Nunca despacha um uncaughtErrorEvent na fase de destino. Ele só despacha o evento nas fases de captura e bubbling. Para detectar um erro não capturado no SWF atual (o SWF no qual o objeto de Carregador é definido), use a propriedade LoaderInfo.uncaughtErrorEvents.

Se o conteúdo carregado pelo objeto Loader for um arquivo AVM1 (ActionScript 2) SWF, os erros não capturados no arquivo AVM1 SWF não resultarão em um evento uncaughtError.

Elementos da 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
            }
        }
    }
}

Cria um objeto Loader que pode ser usado para carregar arquivos, como SWF, JPEG, GIF ou PNG. Chame o método load() para carregar o recurso como um filho da ocorrência de Loader. Em seguida, você pode adicionar o objeto à lista de exibição (por exemplo, usando o método addChild() de uma ocorrência de DisplayObjectContainer). O recurso aparece no Palco conforme ele é carregado.

Também é possível usar uma ocorrência de Loader "fora da lista", ou seja, sem adicioná-la ao contêiner de objetos de exibição na lista de exibição. Nesse modo, a ocorrência de Loader pode ser usada para carregar um arquivo SWF que contenha módulos adicionais de um aplicativo.

Para detectar quando o arquivo SWF terminar de ser carregado, você pode usar os eventos do objeto LoaderInfo associado à propriedade contentLoaderInfo do objeto Loader. Nesse ponto, o código no módulo do arquivo SWF pode ser executado para inicializar e iniciar o módulo. Nesse modo fora de linha, a ocorrência de Loader também pode ser usada para carregar um arquivo SWF que contenha componentes ou recursos de mídia. Mais uma vez, você pode usar as notificações de evento do objeto LoaderInfo para detectar quando os componentes terminam de ser carregados. Nesse ponto, o aplicativo pode começar a usar os componentes e os recursos de mídia na biblioteca do arquivo SWF, instanciando as classes do ActionScript 3.0 que representam esses componentes e recursos.

Para determinar o status de um objeto Loader, monitore os eventos a seguir do objeto LoaderInfo associado à propriedade contentLoaderInfo do objeto Loader:

• O evento open é despachado quando o carregamento é iniciado.
• O evento ioError ou securityError será despachado se o arquivo não puder ser carregado ou se um erro tiver ocorrido durante o processo de carregamento.
• O evento progress é acionado continuamente enquanto o arquivo está sendo carregado.
• O evento complete é despachado quando um arquivo termina de ser baixado, mas antes de os métodos e as propriedades do clipe de filme carregado estarem disponíveis.
• O evento init será despachado depois que as propriedades e os métodos do arquivo SWF carregado estiverem acessíveis, para que você possa começar a manipular o arquivo SWF carregado. Esse evento é despachado antes do manipulador complete. Em arquivos SWF de fluxo, o evento init pode ocorrer significativamente antes do evento complete. Para a maioria das finalidades, use o manipulador init.

Observações (somente iOS): Em aplicativos AIR no iOS, é possível carregar somente um arquivo SWF contendo o ActionScript do pacote do aplicativo. Esta restrição inclui qualquer ActionScript, como os ativos com nomes de classes exportados para o ActionScript. Para carregar qualquer arquivo SWF, é preciso carregar o SWF utilizando o mesmo domínio do aplicativo como o SWF pai.

Em versões anteriores ao AIR 3.6, somente os arquivos SWF que não contenham o código de bytes do ActionScript podem ser carregados, independentemente de terem sido carregados de um pacote de aplicativo ou por uma rede. Como alternativa para usar um arquivo SWF externo com o ActionScript, crie uma biblioteca SWC e vincule-a ao SWF principal.

Estas restrições não se aplicam quando o aplicativo é executado no simulador do iOS (ipa-test-interpreter-simulator ou ipa-debug-interpreter-simulator) ou no modo intérprete (ipa-test-interpreter ou ipa-debug-interpreter.)

Elementos da API relacionados

Cancela a operação do método load() que está atualmente em andamento para a instância Loader.

Elementos da API relacionados

Carrega um arquivo SWF, JPEG, JPEG progressivo, GIF não animado ou PNG em um objeto que é filho do objeto Loader. Se você carregar um arquivo GIF animado, apenas o primeiro quadro será exibido. Como o objeto Loader pode conter apenas um único filho, emitir uma solicitação load() subsequente terminará a solicitação anterior, se esta ainda estiver pendente, e começará um novo carregamento.

Observação: No AIR 1.5 e no Flash Player 10, o tamanho máximo de uma imagem carregada é de 8.191 pixels de largura ou de altura, e o número total de pixels não pode exceder 16.777.215 pixels. (Dessa forma, caso uma imagem carregada tenha 8.191 pixels de largura, ela só pode ter 2.048 pixels de altura.) No Flash Player 9 e anteriores e no AIR 1.1 e anteriores, a limitação é de 2.880 pixels de altura e de 2.880 pixels de largura.

Um arquivo SWF ou uma imagem carregada em um objeto Loader herda as propriedades de posição, giro e escala dos objetos de exibição-pai desse objeto Loader.

Use o método unload() para remover filmes ou imagens carregados com esse método ou para cancelar uma operação de carregamento em progresso.

Você pode impedir o arquivo SWF de usar esse método configurando o parâmetro allowNetworking das marcas object e embed na página HTML com o conteúdo SWF.

Observações para o iOS

Em aplicativos AIR no iOS, você somente pode carregar um arquivo SWF que contenha o ActionScript do pacote do aplicativo. Esta restrição inclui qualquer ActionScript, como os ativos com nomes de classes exportados para o ActionScript. Para carregar qualquer arquivo SWF, é preciso carregar o SWF utilizando o mesmo domínio do aplicativo como o SWF pai, como é mostrado no exemplo a seguir:

     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);

Além disso, não é possível carregar no iOS um arquivo SWF que contenha um código ActionScript ByteCode (ABC) e, então, descarregá-lo e carregá-lo novamente. Se você tentar fazer isso, o runtime lançará o erro 3764.

Em versões anteriores ao AIR 3.6, somente os arquivos SWF que não contenham o código de bytes do ActionScript podem ser carregados, independentemente de terem sido carregados de um pacote de aplicativo ou por uma rede. Como alternativa para usar um arquivo SWF externo com o ActionScript, crie uma biblioteca SWC e vincule-a ao SWF principal.

Estas restrições não se aplicam quando o aplicativo é executado no simulador do iOS (ipa-test-interpreter-simulator ou ipa-debug-interpreter-simulator) ou no modo intérprete (ipa-test-interpreter ou ipa-debug-interpreter.)

Segurança do Loader

Ao usar esse método, considere o modelo de segurança do Flash Player, explicado na descrição da classe Loader.

No Flash Player 10 e posterior, se você usar um Content-Type de partes múltiplas (por exemplo, "multipart/form-data") que contém um upload (indicado por um parâmetro "filename" no cabeçalho "content-disposition" do corpo POST), a operação POST ficará sujeita às regras de segurança aplicadas a uploads:

• A operação POST deverá ser executada em resposta a uma ação iniciada pelo usuário, por exemplo, clique de mouse ou pressionamento de tecla.
• Se a operação POST for entre domínios (se o destino de POST não estiver no mesmo servidor do arquivo SWF que está enviando a solicitação POST), o servidor de destino deverá fornecer um arquivo de diretivas de URL que permita o acesso entre domínios.

Além disso, a sintaxe deverá ser válida (de acordo com o padrão RFC2046) para qualquer Content-Type de partes múltiplas. Se a sintaxe for inválida, a operação POST ficará sujeita às regras de segurança aplicadas a uploads.

Para obter mais informações relacionadas à segurança, consulte o tópico do Centro dos desenvolvedores do Flash Player Security.

Parâmetros

Elementos da API relacionados

Carrega de dados binários armazenados em um objeto ByteArray.

O método loadBytes() é assíncrono. Você deve esperar pelo evento "init" antes de acessar as propriedades de um objeto carregado.

Ao usar esse método, considere o modelo de segurança do Flash Player, explicado na descrição da classe Loader.

Observação (somente iOS): Em aplicativos AIR no iOS, é possível carregar um arquivo SWF contendo o ActionScript de um pacote do aplicativo. Esta restrição inclui qualquer ActionScript, como os ativos com nomes de classes exportados para o ActionScript. Para carregar qualquer arquivo SWF, é preciso carregar o SWF utilizando o mesmo domínio do aplicativo como o SWF pai.

Em versões anteriores ao AIR 3.6, este método não afetava o iOS.

Parâmetros

Elementos da API relacionados

Carrega uma instância de IFilePromise.

O método loadFilePromise pega um objeto IFilePromise e carrega os dados binários. Se os dados forem um fluxo progressivo, como a espera de um vídeo pelo "init" ou por eventos progress antes de acessar as propriedades do objeto carregado. Caso contrário, aguarde o evento completo para certificar-se de que os dados foram totalmente carregados.

Ao usar esse método, considere o modelo de segurança do Flash Player, explicado na descrição da classe Loader.

Parâmetros

Elementos da API relacionados

Remove um filho deste objeto Loader que foi carregado com o uso do método load(). A propriedade do objeto LoaderInfo associado é redefinida para null. O filho não é necessariamente destruído, uma vez que outros objetos podem ter referências a ele; entretanto, ele deixa de ser um filho do objeto Loader.

Ao chamar o método unload() a propriedade contentLoaderInfo do objeto Loader é definida como null. Quaisquer ativos visuais que foram carregados com o SWF são descarregados e removidos da memória. As definições de classe do ActionScript no SWF carregado permanecem na memória e codificam no mesmo domínio de aplicativo que o SWF carregado pode acessar as instâncias dessas classes e criar novas.

Observação (somente iOS): em versões anteriores ao AIR 3.6, este método não afeta iOS.

Como prática recomendada, antes de descarregar um arquivo SWF-filho, convém fechar explicitamente todos os fluxos nos objetos desse arquivo SWF-filho, como objetos LocalConnection, NetConnection, NetStream e Sound. Caso contrário, o áudio no arquivo SWF-filho poderá continuar a ser reproduzido, mesmo que esse arquivo SWF-filho tenha sido descarregado. Para encerrar fluxos no arquivo SWF-filho, adicione um ouvinte de evento ao filho que atende o evento unload. Quando o pai chamar Loader.unload(), o evento unload será despachado ao filho. O código a seguir mostra como fazer isso:

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

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

Elementos da API relacionados

Tenta descarregar o conteúdo do arquivo SWF filho e interrompe a execução de comandos dos arquivos SWF carregados. Esse método tenta descarregar os arquivos SWF que foram carregados com o Loader.load() ou Loader.loadBytes(), removendo referências aos objetos EventDispatcher, NetConnection, Timer, Sound ou Video do arquivo SWF filho. Como resultado, ocorre o seguinte com o arquivo SWF filho e a respectiva lista de exibição:

• Os sons são parados.
• Os ouvintes do evento Stage são removidos.
• Os ouvintes do evento enterFrame, frameConstructed, exitFrame, activate e deactivate são removidos.
• Os timers são parados.
• As ocorrências de Camera e Microphone são desanexadas.
• Os clipes de filme são parados.

Ao chamar o método unloadAndStop(), a propriedade contentLoaderInfo do objeto Loader é definida como null. Quaisquer ativos visuais que foram carregados com o SWF são descarregados e removidos da memória. As definições de classe do ActionScript no SWF carregado permanecem na memória e codificam no mesmo domínio de aplicativo que o SWF carregado pode acessar as instâncias dessas classes e criar novas.

Observação (somente iOS): em versões anteriores ao AIR 3.6, este método não afeta iOS.

Parâmetros

Elementos da API relacionados

1. Uma propriedade url é criada, representando a localização e o nome do arquivo de imagem
2. No construtor LoaderExample, um novo objeto Loader denominado loader é criado, sendo então transmitido ao método configureListeners(), descrito na etapa 3.
3. O construtor cria uma nova ocorrência de um objeto URLRequest, request, com a url transmitida para que o nome e a localização do arquivo sejam conhecidos.
4. O objeto request é transmitido ao método load() do objeto loader, que carrega a imagem na lista de exibição.
5. Um ouvinte de eventos clickHandler é registrado para o evento click no carregador. Depois de um clique do mouse, a imagem carregada é descarregada.
6. O método configureListeners() adiciona sete ouvintes de eventos usando os seguintes métodos:
   • O método completeHandler() é executado quando o carregamento da imagem é concluído.
   • O método httpStatusHandler() será executado se a imagem não estiver carregada localmente e apenas se uma solicitação de rede tiver sido disponibilizada e se o Flash Player puder detectá-la.
   • O método initHandler() é executado antes do método completeHandler() e depois do método progressHandler(). Em geral, o evento init é mais útil ao carregar arquivos SWF.
   • O método ioErrorHandler() será executado se o arquivo de imagem não estiver disponível ou acessível.
   • O método openHandler() é executado quando o arquivo de imagem é aberto pela primeira vez.
   • O método progressHandler() é executado quando o arquivo de imagem começa a ser carregado, sendo novamente executado quando o carregamento da imagem é concluído.
   • O método unLoadHandler() é executado quando a imagem é descarregada com o uso do método unload(), no momento em que o usuário clica na imagem.

Lembre-se destes requisitos:

• Esse exemplo requer que um arquivo denominado Image.gif seja inserido no mesmo diretório que o arquivo SWF compilado. Use uma imagem com uma área que se encaixe nas dimensões do arquivo SWF principal.
• Embora esse exemplo utilize todos os eventos disponíveis para o objeto LoaderInfo, a maioria das situações requer apenas um subconjunto. Em particular, ao carregar apenas um arquivo de image, o evento complete (e talvez o evento ioError) são suficientes durante o carregamento de uma imagem 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();
        }
    }
}