API Docs for: 1.4.0
Show:

Kiwi.GameObjects.TextField Class

Extends Kiwi.Entity
Module: GameObjects
Parent Module: Kiwi

TextField is a GameObject that is used when you are wanting to render text onto the current State.

TextField has width/height and a hitbox, but because text is difficult to measure, these may not be 100% accurate. It does not have an "Input" component either, although you may choose to add one. Be aware of these limitations.

Note that there also exists a "Textfield" object. This is simply a legacy alias of "TextField", which was renamed in v1.2.0 for naming standardization purposes.

Constructor

Kiwi.GameObjects.TextField

(
  • state
  • text
  • [x=0]
  • [y=0]
  • [color="#000000"]
  • [size=32]
  • [weight="normal"]
  • [fontFamily="sans-serif"]
)
TextField

Parameters:

  • state Kiwi.State

    The state that this TextField belongs to

  • text String

    The text that is contained within this textfield.

  • [x=0] Number optional

    The new x coordinate from the Position component

  • [y=0] Number optional

    The new y coordinate from the Position component

  • [color="#000000"] String optional

    The color of the text.

  • [size=32] Number optional

    The size of the text in pixels.

  • [weight="normal"] String optional

    The weight of the text.

  • [fontFamily="sans-serif"] String optional

    The font family that is to be used when rendering.

Returns:

TextField:

This Game Object.

Methods

_renderText

() private

This method is used to render the text to an offscreen-canvas which is held in a TextureAtlas (which is generated upon the instanitation of this class). This is so that the canvas doesn't render it every frame as it can be costly and so that it can be used in WebGL with the TextureAtlasRenderer.

addTag

(
  • tag
)
public

Inherited from Kiwi.Entity: src\core\Entity.ts:464

Available since 1.1.0

Adds a new Tag to this Entity. Useful for identifying large amounts of the same type of GameObjects. You can pass multiple strings to add multiple tags.

Parameters:

  • tag String

    The tag that you would like to add to this Entity.

centerAnchorPoint

() public

Inherited from Kiwi.Entity: src\core\Entity.ts:332

Available since 1.1.0

Center the anchor point. Moves the anchor point (rotPointX and Y) to precisely halfway along the width and height properties of this Entity.

destroy

(
  • [immediate=false]
)
public

Used to completely destroy this entity and of its components. Used for garbage collection and developers can also use it as needed. It is more reliable to use "exists = false", as this will ensure that "destroy" is called at a convenient time.

Parameters:

  • [immediate=false] Boolean optional

    If the object should be immediately removed or if it should be removed at the end of the next update loop.

hasTag

(
  • tag
)
Boolean public

Inherited from Kiwi.Entity: src\core\Entity.ts:499

Available since 1.1.0

Checks to see if this Entity has a Tag based upon a string which you pass.

Parameters:

  • tag String

Returns:

Boolean:

objType

() String public

Inherited from Kiwi.Entity but overwritten in src\gameobjects\Textfield.ts:77

Returns the type of object that this is.

Note: This is not camel-cased because of an error in early development. To preserve API compatibility, all 1.x.x releases retail this form. This will be fixed in v2.

Returns:

String:

"Textfield"

removeTag

(
  • tag
)
public

Inherited from Kiwi.Entity: src\core\Entity.ts:483

Available since 1.1.0

Removes a Tag from this Entity.

Parameters:

  • tag String

    The tag that you would like to remove from this Entity.

render

(
  • UNKNOWN
)
public

Inherited from Kiwi.Entity but overwritten in src\gameobjects\Textfield.ts:427

Called by the Layer to which this Game Object is attached

Parameters:

renderGL

(
  • gl
  • camera
  • params
)
public

Inherited from Kiwi.Entity but overwritten in src\gameobjects\Textfield.ts:475

Renders the GameObject using WebGL.

Parameters:

  • gl WebGLRenderingContext
  • camera Kiwi.Camera
  • params Object

scaleToHeight

(
  • value
)
public

Inherited from Kiwi.Entity: src\core\Entity.ts:321

Available since 1.1.0

Scale to desired height, preserving aspect ratio. This function changes the scale, not the height. If the height changes, for example, as part of an animation sequence, the Entity will retain the new scale.

