GetDisplayedElement Method
The GetDisplayedElement method extracts the specified element from a multi-image bitmap that is currently displayed as a field’s background. The element can be an image, sector, sprite icon, or embedded sprite. The element can be specified by index, explicit display coordinates, event location data, or mouse-cursor position.
The method returns specifications such as position and size (and optionally the image itself) of the element. These specifications are returned byref in a ChoiceDetail object. The image may also be returned directly as a BitmapObject if the extractimages parameter is set to TRUE. For events that have start and end loci—like a draw, lasso, move, or drag event—a second ChoiceDetail parameter is provided.
For sprite (BE_EMBED) settings, the returned bitmap is the sprite as it appears on the field’s background, with its transparent areas painted the transparent color rather than showing the field background onto which the sprite was painted.
This method has the following syntax:
BitmapObject = BitmapObject.GetDisplayedElement(selectiontype = integer,
hostfield = BitmapObject[, elementindex = integer]
[, x = integer, y = integer][, elementdetail = ChoiceDetail
[, secondelementdetail = ChoiceDetail]][, extractimages = integer]
[, ignoreclearregions = integer][, xleft = integer, ytop = integer])
This method has the following parameters:
selectiontype
(Required) Specifies the combination of selection type and element type defining the element to be returned.
Valid selection types are:
BE_INDEX
Provides details about the element (image, sector, icon, sprite) corresponding to the specified elementindex.
The elementindex must be specified except for image elements, which default to the index of the currently displayed image.
BE_FIELD
Provides details of the sprite or image sector, positioned relative to the hostfield’s topleft corner, at the pixel coordinates specified by the x and y, or xleft and ytop, parameters.
BE_EVENT
Provides details of the sprite or image sector, positioned where the event was triggered.
Note: ClickPoint and Select events are triggered on mouse-down; others are triggered on mouse-up. DragSegment is a special case: the returned elementdetails and bitmap relate to the mouse-down location, and the secondelementdetails relate to the mouse-up location.
BE_MOUSECURSOR
Provides details of the sprite or image sector, positioned under the mouse cursor.
Valid element types are:
BE_IMAGE
Specifies that the elementdetail parameter will be populated with details about the image specified by elementindex. If elementindex is unspecified or zero (0), the index of the currently-displayed image is used.
BE_SECTOR
Specifies that the elementdetail parameter will be populated with details about the elementindex- or position-specified sector of the currently displayed image.
BE_ICON
Specifies that the elementdetail parameter will be populated with details about the source icon specified by the elementindex parameter, or details about the source icon from which the position-specified sprite was derived.
BE_EMBED
Returns details of the sprite specified by elementindex or position.
A call to GetDisplayedElement specifying a selectiontype of (BE_FIELD+BE_EMBED) and a pair of xstart, ystart coordinates would identify and return the embedded sprite displayed at position xstart, ystart relative to the topleft of the specified field.
hostfield
(Required) Specifies the field that displays this bitmap, to which the method is being applied.
elementindex
Specifies the index of the image, sector, icon, or sprite being returned.
For BE_IMAGE (which assumes that BE_INDEX was specified), if the elementindex is unspecified or zero (0), the currently displayed image is used. For all other specifications involving BE_INDEX, the elementindex must be specified.
x
Specifies the x location in pixels of the point on the hostfield to examine.
Default: 0
y
Specifies the y location in pixels of the point on the hostfield to examine.
Default: 0
elementdetail
Specifies a ChoiceDetail object, passed byref, that will contain the specifications of the element when the method completes.
The specifications are laid out as follows:
• EnumValue holds the index of an element within the set of elements of that type. Therefore, if the elementindex parameter was specified, the EnumValue will contain the same value.
• EnumText holds a text string containing the elementindex and the pixel position and size of the element, together with either its iconindex and icontype (for BE_EMBED elements) or the imageindex (for BE_IMAGE or BE_SECTOR elements). The text string follows this format:
elementindex: x,y,width,height - iconindex(icontype)
elementindex: x,y,width,height - imageindex
• EnumDisplay holds an expanded version of this information, intended for possible display in a ChoiceField at edit or runtime.
• EnumBitmap holds the element BitmapObject if the extractimages parameter was set to TRUE.
• ToolTipText holds any text label associated with the BE_EMBED element. (Individual sprites can have their own text label or text identifier)
• EnumSubText[1] holds a StringObject containing the spritemap (full description) of the clicked sprite. For more information about how to access the contents of this map, see the SpriteDescriptor
Populate Method.
• ImageIndex holds either the index of the icon corresponding to the identified sprite (for BE_EMBED), or the image index of the field BgBitmap’s currently displayed image (for BE_IMAGE or BE_SECTOR)
Default: NULL
secondelementdetail
For those BE_EVENT events that have 2 loci (for example, DragSegment events), specifies a second ChoiceDetail object, passed byref, that will contain the specifications of the second identified element when the method completes,).
Default: NULL
extractimages
Specifies whether the element will be extracted as a bitmap object and returned.
Default: FALSE
ignoreclearregions
Specifies whether transparent areas of a sprite will be ignored (not considered as a “hit” location), for position-specified requests.
Default: TRUE (transparent areas will be ignored)
xleft
Specifies the x-location in OpenROAD units of the point on the hostfield to examine.
Default: 0
ytop
Specifies the y-location in OpenROAD units of the point on the hostfield to examine.
Default: 0
The method returns the specified bitmap element if successful, and null if not successful.
If the null return is due to a specification error (for example, a GetDisplayedElement call specifying an elementindex greater than the number of elements), the ErrorStatus of the field’s BgBitmap will be non-zero.
If the null return is due to a user action (for example, a GetDisplayedElement call specifying BE_EMBED+BE_MOUSECURSOR after the user clicked an area empty of sprites), the ErrorStatus of the field’s BgBitmap will be zero (0).
Example—GetDisplayedElement method:
This example involves a field with a BgPattern of FP_BITMAPCLEAR and a BgDisplayPolicy of BDP_BORDEREDSCALED, with a BgBitmap with 10 images and 5 icons, two of which are displayed as sprites (for more information about how to display sprites, see FormField UpdBackground method).
When the field is clicked, the following event code gets the details and image of the topmost clicked sprite:
mySpriteBitmap = myField.BgBitmap.GetDisplayedElement(
selectiontype=BE_EMBED + BE_MOUSECURSOR, extractimages=true,
elementdetail=Byref(elementdetail), hostfield=myField);
mySpriteDescriptor.Populate(string=elementdetail.EnumSubText[1]);
The following code gets the details and image of the background sector at the specified location, then obtains the x,y position of the sector on the field. In the example, tokens and coords are StringObject variables, pixeldensity is a float variable:
mySectorBitmap = myField.BgBitmap.GetDisplayedElement(
selectiontype=BE_SECTOR + BE_FIELD, extractimages=true,
elementdetail=Byref(elementdetail), hostfield=myField,
xleft=400, ytop=50);
tokens = ToString(text=elementdetail.EnumText).Split(delimiter=‘ ’, extactrows=3);
coords = tokens[2].Split(delimiter=‘,’, exactrows=3);
x = Int4(cords[1].Value);
y = Int4(cords[2].Value);
xleft = x / pixeldensity;
ytop = y / pixeldensity;
The following code gets the details and image of the fourth image in the background bitmap:
myImageBitmap = myField.BgBitmap.GetDisplayedElement(
selectiontype=BE_IMAGE + BE_INDEX, extractimages=true,
elementdetail=Byref(elementdetail), hostfield=myField,
elementindex=4);