Image
Object List Hierarchy Next Object
Definition:
A graphical control that in addition to having all the functionality of a
Drawable, can be used to display a Bitmap, through the Picture property.
Icon: 
Added Features:
The following tables list and describe the properties, methods, and events
added by Image.
Properties Use to...
AutoInitCropRect Control whether or not the CropRect is automatically configured to match the
Bitmap in the picture property.
CropXOffset Set the left edge of the visible portion of the Bitmap.
CropYOffset Set the top edge of the visible portion of the Bitmap.
CropXSize Set the width of the visible portion of the Bitmap (must be>=1).
CropYSize Set the height of the visible portion of the Bitmap (must be >=1).
Picture Reference a Bitmap.
ResizeMode Determine how the CropRect and Scale change when the control is resized.
ScaleX Set the CropRect according to a desired scale (must be > 0).
ScaleY Set the CropRect according to a desired scale (must be > 0).
ScrollBars Specify whether an image has horizontal, vertical, or both horizontal and
vertical scroll bars.
Methods Use to...
DetailedEdit Brings up a form for providing additional information when an object is double
clicked in the Property Editor or a control on a form is double clicked while
the Form Editor is on.
InitCropRect Initialize the CropRect.
PropertyEdit Bring up an OpenDialog when the FileName property is double clicked.
Events Use to...
Change Indicate that the contents of a control have changed and initiates some
action.
Copied Features:
Properties 
Methods 
Events
Details:
An Image control can be used just like a Drawable. Image, however, has an
additional property called the Picture property. The Image displays the given
Bitmap according to the settings of the CropRect properties (CropXOffset,
CropYOffset, CropXSize, CropYSize). The CropRect defines the portion of the Bitmap to
display in the Image control. The CropRect components are all measured in pixels.
The rule used for displaying the Bitmap is to take the area of the Bitmap
defined by the CropRect and “fit” it into the Image control. That is, to stretch or shrink the CropRect as
appropriate so that the entire CropRect is visible in the Image control. If the
CropRect is bigger than the designated space in the Image control, the Bitmap will
appear to have shrunk to fit in the area available. If the CropRect is smaller
than the available space in the Image control, the Bitmap will expand (zoom)
to fit in the area available.
By using the ScrollBar property, the control can be used to “Pan” the Bitmap to see the parts that do not fit in the viewable area.
To view the entire Bitmap in the Image control, set the following:
Image1.CropXOffset = 0
Image1.CropYOffset = 0
Image1.CropXSize = Image1.Picture.Width
Image1.CropYSize = Image1.Picture.Height
If the Image control is bigger than the Bitmap, the Bitmap will expand to fill
the available space. Conversely, if the Image control is smaller than the
Bitmap, the Bitmap will appear smaller than normal size.
The ScaleX and ScaleY properties can be used to show the Bitmap at a given size, when set they
affect CropXSize and CropYSize as follows:
Image1.CropXSize = Image1.Width / Image1.ScaleX
Image1.CropYSize = Image1.Height / Image1.ScaleY
If ScaleX is given as 1.0, the CropXSize will be equal to the width of the
Image control. This will have the effect of showing the Bitmap at 1-to-1 size. he
same applies to the ScaleY property with respect to CropYSize and Height.
If ScaleX is given as 2.0, the CropXSize will be equal to one-half of the
Image control's width, forcing the Bitmap to stretch to two-times its normal size
when it fills the Image control area.
ScaleX and ScaleY are affected by setting the CropXSize and CropYSize properties as follows:
Image1.ScaleX = Image1.Width / Image1.CropXSize
Image1.ScaleY = Image1.Height / Image1.CropYSize
If the ResizeMode is “Clip”, the CropXSize and CropYSize properties are changed proportionally with how
the Width and Height of the Image control change. The ScaleX and ScaleY
properties are unchanged. For example, if the Width of the Image control gets twice as
big, the CropXSize will be multiplied by two, having no net effect on ScaleX.
If the ResizeMode is “Fit,” the CropXSize and CropYSize properties are not changed regardless of how the
Width and Height of the Image control changes. What does change, however, is
the ScaleX and ScaleY properties to reflect the new relationships of CropXSize
vs. Width and CropYSize vs. Height. For example, if the Width of the Image
control gets twice as wide, CropXSize stays the same, making ScaleX twice what it was.
By setting the ResizeMode property you are essentially declaring which of the
two measurements is the most important, either the CropRect (CropXSize,
CropYSize) or the Scales (ScaleX, ScaleY). If the CropRect is the most important,
meaning it shouldn't change unless it is set explicity, use ResizeMode="Fit." If
it is the Scales that are important, use ResizeMode="Clip."
For example, for a PictureClip application, where the bitmap is an array of
same-sized icons. Set the properties like this:
ResizeMode = "Fit"
CropXOffset = 0
CropYOffset = 0
CropXSize = 32 ' Width of each sub-bitmap
CropYSize = 32 ' Heigh of each sub-bitmap
When CropXOffset and CropYOffset are changed (in 32x32 increments) the
sub-bitmap at that location will be shown. Note that the ViewRect (the size of the
Image control) should be appropriate for the scale that the sub-bitmaps are to be
drawn at. If the ViewRect has Width and Height of 32 pixels, then the
sub-bitmaps will draw at 1:1 size.
If the CropRect includes areas that would be considered off the Bitmap area,
the missing area will appear as a border surrounding the Bitmap when it is
displayed in the Image control. For example, if the Bitmap is 200x200 and the
CropRect=(0,0,300,200), the width of the CropRect exceeds the available area of the
Bitmap. The missing area appears as blank space when the Bitmap is displayed.
If you want the Bitmap to have a border when displayed, the CropRect can be
set to: (-50, -50, Bitmap.Width+100, Bitmap.Height+100), as shown below:
Image1.CropXOffset = -50
Image1.CropYOffset = -50
Image1.CropXSize = Image1.Picture.Width + 100
Image1.CropYSize = Image1.Picture.Height + 100
This will have the effect of placing a 50 pixel border around the Bitmap.