====== Images ======

{{tag>actionstep documentation}}

ActionStep has rather strong support for images using Cocoa's model. It is possible to load images from a URL, symbol, or a bitmap.

Basically, an image is made up of 2 classes:

  - ''NSImage''
  - ''NSImageRep''

By extending ''NSImageRep'', you can add more functionality without having to change ''NSImage''.

===== Basics =====

==== NSImage ====


An instance of ''NSImage'' can contain many instances of ''NSImageRep''.

ActionStep's implementation is unable to determine the best representation currently, and simply returns the first image rep inserted. However, this may change in the future, since the best rep can be determined by player version, operating system, Stage dimensions, etc.

When an ''NSImage'' instance is constructed, you can cache it for later use, by invoking ''-setName''. You can retrieve a cached image using ''+imageNamed''.

<code actionscript>
var img:NSImage = (new NSImage()).initWithSize(new NSSize(10, 10));
if(img.setName("Some image")) {
  //whoops, an image already exists!
  //deal with it...
  NSImage.imageNamed("Some image").release();
  //insert again
  img.setName("Some image");
}

//at some point later...
var oldImg:NSImage = NSImage.imageNamed("Some image");
</code>

Note that ''-setName'' returns a boolean value indicating if an image by the same name has already been cached.

^ Return value ^ true                 ^ false^
^ Behaviour    | Image successfully cached          | Image not cached        |

What the above code does is that the old cached image is removed, allowing the new one to be cached. This may not be recommended for other purposes unless you know what you are doing. Another solution would be, of course, to use a different name.

==== NSImageRep ====

This can be said to be the more important of the two classes since it actually does the drawing.

Subclasses need only override 3 methods:

|             ^ Behaviour ^
^ Constructor | instantiate ''m_size'' to the correct size |
^ description | return a descriptive string of what this image draws |
^ draw | make use of ''m_drawPoint:NSPoint'', ''m_drawRect:NSRect'' and ''m_drawClip:MovieClip'' to draw your image using simple line methods |

===== Loading from a URL =====

To load an image from a URL, initialize the image using this method:

<code actionscript>
var img:NSImage = (new NSImage()).initWithContentsOfURL();
</code>

You can also view loading progress by registering a delegate:

<code actionscript>
img.setDelegate({
  imageDidLoadRepresentationWithStatus:
function(img:NSImage, rep:NSImageRep, status:NSImageLoadStatus):Void {
  trace("loaded with status: "+(ASUtils.findMatch([NSImageLoadStatus], status)).objectForKey("prop"));
},

  imageHasLoadedImageRepBytesOfTotalBytes:
function(img:NSImage, rep:NSImageRep, bytesLoaded:Number, bytesTotal:Number):Void {
  trace("completed: "+(bytesLoaded/bytesTotal)*100);
}
});
</code>

The output would be something like this:

<file>
[DEBUG] completed: 97.2796248525105 -- org.actionstep.test.ASTestImages:48 (test)
[DEBUG] completed: 99.3494041046916 -- org.actionstep.test.ASTestImages:48 (test)
[DEBUG] completed: 100 -- org.actionstep.test.ASTestImages:48 (test)
[DEBUG] loaded with status: NSImageLoadStatusCompleted -- org.actionstep.test.ASTestImages:43 (test)
</file>

===== Loading from a library symbol =====

If you have used Flash or [[:swfmill]] to import graphics into the swf, you can also use the class ''ASSymbolImageRep''. The symbol to be attached can be anything you fancy, even an animated MovieClip!

When constructing add the symbol's name and size:

<code actionscript>
var rep:ASSymbolImageRep = new ASSymbolImageRep("myClip", new NSSize(100, 100));
</code>

Animation on the clip is supported using the following methods:

|               ^ Behaviour ^
^ -initialFrame | Number specifying the frame where playing will start |
^ -animates | Boolean specifying if the symbol contains animation |

===== Drawing to a BitmapData instance =====
FIXME
===== Drawing to a cell =====
FIXME