BgDisplayPolicy Attribute
Data Type: integer
4GL Access: RW
The BgDisplayPolicy attribute controls the positioning and display of form field background images.
Valid values are:
BDP_DEFAULT
BDP_FIXED
BDP_RELATIVE
BDP_BORDEREDTILED
BDP_BORDEREDSCALED
BDP_CORNERED
BDP_BORDEREDTILED, BDP_BORDEREDSCALED, and BDP_CORNERED require the following companion settings:
• RequireRealField set to TRUE
• OutlineStyle set to a non-OS_STANDARD value
• OutlineWidth set to LW_NOLINE
Except for BDP_RELATIVE, all settings anchor the background image to the top left corner of the field.
Descriptions of system constant values and their numeric equivalents are listed in
BgDisplayPolicy Settings.
When the setting is BDP_RELATIVE, the background image is anchored relative to the closest parent field whose background is fixed. Parent field settings are evaluated regardless of whether they have a background image themselves. If neither the field nor its parents have a fixed setting, the image is anchored relative to the TopForm top left corner.
When the setting is BDP_FIXED, BDP_RELATIVE, or BDP_DEFAULT, the background image is painted at its exact size and tiled, if necessary, to fill the whole field.
When the setting is BDP_BORDEREDTILED, the image's border effect is preserved: the image corners are mapped to the field corners, the image edges are resized to fill the field by corner-to-corner tiling, and the center is resized to fill the remainder of the field by tiling.
When the setting is BDP_BORDEREDSCALED, the image's border effect is preserved: the image corners are mapped to the field corners (any transparency effects are honored), the image edges are resized to fill the field by corner-to-corner rescaling of the edges, and the center is resized to fill the remainder of the field by rescaling.
When the setting is BDP_CORNERED, the effect is identical to BDP_BORDEREDSCALED, except that the corners are modified to follow the cornerradius set for the image.
This value is typically set at runtime by a call to the field's UpdBackground method, passing the desired cornerradius (as the cornersize parameter). For more information about how cornerradius is used with BDP_BORDEREDSCALED and BDP_CORNERED, see the FormField.UpdBackground method (see
UpdBackground Method).
When BDP_BORDEREDTILED, BDP_BORDEREDSCALED, and BDP_CORNERED are set, the sizes of the image corners, edges, and center are defined in order of evaluation, as follows:
• A non-zero cornerradius defined for the image automatically defines the size of the image sectors. This value can define different sizes for each corner (for more information, see the FormField.UpdBackground method cornersize parameter (see
UpdBackground Method)). This is the only mechanism that BDP_CORNERED responds to.
• The presence of two horizontal and two vertical dividers of the appropriate color (RGB 254,255,255) in the image defines the image sectors.
• In the absence of dividers or a positive cornerradius, the corners, edges, and center are assumed to be of identical size.
For fields with a BgDisplayPolicy of BDP_BORDEREDTILED, BDP_BORDEREDSCALED, or BDP_CORNERED, the corner exteriors are always transparent if set to the background bitmap's transparency color. In the remaining background, pixels of this color are treated as transparent only if the field's BgPattern is FP_BITMAPCLEAR. The transparency color is set by the first corner of the bitmap that has one of the allowed transparency colors:
• Allowed transparency colors are those that combine pure red, green, or blue RGB values; that is, each RGB value must be 0 or 255:
All four corner pixels of the BgBitmap are examined, in turn, clockwise from top left, until one of these colors is encountered. This enables the top left pixel to be solid, if required.
• If a corner with one of these transparency colors is detected, all pixels in the exterior corners of the bitmap with this color are interpreted as transparent. If the field's BgPattern is FP_BITMAPCLEAR, all other pixels with this color are also interpreted as transparent.
Example 1
The following is a BgBitmap image:
This field's BgBitmap is:
• 3 by 3 pixels in size (the field itself may be much bigger).
• All top row pixels are RGB(255,128,255)—a solid color.
• All bottom row pixels are RGB(0,255,0)—a transparency color.
• The third corner (bottom right) defines the bitmap's transparency color to be RGB(0,255,0).
• The outer middle row pixels are RGB(0,0,0)—a transparency color, but it behaves as solid in this example because the first non-transparent corner is not this color.
• The center middle row pixel is RGB(0,255,0), the transparency color.
If the corner radius is set to 1 pixel, OpenROAD treats such a bitmap as comprising four corners of 1x1 pixels, four edges of 1x1 pixels, and a central area of 1x1 pixels. When displayed, the edges and the central area expand to fill whatever size the field is set to. For this example, assume that the BDP_CORNERED border width is 0 (BDP_CORNERED borders are non-transparent).
This definition produces the following transparency effects:
Example 2
If a field's BgBitmap has a foreground shape on a white background, RGB(255,255,255), the white background is automatically interpreted as transparent unless all four corners are recolored, perhaps to RGB(254,255,255):
• RGB(254,255,255) is visually indistinguishable from pure white (255,255,255).
• Such a bitmap still appears as a white background if the single pixels in all four corners are recolored to another non-solid color. (The entire background is white, except for the corner pixels, which are transparent.)