Parameters:

  • value Number

    The desired height in pixels.

scaleToWidth

(
  • value
)
public

Inherited from Kiwi.Entity: src\core\Entity.ts:310

Available since 1.1.0

Scale to desired width, preserving aspect ratio. This function changes the scale, not the width. If the width changes, for example, as part of an animation sequence, the Entity will retain the new scale.

Parameters:

  • value Number

    The desired width in pixels.

update

() public

This isn't called until the Entity has been added to a Group or a State. Note: If added to a Group, who is not 'active' (so the Groups update loop doesn't run) then each member will not execute either.

Properties

_active

Boolean private

An active Entity is one that has its update method called by its parent.

Default: true

_alignWidth

Number private

Defined in src\gameobjects\Textfield.ts:143

Available since 1.1.0

The pixel width of the text. Used internally for alignment purposes.

Default: 0

_alpha

Number private

The alpha of this entity.

_baseline

String private

The baseline of the text to be rendered.

_canvas

HTMLCanvasElement. private

The canvas element which the text is rendered onto.

_cellIndex

Number private

Holds the current cell that is being used by the entity.

Default: 0

_clock

Kiwi.Clock private

The clock that this entity use's for time based calculations. This generated by the state on instatiation.

_ctx

CanvasRenderingContext2D private

The context for the canvas element. Used whilst rendering text.

_dirty

Boolean private

A value used by components to control if the Entity needs re-rendering

_exists

Boolean private

If an Entity no longer exists it is cleared for garbage collection or pool re-allocation

_fontColor

Kiwi.Utils.Color private

The color of the text.

_fontFamily

String private

The font family that is to be rendered.

Default: "sans-serif"

_fontSize

Number private

The size of the font.

Default: 32

_fontWeight

String private

The weight of the font.

Default: "normal"

_inputEnabled

Boolean deprecated private

Inherited from Kiwi.Entity: src\core\Entity.ts:568

Deprecated: As of 1.2.3, nothing was found to use this.

Controls if this Entity is input enabled or not (i.e. responds to touch/mouse events)

_parent

Kiwi.Group private

The group that this entity belongs to. If added onto the state then this is the state.

_pt1

Kiwi.Geom.Point private

Geometry point used in rendering.

_pt2

Kiwi.Geom.Point private

Geometry point used in rendering.

_pt3

Kiwi.Geom.Point private

Geometry point used in rendering.

_pt4

Kiwi.Geom.Point private

Geometry point used in rendering.

_tags

Array private

Inherited from Kiwi.Entity: src\core\Entity.ts:454

Available since 1.1.0

Any tags that are on this Entity. This can be used to grab GameObjects or Groups on the whole game which have these particular tags. By default Entitys contain no tags.

_tempDirty

Boolean private

If the temporary canvas is dirty and needs to be re-rendered. Only used when the text field rendering is being optimised.

_text

String private

The text that is to be rendered.

_textAlign

String private

The alignment of the text. This can either be "left", "right" or "center"

Default: "center"

_visible

Boolean private

A boolean that indicates whether or not this entity is visible or not. Note that is does not get set to false if the alpha is 0.

Default: true

_willRender

Boolean deprecated private

Inherited from Kiwi.Entity: src\core\Entity.ts:543

Deprecated: Use _visible instead

Controls whether render is automatically called by the parent.

Default: true

active

Boolean public

Toggles the active state of this Entity. An Entity that is active has its update method called by its parent. This method should be over-ridden to handle specific dom/canvas/webgl implementations.

alpha

Number public

Alpha of this entity. A number between 0 (invisible) and 1 (completely visible).

anchorPointX

Number public

Inherited from Kiwi.Entity: src\core\Entity.ts:203

Available since 1.1.0

The anchor point on the x-axis. This is just aliased to the rotPointX on the transform object.

anchorPointY

Number public

Inherited from Kiwi.Entity: src\core\Entity.ts:217

Available since 1.1.0

The anchor point on the y-axis. This is just aliased to the rotPointY on the transform object.

atlas

Kiwi.Textures.TextureAtlas public

The texture atlas that is to be used on this entity.

box

