Platforms to show: All Mac Windows Linux Cross-Platform

Back to NSImageMBS class.

Next items

NSImageMBS.addRepresentation(img as NSImageRepMBS)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 8.4 ✅ Yes ❌ No ❌ No ❌ No Desktop, Console & Web
Adds the specified image representation object to to the receiver.

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.

Some examples using this method:

NSImageMBS.BMPRepresentation as Memoryblock

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 7.2 ✅ Yes ❌ No ❌ No ✅ Yes All
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=New Picture(100,100,32)
p.Graphics.ForeColor=&cFF0000
p.Graphics.FillOval 0,0,100,100
Backdrop=p
img=new NSImageMBS(p,p.Mask)

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

f.Launch

BMP does not support masks.

NSImageMBS.BMPRepresentationMT as Memoryblock

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 13.1 ✅ Yes ❌ No ❌ No ✅ Yes All
The image as the binary data in a BMP file.

BMP does not support masks.

The work is performed on a preemptive thread, so this function does not block the application and can yield time to other Xojo threads. Must be called in a Xojo thread to enjoy benefits. If called in main thread will block, but keep other background threads running.
If you run several threads calling MT methods, you can get all CPU cores busy while main thread shows GUI with progress window.

NSImageMBS.cancelIncrementalLoad

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 9.6 ✅ Yes ❌ No ❌ No ❌ No Desktop, Console & Web
Cancels the current download operation immediately, if the image is being incrementally loaded.

This call has no effect if the image is not loading.

NSImageMBS.Constructor

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 7.2 ✅ Yes ❌ No ❌ No ✅ Yes All
The default constructor creating a dummy NSImage object.

See also:

NSImageMBS.Constructor(data as Memoryblock)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 7.2 ✅ Yes ❌ No ❌ No ✅ Yes All
The data constructor calling initWithData internally.

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

See also:

NSImageMBS.Constructor(file as folderitem)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 7.2 ✅ Yes ❌ No ❌ No ✅ Yes All
The file constructor calling initWithContentsOfURL(file) internally.

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

See also:

NSImageMBS.Constructor(image as Picture, mask as picture = nil)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 7.2 ✅ Yes ❌ No ❌ No ✅ Yes All
Creates a new NSImageMBS object based on the image data in a Xojo picture.
Example
dim img as new NSImageMBS(pict)

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

With 11.3 plugins we are deprecating to pass a mask. The plugin prefers to simply take the mask or alpha channel of the picture itself.

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

See also:

NSImageMBS.Constructor(width as Double, height as Double)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 7.2 ✅ Yes ❌ No ❌ No ✅ Yes All
The size constructor calling initWithSize internally.

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

See also:

NSImageMBS.CopyMask as picture

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 7.5 ✅ Yes ❌ No ❌ No ❌ No All
Copies the content of the NSImage in current size.
Example
dim f as FolderItem
dim n as NSImageMBS

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

Copies only the alpha channel as mask.
Returns nil on any error.

Not implemented for iOS.

NSImageMBS.CopyPicture(CGColorSpace as Variant = nil, BackgroundColor as NSColorMBS = nil) as picture

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 7.5 ✅ Yes ❌ No ❌ No ✅ Yes All
Copies the content of the NSImage in current size.
Example
dim f as FolderItem
dim n as NSImageMBS

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

A convenience function instead of using CGPictureContextMBS with DrawIntoCGContextAtRect.

Returns nil on any error.

With Colorspace parameter you can pass a RGB CGColorspace to define which colorspace is used. Default is DeviceRGB, but you could also pass generic RGB or other.

If BackgroundColor is not nil, the image is filled in background with this color and NSImage rendered on top of it.

Implemented for iOS in v22.4 to return underlaying UIImage as Xojo picture. Colorspace and background are ignored as picture is passed directly.

NSImageMBS.CopyPictureRect(x as Integer, y as Integer, w as Integer, h as Integer, CGColorSpace as Variant = nil, BackgroundColor as NSColorMBS = nil) as picture

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 13.2 ✅ Yes ❌ No ❌ No ❌ No All
Copies the content of the NSImage from the given rectangle.
Example
dim f as FolderItem
dim n as NSImageMBS

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

