Name: clickText

Type: function

Syntax: the clickText

Syntax: clickText()

Summary: <return|Returns> the <word> or <grouped text|text group> the user last clicked.

Introduced: 1.0

OS: mac,windows,linux,ios,android

Platforms: desktop,web,mobile

Example:
the clickText

Example:
if the clickText contains "*" then goToFootnote (the clickText)

Returns: The <clickText> <function> <return|returns> the text that the user clicked.

Description:
Use the <clickText> <function> within a <mouseDown>, <mouseUp>, or <selectionChanged> <handler> to determine which <word> or <grouped text|text group> the user clicked, in order to provide <hypertext> (clickable text) or take some action based on the click.

The <clickText> <function> is cleared at the next mouse click, as well as after some editing actions such as deleting text. If the user has clicked anywhere since clicking the <field>, the <clickText> <function> <return|returns> empty.

The returned value contains the word the user clicked. If the textStyle of the clicked text is "link", the <return value|returned value> contains the entire <grouped text|text group>.

>*Important:*  Words are defined a little differently by the <clickText> <function> than the way they are used in <chunk expression|chunk expressions>. A word, for purposes of the <clickText>, is any text delimited by spaces, tabs, returns, or punctuation. If you click a punctuation <character>, only that <character> is returned. This means that, for example, clicking a hyphenated word only returns the part of the word that was clicked.

The returned value indicates the text that the mouse pointer was over when the mouse was clicked. Moving the mouse before the mouse button is released does not affect the value returned by the <clickText>.

If the field is locked, the <clickText> function is most useful within a <handler> (such as <mouseDown> or <mouseUp>) that is <trigger|triggered> by the mouse click.

If the field is unlocked, mouseDown and <mouseUp> <message|messages> are not sent when the user clicks in the <field> (unless the user right-clicks or holds down the Control key while clicking). Use the <clickText> <function> within a <selectionChanged> <handler> to determine what text the user is editing in an <unlock|unlocked> <field>.

To get the location of the word or text group clicked, use the <clickChunk> <function>.

References: word (keyword), field (keyword), character (keyword), mouseDown (message), mouseUp (message), selectionChanged (message), mouseText (function), clickCharChunk (function), selectedText (function), clickChunk (function), clickChar (function), foundText (function), return (glossary), chunk expression (glossary), handler (glossary), return value (glossary), trigger (glossary), message (glossary), unlock (glossary), grouped text (glossary), hypertext (glossary), function (control_st)

Tags: ui
