Language Reference Guide : System Classes : SpriteDescriptor Class
 
Share this page          
SpriteDescriptor Class
The SpriteDescriptor class defines the specification of a sprite—an image embedded in a field background.
You can also use this class to define the specification of a field background sector, for use when defining the location of sprites on that background. In this context a sector is an “empty sprite,” background rather than embedded, defining a significant area of a field’s background.
You can declare variables of type SpriteDescriptor anywhere in the application for your purposes; additionally there is a global variable CurSpriteDescriptor available for use. If you have an existing variable of that name, use core!CurSpriteDescriptor to distinguish the global SpriteDescriptor variable.
Each descriptor specifies the detailed position, size, shape, and identity of a single sprite or sector; the set of all descriptors can then be applied to a field as a spritemap or sectormap created using the SpriteDescriptor SpriteMap method. A sectormap maps the sectors belonging to a displayed field; a spritemap maps the sprites displayed onto a field, sometimes in terms of the sectors. Almost all attributes of the class are relevant to both sectors and sprites.
Note:  A spritemap or sectormap applied to a field will only affect the display if that field is displaying its BgBitmap and using a “bdp-enabled” BgDisplayPolicy setting, either BDP_CORNERED, BDP_BORDEREDSCALED, OR BDP_BORDEREDTILED.
Typically you set the attributes of a SpriteDescriptor by simple assignment: the Object SetAttribute method is useful for this. For example:
CurSpriteDescriptor.SetAttribute( spritesourceindex=1, x=1, y=1);
This code example shows the minimum specification allowed for sprites: SpriteSourceIndex, X, and Y must always be specified; any other SpriteDescriptor attributes may be null (unset).
The SpriteSourceIndex identifies which image in the BgBitmap’s spriteset is being used for the displayed sprite (which may be resized, reoriented, or rendered translucent or transparent when displayed, depending on the other SpriteDescriptor attributes that you set).
Certain SpriteSourceindex values have special meaning. In a spritemap, a value of 0 treats the whole field as a sprite. Thus the following code enables the end user to drag a field in show-contents-while-dragging style (normal field drag involves a “ghost” rectangle, and the contents don’t move until the drag is done):
CurSpriteDescriptor.SetAttribute( spritesourceindex=0, response=RSP_DRAG, x=1, y=1);
SDset[1] = CurSpriteDescriptor;
CurSpriteDescriptor.ApplySpriteMap( targetfield=myField, descriptors=SDset);
A special case of this is where the frame has no titlebar. In this case, dragging the field actually drags the frame, allowing a SubForm (for instance) to substitute for the titlebar. The following code would achieve this:
curframe.SetAttribute( IsBordered=FALSE, istitled=FALSE);
curframe.MainbarTop.InsertRow(rownumber=1);
sub = SubForm.Create();
sub.SetAttribute( xleft=1, height=229, sizetofit=STF_FRAMEHORIZONTAL, parentfield=curframe.MainbarTop[1]);
 
CurSpriteDescriptor.SetAttribute( spritesourceindex=0, response=RSP_DRAG, x=1, y=1);
SDset[1] = CurSpriteDescriptor;
CurSpriteDescriptor.ApplySpriteMap( targetfield=sub, descriptors=SDset);
In a sectormap, a SpriteSourceIndex of 0 has no meaning. But an index of 1 means that sector is rectangular, whereas an index of 2 or more means the sector has the shape of the spriteset image with that index. This can be useful when defining responsive regions of a map, for example, where counties lie within countries, and towns within counties, and regions are irregular in shape. Thus, if the second image in the spriteset was a circular image and the third was a diamond-shaped image, the following code would define a sectormap for the field’s background that had three overlaid sectors: one rectangular, one circular, and one diamond-shaped:
CurSpriteDescriptor.SetAttribute( spritesourceindex=1, x=1, y=1, width=50, height=50);
SDset[1] = CurSpriteDescriptor.Duplicate();
CurSpriteDescriptor.SetAttribute( spritesourceindex=2, x=1, y=1, width=50, height=50);
SDset[2] = CurSpriteDescriptor.Duplicate();
CurSpriteDescriptor.SetAttribute( spritesourceindex=3, x=1, y=1, width=50, height=50);
SDset[3] = CurSpriteDescriptor.Duplicate();
CurSpriteDescriptor.ApplySectorMap( targetfield=myField, descriptors=SDset);
A SpriteSource image can be the source for more than one sprite on the same field background if several SpriteDescriptor specifications are being applied in combination.
Inherits From
UserObject Class
Inherited By
None
Attributes
Angle
DescriptorString
Flags
Flip
Gravity
Height
HeightUnit
Name
Opacity
PropertyString
Response
Sector
SpriteIndex
SpriteSource
SpriteSourceIndex
Width
WidthUnit
X
XUnit
Y
YUnit
Methods
ApplySectorMap
ApplySpriteMap
SpriteImage
SpriteKey
SpriteMap
WhichSector
WhichSprite