A convenience function instead of using CGPictureContextMBS with DrawIntoCGContextAtRect.

Returns nil on any error.

With Colorspace parameter you can pass a RGB CGColorspace to define which colorspace is used. Default is DeviceRGB, but you could also pass generic RGB or other.

If BackgroundColor is not nil, the image is filled in background with this color and NSImage rendered on top of it.

Not implemented for iOS.

NSImageMBS.CopyPictureWithAlpha as picture

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 15.1 ✅ Yes ❌ No ❌ No ❌ No All
Copies the content of the NSImage in current size.

This is a function for Cocoa target which returns picture with alpha channel.
Returns nil on any error.

Not implemented for iOS.

NSImageMBS.CopyPictureWithAlphaRect(x as Integer, y as Integer, w as Integer, h as Integer) as picture

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 15.1 ✅ Yes ❌ No ❌ No ❌ No All
Copies the content of the NSImage in given rectangle.

This is a function for Cocoa target which returns picture with alpha channel.
Returns nil on any error.

Not implemented for iOS.

NSImageMBS.CopyPictureWithMask(CGColorSpace as Variant = nil) as picture

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 7.5 ✅ Yes ❌ No ❌ No ❌ No All
Copies the content of the NSImage in current size.
Example
dim f as FolderItem
dim n as NSImageMBS

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

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.

With Colorspace parameter you can pass a RGB CGColorspace to define which colorspace is used. Default is DeviceRGB, but you could also pass generic RGB or other.

Not implemented for iOS.

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

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 7.2 ✅ Yes ❌ No ❌ No ✅ Yes All
Draws the image.

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

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 7.2 ✅ Yes ❌ No ❌ No ✅ Yes All
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

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

Returns true on success and false on failure.

Some examples using this method:

NSImageMBS.GIFRepresentation as Memoryblock

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 7.2 ✅ Yes ❌ No ❌ No ✅ Yes All
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=New Picture(100,100,32)
p.Graphics.ForeColor=&cFF0000
p.Graphics.FillOval 0,0,100,100
Backdrop=p
img=new NSImageMBS(p,p.Mask)

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

f.Launch

GIF does support masks in a limited way.

NSImageMBS.GIFRepresentationMT as Memoryblock

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 13.1 ✅ Yes ❌ No ❌ No ✅ Yes All
The image as the binary data in a GIF file.

GIF does support masks in a limited way.

The work is performed on a preemptive thread, so this function does not block the application and can yield time to other Xojo threads. Must be called in a Xojo thread to enjoy benefits. If called in main thread will block, but keep other background threads running.
If you run several threads calling MT methods, you can get all CPU cores busy while main thread shows GUI with progress window.

