ReplaceBitmap Method
The ReplaceBitmap method replaces an area of a bitmap with another bitmap.
ReplaceBitmap enables new bitmaps to be composed in the runtime application by applying replacement bitmaps, typically with areas of transparency (for example, icon shapes, faces, schematic shapes), onto standard "background" bitmaps.
By default, the replaced area is a rectangle. If the replacement rectangle overlaps the edges of the target bitmap, the replacement still takes place, but the bitmap's errorstatus is set to a non-zero value. If the clearcolor parameter is set, pixels of the specified color are not replaced.
The coordinates parameter enables irregular areas of the bitmap to be replaced. If the coordinates parameter is set, replacement depends on the setting of the xseed and yseed parameters:
• If xseed and yseed are unset, only the pixels specified in the coordinates list are replaced.
• If xseed and yseed are set, the coordinates are interpreted as a replacement boundary, and replacement exclusively takes place on whichever side of the boundary the xseed,yseed location falls (the boundary itself is included in any replacement).
• The replacement should be large enough to fill the bounded area; if it is not, the results will be logical but not necessarily what you had in mind.
Note: All coordinate values are applied relative to the replacement's topleft (the x,y location), not the target bitmap's location (0,0).
If the BitmapObject is attached to a FormField or a stored TaggedValue Item, using this in your program during development may change your frame's source definition. See BitmapObject Attributes and Methods Affecting the Frame Source (see
BitmapObject Class).
This method has the following syntax:
BitmapObject = BitmapObject.ReplaceBitmap(replacement = BitmapObject
[, x = integer, y = integer][, clearcolor = integer]
[, asnewobject = integer][, coordinates = Object]
[, xseed = integer][, yseed = integer]])
This method has the following parameters:
replacement
(Required) Specifies the replacement bitmap being applied to the main bitmap.
There is no default.
x
Specifies the x location in pixels of the replacement bitmap's topleft relative to the main bitmap.
Default: 1
y
Specifies the y location in pixels of the replacement bitmap's topleft relative to the main bitmap.
Default: 1
clearcolor
Specifies the color of those pixels in the replacement bitmap that must not be applied to the main bitmap. If undefined, all pixels are opaque.
asnewobject
Specifies whether to apply the changes to a copy of the main bitmap, rather than the main bitmap itself.
Default: FALSE
coordinates
Contains the x,y coordinates (as pixel positions) defining the replacement area. This enables irregular areas to be replaced.
The coordinates can be supplied as either a string object or a long byte object. If it is a string object, the string object's ClientData after the call will reference a long byte object to which a binary version of the coordinates in the string has been appended. This long byte object is suitable for use not only by ReplaceBitmap but also by
SetPixelColor Method and
GetPixelColor Method;
FillBitmap Method also provides coordinates in this form.
Coordinates supplied as a string must be in the form:
x,y [x,y]
String coordinates can be provided as partial sets, signaled by appending "+" to the end of the string. You can make repeated calls to ReplaceBitmap, passing the same string object with successive "+"-terminated segments of the coordinates, to build up the complete coordinate-set within the string's ClientData-referenced long byte object. This technique offers flexibility and a smaller memory footprint. Such "partial" calls do not involve any change to the bitmap. The following is an example of this technique, which defines the boundary of a square:
x = 20;
y = 20;
for i = 1 to 100 do
x = x + 1;
string.ConcatVarchar(text=varchar(x) + ',' + varchar(y) + ' ');
endfor;
string.ConcatVarchar(text='+');
mybitmap.ReplaceBitmap(replacement=myotherbitmap, coordinates=string);
lbyte = string.ClientData;
/* lbyte.Length is 100*4 + 4 */
string.Value = '';
for i = 1 to 100 do
y = y + 1;
string.ConcatVarchar(text=varchar(x) + ',' + varchar(y) + ' ');
endfor;
string.ConcatVarchar(text='+');
mybitmap.ReplaceBitmap(replacement=myotherbitmap, coordinates=string);
/* lbyte.Length is 200*4 + 4 */
string.Value = '';
for i = 1 to 100 do
x = x - 1;
string.ConcatVarchar(text=varchar(x) + ',' + varchar(y) + ' ');
endfor;
string.ConcatVarchar(text='+');
mybitmap.ReplaceBitmap(replacement=myotherbitmap, coordinates=string);
/* lbyte.Length is 300*4 + 4 */
string.Value = '';
for i = 1 to 100 do
y = y - 1;
string.ConcatVarchar(text=varchar(x) + ',' + varchar(y) + ' ');
endfor;
string.ConcatVarchar(text='+');
mybitmap.ReplaceBitmap(replacement=myotherbitmap, coordinates=string);
/*lbyte.Length is 400*4 + 4 */
mybitmap.ClientData = null;
The coordinates may define the entire set of pixels to be replaced, or the boundary enclosing or excluding the pixels to be replaced, depending on whether xseed and yseed are set. Continuing the previous example:
mybitmap.ReplaceBitmap(
replacement=myotherbitmap, x=1, y=1, coordinates=lbyte, xseed=30, yseed=30);
/* Replaces a 100x100 square of mybitmap, starting at 20x20, with the corresponding 100x100 square from myotherbitmap. If xseed and yseed were 1, it would apply the replacement outside the square. If xseed and yseed were unset, it would replace the outline of the square only. */
xseed
Specifies the x location of the "seed" point defining how coordinates are to be interpreted. If xseed and yseed are undefined, only the pixels defined with coordinates are replaced. Otherwise, replacement is applied to the area occupied by the seed and bounded by the coordinates.
yseed
Specifies the y location of the "seed" point defining how coordinates are to be interpreted. If xseed and yseed are undefined, only the pixels defined with coordinates are replaced. Otherwise, replacement is applied to the area occupied by the seed and bounded by the coordinates.
If successful, the method returns a version of the main bitmap with the replacement applied. If unsuccessful, it returns NULL. Unless asnewobject is set to TRUE, the modifications are applied to the host bitmap.