#include <CUTextField.h>

Inheritance diagram for cugl::scene2::TextField:

Public Types
typedef std::function< void(const std::string name, const std::string current)>	Listener

Public Member Functions
	TextField ()

	~TextField ()

virtual void	dispose () override

virtual bool	initWithData (const Scene2Loader *loader, const std::shared_ptr< JsonValue > &data) override

bool	hasTypeListener () const

const Listener	getTypeListener (Uint32 key) const

const std::vector< Listener >	getTypeListeners () const

Uint32	addTypeListener (Listener listener)

bool	removeTypeListener (Uint32 key)

void	clearTypeListeners ()

bool	hasExitListener () const

const Listener	getExitListener (Uint32 key) const

const std::vector< Listener >	getExitListeners () const

Uint32	addExitListener (Listener listener)

bool	removeExitListener (Uint32 key)

void	clearExitListeners ()

virtual void	setText (const std::string text, bool resize=false) override

bool	activate ()

bool	deactivate (bool dispose=false)

bool	isActive () const

bool	requestFocus ()

bool	releaseFocus ()

bool	hasFocus () const

const Rect &	getCursor () const

bool	isCursorVisible () const

void	setCursorVisible (bool visible)

float	getCursorWidth () const

void	setCursorWidth (float width)

Color4	getCursorColor () const

void	setCursorColor (const Color4 color)

virtual void	draw (const std::shared_ptr< SpriteBatch > &batch, const Affine2 &transform, Color4 tint) override

virtual void	generateRenderData () override

Public Member Functions inherited from cugl::scene2::Label
	Label ()

	~Label ()

virtual void	dispose () override

virtual bool	initWithPosition (const Vec2 pos) override

bool	initWithPosition (float x, float y)

virtual bool	initWithBounds (const Size size) override

virtual bool	initWithBounds (float width, float height) override

virtual bool	initWithBounds (const Rect rect) override

virtual bool	initWithBounds (float x, float y, float width, float height) override

bool	initWithText (const std::string text, const std::shared_ptr< Font > &font)

bool	initWithText (const Vec2 position, const std::string text, const std::shared_ptr< Font > &font)

bool	initWithTextBox (const Size size, const std::string text, const std::shared_ptr< Font > &font)

bool	initWithTextBox (const Rect rect, const std::string text, const std::shared_ptr< Font > &font)

virtual bool	initWithData (const Scene2Loader *loader, const std::shared_ptr< JsonValue > &data) override

const std::string	getText () const

virtual void	setText (const std::string text, bool resize=false)

std::shared_ptr< Font >	getFont () const

void	setFont (const std::shared_ptr< Font > &font, bool resize=false)

HorizontalAlign	getHorizontalAlignment () const

void	setHorizontalAlignment (HorizontalAlign halign)

VerticalAlign	getVerticalAlignment () const

void	setVerticalAlignment (VerticalAlign valign)

bool	getWrap () const

void	setWrap (bool wrap)

float	getSpacing () const

void	setSpacing (float spacing)

void	setPadding (float left, float bottom, float right, float top)

void	setPadding (float pad)

float	getPaddingLeft () const

void	setPaddingLeft (float left)

float	getPaddingBottom () const

void	setPaddingBottom (float bot)

float	getPaddingRight () const

void	setPaddingRight (float right)

float	getPaddingTop () const

void	setPaddingTop (float top)

const Rect	getInterior () const

void	setInterior (const Rect rect)

const Rect	getTextBounds () const

const Rect	getTrueBounds () const

virtual void	setContentSize (const Size size) override

virtual void	setContentSize (float width, float height) override

Color4	getForeground () const

void	setForeground (Color4 color)

Color4	getBackground () const

void	setBackground (Color4 color)

const Vec2 &	getDropShadow () const

void	setDropShadow (const Vec2 p)

void	setDropShadow (float x, float y)

float	getShadowBlur () const

void	setShadowBlur (float blur)

void	setBlendFunc (GLenum srcFactor, GLenum dstFactor)

GLenum	getSourceBlendFactor () const

GLenum	getDestinationBlendFactor () const

void	setBlendEquation (GLenum equation)

GLenum	getBlendEquation () const

virtual void	draw (const std::shared_ptr< SpriteBatch > &batch, const Affine2 &transform, Color4 tint) override

Public Member Functions inherited from cugl::scene2::SceneNode
	SceneNode ()

	~SceneNode ()

virtual void	dispose ()

virtual bool	init ()

virtual bool	initWithPosition (const Vec2 pos)

bool	initWithPosition (float x, float y)

virtual bool	initWithBounds (const Size size)

virtual bool	initWithBounds (float width, float height)

virtual bool	initWithBounds (const Rect rect)

virtual bool	initWithBounds (float x, float y, float width, float height)

virtual bool	initWithData (const Scene2Loader *loader, const std::shared_ptr< JsonValue > &data)

virtual std::shared_ptr< SceneNode >	copy (const std::shared_ptr< SceneNode > &dst) const

unsigned int	getTag () const

void	setTag (unsigned int tag)

const std::string	getName () const

void	setName (const std::string name)

const std::string	getClassName () const

virtual std::string	toString (bool verbose=false) const

	operator std::string () const

const Vec2	getPosition () const

void	setPosition (const Vec2 &position)

void	setPosition (float x, float y)

float	getPositionX (void) const

void	setPositionX (float x)

float	getPositionY (void) const

void	setPositionY (float y)

Vec2	getWorldPosition () const

const Size	getContentSize () const

