NSImageMBS.addRepresentation(img as NSImageRepMBS)
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Plugin version: 8.4, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: Adds the specified image representation object to to the receiver.
Notes:
After invoking this method, you may need to explicitly set features of the new image representation, such as the size, number of colors, and so on. This is true particularly when the NSImage object has multiple image representations to choose from. See NSImageRep and its subclasses for the methods you use to complete initialization.

Any representation added by this method is retained by the receiver. Image representations cannot be shared among multiple NSImage objects.

NSImageMBS.backgroundColor as variant
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Plugin version: 8.4, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: The background color of image.
Notes:
The background color of the image. The default color is transparent, as returned by the clearColor method of NSColor.
The background color is visible only if the drawn image representation does not completely cover all of the pixels available for the image's current size.

The value of this variant must be an object of class NSColorMBS.
(Read and Write runtime property)

NSImageMBS.BMPRepresentation as String
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Console safe, Plugin version: 7.2, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: The image as the binary data in a BMP file.
Example:

dim img as NSImageMBS
dim p as Picture
dim f as FolderItem
dim b as BinaryStream

p=NewPicture(100,100,32)
p.Graphics.ForeColor=&cFF0000
p.Graphics.FillOval 0,0,100,100
Backdrop=p
img=new NSImageMBS(p,p.Mask)

f=DesktopFolder.Child("test.bmp")
b=f.CreateBinaryFile("")
b.Write img.BMPRepresentation
b.Close

f.Launch

Notes: BMP does not support masks.

NSImageMBS.cacheDepthMatchesImageDepth as Boolean
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Console safe, Plugin version: 7.2, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: Returns a Boolean value indicating whether an image's offscreen window caches use the same bit depth as the image data itself.
Notes: Returns true if the offscreen window caches use the same bit depth as the image data; otherwise, false. The default value is false.

class NSImageMBS
class, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Console safe, Plugin version: 7.2, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: An NSImage object is a high-level class for manipulating image data.
Notes:
You use this class to load existing images or create new ones and composite them into a view or other image. This class works in conjunction with one or more image representation objects (subclasses of NSImageRep), which manage the actual image data.

All methods in this class will catch exceptions from Cocoa and raise a NSExceptionMBS instead. Using the message, name and reason properties you can see what was the reason for this exception. Please report if you find a method which does not handle exceptions correct.

NSImageMBS.Constructor
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Console safe, Plugin version: 7.2, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: The default constructor creating a dummy NSImage object.

NSImageMBS.Constructor(data as string)
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Console safe, Plugin version: 7.2, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: The data constructor calling initWithData internally.
Notes:
Calls initWithData.
On success the image is valid and the handle is not zero.

NSImageMBS.Constructor(file as folderitem)
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Console safe, Plugin version: 7.2, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: The file constructor calling initWithContentsOfURL(file) internally.
Notes:
Calls initWithContentsOfURL.
On success the image is valid and the handle is not zero.

NSImageMBS.Constructor(image as Picture, mask as picture=nil)
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Plugin version: 7.2, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: Creates a new NSImageMBS object based on the image data in a Realbasic picture.
Example:

dim img as new NSImageMBS(pict, pict.mask)

Notes:
Optional you can pass a picture with the mask. It is valid to use the mask property of the image for the second parameter.

On success the image is valid and the handle is not zero.
Calls initWithPicture.

NSImageMBS.Constructor(width as double, height as double)
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Console safe, Plugin version: 7.2, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: The size constructor calling initWithSize internally.
Notes:
Calls initWithSize.
On success the image is valid and the handle is not zero.

NSImageMBS.CopyMask as picture
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Plugin version: 7.5, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: Copies the content of the NSImage in current size.
Example:

dim f as FolderItem
dim n as NSImageMBS

f=DesktopFolder.Child("test.png")
n=new NSImageMBS(f)
Backdrop=n.CopyMask

Notes:
Copies only the alpha channel as mask.

A convenience function instead of using CGPictureContextMBS with DrawIntoCGContextAtRect.

Returns nil on any error.

NSImageMBS.CopyPicture as picture
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Plugin version: 7.5, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: Copies the content of the NSImage in current size.
Example:

dim f as FolderItem
dim n as NSImageMBS

f=DesktopFolder.Child("test.png")
n=new NSImageMBS(f)
Backdrop=n.CopyPicture // background is black

Notes:
A convenience function instead of using CGPictureContextMBS with DrawIntoCGContextAtRect.

