File builtin/vn/text.lua

text.lua Provides the 'built-in' VN text functions.

Functions

appendText (str) Appends text to the main textbox
appendTextLine (string) Appends a new line of text to the main textbox
appendTextLog (string, newPage) Appends text to the textlog, but not the text state
clearText () Clears the current text of the main textbox
createStyle (s) Creates a new TextStyle object from the given table
createStyledText (text, style) Creates a new StyledText object from the given string and TextStyle
customTextBox (mode, t, baseFunc) Utility function for creating a standard text box.
extendStyle (s, e) Creates a new TextStyle object, overriding attributes in s with those in e
getCurrentStyle () Returns the top of the current style state.
getTextLayer (mode) Returns the current text layer
getTextLayerConstructor (mode) Returns the current constructor function for the specified text mode
getTextLayerDrawable (name) Returns a named drawable from the current text layer, or nil if a drawable with that name doesn't (yet) exist.
paragraph.append (string) Gets called during execution of a text line to add pieces of text between commands.
paragraph.finish () Gets called at the end of each text line
paragraph.start (filename, lineNum) Gets called at the beginning of each text line.
paragraph.stringify (word) Gets called during execution of a text line to replace words starting with a dollar sign.
popStyle () Pops the top entry from the style stack.
pushStyle () Adds a new entry to the top of the style stack that's a copy of getCurrentStyle.
registerSpeaker (id, ...) Registers a paragraph.stringifier function to convert $variables inside text to a call to sayLine.
registerTextTagHandler (tag, openFunc, closeFunc) Registers text tag handler functions (open/close) for a specific text tag
say (name, textStyle, nameStyle) Changes the name of the person currently speaking
sayLine (...) Changes the name of the person currently speaking.
setTextLayerConstructor (mode, func) The text layer constructor gets called when a new text layer is created.
setTextModeADV () Changes the text mode to bottom-aligned textbox mode
setTextModeNVL () Changes the text mode to full-screen textbox mode
style (s) Changes the current style for the text and appendText functions.
Usage: text text text [style{color=0xFFFF0000}] text text
For a list of all TextStyle properties (besides color), see: createStyle
text (str) Sets the current text of the main textbox
textLog () Runs the textLog mode
textSpeed (s) Sets the text speed to the default speed multiplied by the specified factor.
textoff (...) Fades out the main textbox
texton (...) Fades in the main textbox
waitForTextVisible (textDrawable) Waits until all characters in a text drawable have become visible


Functions

appendText (str)
Appends text to the main textbox

Parameters:

  • str: The text to append (may be either a string, or a StyledText object)
appendTextLine (string)
Appends a new line of text to the main textbox

Parameters:

  • string: The text to append
appendTextLog (string, newPage)
Appends text to the textlog, but not the text state

Parameters:

  • string: The text to append
  • newPage: If true, starts a new page before appending the text to the text log.
clearText ()
Clears the current text of the main textbox
createStyle (s)
Creates a new TextStyle object from the given table

Parameters:

  • s: A table with attribute/value pairs for the new TextStyle
    List of TextStyle properties:
    • fontName The filename (without the .ttf) of the font to use
    • fontStyle "plain", "bold", "italic" or "bolditalic"
    • fontSize Determines the text size
    • anchor Controls text alignment, corresponds to numpad directions (4=left, 6=right, 7=top left)
    • color Text ARGB color packed into a single integer (red=0xFFFF0000, green=0xFF00FF00, blue=0xFF0000FF, etc)
    • underline Set to true to make the text underlined
    • outlineSize Thickness of the text outline (stroke)
    • outlineColor Outline ARGB color packed into a single integer (white=0xFFFFFFFF, black=0xFF000000, etc)
    • shadowColor Shadow ARGB color packed into a single integer (50% black=0x80000000, etc)
    • shadowDx Shadow x-offset
    • shadowDy Shadow y-offset

Return value:

    A newly condtructed TextStyle object, or nil in the case of an error.
createStyledText (text, style)
Creates a new StyledText object from the given string and TextStyle

Parameters:

  • text: The text part of the StyledText
  • style: The base style for the StyledText

Return value:

    A new StyledText object
customTextBox (mode, t, baseFunc)
Utility function for creating a standard text box.

Parameters:

  • mode:
  • t:
  • baseFunc:
