The presentation server supports the following image formats via WIC:

• BMP
• GIF
• ICO
• JPEG
• PNG
• TIFF

These properties apply to most IMAGE objects unless noted otherwise.

Specifies the horizontal and vertical alignment of the image.

A numeric value that describes the position of the image within its parent object:

The ALIGN property is ignored if either of these conditions are met:

• If the ORIGIN property is set to a value other than (0,0)
• If the STYLE property is set to any value other than "Clip" (0).

Equated constants for the ALIGN property can be found in the PS_EQUATES insert record.

 
 // Set the alignment of the background image for the PNL_MAIN control //

$Insert PS_Equates

 Call Set_Property_Only( @Window : "PNL_MAIN.IMAGE", "ALIGN", |
                         PS_IA_BOTTOMRIGHT$ ) 
 

Image ORIGIN property, Image STYLE property.

Specifies if the image should be scaled along with its parent object.

This property is a boolean value. If set to TRUE$ (the default value) then the image will be scaled along with its parent control when the underlying parent form's DPI or SCALEFACTOR property is changed.

N/a.

 
 $Insert Logical
 
 // Example: Set the auto-scaling of the background image for the//
 // current window to FALSE$//
 Call Set_Property_Only( @Window : ".IMAGE", "AUTOSCALE", FALSE$ ) 
 

DPI property, WINDOW SCALEFACTOR property, WINDOW SCALED event, Appendix K – High-DPI Programming.

Specifies the color in the image that is considered to be the "transparent color".

This property can be a standard RGB color value or one of the special "color-key" values listed below:

Earlier versions of OpenInsight have supported basic image transparency via a method called “color-keying”, where a specific color in the image is nominated as the transparent color (by default the color of the top-left pixel). When the image is drawn to screen the pixels that match the transparent color are not rendered so the background pixels show through instead. Whilst this can be effective in simple cases, it is sub-optimal for images that have smooth curves and shadows as these tend to appear very pixelated.

A much better alternative is to use an image format that supports an “alpha channel” such as a PNG file. Basically this means that each pixel in the image has an extra byte that describes its transparency - a value of 0 means that the pixel is totally transparent, while a value of 255 means that the pixel is totally opaque, Values in between are used to calculate how the image pixel is combined with the background pixel when drawn, so that it gives the appearance of being translucent, allowing the background pixel to show through to some degree. This is a technique known as Alpha-blending and is supported fully in this version of OpenInsight.

Because of this you should only use color-keying on older format images like 24-bit bitmap images that do not have an alpha channel - using more modern formats like PNG files will give much better results.

Equated constants for the COLORKEY property can be found in the PS_EQUATES insert record with the prefix "PS_TC_".

The 24-bit bitmap image below (i.e.no alpha-channel) has a white background. To draw it "transparently" onto a surface that is a different color we have to set the COLORKEY property. In this case we can hard-code it to White (RGB value of 0x00FFFFFF), or we can tell it to use one of the corner pixels instead.

 
 $Insert PS_Equates
 
 // Example 1: Set the ColorKey of the background image for the//
 // current window to use the top-left pixel of the image.//
 
 Call Set_Property_Only( @Window : ".IMAGE", "COLORKEY", PS_TC_TOPLEFT$ )
 

The code above gives the following results:

Note the pixelated edge due to the shadow in the image. A PNG file with an alpha-channel gives much better results however, as the shadow is blended correctly:

N/a.

Specifies the number of sub- images in an image file. For an object that can support many images (like a TOOLBAR), or several image states (like a PUSHBUTTON), it is often better to have a single file containing all the required images arranged in a horizontal strip rather than loading individual files. The INDEX property is then used to display the desired image. For example, the following image file would have a COUNT property of 6, and setting the INDEX property to 4 would display the "search" image:

This property is an integer value, greater than 0.

Note that this property is not the same as the FRAMECOUNT property (see below). Frames are intrinsic to the image format itself, whereas those defined by the COUNT property are multiple sub-images combined in a file with a single frame (In effect this emulates a multi-frame file format). Each of these "sub-images" should have the same width.

 
 // Set the number of images in the IMAGE object and display the//
 // the 4th image//
 
 ObjxArray =        @Window : ".IMAGE"
 PropArray =        "COUNT"
 DataArray =        6
 
 ObjxArray := @Rm : @Window : ".IMAGE"
 PropArray := @Rm : "INDEX"
 DataArray := @Rm : 4
 
 Call Set_Property_Only( ObjxArray, PropArray, DataArray )
    

