Framework documentation IN

Change-Id: I767477c1fc3745f9e1f58075fe30c9ac8da63581

1 files changed, 323 insertions, 0 deletions

diff --git a/documentation/components/components-textfield.asciidoc b/documentation/components/components-textfield.asciidoc
new file mode 100644
index 0000000000..e59b38bbf7
--- /dev/null
+++ b/documentation/components/components-textfield.asciidoc
@@ -0,0 +1,323 @@
+---
+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[]
+
+[[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.
+
+Bean Binding
+[[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. There is no standard way in HTML for
+setting the width exactly to a number of letters (in a monospaced font). You can
+trick your way around this restriction by putting the text field in an
+undefined-width [classname]#VerticalLayout# together with an undefined-width
+[classname]#Label# that contains a sample text, and setting the width of the
+text field as 100%. The layout will get its width from the label, and the text
+field will use that.
+
+Fitting TextField width to fixed input length
+[[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")))
+
+