Picture Class

The Picture class is used for opening, creating, and saving images in various formats. There are two ways to access an image that's saved in a file. The first way to open a picture is to import it into your project by dragging it from the desktop onto the Project Editor in the IDE. If you double-click an image, the image editor will appear, which is not much of an editor, but it does give you a look at what the image is. If the image is selected, you can set a property that designates whether to treat the color white as transparent. You can refer to any Picture that has been imported into the project by its name; you do not have to instantiate it or do anything else.

FolderItems and Pictures

The second way to open an existing image file is to use the FolderItem class. The FolderItem class provides a few methods for handling Picture objects. The first is a general method used for opening files as Picture objects:

FolderItem.OpenAsPicture as Picture

On Windows, OpenAsPicture will open JPG, GIF, and BMP images by default, but if QuickTime has been installed, it can open all the formats that QuickTime can open. If for some reason you have a Macintosh that does not have QuickTime installed, it will open only PICT images. On Linux, OpenAsPicture will open BMP, GIF, TIFF, and XBM formats.

If you would like to open a vector image, you can use the following method:

FolderItem.OpenAsVectorPicture as Picture

Like OpenAsPicture, the OpenAsVectorPicture method returns a Picture object, but REALbasic will have tried to convert as much of the picture into Object2D objects as it can. These can be referenced by the Objects property of the Picture class, which is a Group2D instance.

When it comes time to save an image, you can choose to save it as a JPG using the following method:

FolderItem.SaveAsJPEG(Picture as Picture)

The following SaveAsPicture method provides a lot more functionality because you can decide which format to save it in, based on the platform the application is running:

FolderItem.SaveAsPicture(Picture as Picture, [Format as Integer])

REALbasic has set aside a range of values for different formats, not all of which have been designated yet. The following list shows the basic groupings:

0-99	Meta-formats
200-299	Macintosh only
300-399	Windows only

Within each range, the values of 049 represent vector images, and 5099 represent raster images. There are class constants defined for the currently supported formats:

FolderItem.SaveAsMostCompatible = 0 FolderItem.SaveAsMostComplete = 1 FolderItem.SaveAsDefault = 2 FolderItem.SaveAsDefaultVector = 3 FolderItem.SaveAsDefaultRaster = 4 FolderItem.SaveAsMacintoshPICT = 100 FolderItem.SaveAsMacintoshRasterPICT = 250 FolderItem.SaveAsWindowsWMF = 300 FolderItem.SaveAsWindowsEMF = 301 FolderItem.SaveAsWindowsBMP= 350

Creating a Picture

In addition to opening images from files, you can also easily create new Pictures programmatically in REALbasic. There are two ways to do it. The first is the NewPicture function, which takes the following arguments and returns a Picture object:

REALbasic.NewPicture(Height as Integer, Width as Integer, Depth as Integer) as Picture

The second is using the New operator and instantiating it like any other object:

Picture.Constructor(Height as Integer, Width as Integer, Depth as Integer)

The advantage of using the New operator is that if something is wrong with the Picture, an error will be thrown.

Handling Transparencies

Much like creating a Picture, there are two ways to make a part of a Picture transparent. Basically, there's the easy way and there's the hard way. The easy way is to designate anything that is the color white in a given picture as transparent, which you can do by setting the following property:

Picture.Transparent as Integer

Setting the property to 0 means that white is not transparent; setting it to 1 means that white is transparent. This is the same value that you can set in the IDE when you have imported a Picture into your project. Although that is certainly easy, there are times where that's not flexible enough, and in those situations, you can create a Mask for your picture that will determine which parts are transparent and which parts are not:

Picture.Mask as Picture

To refresh your memory on how Masks work, take a look at the section that covers creating icons.

Creating and Manipulating Pictures

Three objects that are properties of all Picture objects are very important; they provide the tools you need to generate pictures of your own. You've already seen the Graphics class. The other two will be covered separately later in the chapter.

Picture.Graphics as Graphics Picture.Objects as Group2D Picture.RBGSurface as RBGSurface

Note that the RGBSurface object is available only if the color depth is 16 or 32 bits.

More Picture Properties

The following property determines the color depth (in bits):

Picture.Depth as Integer

Legal values are 0,1,2,4,8,16, and 32. A value of 0 indicates that this Picture is a vector rather than a raster image.

As you might suspect, Pictures have heights and widths:

Picture.Height as Integer Picture.Width as Integer

Likewise, they have resolutions (in dots per inch):

Picture.HorizontalResolution as Integer Picture.VerticalResolution as Integer

Finally, some pictures are composed of multiple pictures. Animated GIFs are one example. The following properties give you access to the individual Pictures:

Picture.ImageCount as Integer Picture.IndexedImage(index as Integer) as Picture

RGBSurface Class

Although the Graphics class also lets you manipulate individual pixels, the RGBSurface class is supposed to let you do so much more efficiently. It also provides methods for transforming a graphic all at once.

RGBSurface.FloodFill(x as Integer, y as Integer, FillColor as Color) RGBSurface.Pixel(x as Integer, y as Integer) RGBSurface.Transform(Map() as Integer) RGBSurface.Transform(RedMap() as Integer, GreenMap() as Integer, BlueMap as Integer)