IlvTextField Class Reference

Gadget class. More...

#include <ilviews/gadgets/textfd.h>

Inheritance diagram for IlvTextField:

List of all members.

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

---

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

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

)

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

)

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

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 IlvDateField, and IlvNumberField.

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 an IlFloat. The atof function 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 atoi function 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)

Reimplemented in IlvComboBox.

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

Reimplemented in IlvComboBox.

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	(	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::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

)

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

)

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::setChangeFocusOnValidation

(

IlBoolean

value

)

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

Parameters:

value

A Boolean value specifying 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

A Boolean value specifying 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	A Boolean value specifying 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	(	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	A Boolean value specifying whether the text field should be redrawn.

See also:

getFloatValue

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	A Boolean value specifying whether the text field should be redrawn.

See also:

getIntValue

Reimplemented in IlvNumberField.

void IlvTextField::showCursor	(	IlBoolean	value,
		IlBoolean	redraw = IlFalse
	)

Specifies whether the cursor should be visible.

Parameters:

	value	A Boolean value specifying whether the cursor should be visible (IlTrue) or not (IlFalse).
	redraw	A Boolean value specifying 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 IlvDateField, and IlvNumberField.