Docs Flobtive Textfields

Textfields

Properties

Property	Description	Type	Default
state	An object for storing custom attributes / property values that belongs to that flobtive. When the state object changes, a re-appearance is triggered. Cannot be inherited from other flobtives.	`object`	`{ }`
type	The flobtive's description type. `readonly`
_alpha	The alpha transparency value of the textfield. `Min: 0 \| Max: 1`	`number`	`1`
_anchorX	The horizontal axis of the textfield, in percentage. `Min: 0 \| Max: 100`	`number`	`0`
_anchorY	The vertical axis of the textfield, in percentage. `Min: 0 \| Max: 100`	`number`	`0`
_backgroundColor	The textfield's background color.	`string`	`"none"`
_borderColor	The textfield's border color.	`string`	`"none"`
_focused	A value that indicates whether the textfield is selected. `readonly`	`boolean`	`false`
_fontColor	The textfield's font color.	`string`	`"black"`
_fontFamily	The textfield's font family.	`"string"`	`"Arial, sans-serif"`
_fontSize	The textfield's font size, in pixels. `Min: 8 \| Max: 80`	`number`	`20`
_height	The vertical dimension of the textfield, in pixels. `Min: 2`	`number`	`20`
_hovered	A value that indicates whether the textfield is being hovered by the cursor. Only available when the textfield has an onClick() event handler. `readonly`	`boolean`	`false`
_lineHeight	The height of a line in the textfield. `Min: 1`	`number`	`_fontSize`
_multiline	A value that indicates whether the textfield words wrap at borders.	`boolean`	`true`
_padding	The space between the textfield's borders and its text.	`number`	`0`
_rotation	The rotation of the textfield, in degrees, from its original orientation. `Min: -179 \| Max: 180`	`number`	`0`
_text	The text content of the textfield.	`string`	`""`
_textAlign	The horizontal alignment of text in the textfield.	`string`	`"left"`
_type	The textfield's text type.	`string`	`"dynamic"`
_visible	A value that indicates whether the textfield is visible.	`boolean`	`true`
_width	The horizontal dimension of the textfield, in pixels. `Min: 2`	`number`	`100`
_wordWrap	A value that indicates whether the text content should be automatically wrapped onto a new line when it exceeds the dimensions of the textfield.	`boolean`	`true`
_x	The horizontal position / x coordinate of a textfield relative to the coordinates of the stage. Smaller values to the left, larger values to the right.	`number`	`0`
_y	The vertical position / y coordinate of a textfield relative to the coordinates of the stage. Smaller values to the top, larger values to the bottom.	`number`	`0`

Event Summary

Event	Description
onClick()	Handler for when textfield is clicked.

Method Summary

Method	Description
addScript()	Adds a copy of the script specified to the textfield's heirarchy.
addText()	Adds comma separated strings of text (joined by spaces) to the textfield's existing text content. The equivalent of `_text += "added" + " " + "text"` When entered with multiple parameters, concatenates all strings and numbers, separated by spaces.
addTextLn()	Adds comma separated strings of text (joined by spaces) to the textfield's existing text content, followed by a line break. The equivalent of `_text += "added" + " " + "text" + "\n"` When entered with multiple parameters, concatenates all strings and numbers, separated by spaces, before ending with a line break.
addTextLns()	Adds comma separated strings of text (joined by line breaks) to the textfield's existing text content, followed by a line break. The equivalent of `_text += "added" + "\n" + "text" + "\n"` When entered with multiple parameters, concatenates all strings and numbers, separated by line breaks, before ending with a line break.
changeState()	Modifies the textfield's state by creating or replacing the attribute specified.
clearText()	Clears the textfield's text content. The equivalent of `_text = ""`
getText()	Returns the textfield's text content. The equivalent of `_text`
globalToLocal()	Converts the point object from the stage's global coordinates to the textfield's local coordinates.
hitTest()	Evaluates the textfield to see if a point is in a flevaclip or if two flevaclips intersect.
localToGlobal()	Converts the point object from the textfield's local coordinates to the stage's global coordinates.
removeTextLn()	Removes the specified number of lines of text from the textfield.
setState()	Merges the textfield's current state with the object specified or evaluated from any functions specified.
setText()	Sets the textfield's text content. The equivalent of `_text = "Text content"` When entered with multiple parameters, concatenates all strings and numbers, separated by spaces.
swapDepths()	Swaps the stacking / depth level of this textfield with the number specified.
useState()	Overwrites the textfield's current state with the object specified or evaluated from any functions specified.

