Rogue Wave Views
Gadgets Package API Reference Guide
Product Documentation:

Rogue Wave Views
Documentation Home
List of all members | Public Member Functions | Friends
IlvTextField Class Reference

Gadget class. More...

#include <ilviews/gadgets/textfd.h>

Inheritance diagram for IlvTextField:
IlvGadget IlvSimpleGraphic IlvStylable IlvGraphic IlvValueInterface IlvComboBox IlvDateField IlvNumberField IlvPasswordTextField IlvScrolledComboBox

Public Member Functions

 IlvTextField (IlvDisplay *display, const char *label, const IlvRect &rect, IlUShort thickness=IlvDefaultGadgetThickness, IlvPalette *palette=0)
 Constructor. More...
 
 IlvTextField (IlvDisplay *display, const IlvPoint &point, const char *label, IlUShort thickness=IlvDefaultGadgetThickness, IlvPalette *palette=0)
 Constructor. More...
 
void addChangeCallback (IlvGraphicCallback callback)
 Adds a Label Changed callback. More...
 
void addChangeCallback (IlSymbol *callbackName)
 Adds a named Label Changed callback. More...
 
void addChangeCallback (IlvGraphicCallback callback, IlAny arg)
 Adds a Label Changed callback. More...
 
void addChangeCallback (IlSymbol *callbackName, IlAny arg)
 Adds a named Label Changed callback. More...
 
virtual const char * check (IlUShort character)
 Is called by the interactor for each key down event that corresponds to a regular character. More...
 
void ensureVisible (IlShort position, const IlvTransformer *t=0)
 Ensures that the character located at the specified position is visible. More...
 
IlvPosition getAlignment () const
 Returns the alignment of the text field. More...
 
IlvGraphicCallback getChangeCallback () const
 Returns a pointer to the first unnamed callback in the Label Changed callback list. More...
 
IlSymbolgetChangeCallbackName () const
 Returns the name of the first named callback in the Label Changed callback list. More...
 
IlBoolean getChangeFocusOnValidation () const
 Indicates whether the text field moves the keyboard focus to the next gadget once validated. More...
 
IlShort getCursorPosition () const
 Returns the cursor position. More...
 
IlShort getEndSelection () const
 Returns the index of the last selected character. More...
 
IlFloat getFloatValue () const
 Converts the text field contents to a floating point value and returns the result of the conversion. More...
 
IlInt getIntValue () const
 Converts the text field contents to an integer and returns the result of the conversion. More...
 
const char * getLabel () const
 Returns the label displayed by the text field. More...
 
IlShort getMaxChar () const
 Returns the maximum number of characters that the user can type in the text field. More...
 
virtual const char * getMessage () const
 Returns the message displayed by this text field. More...
 
IlShort getStartSelection () const
 Returns the index of the first selected character. More...
 
IlShort getTextPosition () const
 Returns the index of the first visible character of the text field. More...
 
virtual IlBoolean handleControl (IlUShort character)
 Is called by the interactor to handle control keys. More...
 
IlBoolean isCursorShown () const
 Indicates whether the cursor is visible. More...
 
IlBoolean isEditable () const
 Indicates whether the text field can be edited. More...
 
virtual void labelChanged ()
 Is called by the interactor whenever the label of the text field changes. More...
 
IlShort pointToPosition (const IlvPoint &point, const IlvTransformer *t=0) const
 Returns the index of the character located at the specified point. More...
 
virtual void removeSelection ()
 Removes the selected label from the text field. More...
 
void setAlignment (IlvPosition alignment)
 Sets the alignment of the text field. More...
 
void setChangeCallback (IlvGraphicCallback callback)
 Sets a Label Changed callback. More...
 
void setChangeCallback (IlSymbol *callbackName)
 Sets a named Label Changed callback. More...
 
void setChangeCallback (IlvGraphicCallback callback, IlAny arg)
 Sets a Label Changed callback. More...
 
void setChangeCallback (IlSymbol *callbackName, IlAny arg)
 Sets a named Label Changed callback. More...
 
void setChangeFocusOnValidation (IlBoolean value)
 Specifies whether the text field should move the keyboard focus to the next gadget once validated. More...
 
void setCursorPosition (IlShort position)
 Sets the cursor position. More...
 
void setEditable (IlBoolean value)
 Specifies whether the text field can be edited. More...
 