virtual void	setContentSize (const Size size)

virtual void	setContentSize (float width, float height)

float	getContentWidth () const

void	setContentWidth (float width)

float	getContentHeight () const

void	setContentHeight (float height)

virtual Rect	getLayoutBounds () const

Size	getSize () const

float	getWidth () const

float	getHeight () const

Rect	getBoundingBox () const

virtual void	setAnchor (const Vec2 anchor)

virtual void	setAnchor (float x, float y)

const Vec2	getAnchor () const

Vec2	getAnchorInPixels ()

Color4	getColor () const

virtual void	setColor (Color4 color)

Color4	getAbsoluteColor ()

bool	isVisible () const

void	setVisible (bool visible)

bool	hasRelativeColor () const

void	setRelativeColor (bool flag)

std::shared_ptr< Scissor >	getScissor () const

void	setScissor (const std::shared_ptr< Scissor > &scissor)

void	setScissor ()

const Vec2	getScale () const

float	getScaleX () const

float	getScaleY () const

void	setScale (float scale)

void	setScale (const Vec2 vec)

void	setScale (float sx, float sy)

float	getAngle ()

void	setAngle (float angle)

const Affine2 &	getTransform () const

const Affine2 &	getAlternateTransform () const

void	setAlternateTransform (const Affine2 &transform)

bool	withAlternateTransform ()

void	chooseAlternateTransform (bool active)

const Affine2 &	getNodeToParentTransform () const

Affine2	getParentToNodeTransform () const

Affine2	getNodeToWorldTransform () const

Affine2	getWorldToNodeTransform () const

Vec2	screenToNodeCoords (const Vec2 screenPoint) const

Vec2	worldToNodeCoords (const Vec2 worldPoint) const

Vec2	nodeToScreenCoords (const Vec2 nodePoint) const

Vec2	nodeToWorldCoords (const Vec2 nodePoint) const

Vec2	parentToNodeCoords (const Vec2 parentPoint) const

Vec2	nodeToParentCoords (const Vec2 nodePoint) const

size_t	getChildCount () const

std::shared_ptr< SceneNode >	getChild (unsigned int pos)

const std::shared_ptr< SceneNode > &	getChild (unsigned int pos) const

template<typename T >
std::shared_ptr< T >	getChild (unsigned int pos) const

std::shared_ptr< SceneNode >	getChildByTag (unsigned int tag) const

template<typename T >
std::shared_ptr< T >	getChildByTag (unsigned int tag) const

std::shared_ptr< SceneNode >	getChildByName (const std::string name) const

template<typename T >
std::shared_ptr< T >	getChildByName (const std::string name) const

std::vector< std::shared_ptr< SceneNode > >	getChildren ()

const std::vector< std::shared_ptr< SceneNode > > &	getChildren () const

void	addChild (const std::shared_ptr< SceneNode > &child)

void	addChildWithTag (const std::shared_ptr< SceneNode > &child, unsigned int tag)

void	addChildWithName (const std::shared_ptr< SceneNode > &child, const std::string name)

void	swapChild (const std::shared_ptr< SceneNode > &child1, const std::shared_ptr< SceneNode > &child2, bool inherit=false)

SceneNode *	getParent ()

const SceneNode *	getParent () const

Scene2 *	getScene ()

const Scene2 *	getScene () const

void	removeFromParent ()

virtual void	removeChild (unsigned int pos)

void	removeChild (const std::shared_ptr< SceneNode > &child)

void	removeChildByTag (unsigned int tag)

void	removeChildByName (const std::string name)

virtual void	removeAllChildren ()

void	setPriority (float priority)

float	getPriority ()

virtual void	render (const std::shared_ptr< SpriteBatch > &batch, const Affine2 &transform, Color4 tint)

virtual void	render (const std::shared_ptr< SpriteBatch > &batch)

virtual void	draw (const std::shared_ptr< SpriteBatch > &batch, const Affine2 &transform, Color4 tint)

const std::shared_ptr< Layout > &	getLayout () const

void	setLayout (const std::shared_ptr< Layout > &layout)

virtual void	doLayout ()

Static Public Member Functions
static std::shared_ptr< TextField >	allocWithBounds (const Size size)

static std::shared_ptr< TextField >	allocWithBounds (float width, float height)

static std::shared_ptr< TextField >	allocWithBounds (const Rect rect)

static std::shared_ptr< TextField >	allocWithBounds (float x, float y, float width, float height)

static std::shared_ptr< TextField >	allocWithText (const std::string text, const std::shared_ptr< Font > &font)

static std::shared_ptr< TextField >	allocWithText (const Vec2 position, const std::string text, const std::shared_ptr< Font > &font)

static std::shared_ptr< TextField >	allocWithTextBox (const Size size, const std::string text, const std::shared_ptr< Font > &font)

static std::shared_ptr< TextField >	allocWithTextBox (const Rect rect, const std::string text, const std::shared_ptr< Font > &font)

static std::shared_ptr< SceneNode >	allocWithData (const Scene2Loader *loader, const std::shared_ptr< JsonValue > data)

Static Public Member Functions inherited from cugl::scene2::Label
static std::shared_ptr< Label >	allocWithBounds (const Size size)

static std::shared_ptr< Label >	allocWithBounds (float width, float height)

static std::shared_ptr< Label >	allocWithBounds (const Rect rect)

static std::shared_ptr< Label >	allocWithBounds (float x, float y, float width, float height)

static std::shared_ptr< Label >	allocWithText (const std::string text, const std::shared_ptr< Font > &font)