Returns nil on any error.

NSImageMBS.CopyPictureWithMask as picture
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Plugin version: 7.5, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: Copies the content of the NSImage in current size.
Example:

dim f as FolderItem
dim n as NSImageMBS

f=DesktopFolder.Child("test.png")
n=new NSImageMBS(f)
Backdrop=n.CopyPictureWithMask

Notes:
Copies the picture and its mask.
This function is faster than CopyPicture and CopyMask combined as the picture is only copied one time to an internal buffer.

A convenience function instead of using CGPictureContextMBS with DrawIntoCGContextAtRect.

Returns nil on any error.

NSImageMBS.DrawIntoCGContextAtPoint(cgcontext as integer, x as double, y as double, sx as double, sy as double, SourceW as double, SourceH as double, operation as integer, fraction as double) as boolean
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Console safe, Plugin version: 7.2, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: Draws the image.
Notes: Same as DrawIntoCGContextAtRect, but with a point instead of a rectangle.

NSImageMBS.DrawIntoCGContextAtRect(cgcontext as integer, x as double, y as double, w as double, h as double, SourceX as double, SourceY as double, SourceW as double, SourceH as double, operation as integer, fraction as double) as boolean
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Console safe, Plugin version: 7.2, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: Draws the image.
Example:

Function OpenAsNSimage(extends file as folderitem) As picture
  dim width as integer
  dim height as integer
  dim c as NSImageMBS
  dim g as CGPictureContextMBS
  
  // load image from file
  c=new NSImageMBS
  
  // is that image valid?
  if c.initWithContentsOfURL(file) then
    Width=c.Width
    height=c.Height
    
    // create a drawing buffer to draw inside
    g=new CGPictureContextMBS(width,height)
    
    if g.Handle<>0 then // valid?
      
      // now draw the image inside.
      // you could scale or even apply transparency...
      if c.DrawIntoCGContextAtRect(g.Handle, 0, 0, width, height, 0,0,width,height,2,1.0) then
        // make a RB Picture from it
        Return g.CopyPicture
      end if
    end if
  end if
End Function

Notes:
Draws the image into a CGContext. You need to specify first the destination rectangle followed by the source rectangle.

fraction:
The opacity of the image, specified as a value from 0.0 to 1.0. Specifying a value of 0.0 draws the image as fully transparent while a value of 1.0 draws the image as fully opaque. Values greater than 1.0 are interpreted as 1.0.

operation codes:

NSCompositeClear	= 0	Transparent.
NSCompositeCopy	= 1	Source image.
NSCompositeSourceOver	= 2	Source image wherever source image is opaque, and destination image elsewhere.
NSCompositeSourceIn	= 3	Source image wherever both images are opaque, and transparent elsewhere.
NSCompositeSourceOut	= 4	Source image wherever source image is opaque but destination image is transparent, and transparent elsewhere.
NSCompositeSourceAtop	= 5	Source image wherever both images are opaque, destination image wherever destination image is opaque but source image is transparent, and transparent elsewhere.
NSCompositeDestinationOver	= 6	Destination image wherever destination image is opaque, and source image elsewhere.
NSCompositeDestinationIn	= 7	Destination image wherever both images are opaque, and transparent elsewhere.
NSCompositeDestinationOut	= 8	Destination image wherever destination image is opaque but source image is transparent, and transparent elsewhere.
NSCompositeDestinationAtop	= 9	Destination image wherever both images are opaque, source image wherever source image is opaque but destination image is transparent, and transparent elsewhere.
NSCompositeXOR	= 10	Exclusive OR of source and destination images.
NSCompositePlusDarker	= 11	Sum of source and destination images, with color values approaching 0 as a limit.
NSCompositeHighlight	= 12	Source image wherever source image is opaque, and destination image elsewhere.
NSCompositePlusLighter	= 13	Sum of source and destination images, with color values approaching 1 as a limit.

Returns true on success and false on failure.

NSImageMBS.GIFRepresentation as String
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Console safe, Plugin version: 7.2, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: The image as the binary data in a GIF file.
Example:

dim img as NSImageMBS
dim p as Picture
dim f as FolderItem
dim b as BinaryStream

p=NewPicture(100,100,32)
p.Graphics.ForeColor=&cFF0000
p.Graphics.FillOval 0,0,100,100
Backdrop=p
img=new NSImageMBS(p,p.Mask)