Methods

`addScript(script)`

Adds a copy of the specified script to the textfield's heirarchy.

Parameters

script
- Types: string | Script | function
  - string: A label to identify the name of a script existing in the engine's library.
  - Script: A reference to an existing script in the engine's library.
  - function: A custom function to act directly upon the textfield.
- The script is then bound to the textfield, and executed in every game loop for the life-cycle of the textfield.

Example

Assuming the script is originally created:

/* Within engine's onload */

// create function to turn into script
const myFunction = function() {
    flevar.trace("Hello World!");
}

// create script and add to flevar's library
flevar.createScript("my_script", myFunction);

Adding a script by its label:

/* Within textfield's onload */

// add script to textfield from library with label "my_script"
textfield.addScript("my_script");

Adding a script by its reference:

/* Within textfield's onload */

// create a reference of the script
const myScript = flevar.getScript("my_script");
// add script to textfield from its reference
textfield.addScript(myScript);

Adding a script using a function:

/* Within textfield's onload */

// add script to textfield from function created earlier
textfield.addScript(myFunction);

go to top

`changeState(key, value)`

Modifies the textfield's state by creating or replacing the attribute specified.

Parameters

key
- Type: string
- The name of the state attribute being modified.
value
- Type: any
- The value of the state attribute being modified.

Example

Assuming the state was previously set, and already has attributes:

/* Within textfield's onload */

// trace the attributes of state
flevar.trace(textfield.state);

// > { baz: 3, foo: "bar", plank: "Descendant of tree" }

Modifying the state to change already existing attribute baz:

/* Within textfield's onload */

// modify `baz` attribute
textfield.changeState("baz", 8);

// trace the attributes of state
flevar.trace(textfield.state);

// > { baz: 8, foo: "bar", plank: "Descendant of tree" }

Modifying the state to create new attribute hue:

/* Within textfield's onload */

// create `hue` attribute
textfield.changeState("hue", "#e44d26");

// trace the attributes of state
flevar.trace(textfield.state);

// > { baz: 8, foo: "bar", hue: "#e44d26", plank: "Descendant of tree" }

go to top

`globalToLocal(point, relative)`

Converts the point object from the stage's global coordinates to the textfield's local coordinates. Global coordinates relate to the top-left corner of the stage. Local coordinates relate to the anchor points of the textfield.

Parameters

point
- Type: object
- An object with x and y coordinates.
relative
- Type: boolean
- Default: false
- Determines whether the local point is rotated relatively to the textfield's _rotation property or not.

Notes

The textfield coordinates are expressed using _x and _y, because those are the textfield properties that you use to set the x and y values for FlevaClips. However, your generic object uses x and y without the underscore.
The globalToLocal() method doesn't return a value, because it changes the values of x and y in the generic object that you send as the parameter. It changes them from values relative to the stage (global coordinates) to values relative to a specific textfield (local coordinates).

Example

After you create a point object with global coordinates, you can convert the coordinates to local coordinates.

Assuming the textfield is located at _x: 100 and _y: 100:

/* Within textfield onload */
const myPoint = { x: 20, y: 50 };

// convert the point from global coordinates to local coordinates
textfield.globalToLocal(myPoint);

// trace the coordinates of the myPoint
flevar.trace(myPoint);

// > { x: -80, y: -50 }