static std::shared_ptr< Label >	allocWithText (const Vec2 position, const std::string text, const std::shared_ptr< Font > &font)

static std::shared_ptr< Label >	allocWithTextBox (const Size size, const std::string text, const std::shared_ptr< Font > &font)

static std::shared_ptr< Label >	allocWithTextBox (const Rect rect, const std::string text, const std::shared_ptr< Font > &font)

static std::shared_ptr< SceneNode >	allocWithData (const Scene2Loader *loader, const std::shared_ptr< JsonValue > &data)

Static Public Member Functions inherited from cugl::scene2::SceneNode
static std::shared_ptr< SceneNode >	alloc ()

static std::shared_ptr< SceneNode >	allocWithPosition (const Vec2 pos)

static std::shared_ptr< SceneNode >	allocWithPosition (float x, float y)

static std::shared_ptr< SceneNode >	allocWithBounds (const Size size)

static std::shared_ptr< SceneNode >	allocWithBounds (float width, float height)

static std::shared_ptr< SceneNode >	allocWithBounds (const Rect rect)

static std::shared_ptr< SceneNode >	allocWithBounds (float x, float y, float width, float height)

static std::shared_ptr< SceneNode >	allocWithData (const Scene2Loader *loader, const std::shared_ptr< JsonValue > &data)

Protected Member Functions
void	updateInput (const TextInputEvent &event, bool focus)

void	updateKey (const KeyEvent &event, bool focus, bool down)

void	updatePress (Vec2 pos, bool focus)

void	updateCursor ()

size_t	skipWord (bool forward) const

void	deleteChar ()

void	leftArrow ()

void	rightArrow ()

void	upArrow ()

void	downArrow ()

size_t	insertChar (Uint32 unicode, size_t pos)

size_t	breakLine (size_t pos)

size_t	getCharIndex (size_t row, float &offset) const

size_t	getCharRow () const

void	invokeListeners (bool exit)

Protected Member Functions inherited from cugl::scene2::Label
virtual void	generateRenderData ()

void	clearRenderData ()

void	updateColor ()

void	resize ()

void	reanchor ()

Protected Attributes
size_t	_charsize

Rect	_cursor

int	_cursorBlink

size_t	_cursorIndex

bool	_showCursor

float	_cursorWidth

Color4	_cursorColor

bool	_active

bool	_focused

bool	_mouse

Uint32	_tkey

Uint32	_kkey

Uint32	_fkey

Uint32	_nextKey

std::unordered_map< Uint32, Listener >	_typeListeners

std::unordered_map< Uint32, Listener >	_exitListeners

bool	_altDown

bool	_metaDown

bool	_shiftDown

size_t	_keyCount

Protected Attributes inherited from cugl::scene2::Label
std::shared_ptr< Font >	_font

std::shared_ptr< TextLayout >	_layout

Vec2	_offset

float	_padbot

float	_padleft

float	_padtop

float	_padrght

bool	_dropShadow

float	_dropBlur

Vec2	_dropOffset

Color4	_foreground

Color4	_background

GLenum	_blendEquation

GLenum	_srcFactor

GLenum	_dstFactor

bool	_rendered

Rect	_bounds

std::unordered_map< GLuint, std::shared_ptr< GlyphRun > >	_glyphrun

Protected Attributes inherited from cugl::scene2::SceneNode
Vec2	_position

Vec2	_anchor

Size	_contentSize

Color4	_tintColor

bool	_hasParentColor

bool	_isVisible

std::shared_ptr< Scissor >	_scissor

Vec2	_scale

float	_angle

Affine2	_transform

bool	_useTransform

Affine2	_combined

std::vector< std::shared_ptr< SceneNode > >	_children

SceneNode *	_parent

Scene2 *	_graph

std::shared_ptr< Layout >	_layout

int	_childOffset

unsigned int	_tag

std::string	_name

size_t	_hashOfName

std::string	_classname

float	_priority

std::shared_ptr< JsonValue >	_json

Detailed Description

This class represents a single line text field.

A text field is a subclass of {link Label} that permits the user to edit it when focused (e.g. when it is selected to receive keyboard events). A focused field displays a blinking cursor with the current edit position. There is no cursor displayed when the field does not have focus.

The textfield can track its own state, via the activate() method, relieving you of having to manually the keyboard. In addition, it also reponds to mouse/touch input, allowing you to reposition the cursor and either focus or unfocus the text field. However, the appropriate input devices must be active before you can activate the text fields, as it needs to attach internal listeners. These devices include TextInput, Keyboard, and either Mouse or Touchscreen.

The text field supports two category of listeners. The first tracks any changes to the text. The second only updates when the field loses focus, such as when the user presses return.

As with Label, a text field is able to support multiline text. In addition, the user can navigate this text with the arrow keys or by using the mouse/touch to reposition the cursor. With that said, this class is is designed for small-to-medium sized segments of text. It is not designed to be an all-purpose text editor for managing large strings. That is because every single edit (no matter how small) will reformat the entire text.

Member Typedef Documentation

◆ Listener

cugl::scene2::TextField::Listener

This type represents a listener for text change in the TextField class.

In CUGL, listeners are implemented as a set of callback functions, not as objects. This allows each listener to implement as much or as little functionality as it wants. For simplicity, TextField nodes only support a single listener. If you wish for more than one listener, then your listener should handle its own dispatch.

The function type is equivalent to

 std::function<void (const std::string name, const std::string current)>

Parameters

