ui.Sprite¶

Overview¶

Decorative component that simply draws an image onto the screen.

This is mostly an extension of ui.SpriteData, with the only functionality besides what's provided by that and by Component being functionality to associate this component with an object, making it so the object's model is drawn instead of the normal component contents.

Warning

These components don't currently support segmented sprites, with the visualMargin property getting ignored.

Example¶

local sprite = ui.Sprite.new(parent)
sprite:SetSize(100, 50)
sprite.sprite = Plugin.resources.my_sprite
-- or
sprite.sprite = builtin_sprite_id_to_use
sprite.colour = Vector4.new(1.0, 0.0, 1.0, 1.0)

Enumerations¶

ui.ObjectQuantityDisplayMode¶

Enumeration identifying how the quantity of an associated object should be displayed on a sprite with an associated object.

Info

The font used for the quantity indicator is currently hardcoded.

Value	Description
NEVER	The quantity indicator is never displayed.
ALWAYS	The quantity indicator is always displayed.
MULTIPLE	The quantity indicator is displayed if there's more than one object in the stack.

Methods¶

Constructor¶

function ui.Sprite.new(parent : ui.ComponentCollection, categoryID : Int?, dynamicID : Int?) -> Sprite

Creates a new sprite component on the specified parent.

Warning

Creating a component can fail if there's already a component on that parent with the same category ID and dynamic ID, or if those are omitted and the application is unable to generate a valid ID for the component.

Parameter	Type	Description
parent	ui.ComponentCollection	Parent component to create this sprite component in.
categoryID	Int?	Category ID used to identify this component. Defaults to the parent's category ID if not specified.
dynamicID	Int?	Dynamic ID used to identify this component. Defaults to auto-incrementing from the parent's dynamic ID if not specified.

Returns	Description
Sprite	The newly created sprite component. The caller must set its layout and visual information afterwards.

SetAssociatedObject¶

function ui.Sprite:SetAssociatedObject(objectID : Int, quantity : Uint64?)

Associates an object with this component, making it use the object's name and optionally it's quantity as the displayed contents for this component.

Parameter	Type	Description
objectID	Int	Numeric ID for the object to associate with this component.
quantity	Uint64?	The quantity for the object to associate with this component.

AlignTo¶

function ui.Sprite:AlignTo(alignment : ui.AlignMode)
function ui.Sprite:AlignTo(horizontalAlignment : ui.AlignMode, verticalAlignment : ui.AlignMode)

Sets the alignment for this sprite.

Parameter	Type	Description
alignment	ui.AlignMode	The alignment to set as both horizontal and vertical alignments.
horizontalAlignment	ui.AlignMode	The desired horizontal alignment.
verticalAlignment	ui.AlignMode	The desired vertical alignment.

SetConfig¶

function ui.Sprite:SetConfig(config : ui.SpriteDataConfig)

Sets this Sprite's properties based on the provided config values.

Parameter	Type	Description
config	ui.SpriteDataConfig	The config to source the various properties from.

GetConfigCopy¶

function ui.Sprite:GetConfigCopy() -> ui.SpriteDataConfig

Returns a copy of this Sprite's config, allowing it to be used elsewhere.

Returns	Description
ui.SpriteDataConfig	Config containing a copy of all properties set on this Sprite object, excluding non-config properties (eg. `content`)

Properties¶

Name	Type	Description
associatedObjectID	Int	Numeric ID for the object associated with this component, or -1 if no associated object exists.
associatedObjectQuantity	Int	The quantity for the object associated with this component.
associatedObjectQuantityMode	ui.ObjectQuantityDisplayMode	Specifies when the label listing the quantity for the associated object should be displayed.
sprite	Int	RuntimeSprite
spriteID	Int	Gets the built-in sprite ID to draw.
runtimeSprite	RuntimeSprite	Gets the current runtime sprite to draw or nil if it doesn't exist.
visualMargins	ui.Margin	(Modifiable Contents) Offsets used to split this sprite's graphics into multiple segments for drawing.
outlineWidth	Uint8	Thickness of the sprite's outline. Only used when the containing component is associated with an object.
rotationDegrees	Float	Rotation of this sprite in degrees.
rotationRadians	Float	Rotation of this sprite in radians.
isFlippedHorizontally	Bool	Flag indicating whether or not this sprite is drawn mirrored horizontally.
isFlippedVertical	Bool	Flag indicating whether or not this sprite is drawn mirrored vertical.
isTiling	Bool	Flag indicating whether or not this sprite uses tiled visuals.
shadowColour	Vector4	Colour used when drawing this sprite's shadow. If alpha is 0, no shadow will be drawn.
shadowRGBA	Uint	Hex-encoded red/green/blue/alpha colour code used when drawing this sprite. If alpha is 0, no shadow will be drawn.