Using IlvTextField

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

A Text Field

This section covers the following topics:

Aligning Text

The text of an IlvTextField can be left-aligned (the default), right-aligned, or centered. To change the text alignment, use setAlignment.

Setting and Retrieving Text

Use the member functions setLabel and getLabel to set and retrieve text. The class IlvTextField also contains a set of useful methods for setting or retrieving formatted text such as integer or float values:

  • getIntValue() retrieves an integer value.

  • getFloatValue() retrieves a float value.

  • setValue(IlvInt) sets an integer value.

  • setValue(IlvFloat,const char* format) sets a float value.

Subclasses of IlvTextField edit an integer, a float, a date, and a password.

See Using IlvDateField, Using IlvNumberField.

Localizing a Text Field

Text fields in read-only mode can be localized.

See Localizing a Gadget.

Limiting the Number of Characters

You can limit the number of characters that can be edited in a text field with setMaxChar. When its parameter is set to -1, you can type as many characters as you want. This member function limits the number of characters that you can type in a text field, but not the number of characters you can specify with setLabel. See Setting and Retrieving Text.

Event Handling and Callbacks

This section covers the following topics:

The Validate Method and the Main Callback

When the user presses the Enter key in a text field, the validate member function is called. This virtual method invokes the Main callback of the text field and moves the focus to the next gadget in the focus chain.

Setting the Main callback for a text field provides an easy way to validate it. You can set a Focus Out callback to validate the text field instead of the Main callback. In this case, the field is validated when it loses the focus.

See Associating a Callback with a Gadget and Focus Management.

The Check Method

Each time the user types a regular ASCII character in a text field, the virtual check member function is called. Its default implementation removes the selected text and adds the characters that the user enters at the current cursor location.

This method checks the maximum number of characters allowed (see Limiting the Number of Characters). As a consequence, when you redefine it, be sure to add a test (similar to the one shown below) to allow this mechanism to work.

The labelChanged Method

When the user modifies the content of a text field, the member function labelChanged is called. Its default implementation invokes the Change callback.

To set this callback, use setChangeCallback.

See Associating a Callback with a Gadget.

Keyboard Shortcuts

The following table lists the keyboard shortcuts that can be used with text fields:

Key

Behavior

Home or Ctrl+A

 Moves the cursor to the beginning of the text.
End or Ctrl+E Moves the cursor to the end of the text.
Left arrow key or Ctrl+B Moves cursor left one character.
Right arrow key or Ctrl+F Moves cursor right one character.
Ctrl+K Removes the text after the cursor.
Ctrl+U Removes the text before the cursor.
Del or Ctrl+D Removes the character after the cursor.
Back Space or Ctrl+H Removes the character before the cursor.
Ctrl+X Cuts the selected text to the clipboard.
Ctrl+C Copies the selected text to the clipboard.
Ctrl+V Pastes text from the clipboard.
Ctrl+Insert (Windows) Copies the selected text to the clipboard.
Shift+Insert (Windows) Pastes text from the clipboard.
Ctrl+Left, Ctrl+Right Moves the cursor one word backward or forward.
Shift+Left, Shift+Right Extends the selection one character to the left or to the right.
Ctrl+Shift+Left, Ctrl+Shift+Right Extends the selection one word to the left or to the right.
Shift+Home, Shift+End Extends the selection to the beginning or the end of the text.