Class # Picture --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ## Description A Picture object contains a Picture or an image. ## Properties

table-centered_columns_3_and_4

| Name | Type | Read-Only | Shared | |------------------------------------------------------|---------------------------------------------|-----------|--------| | `Depth` | `Integer` | ✓ | | | `Graphics` | `Graphics` | ✓ | | | `Handle` | `Ptr` | ✓ | | | `HasAlphaChannel` | `Boolean` | ✓ | | | `Height` | `Integer` | ✓ | | | `HorizontalResolution` | `Integer` | | | | `ImageCount` | `Integer` | ✓ | | | `MetaData` | `Dictionary` | | | | `Objects` | `Group2D` | | | | `RGBSurface` | `RGBSurface` | ✓ | | | `Type` | `Types` | ✓ | | | `VerticalResolution` | `Integer` | | | | `Width` | `Integer` | ✓ | | ## Methods

table-centered_column_4

| Name | Parameters | Returns | Shared | |------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------|--------| | `ApplyMask` | theMask As Picture | | | | `BestRepresentation` | width As `Integer`, height As `Integer`, scale As `Double` | Picture | | | `Constructor` | width As `Integer`, height As `Integer` | | | | `Constructor` | width As `Integer`, height As `Integer`, bitmaps() As Picture | | | | `CopyColorChannels` | | Picture | | | `CopyMask` | | Picture | | | `CopyOSHandle` | type As `HandleTypes` | `Ptr` | | | | width As `Integer`, height As `Integer`, scale As `Double`, type As `HandleTypes` | `Ptr` | | | `FromData` | data As `MemoryBlock` | Picture | ✓ | | | data As `String` | Picture | ✓ | | `FromHandle` | image As `Ptr` | Picture | ✓ | | `FromScaleFactor` | width As `Double`, height As `Double`, scaleFactor As `Double` | Picture | ✓ | | `ImageAt` | index As `Integer` | Picture | | | `IsExportFormatSupported` | format As `Formats` | `Boolean` | ✓ | | `IsImportFormatSupported` | format As `Formats` | `Boolean` | ✓ | | `Open` | file As `FolderItem` | Picture | ✓ | | `OpenVector` | vectorFile As `FolderItem` | Picture | ✓ | | `Save` | file As `FolderItem`, format As `Formats`, quality As `Integer` = Picture.QualityDefault | | | | `SaveToPhotos` | format As `Formats`, quality As `Integer` = Picture.QualityDefault | | | | `SystemImage` | name As `String`, size As `Double`, weight As `Picture.SystemImageWeights` = `Picture.SystemImageWeights.Regular`, templateColor As `ColorGroup` = `Nil`, fallbackTemplateImage As Picture = `Nil` | Picture | ✓ | | | name As `String`, size As `Double` = 24, templateColor As `ColorGroup` = `Nil`, fallbackTemplateImage As Picture = `Nil` | Picture | ✓ | | `ToData` | format As `Formats`, jpegQuality As `Integer` = Picture.QualityDefault | `MemoryBlock` | | ## Enumerations

forsearch

Picture.Formats ### Formats > The various Picture formats that are supported. > > | Enum | Supported Platforms | > |------|-------------------------------------| > | BMP | Android, iOS, Linux, macOS, Windows | > | GIF | Android, macOS, Windows | > | HEIC | iOS | > | JPEG | Android, iOS, Linux, macOS, Windows | > | PNG | Android, iOS, Linux, macOS, Windows | > | TIFF | iOS, Linux, macOS, Windows |

forsearch

Picture.HandleTypes ### HandleTypes > OS handle types. > > | Enum | Description | > |-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| > | MacCGImage | A CGImageRef that you are responsible for releasing with CFRelease. Supported on macOS GUI applications. | > | WindowsBMP | A 32-bit HBITMAP that you are responsible for releasing with DeleteObject. Supported in Windows GUI applications. | > | WindowsICON | A 32-bit HICON that you are responsible for releasing with DeleteObject. Supported in Windows GUI applications. | > | LinuxGdkPixbuf | A 32-bit GdkPixbuf that you are responsible for releasing with g_object_unref. Supported in Linux GUI applications. | > | ConsoleGDImage | A gdImagePtr that you are responsible for releasing with gdFree. This requires the use of the libgd library. Supported in console applications (all platforms). | > | MacNSImage | A NSImage object that has been autoreleased, so an explicit release is not necessary. This is supported for all types of Pictures, including vector images. Supported on macOS GUI applications. | > | iOSUIImage | A UIImage object that has been autoreleased, so an explicit release is not necessary. Supported in iOS/iPadOS applications. | > | AndroidBitmap | Supported for Android applications. | > | AndroidDrawable | Supported for Android applications. |