Image FRAMECOUNT property, Image INDEX property.

When used with Get_Property this property returns the name of the file being displayed. When used with Set_Property it operates the same as the FILENAMES property.

When used with Get_Property the value is the name of the selected image file name being displayed.

When used with Set_Property the value can be an @Fm-delimited array of file names as per the FILENAMES property.

Image file names can be in one of several formats:

• A path and file name of an image file.
• A path and file name to a resource file (such as a DLL) containing the image, along with its resource ID. The latter component is separated from the file name by a “#” character.

E.g.

.\res\MyAppRes.Dll#192

.\res\MyAppRes.Dll#MYIMAGE

Note that if the image is stored in a custom resource section (rather than the usual BITMAP section) the custom section name may be specified by appending it after the resource name like so:

.\res\MyAppRes.Dll#192#JPG

.\res\MyAppRes.Dll#MYIMAGE#PNG

• The name of a "System Icon" (See Appendix J).
• The string "<memory> if the image has been set by the SETIMAGE method.
• The string "<HBITMAP>" if the image was set by the SETHBITMAP method.

(Note that the latter two formats cannot be used with Set_Property).

When a control has been given a set of multiple filenames to display, the Presentation Server selects the closest match based on the current scaling information for the parent form (See the FILENAMES property for more details).

 
 // Example - get the current file name being used be the current form's IMAGE object//
 ImgFile = Get_Property( @Window : ".IMAGE", "FILENAME" )
    

Image FILENAMES property, WINDOW DPI property, WINDOW SCALEFACTOR property, Image SAVETOFILE method, Image SETHBITMAP method, Image SETIMAGE method, WINDOW SCALED event, Appendix J – System Icons, Appendix K – High-DPI Programming.

Specifies an array of DPI-specific files to be displayed.

This property is an @Fm-delimited array of file names used to display the image at different DPI/Scaled settings. The position of a filename in the array corresponds to the DPI value for which it should be used, as illustrated in the following table:

Image file names can be in one of several formats:

• A path and file name of an image file.
• A path and file name to a resource file (such as a DLL) containing the image, along with its resource ID. The latter component is separated from the file name by a “#” character.

E.g.

.\res\MyAppRes.Dll#192

.\res\MyAppRes.Dll#MYIMAGE

Note that if the image is stored in a custom resource section (rather than the usual BITMAP section) the custom section name may specified by appending it after the resource name like so:

.\res\MyAppRes.Dll#192#JPG

.\res\MyAppRes.Dll#MYIMAGE#PNG

• The name of a "System Icon" (See Appendix J).
• The string "<memory> if the image has been set by the SETIMAGE method.
• The string "<HBITMAP>" if the image was set by the SETHBITMAP method.

(Note that the latter two formats cannot be used with Set_Property).

When the Presentation Server needs to display an image it first takes the product of the parent form's SCALEFACTOR property and the DPI of the monitor on which it is displayed to calculate a "required DPI". This value is then compared to the files in the FILENAMES property to find the closest fit, which is then rendered on the object in question. If an exact DPI match cannot be found the file with the next largest DPI is used because image quality is usually better when an image is resized smaller than when it is resized larger.

 
 // Example - set an array of files for an IMAGE object so that the system//
 // can pick one that looks better depending on the form's DPI and SCALEFACTOR.//
 ////
 // For a required DPI of 96 or less the object will select ImgFiles<1>//
 // For a required DPI between 144 (inc) and 96 the object will select ImgFiles<2>//
 // For a required DPI greater than 144 it will select ImgFiles<3>//
 
 ImgFiles    = ""
 ImgFiles<1> = ".\images\test_dummy.png"     ; // 96DPI   (100%)//
 ImgFiles<3> = ".\images\test_dummy_150.png" ; // 144DPI  (150%)//
 ImgFiles<5> = ".\images\test_dummy_200.png" ; // 192DPI  (200%)//
 
 PrevImages = Set_Property( @Window : ".IMAGE", "FILENAMES", ImgFiles )
 