Kiwi.Components.Box public

Defined in src\gameobjects\Textfield.ts:308

Available since 1.2.0

Hitbox component

cellIndex

Number public

Used as a reference to a single Cell in the atlas that is to be rendered.

E.g. If you had a spritesheet with 3 frames/cells and you wanted the second frame to be displayed you would change this value to 1

Default: 0

clock

Kiwi.Time.Clock public

The Clock used to update this all of this Entities components (defaults to the Game MasterClock)

color

String public

The color of the font that is contained in this textfield. May be set with a string, or an array of any valid Kiwi.Utils.Color arguments. Returns a hex string prepended with "#".

components

Kiwi.ComponentManager public

The Component Manager

dirty

Boolean public

A value used by components to control if the Entity needs re-rendering

exists

Boolean public

Toggles the existence of this Entity. An Entity that no longer exists can be garbage collected or re-allocated in a pool.

fontFamily

String public

The font family that is being used to render the text.

fontSize

Number public

The size on font when being displayed onscreen.

fontWeight

String public

The weight of the font.

game

Game public

The game this Entity belongs to

height

Number public

The height of the entity in pixels, pre-transform.

To obtain the actual height, multiply height by scaleY.

Default: 0

id

String public

A unique identifier for this Entity within the game used internally by the framework. See the name property for a friendly version.

inputEnabled

Boolean deprecated public

Inherited from Kiwi.Entity: src\core\Entity.ts:577

Deprecated: As of 1.2.3, nothing was found to use this.

Controls if this Entity is input enabled or not (i.e. responds to touch/mouse events) This method should be over-ridden to handle specific game object implementations.

name

String public

A name for this Entity. This is not checked for uniqueness within the Game, but is very useful for debugging

Default: ''

parent

Group public

The group that this entity belongs to/is a child of once added to one. If added onto the state then this is the state.

Sub-properties:

rotation

Number public

Rotation of this Entity. This is just aliased to the transform property.

rotPointX

Number public

The rotation point on the x-axis. This is just aliased to the rotPointX on the transform object.

rotPointY

Number public

The rotation point on the y-axis. This is just aliased to the rotPointY on the transform object.

scale

Number public

Inherited from Kiwi.Entity: src\core\Entity.ts:153

Available since 1.1.0

Scale both axes of this Entity. This is just aliased to the transform property. This is WRITE-ONLY.

scaleX

Number public

Scale X of this Entity. This is just aliased to the transform property.

scaleY

Number public

Scale Y coordinate of this Entity. This is just aliased to the transform property.

state

State public

The state this Entity belongs to (either the current game state or a persistent world state)

text

String public

The text that you would like to appear in this textfield.

TEXT_ALIGN_CENTER

String public final static

A static property that contains the string to center align the text.

TEXT_ALIGN_LEFT

String public final static

A static property that contains the string to left align the text.

TEXT_ALIGN_RIGHT

String public final static

A static property that contains the string to right align the text.

textAlign

String public

Alignment of the text. You can either use the static TEXT_ALIGN constants or pass a string.

transform

Kiwi.Geom.Transform public

Represents the position, scale, rotation and registration of this Entity.

visible

Boolean public

Set the visibility of this entity. True or False.

Default: true

width

Number public

The width of the entity in pixels, pre-transform.

To obtain the actual width, multiply width by scaleX.

Default: 0

willRender

Boolean deprecated public

Inherited from Kiwi.Entity: src\core\Entity.ts:553

Deprecated: Use visible instead

Toggles if this Entity will be rendered.

Default: true

worldX

Number public

Inherited from Kiwi.Entity: src\core\Entity.ts:104

Available since 1.1.0

X coordinate of this Entity in world space; that is, after inheriting parent transforms. This is just aliased to the transform property. Property is READ-ONLY.

worldY

Number public

Inherited from Kiwi.Entity: src\core\Entity.ts:115

Available since 1.1.0

Y coordinate of this Entity in world space; that is, after inheriting parent transforms. This is just aliased to the transform property. Property is READ-ONLY.

x

Number public

X coordinate of this Entity. This is just aliased to the transform property.

y

Number public

Y coordinate of this Entity. This is just aliased to the transform property.