The global point (20, 50) became (-80, -50) when converted to a local point.

Assuming the textfield has _rotation: 90:

/* Within textfield onload */
const myPoint = { x: 20, y: 50 };

// convert the point from global coordinates to local coordinates relative to the textfield's rotation
textfield.globalToLocal(myPoint, true);

// trace the coordinates of the myPoint
flevar.trace(myPoint);

// > { x: -50, y: 80 }

Note: The above example may yield { x: 50.00000000000001, y: 80 }
JavaScript's rounding behavior means that either coordinate could still be a float, and should be expected as such.
You can convert them to integers using Math.round(), Math.ceil(), or Math.floor() as needed.

The local point (-80, -50) is rotated relatively to the textfield's _rotation, becoming (-50, 80).

go to top

`hitTest()`

Evaluates the textfield to see if it overlaps or intersects with the hit area that the target or x and y coordinate parameters identify.

Usages

hitTest(target)
hitTest(x, y)

Parameters

x
- Type: number
- The horizontal coordinate of the point to test.
y
- Type: number
- The vertical coordinate of the point to test.
target
- Types: string | FlevaClip
  - string: The instanceName of the flevaclip to test for the collision.
  - FlevaClip: The flevaclip reference in which to test for the collision.

Returns

Type: boolean
- true if the collision test is true; false otherwise.

Notes

The bounding box refers to the smallest rectangle that can encompass every occupied pixel of that flevaclip.
The rotated box refers to the actual rectangle around the flevaclip, at any given rotation.

Example

Assuming const _root = flevar._root;, and 2 textfields exist with instanceName: "flevaclip1" and instanceName: "flevaclip2":

To see if both textfields' bounding boxes collide:

/* Within flevaclip1's added script */

// either evaluate collision by reference
if(textfield.hitTest(_root.flevaclip2)) {
  flevar.trace("Hitting!");
}

// or evaluate collision by instanceName label
if(textfield.hitTest("flevaclip2")) {
  flevar.trace("Hitting!");
}

To test if mouse is over a textfield's bounding box:

/* Within either textfield's added script */

// evaluate mouse points collision
if(textfield.hitTest(_root._xmouse, _root._ymouse)) {
  flevar.trace("Mouse is hovering");
}

To test if mouse is over a textfield's rotated box:

/* Within either textfield's added script */

// evaluate mouse points collision
if(textfield.hitTest(_root._xmouse, _root._ymouse, true)) {
  flevar.trace("Mouse is hovering");
}

go to top

`localToGlobal(point, relative)`

Converts the point object from the stage's global coordinates to the textfield's local coordinates. Global coordinates relate to the top-left corner of the stage. Local coordinates relate to the anchor points of the textfield.

Converts the point object from the textfield's local coordinates to the stage's global coordinates. Local coordinates relate to the anchor points of the textfield. Global coordinates relate to the top-left corner of the stage.

Parameters

point
- Type: object
- An object with x and y coordinates.
relative
- Type: boolean
- Default: false
- Determines whether the local point is rotated relatively from the textfield's _rotation property or not.

Notes

The textfield coordinates are expressed using _x and _y, because those are the textfield properties that you use to set the x and y values for FlevaClips. However, your generic object uses x and y without the underscore.
The localToGlobal() method doesn't return a value, because it changes the values of x and y in the generic object that you send as the parameter. It changes them from values relative to a specific textfield (local coordinates) to values relative to the stage (global coordinates).

Example

After you create a point object with local coordinates, you can convert the coordinates to global coordinates.

Assuming the textfield is located at _x: 100 and _y: 100:

/* Within textfield onload */
const myPoint = { x: -50, y: 80 };

// convert the point from local coordinates to global coordinates
textfield.localToGlobal(myPoint);

// trace the coordinates of the myPoint
flevar.trace(myPoint);

// > { x: 50, y: 180 }

The local point (-50, 80) became (50, 180) when converted to a global point.

