SpriteGrid

Developer documentation

Text tools

3 tools. Every change a tool makes is one undo step in SpriteGrid.

list_fontsFonts for textlooks only

The fonts text can be written in: SpriteGrid's own pixel fonts, the ones the user imported, and (with includeSystem) the computer's. Each says whether it's a pixel font and the size it was drawn for.

Parameters

includeSystemboolean

True to list the computer's fonts too (there can be hundreds; they aren't pixel fonts, mostly).

Returns
defaultstringrequired

The font text starts in when none is given.

fontslist of objectsrequired

The fonts, SpriteGrid's own first.

4 fields
namestringrequired

Its name: pass it as `font`.

sourcestringrequired

bundled (SpriteGrid's own pixel fonts), imported (the user's) or system (the computer's).

pixelFontbooleanrequired

True for a pixel font: it's exact at its native size, and scale makes it bigger in whole steps.

nativeSizeintegerrequired

The size in pixels it was drawn for, or null for a font that isn't a pixel font (or a system font not looked at yet).

add_textAdd text

Adds a text layer: words drawn in a font, in whole pixels (no smoothing), that stay editable (update_text changes them; the user can edit them with the Text tool). Give boxWidth to wrap the words in a box that wide. It goes above the selected layer unless above, below or inside says otherwise. Returns its id; changed is the area the text takes. Check it with render_preview. One undo step.

Parameters

textstringrequired

The words. \n starts a new line.

positionobjectrequired

Where the text goes: the top of its first line, and its left edge (alignment left), middle (center) or right edge (right). For text in a box, the box's top-left corner.

2 fields
xintegerrequired

Pixels from the left edge.

yintegerrequired

Pixels from the top edge.

fontstring

A font's name from list_fonts. A pixel font (SpriteGrid's own are) is drawn at its native size unless size is given; make it bigger with scale. Leave it out for the default font (list_fonts says which).

sizeinteger

The font's size in pixels, 1 to 512.

scaleinteger

How many pixels each of the font's pixels becomes, across and down: 1 to 16. Pixel fonts stay crisp scaled up.

colorstring

"#RRGGBB" or "#RRGGBBAA". Leave it out for the user's primary color.

alignmentstring

"left" (the default), "center" or "right".

letterSpacinginteger

Extra pixels (of the font's, so scaled too) between letters; negative draws them closer.

lineSpacinginteger

Extra pixels (of the font's) between lines.

boxWidthinteger

The width in pixels of a box to wrap the words in. Leave it out (or 0) for text that only breaks at \n.

namestring

The layer's name. Leave it out to name it after the text's first line.

abovestring

Put it just above this layer (id or exact name).

belowstring

Put it just below this layer.

insidestring

Put it at the top of this group.

documentstring

Which document: its id from get_status (like "doc-1"), its path, or its name. Leave it out for the one you're working on, or the one shown in SpriteGrid before you've worked on one.

expectedRevisioninteger

The document's revision when you looked at it: if the document has changed since (the user edited it, say), nothing is done and you're told so.

Returns
documentstringrequired

The document's id.

revisionintegerrequired

Its revision after the change.

summarystringrequired

What changed, in a line.

layerstring

The layer changed or made, if there was one.

changedobject

The rectangle of pixels that changed, if any did.

4 fields
xintegerrequired

Left edge, in pixels from the left of the canvas.

yintegerrequired

Top edge, in pixels from the top of the canvas.

widthintegerrequired

Width in pixels.

heightintegerrequired

Height in pixels.

pixelsChangedinteger

How many pixels changed.

slicestring

The slice changed or made, if there was one.

effectstring

The effect changed or added, if there was one.

tilestring

The tile changed or made, if there was one.

update_textChange text

Changes a text layer's words, font, size, scale, color, alignment, spacing, box, position or rotation: any of them, in one undo step. What you leave out stays as it is (describe_document shows a text layer's). Turned text turns around a point of its own (describe_document's turnsAround): fixed when it's first turned, it stays put as the words change, and moves with position. For outlines and shadows, add the outline and drop-shadow effects to the layer (add_effect).

Parameters

layerstring

Which layer: its id, or its exact name (describe_document lists them). Leave it out for the layer selected in SpriteGrid.

textstring

New words. \n starts a new line.

positionobject

A new place for its anchor (see add_text).

2 fields
xintegerrequired

Pixels from the left edge.

yintegerrequired

Pixels from the top edge.

fontstring

A font's name from list_fonts. A pixel font (SpriteGrid's own are) is drawn at its native size unless size is given; make it bigger with scale.

sizeinteger

The font's size in pixels, 1 to 512.

scaleinteger

1 to 16: how many pixels each of the font's pixels becomes.

colorstring

"#RRGGBB" or "#RRGGBBAA".

alignmentstring

"left", "center" or "right".

letterSpacinginteger

Extra pixels (of the font's) between letters.

lineSpacinginteger

Extra pixels (of the font's) between lines.

boxWidthinteger

The width of the box it wraps in, in pixels; 0 for no box.

rotationnumber

How far to turn it, in degrees clockwise; 0 to straighten it.

documentstring

Which document: its id from get_status (like "doc-1"), its path, or its name. Leave it out for the one you're working on, or the one shown in SpriteGrid before you've worked on one.

expectedRevisioninteger

The document's revision when you looked at it: if the document has changed since (the user edited it, say), nothing is done and you're told so.

Returns
documentstringrequired

The document's id.

revisionintegerrequired

Its revision after the change.

summarystringrequired

What changed, in a line.

layerstring

The layer changed or made, if there was one.

changedobject

The rectangle of pixels that changed, if any did.

4 fields
xintegerrequired

Left edge, in pixels from the left of the canvas.

yintegerrequired

Top edge, in pixels from the top of the canvas.

widthintegerrequired

Width in pixels.

heightintegerrequired

Height in pixels.

pixelsChangedinteger

How many pixels changed.

slicestring

The slice changed or made, if there was one.

effectstring

The effect changed or added, if there was one.

tilestring

The tile changed or made, if there was one.