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.

Typically you set the attributes of a SpriteDescriptor by simple assignment: the Object SetAttribute method is useful for this. For example:

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):

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:

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:

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.