CUGL 2.1
Cornell University Game Library
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
cugl::scene2::TextField Class Reference

#include <CUTextField.h>

Inheritance diagram for cugl::scene2::TextField:
cugl::scene2::Label cugl::scene2::SceneNode

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< ListenergetTypeListeners () const
 
Uint32 addTypeListener (Listener listener)
 
bool removeTypeListener (Uint32 key)
 
void clearTypeListeners ()
 
bool hasExitListener () const
 
const Listener getExitListener (Uint32 key) const
 
const std::vector< ListenergetExitListeners () 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 RectgetCursor () 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 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)
 
const std::string & getText () const
 
std::shared_ptr< FontgetFont () 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 Vec2getDropShadow () 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
 
- Public Member Functions inherited from cugl::scene2::SceneNode
 SceneNode ()
 
 ~SceneNode ()
 
virtual bool init ()
 
bool initWithPosition (float x, float y)
 
virtual std::shared_ptr< SceneNodecopy (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
 
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< ScissorgetScissor () 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 Affine2getTransform () const
 
const Affine2getAlternateTransform () const
 
void setAlternateTransform (const Affine2 &transform)
 
bool withAlternateTransform ()
 
void chooseAlternateTransform (bool active)
 
const Affine2getNodeToParentTransform () 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< SceneNodegetChild (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< SceneNodegetChildByTag (unsigned int tag) const
 
template<typename T >
std::shared_ptr< T > getChildByTag (unsigned int tag) const
 
std::shared_ptr< SceneNodegetChildByName (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)
 
SceneNodegetParent ()
 
const SceneNodegetParent () const
 
Scene2getScene ()
 
const Scene2getScene () 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)
 
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< TextFieldallocWithBounds (const Size size)
 
static std::shared_ptr< TextFieldallocWithBounds (float width, float height)
 
static std::shared_ptr< TextFieldallocWithBounds (const Rect rect)
 
static std::shared_ptr< TextFieldallocWithBounds (float x, float y, float width, float height)
 
static std::shared_ptr< TextFieldallocWithText (const std::string text, const std::shared_ptr< Font > &font)
 
static std::shared_ptr< TextFieldallocWithText (const Vec2 position, const std::string text, const std::shared_ptr< Font > &font)
 
static std::shared_ptr< TextFieldallocWithTextBox (const Size size, const std::string text, const std::shared_ptr< Font > &font)
 
static std::shared_ptr< TextFieldallocWithTextBox (const Rect rect, const std::string text, const std::shared_ptr< Font > &font)
 
static std::shared_ptr< SceneNodeallocWithData (const Scene2Loader *loader, const std::shared_ptr< JsonValue > data)
 
- Static Public Member Functions inherited from cugl::scene2::Label
static std::shared_ptr< LabelallocWithBounds (const Size size)
 
static std::shared_ptr< LabelallocWithBounds (float width, float height)
 
static std::shared_ptr< LabelallocWithBounds (const Rect rect)
 
static std::shared_ptr< LabelallocWithBounds (float x, float y, float width, float height)
 
static std::shared_ptr< LabelallocWithText (const std::string text, const std::shared_ptr< Font > &font)
 
static std::shared_ptr< LabelallocWithText (const Vec2 position, const std::string text, const std::shared_ptr< Font > &font)
 
static std::shared_ptr< LabelallocWithTextBox (const Size size, const std::string text, const std::shared_ptr< Font > &font)
 
static std::shared_ptr< LabelallocWithTextBox (const Rect rect, const std::string text, const std::shared_ptr< Font > &font)
 
static std::shared_ptr< SceneNodeallocWithData (const Scene2Loader *loader, const std::shared_ptr< JsonValue > &data)
 
- Static Public Member Functions inherited from cugl::scene2::SceneNode
static std::shared_ptr< SceneNodealloc ()
 
static std::shared_ptr< SceneNodeallocWithPosition (const Vec2 pos)
 
static std::shared_ptr< SceneNodeallocWithPosition (float x, float y)
 
static std::shared_ptr< SceneNodeallocWithBounds (const Size size)
 
static std::shared_ptr< SceneNodeallocWithBounds (float width, float height)
 
static std::shared_ptr< SceneNodeallocWithBounds (const Rect rect)
 
static std::shared_ptr< SceneNodeallocWithBounds (float x, float y, float width, float height)
 
static std::shared_ptr< SceneNodeallocWithData (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
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

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
nameThe text field name
currentText 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
listenerThe 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
listenerThe 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
rectThe 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
sizeThe 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
widthThe width of the text field in parent space
heightThe 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
xThe x-coordinate of the origin in parent space
yThe y-coordinate of the origin in parent space
widthThe width of the text field in parent space
heightThe 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
loaderThe scene loader passing this JSON file
dataThe 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
textThe text to display in the text field
fontThe 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
positionThe text field position
textThe text to display in the text field
fontThe 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
rectThe bounds of the text field to display
textThe text to display in the text field
fontThe 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
sizeThe size of the text field to display
textThe text to display in the text field
fontThe 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
posThe 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.

Returns
true if the listener was succesfully removed

◆ 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.

Returns
true if the listener was succesfully removed

◆ 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
disposeWhether 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
batchThe SpriteBatch to draw with.
transformThe global transformation matrix.
tintThe 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
rowThe text row
offsetThe 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
keyThe 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
keyThe 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
loaderThe scene loader passing this JSON file
dataThe 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
unicodeThe unicode character
posThe 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
exitWhether 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
keyThe 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
keyThe 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
colorThe 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
visibleWhether 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
widthThe 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
textThe text for this label.
resizeWhether 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
forwardWhether 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
eventThe text input event to be handled.
focusWhether 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
eventThe key event to be handled.
focusWhether the text field currently has keyboard focus
downWhether 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
posThe screen coordinate where the event happened.
focusWhether 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: