Text Pointers

Text pointers are floating labels with optional attached arrows and close buttons that point to items on screen, drawing the player's attention there. They are primarily intended for use in tutorial scripts. They have been extended to show streaming text in cutscenes in battle, using cutscene:show_custom_cutscene_subtitle.

Text pointer objects are created with text_pointer:new, configured, and then visually shown with text_pointer:show. Once shown, a text pointer may be hidden again by calling text_pointer:hide. Alternatively, the core object provides the function core:hide_all_text_pointers to hide all visible text pointers.

A great many configuration options exist for text pointers. To simplify configuration as much as possible, a number of syles have been provided, each of which sets a range of configuration options automatically. Styles can be set with text_pointer:set_style.

Loaded in Battle loaded in battle
Loaded in Campaign loaded in campaign
Loaded in Frontend loaded in frontend
Back to top

Creation

text_pointer:new(string name, [number x position], [number y position], [number length], [string display mode])
Creates a text_pointer object. Text pointers must be given a unique name, an x/y position, a pointer.

Parameters:

1

string

Name for the text pointer. Must be unique amongst text pointers.

2

number

optional, default value=0

X position. This is either the absolute position on-screen, or the position in 3D space if the pointer display mode is set to worldspace.

3

number

optional, default value=0

Y position. This is either the absolute position on-screen, or the position in 3D space if the pointer display mode is set to worldspace.

4

number

optional, default value=0

Length of the attached arrow pointer and line. Can be zero.

5

string

optional, default value="bottom"

Pointer display mode. Determines in what direction the arrow pointer appears relative to the pointer label. Supported values:

  • "top", the pointer line is drawn above the text label, pointing upwards.

  • "bottom", the pointer line is drawn below the text label, pointing downwards.

  • "left", the pointer line is drawn to the left of the text label, pointing to the left.

  • "right", the pointer line is drawn to the right of the text label, pointing to the right.

  • "worldspace", a special mode, whereby the text pointer appears in 3D space rather than 2D. In this case the pointer line appears below the text label.

  • "subtitle", a special mode, whereby the text pointer appears and behaves as a cutscene subtitle in the lower cinematic bar. x/y positions are disregarded in this case.

Returns:

  1. text_pointer

defined in ../working_data/script/_lib/lib_common_ui.lua, line 141

Back to top

Usage

Once an text_pointer object has been created with text_pointer:new, functions on it may be called in the form showed below.

Example - Specification:

<text_pointer_object>:<function_name>(<args>)

Example - Creation and Usage:

local tp_test = text_pointer:new(
    "test_pointer",
    400,
    300
)
tp_test:set_panel_width(400)        -- calling a function on the object once created
Back to top

Layout Configuration

text_pointer:set_layout_path(string path)
Sets the path to the folder that contains the component layout file. Default value is "UI/Common UI/".

Parameters:

1

string

path

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 256

text_pointer:set_layout(string path)
Sets the name of the layout to use for this text pointer. Default value is "text_pointer_text_only".

Parameters:

1

string

path

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 269

Back to top

Display Dimensions and Position

text_pointer:get_text_label()
Returns the text label uicomponent

Returns:

  1. uicomponent text label

defined in ../working_data/script/_lib/lib_common_ui.lua, line 294

text_pointer:set_pointer_width(number pointer width)
Sets the width of the pointer line. Default width is 5 pixels.

Parameters:

1

number

pointer width

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 302

text_pointer:set_panel_width(number panel width, [boolean shrink horizontally])
Sets the width of the text panel on-screen. The default width is set by the component layout.

Parameters:

1

number

Width of panel on-screen in pixels.

2

boolean

optional, default value=false

Shrink text horizontally if on one line.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 315

text_pointer:set_panel_width_to_screen(number difference, [boolean shrink horizontally])
Sets the width of the text panel on-screen to be the screen width minus a supplied numeric value.

Parameters:

1

number

Width of panel on-screen will be the screen width minus this value, in pixels.

2

boolean