Assuming the textfield has _rotation: 90:

/* Within textfield onload */
const myPoint = { x: -50, y: 80 };

// convert the point from global coordinates to local coordinates relative to the textfield's rotation
textfield.localToGlobal(myPoint, true);

// trace the coordinates of the myPoint
flevar.trace(myPoint);

// > { x: 20, y: 50 }

Note: The above example may yield { x: 20, y: 50.00000000000001 }
JavaScript's rounding behavior means that either coordinate could still be a float, and should be expected as such.
You can convert them to integers using Math.round(), Math.ceil(), or Math.floor() as needed.

The local point (-50, 80) is rotated relatively from the textfield's _rotation, then mapped relative to the stage, becoming the global point (20, 50).

go to top

`removeTextLn(limit)`

Removes the specified number of lines of text from the textfield.

Parameters

limit
- Type: number
- The number of lines of text to remove from the textfield.
  - Positive values remove those number of lines from the top of the textfield.
  - Negative values remove those number of lines from the bottom of the textfield.

Notes

The lines of text considered are lines created from line breaks, rather than lines created from word wraps.

Examples

Assuming a textfield is created with 5 lines of text:

const fiveLinesOfText = `This is line 1;
This is line 2;
This is line 3;
This is line 4;
This is line 5;`;

flevar.createTextfield("my_textfield", { _text: fiveLinesOfText });

Remove the first 2 lines from the textfield:

/* Within textfield's onload */
textfield.removeTextLn(2);

/* Remaining expected text content */
//This is line 3;
//This is line 4;
//This is line 5;

Using the same initial 5 lines of text, remove the last 2 lines from the textfield:

/* Within textfield's onload */
textfield.removeTextLn(-2);

/* Remaining expected text content */
//This is line 1;
//This is line 2;
//This is line 3;

go to top

`setState(state)`

Merges the textfield's current state with the object specified or evaluated from any functions specified.

Parameters

state
- Types: object | function | Script
  - object: The new state object by which to merge.
  - function: The new state function which is evaluated, and the returned object merged.
  - Script: The script reference which is evaluated, and the returned object merged.

Notes

FlevaR's setState works similar to React's setState:
- objects passed are merged with the state object.
- functions or Scripts passed are evaluated with a copy of the flobtive's state passed as its first parameter. The returned object is then merged with the state object.
A re-appearance is only triggered when the values of state have changed. i.e. If setState passes values that all already exist in the flobtive's state, no re-appearance is triggered.

Example

Assuming const trace = flevar.trace;, and const utils = flevar.utils;.

Using setState with an object:

/* Within textfield's onload */

// trace the state value
trace(textfield.state);

// > { }

// modify the state
textfield.setState({ name: "Bob", currency: 200 });

// trace the state value
trace(textfield.state);

// > { name: "Bob", currency: 200 }

Assuming textfield's state is as modified above.

Using setState with a function:

/* Within textfield's onload */

// trace the state value
trace(textfield.state);

// > { name: "Bob", currency: 200 }

// modify the state
textfield.setState(function(stateCopy) {
  // create a new state object intended to modify textfield's state
  const newState = { color: "red", number: 24 };

  // loop through existing state attributes, using the copy of textfield's state, so as to not alter it mistakenly
  for(const attributeName of Object.keys(stateCopy)) {
    // check if attribute is a number
    if(utils.isNumber(stateCopy[attributeName])) {
      // double the number value in the newState object
      newState[attributeName] = stateCopy[attributeName] * 2;
    }
  }

  // trace the newState value
  trace(newState);

  // > { color: "red", number: 24, currency: 400 }

  // return the newState object to be merged with the textfield's state
  return newState;
});

// trace the state value
trace(textfield.state);

// > { name: "Bob", currency: 400, color: "red", number: 24 }

Assuming a script has been created:

/* Within engine's onload */

flevar.createScript("stateFunc", function(stateCopy) {
  return { message: "Hello World!" };
});

