diff options
Diffstat (limited to 'documentation/components/components-textfield.asciidoc')
| -rw-r--r-- | documentation/components/components-textfield.asciidoc | 323 |
1 files changed, 0 insertions, 323 deletions
diff --git a/documentation/components/components-textfield.asciidoc b/documentation/components/components-textfield.asciidoc deleted file mode 100644 index e59b38bbf7..0000000000 --- a/documentation/components/components-textfield.asciidoc +++ /dev/null @@ -1,323 +0,0 @@ ---- -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"))) - - |