Language Reference Guide : System Classes : BitmapObject Class : Elements Method
 
Share this page          
Elements Method
The Elements method obtains the set of all elements of a specified type contained in a composite BitmapObject. The elements can be images, sectors, or sprite source images.
The elements’ position and size are returned byref as an array of ChoiceDetail Class. If the extractimages parameter is set to TRUE, the ChoiceDetail objects include bitmaps of the elements, and these bitmap objects are also returned directly as an array of BitmapObject.
This method has the following syntax:
array of BitmapObject = BitmapObject.Elements(type = integer,
          imageindex = integer, elementdetails = array of ChoiceDetail,
          extractimages = integer)
This method has the following parameters:
type
Specifies the type of element to be returned. Valid element types are:
BE_IMAGE
Provides the set of alternative images that this BitmapObject contains.
BE_SECTOR
Provides the set of 9 sectors into which the imageindex-specified image is parsed for BDP_BORDEREDxxx backgrounds.
BE_ICON
Provides the set of sprite source images that this BitmapObject contains.
Default: BE_IMAGE
For more information about the settings for this parameter, see Element Type Settings for BitmapObject.
imageindex
Specifies the index of the alternative image to which the elements belong. This applies only where the type is BE_SECTOR.
Default: 1
elementdetails
Specifies a ChoiceDetail array, passed byref, that will contain the specifications of the elements 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 being returned.
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.
ImageIndex holds the passed ImageIndex. If no imageindex was passed, it is set to the current imageindex setting of that BitmapObject.
Default: NULL
extractimages
Specifies whether the elements will be extracted as BitmapObjects.
Default: FALSE
The method returns an array of the specified bitmap elements if extractimages is TRUE and the method is successful; otherwise it returns NULL. If the null return is due to a specification error, the ErrorStatus of the field’s BgBitmap is non-zero.
Example—Elements method:
This example involves a bitmap object whose bitmap contains 10 alternative images and 5 sprite source-icons.
The following code extracts the set of 10 alternative images as an array of bitmap objects:
imageBitmaps = myCompositeBitmap. Elements(
    type=BE_IMAGE, extractimages=TRUE);
The following code extracts the 9 sectors of the fourth alternative image as bitmap objects, together with position and size details for each of them:
sectorBitmaps = myCompositeBitmap. Elements(
    type=BE_SECTOR, extractimages=TRUE,
    elementdetails=Byref(elementdetails),imageindex=4);
The following code extracts the position and size details of the 5 source images from the original bitmap, but does not extract them as bitmap objects. It then gets the height and width of the third icon. In this example, tokens and coords are StringObject variables:
myCompositeBitmap. Elements(
    type=BE_ICON, elementdetails=Byref(elementdetails));
tokens = ToString(text=elementdetails[4].EnumText).Split(delimiter=' ', exactrows=3);
coords = tokens[2].Split(delimiter=',', exactrows=4);
width = Int4(cords[3].Value);
height = Int4(cords[4].Value);