name	The text field name
current	Text after editing

Constructor & Destructor Documentation

◆ TextField()

cugl::scene2::TextField::TextField ( )

Creates an uninitialized text field with no size or font.

You must initialize this field before use.

NEVER USE A CONSTRUCTOR WITH NEW. If you want to allocate a Node on the heap, use one of the static constructors instead.

◆ ~TextField()

cugl::scene2::TextField::~TextField ( )

inline

Deletes this text field, disposing all resources

It is unsafe to call this on a text field that is still currently inside of a scene graph.

Member Function Documentation

◆ activate()

bool cugl::scene2::TextField::activate ( )

Activates this text field to enable editing.

This method attaches a listener to either the Mouse or Touchscreen inputs to monitor when the text field is pressed and/or released. The text field will favor the mouse, but will use the touch screen if no mouse input is active. If neither input is active, this method will fail.

It will also attach a listener to TextInput to provide access to a (possibly virtual) keyboard and collect user typing. Finally, it attaches a liatener to Keyboard to monitor special keys such as Alt, Meta, and the arrow keys.

Notice that activating a text field and requesting focus is separate. The field will request focus if selected by a touch or press, but it cannot be editted until it has focus.

Returns: true if the text field was successfully activated

◆ addExitListener()

Uint32 cugl::scene2::TextField::addExitListener ( Listener listener )

Returns a key for a exit listener after adding it to this field.

This listener is invoked when the field loses focus.

C++ cannot hash functions types. Therefore, the listener will be identified by a unique key, returned by this function. You should remember this key to remove the listener if necessary.

Parameters

listener The listener to add

Returns: the key for the listener

◆ addTypeListener()

Uint32 cugl::scene2::TextField::addTypeListener ( Listener listener )

Returns a key for a type listener after adding it to this text field.

This listener is invoked when the text changes.

C++ cannot hash functions types. Therefore, the listener will be identified by a unique key, returned by this function. You should remember this key to remove the listener if necessary.

Parameters

listener The listener to add

Returns: the key for the listener

◆ allocWithBounds() [1/4]

static std::shared_ptr< TextField > cugl::scene2::TextField::allocWithBounds ( const Rect rect )

inlinestatic

Returns a newly allocated text field with the given bounds.

The rectangle origin is the bottom left corner of the node in parent space, and corresponds to the origin of the Node space. The size defines its content width and height in node space. The node anchor is placed in the bottom left corner.

The label will empty, as it has no font or text.

Parameters

rect	The bounds of the text field in parent space

Returns: a newly allocated text field with the given bounds.

◆ allocWithBounds() [2/4]

static std::shared_ptr< TextField > cugl::scene2::TextField::allocWithBounds ( const Size size )

inlinestatic

Returns a newly allocated text field with the given size.

The size defines the content size. The bounding box of the node is (0,0,width,height) and is anchored in the bottom left corner (0,0). The node is positioned at the origin in parent space.

The label will empty, as it has no font or text.

Parameters

size	The size of the text field in parent space

Returns: a newly allocated text field with the given size.

◆ allocWithBounds() [3/4]

static std::shared_ptr< TextField > cugl::scene2::TextField::allocWithBounds	(	float	width,
		float	height
	)

inlinestatic

Returns a newly allocated text field with the given size.

The size defines the content size. The bounding box of the node is (0,0,width,height) and is anchored in the bottom left corner (0,0). The node is positioned at the origin in parent space.

The label will empty, as it has no font or text.

Parameters

width	The width of the text field in parent space
height	The height of the text field in parent space

Returns: a newly allocated text field with the given size.

◆ allocWithBounds() [4/4]

static std::shared_ptr< TextField > cugl::scene2::TextField::allocWithBounds	(	float	x,
		float	y,
		float	width,
		float	height
	)

inlinestatic

Returns a newly allocated text field with the given bounds.

The rectangle origin is the bottom left corner of the node in parent space, and corresponds to the origin of the Node space. The size defines its content width and height in node space. The node anchor is placed in the bottom left corner.

The label will empty, as it has no font or text.

Parameters

x	The x-coordinate of the origin in parent space
y	The y-coordinate of the origin in parent space
width	The width of the text field in parent space
height	The height of the text field in parent space

Returns: a newly allocated text field with the given bounds.

◆ allocWithData()

static std::shared_ptr< SceneNode > cugl::scene2::TextField::allocWithData	(	const Scene2Loader *	loader,
		const std::shared_ptr< JsonValue >	data
	)

inlinestatic

Returns a newly allocated node with the given JSON specificaton.

This initializer is designed to receive the "data" object from the JSON passed to Scene2Loader. This JSON format supports all of the attribute values of its parent class. In addition, it supports the following additional attributes:

"cursor":        A boolean indicating whether to show the cursor (when active)
"cursorwidth":   A number indicating the width of the cursor rectangle
"cursorcolor":   Either a four-element integer array (values 0..255) or a string
                 Any string should be a web color or a Tkinter color name.

All attributes are optional. There are no required attributes.

Parameters

loader	The scene loader passing this JSON file
data	The JSON object specifying the node

Returns: a newly allocated node with the given JSON specificaton.

◆ allocWithText() [1/2]

static std::shared_ptr< TextField > cugl::scene2::TextField::allocWithText	(	const std::string	text,
		const std::shared_ptr< Font > &	font
	)

inlinestatic

Returns a newly allocated text field with the given text and font