forsearch

Picture.SystemImageWeights ### SystemImageWeights > The weight of a system image retrieve using SystemImage method. > > | Enum | Description | > |-------------|-------------------------------------| > | Unspecified | An unspecified symbol image weight. | > | UltraLight | An ultralight weight. | > | Thin | A thin weight. | > | Light | A light weight. | > | Regular | A regular weight. | > | Medium | A medium weight. | > | Semibold | A semibold weight. | > | Bold | A bold weight. | > | Heavy | A heavy weight. | > | Black | An ultra-heavy weight. |

forsearch

Picture.Types ### Types > The valid Picture types: Image, Vector, MutableBitmap, ImmutableBitmap > > | Enum | Description | > |-----------------|-----------------------------------------| > | Image | An Image for use with HiDPI displays. | > | Vector | A Vector graphic. | > | MutableBitmap | A bitmap image that can be modified. | > | ImmutableBitmap | A bitmap image that cannot be modified. | ## Property descriptions

forsearch

Picture.Depth **Depth** As `Integer` > The bit depth of the picture. > > This property is read-only. > >

> >

> > Important > >

> > This property is not supported for mobile projects. > >

forsearch

Picture.Graphics **Graphics** As `Graphics` > The actual Picture. The Graphics property gives you access to the methods of the `Graphics` class. Use it to draw in the Picture. Use it when you need to draw into the Picture. Create a new Picture instance and then draw into it using the Graphics property. > > This property is read-only. > > This example creates a blank Picture instance and then draws into it using the Graphics property. It assigns the Picture to the backdrop property of a Canvas. A recommended alternative is to update the interface via drawing in the Canvas's `Paint` event instead. > > ``` xojo > Var p As New Picture (340, 280, 32) > > p.Graphics.Bold = True > p.Graphics.Italic = True > p.Graphics.FontName = "Helvetica" > p.Graphics.FontSize = 18 > p.Graphics.DrawingColor = &cff0000 > p.Graphics.DrawText("Hello World", 10, 100) > > Canvas1.Backdrop = p > ``` > > You can also draw into an existing Picture instance. However, in this case, because loading a picture from a file creates a picture that is immutable (not changeable), you must create another picture and draw the picture you are opening from a file into that picture so that you can draw on top of it: > > ``` xojo > Var f As FolderItem = FolderItem.ShowOpenFileDialog("image/jpeg") > > If f <> Nil Then > Var p As Picture = Picture.Open(f) > Var mutablePicture As New Picture(p.Width, p.Height) > > mutablePicture.Graphics.Bold = True > mutablePicture.Graphics.Italic = True > mutablePicture.Graphics.FontName = "Helvetica" > mutablePicture.Graphics.FontSize = 18 > mutablePicture.Graphics.DrawingColor = &cff0000 > mutablePicture.Graphics.DrawText("Hello World", 50, 230) > Canvas1.Backdrop = mutablePicture > End If > ```

forsearch

Picture.Handle **Handle** As `Ptr` > Returns a `Ptr` to the underlying image. This property is for use with Declares on iOS only. > > The `Ptr` returned is a UIImage. > >

> >

> > Note > >

> > A `Ptr` is only returned if the picture is a project item or was retrieved via `Picture.SystemImage`. > >

> > This property is read-only.

forsearch

Picture.HasAlphaChannel **HasAlphaChannel** As `Boolean` > `True` if the Picture has an alpha channel. > > This property is read-only. > >

> >

> > Important > >

> > This property is not supported for mobile projects. > >

> > A Picture that is created with the constructor that omits the *Depth* parameter has an alpha channel and old pictures can be converted to this format with the following code: > > ``` xojo > Function ConvertToAlphaPicture(input As Picture) As Picture > If input.HasAlphaChannel Then Return input > > Var result As New Picture(input.Width, input.Height) > > result.Graphics.DrawPicture(input, 0, 0) > > Return result > End Function > ```

forsearch