extendStyle (s, e)
Creates a new TextStyle object, overriding attributes in s with those in e

Parameters:

  • s: An existing TextStyle object
  • e: A table with attribute/value pairs for the new TextStyle

Return value:

    A newly condtructed TextStyle object, or nil in the case of an error.
getCurrentStyle ()
Returns the top of the current style state. The style stack can be manipulated with pushStyle, popStyle, style.
getTextLayer (mode)
Returns the current text layer

Parameters:

  • mode:
getTextLayerConstructor (mode)
Returns the current constructor function for the specified text mode

Parameters:

  • mode: The text mode to get the constructor for

Return value:

    The constructor function

See also:

getTextLayerDrawable (name)
Returns a named drawable from the current text layer, or nil if a drawable with that name doesn't (yet) exist.

Parameters:

  • name:
paragraph.append (string)
Gets called during execution of a text line to add pieces of text between commands.

Parameters:

  • string: The text to append
paragraph.finish ()
Gets called at the end of each text line
paragraph.start (filename, lineNum)
Gets called at the beginning of each text line.

Parameters:

  • filename: The filename in which the paragraph resides
  • lineNum: The zero-based text line index of the paragraph
paragraph.stringify (word)
Gets called during execution of a text line to replace words starting with a dollar sign. If a handler function is registered for the word in the paragraph.stringifiers table, that function is evaluated. Otherwise, if word is a valid variable in the local context, its value is converted to a string and appended to the current paragraph.

Parameters:

  • word: The characters following the dollar sign
popStyle ()
Pops the top entry from the style stack.
pushStyle ()
Adds a new entry to the top of the style stack that's a copy of getCurrentStyle.
registerSpeaker (id, ...)
Registers a paragraph.stringifier function to convert $variables inside text to a call to sayLine. In addition, a global say_XXX function is created that calls the say function to change the active speaker. Example: registerSpeaker("bal", "Balthasar") $bal This line is now said with my name, Balthasar.

Parameters:

  • id: The value of the text after the $-sign that triggers the say function.
  • ...:
registerTextTagHandler (tag, openFunc, closeFunc)
Registers text tag handler functions (open/close) for a specific text tag

Parameters:

  • tag:
  • openFunc:
  • closeFunc:
say (name, textStyle, nameStyle)
Changes the name of the person currently speaking

Parameters:

  • name:
  • textStyle:
  • nameStyle:
sayLine (...)
Changes the name of the person currently speaking. Resets the speaker to default at the end of the paragraph.

Parameters:

  • ...:

See also:

setTextLayerConstructor (mode, func)
The text layer constructor gets called when a new text layer is created. It should create the base drawables and return them in a table.

Parameters:

  • mode: The text mode this constructor is for
  • func: The constructor function to use

Return value:

    A table with the drawables created for the layer. Some table keys have special meanings:
    • text: The main text box. Any key starting with "text" is considered to be part of the main text box (if you use "textBackground" as a key, that drawable will appear/disappear together with the main textbox).
    • nameText: An optional secondary text box to hold the speaking character's name. As with "text", all keys starting with "nameText" are considered part of the nameTextBox.
    • cursor: An optional click-to-continue cursor
setTextModeADV ()
Changes the text mode to bottom-aligned textbox mode
setTextModeNVL ()
Changes the text mode to full-screen textbox mode
style (s)
Changes the current style for the text and appendText functions.
Usage: text text text [style{color=0xFFFF0000}] text text
For a list of all TextStyle properties (besides color), see: createStyle

Parameters:

  • s:

See also:

text (str)
Sets the current text of the main textbox

Parameters:

  • str: The new text (may be either a string, or a StyledText object)
textLog ()
Runs the textLog mode
textSpeed (s)
Sets the text speed to the default speed multiplied by the specified factor. Resets at the end of a paragraph, when changing text modes or by calling the textSpeed function without any arguments.

Parameters:

  • s: The number to multiply the default text speed by
textoff (...)
Fades out the main textbox

Parameters:

  • ...:
texton (...)
Fades in the main textbox

Parameters:

  • ...:
waitForTextVisible (textDrawable)
Waits until all characters in a text drawable have become visible

Parameters:

  • textDrawable: An optional text drawable to wait for. This function waits on the main text box if this parameter is nil or unspecified.

Valid XHTML 1.0!