The text field will be sized to fit the rendered text exactly. That is, the height will be the maximum height of the font, and the width will be the sum of the advance of the rendered characters. That means that there may be some natural spacing around the characters.

By default, the text will formated so that the origin is on the left edge of the baseline (of the top line). The text will take up a single line unless there are newline characters in the string. If any glyphs are missing from the font atlas, they will not be rendered.

The text will be placed at the origin of the parent and will be anchored in the bottom left corner.

Parameters

text	The text to display in the text field
font	The font for this text field

Returns: a newly allocated text field with the given text and font atlas

◆ allocWithText() [2/2]

static std::shared_ptr< TextField > cugl::scene2::TextField::allocWithText	(	const Vec2	position,
		const std::string	text,
		const std::shared_ptr< Font > &	font
	)

inlinestatic

Returns a newly allocated text field with the given text and font

The text field will be sized to fit the rendered text exactly. That is, the height will be the maximum height of the font, and the width will be the sum of the advance of the rendered characters. That means that there may be some natural spacing around the characters.

By default, the text will formated so that the origin is on the left edge of the baseline (of the top line). The text will take up a single line unless there are newline characters in the string. If any glyphs are missing from the font atlas, they will not be rendered.

The text will be placed at the origin of the parent and will be anchored in the bottom left corner.

Parameters

position	The text field position
text	The text to display in the text field
font	The font for this text field

Returns: a newly allocated text field with the given text and font atlas

◆ allocWithTextBox() [1/2]

static std::shared_ptr< TextField > cugl::scene2::TextField::allocWithTextBox	(	const Rect	rect,
		const std::string	text,
		const std::shared_ptr< Font > &	font
	)

inlinestatic

Returns a newly allocated multiline text field with the given dimensions

The text field will use the size specified and attempt to fit the text in this region. Lines will be broken at white space locations to keep each line within the size width. However, this may result in so many lines that glyphs at the bottom are cut out. A label will never render text outside of its content bounds.

By default, a multiline text field is aligned to the top and left. It has a line spacing of 1 (single-spaced).

The label will use the rectangle origin to position this label in its parent. It will be anchored in the bottom left.

Parameters

rect	The bounds of the text field to display
text	The text to display in the text field
font	The font for this text field

Returns: a newly allocated multiline text field with the given dimensions

◆ allocWithTextBox() [2/2]

static std::shared_ptr< TextField > cugl::scene2::TextField::allocWithTextBox	(	const Size	size,
		const std::string	text,
		const std::shared_ptr< Font > &	font
	)

inlinestatic

Returns a newly allocated multiline text field with the given dimensions

The text field will use the size specified and attempt to fit the text in this region. Lines will be broken at white space locations to keep each line within the size width. However, this may result in so many lines that glyphs at the bottom are cut out. A label will never render text outside of its content bounds.

By default, a multiline text field is aligned to the top and left. It has a line spacing of 1 (single-spaced).

The label will be placed at the origin of the parent and will be anchored in the bottom left.

Parameters

size	The size of the text field to display
text	The text to display in the text field
font	The font for this text field

Returns: a newly allocated multiline text field with the given dimensions

◆ breakLine()

size_t cugl::scene2::TextField::breakLine ( size_t pos )

protected

Inserts a newline character into the text

This method will force a recomputation of the layout.

Parameters

pos	The position to insert the newline

◆ clearExitListeners()

void cugl::scene2::TextField::clearExitListeners ( )

Clears all listeners for this text field.

These listener are invoked when the field loses focus. This method does not require you to remember the keys assigned to the individual listeners.

◆ clearTypeListeners()

void cugl::scene2::TextField::clearTypeListeners ( )

Clears all type listeners for this text field.

These listeners are invoked when the text changes. This method does not require you to remember the keys assigned to the individual listeners.

◆ deactivate()

bool cugl::scene2::TextField::deactivate ( bool dispose = false )

Deactivates this text field, ignoring any future input.

This method removes its internal listener from either the Mouse or Touchscreen, and from Keyboard and TextInput.

When deactivated, the text field will no longer change its text on its own. However, the user can still change manually with the setText() method. Futhermore, the appropriate type listener will be called when the text changes. However, any attempts to manually acquire focus will fail.

Parameters

dispose Whether this request is the result of a dispose action

Returns: true if the text field was successfully deactivated

◆ deleteChar()

void cugl::scene2::TextField::deleteChar ( )

protected

Deletes one character before the current cursor.

If alt is pressed, the method will delete an entire word. If meta is pressed, it will delete the entire field. If the deletion key is held down, this method will be called multiple times in a row after a short delay, lasting until the key is released.

◆ dispose()

virtual void cugl::scene2::TextField::dispose ( )

overridevirtual

Disposes all of the resources used by this text field.

A disposed text field can be safely reinitialized. Any child will be released. They will be deleted if no other object owns them.

It is unsafe to call this on a text field that is still currently inside of a scene graph.

Reimplemented from cugl::scene2::Label.

◆ downArrow()

void cugl::scene2::TextField::downArrow ( )

protected

Moves the cursor one line down.

The cursor is moved "visually". That is, it is moved to the edit position that is closest horizontally to the original position. In the case of monospaced fonts, this insures that the cursor maintains the same number of characters from the start of the line. However, this is not the case for proportional fonts.

◆ draw()

virtual void cugl::scene2::TextField::draw	(	const std::shared_ptr< SpriteBatch > &	batch,
		const Affine2 &	transform,
		Color4	tint
	)

overridevirtual

Draws this text field via the given SpriteBatch.

This method only worries about drawing the current text field. It does not attempt to render the children.