void setEndSelection (IlShort position)
 Sets the index of the last selected character. More...
 
virtual void setLabel (const char *label, IlBoolean redraw=IlFalse)
 Sets the label of the text field. More...
 
void setMaxChar (IlShort count)
 Sets the maximum number of characters that the user can type in the text field. More...
 
void setSelection (IlShort start, IlShort end)
 Selects a portion of the text field content. More...
 
void setStartSelection (IlShort position)
 Sets the index of the first selected character. More...
 
void setTextPosition (IlShort position)
 Sets the index of the first visible character of the text field. More...
 
void setValue (IlInt value, IlBoolean redraw=IlFalse)
 Sets the text field label to an integer value. More...
 
void setValue (IlFloat value, const char *format=0, IlBoolean redraw=IlFalse)
 Sets the text field label to a floating-point value. More...
 
void showCursor (IlBoolean value, IlBoolean redraw=IlFalse)
 Specifies whether the cursor should be visible. More...
 
virtual void validate ()
 Is called by the interactor when the user presses the Return or the Enter key. More...
 

Friends

class IlvDefaultTextFieldLFHandler
 

Detailed Description

Gadget class.

Library: ilvgadgt

The IlvTextField class defines a one-line text editor that is used to display and edit a short character string.

- IlvTextField -

The contents of a text field can be modified by clicking it and entering new text. Instances of IlvTextField handle a cursor that indicates where new text should be inserted. It is also possible to select a portion of text by dragging the mouse on it.

See also
IlvText, IlvComboBox.

Accessors

Accessors provide a scriptable and uniform way to inspect and modify an object by using its base class methods IlvValueInterface::queryValue(), IlvValueInterface::queryValues(), IlvValueInterface::changeValue(), IlvValueInterface::changeValues(). This class inherits the accessors of its superclass IlvGadget and adds the following ones:

Name Type Equivalent methods
alignment Direction getAlignment(), setAlignment()
label String getLabel(), setLabel()
cursorPosition Int getCursorPosition(), setCursorPosition()
selectionStart Int getStartSelection(), setSelection()
selectionEnd Int getEndSelection(), setSelection()
maxChar Int getMaxChar(), setMaxChar()
editable Boolean isEditable(), setEditable()
focusChange Boolean getChangeFocusOnValidation(), setChangeFocusOnValidation()

Styling

This class supports the following CSS properties:

Graphic property CSS property Type
Background color background-colorColor
Text color color Color

Constructor & Destructor Documentation

IlvTextField::IlvTextField ( IlvDisplay display,
const char *  label,
const IlvRect rect,
IlUShort  thickness = IlvDefaultGadgetThickness,
IlvPalette palette = 0 
)

Constructor.

Initializes a new instance of the class IlvTextField.

Parameters
displayThe connection to the display.
rectThe size and position of the text field.
labelThe label of the text field. The label is copied.
thicknessThe thickness of the text field.
paletteThe palette used by the text field.
IlvTextField::IlvTextField ( IlvDisplay display,
const IlvPoint point,
const char *  label,
IlUShort  thickness = IlvDefaultGadgetThickness,
IlvPalette palette = 0 
)

Constructor.

Initializes a new instance of the class IlvTextField.

Parameters
displayThe connection to the display.
pointThe position of the text field.
labelThe label of the text field. The label is copied.
thicknessThe thickness of the text field.
paletteThe palette used by the text field.

Member Function Documentation

void IlvTextField::addChangeCallback ( IlvGraphicCallback  callback)

Adds a Label Changed callback.

Adds callback to the Label Changed callback list. A Label Changed callback is invoked when the text field contents is changed through the interactor.

Parameters
callbackA pointer to the new callback.
See also
labelChanged(), setChangeCallback(), getChangeCallback().
void IlvTextField::addChangeCallback ( IlSymbol callbackName)

Adds a named Label Changed callback.

Adds the callback name callbackName to the Label Changed callback list. A Label Changed callback is called when the text field contents is changed through the interactor.

Parameters
callbackNameThe name of the new callback.
See also
labelChanged(), setChangeCallback(), getChangeCallbackName().
void IlvTextField::addChangeCallback ( IlvGraphicCallback  callback,
IlAny  arg 
)

Adds a Label Changed callback.

Adds callback to the Label Changed callback list. The callback function, when invoked, receives the user parameter arg. A Label Changed callback is invoked when the text field contents is changed through the interactor.