Image FILENAME property, WINDOW DPI property, WINDOW SCALEFACTOR property, Image SAVETOFILE method, Image SETHBITMAP method, Image SETIMAGE method, WINDOW SCALED event, Appendix J – System Icons, Appendix K – High-DPI Programming.

Some image formats, such the animated GIF format, hold more than one image "internally", and each image therein is referred to as a "frame". This property returns the number of frames contained in such an image.

If the IMAGE object has a valid image file loaded then this property is an integer value greater than 0. If a valid image is not loaded this property returns 0.

Note that this property is not the same as the COUNT property. Frames are intrinsic to the image format itself, whereas those defined by the COUNT property are "multiple images" combined in a file within a single frame; i.e. the COUNT indicates how many "slices" to chop the image into and the INDEX specifies which slice to display (In effect this emulates a multi-frame file format).

Most common image file formats do not support more than one frame.

The following example shows how to play an animated GIF file in a BITMAP control by using two events:

• A TIMER event for the BITMAP control that increments the FRAMEINDEX of the image:

 
Function TIMER( CtrlEntID, CtrlClassID )
   
   $Insert Logical 
 
   FrameCount = Get_Property( CtrlEntID : ".IMAGE", "FRAMECOUNT" )
   FrameIndex = Get_Property( CtrlEntID : ".IMAGE", "FRAMEINDEX" )
   
   FrameIndex += 1
   
   If ( FrameIndex > FrameCount ) Then
      FrameIndex = 1 
   End
   
   Call Set_Property_Only( CtrlEntID : ".IMAGE", "FRAMEINDEX", FrameIndex )
 
Return TRUE$ 
    

• A PUSHBUTTON CLICK event that starts the BITMAP TIMER event by setting its TIMER property to the same value as the image's FRAMEDELAY value:

 
Function CLICK( CtrlEntID, CtrlClassID )
   
   $Insert Logical 
 
   FrameDelay = Get_Property( CtrlEntID : ".IMAGE", "FRAMEDELAY" )
   
   Call Set_Property_Only( CtrlEntID : ".IMAGE", "TIMER", FrameDelay )
 
Return TRUE$ 
    

Image COUNT property, Image FRAMEDELAY property, Image FRAMEINDEX property, SYSTEM GETIMAGEINFO method.

Returns the "frame delay" for a multi-frame image. This is the number of milliseconds that should elapse between changing frames when the image is animated.

This property is an integer value. This value always returns 0 if the image is not a multi-frame image.

If the image has multiple frames then the property value always returns at least 90 milliseconds – this is a default value that matches the default on most browsers if the frame delay cannot be extracted from the image file for some reason.

See the FRAMECOUNT property for an example of how to use the FRAMEDELAY when animating a GIF image file.

Image FRAMECOUNT property, Image FRAMEINDEX property.

Specifies the frame to display in a multi-frame image.

This property is an integer value. It cannot be greater that the image's FRAMECOUNT value.

N/a.

See the FRAMECOUNT property for an example of how to use the FRAMEINDEX when animating a GIF image file.

Image FRAMECOUNT property, Image FRAMEDELAY property.

Specifies the image number to display in a multi-image file as described in the COUNT property. For example, the following image file would have a COUNT property of 6, and setting the INDEX property to 3 would display the "print setup" image:

This property is an integer value. It cannot be greater that the image's COUNT value.

When the INDEX property is changed the system uses the image file's total width divided by its COUNT property to find the width of a "sub-image". It then uses this value, along with the COUNT property, to calculate an offset into the image where the desired sub-image is located.

 
// Example - show the 3rd sub-image in a multi-image file, assuming that//
// it has a COUNT of 6...//
   
$Insert Logical 
 
Call Set_Property_Only( CtrlEntID : ".IMAGE", "INDEX", 3 )
    

Image COUNT property.

Specifies the point within the image (not the object) to begin drawing from.

This property is an @Fm-delimited array of coordinates:

<1> Left coordinate

<2> Top coordinate

This property can be used to scroll an image – e.g. repeatedly incrementing the Left coordinate will scroll the image to the left.

The OFFSET property only applies to images with the STYLE property set to "Clip".

 
 // Example - Set the OFFSET property of the image in the current control//
 // to begin drawing from 20,40//
 
 Call Set_Property( CtrlEntID : ".IMAGE", "OFFSET", 20 : @Fm : 40 ) 
    

Image ORIGIN property, IMAGE STYLE property.

