Skip to content

Latest commit

 

History

History
349 lines (252 loc) · 7.69 KB

text_api.md

File metadata and controls

349 lines (252 loc) · 7.69 KB

druid.text API

at /druid/base/text.lua

Basic Druid text component. Text components by default have the text size adjusting.

Setup

Create text node with druid: text = druid:new_text(node_name, [initial_value], [text_adjust_type])

Notes

  • Text component by default have auto adjust text sizing. Text never will be bigger, than text node size, which you can setup in GUI scene.
  • Text pivot can be changed with text:set_pivot, and text will save their position inside their text size box
  • There are several text adjust types:
    • "downscale" - Change text's scale to fit in the text node size (default)
    • "trim" - Trim the text with postfix (default - "...") to fit in the text node size
    • "no_adjust" - No any adjust, like default Defold text node
    • "downscale_limited" - Change text's scale like downscale, but there is limit for text's scale
    • "scroll" - Change text's pivot to imitate scrolling in the text box. Use with stencil node for better effect.
    • "scale_then_scroll" - Combine two modes: first limited downscale, then scroll
    • "trim_left" - Trim the text with postfix (default - "...") to fit in the text node size
    • "scale_then_trim" - Combine two modes: first limited downscale, then trim
    • "scale_then_trim_left" - Combine two modes: first limited downscale, then trim left

Functions

Fields

init

text:init(node, [value], adjust_type)

The Text constructor

adjust_type:
    | "downscale"
    | "trim"
    | "no_adjust"
    | "downscale_limited"
    | "scroll"
    | "scale_then_scroll"
    | "trim_left"
    | "scale_then_trim"
    | "scale_then_trim_left"
  • Parameters:
    • node (string|node): Node name or GUI Text Node itself
    • [value] (string|nil): Initial text. Default value is node text from GUI scene. Default: nil
    • adjust_type ("downscale"|"downscale_limited"|"no_adjust"|"scale_then_scroll"|"scale_then_trim"...(+5)): Adjust type for text. By default is "downscale". Options: "downscale", "trim", "no_adjust", "downscale_limited", "scroll", "scale_then_scroll", "trim_left", "scale_then_trim", "scale_then_trim_left"

get_text_size

text:get_text_size([text])

Calculate text width with font with respect to trailing space

  • Parameters:

    • [text] (string|nil): The text to calculate the size of, if nil - use current text

  • Returns:

    • width (number): The text width
    • height (number): The text height

get_text_index_by_width

text:get_text_index_by_width(width)

Get chars count by width

  • Parameters:

    • width (number): The width to get the chars count of

  • Returns:

    • index (number): The chars count

set_to

text:set_to(set_to)

Set text to text field

  • Parameters:

    • set_to (string): Text for node

  • Returns:

    • self (druid.text): Current text instance

set_text

text:set_text([new_text])

  • Parameters:

    • [new_text] (any):

  • Returns:

    • `` (druid.text):

get_text

text:get_text()
  • Returns:
    • `` (unknown):

set_size

text:set_size(size)

Set text area size

  • Parameters:

    • size (vector3): The new text area size

  • Returns:

    • self (druid.text): Current text instance

set_color

text:set_color(color)

Set color

  • Parameters:

    • color (vector4): Color for node

  • Returns:

    • self (druid.text): Current text instance

set_alpha

text:set_alpha(alpha)

Set alpha

  • Parameters:

    • alpha (number): Alpha for node

  • Returns:

    • self (druid.text): Current text instance

set_scale

text:set_scale(scale)

Set scale

  • Parameters:

    • scale (vector3): Scale for node

  • Returns:

    • self (druid.text): Current text instance

set_pivot

text:set_pivot(pivot)

Set text pivot. Text will re-anchor inside text area

  • Parameters:

    • pivot (userdata): The gui.PIVOT_* constant

  • Returns:

    • self (druid.text): Current text instance

is_multiline

text:is_multiline()

Return true, if text with line break

  • Returns:
    • Is (boolean): text node with line break

set_text_adjust

text:set_text_adjust(adjust_type, [minimal_scale])

Set text adjust, refresh the current text visuals, if needed

adjust_type:
    | "downscale"
    | "trim"
    | "no_adjust"
    | "downscale_limited"
    | "scroll"
    | "scale_then_scroll"
    | "trim_left"
    | "scale_then_trim"
    | "scale_then_trim_left"

  • Parameters:

    • adjust_type ("downscale"|"downscale_limited"|"no_adjust"|"scale_then_scroll"|"scale_then_trim"...(+5)): The adjust type to set, values: "downscale", "trim", "no_adjust", "downscale_limited", "scroll", "scale_then_scroll", "trim_left", "scale_then_trim", "scale_then_trim_left"
    • [minimal_scale] (number|nil): To remove minimal scale, use text:set_minimal_scale(nil), if pass nil - not change minimal scale

  • Returns:

    • self (druid.text): Current text instance

set_minimal_scale

text:set_minimal_scale(minimal_scale)

Set minimal scale for "downscale_limited" or "scale_then_scroll" adjust types

  • Parameters:

    • minimal_scale (number): If pass nil - not use minimal scale

  • Returns:

    • self (druid.text): Current text instance

get_text_adjust

text:get_text_adjust()

Return current text adjust type

  • Returns:
    • adjust_type (string): The current text adjust type

Fields

  • node (node): The text node

  • on_set_text (event): fun(self: druid.text, text: string) The event triggered when the text is set

  • on_update_text_scale (event): fun(self: druid.text, scale: vector3, metrics: table) The event triggered when the text scale is updated

  • on_set_pivot (event): fun(self: druid.text, pivot: userdata) The event triggered when the text pivot is set

  • style (druid.text.style): The style of the text

  • start_pivot (userdata): The start pivot of the text

  • start_scale (vector3): The start scale of the text

  • scale (vector3): The current scale of the text

  • pos (unknown)

  • node_id (unknown)

  • start_size (unknown)

  • text_area (unknown)

  • adjust_type (string|"downscale"|"downscale_limited"|"no_adjust"|"scale_then_scroll"...(+6))

  • color (unknown)

  • last_value (unknown)

  • last_scale (vector3)