Parameters
callbackA pointer to the new callback.
argThe callback argument.
See also
labelChanged(), setChangeCallback(), getChangeCallback().
void IlvTextField::addChangeCallback ( IlSymbol callbackName,
IlAny  arg 
)

Adds a named Label Changed callback.

Adds callbackName to the Label Changed callback list. The callback function, when invoked, receives the user parameter arg. A Label Changed callback is invoked when the text field contents is changed through the interactor.

Parameters
callbackNameThe name of the new callback.
argThe callback argument.
See also
labelChanged(), setChangeCallback(), getChangeCallbackName().
virtual const char* IlvTextField::check ( IlUShort  character)
virtual

Is called by the interactor for each key down event that corresponds to a regular character.

The default implementation inserts character in the text field (erasing the selection if there is one).

Parameters
characterThe ASCII code of the character.
Returns
The new label of the text field.
See also
setLabel().

Reimplemented in IlvNumberField, and IlvDateField.

void IlvTextField::ensureVisible ( IlShort  position,
const IlvTransformer t = 0 
)

Ensures that the character located at the specified position is visible.

Parameters
positionThe position of the character to be made visible.
tThe transformer applied to this text field.
IlvPosition IlvTextField::getAlignment ( ) const

Returns the alignment of the text field.

Returns
The alignment of the text field.
See also
setAlignment().
IlvGraphicCallback IlvTextField::getChangeCallback ( ) const

Returns a pointer to the first unnamed callback in the Label Changed callback list.

A Label Changed callback is invoked when the text field contents is changed through the interactor.

Returns
A pointer to the first unnamed callback in the Label Changed callback list.
See also
labelChanged(), setChangeCallback(), addChangeCallback().
IlSymbol* IlvTextField::getChangeCallbackName ( ) const

Returns the name of the first named callback in the Label Changed callback list.

A Label Changed callback is invoked when the text field contents is changed through the interactor.

Returns
The name of the first named callback in the Label Changed callback list.
See also
labelChanged(), setChangeCallback(), addChangeCallback().
IlBoolean IlvTextField::getChangeFocusOnValidation ( ) const

Indicates whether the text field moves the keyboard focus to the next gadget once validated.

Returns
IlTrue if the text field moves the keyboard focus to the next gadget when the Return key is pressed (the default) and IlFalse otherwise.
See also
setChangeFocusOnValidation().
IlShort IlvTextField::getCursorPosition ( ) const

Returns the cursor position.

Returns
The cursor position. A value of 0 means that the cursor is placed just before the first character.
See also
setCursorPosition().
IlShort IlvTextField::getEndSelection ( ) const

Returns the index of the last selected character.

Returns
The index of the last selected character.
See also
getStartSelection().
IlFloat IlvTextField::getFloatValue ( ) const

Converts the text field contents to a floating point value and returns the result of the conversion.

Returns
The conversion of the text field label to IlFloat. The function atof() is used to perform the conversion.
See also
setValue(IlFloat, const char*, IlBoolean), getIntValue().
IlInt IlvTextField::getIntValue ( ) const

Converts the text field contents to an integer and returns the result of the conversion.

Returns
The conversion of the text field label to an IlInt. The function atoi() is used to perform the conversion.
See also
setValue(IlInt, IlBoolean), getFloatValue().
const char* IlvTextField::getLabel ( ) const

Returns the label displayed by the text field.

Returns
The label displayed by the text field.
See also
setLabel(), setValue(IlInt, IlBoolean), setValue(IlFloat, const char*, IlBoolean).
IlShort IlvTextField::getMaxChar ( ) const

Returns the maximum number of characters that the user can type in the text field.

Returns
The maximum number of characters that can be typed in the text field. The member function returns -1 if no limit has been defined.
See also
setMaxChar().
virtual const char* IlvTextField::getMessage ( ) const
virtual

Returns the message displayed by this text field.

If the text field cannot be edited, the message database is used to find the translation of the text field contents to the current language. If the text field can be edited, the method returns the result of IlvTextField::getLabel().

Returns
The message displayed by this text field.
See also
getLabel(), IlvMessageDatabase, IlvDisplay::getCurrentLanguage().

Reimplemented in IlvPasswordTextField.

IlShort IlvTextField::getStartSelection ( ) const

