123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177 |
- ---
- title: TextField
- order: 9
- layout: page
- ---
-
- [[components.textfield]]
- = TextField
-
- ifdef::web[]
- [.sampler]
- image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/data-input/text-input/text-field"]
- endif::web[]
-
- ((("[classname]#TextField#", id="term.components.textfield", range="startofrange")))
-
- [classname]#TextField# is one of the most commonly used user interface components.
- It is a field that allows entering textual values with 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");
- ----
-
- The result is shown in <<figure.components.textfield.basic>>.
-
- [[figure.components.textfield.basic]]
- .[classname]#TextField# Example
- image::img/textfield-example.png[width=40%, scaledwidth=50%]
-
- Value changes are handled by adding a listener using [methodname]#addValueChangeListener()# method, as in most other fields. The value can be acquired with [methodname]#getValue()# directly from the text field or from the parameter
- passed to the event listener.
-
- [source, java]
- ----
- // Handle changes in the value
- tf.addValueChangeListener(event ->
- // Do something with the value
- Notification.show("Value is: " + event.getValue()));
- ----
-
- [classname]#TextField# edits [classname]#String# values, but you can use [classname]#Binder#
- to bind it to any property type that has a proper converter, as described in
- <<../datamodel/datamodel-forms.asciidoc#datamodel.forms.conversion,"Conversion">>.
-
- Much of the API of [classname]#TextField# is defined in
- [classname]#AbstractTextField#, which allows different kinds of text input
- fields, 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=80%, scaledwidth=100%]
-
- [[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.textchangeevents]]
- == Configuring the Granularity of Value Change Events
-
- ((("[classname]#Text change events#", id="term.components.textfield.textchangeevents", range="startofrange")))
-
- Often you want to control how frequently [classname]#TextField# value changes are transmitted to the server.
- Sometimes the changes should be sent only after the field loses focus.
- In the other extreme, it can sometimes be useful to receive events every time the user presses a key.
-
- The __value 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]#ValueChangeMode#)))
- You can set the text change event mode of a [classname]#TextField# with
- [methodname]#setValueChangeMode()#. The allowed modes are defined in
- [classname]#ValueChangeMode# enum and are as follows:
-
- [parameter]#ValueChangeMode.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]#setValueChangeTimeout()#.
-
- +
- This is the default mode.
-
- [parameter]#ValueChangeMode.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]#setValueChangeTimeout()#.
-
- [parameter]#ValueChangeMode.EAGER#:: The [classname]#ValueChangeEvent# 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.
-
- [parameter]#ValueChangeMode.BLUR#:: The [classname]#ValueChangeEvent# is fired, after the field has lost focus.
-
- [source, java]
- ----
- // Text field with maximum length
- TextField tf = new TextField("My Eventful Field");
- tf.setValue("Initial content");
- tf.setMaxLength(20);
-
- // Counter for input length
- Label counter = new Label();
- counter.setValue(tf.getValue().length() +
- " of " + tf.getMaxLength());
-
- // Display the current length interactively in the counter
- tf.addValueChangeListener(event -> {
- int len = event.getValue().length();
- counter.setValue(len + " of " + tf.getMaxLength());
- });
-
- tf.setValueChangeMode(ValueChangeMode.EAGER);
- ----
-
-
- The result is shown in <<figure.components.textfield.textchangeevents>>.
-
- [[figure.components.textfield.textchangeevents]]
- .Text Change Events
- image::img/textfield-textchangeevents.png[width=35%, scaledwidth=50%]
-
-
- (((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;
- }
- ----
-
- 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")))
|