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, [string display mode], [number length], [number x position], [number y position])

Creates a text_pointer object pointing to a supplied position on the screen.

Parameters:

1

string

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

2

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.

3

number

optional, default value=0

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

4

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.

5

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.

Returns:

  1. text_pointer

defined in ../working_data/script/_lib/lib_text_pointers.lua, line 86

text_pointer:new_from_component(
  string
name,
  [string
display mode],
  [number
length],
  object
ui component,
  [number
x proportion],
  [number
y proportion]
)

Creates a text_pointer object pointing to a supplied uicomponent. The uicomponent may either be supplied directly or as a function that returns a uicomponent.

Parameters:

1

string

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

2

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.

3

number

optional, default value=0

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

4

object

UI component to point at. This can be supplied as either a uicomponent or a function that returns a uicomponent. By default the pointer will point to the middle of the component - use the offset parameters to change this.

5

number

optional, default value=0.5

Unary x proportion specifying a pointed position relative to the dimensions of the specified component. Supply zero to point at the left edge of the component, one to point at the right edge of the component, or 0.5 to point at the middle of the component, for example. Values less than zero or greater than one are valid.

6

number

optional, default value=0.5

Unary y proportion specifying a pointed position relative to the dimensions of the specified component. Supply zero to point at the top edge of the component, one to point at the bottom edge of the component, or 0.5 to point at the middle of the component, for example. Values less than zero or greater than one are valid.

Returns:

  1. text_pointer

defined in ../working_data/script/_lib/lib_text_pointers.lua, line 125

text_pointer:new_from_position_offset_to_text_pointer(
  string
name,
  text_pointer
text pointer,
  number
x offset,
  number
y offset
)

Creates a text_pointer object with a position relative to another text pointer. This can be used to make text pointers appear in a sequence on the screen.

Parameters:

1

string

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

2

text_pointer

Text pointer object to display relative to.

3

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.

4

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. text_pointer

defined in ../working_data/script/_lib/lib_text_pointers.lua, line 202

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_text_pointers.lua, line 352

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_text_pointers.lua, line 365

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_text_pointers.lua, line 390

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_text_pointers.lua, line 398

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_text_pointers.lua, line 411

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_text_pointers.lua, line 426

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_text_pointers.lua, line 441

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

2

number

y offset

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_text_pointers.lua, line 455

text_pointer:set_show_pointer_end_without_line(boolean show line end without line)

Sets whether the line end should be drawn without the line.

Parameters:

1

boolean

show line end without line

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_text_pointers.lua, line 475

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_text_pointers.lua, line 501

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_text_pointers.lua, line 514

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_text_pointers.lua, line 541

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_text_pointers.lua, line 576

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

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_text_pointers.lua, line 598

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_text_pointers.lua, line 624

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_text_pointers.lua, line 637

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_text_pointers.lua, line 650

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_text_pointers.lua, line 663

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_text_pointers.lua, line 692

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_text_pointers.lua, line 705

text_pointer:set_line_end_state_override(string state name)

Sets a different state for the line end uicomponent. Any state set here must be present on the line_end component in the text_pointer_line_parent layout.

Parameters:

1

string

state name

Returns:

  1. nil

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

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_text_pointers.lua, line 743

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_text_pointers.lua, line 755

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. Calling this also sets the close button to show.
A callback set using this function will not be called if the text pointer is hidden by external script - use text_pointer:set_hide_callback to set a callback that would be called in this case.

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_text_pointers.lua, line 767

text_pointer:set_hide_callback(function callback, [number delay], [boolean show close button])

Set a callback to call when the text pointer is hidden. An optional delay may also be set. A further optional flag 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)

3

boolean

optional, default value=false

Sets the close button to show on the text pointer.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_text_pointers.lua, line 790

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_text_pointers.lua, line 813

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_text_pointers.lua, line 826

Back to top

Subtitle Mode