Returns the index of the first selected character.

Returns
The index of the first selected character. The first character has an index of 0.
See also
getEndSelection().
IlShort IlvTextField::getTextPosition ( ) const

Returns the index of the first visible character of the text field.

Returns
The index of the first visible character of the text field. A value of 0 means that the first character is visible.
See also
setTextPosition().
virtual IlBoolean IlvTextField::handleControl ( IlUShort  character)
virtual

Is called by the interactor to handle control keys.

Should only handle control characters, that is, characters for which calling iscntrl() returns a value different from 0. The control characters used are:

  • Ctrl-A or Home key: Cursor goes to beginning.
  • Ctrl-X: Cuts the selected text.
  • Ctrl-C: Copies the selected text.
  • Ctrl-V: Pastes text from clipboard.
  • Ctrl-B: Cursor goes backward one character.
  • Ctrl-F: Cursor goes forward one character.
  • Ctrl-E or End key: Cursor goes to end.
  • Ctrl-K: Removes characters after the cursor.
  • Ctrl-U: Removes characters before the cursor.
  • Ctrl-D or Delete key: Removes one character after the cursor.
  • Ctrl-H or Backspace key: Removes one character before the cursor.
  • Left key: Moves cursor to left one character.
  • Right key: Moves cursor to right one character.
Parameters
characterThe ASCII code of the control character.
IlBoolean IlvTextField::isCursorShown ( ) const

Indicates whether the cursor is visible.

Returns
IlTrue if the cursor is visible, and IlFalse if it is not.
See also
showCursor().
IlBoolean IlvTextField::isEditable ( ) const

Indicates whether the text field can be edited.

The contents of a noneditable text field can be copied and localized. See IlvTextField::getMessage().

Returns
IlTrue if the text field can be edited and IlFalse otherwise.
See also
setEditable(), getMessage().
virtual void IlvTextField::labelChanged ( )
virtual

Is called by the interactor whenever the label of the text field changes.

The default implementation calls the Label Changed callback.

See also
setChangeCallback().

Reimplemented in IlvComboBox.

IlShort IlvTextField::pointToPosition ( const IlvPoint point,
const IlvTransformer t = 0 
) const

Returns the index of the character located at the specified point.

Parameters
pointThe point where the character is located.
tThe transformer applied to the text field.
Returns
The index of the character located at point when the text is drawn with the transformer t.
virtual void IlvTextField::removeSelection ( )
virtual

Removes the selected label from the text field.

The text field is not redrawn.

void IlvTextField::setAlignment ( IlvPosition  alignment)

Sets the alignment of the text field.

Parameters
alignmentThe new text field alignment. Valid values are: IlvRight, IlvLeft and IlvCenter.
See also
getAlignment().
void IlvTextField::setChangeCallback ( IlvGraphicCallback  callback)

Sets a Label Changed callback.

Removes all the existing Label Changed callbacks before adding callback to the Label Changed callback list. A Label Changed callback is invoked when the text field contents is changed through the interactor.

Parameters
callbackA pointer to the new callback.
See also
labelChanged(), addChangeCallback(), getChangeCallback().
void IlvTextField::setChangeCallback ( IlSymbol callbackName)

Sets a named Label Changed callback.

Removes all the existing Label Changed callbacks before adding the callback name callbackName to the Label Changed callback list. A Label Changed callback is called when the text field contents is changed through the interactor.

Parameters
callbackNameThe name of the new callback.
See also
labelChanged(), addChangeCallback(), getChangeCallbackName().
void IlvTextField::setChangeCallback ( IlvGraphicCallback  callback,
IlAny  arg 
)

Sets a Label Changed callback.

Removes all the existing Label Changed callbacks before adding callback to the Label Changed callback list. The callback function, when invoked, receives the user parameter arg. A Label Changed callback is invoked when the text field contents is changed through the interactor.

Parameters
callbackA pointer to the new callback.
argThe callback argument.
See also
labelChanged(), addChangeCallback(), getChangeCallback().
void IlvTextField::setChangeCallback ( IlSymbol callbackName,
IlAny  arg 
)

Sets a named Label Changed callback.

Removes all the existing Label Changed callbacks before adding callbackName to the Label Changed callback list. The callback function, when invoked, receives the user parameter arg. A Label Changed callback is invoked when the text field contents is changed through the interactor.