Using setState with Script reference:

/* Within textfield's onload */

// trace the state value
trace(textfield.state);

// > { }

// modify the state
textfield.setState(flevar.getScript("stateFunc"));

// trace the state value
trace(textfield.state);

// > { message: "Hello World!" }

go to top

`swapDepths(depth)`

Swaps the stacking / depth level of this textfield with the number specified.

Parameters

depth
- Type: number
- The depth number to swap to.

Notes

FlevaClips with higher depth values appear above those with lower values.
FlevaClips with the same depth value appear by the order which they were added. i.e. FlevaClips added first would be below clips added after, if they share the same depth value.

go to top

`useState(state)`

Overwrites the textfield's current state with the object specified or evaluated from any functions specified.

Parameters

state
- Types: object | function | Script
  - object: The new state object by which to use.
  - function: The new state function which is evaluated, and the returned object used.
  - Script: The script reference which is evaluated, and the returned object used.

Notes

FlevaR's useState works similar to React's useState:
- objects passed are used as the new state object.
- functions or Scripts passed are evaluated with a copy of the flobtive's state passed as its first parameter. The returned object is then used as the new the state object.
A re-appearance is always triggered with useState, since even if the overwritten object has the same attributes and values, the object is new.

Example

Assuming const trace = flevar.trace;, and const utils = flevar.utils;.

Using useState with an object:

/* Within textfield's onload */

// trace the state value
trace(textfield.state);

// > { }

// modify the state
textfield.useState({ name: "Bob", currency: 200 });

// trace the state value
trace(textfield.state);

// > { name: "Bob", currency: 200 }

Assuming textfield's state is as modified above.

Using useState with a function:

/* Within textfield's onload */

// trace the state value
trace(textfield.state);

// > { name: "Bob", currency: 200 }

// modify the state
textfield.useState(function(stateCopy) {
  // create a new state object intended to modify textfield's state
  const newState = { color: "red", number: 24 };

  // loop through existing state attributes, using the copy of textfield's state, so as to not alter it mistakenly
  for(const attributeName of Object.keys(stateCopy)) {
    // check if attribute is a number
    if(utils.isNumber(stateCopy[attributeName])) {
      // double the number value in the newState object
      newState[attributeName] = stateCopy[attributeName] * 2;
    }
  }

  // trace the newState value
  trace(newState);

  // > { color: "red", number: 24, currency: 400 }

  // return the newState object to be used as the new textfield's state
  return newState;
});

// trace the state value
trace(textfield.state);

// > { color: "red", number: 24, currency: 400 }

Assuming a script has been created:

/* Within engine's onload */

flevar.createScript("stateFunc", function(stateCopy) {
  return { message: "Hello World!" };
});

Using useState with Script reference:

/* Within textfield's onload */

// trace the state value
trace(textfield.state);

// > { }

// modify the state
textfield.useState(flevar.getScript("stateFunc"));

// trace the state value
trace(textfield.state);

// > { message: "Hello World!" }

go to top

Docs Flobtive Textfields

Textfields

Properties

Event Summary

Method Summary

Methods

addScript(script)

Parameters

Example

changeState(key, value)

Parameters

Example

globalToLocal(point, relative)

Parameters

Notes

Example

hitTest()

Usages

Parameters

Returns

Notes

Example

localToGlobal(point, relative)

Parameters

Notes

Example

removeTextLn(limit)

Parameters

Notes

Examples

setState(state)

Parameters

Notes

Example

swapDepths(depth)

Parameters

Notes

useState(state)

Parameters

Notes

Example

*(Working Draft)

Home Page

Guide

Documentation

Clone this wiki locally

`addScript(script)`

`changeState(key, value)`

`globalToLocal(point, relative)`

`hitTest()`

`localToGlobal(point, relative)`

`removeTextLn(limit)`

`setState(state)`

`swapDepths(depth)`

`useState(state)`

**(Working Draft)*