text_pointer:set_position_as_subtitle([position as 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.

Parameters:

1

position

optional, default value=true

as subtitle

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_text_pointers.lua, line 863

Back to top

Setting Component Text

text_pointer:add_component_text(string component name, string localised text, [exempt from streaming])

Sets the text displayed by a specified child uicomponent of the text pointer to a localised value. Use this method to show customised text on the text pointer.

Parameters:

1

string

Name of text component on the text pointer.

2

string

Full database key of localised text, in the form [table]_[localised_field]_[record_key].

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_text_pointers.lua, line 886

text_pointer:set_show_callback(function callback)

Sets a callback to call when the text pointer is shown with text_pointer:show.

Parameters:

1

function

callback

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_text_pointers.lua, line 919

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 with text_pointer:set_position_as_subtitle, and if set to true causes the text pointer to override the player's subtitles preferences.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_text_pointers.lua, line 941

text_pointer:hide([hide immediately], [suppress event])

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

Hide the text pointer immediately without any animation.

2

suppress

optional, default value=false

Suppress the scripted event that triggers - this is for internal use.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_text_pointers.lua, line 1685

text_pointer:is_showing()

Returns whether the text pointer is currently showing.

Returns:

  1. boolean is showing

defined in ../working_data/script/_lib/lib_text_pointers.lua, line 1802

text_pointer:has_ever_been_shown()

Returns whether the text pointer has ever been shown.

Returns:

  1. boolean ever shown

defined in ../working_data/script/_lib/lib_text_pointers.lua, line 1810

Back to top

Styles

text_pointer:set_style(string style, ... additional args)

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.
Multiple styles may be set on a given text pointer if the configuration options do not overlap (if they do then the later settings will overwrite the earlier settings).
Currently-supported styles are:
title_and_textSets the layout of the text pointer to "text_pointer_title_and_text". When setting this style the calling script must also supply two strings specifying the text db key of the title and the text to display.
text_onlySets the layout of the text pointer to "text_pointer_text_only". When setting this style the calling script must also supply a string specifying the text db key of the text to display.
topmostSets the pointer to be topmost and with a component priority of 1500.
semitransparentSets the "topmost" style and the panel state to "semitransparent".
semitransparent_highlightSets the "semitransparent" style and sets the close button to highlight two seconds after it is shown. The text pointer will not close when the close button is clicked, however.
semitransparent_highlight_dont_closeSets the "semitransparent" style and sets the close button to highlight two seconds after it is shown. The text pointer will close when the close button is clicked.
subtitle_with_frameSets the pointer into subtitle mode with a frame.
activeSets the "topmost" style, and sets the panel into the appropriate visual style for the active text pointer interface.

Parameters:

1

string

style

2

...

additional args

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_text_pointers.lua, line 1825


Active Text Pointers

Active pointers are a particular style of text_pointer, declared as a separate class with a cut-down interface. Visually, an active pointer appears as a text box with a close button and an enlarged pointer arrow with no connecting line. The pointer arrow appears in one of the four corners of the panel.

Active pointers are always associated with a uicomponent at which they visually point. While showing, the active pointer repeatedly polls the properties of this uicomponent. Should the uicomponent move on-screen, become invisible, or be destroyed, the active pointer will automatically dismiss itself. From an implementation perspective active pointers are intended to be relatively 'fire and forget', requiring a minimum of manual setup in script.

An active pointer will automatically immediately hide itself if any parent/ancestor of it, back to the ui root, is seen to play an animation called "hide". This generally occurs when the host panel (e.g. diplomacy panel) is closing.

Back to top

Active Pointer Display Methods

Once declared, an active pointer may be shown directly with active_pointer:show. Alternatively, active_pointer:show_when_ready may be used to show the pointer, which waits until the target uicomponent has stopped moving and become visible before the pointer is shown. active_pointer:show_when_ready may optionally take a delay value, which imposes a grace period before the text pointer is shown, and a timeout period after which the function will stop trying to show the pointer. Default values for both of these can be set on the active pointer with active_pointer:set_default_delay and active_pointer:set_default_timeout.

The active pointer interface also provides functionality to allow the pointer itself to manage being shown. active_pointer:show_on_event may be used to specify a script event and condition on which the active pointer should attempt to display. Furthermore, active_pointer:wait_for_active_pointer allows this active pointer to be enqueued behind another, so that the foreign active pointer must be shown before this one will attempt to display. One active pointer can wait for multiple other active pointers, which may themselves wait upon other active pointers and so-on.

Back to top

Storing in Advice History

By default, active pointers store a record when they are displayed in the advice history, and will not display if that record is present when active_pointer:show is called again. This behaviour, which is enabled by default, requires that the active pointer name is unique amongst active pointers, as the name of the advice history flag is derived from the pointer name.

This functionality can be disabled when calling active_pointer:new by setting the suppress-record boolean argument to true. When this is set to false the active pointer need not have a unique name, but advanced functionality like active_pointer:show_on_event and active_pointer:wait_for_active_pointer will not be available.

Back to top

Creation

active_pointer:new(
  
string name,
  string
orientation,
  uicomponent/function
uicomponent specifier,
  string
text key,
  [number
x proportion],
  [number
y proportion],
  [number
width],
  [boolean
suppress record]
)

Creates and returns a new active text pointer object.

Parameters:

1

string

Name for this text pointer. If this pointer is storing a record in the advice history (which is the default behaviour, and must be opted-out of by setting this suppress record in advice argument to true on this function) then the supplied name must be unique.

2

string

Orientation of the pointer arrow that is drawn. Supported values are "topleft", "topright", "bottomleft" and "bottomright".

3

uicomponent/function

Specifier of uicomponent to point at. This can either be a uicomponent object or a function that returns a uicomponent. It's strongly recommended that if the text pointer is not being displayed immediately after being created that a function is used.

4

string

Localised text key to display, in [table]_[field]_[key] format.

5

number

optional, default value=0.5

Unary x proportion specifying a pointed position relative to the dimensions of the specified component. Supply 0 to point at the left edge of the component, 1 to point at the right edge of the component, or 0.5 to point at the middle of the component, for example. Values less than zero or greater than one are valid.

6

number

optional, default value=0.5

Unary y proportion specifying a pointed position relative to the dimensions of the specified component. Supply 0 to point at the top edge of the component, 1 to point at the bottom edge of the component, or 0.5 to point at the middle of the component, for example. Values less than zero or greater than one are valid.

7

number

optional, default value=250

Width of the text pointer panel in pixels.

8

boolean

optional, default value=false

Sets this active pointer to not record a record of whether it's been triggered in advice history. If this is set to true then the active pointer is not registered with the script core, and it doesn't need to have a unique name. However, the active pointer will not be able to automatically listen for events.

Returns:

  1. active_pointer active text pointer

defined in ../working_data/script/_lib/lib_text_pointers_active.lua, line 108

Back to top

Usage

Once a active_pointer object has been created with active_pointer:new, functions on it may be called in the form showed below. Active text pointers inherit from text pointers, so all functions provided by the text_pointer interface may be called on a active_pointer.

Example - Specification:

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

Example - Creation and Usage:

local ap_example = active_pointer:new(
    "example",
    "bottomright",
    "ui_text_replacements_localised_text_example_text_pointer_str",
    function()
        -- function that should return a uicomponent
        return find_uicomponent(core:get_ui_root(), "diplomacy_dropdown", "main_button_bar", "menu_buttons", "button_quick_deal");
    end,
    -- point at top-right of uicomponent
    0.25,
    0.75
)

-- calling a function on the object once created
ap_example:show_when_ready()
Back to top

Configuration

active_pointer:set_default_delay(number delay)

Sets a default delay period for this active pointer, which is the period between when active_pointer:show_when_ready has detected that the pointer is ready to be shown and when the pointer is actually shown. Any default set here may be overridden when active_pointer:show_when_ready, active_pointer:show_after_active_pointer or active_pointer:show_on_event are called.

Parameters:

1

number

Delay value. This should be set in seconds in campaign, and milliseconds in battle or in the frontend.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_text_pointers_active.lua, line 475

active_pointer:set_default_timeout(number timeout)

Sets a default timeout period for this active pointer, which is the period over which active_pointer:show_when_ready will poll the target uicomponent to see if it becomes visible and stops moving. If the timeout period elapses then the attempt to show the text pointer is stopped. By default this is 5 seconds in campaign, or 5000ms in battle or the frontend.

Parameters:

1

number

Default timeout value. This should be set in seconds in campaign, and milliseconds in battle or in the frontend.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_text_pointers_active.lua, line 488

Back to top

Hide on Event

While being displayed, the active pointer polls its target uicomponent and will automatically hide itself once the target uicomponent moves or becomes invisible. Due to the inherent delay when polling with a model timer, in certain circumstances there is a visible delay before the text pointer hides. active_pointer:add_hide_on_event_record can be used to make the active pointer directly respond to script events and hide itself before its poll picks up on a ui state change.

active_pointer:add_hide_on_event_record(
  
string event name,
  [function/boolean
condition],
  [boolean
hide immediately]
)

Adds a hide-on-event record for this active pointer. If the event is received while the active pointer is being shown, and the optional conditional check passes, then the active pointer is hidden. An optional flag specifies whether this hide should happen immediately, without any fade animation.

Parameters:

1

string

Script event name.

2

function/boolean

optional, default value=true

Conditional check. This can be a function that returns a boolean, or true to always pass when the supplied event is received.

3

boolean

optional, default value=true

Hide the text pointer immediately, without a fade animation.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_text_pointers_active.lua, line 559

Back to top

Direct Triggering

active_pointer:show()

Immediately shows the text pointer, unless it's been set to pay attention to advice history (and has already been shown).

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_text_pointers_active.lua, line 606

active_pointer:show_when_ready([number delay override], [number timeout override])

Shows the active text pointer when the target uicomponent that was specified when the active pointer was created is not moving, is visible, and is fully onscreen. If this does not happen within the timeout period (default 5 seconds) then the process is cancelled.

Parameters:

1

number

optional, default value=0

Delay between the uicomponent stopping moving/becoming visible and the text pointer actually being shown. This should be supplied in seconds in campaign, and in milliseconds in battle and the frontend. The default value is 1 second, or 1000ms, or whatever has been set with active_pointer:set_default_delay.

2

number

optional, default value=0

Timeout period override. The timeout is the elapsed period after which the show_when_ready process will halt if the target uicomponent has not stopped moving or become visible. In campaign this should be supplied in seconds, and defaults to either 5 or whatever value has been set with active_pointer:set_default_timeout. In battle and the frontend, the timeout period is set in milliseconds and defaults to 5000.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_text_pointers_active.lua, line 638

Back to top

Managed Triggering

These functions are only supported when the active pointer is set to store its use in the advice history - see the Storing in Advice History section for more information.

active_pointer:wait_for_active_pointer(
  
string active pointer name,
  [number
delay override],
  [number
timeout override]
)

Prevents this active pointer from being shown before another active pointer has been shown. An active pointer may wait for multiple other active pointers, each wait being registered with a call to this function. Should multiple waits be set up for an active pointer, it will fail to display until all active pointers being waited for have finished showing.
This function sets up an active_pointer:show_after_active_pointer process automatically, which attempts to show this pointer once the active pointer being waited for is dismissed.
This active pointer must have registered itself in the advice history for this function to work.

Parameters:

1

string

Name of active pointer to wait for. The active pointer being waited for must have registered itself in the advice history.

2

number

optional, default value=0

Delay override, which will be supplied to active_pointer:show_when_ready if this monitor tries to show the pointer. This is the delay between the uicomponent stopping moving/becoming visible and the text pointer actually being shown. This should be supplied in seconds in campaign, and in milliseconds in battle and the frontend. The default value is 1 second, or 1000ms, or whatever has been set with active_pointer:set_default_delay.

3

number

optional, default value=0

Timeout period override, which will be supplied to active_pointer:show_when_ready if this monitor tries to show the pointer. The timeout is the elapsed period after which the show_when_ready process will halt if the target uicomponent has not stopped moving or become visible. In campaign this should be supplied in seconds, and defaults to either 5 or whatever value has been set with active_pointer:set_default_timeout. In battle and the frontend, the timeout period is set in milliseconds and defaults to 5000.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_text_pointers_active.lua, line 775

active_pointer:show_after_active_pointer(
  
string active pointer name,
  [number
delay override],
  [number
timeout override]
)

Sets up a listener that attempts to show this active pointer once the specified active pointer closes. Unlike active_pointer:wait_for_active_pointer this doesn't demand that the specified active pointer must have first been shown before this active pointer can be shown - this active pointer could trigger before the specified active pointer (from a different event, for example).
This active pointer must have registered itself in the advice history for this function to work.

Parameters:

1

string

Name of active pointer to wait for. The active pointer being waited for must have registered itself in the advice history.

2

number

optional, default value=0

Delay override, which will be supplied to active_pointer:show_when_ready if this monitor tries to show the pointer. This is the delay between the uicomponent stopping moving/becoming visible and the text pointer actually being shown. This should be supplied in seconds in campaign, and in milliseconds in battle and the frontend. The default value is 1 second, or 1000ms, or whatever has been set with active_pointer:set_default_delay.

3

number

optional, default value=0

Timeout period override, which will be supplied to active_pointer:show_when_ready if this monitor tries to show the pointer. The timeout is the elapsed period after which the show_when_ready process will halt if the target uicomponent has not stopped moving or become visible. In campaign this should be supplied in seconds, and defaults to either 5 or whatever value has been set with active_pointer:set_default_timeout. In battle and the frontend, the timeout period is set in milliseconds and defaults to 5000.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_text_pointers_active.lua, line 801

active_pointer:show_on_event(
  
string event,
  [boolean/function
condition],
  [number
delay override],
  [number
timeout override]
)

Sets the active pointer to trigger when a script event is received, with an optional conditional check that must be passed.
This active pointer must have registered itself in the advice history for this function to work.

Parameters:

1

string

Event name.

2

boolean/function

optional, default value=true

Conditional check. This may be omitted, or true may be supplied to always trigger whenever the supplied event is received.

3

number

optional, default value=0

Delay override, which will be supplied to active_pointer:show_when_ready if this monitor tries to show the pointer. This is the delay between the uicomponent stopping moving/becoming visible and the text pointer actually being shown. This should be supplied in seconds in campaign, and in milliseconds in battle and the frontend. The default value is 1 second, or 1000ms, or whatever has been set with active_pointer:set_default_delay.

4

number

optional, default value=0

Timeout period override, which will be supplied to active_pointer:show_when_ready if this monitor tries to show the pointer. The timeout is the elapsed period after which the show_when_ready process will halt if the target uicomponent has not stopped moving or become visible. In campaign this should be supplied in seconds, and defaults to either 5 or whatever value has been set with active_pointer:set_default_timeout. In battle and the frontend, the timeout period is set in milliseconds and defaults to 5000.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_text_pointers_active.lua, line 858

Last updated 25/08/2021 12:07:50