UpdBackground Method
The UpdBackground method changes a field's background.
This method has the following syntax:
For all shape fields:
FormField.UpdBackground()
For all active fields:
FormField.UpdBackground(imageindex = integer, cornersize = integer,
opacity = float, spritemap = StringObject)
You need not use this method if you are changing the BgBitmap attribute explicitly to use a different BitmapObject with no special settings for the field background.
You only need to call this method if you are applying special parameters to an active field background, or loading a different image into the same BitmapObject already pointed to by the BgBitmap attribute, as in the following example:
field(personaldata.name).BgBitmap.FileHandle = 'c:\windows\honey.bmp';
field(personaldata.name).UpdBackground();
The special parameters apply only to fields that have BgDisplayPolicy (see
BgDisplayPolicy Attribute) set to one of the "outline" settings: BDP_BORDERED, BDP_BORDEREDSCALED, or BDP_CORNERED (see
BgDisplayPolicy Settings).
This method has the following parameters (active fields only):
imageindex
Specifies the index of the image to use in bitmaps that contain multiple images. An imageindex of 1 applies the topmost image in the bitmap, 2 applies the second image, and so on. An imageindex of 0 is treated as requesting the first image. No change takes place if the imageindex is out of range, and the bitmap’s errorstatus is set to a non-zero value.
The following example applies the second image in the bitmap as the field’s background:
field(personaldata.name).UpdBackground(imageindex=2);
OpenROAD examines the background bitmap for horizontal dividers of the special color RGB(253,0,255), which separate successive images within the bitmap. It then extracts and applies the image corresponding to the imageindex supplied.
cornersize
Specifies the size of the corners (or corner sectors) of the background bitmap being applied. The size is specified in pixels. The maximum size for any corner is 255. For BDP_CORNERED settings, the size is interpreted as the radius of the corner's curve; for BDP_BORDERED settings, the size is interpreted as the depth of each edge.
For BDP_CORNERED BgDisplayPolicy settings (see
BgDisplayPolicy Settings), the method treats the specified image as a rectangular image, detects the color and width of any border it may have (including simple two-tone borders), then computes and applies corners of the specified color, width, and radius when painting the background to display a field with rounded corners.
The following example produces a field with corners rounded to a radius of 11 pixels, based on the fifth image contained in the bitmap:
field(personaldata.name).UpdBackground(imageindex=5, cornersize=11);
It is possible with this setting to specify different roundings for different field corners by specifying a radius greater than 255. The radius will be interpreted as follows
Top left corner: Mod(radius/256**0,256)
Top right corner: Mod(radius/256**1,25)
Bottom right corner: Mod(radius/256**2,256)
Bottom left corner: Mod(radius/256**3,256)
The following example produces a field with the top corners rounded to a radius of 20 pixels and the bottom corners rectangular:
field(personaldata.name).BgDisplayPolicy = BDP_CORNERED;
field(personaldata.name).UpdBackground(cornersize=20 + 20 * 256 + 1 * 256**2 + 1 * 256**3);
For BDP_BORDERED or BDP_BORDEREDSCALED BgDisplayPolicy settings (see
BgDisplayPolicy Settings), the cornersize is used to define the corner, edge, and central areas of the bitmap when the background is being drawn.
For example, if the bitmap image is 20 pixels wide and high, then a cornersize of 5 defines each corner as 5x5 pixels, each edge as 10x5 pixels (10 = 20 – 2 * 5), and the central area as 10x10 pixels. If the field is 100 pixels wide and 17 pixels high, the displayed field will have:
• 5x5 corners identical to the bitmap's corners
• 90x5 horizontal edges, top and bottom, derived from the bitmap's edges either by scaling (BDP_BORDEREDSCALED) or tiling (BDP_BORDERED)
• 7x5 vertical edges, right and left, derived from the bitmap's edges
• 90x7 central area derived from the bitmap's central area
The following example produces such a display:
field(personaldata.name).BgDisplayPolicy = BDP_BORDEREDSCALED;
field(personaldata.name).UpdBackground(cornersize = 5);
To specify different sizes for different field corners using one of the BDP_BORDERED settings, specify a cornersize greater than 255. The value will be interpreted as follows:
• Thickness of left edge: Mod(cornersize/256**0,256)
• Thickness of top edge: Mod(cornersize/256**1,256)
• Thickness of right edge: Mod(cornersize/256**2,256)
• Thickness of bottom edge: Mod(cornersize/256**3,256)
opacity
Specifies the opacity of the field’s background. An opacity of 0.99 (or 1) displays the field with a solid (fully opaque) background. An opacity of 0.01 hides the field (makes it fully transparent). An opacity of 0 is treated as no setting: the field is displayed as solid. Opacity is only applied if the field’s BgDisplayPolicy is BDP_BORDERED, BDP_BORDEREDSCALED, or BDP_CORNERED (see
BgDisplayPolicy Attribute).
The following example produces a dimmed field:
field(personaldata.name).BgDisplayPolicy = BDP_BORDEREDSCALED;
field(personaldata.name).UpdBackground(opacity = 0.25);
spritemap
Specifies the pattern of embedded icons (sprites) to display over the field's background. Each displayed element is defined by a semicolon-delimited substring that always includes the source image index and the display location of the sprite, and may also include the response, opacity, scaling, and unique identifier of the sprite. Spritemaps are applied only if the field's BgDisplayPolicy is BDP_BORDERED or BDP_BORDEREDSCALED (see
BgDisplayPolicy Attribute).
OpenROAD examines the background bitmap for a horizontal divider of the special color RGB(252,0,255); the area beyond this divider contains the bitmap's set of icons, separated by horizontal and vertical dividers of color RGB(254,0,255). Each icon typically has an associated behavior (type), and may be used for several sprites in a display. (For example, a “chess pawn” icon would appear as 8 different sprites on a chessboard display.)
Five spritemap patterns are supported, defined by the string’s prefix:
<no prefix>
The spritemap string defines all the sprites to be displayed on the field’s background; any previously displayed sprites are replaced. The full bitmap is redrawn.
'+-'
The spritemap string contains exactly 2 settings, the first of which defines the sprite to be added, and the second of which defines the sprite to be removed. This setting (and the following two) is used for smooth minimum-redraw effects, such as traveling sprites.
'-'
The spritemap string contains exactly 1 setting, defining a sprite to be removed.
'+'
The spritemap string contains exactly 1 setting, defining a sprite to be added.
'='
The spritemap string defines all the sprites to be displayed at the next “no prefix” UpdBackground call. No change is made to the display at this point. This is typically used to synchronize settings or to prepare for a display switch.
Examples:
The following example sets up the white pieces (40x40 pixels each) on a 320x320-pixel chessboard field, whose BgBitmap contains the chessboard as the main image and the pieces as the attached iconset:
Settings.Value =
'1(101) 1,279;' + //Ra1
'2(102) 41,279;' + //Nb1
'3(103) 81,279;' + //Bc1
'4(104) 121,279;' + //Qd1
'5(105) 161,279;' + //Ke1
'3(103) 201,279;' + //Bf1
'2(102) 241,279;' + //Ng1
'1(101) 281,279;' + //Rh1
'6(106) 1,239;' + //(P)a2
'6(106) 41,239;' + //(P)b2
'6(106) 81,239;' + //(P)c2
'6(106) 121,239;' + //(P)d2
'6(106) 161,239;' + //(P)e2
'6(106) 201,239;' + //(P)f2
'6(106) 241,239;' + //(P)g2
'6(106) 281,239'); //(P)h2;
field(personaldata.name).UpdBackground(spritemap = settings);
The first number in each case is the index of the icon in the iconset (6 different white pieces), the number in parens defines the type (behavior) of the icon. In the example from which this was taken, the codes were used in the 4GL code to define which cursor to apply when the pieces were clicked. In other examples the type might be used by the 4GL developer to define what happens when the sprites are clicked: a help or a details popup is displayed, a list dropdown appears, and so on.
The following example moves one of the pawns:
field(personaldata.name).UpdBackground(spritemap =
'+-6(106) 161,219; 6(106) 161,279'); //Pe2-e4