Gadget class. More...

#include <ilviews/gadgets/textfd.h>

Inheritance diagram for IlvTextField:

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

IlSymbol *	getChangeCallbackName () 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-color`	Color
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

display	The connection to the display.
rect	The size and position of the text field.
label	The label of the text field. The label is copied.
thickness	The thickness of the text field.
palette	The 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

display	The connection to the display.
point	The position of the text field.
label	The label of the text field. The label is copied.
thickness	The thickness of the text field.
palette	The 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

callback A 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

callbackName The 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

callback	A pointer to the new callback.
arg	The 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

callbackName	The name of the new callback.
arg	The 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

character The 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

position	The position of the character to be made visible.
t	The 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

character The 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

point	The point where the character is located.
t	The 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

alignment The 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

callback A 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

callbackName The 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

callback	A pointer to the new callback.
arg	The 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

callbackName	The name of the new callback.
arg	The 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

value Specifies 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

position The 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

value Specifies 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

position The 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

label	The new label of the text field. The old label is deleted and the new one is copied.
redraw	Specifies 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

count The 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

start	The index of the first selected character.
end	The index of the last selected character.

See also: setStartSelection(), setEndSelection().

void IlvTextField::setStartSelection ( IlShort position )

Sets the index of the first selected character.

Parameters

position The 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

position The 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

value	The integer value.
redraw	Specifies 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

value	The floating-point value.
format	A 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"`.
redraw	Specifies 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

value	Specifies whether the cursor should be visible (`IlTrue`) or not (`IlFalse`).
redraw	Specifies 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.

Public Member Functions

Friends

Detailed Description

Accessors

Styling

Constructor & Destructor Documentation

Member Function Documentation