Picture.Height **Height** As `Integer` > The height (in pixels) of the Picture. > > This property is read-only. > > This example displays the width and height of the Picture that the user chose: > > ``` xojo > Var f As FolderItem = FolderItem.ShowOpenFileDialog("image/jpeg") > > If f <> Nil Then > Var pic As Picture = Picture.Open(f) > > Label1.Text = pic.Width.ToString > Label2.Text = pic.Height.ToString > End If > ```

forsearch

Picture.HorizontalResolution **HorizontalResolution** As `Integer` > The horizontal resolution of the Picture. > >

> >

> > Important > >

> > This property is not supported for Android. > >

> > The horizontal resolution is established when you use the Open shared method and written out when using the Save method. When creating a Picture, the default resolution is 72 (pixels). > >

> >

> > Note > >

> > To get the actual Picture resolution for an opened Picture file on Linux, gtk+ 2.32 or later is required. > >

> > This example gets the horizontal and vertical resolution of the Picture that was opened: > > ``` xojo > Var f As FolderItem = FolderItem.ShowOpenFileDialog("image/jpeg") > > If f <> Nil Then > Var pic As Picture = Picture.Open(f) > > ImageWell1.Image = pic > Label1.Text = pic.HorizontalResolution.ToString > Label2.Text = pic.VerticalResolution.ToString > End If > ```

forsearch

Picture.ImageCount **ImageCount** As `Integer` > The number of indexed images in the Picture. > > This property is read-only. > >

> >

> > Important > >

> > This property is not supported for Android. > >

> > This applies to image formats that can contain multiple images, such as TIFF. > > This example gets the number of indexed images in the Picture. > > ``` xojo > Var width As Integer = 2000 > Var height As Integer = 2000 > > ' creates new picture > Var pic As New Picture(width, height, 32) > Var f As FolderItem = FolderItem.ShowOpenFileDialog("image/jpeg") > > If f <> Nil Then > pic = Picture.Open(f) > ImageWell1.Image = pic > Label1.Text = pic.ImageCount.ToString > End If > ```

forsearch

Picture.MetaData **MetaData** As `Dictionary` > Allows you to get and set the Exif data for the picture. > >

> >

> > Important > >

> > This property is currently supported for iOS only. > >

forsearch

Picture.Objects **Objects** As `Group2D` > A set of vector graphics associated with the Picture (optional). > >

> >

> > Important > >

> > This property is not supported for mobile projects. > >

> > Specify a depth of zero to create a Picture with no pixel map at all, but with a preinitialized Objects property. Use this option for creating vector graphics pictures via the set of Object2D subclasses. > > Create a vector image: > > ``` xojo > Var vectorImage As New Picture(10, 10, 0) > ```

forsearch

Picture.RGBSurface **RGBSurface** As `RGBSurface` > Provides pixel-level access to the Picture's bitmap. > > This property is read-only. > > Used only for pictures built with the Picture constructor with no pixel depth or only a depth of 16 or 32, otherwise it returns `Nil`. Returns an `RGBSurface` object. Calling RGBSurface is a computer-intensive process. Use it to access individual pixels of the Picture image. It is extremely fast — faster than accessing pixels through the `Graphics` property.

forsearch

Picture.Type **Type** As `Types` > The Type of the Picture. This is set automatically based on how the Picture was created. > > This property is read-only. > >

> >

> > Important > >

> > This property is not supported for Android. > >