optional, default value=false

Shrink text horizontally if on one line.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 330

text_pointer:set_worldspace_display_height(number display height)
Sets the height of the terrain at the pointer position. This only needs to be set if the pointer is displaying in worldspace. The script has no way of determining the height of the terrain at a position in worldspace, so it must be supplied here.
Without setting a height, a worldspace pointer will appear pointing to a height of 0, which will likely be beneath the terrain being pointed at.

Parameters:

1

number

display height

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 345

text_pointer:set_label_offset(number x offset, number y offset)
Without setting a label offset, the text label with be centred to the position being pointed at e.g. centred directly above it if the display mode is set to "bottom", centred to the left if the display mode is set to "right" etc. Set a label offset to move the label relative to this position.

Parameters:

1

number

x offset in pixels.

2

number

y offset in pixels.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 359

Back to top

Component Priority and Topmost

text_pointer:set_priority(number priority)
Sets the component priority of the text pointer. This determines what components the text pointer is drawn on top of, and what components it is drawn underneath.

Parameters:

1

number

priority

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 393

text_pointer:set_topmost([boolean topmost])
Sets the text pointer components to be topmost in the UI heirarchy.

Parameters:

1

boolean

optional, default value=true

topmost

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 406

Back to top

Pulse Highlighting

text_pointer:set_should_pulse([boolean pulse], [number pulse strength])
Sets the text pointer to pulse-highlight when it shows.

Parameters:

1

boolean

optional, default value=true

Set to true to enable pulsing.

2

number

optional, default value=nil

Pulse strength override. Supply a positive number here to modify the strength of the pulse. Default value is 5.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 433

Back to top

Streaming

text_pointer:set_stream_by_char(boolean should stream, [number stream duration])
Sets the text pointer to stream its text, and optionally sets the duration over which the text is to be streamed.

Parameters:

1

boolean

should stream

2

number

optional, default value=nil

stream duration

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 468

text_pointer:set_stream_duration(number stream duration)
Sets just the duration over which the text is to be streamed.

Parameters:

1

number

Stream duration in seconds

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 490

Back to top

Show and Hide Animations

text_pointer:set_panel_show_animation(string animation name)
Sets a different panel show animation. Any animation set here must be present on the panel component in the text pointer layout. Default is "show".

Parameters:

1

string

animation name

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 516

text_pointer:set_panel_hide_animation(string animation name)
Sets a different panel hide animation. Any animation set here must be present on the panel component in the text pointer layout. Default is "hide".

Parameters:

1

string

animation name

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 529

text_pointer:set_text_show_animation(string animation name)
Sets a text show animation. Any animation set here must be present on the line component in the text pointer layout.

Parameters:

1

string

animation name

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 542

text_pointer:set_text_hide_animation(string animation name)
Sets a text hide animation. Any animation set here must be present on the line component in the text pointer layout.

Parameters:

1

string

animation name

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 555

Back to top

State Overrides

text_pointer:set_panel_state_override(string state name)
Sets a different state for the text pointer panel. Any state set here must be present on the panel component in the text pointer layout.

Parameters:

1

string

state name

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 584

text_pointer:set_text_state_override(string state name)
Sets a different state for each line of text pointer panel. Any state set here must be present on the line component in the text pointer layout.

Parameters:

1

string

state name

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 597

Back to top

Close Button

text_pointer:set_show_close_button([boolean show button])
Shows a close button on the text pointer. By default a close button is not shown.

Parameters:

1

boolean

optional, default value=true

show button

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 622

text_pointer:set_hide_on_close_button_clicked([boolean close on click])
Hides the text pointer when the close button is clicked. By default, this is enabled, so the panel closes when the button is clicked.

Parameters:

1

boolean

optional, default value=true

close on click

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 634

text_pointer:set_close_button_callback(function callback, [number delay])
Set a callback to call when the close button is clicked. An optional delay may also be set. This also sets the close button to show.

Parameters:

1

function

Callback

2

number

optional, default value=0