This method provides the correct transformation matrix and tint color. You do not need to worry about whether the node uses relative color. This method is called by render() and these values are guaranteed to be correct. In addition, this method does not need to check for visibility, as it is guaranteed to only be called when the node is visible.

This method overrides the one from Label. It adds the drawing of a blinking cursor that indicates the edit position.

Parameters

batch	The SpriteBatch to draw with.
transform	The global transformation matrix.
tint	The tint to blend with the Node color.

Reimplemented from cugl::scene2::Label.

◆ generateRenderData()

virtual void cugl::scene2::TextField::generateRenderData ( )

overridevirtual

Allocates the render data necessary to render this node.

Reimplemented from cugl::scene2::Label.

◆ getCharIndex()

size_t cugl::scene2::TextField::getCharIndex	(	size_t	row,
		float &	offset
	)		const

protected

Returns the index for the given row and x-coordinate

The method is used to place the cursor position from either a mouse/touch click, or an up/down arrow. The value offset is adjusted to be center of the cursor, preventing us from having to call updateCursor.

In determining the cursor position, this method find the nearest character to offset. It moves the cursor to either the left or right of this character depending on which side of the character centerline this offset sits.

Parameters

row	The text row
offset	The x-coordinate to place the cursor

Returns: the index for the given row and x-coordinate

◆ getCharRow()

size_t cugl::scene2::TextField::getCharRow ( ) const

protected

Returns the text row for the current cursor position.

Returns: the text row for the current cursor position.

◆ getCursor()

const Rect & cugl::scene2::TextField::getCursor ( ) const

inline

Returns the cursor rectangle.

The cursor is a rectangle indicating the editing position of the text field. It has width getCursorWidth, and its height is the line height. It is centered on the insertion position.

By default, this cursor will be shown (blinking) when the text field has focus. However, it is possible to disable the cursor by calling setCursorVisible. That will hide the cursor even when editing is active. You can then use this rectangle to overlay your own custom cursor image.

Returns: the cursor rectangle.

◆ getCursorColor()

Color4 cugl::scene2::TextField::getCursorColor ( ) const

inline

Returns the cursor color

If the cursor is visible, then it will be drawn (when active) as a solid rectangle with this color. By default, this value is black.

Returns: the cursor color

◆ getCursorWidth()

float cugl::scene2::TextField::getCursorWidth ( ) const

inline

Returns the cursor width.

The cursor is always a simple rectangle, though this rectangle can be accessed by getCursor to draw a custom cursor image. While the cursor always has the line height as its height, this value controls the width. The cursor is always centered on the insertion position.

Returns: the cursor width.

◆ getExitListener()

const Listener cugl::scene2::TextField::getExitListener ( Uint32 key ) const

Returns the exit listener for the given key

This listener is invoked when the field loses focus.

If there is no listener for the given key, it returns nullptr.

Parameters

key	The identifier for the listener

Returns: the listener for the given key

◆ getExitListeners()

const std::vector< Listener > cugl::scene2::TextField::getExitListeners ( ) const

Returns all exit listeners for this text field

These listeners are invoked when the field loses focus.

Returns: the exits listeners for this text field

◆ getTypeListener()

const Listener cugl::scene2::TextField::getTypeListener ( Uint32 key ) const

Returns the type listener for the given key

This listener is invoked when the text changes.

If there is no listener for the given key, it returns nullptr.

Parameters

key	The identifier for the listener

Returns: the type listener for the given key

◆ getTypeListeners()

const std::vector< Listener > cugl::scene2::TextField::getTypeListeners ( ) const

Returns all type listeners for this text field

This listener is invoked when the text changes.

Returns: the type listeners for this text field

◆ hasExitListener()

bool cugl::scene2::TextField::hasExitListener ( ) const

inline

Returns true if this text field has an exit listener

This listener is invoked when the field loses focus.

Returns: true if this text field has an exit listener

◆ hasFocus()

bool cugl::scene2::TextField::hasFocus ( ) const

inline

Returns true if this text field has focus.

Returns: true if this text field has focus.

◆ hasTypeListener()

bool cugl::scene2::TextField::hasTypeListener ( ) const

inline

Returns true if this text field has a type listener

This listener is invoked when the text changes.

Returns: true if this text field has a type listener

◆ initWithData()

virtual bool cugl::scene2::TextField::initWithData	(	const Scene2Loader *	loader,
		const std::shared_ptr< JsonValue > &	data
	)

overridevirtual

Initializes a node with the given JSON specificaton.

This initializer is designed to receive the "data" object from the JSON passed to Scene2Loader. This JSON format supports all of the attribute values of its parent class. In addition, it supports the following additional attributes:

"cursor":        A boolean indicating whether to show the cursor (when active)
"cursorwidth":   A number indicating the width of the cursor rectangle
"cursorcolor":   Either a four-element integer array (values 0..255) or a string
                 Any string should be a web color or a Tkinter color name.

All attributes are optional. There are no required attributes.

Parameters

loader	The scene loader passing this JSON file
data	The JSON object specifying the node

Returns: true if initialization was successful.

Reimplemented from cugl::scene2::Label.

◆ insertChar()

size_t cugl::scene2::TextField::insertChar	(	Uint32	unicode,
		size_t	pos
	)

protected

Inserts the given unicode character into the text

This method will force a recomputation of the layout.

Parameters

unicode	The unicode character
pos	The position to insert the character

◆ invokeListeners()

void cugl::scene2::TextField::invokeListeners ( bool exit )