Specifies the point within the object (not the image) to begin drawing from.

This property is an @Fm-delimited array of coordinates:

<1> Left coordinate

<2> Top coordinate

The ORIGIN property only applies to images with the STYLE property set to "Clip".

 
 // Example - Set the ORIGIN property of the image in the current control//
 // to begin drawing from 50,50//
 
 Call Set_Property( CtrlEntID : ".IMAGE", "ORIGIN", 50 : @Fm : 50 ) 
    

Image OFFSET property, IMAGE STYLE property.

Returns the dimension of the image in pixels (not DIPs).

An @Fm-delimited array of image information formatted as follows:

   <1> Image Width (pixels)
   <2> Image Height (pixels)

N/a.

 
 // Example - get the size of the image from the current form's IMAGE sub-object//
 ImgSize = Get_Property( @Window : ".IMAGE", "SIZE" )
    

SYSTEM GETIMAGEINFO method.

Specifies the basic method for how the image is drawn onto the object.

This property can be one of the following numeric values:

Equates constants for the Image STYLE property can be found in the PS_EQUATES insert record.

 
 // Example - Set the STYLE property of the image in the current control//
 // to "Tile"//
 $Insert PS_Equates
 
 Call Set_Property_Only( CtrlEntID : ".IMAGE", "STYLE", PS_IS_TILE$ ) 
    

Image ALIGN property, Image ORIGIN property.

Specifies the degree of transparency applied to an image when it is drawn onto an object.

This property is an integer value between 1 and 100 which represents the percentage of transparency applied to the image. A value of 0 means fully opaque, while a value of 100 means fully transparent (i.e. the image will not be drawn).

Be aware that the use of translucency does involve extra overhead when drawing objects because there are the extra steps of painting in the object's background and then blending it with image itself – while the PS attempts to mitigate this using cached bitmaps and double-buffering there will always be some impact.

 
 // Set the TRANSLUCENCY of the current form's IMAGE to 60%//
 
 PrevVal = Set_Property( @Window : ".IMAGE", "TRANSLUCENCY", 60 )
    

Common GUI Object TRANSLUCENCY property, WINDOW TRANSLUCENCY property.

These methods apply to most IMAGE objects unless noted otherwise.

Saves the current image to a file.

SuccessFlag = Exec_Method( ObjImageID, "SAVETOFILE", FileName )

Returns TRUE$ if the image was saved successfully, or FALSE$ otherwise.

This method uses the Bitmap Save method in the Windows GDI+ library. Please see the Microsoft website for more details.

 
 // Example – Save the contents of the current control's IMAGE object to a PNG file.// 
 
 FileName = "C:\Temp\TestImage.png"
 IsOK = Exec_Method( CtrlEntID : ".IMAGE", "SAVETOFILE", FileName )
                 

Image FILENAME property, Image FILENAMES property.

Loads an image using a Windows GDI BITMAP handle (HBITMAP).

SuccessFlag = Exec_Method( ObjImageID, "SETHBITMAP", hBitmap, hPalette, |

Options )

Returns TRUE$ if the image was loaded successfully, or FALSE$ otherwise.

This method copies the bitmap from the passed BITMAP handle when loading the image, so it is safe to release the HBITMAP after the method returns.

If an image is loaded via this method the object's FILENAME and FILENAMES properties will return the string "<HBITMAP>".

32-bit bitmaps produced with normal GDI functions (like the example below) should use the "Ignore alpha channel" option, otherwise they will appear transparent as GDI is not alpha channel aware. Equates constants for the Options parameter can be found in the PS_EQUATES insert record.

Automatic image selection for DPI scaling cannot be applied to the image when it is set using this method. Only the FILENAMES property supports this feature.