> > Uses the Types Enumeration to specify the Type: > > - Image: An Image for use with HiDPI displays. > - Vector: A Vector graphic. > - MutableBitmap: A bitmap Picture that can be modified. > - ImmutableBitmap: A bitmap Picture that cannot be modified. > > Pictures in the project, loaded from disk, received from drag and drop, or loaded from data will be loaded as Images (unless it's a Vector in which case it is loaded as Vector). This better preserves color spaces, loads multiple resolutions if the format supports it, and reduces memory usage.

forsearch

Picture.VerticalResolution **VerticalResolution** As `Integer` > The vertical resolution of the Picture. > >

> >

> > Important > >

> > This property is not supported for Android. > >

> > The vertical resolution is established when you use the Open shared method and written out when you use the Save method. When creating a Picture, the default resolution is 72 (pixels). > >

> >

> > Note > >

> > To get the actual Picture resolution for an opened Picture file on Linux, gtk+ 2.32 or later is required. > >

> > This example gets the horizontal and vertical resolution of the Picture that was opened. > > ``` xojo > Var f As FolderItem = FolderItem.ShowOpenFileDialog("image/jpeg") > > If f <> Nil Then > Var pic As Picture = Picture.Open(f) > > ImageWell1.Image = pic > Label1.Text = pic.HorizontalResolution.ToString > Label2.Text = pic.VerticalResolution.ToString > End If > ```

forsearch

Picture.Width **Width** As `Integer` > The width (in pixels) of the Picture. > > This property is read-only. > > This example displays the width and height of the Picture that the user chose. > > ``` xojo > Var width As Integer = 2000 > Var height As Integer = 2000 > > ' creates new picture > Var pic As New Picture(width, height) > Var f As FolderItem = FolderItem.ShowOpenFileDialog("image/jpeg") > > If f <> Nil Then > pic = Picture.Open(f) > Label1.Text = pic.Width.ToString > Label2.Text = pic.Height.ToString > End If > ``` ## Method descriptions

forsearch

Picture.ApplyMask **ApplyMask**(theMask As Picture) > When used on a Picture with an alpha channel, this overwrites the Picture's alpha channel with the mask data. When used on a Picture with a mask, it overwrites the current mask with a copy of the mask passed in. > >

> >

> > Important > >

> > This method is not supported for Android. > >

forsearch

Picture.BestRepresentation **BestRepresentation**(width As `Integer`, height As `Integer`, scale As `Double`) As Picture > Calculates which Picture is the best to use for drawing at the requested size. > >

> >

> > Important > >

> > This method is not supported for Android. > >

> > The algorithm iterates through the indexed images, first finding Picture with the closest number of pixels to the destination, preferring the next largest image if no exact match is found. If multiple pictures match, the Picture with the DPI closest to the destination scale is chosen. It is possible that this function returns Self. > > Raises an `InvalidArgumentException` if width, height, or scale are less than or equal to zero.

forsearch

Picture.Constructor **Constructor**(width As `Integer`, height As `Integer`) >

> >

> > Note > >

> > `Constructors` are special methods called when you create an object with the `New` keyword and pass in the parameters above. > >

> > Creates a Picture of the *width* and *height* specified. > > A Picture created with this constructor supports an alpha channel directly instead of requiring the use of masks. > > The *width* and *height* are in points.

forsearch

Picture.Constructor **Constructor**(width As `Integer`, height As `Integer`, bitmaps() As Picture) > Creates a Picture of the size specified by the *width* and *height* from one or more Bitmap pictures. > >

> >

> > Important > >

> > This method is not supported for Android. > >

> > The *width* and *height* are in points. The *bitmaps* are copied upon creation. All bitmaps must have the same aspect ratio. A bitmap's DPI will be calculated from the point size and the bitmap's size in pixels. Pictures created using this constructor have their Type set to Types.Image.

forsearch

Picture.CopyColorChannels **CopyColorChannels** As Picture > Copies just the color information from a Picture. > >

> >

> > Important > >

> > This method is not supported for Android. > >

> > This method returns a clone of the color data in a Picture with a solid mask. > > The returned Picture object: > > - has the same dimensions, resolutions and scale factors as the original. > - is a mutable bitmap > - uses alpha channels instead of masks (i.e. HasAlphaChannel will be True) > - is entirely opaque > >

> >

> > Warning > >

> > An `UnsupportedOperationException` will be raised when called on a vector or multi-representation image. > >

> >

> > Warning > >

> > An OutOfMemoryException will be raised if the Picture cannot be created. > >

> > Get the color channels from MyPic: > > ``` xojo > Var colorChannels As Picture > > colorChannels = MyPic.CopyColorChannels > ```

forsearch

Picture.CopyMask **CopyMask** As Picture > When used on a Picture with an alpha channel, this takes the image's alpha channel and creates the equivalent mask. If used on a Picture with a mask, it returns a copy of the current mask. In neither case does it alter the original image and the copied mask is not updated when any drawing happens on the original Picture. > >

> >

> > Important > >

> > This method is not supported for Android. > >

forsearch

Picture.CopyOSHandle **CopyOSHandle**(type As `Picture.HandleTypes`) As `Ptr` > Returns a platform-specific image handle. > >

> >

> > Important > >

> > This method is not supported for Android. > >

> > The following code gets the CGImageRef from the Picture and properly releases it. > > ``` xojo > Declare Sub CFRelease Lib "CoreFoundation" (obj As Ptr) > > Var pict As New Picture(100, 100, 32) > Var cgImage As Ptr = pict.CopyOSHandle(Picture.HandleTypes.MacCGImage) > > ' Do something with the 'cgImage' object > CFRelease(cgImage) > ``` ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

forsearch

Picture.CopyOSHandle **CopyOSHandle**(width As `Integer`, height As `Integer`, scale As `Double`, type As `HandleTypes`) As `Ptr` > Returns a platform-specific image handle that is the best match for drawing at the given resolution, using the same logic as `BestRepresentation`. > >

> >

> > Important > >

> > This method is not supported for Android. > >

forsearch

Picture.ImageAt **ImageAt**(index As `Integer`) As Picture > Returns the image in the picture specified by the passed *index*. > >

> >

> > Important > >

> > This method is not supported for Android. > >

> >

> > Warning > >

> > The individual pictures aren't necessarily stored/returned in ascending scalefactor order. Do not rely on a particular order for the pictures. > >

> > This example gets the image referenced by the passed index and displays it in the `ImageViewer`: > > ``` xojo > Var f As FolderItem = FolderItem.ShowOpenFileDialog("image/jpeg") > > If f <> Nil Then > Var pic As Picture = Picture.Open(f) > ImageViewer1.Image = pic.ImageAt(0) > End If > ``` > > If you have an Image Set with multiple images for HiDPI and want to split out each of the pictures it contains, you can do so like this: > > ``` xojo > Var g As Graphics > Var p, pics() As Picture > > ' Break the Image into its component pictures > ' Also copy the horizontal/vertical resolution and scale factors > ' so that the pictures draw properly when used later. > For i As Integer = 0 To MyImageSet.ImageCount - 1 > p = New Picture(MyImageSet.ImageAt(i).Width, ImageAt(i).Height) > p.HorizontalResolution = MyImageSet.ImageAt(i).HorizontalResolution > p.VerticalResolution = MyImageSet.ImageAt(i).VerticalResolution > pics.Add(p) > g = p.Graphics > g.ScaleX = p.HorizontalResolution / 72 > g.ScaleY = p.VerticalResolution / 72 > g.DrawPicture(MyImageSet.ImageAt(i), 0, 0) > Next > ``` > > If you later modify the pictures in the array and want to recreate it as an image, you can do so using the constructor like this: > > ``` xojo > ' Recreate the image from the component pictures > p = New Picture(MyImageSet.Width, MyImageSet.Height, pics) > ```

forsearch

Picture.FromData **FromData**(data As `MemoryBlock`) As Picture > Obtains a Picture that is stored in a `MemoryBlock` and returns a Picture. > > This method is `shared`. > > This example uses `ToData` to convert an image in an `ImageViewer` into a `MemoryBlock` and then uses FromData to display the image: > > ``` xojo > Var mb As MemoryBlock > > If ProductImageViewer.Image <> Nil Then > ' Get the image data > mb = ProductImageViewer.Image.ToData(Picture.Formats.JPEG, Picture.QualityHigh) > ' convert the MemoryBlock back into an image > ImageViewer1.Image = Picture.FromData(mb) > End If > ``` ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

forsearch

Picture.FromData **FromData**(data As `String`) As Picture > Obtains a Picture that is stored in the *data* passed and returns a Picture. > > This method is `shared`. > >

> >

> > Important > >

> > This signature is supported for Android only. > >

forsearch

Picture.FromHandle **FromHandle**(image As `Ptr`) As Picture > Returns a Picture from an OS handle > > This method is `shared`. > >

> >

> > Important > >

> > This method is supported for iOS only. > >

forsearch

Picture.FromScaleFactor **FromScaleFactor**(width As `Double`, height As `Double`, scaleFactor As `Double`) As Picture > Creates a new Picture with the specified *width* and *height* (rounded to the nearest pixel), adjusted for a given scale factor. > > This method is `shared`.

forsearch

Picture.IsExportFormatSupported **IsExportFormatSupported**(format As `Formats`) As `Boolean` > Returns `True` if the passed format is supported for export. > > This method is `shared`. > >

> >

> > Important > >

> > This method is supported for desktop and console projects only. > >

> > This example checks to see that the format is supported for export prior to calling it: > > ``` xojo > Var imageData As String > Var bs As BinaryStream > Var f As FolderItem > > If ImageWell1.Image <> Nil Then > ' Get a temporary file to save the image to > If Picture.IsExportFormatSupported(Picture.Formats.JPEG) Then > f = SpecialFolder.Temporary.Child("TempImage.jpg") > > ' Save the image out to the file > ImageWell1.Image.Save(f, Picture.Formats.JPEG) > End If > > ' Open the file as a BinaryStream and read the data in > bs = BinaryStream.Open(f, False) > > If bs <> Nil Then > imageData = bs.Read(bs.Length) > bs.Close > End If > > ' delete the temporary file if it exists > If f.Exists Then > f.Delete > End If > End If > ```

forsearch

Picture.IsImportFormatSupported **IsImportFormatSupported**(format As `Formats`) As `Boolean` > Returns `True` if the passed format is supported for import. > > This method is `shared`. > >

> >

> > Important > >

> > This method is supported for desktop and console projects only. > >

> > BMP, GIF and TIFF formats are not supported for Console apps. > > This example checks to see if a format is supported for import prior to calling it: > > ``` xojo > Var width As Integer = 2000 > Var height As Integer = 2000 > > ' creates new picture > Var pic As New Picture(width, height) > > Var f As FolderItem = FolderItem.ShowOpenFileDialog("image/jpeg") > > If Picture.IsImportFormatSupported(Picture.Formats.JPEG) Then > If f <> Nil Then > pic = Picture.Open(f) > ImageWell1.Image = pic > End If > End If > ```

forsearch

Picture.Open **Open**(file As `FolderItem`) As Picture > Opens the passed `FolderItem` to be read as a Picture. Returns a Picture on success. If the FolderItem passed is nil, a `NilObjectException` is raised. If Picture.Open fails for any other reason, `Nil` is returned with no other error information. > > This method is `shared`. > >

> >

> > Note > >

> > Pictures opened with this method are immutable. > > All supported `Picture.Formats` can also be opened. Depending on the operating system also others. > >

> > The following example prompts you to select a file and then opens it and displays it in an `DesktopImageViewer`: > > ``` xojo > Var f As FolderItem = FolderItem.ShowOpenFileDialog("") > > If f <> Nil And f.Exists Then > ImageWell1.Image = Picture.Open(f) > End If > ```

forsearch

Picture.OpenVector **OpenVector**(vectorFile As `FolderItem`) As Picture > Opens the passed FolderItem to be read as a vector Picture. > > This method is `shared`. > >

> >

> > Important > >

> > This method is supported for desktop and console projects only. > >

> > It will do its best to convert a PICT file (on macOS) or an .emf file (Windows) to a Picture composed of `Object2D` objects. The original file may contain elements that do not have an equivalent `Object2D` object. This method will do its best to map these objects, but there may be some loss of information, depending on the characteristics of the original file. PICTs support unrotated Rectangles, Lines, Ellipses, RoundRects, Polygons, Text, Pixmaps, and Arcs. > > .emf files support unrotated Rectangles, Lines, Ellipses, RoundRects, Polygons, Text, Pixmaps and Arcs. > > .emf files are displayed as actual size. For the most part this is huge; you probably will want to scale them down before viewing (pic1.objects.scale = scalingFactor). We find that a scale factor of 0.045 is a good value. > > The following example opens an ancient PICT file as a Picture. The image/x-pict file type has been added using the File Types Editor. > > ``` xojo > Var f As FolderItem = FolderItem.ShowOpenFileDialog("image/x-pict") > Var p As Picture = Picture.OpenVector(f) > > If p <> Nil Then > MessageBox(p.ImageCount.ToString) > Else > MessageBox("Open failed!") > End If > ```

forsearch

Picture.Save **Save**(file As `FolderItem`, format As `Formats`, quality As `Integer` = Picture.QualityDefault) > Saves the Picture in file specified by *file*, using the file format specified by *format*. For the list of available formats, see `Formats`. > >

> >

> > Note > >

> > Only JPEG and PNG are supported in `console applications` > >

> > If the `FolderItem` exists, then it will be overwritten by the new Picture file. > > If you are using the JPEG format, then there is an optional parameter for the quality of the JPEG. You specify the quality using the following class constants. Introduced 2010r5 > > | Constant | Value | > |----------------|-------| > | QualityDefault | -1 | > | QualityMaximum | 100 | > | QualityHigh | 80 | > | QualityMedium | 50 | > | QualityLow | 25 | > | QualityMinimum | 0 | > > The following example saves the contents of an `DesktopImageViewer` to a temporary file on disk and then reads it into a `BinaryStream` for storage in a database. The property f as `FolderItem` is a property of the window. > > ``` xojo > Var imageData As String > Var bs As BinaryStream > Var f As FolderItem > > If ImageWell1.Image <> Nil Then > ' Get a temporary file to save the image to > If Picture.IsExportFormatSupported(Picture.Formats.JPEG) Then > f = SpecialFolder.Temporary.Child("TempImage.jpg") > > ' Save the image out to the file > ImageWell1.Image.Save(f, Picture.Formats.JPEG) > End If > > ' Open the file as a BinaryStream and read the data in > bs = BinaryStream.Open(f, False) > > If bs <> Nil Then > imageData = bs.Read(bs.Length) > bs.Close > End If > > ' delete the temporary file if it exists > If f.Exists Then > f.Delete > End If > End If > ```

forsearch

Picture.SaveToPhotos **SaveToPhotos**(format As `Formats`, quality As `Integer` = Picture.QualityDefault) > Saves the Picture to the user album, using the *format* and *quality* passed. > >

> >

> > Important > >

> > This method is currently supported for iOS only. > >

forsearch

Picture.SystemImage **SystemImage**(name As `String`, size As `Double`, weight As `SystemImageWeights` = `Picture.SystemImageWeights.Regular`, templateColor As `ColorGroup` = `Nil`, fallbackTemplateImage As Picture = `Nil`) As Picture > This method retrieves an image based upon the parameters passed. > > On iOS these images come from iOS itself and are called *SF Symbols*. There are over more than 1500 system symbol images available. To browse the available symbol images, use the [Apple SF Symbols](https://developer.apple.com/design/resources/) viewer app. > > This method is `shared`. > >

> >

> > Important > >

> > This method is only supported for iOS. > >

> > This example returns the image named "moon" at a size of 50 and then draws it into a `Graphics` object: > > ``` xojo > Var moon As Picture = Picture.SystemImage("moon", 50) > g.DrawPicture(moon, 0, 0) > ``` ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

forsearch

Picture.SystemImage **SystemImage**(name As `String`, size As `Double` = 24, templateColor As `ColorGroup` = `Nil`, fallbackTemplateImage As Picture = `Nil`) As Picture > This method retrieves an image based upon the parameters passed. > > On Android, the image comes from a library of images built-in to the Xojo Android framework. There are over [more than 2000 images available](https://pictogrammers.com/library/mdi/). > > This method is `shared`. > >

> >

> > Important > >

> > This method is only supported for Android. > >

> > This example returns the image named "moon-full" at a size of 48 and then draws it into a `Graphics` object: > > ``` xojo > Var moon As Picture = Picture.SystemImage("moon-full", 48) > g.DrawPicture(moon, 0, 0) > ```

forsearch

Picture.ToData **ToData**(format As `Formats`, jpegQuality As `Integer` = Picture.QualityDefault) As `MemoryBlock` > Converts the Picture to a `MemoryBlock`. > >

> >

> > Note > >

> > Console applications only support JPEG and PNG image types. > >

> > If you are using the JPEG format, then there is an optional parameter for the quality of the JPEG. You specify the quality using the following class constants instead of the literal values. > > | Constant | Value | > |----------------|-------| > | QualityDefault | -1 | > | QualityMaximum | 100 | > | QualityHigh | 80 | > | QualityMedium | 50 | > | QualityLow | 25 | > | QualityMinimum | 0 | > > This example uses ToData to convert an image in an `DesktopImageViewer` into a `MemoryBlock`: > > ``` xojo > Var mb As MemoryBlock > > If ProductImageViewer.Image <> Nil Then > ' Get the image data > mb = ProductImageViewer.Image.ToData(Picture.Formats.JPEG, Picture.QualityHigh) > ' convert the MemoryBlock back into an image > ImageViewer1.Image = Picture.FromData(mb) > End If > ``` ## Notes

Note

Console applications only support JPEG and PNG image types.

--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Image Sets and HiDPI When adding Pictures to your projects, you create `Image Set Editor` which can contain the Picture at various sizes for use with HiDPI displays. Also refer to `HiDPI Support` for important additional information. --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Support for transparency Picture objects support alpha channels (transparency) directly, without the need for a mask. Support for the alpha channel is now built into the color functions: `Color.RGB`, `Color.HSV`, `Color.CMY`, and `&c`. These functions have an optional fourth parameter that specifies the degree of transparency of the color. Here are the modified functions: | Function | Parameters | |--------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `Color.RGB` | *red* as `Integer`, green As `Integer`, blue As `Integer`, alpha As `Integer` = 0 | | `Color.HSV` | *hue* as `Double`, saturation As `Double`, value As `Double`, alpha As `Integer` = 0 | | `Color.CMY` | *cyan* as `Double`, magenta As `Double`, yellow As `Double`, alpha As `Integer` = 0 | | `&c` | *RRGGBBAA*, where the hex digits specify the amounts of red, green, blue, and transparency in the color. For the transparency parameter, 00 is opaque and FF is fully transparent. | In the Picture class, support for alpha channels means that the use of masks is no longer required. This streamlines the process and reduces memory support. To take advantage of this feature, you can create new Picture objects with alpha channel support and convert “old” Picture objects to those with alpha channels. --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Updating pictures with masks Pictures loaded from disk, databases, project files, or Picture.FromData continue to return pictures with masks. This is required for legacy compatibility, but masked Pictures can be converted to a Picture with an alpha channel with the following code: ``` xojo Function ConvertToAlphaPicture(input As Picture) As Picture If input.HasAlphaChannel Then Return input Var result As New Picture(input.Width, input.Height) result.HorizontalResolution = input.HorizontalResolution result.VerticalResolution = input.VerticalResolution result.Graphics.DrawPicture(input, 0, 0) Return result End Function ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### HasAlphaChannel property ``` xojo HasAlphaChannel As Boolean ``` This property indicates whether or not the Picture has an alpha channel. For Pictures using masks, this returns `False`. --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### CopyMask method ``` xojo CopyMask As Picture ``` When used on a Picture with an alpha channel, this takes the image's alpha channel and creates the equivalent mask. If used on a Picture with a mask, it returns a copy of the current mask. In neither case does it alter the original image and the copied mask is not updated when any drawing happens on the original Picture. --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### ApplyMask method ``` xojo ApplyMask(theMask As Picture) ``` When used on a Picture with an alpha channel, this overwrites the Picture's alpha channel with the mask data. When used on a Picture with a mask, it overwrites the current mask with a copy of the mask passed in. --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Other alpha channel notes `Pixel` and `RGBSurface` have been updated to properly support alpha channels by taking them into account when rendering them. Additionally, `Pixel` properly reports back alpha channel information, if available. Pictures with alpha channels cannot also use masks. Trying to do so will raise an `UnsupportedOperationException` at runtime. Reading this value always returns `Nil` for pictures with alpha channels. For pictures without alpha channels, the mask functionality continues to work normally. On macOS and Linux, Pictures are stored internally with their alpha channels premultiplied into the color channels. Since premultiplication is a lossy operation, the color you draw may not be exactly what you get out when inspecting it with an `RGBSurface`. For example, drawing a `&cFF00EECC` rectangle will result in a different color if read from that pixel using `RGBSurface`. --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Plugin support The color type has changed from being XRGB to ARGB. If you previously put garbage into the first byte, this is going to cause problems now that the framework uses this to store the alpha component. On macOS, a Picture with an alpha channel is represented internally as a premultiplied ARGB buffer wrapped by a `CGBitmapContext`. This buffer can be accessed the same way as for masked images: `REALLockPictureDescription` and then `CGBitmapContextGetData`. On Windows, a Picture with an alpha channel is represented internally as a premultiplied 32-bit BGRA buffer. This buffer can be accessed the same way as for masked images: `REALLockPictureDescription` and the raw bytes are returned in the data field. On Linux, a Picture with an alpha channel is represented internally as a 32-bit premultiplied ARGB buffer wrapped by a `cairo_t`. This buffer can be accessed the same way as for masked images: `REALLockPictureDescription` and then `cairo_image_surface_get_data( cairo_get_target( cairo_t * ) )`. On console and web apps, a Picture with an alpha channel is represented internally as a 32-bit ARGB buffer wrapped by a gdImagePtr.

Note

The ARGB buffer is NOT premultiplied, and the maximum alpha value is 127 instead of 255. This buffer can be accessed the same way as for masked images: `REALLockPictureDescription` with `pictureGDPtr` (this will give you the raw buffer with an 11 byte header).

`Object` parent class; `RGBSurface` object; `Graphics` class.