protected

Invokes the appropriate listeners for this text field.

If exit is true, it invokes the exit listeners. Otherwise it invokes the type listeners.

Parameters

exit	Whether to invoke the exit listeners

◆ isActive()

bool cugl::scene2::TextField::isActive ( ) const

inline

Returns true if this text field has been activated.

Returns: true if this text field has been activated.

◆ isCursorVisible()

bool cugl::scene2::TextField::isCursorVisible ( ) const

inline

Returns true if the cursor is visible (when active).

By default, the cursor will be shown (blinking) when the text field has focus. Hiding the cursor allows you to replace it with your own custom cursor image. The text field will still track the cursor rectangle; it just will not show it.

Returns: true if the cursor is visible (when active).

◆ leftArrow()

void cugl::scene2::TextField::leftArrow ( )

protected

Moves the cursor one position to the left.

If the label is multiline, this will move the cursor from the beginning of line to the end of the next. Nothing will happen if the cursor is at the start of the text.

◆ releaseFocus()

bool cugl::scene2::TextField::releaseFocus ( )

Releases text input focus for this text field.

When the focus is released, the label can no longer be editting. Typically this means that the user has input the final value, which is why the exit listener (if any exists) is called.

In addition to calling this method manually, a user can release focus either by pressing RETURN or clicking somewhere outside of the field.

Returns: true if successfully released focus.

◆ removeExitListener()

bool cugl::scene2::TextField::removeExitListener ( Uint32 key )

Removes a listener from this text fieldexi.

This listener is invoked when the field loses focus.

Listeners must be identified by the key returned by the addExitListener method. If this text field does not have a listener for the given key, this method will fail.

Parameters

key	The key of the listener to remove

Returns: true if the listener was succesfully removed

◆ removeTypeListener()

bool cugl::scene2::TextField::removeTypeListener ( Uint32 key )

Removes a type listener from this text field.

This listener is invoked when the text changes.

Listeners must be identified by the key returned by the addTypeListener method. If this text field does not have a listener for the given key, this method will fail.

Parameters

key	The key of the listener to remove

Returns: true if the listener was succesfully removed

◆ requestFocus()

bool cugl::scene2::TextField::requestFocus ( )

Requests text input focus for this text field.

When a text field is activated, it does not immediately have focus. A text field without focus cannot be editted. By either clicking on the field or calling thus function, you can acquire focus and edit the field.

This method will fail if the text field is not active.

Returns: true if successfully requested focus.

◆ rightArrow()

void cugl::scene2::TextField::rightArrow ( )

protected

Moves the cursor one position to the right.

If the label is multiline, this will move the cursor from the end of a line to the beginning of the next. Nothing will happen if the cursor is at the end of the text.

◆ setCursorColor()

void cugl::scene2::TextField::setCursorColor ( const Color4 color )

inline

Sets the cursor color

If the cursor is visible, then it will be drawn (when active) as a solid rectangle with this color. By default, this value is black.

Parameters

color The cursor color

◆ setCursorVisible()

void cugl::scene2::TextField::setCursorVisible ( bool visible )

inline

Sets whether the cursor is visible (when active).

By default, the cursor will be shown (blinking) when the text field has focus. Hiding the cursor allows you to replace it with your own custom cursor image. The text field will still track the cursor rectangle; it just will not show it.

Parameters

visible Whether the cursor is visible (when active).

◆ setCursorWidth()

void cugl::scene2::TextField::setCursorWidth ( float width )

inline

Sets the cursor width.

The cursor is always a simple rectangle, though this rectangle can be accessed by getCursor to draw a custom cursor image. While the cursor always has the line height as its height, this value controls the width. The cursor is always centered on the insertion position.

Parameters

width The cursor width.

◆ setText()

virtual void cugl::scene2::TextField::setText	(	const std::string	text,
		bool	resize = `false`
	)

overridevirtual

Sets the text for this label.

The string must be in either ASCII or UTF8 format. No other string encodings are supported. As all ASCII strings are also UTF8, you can this effectively means that the text must be UTF8.

If the font is missing glyphs in this string, the characters in the text may be different than those displayed. Furthermore, if this label has no font, then the text will not display at all.

Changing this value will regenerate the render data, and is potentially expensive, particularly if the font is using a fallback atlas.

Reseting this value will naturally put the cursor at the end of the text.

Parameters

text	The text for this label.
resize	Whether to resize the label to fit the new text.

Reimplemented from cugl::scene2::Label.

◆ skipWord()

size_t cugl::scene2::TextField::skipWord ( bool forward ) const

protected

Moves the cursor one word forward or backward.

If there is any space between the cursor and the word in the correct direction, it will move adjacent to the word. Otherwise, it will skip over the word.

Parameters

forward Whether to move the cursor forward.

Returns: the index of the new cursor position

◆ upArrow()

void cugl::scene2::TextField::upArrow ( )

protected

Moves the cursor one line up.

The cursor is moved "visually". That is, it is moved to the edit position that is closest horizontally to the original position. In the case of monospaced fonts, this insures that the cursor maintains the same number of characters from the start of the line. However, this is not the case for proportional fonts.

◆ updateCursor()

void cugl::scene2::TextField::updateCursor ( )

protected

Updates the cursor position.

This method is called whenever either the text changes or the cursor moves. Notice that this must be updated even if the cursor is not visible.

◆ updateInput()

void cugl::scene2::TextField::updateInput	(	const TextInputEvent &	event,
		bool	focus
	)

protected