Delay before calling callback, in s (campaign) or ms (battle/frontend)

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 646

text_pointer:set_close_button_component(string component name)
Overrides the component to use as the close button, by name.

Parameters:

1

string

component name

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 668

text_pointer:set_highlight_close_button(
  [delay, Period the text pointer should wait after being shown before the button highlight begins. This is specified in s in campaign]
)
Instructs the text pointer to highlight the close button when it shows, with an optional delay between the time of showing and the time the close button is highlighted. Immediately highlights the close button if the text pointer is already showing.

Parameters:

1

delay,

optional, default value=0

ms in battle or the frontend.

This is disregarded if the text pointer is already showing at the time this function is called.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 681

Back to top

Subtitle Mode

text_pointer:set_subtitle()
Sets the text pointer to position itself/behave as a cutscene subtitle, in the lower cinematic bar. This is akin to setting the pointer display mode to "subtitle" in text_pointer:new.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 718

text_pointer:set_subtitle_position(string position)

Sets a subtitle position string, which determines where the subtitle is displayed. This also sets the text pointer into subtitle mode. Valid subtitle modes are as follows:

  • bottom_subtitle_bar

  • top_subtitle_bar

  • top_centre

By default, subtitles show on the bottom subtitle bar unless set otherwise with this function.

Parameters:

1

string

position

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 725

Back to top

Relative Positioning to Text Pointer

text_pointer:set_position_offset_to_text_pointer(text_pointer text pointer, number x offset, number y offset)
Sets the position of this text pointer relative to another pointer. Calling this function overrides this text pointer's display mode, and causes it to display relative to another text pointer's position when shown.

Parameters:

1

text_pointer

Text pointer object to display relative to.

2

number

x offset in pixels from the other text pointer. This takes into account the other text pointer's size, so the two text pointers cannot overlap.

Supplying a value of 10 would mean a gap of 10 pixels between the two text pointers, with this text pointer on the right of the other, while a value of -10 would mean a gap of 10 pixels with this text pointer on the left.

3

number

y offset in pixels from the other text pointer. This takes into account the other text pointer's size, so the two text pointers cannot overlap.

Supplying a value of 10 would mean a gap of 10 pixels between the two text pointers, with this text pointer below the other (as a higher value of y means a position further down the screen), while a value of -10 would mean a gap of 10 pixels with this text pointer above the other.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 772

Back to top

Setting Component Text

text_pointer:add_component_text(string component name, string override text key, [exempt from streaming])
Sets the text of the specified component on the text pointer to that looked up by a supplied db text key. Use this method to show customised text on the text pointer.

Parameters:

1

string

Name of text component on the text pointer.

2

string

Name of text component on the text pointer.

3

exempt

optional, default value=false

Exempts this text from being streamed, if the text pointer is set to stream text.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 833

Back to top

Showing and Hiding

text_pointer:show([force display])
Makes the text pointer visible.

Parameters:

1

force

optional, default value=false

Forces the text pointer to display. This flag is only considered if the text pointer has been set to behave as a subtitle, in which case the text is always displayed and the player's subtitles preferences are ignored.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 874

text_pointer:hide([hide immediately])
Hides the text pointer. Supply true as a single argument to hide it immediately and prevent it from animating.

Parameters:

1

hide

optional, default value=false

immediately

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_common_ui.lua, line 1617

Back to top

Styles

text_pointer:set_style(string style)
Sets the style of this text pointer. Setting a style automatically sets a range of configuration options common to that style - inspect the script function to find out what exactly gets set or to add more styles. Current supported styles are:
  • standard

  • semitransparent_worldspace

  • semitransparent

  • semitransparent_large

  • semitransparent_2_sec_highlight

  • e3_subtitle_with_frame

  • subtitle_with_frame

  • top_centre_subtitle

    • Parameters:

    1

    string

    style

    Returns:

    1. nil

    defined in ../working_data/script/_lib/lib_common_ui.lua, line 1733

    Last updated 07/02/21 06:39:14