Parameters
callbackNameThe name of the new callback.
argThe callback argument.
See also
labelChanged(), addChangeCallback(), getChangeCallbackName().
void IlvTextField::setChangeFocusOnValidation ( IlBoolean  value)

Specifies whether the text field should move the keyboard focus to the next gadget once validated.

Parameters
valueSpecifies whether the text field should move the keyboard focus to the next gadget in the focus chain when the when the user presses the Return key.
void IlvTextField::setCursorPosition ( IlShort  position)

Sets the cursor position.

Parameters
positionThe new cursor position. If position is greater than the number of characters in the text field, the cursor is placed after the last character.
See also
getCursorPosition().
void IlvTextField::setEditable ( IlBoolean  value)

Specifies whether the text field can be edited.

The contents of a noneditable text field can be copied and localized. See IlvTextField::getMessage().

Parameters
valueSpecifies whether the text field can be edited (IlTrue) or not (IlFalse).
See also
isEditable(), getMessage().
void IlvTextField::setEndSelection ( IlShort  position)

Sets the index of the last selected character.

Parameters
positionThe index of the last selected character.
See also
setFirstSelection(), getEndSelection().
virtual void IlvTextField::setLabel ( const char *  label,
IlBoolean  redraw = IlFalse 
)
virtual

Sets the label of the text field.

Parameters
labelThe new label of the text field. The old label is deleted and the new one is copied.
redrawSpecifies whether the text field should be redrawn.
See also
getLabel(), getIntValue(), getFloatValue().

Reimplemented in IlvComboBox.

void IlvTextField::setMaxChar ( IlShort  count)

Sets the maximum number of characters that the user can type in the text field.

When the maximum number of characters has been reached, typing additional characters is not taken into account.

Parameters
countThe maximum number of characters that can be typed in the text field.
See also
getMaxChar().
void IlvTextField::setSelection ( IlShort  start,
IlShort  end 
)

Selects a portion of the text field content.

Entirely defines the selection range by setting the index of the first selected character to start and the index of the last selected character to end. To set the selected characters, count the number of delimiters rather than the number of intervals, as follows: If there are six characters: |A|B|C|D|E|F|, there are seven delimiters from 0 to 6 starting from the left. Thus setSelection(1, 5) selects B,C,D and E; and setSelection(1, 2) selects B.

Parameters
startThe index of the first selected character.
endThe index of the last selected character.
See also
setStartSelection(), setEndSelection().
void IlvTextField::setStartSelection ( IlShort  position)

Sets the index of the first selected character.

Parameters
positionThe index of the first selected character.
See also
setEndSelection(), getStartSelection().
void IlvTextField::setTextPosition ( IlShort  position)

Sets the index of the first visible character of the text field.

Parameters
positionThe index of the first visible character.
See also
getTextPosition(), ensureVisible().
void IlvTextField::setValue ( IlInt  value,
IlBoolean  redraw = IlFalse 
)

Sets the text field label to an integer value.

Sets the text field label to the ASCII representation of value.

Parameters
valueThe integer value.
redrawSpecifies whether the text field should be redrawn.
See also
getIntValue().
void IlvTextField::setValue ( IlFloat  value,
const char *  format = 0,
IlBoolean  redraw = IlFalse 
)

Sets the text field label to a floating-point value.

Sets the text field label to the ASCII representation of value and displays it with the specified format.

Parameters
valueThe floating-point value.
formatA string representing the format in which value will be displayed. The syntax is the one used by the function printf(). The default format is "%.f".
redrawSpecifies whether the text field should be redrawn.
See also
getFloatValue().
void IlvTextField::showCursor ( IlBoolean  value,
IlBoolean  redraw = IlFalse 
)

Specifies whether the cursor should be visible.

Parameters
valueSpecifies whether the cursor should be visible (IlTrue) or not (IlFalse).
redrawSpecifies whether the text field should be redrawn.
See also
isCursorShown().
virtual void IlvTextField::validate ( )
virtual

Is called by the interactor when the user presses the Return or the Enter key.

The default implementation invokes the main callback of the text field. If the method IlvTextField::getChangeFocusOnValidation() returns IlTrue, the keyboard focus moves to the next gadget in the focus chain.

See also
getChangeFocusOnValidation(), IlvGraphicHolder::setFocus().

Reimplemented in IlvNumberField, and IlvDateField.


© Copyright 2016, Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.