Updates the text with the given input data.

This method is a callback for the TextInput device.

Parameters

event	The text input event to be handled.
focus	Whether the text field currently has text input focus.

◆ updateKey()

void cugl::scene2::TextField::updateKey	(	const KeyEvent &	event,
		bool	focus,
		bool	down
	)

protected

Updates the state of any special keys.

This method is a callback for the Keyboard device.

Parameters

event	The key event to be handled.
focus	Whether the text field currently has keyboard focus
down	Whether the key is pressed down (as opposed to released)

◆ updatePress()

void cugl::scene2::TextField::updatePress	(	Vec2	pos,
		bool	focus
	)

protected

Responds to a touch or press, changing the field focus.

If the press is outside text field, focus will be released. If the press is within the bounds, it will request focus (if not currently in focus) and move the cursor to the position pressed.

Parameters

pos	The screen coordinate where the event happened.
focus	Whether the text field currently has keyboard focus

Member Data Documentation

◆ _active

bool cugl::scene2::TextField::_active

protected

Whether the field is actively checking for state changes

◆ _altDown

bool cugl::scene2::TextField::_altDown

protected

Whether the Alt key is down (used for word level editing)

◆ _charsize

size_t cugl::scene2::TextField::_charsize

protected

The current number of characters in the input

◆ _cursor

Rect cugl::scene2::TextField::_cursor

protected

The current cursor rectangle,

◆ _cursorBlink

int cugl::scene2::TextField::_cursorBlink

protected

Timer for blinking the cursor.

◆ _cursorColor

Color4 cugl::scene2::TextField::_cursorColor

protected

The current cursor color

◆ _cursorIndex

size_t cugl::scene2::TextField::_cursorIndex

protected

Cursor position indexed from the start of the text. 0 (before) start.

◆ _cursorWidth

float cugl::scene2::TextField::_cursorWidth

protected

The width of the cursor rectangle

◆ _exitListeners

std::unordered_map<Uint32,Listener> cugl::scene2::TextField::_exitListeners

protected

The listener callbacks for loss of focus

◆ _fkey

Uint32 cugl::scene2::TextField::_fkey

protected

The (master) focus key when the text field is checking for events

◆ _focused

bool cugl::scene2::TextField::_focused

protected

Whether the field is actively receiving keyboad events

◆ _keyCount

size_t cugl::scene2::TextField::_keyCount

protected

A timer to safely implement key hold-downs

◆ _kkey

Uint32 cugl::scene2::TextField::_kkey

protected

The (master) keyboard key when the text field is checking for events

◆ _metaDown

bool cugl::scene2::TextField::_metaDown

protected

Whether the Meta key is down (used for line level editing)

◆ _mouse

bool cugl::scene2::TextField::_mouse

protected

Whether we are using the mouse (as opposed to the touch screen)

◆ _nextKey

Uint32 cugl::scene2::TextField::_nextKey

protected

The key distributer for user-level listeners

◆ _shiftDown

bool cugl::scene2::TextField::_shiftDown

protected

Whether the Shift key is down (used for line level editing)

◆ _showCursor

bool cugl::scene2::TextField::_showCursor

protected

Whether to show the cursor (as opposed to just tracking the position)

◆ _tkey

Uint32 cugl::scene2::TextField::_tkey

protected

The (master) text input key when the text field is checking for events

◆ _typeListeners

std::unordered_map<Uint32,Listener> cugl::scene2::TextField::_typeListeners

protected

The listener callbacks for text changes

The documentation for this class was generated from the following file:

cugl/include/cugl/scene2/ui/CUTextField.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ Listener

Constructor & Destructor Documentation

◆ TextField()

◆ ~TextField()

Member Function Documentation

◆ activate()

◆ addExitListener()

◆ addTypeListener()

◆ allocWithBounds() [1/4]

◆ allocWithBounds() [2/4]

◆ allocWithBounds() [3/4]

◆ allocWithBounds() [4/4]

◆ allocWithData()

◆ allocWithText() [1/2]

◆ allocWithText() [2/2]

◆ allocWithTextBox() [1/2]

◆ allocWithTextBox() [2/2]

◆ breakLine()

◆ clearExitListeners()

◆ clearTypeListeners()

◆ deactivate()

◆ deleteChar()

◆ dispose()

◆ downArrow()

◆ draw()

◆ generateRenderData()

◆ getCharIndex()

◆ getCharRow()

◆ getCursor()

◆ getCursorColor()

◆ getCursorWidth()

◆ getExitListener()

◆ getExitListeners()

◆ getTypeListener()

◆ getTypeListeners()

◆ hasExitListener()

◆ hasFocus()

◆ hasTypeListener()

◆ initWithData()

◆ insertChar()

◆ invokeListeners()

◆ isActive()

◆ isCursorVisible()

◆ leftArrow()

◆ releaseFocus()

◆ removeExitListener()

◆ removeTypeListener()

◆ requestFocus()

◆ rightArrow()

◆ setCursorColor()

◆ setCursorVisible()

◆ setCursorWidth()

◆ setText()

◆ skipWord()

◆ upArrow()

◆ updateCursor()

◆ updateInput()

◆ updateKey()

◆ updatePress()

Member Data Documentation

◆ _active

◆ _altDown

◆ _charsize

◆ _cursor

◆ _cursorBlink

◆ _cursorColor

◆ _cursorIndex

◆ _cursorWidth

◆ _exitListeners

◆ _fkey

◆ _focused

◆ _keyCount

◆ _kkey