f=DesktopFolder.Child("test.gif")
b=f.CreateBinaryFile("")
b.Write img.GIFRepresentation
b.Close

f.Launch

Notes: GIF does support masks in a limited way.

NSImageMBS.Handle as Integer
property, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Console safe, Plugin version: 7.2, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: The handle to the internally used NSImage object.
Notes: (Read and Write property)

NSImageMBS.height as double
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Console safe, Plugin version: 7.2, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: The height of the image or zero.
Notes: If no size has been set and the size cannot be determined from any of the receiver's image representations.

NSImageMBS.imageByFadingToFraction(fraction as double) as NSImageMBS
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Console safe, Plugin version: 7.2, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: Returns an image with a mask faded to the given percentage
Example:

dim img as NSImageMBS
dim p as Picture
dim f as FolderItem
dim b as BinaryStream

p=NewPicture(100,100,32)
p.Graphics.ForeColor=&cFF0000
p.Graphics.FillOval 0,0,100,100
Backdrop=p
img=new NSImageMBS(p)

img=img.imageByFadingToFraction(0.1)

f=DesktopFolder.Child("test.png")
b=f.CreateBinaryFile("")
b.Write img.PNGRepresentation
b.Close

f.Launch

Notes: Returns nil on failure.

NSImageMBS.imageByScalingToSize(width as double, height as double) as NSImageMBS
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Console safe, Plugin version: 7.2, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: Scales image to the new size.
Example:

dim img as NSImageMBS
dim p as Picture
dim f as FolderItem
dim b as BinaryStream

p=NewPicture(100,100,32)
p.Graphics.ForeColor=&cFF0000
p.Graphics.FillOval 0,0,100,100
Backdrop=p
img=new NSImageMBS(p)

img=img.imageByScalingToSize(200,200)

f=DesktopFolder.Child("test.png")
b=f.CreateBinaryFile("")
b.Write img.PNGRepresentation
b.Close

f.Launch

Notes: Returns nil on failure.

NSImageMBS.imageByScalingToSize(width as double, height as double, fraction as double) as NSImageMBS
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Console safe, Plugin version: 7.2, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: Scales image to the new size with given fading.
Example:

dim img as NSImageMBS
dim p as Picture
dim f as FolderItem
dim b as BinaryStream

p=NewPicture(100,100,32)
p.Graphics.ForeColor=&cFF0000
p.Graphics.FillOval 0,0,100,100
Backdrop=p
img=new NSImageMBS(p)

img=img.imageByScalingToSize(200,200,0.5)

f=DesktopFolder.Child("test.png")
b=f.CreateBinaryFile("")
b.Write img.PNGRepresentation
b.Close

f.Launch

Notes: Returns nil on failure.

NSImageMBS.imageByScalingToSize(width as double, height as double, fraction as double, flip as boolean, proportionally as boolean) as NSImageMBS
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Console safe, Plugin version: 7.2, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: Scales image to the new size with given fading fraction.
Example:

dim img as NSImageMBS
dim p as Picture
dim f as FolderItem
dim b as BinaryStream

p=NewPicture(100,100,32)
p.Graphics.ForeColor=&cFF0000
p.Graphics.FillOval 0,0,100,100
Backdrop=p
img=new NSImageMBS(p)

img=img.imageByScalingToSize(200,200)

f=DesktopFolder.Child("test.png")
b=f.CreateBinaryFile("")
b.Write img.PNGRepresentation
b.Close

f.Launch

Notes:
Returns nil on failure.
The image can be flipped vertically with the flip property.

NSImageMBS.imageNamed(name as string) as NSImageMBS
shared method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Plugin version: 8.4, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: Returns the NSImage instance associated with the specified name.
Notes:
This method searches for named images in several places, returning the first image it finds matching the given name. The order of the search is as follows:

1. Search for an object whose name was set explicitly using the setName: method and currently resides in the image cache.
2. Search the application's main bundle for a file whose name matches the pecified string. (For information on how the bundle is searched, see "Searching for Bundle Resources" in Bundle Programming Guide.)
3. Search the Application Kit framework for a shared image with the specified name.

When looking for files in the application bundle, it is better (but not required) to include the filename extension in the name parameter. When naming an image with the setName method, it is also convention not to include filename extensions in the names you specify. That way, you can easily distinguish between images you have named explicitly and those you want to load from the application's bundle.