NSImageMBS.imageByFadingToFraction(fraction as Double) as NSImageMBS

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 7.2 ✅ Yes ❌ No ❌ No ✅ Yes All
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=New Picture(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=SpecialFolder.Desktop.Child("test.png")
b=f.CreateBinaryFile("")
b.Write img.PNGRepresentation
b.Close

f.Launch

Returns nil on failure.

NSImageMBS.imageByScalingToSize(width as Double, height as Double) as NSImageMBS

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 7.2 ✅ Yes ❌ No ❌ No ✅ Yes All
Scales image to the new size.
Example
dim img as NSImageMBS
dim p as Picture
dim f as FolderItem
dim b as BinaryStream

p=New Picture(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=SpecialFolder.Desktop.Child("test.png")
b=f.CreateBinaryFile("")
b.Write img.PNGRepresentation
b.Close

f.Launch

Returns nil on failure.
Internally creates a copy of the image.

See also:

Some examples using this method:

NSImageMBS.imageByScalingToSize(width as Double, height as Double, fraction as Double) as NSImageMBS

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 7.2 ✅ Yes ❌ No ❌ No ✅ Yes All
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=New Picture(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=SpecialFolder.Desktop.Child("test.png")
b=f.CreateBinaryFile("")
b.Write img.PNGRepresentation
b.Close

f.Launch

Returns nil on failure.
Internally creates a copy of the image.

See also:

NSImageMBS.imageByScalingToSize(width as Double, height as Double, fraction as Double, flip as boolean, proportionally as boolean) as NSImageMBS

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 7.2 ✅ Yes ❌ No ❌ No ✅ Yes All
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=New Picture(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=SpecialFolder.Desktop.Child("test.png")
b=f.CreateBinaryFile("")
b.Write img.PNGRepresentation
b.Close

f.Launch

Returns nil on failure.
The image can be flipped vertically with the flip property.
Internally creates a copy of the image.

See also:

NSImageMBS.imageWithSymbolConfiguration(configuration as NSImageSymbolConfigurationMBS) as NSImageMBS

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 22.1 ✅ Yes ❌ No ❌ No ❌ No Desktop, Console & Web
Creates a new symbol image with the specified configuration.
Example
Dim config As NSImageSymbolConfigurationMBS = NSImageSymbolConfigurationMBS.configurationWithPointSize(40, 0)
Dim n As NSImageMBS = NSImageMBS.imageWithSystemSymbolName("trash")
Dim o As NSImageMBS = n.imageWithSymbolConfiguration(config)

Backdrop = o.CopyPictureWithAlpha

NSImageMBS.imageWithTintColor(tintColor as NSColorMBS) as NSImageMBS

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 20.1 ✅ Yes ❌ No ❌ No ❌ No Desktop, Console & Web
Creates a copy of the image colored with the given tint.

Input image should be grayscale.

NSImageMBS.initWithContentsOfURL(file as folderitem) as boolean

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 7.2 ✅ Yes ❌ No ❌ No ✅ Yes All
Initializes and returns an NSImage instance with the contents of the specified folderitem.

Returns true on success and false on failure.

See also:

NSImageMBS.initWithContentsOfURL(url as string) as boolean

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 7.2 ✅ Yes ❌ No ❌ No ✅ Yes All
Initializes and returns an NSImage instance with the contents of the specified URL.

Returns true on success and false on failure.

See also:

NSImageMBS.initWithData(data as Memoryblock) as boolean

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 7.2 ✅ Yes ❌ No ❌ No ✅ Yes All
Initializes and with the contents of the specified data in the string.

Returns true on success and false on failure.

NSImageMBS.initWithDataIgnoringOrientation(data as Memoryblock) as boolean

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 9.6 ✅ Yes ❌ No ❌ No ❌ No Desktop, Console & Web
Initializes and returns an NSImage instance with the contents of the specified memoryblock, ignoring the EXIF orientation tags.

An initialized NSImage instance, or nil if the method cannot create an image representation from the contents of the specified data object.
Available in Mac OS X v10.6 and later.

NSImageMBS.initWithIconRef(IconHandle as Integer) as boolean

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 9.6 ✅ Yes ❌ No ❌ No ❌ No Desktop, Console & Web
Initializes the image object with a Carbon-style icon resource.

IconHandle: A reference to a Carbon icon resource (IconRef).

Creates one or more bitmap image representations, one for each size icon contained in the IconRef data structure. This initialization method automatically retains the data in the iconRef parameter and loads the bitmaps from that data file lazily.
Available in Mac OS X v10.5 and later.

NSImageMBS.initWithPasteboard as boolean

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 9.6 ✅ Yes ❌ No ❌ No ✅ Yes All
Initializes an NSImage instance with data from the pasteboard.

The specified pasteboard should contain a type supported by one of the registered NSImageRep subclasses. Table 1 lists the default pasteboard types and file extensions for several NSImageRep subclasses.

NSImageMBS.initWithPicture(img as picture, mask as picture = nil) as boolean

Type Topic Plugin Version macOS Windows Linux iOS Targets
method Cocoa Drawing MBS MacBase Plugin 7.2 ✅ Yes ❌ No ❌ No ✅ Yes All
Initializes the image object with image data from the Xojo pictures.
Example
dim img as new NSImageMBS
if img.initWithPicture(pict, pict.mask) then
MsgBox "OK"
end if

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

With 11.3 plugins we are deprecating to pass a mask. The plugin prefers to simply take the mask or alpha channel of the picture itself.

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

Some examples using this method:

Next items

The items on this page are in the following plugins: MBS MacBase Plugin.


The biggest plugin in space...