For more information on Windows GDI and BITMAP objects please consult the Microsoft website.

 
 // Example - draw into a bitmap and display it in the BMP_TEST control//
 Declare Function MSWin_GetDC, MSWin_ReleaseDC, MSWin_CreateCompatibleBitMap
 Declare Function MSWIn_CreateCompatibleDC, MSWin_SelectObject, MSWin_MoveToEx
 Declare Function MsWin_LineTo, MSWin_Rectangle, MSWin_Ellipse, MSWin_RoundRect
 $Insert PS_Equates
 $Insert Logical
 
 // Create a new bitmap in memory the same size as the current control//
 CtrlSize = Get_Property( @Window : ".BMP_TEST", "CLIENTSIZE" )
 ClientX  = CtrlSize<1>
 ClientY  = CtrlSize<2>
 
 // Create the bitmap in memory, compatible with the control //
 hwnd     = Get_Property( @Window : ".BMP_TEST", "HANDLE" )
 hdc      = MSWin_GetDC( Hwnd )
 hdcMem   = MSWIn_CreateCompatibleDC( hdc )
 hBitmap  = MSWin_CreateCompatibleBitMap( hdc, ClientX , ClientY )
 hBmpOrig = MSWin_SelectObject( hdcMem, hBitmap )
 
 // Done with this...//
 Call MSWin_ReleaseDC( hwnd, hdc )

 // Draw into the memory DC and therefore the bitmap//
 Left  = int( ClientX / 8 ); Top = int( ClientY / 8 )
 Right = 7 * Left; Bottom = 7 * Top
 Call MSWin_Rectangle( hdcMem, Left, Top, Right, Bottom )

 Call MSWin_MoveToEx( hdcMem, 0, 0, 0 );
 Call MsWin_LineTo( hdcMem, ClientX, ClientY );

 Call MSWin_MoveToEx( hdcMem, 0, ClientY, 0 );
 Call MsWin_LineTo( hdcMem, ClientX, 0 );

 Call MSWin_Ellipse( hdcMem, Left, Top, Right, Bottom )
                 
 Left  = int( ClientX / 4 ); Top = int( ClientY / 4 )
 Right = 3 * Left; Bottom = 3 * Top
 Call MSWin_RoundRect( hdcMem, Left, Top, Right, Bottom,      |
                       int( ClientX / 4 ), int( ClientY / 4 ) )
                   
 // Put the original bitmap back//
 Call MSWin_SelectObject( hdcMem, hBmpOrig  )
 
 // Set the new bitmap in the control's IMAGE sub-object (creates a copy)//
 IsOK = Exec_Method( @Window : ".BMP_TEST.IMAGE", "SETHBITMAP", |
                    hBitmap, "", PS_SBM_OPT_IGNOREALPHA$ )

 // Delete the bitmap//
 Call MSWin_DeleteDC( hDCMem )
 Call MSWin_DeleteObject( hBitMap )
 

return TRUE$

Image FILENAME property, Image FILENAMES property, Image SETIMAGE method.

Loads an image using an array of raw bytes.

SuccessFlag = Exec_Method( ObjImageID, "SETIMAGE", ImageBytes )

Returns TRUE$ if the image was loaded successfully, or FALSE$ otherwise.

The format of the image (PNG,JPG,BMP etc) is deduced from the passed array of bytes.

If an image is loaded via this method the object's FILENAME and FILENAMES properties will return the string "<memory>".

Automatic image selection for DPI scaling cannot be applied to the image when it is set using this method. Only the FILENAMES property supports this feature.

 
 // Example - Read a JPG file and use the contents to set the image in//
 // the current control//
 
 OSRead JPGBytes From "C:\Temp\MyImage.jpg" Then
    IsOK = Exec_Method( CtrlEntID : ".IMAGE", "SETIMAGE", JPGBytes )
 End
                 

Image FILENAME property, Image FILENAMES property, Image SETHBITMAP method.

Loads an image file and related properties into an image object using an OpenInsight repository entity ID.

SuccessFlag = Exec_Method( ObjImageID, "SETREPOSIMAGE", ReposID )

Returns TRUE$ if the image entity was loaded successfully, or FALSE$ otherwise. Error information is reported via the Get_Status stored procedure.

Image entities stored in the OpenInsight repository contain the following image object properties:

• FILENAMES
• COLORKEY
• COUNT

The SETREPOSIMAGE method uses the passed entity ID to access these properties and set them for the image object.

 
 // Example - load the RTI_IDE_DEFAULT_IMAGE PNG file into the current//
 // control's IMAGE sub-object//
 
 ReposID = @AppID<1> : "*IMAGE*PNG*RTI_IDE_DEFAULT_IMAGE"
 If Exec_Method( CtrlEntID : ".IMAGE", "SETREPOSIMAGE", ReposID ) Else
    Call Get_Status( ErrInfo )
 End
                 

COLORKEY property, COUNT property, FILENAMES property.