One particularly useful image you can retrieve is your application's icon. This image is set by Cocoa automatically and referenced by the string "NSApplicationIcon". Icons for other applications can be obtained through the use of methods declared in the NSWorkspace class. You can also retrieve some standard system images using Cocoa defined constants; for more information, see the Constants section of this class.

If an application is linked in Mac OS X v10.5 or later, images requested using this method and whose name ends in the word "Template" are automatically marked as template images.

The NSImage class keeps a reference to any named images in a table until the image name is cleared. Consequently you do not need to retain the returned image object unless its name could be cleared. You can clear an image object from the table by passing nil to the setName: method of the corresponding NSImage object.
Shared Methods require Realbasic 2006r4 or newer. In older REALbasic versions this function is available with the name NSImageMBS_imageNamed(name as string) as NSImageMBS.

NSImageMBS.initWithContentsOfURL(file as folderitem) as boolean
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Console safe, Plugin version: 7.2, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: Initializes and returns an NSImage instance with the contents of the specified folderitem.
Notes: Returns true on success and false on failure.

NSImageMBS.initWithContentsOfURL(url as string) as boolean
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Console safe, Plugin version: 7.2, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: Initializes and returns an NSImage instance with the contents of the specified URL.
Notes: Returns true on success and false on failure.

NSImageMBS.initWithData(data as string) as boolean
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Console safe, Plugin version: 7.2, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: Initializes and with the contents of the specified data in the string.
Notes: Returns true on success and false on failure.

NSImageMBS.initWithPicture(img as picture, mask as picture=nil) as boolean
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Plugin version: 7.2, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: Initializes the image object with image data from the Realbasic pictures.
Example:

dim img as new NSImageMBS
img.initWithPicture(pict, pict.mask)

Notes:
Optional you can pass a picture with the mask. It is valid to use the mask property of the image for the second parameter.

On success the image is valid and the handle is not zero.

NSImageMBS.initWithSize(width as double, height as double) as boolean
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Console safe, Plugin version: 7.2, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: Initializes an empty image object with the given size.
Notes: Returns true on success and false on failure.

NSImageMBS.isCachedSeparately as Boolean
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Console safe, Plugin version: 7.2, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: Returns a Boolean value indicating whether each image representation caches its contents in a separate offscreen window.
Notes:
Returns true if the image representations cache their content in separate offscreen windows; otherwise, false. The default value is false.

Discussion:
If this method returns false, it means that the image may be cached in a shared window but is not required to be. Images are cached in a shared window if they have the same general attributes, such as color space, resolution, and bit depth.

NSImageMBS.isDataRetained as Boolean
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Console safe, Plugin version: 7.2, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: Returns a Boolean value indicating whether the receiver retains its source image data.
Notes: Returns true if the image retains its source data; otherwise, false. The default value is false with some exceptions, which are covered in the discussion.

NSImageMBS.isFlipped as Boolean
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Console safe, Plugin version: 7.2, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: Returns a Boolean value indicating whether the image uses a flipped coordinate system.
Notes: Returns true if the image's coordinate system is flipped; otherwise, false. The default is false.

NSImageMBS.isValid as Boolean
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Console safe, Plugin version: 7.2, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: Returns a Boolean value indicating whether the image can be drawn.
Notes:
Return value: true if the receiver can be drawn; otherwise, false.

If the object is initialized with an existing image file, but the corresponding image data is not yet loaded into memory, this method loads the data and expands it as needed. If the object contains no image representations and no associated image file, this method creates a valid cached image representation and initializes it to the default bit depth. This method returns false in cases where the file or URL from which it was initialized is nonexistent or when the data in an existing file is invalid.

NSImageMBS.JPEGRepresentation as String
method, Graphics & Pictures, MBS Cocoa Plugin (NSImage), class NSImageMBS, Console safe, Plugin version: 7.2, Mac OS X: Works, Windows: Does nothing, Linux x86: Does nothing, Feedback.

Function: The image as the binary data in a JPEG file.
Example:

dim img as NSImageMBS
dim p as Picture
dim f as FolderItem
dim b as BinaryStream

p=NewPicture(100,100,32)
p.Graphics.ForeColor=&cFF0000
p.Graphics.FillOval 0,0,100,100
Backdrop=p
img=new NSImageMBS(p)

f=DesktopFolder.Child("test.jpeg")
b=f.CreateBinaryFile("")
b.Write img.JPEGRepresentation
b.Close

f.Launch

Notes: JPEG does not support masks.