Name: measureText

Type: function

Syntax: measureText(<text>,<objectReference>,[<mode>])

Summary:
<return|Returns> the width, size or bounds of the text drawn with the
effective font attribute of the given object.

Introduced: 6.5

OS: mac, windows, linux, ios, android

Platforms: desktop, server, mobile

Example:
local tText, tTextWidth
put "Hello world" into tText
put measureText(tText,field "myField") into tTextWidth

Example:
local tText, tTextSize
put "Hello world" into field "someField"
put field "someField" into tText
put measureText(tText,field "someField","size") into tTextSize

Example:
# handler in a field
on textChanged
  local tTextBounds
  put measureText("foo",me,"bounds") into tTextBounds
  put "The text in this field has these bounds: " & tTextBounds
end textChanged

Parameters:
text(string):
Any text string, or an <expression> that <evaluate|evaluates> to 
a string.

objectReference(string):
An expression that <evaluate|evaluates> to an object reference.

mode(enum):
-   "width": (default if not specified)
-   "size":
-   "bounds":

Returns:
-   width (number): the width of the text
-   size (int,int): the width and height of the text as a 
comma-separated list; e.g. width,height
-   bounds (rect): a rectangle identifying the bounds of the text in the
form `0,-ascent,width,descent` where ascent and descent are relative to
a 0 baseline the text is drawn on.


Description:
Use the <measureText> <function> to find the dimensions of the given 
text if drawn using the effective font attributes of the object 
specified in the <objectReference> parameter.

References: function (control structure), return (glossary), 
formattedWidth (property), formattedHeight (property), 
textChanged (message), expression (glossary), evaluate (glossary)

Tags: ui, text processing
