123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302 |
- ---
- title: TextField
- order: 9
- layout: page
- ---
-
- [[components.textfield]]
- = [classname]#TextField#
-
- ((("[classname]#TextField#", id="term.components.textfield", range="startofrange")))
-
- [classname]#TextField# is one of the most commonly used user interface
- components. It is a [classname]#Field# component that allows entering textual
- values using keyboard.
-
- The following example creates a simple text field:
-
- [source, java]
- ----
- // Create a text field
- TextField tf = new TextField("A Field");
-
- // Put some initial content in it
- tf.setValue("Stuff in the field");
- ----
- See the http://demo.vaadin.com/book-examples-vaadin7/book#component.textfield.basic[on-line example, window="_blank"].
-
- The result is shown in <<figure.components.textfield.basic>>.
-
- [[figure.components.textfield.basic]]
- .[classname]#TextField# Example
- image::img/textfield-example.png[]
-
- Value changes are handled with a [classname]#Property.ValueChangeListener#, as
- in most other fields. The value can be acquired with [methodname]#getValue()#
- directly from the text field, as is done in the example below, or from the
- property reference of the event.
-
- [source, java]
- ----
- // Handle changes in the value
- tf.addValueChangeListener(new Property.ValueChangeListener() {
- public void valueChange(ValueChangeEvent event) {
- // Assuming that the value type is a String
- String value = (String) event.getProperty().getValue();
-
- // Do something with the value
- Notification.show("Value is: " + value);
- }
- });
-
- // Fire value changes immediately when the field loses focus
- tf.setImmediate(true);
- ----
- See the http://demo.vaadin.com/book-examples-vaadin7/book#component.textfield.inputhandling[on-line example, window="_blank"].
-
- As with other event listeners, you can use lambda expression with one parameter
- to handle the events in Java 8.
-
- Much of the API of [classname]#TextField# is defined in
- [classname]#AbstractTextField#, which allows different kinds of text input
- fields, such as rich text editors, which do not share all the features of the
- single-line text fields.
-
- [[figure.components.textfield.api]]
- .Text Field Class Relationships
- image::img/textfield-diagram-hi.png[width=50%]
-
- [[components.textfield.databinding]]
- == Data Binding
-
- [classname]#TextField# edits [classname]#String# values, but you can bind it to
- any property type that has a proper converter, as described in
- <<dummy/../../../framework/datamodel/datamodel-properties#datamodel.properties.converter,"Converting
- Between Property Type and Representation">>.
-
- [source, java]
- ----
- // Have an initial data model. As Double is unmodificable and
- // doesn't support assignment from String, the object is
- // reconstructed in the wrapper when the value is changed.
- Double trouble = 42.0;
-
- // Wrap it in a property data source
- final ObjectProperty<Double> property =
- new ObjectProperty<Double>(trouble);
-
- // Create a text field bound to it
- // (StringToDoubleConverter is used automatically)
- TextField tf = new TextField("The Answer", property);
- tf.setImmediate(true);
-
- // Show that the value is really written back to the
- // data source when edited by user.
- Label feedback = new Label(property);
- feedback.setCaption("The Value");
- ----
- See the http://demo.vaadin.com/book-examples-vaadin7/book#component.textfield.databinding[on-line example, window="_blank"].
-
- When you put a [classname]#Table# in editable mode or create fields with a
- [classname]#FieldGroup#, the [classname]#DefaultFieldFactory# creates a
- [classname]#TextField# for almost every property type by default. You often need
- to make a custom factory to customize the creation and to set the field tooltip,
- validation, formatting, and so on.
-
- See
- <<dummy/../../../framework/datamodel/datamodel-overview.asciidoc#datamodel.overview,"Binding
- Components to Data">> for more details on data binding, field factories for
- [classname]#Table# in
- <<dummy/../../../framework/components/components-table#components.table.editing,"Editing
- the Values in a Table">>, and
- <<dummy/../../../framework/datamodel/datamodel-itembinding#datamodel.itembinding,"Creating
- Forms by Binding Fields to Items">> regarding forms.
-
- [[components.textfield.length]]
- == String Length
-
- The [methodname]#setMaxLength()# method sets the maximum length of the input
- string so that the browser prevents the user from entering a longer one. As a
- security feature, the input value is automatically truncated on the server-side,
- as the maximum length setting could be bypassed on the client-side. The maximum
- length property is defined at [classname]#AbstractTextField# level.
-
- Notice that the maximum length setting does not affect the width of the field.
- You can set the width with [methodname]#setWidth()#, as with other components.
- Using __em__ widths is recommended to better approximate the proper width in
- relation to the size of the used font, but the __em__ width is not exactly the
- width of a letter and varies by browser and operating system. There is no standard
- way in HTML for setting the width exactly to a number of letters (in a monospaced font).
-
- [[components.textfield.nullvalues]]
- == Handling Null Values
-
- ((("Null representation", id="term.components.textfield.nullvalues", range="startofrange")))
-
- ((("[methodname]#setNullRepresentation()#")))
- As with any field, the value of a [classname]#TextField# can be set as
- [parameter]#null#. This occurs most commonly when you create a new field without
- setting a value for it or bind the field value to a data source that allows null
- values. In such case, you might want to show a special value that stands for the
- null value. You can set the null representation with the
- [methodname]#setNullRepresentation()# method. Most typically, you use an empty
- string for the null representation, unless you want to differentiate from a
- string that is explicitly empty. The default null representation is "
- [literal]#++null++#", which essentially warns that you may have forgotten to
- initialize your data objects properly.
-
- ((("[methodname]#setNullSettingAllowed()#")))
- The [methodname]#setNullSettingAllowed()# controls whether the user can actually
- input a null value by using the null value representation. If the setting is
- [literal]#++false++#, which is the default, inputting the null value
- representation string sets the value as the literal value of the string, not
- null. This default assumption is a safeguard for data sources that may not allow
- null values.
-
- [source, java]
- ----
- // Have a property with null value
- ObjectProperty<Double> dataModel =
- new ObjectProperty<Double>(new Double(0.0));
- dataModel.setValue(null); // Have to set it null here
-
- // Create a text field bound to the null data
- TextField tf = new TextField("Field Energy (J)", dataModel);
- tf.setNullRepresentation("-- null-point --");
-
- // Allow user to input the null value by its representation
- tf.setNullSettingAllowed(true);
- ----
- See the http://demo.vaadin.com/book-examples-vaadin7/book#component.textfield.nullvaluerepresentation[on-line example, window="_blank"].
-
- The [classname]#Label#, which is bound to the value of the
- [classname]#TextField#, displays a null value as empty. The resulting user
- interface is shown in <<figure.components.textfield.nullvalues>>.
-
- [[figure.components.textfield.nullvalues]]
- .Null Value Representation
- image::img/textfield-nullrepresentation.png[]
-
- (((range="endofrange", startref="term.components.textfield.nullvalues")))
-
- [[components.textfield.textchangeevents]]
- == Text Change Events
-
- ((("[classname]#Text change events#", id="term.components.textfield.textchangeevents", range="startofrange")))
-
- Often you want to receive a change event immediately when the text field value
- changes. The __immediate__ mode is not literally immediate, as the changes are
- transmitted only after the field loses focus. In the other extreme, using
- keyboard events for every keypress would make typing unbearably slow and also
- processing the keypresses is too complicated for most purposes. __Text change
- events__ are transmitted asynchronously soon after typing and do not block
- typing while an event is being processed.
-
- ((([classname]#TextChangeListener#)))
- Text change events are received with a [classname]#TextChangeListener#, as is
- done in the following example that demonstrates how to create a text length
- counter:
-
- [source, java]
- ----
- // Text field with maximum length
- final TextField tf = new TextField("My Eventful Field");
- tf.setValue("Initial content");
- tf.setMaxLength(20);
-
- // Counter for input length
- final Label counter = new Label();
- counter.setValue(tf.getValue().length() +
- " of " + tf.getMaxLength());
-
- // Display the current length interactively in the counter
- tf.addTextChangeListener(new TextChangeListener() {
- public void textChange(TextChangeEvent event) {
- int len = event.getText().length();
- counter.setValue(len + " of " + tf.getMaxLength());
- }
- });
-
- // The lazy mode is actually the default
- tf.setTextChangeEventMode(TextChangeEventMode.LAZY);
- ----
- See the http://demo.vaadin.com/book-examples-vaadin7/book#component.textfield.textchangeevents.counter[on-line example, window="_blank"].
-
- The result is shown in <<figure.components.textfield.textchangeevents>>.
-
- [[figure.components.textfield.textchangeevents]]
- .Text Change Events
- image::img/textfield-textchangeevents.png[]
-
- The __text change event mode__ defines how quickly the changes are transmitted
- to the server and cause a server-side event. Lazier change events allow sending
- larger changes in one event if the user is typing fast, thereby reducing server
- requests.
-
- ((([classname]#TextChangeEventMode#)))
- You can set the text change event mode of a [classname]#TextField# with
- [methodname]#setTextChangeEventMode()#. The allowed modes are defined in
- [classname]#TextChangeEventMode# enum and are as follows:
-
- [parameter]#TextChangeEventMode.LAZY#(default):: An event is triggered when there is a pause in editing the text. The length of
- the pause can be modified with [methodname]#setInputEventTimeout()#. As with the
- [parameter]#TIMEOUT# mode, a text change event is forced before a possible
- [classname]#ValueChangeEvent#, even if the user did not keep a pause while
- entering the text.
-
- +
- This is the default mode.
-
- [parameter]#TextChangeEventMode.TIMEOUT#:: A text change in the user interface causes the event to be communicated to the
- application after a timeout period. If more changes are made during this period,
- the event sent to the server-side includes the changes made up to the last
- change. The length of the timeout can be set with
- [methodname]#setInputEventTimeout()#.
-
- +
- If a [classname]#ValueChangeEvent# would occur before the timeout period, a
- [classname]#TextChangeEvent# is triggered before it, on the condition that the
- text content has changed since the previous [classname]#TextChangeEvent#.
-
- [parameter]#TextChangeEventMode.EAGER#:: An event is triggered immediately for every change in the text content,
- typically caused by a key press. The requests are separate and are processed
- sequentially one after another. Change events are nevertheless communicated
- asynchronously to the server, so further input can be typed while event requests
- are being processed.
-
- (((range="endofrange", startref="term.components.textfield.textchangeevents")))
-
- [[components.textfield.css]]
- == CSS Style Rules
-
- [source, css]
- ----
- .v-textfield { }
- ----
-
- The HTML structure of [classname]#TextField# is extremely simple, consisting
- only of an element with the [literal]#++v-textfield++# style.
-
- For example, the following custom style uses dashed border:
-
- [source, css]
- ----
- .v-textfield-dashing {
- border: thin dashed;
- background: white; /* Has shading image by default */
- }
- ----
- See the http://demo.vaadin.com/book-examples-vaadin7/book#component.textfield.css[on-line example, window="_blank"].
-
- The result is shown in <<figure.components.textfield.css>>.
-
- [[figure.components.textfield.css]]
- .Styling TextField with CSS
- image::img/textfield-css.png[]
-
- The style name for [classname]#TextField# is also used in several components
- that contain a text input field, even if the text input is not an actual
- [classname]#TextField#. This ensures that the style of different text input
- boxes is similar.
-
- (((range="endofrange", startref="term.components.textfield")))
|