From 93767cf76b2fb14c65b758066c67fc8b48cc2eeb Mon Sep 17 00:00:00 2001 From: Marko Gronroos Date: Fri, 20 May 2016 14:44:42 +0300 Subject: Scaled images for print edition and fixed errors up to the beginning of layouts chapter (#19835). Also major revision of Tree, CustomField, and layouts overview. Change-Id: I19f5e9511b83f953ce4707f324d81c2821ebb69d --- documentation/advanced/advanced-windows.asciidoc | 8 +- .../application/application-architecture.asciidoc | 23 +- .../application/application-overview.asciidoc | 7 +- .../application/application-resources.asciidoc | 22 +- .../architecture/architecture-client-side.asciidoc | 5 +- .../architecture/architecture-events.asciidoc | 19 +- .../architecture/architecture-overview.asciidoc | 2 +- .../architecture/architecture-technology.asciidoc | 6 +- .../clientside/clientside-compiling.asciidoc | 16 +- .../components/components-button.asciidoc | 18 +- .../components/components-calendar.asciidoc | 14 +- .../components/components-checkbox.asciidoc | 9 +- .../components/components-combobox.asciidoc | 6 +- .../components/components-customcomponent.asciidoc | 15 +- .../components/components-customfield.asciidoc | 87 +- .../components/components-datefield.asciidoc | 30 +- .../components/components-embedded.asciidoc | 19 +- .../components/components-features.asciidoc | 107 +- .../components/components-fields.asciidoc | 70 +- documentation/components/components-grid.asciidoc | 75 +- documentation/components/components-label.asciidoc | 16 +- documentation/components/components-link.asciidoc | 72 +- .../components/components-listselect.asciidoc | 11 +- .../components/components-menubar.asciidoc | 27 +- .../components/components-nativeselect.asciidoc | 11 +- .../components/components-optiongroup.asciidoc | 20 +- .../components/components-passwordfield.asciidoc | 10 +- .../components/components-progressbar.asciidoc | 59 +- .../components/components-richtextarea.asciidoc | 8 +- .../components/components-selection.asciidoc | 81 +- .../components/components-slider.asciidoc | 29 +- documentation/components/components-table.asciidoc | 66 +- .../components/components-textarea.asciidoc | 10 +- .../components/components-textfield.asciidoc | 22 +- documentation/components/components-tree.asciidoc | 204 ++-- .../components/components-treetable.asciidoc | 19 +- .../components/components-twincolselect.asciidoc | 6 +- .../components/components-upload.asciidoc | 20 +- documentation/components/img/customfield-basic.png | Bin 0 -> 3215 bytes .../components/img/slider-example1-hi.png | Bin 8084 -> 12675 bytes documentation/components/img/slider-orig.png | Bin 3308 -> 16803 bytes .../components/img/table-columnformatting.png | Bin 14101 -> 25223 bytes documentation/components/img/tree-example1.png | Bin 21923 -> 15383 bytes .../original-drawings/slider-example1.svg | 261 ++--- .../chapter-getting-started.asciidoc | 5 +- .../getting-started-first-project.asciidoc | 88 +- .../getting-started/getting-started-idea.asciidoc | 12 +- .../getting-started-netbeans.asciidoc | 10 +- .../getting-started/getting-started-overview.adoc | 8 +- .../img/idea-maven-newproject-1.png | Bin 48841 -> 30956 bytes .../getting-started/img/idea-newproject-1.png | Bin 47846 -> 29951 bytes .../getting-started/img/idea-newproject-2.png | Bin 48811 -> 29030 bytes .../getting-started/img/netbeans-newproject-1.png | Bin 55377 -> 45003 bytes .../getting-started/img/netbeans-newproject-2.png | Bin 49508 -> 39198 bytes .../getting-started/img/netbeans-server.png | Bin 27387 -> 18349 bytes .../installing/img/installation-steps.svg | 1019 ++++++++++++++++++++ documentation/installing/img/sign-in-form.png | Bin 23263 -> 13875 bytes .../installing/img/signin-via-website.png | Bin 36736 -> 26780 bytes documentation/installing/installing-eclipse.adoc | 55 +- documentation/installing/installing-idea.asciidoc | 4 +- .../installing/installing-netbeans.asciidoc | 2 +- documentation/installing/installing-other.adoc | 2 +- documentation/installing/installing-overview.adoc | 2 +- documentation/installing/installing-toolchain.adoc | 2 +- .../installation-steps-constellation.svg | 143 ++- .../original-drawings/installation-steps.svg | 65 +- documentation/introduction/intro-overview.asciidoc | 5 +- .../layout/img/layout-intro-example-1.png | Bin 21093 -> 46039 bytes documentation/layout/img/layout-schematic-hi.png | Bin 0 -> 54267 bytes documentation/layout/layout-gridlayout.asciidoc | 81 +- documentation/layout/layout-orderedlayout.asciidoc | 50 +- documentation/layout/layout-overview.asciidoc | 48 +- documentation/layout/original-drawings/Makefile | 17 + .../layout/original-drawings/layout-schematic.svg | 546 +++++++++++ 74 files changed, 2601 insertions(+), 1073 deletions(-) create mode 100644 documentation/components/img/customfield-basic.png create mode 100644 documentation/installing/img/installation-steps.svg create mode 100644 documentation/layout/img/layout-schematic-hi.png create mode 100644 documentation/layout/original-drawings/Makefile create mode 100644 documentation/layout/original-drawings/layout-schematic.svg diff --git a/documentation/advanced/advanced-windows.asciidoc b/documentation/advanced/advanced-windows.asciidoc index 5bd77f7c80..d838ee81d0 100644 --- a/documentation/advanced/advanced-windows.asciidoc +++ b/documentation/advanced/advanced-windows.asciidoc @@ -43,12 +43,12 @@ linkend="advanced.windows.caveats"/>. //// [[advanced.windows.popup]] -== Opening Popup Windows +== Opening Pop-up Windows ((("popup windows"))) ((("windows", "popup"))) -Popup windows are native browser windows or tabs opened by user interaction with -an existing window. Due to browser security reasons, it is made incovenient for +Pop-up windows are native browser windows or tabs opened by user interaction with +an existing window. Due to browser security reasons, it is made inconvenient for a web page to open popup windows using JavaScript commands. At the least, the browser will ask for a permission to open the popup, if it is possible at all. This limitation can be circumvented by letting the browser open the new window @@ -57,7 +57,7 @@ Vaadin with the [classname]#BrowserWindowOpener# component extension, which causes the browser to open a window or tab when the component is clicked. [[advanced.windows.popup.ui]] -=== The Popup Window UI +=== The Pop-up Window UI A popup Window displays an [classname]#UI#. The UI of a popup window is defined just like a main UI in a Vaadin application, and it can have a theme, title, and diff --git a/documentation/application/application-architecture.asciidoc b/documentation/application/application-architecture.asciidoc index 77c1756594..c00a378a11 100644 --- a/documentation/application/application-architecture.asciidoc +++ b/documentation/application/application-architecture.asciidoc @@ -14,7 +14,6 @@ way you like to think about it), from the [classname]#UI# class of the application. You normally set a layout component as the content of the UI and fill it with other components. - [source, java] ---- public class MyHierarchicalUI extends UI { @@ -24,10 +23,10 @@ public class MyHierarchicalUI extends UI { VerticalLayout content = new VerticalLayout(); content.setSizeFull(); // Use entire window setContent(content); // Attach to the UI - + // Add some component content.addComponent(new Label("Hello!")); - + // Layout inside layout HorizontalLayout hor = new HorizontalLayout(); hor.setSizeFull(); // Use all available space @@ -64,8 +63,8 @@ UI The result is shown in <>. [[figure.application.architecture.example]] -.Simple Hierarchical UI -image::img/ui-architecture-hierarchical.png[] +.Simple hierarchical UI +image::img/ui-architecture-hierarchical.png[width=70%, scaledwidth=90%] Instead of building the layout in Java, you can also use a declarative design, as described later in @@ -131,7 +130,7 @@ class MyView extends VerticalLayout { addComponent(entry); addComponent(display); addComponent(click); - + // Configure it a bit setSizeFull(); addStyleName("myview"); @@ -164,13 +163,13 @@ class MyView extends CustomComponent { public MyView() { Layout layout = new VerticalLayout(); - + layout.addComponent(entry); layout.addComponent(display); layout.addComponent(click); - + setCompositionRoot(layout); - + setSizeFull(); } } @@ -233,7 +232,7 @@ UI.getCurrent().setLocale(new Locale("en")); // Set the page title (window or tab caption) Page.getCurrent().setTitle("My Page"); - + // Set a session attribute VaadinSession.getCurrent().setAttribute("myattrib", "hello"); @@ -252,7 +251,3 @@ ifdef::web[] <>. endif::web[] - - - - diff --git a/documentation/application/application-overview.asciidoc b/documentation/application/application-overview.asciidoc index b70df520f9..f1a792a60e 100644 --- a/documentation/application/application-overview.asciidoc +++ b/documentation/application/application-overview.asciidoc @@ -19,7 +19,7 @@ by the application server or the application itself. [[figure.application.architecture]] .Server-Side Application Architecture -image::img/application-architecture-hi.png[] +image::img/application-architecture-hi.png[width=70%, scaledwidth=100%] <> illustrates the basic architecture of an application made with the Vaadin Framework, with all the major elements, which @@ -151,8 +151,3 @@ component to an SQL query response. For a complete overview of data binding in Vaadin, please refer to <>. - - - - - diff --git a/documentation/application/application-resources.asciidoc b/documentation/application/application-resources.asciidoc index b5f5db91f2..ee1a8a7eb9 100644 --- a/documentation/application/application-resources.asciidoc +++ b/documentation/application/application-resources.asciidoc @@ -46,8 +46,7 @@ The resource classes in Vaadin are grouped under two interfaces: a generic [[figure.resource.classdiagram]] .Resource Interface and Class Diagram -image::img/resource_classdiagram-hi.png[] - +image::img/resource_classdiagram-hi.png[width=70%, scaledwidth=90%] [[application.resources.file]] == File Resources @@ -70,7 +69,6 @@ folder, which is a special folder that is never accessible using an URL, unlike the other folders of a web application. This is a security solution - another would be to store the resource elsewhere in the file system. - [source, java] ---- // Find the application directory @@ -83,7 +81,7 @@ FileResource resource = new FileResource(new File(basepath + // Show the image in the application Image image = new Image("Image from file", resource); - + // Let the user view the file in browser or download it Link link = new Link("Link to the image file", resource); ---- @@ -95,7 +93,7 @@ regular Eclipse Vaadin project, is shown in [[figure.application.resources.file]] .File Resource -image::img/resource-fileresource.png[] +image::img/resource-fileresource.png[width=50%, scaledwidth=80%] [[application.resources.class]] @@ -145,7 +143,7 @@ the folder structure for the theme resource file in an Eclipse project. [[figure.application.resources.theme]] .Theme Resources -image::img/resource-themeimage.png[] +image::img/resource-themeimage.png[width=40%, scaledwidth=70%] To use theme resources, you must set the theme for the UI. See <> @@ -173,7 +171,7 @@ public class MyImageSource implements StreamResource.StreamSource { ByteArrayOutputStream imagebuffer = null; int reloads = 0; - + /* We need to implement this method that returns * the resource as a stream. */ public InputStream getStream () { @@ -195,7 +193,7 @@ public class MyImageSource /* Write the image to a buffer. */ imagebuffer = new ByteArrayOutputStream(); ImageIO.write(image, "png", imagebuffer); - + /* Return a stream from the buffer. */ return new ByteArrayInputStream( imagebuffer.toByteArray()); @@ -218,13 +216,13 @@ Below we display the image with the [classname]#Image# component. ---- // Create an instance of our stream source. StreamResource.StreamSource imagesource = new MyImageSource (); - + // Create a resource that uses the stream source and give it a name. // The constructor will automatically register the resource in // the application. StreamResource resource = new StreamResource(imagesource, "myimage.png"); - + // Create an image component that gets its contents // from the resource. layout.addComponent(new Image("Image title", resource)); @@ -239,7 +237,3 @@ image::img/application_streamresource.png[] Another way to create dynamic content is a request handler, described in <>. - - - - diff --git a/documentation/architecture/architecture-client-side.asciidoc b/documentation/architecture/architecture-client-side.asciidoc index e16b003687..77e60a8940 100644 --- a/documentation/architecture/architecture-client-side.asciidoc +++ b/documentation/architecture/architecture-client-side.asciidoc @@ -17,7 +17,7 @@ The client-side engine is illustrated in <>. [[figure.architecture.client-side]] .Vaadin Client-Side Engine -image::img/clientside-arch-hi.png[] +image::img/clientside-arch-hi.png[width=60%, scaledwidth=90%] The client-side framework includes two kinds of built-in widgets: GWT widgets and Vaadin-specific widgets. The two widget collections have significant @@ -38,6 +38,3 @@ between the two sides. Integration of widgets with their server-side counterpart components is described in <>. - - - diff --git a/documentation/architecture/architecture-events.asciidoc b/documentation/architecture/architecture-events.asciidoc index e832c581fe..e273a28e97 100644 --- a/documentation/architecture/architecture-events.asciidoc +++ b/documentation/architecture/architecture-events.asciidoc @@ -37,7 +37,6 @@ corresponding listener class. For example, the [classname]#Button# has In the following, we handle button clicks with a listener implemented as an anonymous class: - [source, java] ---- final Button button = new Button("Push it!"); @@ -60,15 +59,21 @@ in this case the [classname]#Button#. [[figure.eventlistenerdiagram]] .Class Diagram of a Button Click Listener -image::img/events-classdiagram-hi.png[] +image::img/events-classdiagram-hi.png[width=50%, scaledwidth=75%] + +In Java 8, you can implement such functional interfaces with a lambda expression: + +[source, java] +---- +Button button = new Button("Push it!"); + +button.addClickListener(event -> + button.setCaption("You pushed it!")); +---- In the ancient times of C programming, __callback functions__ filled largely the same need as listeners do now. In object-oriented languages, we usually only have classes and methods, not functions, so the application has to give a class interface instead of a callback function pointer to the framework. -<> goes into details of handling events in practice. - - - +<> goes into details of handling events in practice. diff --git a/documentation/architecture/architecture-overview.asciidoc b/documentation/architecture/architecture-overview.asciidoc index 9307b7b72c..dee3a13fcf 100644 --- a/documentation/architecture/architecture-overview.asciidoc +++ b/documentation/architecture/architecture-overview.asciidoc @@ -18,7 +18,7 @@ code and services, and can be mixed together easily. [[figure.architecture.detailed]] .Vaadin Runtime Architecture -image::img/architecture-detailed-hi.png[] +image::img/architecture-detailed-hi.png[width=70%, scaledwidth=100%] <> gives a basic illustration of the client-side and server-side communications, in a running situation where the page with the diff --git a/documentation/architecture/architecture-technology.asciidoc b/documentation/architecture/architecture-technology.asciidoc index 39df9c3651..834bcba292 100644 --- a/documentation/architecture/architecture-technology.asciidoc +++ b/documentation/architecture/architecture-technology.asciidoc @@ -165,7 +165,7 @@ dynamic content. This is illustrated in [[figure.architecture.technology.servlet]] .Java Web Applications and Servlets -image::img/java-servlet-hi.png[] +image::img/java-servlet-hi.png[width=40%, scaledwidth=70%] Web applications are usually packaged and deployed to a server as __WAR__ ( __Web application ARchive__) files, which are Java JAR packages, which in turn @@ -202,7 +202,3 @@ widget set in technical terms, needs to be located under the [filename]#VAADIN/widgetsets# path in the web application. The precompiled default widget set is served from the [filename]#vaadin-client-compiled# JAR by the Vaadin Servlet. - - - - diff --git a/documentation/clientside/clientside-compiling.asciidoc b/documentation/clientside/clientside-compiling.asciidoc index 962ff76a6f..328487d178 100644 --- a/documentation/clientside/clientside-compiling.asciidoc +++ b/documentation/clientside/clientside-compiling.asciidoc @@ -35,8 +35,7 @@ The compiler compiles a __client module__, which can be either a pure client-side module or a Vaadin widget set, that is, the Vaadin Client-Side Engine that includes the widgets used in the application. The client module is defined with a module descriptor, which was described in -<>. +<>. The compiler writes the compilation result to a target folder that will include the compiled JavaScript with any static resources included in the module. @@ -46,11 +45,9 @@ the compiled JavaScript with any static resources included in the module. == Compiling in Eclipse When the Vaadin Plugin is installed in Eclipse, you can simply click the -[guibutton]#Compile Vaadin widgets# button in the toolbar. It will compile the -widget set it finds from the project. If the project has multiple widget sets, -such as one for custom widgets and another one for the project, you need to -select the module descriptor of the widget set to compile before clicking the -button. +button in the toolbar. +It will compile the widget set it finds from the project. +If the project has multiple widget sets, such as one for custom widgets and another one for the project, you need to select the module descriptor of the widget set to compile before clicking the button. The compilation with Vaadin Plugin for Eclipse currently requires that the module descriptor has suffix [filename]#Widgetset.gwt.xml#, although you can use @@ -62,9 +59,8 @@ written under [filename]#WebContent/VAADIN/widgetsets# folder. == Compiling with Ant You can find a script template for compiling widget sets with Ant and Ivy at the -link:http://vaadin.com/download/[Vaadin download page]. You can copy the build -script to your project and, once configured, run it with Ant. - +link:http://vaadin.com/download/[Vaadin download page]. +You can copy the build script to your project and, once configured, run it with Ant. [[clientside.compiling.maven]] == Compiling with Maven diff --git a/documentation/components/components-button.asciidoc b/documentation/components/components-button.asciidoc index 59ab380348..9105aa5e9b 100644 --- a/documentation/components/components-button.asciidoc +++ b/documentation/components/components-button.asciidoc @@ -30,23 +30,27 @@ button.addClickListener(new Button.ClickListener() { Notification.show("Do not press this button again"); } }); + +// Java 8 +button.addClickListener(click -> + Notification.show("Do not press this button again")); ---- See the http://demo.vaadin.com/book-examples-vaadin7/book#component.button.basic[on-line example, window="_blank"]. -The result is shown in <>. The listener can also -be given in the constructor, which is often perhaps simpler. +The listener can also be given in the constructor, which is often perhaps simpler. + +The button component can be styled in many ways, as illustrated in <>. [[figure.component.button.basic]] .Button in Different Styles of Valo Theme -image::img/button-example1.png[] +image::img/button-example1.png[width=70%, scaledwidth=100%] If you handle several buttons in the same listener, you can differentiate between them either by comparing the [classname]#Button# object reference returned by the [methodname]#getButton()# method of [classname]#Button.ClickEvent# to a kept reference. For a detailed description of these patterns together with some examples, please see -<>. +<>. == CSS Style Rules @@ -65,7 +69,3 @@ element, which may help in styling in some cases. Some built-in themes contain a small style, which you can enable by adding [parameter]#Reindeer.BUTTON_SMALL#, etc. The [classname]#BaseTheme# also has a [parameter]#BUTTON_LINK# style, which makes the button look like a hyperlink. - - - - diff --git a/documentation/components/components-calendar.asciidoc b/documentation/components/components-calendar.asciidoc index e682be2bb2..6b56483882 100644 --- a/documentation/components/components-calendar.asciidoc +++ b/documentation/components/components-calendar.asciidoc @@ -28,13 +28,9 @@ well as events, is handled with event listeners. Also date/time range selections, event dragging, and event resizing can be listened by the server. The weekly view has navigation buttons to navigate forward and backward in time. These actions are also listened by the server. Custom navigation can be -implemented using event handlers - -ifdef::web[] -, as described in -<> -endif::web[] -. +implemented using event +ifdef::web[handlers, as described in <>.] +ifndef::web[handlers.] The data source of a calendar can be practically anything, as its events are queried dynamically by the component. You can bind the calendar to a Vaadin @@ -67,7 +63,7 @@ always calculated in an accuracy of one millisecond. [[figure.components.calendar.daterange.monthly]] .Monthly view with All-Day and Normal Events -image::img/calendar-monthly.png[] +image::img/calendar-monthly.png[width=60%, scaledwidth=100%] The monthly view, shown in <>, can easily be used to control all types of events, but it is best suited for events @@ -78,7 +74,7 @@ hours. These events can not be moved by dragging in the monthly view. [[figure.components.calendar.daterange.weekly]] .Weekly View -image::img/calendar-weekly.png[] +image::img/calendar-weekly.png[width=60%, scaledwidth=100%] In <>, you can see four normal day events and also all-day events at the top of the time line grid. diff --git a/documentation/components/components-checkbox.asciidoc b/documentation/components/components-checkbox.asciidoc index 4e84010b6a..570a3ee083 100644 --- a/documentation/components/components-checkbox.asciidoc +++ b/documentation/components/components-checkbox.asciidoc @@ -46,7 +46,7 @@ The result is shown in <>. [[figure.components.checkbox.basic]] .An Example of a Check Box -image::img/checkbox-example1.png[] +image::img/checkbox-example1.png[width=35%, scaledwidth=50%] For an example on the use of check boxes in a table, see <>. @@ -64,9 +64,4 @@ For an example on the use of check boxes in a table, see The top-level element of a [classname]#CheckBox# has the [literal]#++v-checkbox++# style. It contains two sub-elements: the actual check box [literal]#++input++# element and the [literal]#++label++# element. If you -want to have the label on the left, you can change the positions with " -[literal]#++direction: rtl++#" for the top element. - - - - +want to have the label on the left, you can change the positions with "[literal]#++direction: rtl++#" for the top element. diff --git a/documentation/components/components-combobox.asciidoc b/documentation/components/components-combobox.asciidoc index 67c890779a..f3fd6d9962 100644 --- a/documentation/components/components-combobox.asciidoc +++ b/documentation/components/components-combobox.asciidoc @@ -20,7 +20,7 @@ selection component features are described in Components">>. .The [classname]#ComboBox# Component -image::img/combobox-basic.png[] +image::img/combobox-basic.png[width=35%, scaledwidth=50%] [classname]#ComboBox# supports adding new items when the user presses kbd:[Enter]. @@ -36,7 +36,7 @@ drop-down list by the text entered in the input box. [[figure.components.combobox.filter]] .Filtered Selection in [classname]#ComboBox# -image::img/combobox-filtering.png[] +image::img/combobox-filtering.png[width=35%, scaledwidth=50%] Pressing kbd:[Enter] will complete the item in the input box. Pressing kbd:[Up] and kbd:[Down] arrow keys can be used for selecting an item from the drop-down list. The drop-down list is paged and clicking on the scroll buttons will change to the @@ -62,7 +62,7 @@ component. [parameter]#STARTSWITH#:: Matches only items that begin with the given string. -[parameter]#OFF#(default):: Filtering is by default off and all items are shown all the time. +[parameter]#OFF# (default):: Filtering is by default off and all items are shown all the time. diff --git a/documentation/components/components-customcomponent.asciidoc b/documentation/components/components-customcomponent.asciidoc index cce897daa9..f8e8f1ddff 100644 --- a/documentation/components/components-customcomponent.asciidoc +++ b/documentation/components/components-customcomponent.asciidoc @@ -27,7 +27,6 @@ is typically a layout component that contains other components. For example: - [source, java] ---- class MyComposite extends CustomComponent { @@ -37,7 +36,7 @@ class MyComposite extends CustomComponent { VerticalLayout panelContent = new VerticalLayout(); panelContent.setMargin(true); // Very useful panel.setContent(panelContent); - + // Compose from multiple components Label label = new Label(message); label.setSizeUndefined(); // Shrink @@ -62,7 +61,6 @@ separate. You can use the component as follows: - [source, java] ---- MyComposite mycomposite = new MyComposite("Hello"); @@ -71,17 +69,14 @@ MyComposite mycomposite = new MyComposite("Hello"); The rendered component is shown in <>. [[figure.components.customcomponent]] -.A Custom Composite Component -image::img/customcomponent-example1.png[] +.A custom composite component +image::img/customcomponent-example1.png[width=25%, scaledwidth=40%] You can also inherit any other components, such as layouts, to attain similar -composition. ((("Google Web -Toolkit"))) +composition. +((("Google Web Toolkit"))) Even further, you can create entirely new low-level components, by integrating pure client-side components or by extending the client-side functionality of built-in components. Development of new components is covered in <>. - - - diff --git a/documentation/components/components-customfield.asciidoc b/documentation/components/components-customfield.asciidoc index f57eb2debf..9a05b4aa33 100644 --- a/documentation/components/components-customfield.asciidoc +++ b/documentation/components/components-customfield.asciidoc @@ -7,21 +7,13 @@ layout: page [[components.customfield]] = Composite Fields with [classname]#CustomField# -The [classname]#CustomField# is a way to create composite components like with -[classname]#CustomComponent#, except that it implements the -[interfacename]#Field# interface and inherit [classname]#AbstractField#, -described in -<>. A field allows editing a property value in the Vaadin data model, -and can be bound to data with field groups, as described in -<>. The field values are buffered and can be -validated with validators. - -A composite field class must implement the [methodname]#getType()# and -[methodname]#initContent()# methods. The latter should return the content -composite of the field. It is typically a layout component, but can be any -component. +The [classname]#CustomField# is a way to create composite components as with [classname]#CustomComponent#, except that it implements the [interfacename]#Field# interface and inherits [classname]#AbstractField#, described in <>. +A field allows editing a property value in the Vaadin data model, and can be bound to data with field groups, as described in <>. +The field values are buffered and can be validated with validators. + +A composite field class must implement the [methodname]#getType()# and [methodname]#initContent()# methods. +The latter should return the content composite of the field. +It is typically a layout component, but can be any component. It is also possible to override [methodname]#validate()#, [methodname]#setInternalValue()#, [methodname]#commit()#, @@ -29,5 +21,70 @@ It is also possible to override [methodname]#validate()#, to implement different functionalities in the field. Methods overriding [methodname]#setInternalValue()# should call the superclass method. +[[components.customfield.basic]] +== Basic Use + +Let us consider a simple custom switch button component that allows you to click a button to switch it "on" and "off", as illustrated in <>. + +[[figure.components.customfield.basic]] +.A custom switch button field +image::img/customfield-basic.png[width=25%, scaledwidth=40%] + +The field has [classname]#Boolean# value type, which the [methodname]#getType()# returns. +In [methodname]#initContent()#, we initialize the button and the layout. +Notice how we handle user interaction with the button to change the field value. +We customize the [methodname]#setValue()# method to reflect the state back to the user. + +[source, Java] +---- +public class BooleanField extends CustomField { + Button button = new Button(); + + public BooleanField() { + setValue(true); // On by default + } + + @Override + protected Component initContent() { + // Flip the field value on click + button.addClickListener(click -> + setValue(! (Boolean) getValue())); + + return new VerticalLayout( + new Label("Click the button"), button); + } + + @Override + public Class getType() { + return Boolean.class; + } + + @Override + public void setValue(Boolean newFieldValue) + throws com.vaadin.data.Property.ReadOnlyException, + ConversionException { + button.setCaption(newFieldValue? "On" : "Off"); + super.setValue(newFieldValue); + } +} +---- + +We can now use the field in all the normal ways for a field: + +[source, Java] +---- +// Create it +BooleanField field = new BooleanField(); + +// It's a field so we can set its value +field.setValue(new Boolean(true)); +// ...and read the value +Label value = new Label(field.getValue()? + "Initially on" : "Initially off"); +// ...and handle value changes +field.addValueChangeListener(event -> + value.setValue(field.getValue()? + "It's now on" : "It's now off")); +---- diff --git a/documentation/components/components-datefield.asciidoc b/documentation/components/components-datefield.asciidoc index 029b851947..f1fdd1e922 100644 --- a/documentation/components/components-datefield.asciidoc +++ b/documentation/components/components-datefield.asciidoc @@ -28,7 +28,7 @@ of the date field to current time by using the default constructor of the ---- // Create a DateField with the default style DateField date = new DateField(); - + // Set the date and time to present date.setValue(new Date()); ---- @@ -37,7 +37,7 @@ The result is shown in <>. [[figure.components.datefield.basic]] .[classname]#DateField# ([classname]#PopupDateField#) for Selecting Date and Time -image::img/datefield-example1.png[] +image::img/datefield-example1.png[width=35%, scaledwidth=60%] [[components.datefield.popupdatefield]] == [classname]#PopupDateField# @@ -75,7 +75,7 @@ The result is shown in <>. [[figure.components.datefield.popupdatefield.format]] .Custom Date Format for [classname]#PopupDateField# -image::img/datefield-formatting.png[] +image::img/datefield-formatting.png[width=35%, scaledwidth=60%] The same format specification is also used for parsing user-input date and time, as described later. @@ -143,13 +143,13 @@ PopupDateField date = new PopupDateField("My Date") { ConversionException("Not a number"); } } - + // Bad date throw new Property. ConversionException("Your date needs two slashes"); } }; - + // Display only year, month, and day in slash-delimited format date.setDateFormat("yyyy/MM/dd"); @@ -185,7 +185,7 @@ PopupDateField date = new PopupDateField("My Date") { Notification.show( "Your date needs two slashes", Notification.TYPE_WARNING_MESSAGE); - + // A failure must always also throw an exception throw new Property.ConversionException("Bad date"); } @@ -212,7 +212,7 @@ PopupDateField date = new PopupDateField(); // Set the prompt date.setInputPrompt("Select a date"); - + // Set width explicitly to accommodate the prompt date.setWidth("10em"); ---- @@ -264,19 +264,16 @@ The top-level element of the floating popup calendar has [literal]#++.v-datefield-popup++# style. Observe that the popup frame is outside the HTML structure of the component, hence it is not enclosed in the [literal]#++v-datefield++# element and does not include any custom styles. -//NOTE: May be changed in -#5752. +// NOTE: May be changed in #5752. The content in the [literal]#++v-datefield-calendarpanel++# is the same as in [classname]#InlineDateField#, as described in <>. - - [[components.datefield.calendar]] == [classname]#InlineDateField# The [classname]#InlineDateField# provides a date picker component with a month view. The user can navigate months and years by clicking the appropriate arrows. -Unlike with the popup variant, the month view is always visible in the inline +Unlike with the pop-up variant, the month view is always visible in the inline field. @@ -284,7 +281,7 @@ field. ---- // Create a DateField with the default style InlineDateField date = new InlineDateField(); - + // Set the date and time to present date.setValue(new java.util.Date()); ---- @@ -293,7 +290,7 @@ The result is shown in <>. [[figure.components.datefield.inlinedatefield]] .Example of the [classname]#InlineDateField# -image::img/datefield-inlinedatefield.png[] +image::img/datefield-inlinedatefield.png[width=35%, scaledwidth=60%] The user can also navigate the calendar using the cursor keys. @@ -339,8 +336,6 @@ The other style names should be self-explanatory. For weekdays, the [literal]#++v-first++# and [literal]#++v-last++# styles allow making rounded endings for the weekday bar. - - [[components.datefield.resolution]] == Date and Time Resolution @@ -386,6 +381,3 @@ Sunday, nor in some North African and Middle-Eastern countries, where the week begins on Saturday. In such locales, the week numbers are not displayed. endif::web[] - - - diff --git a/documentation/components/components-embedded.asciidoc b/documentation/components/components-embedded.asciidoc index bea83971a8..cc89114413 100644 --- a/documentation/components/components-embedded.asciidoc +++ b/documentation/components/components-embedded.asciidoc @@ -10,15 +10,12 @@ layout: page You can embed images in Vaadin UIs with the [classname]#Image# component, Adobe Flash graphics with [classname]#Flash#, and other web content with [classname]#BrowserFrame#. There is also a generic [classname]#Embedded# -component for embedding other object types. The embedded content is referenced -as __resources__, as described in -<>. +component for embedding other object types. +The embedded content is referenced as _resources_, as described in <>. The following example displays an image as a class resource loaded with the class loader: - [source, java] ---- Image image = new Image("Yes, logo:", @@ -30,7 +27,7 @@ The caption can be given as null to disable it. An empty string displays an empty caption which takes a bit space. The caption is managed by the containing layout. -You can set an altenative text for an embedded resource with +You can set an alternative text for an embedded resource with [methodname]#setAlternateText()#, which can be shown if images are disabled in the browser for some reason. The text can be used for accessibility purposes, such as for text-to-speech generation. @@ -77,8 +74,8 @@ resource is not enough. Because of how caching is handled in some browsers, you can cause a reload easiest by renaming the filename of the resource with a unique name, such as one including a timestamp. You should set cache time to zero with [methodname]#setCacheTime()# for the resource object when you create -it.//BUG -#2470. +it. +// BUG #2470. [source, java] @@ -137,7 +134,7 @@ for the Flash object element in HTML. == [classname]#BrowserFrame# The [classname]#BrowserFrame# allows embedding web content inside an HTML -<iframe> element. You can refer to an external URL with +`<iframe>` element. You can refer to an external URL with [classname]#ExternalResource#. As the [classname]#BrowserFrame# has undefined size by default, it is critical @@ -199,7 +196,3 @@ example above (where it was actually unnecessary). Some embeddable object types may require special support in the browser. You should make sure that there is a proper fallback mechanism if the browser does not support the embedded type. - - - - diff --git a/documentation/components/components-features.asciidoc b/documentation/components/components-features.asciidoc index fd4e748c05..625d9b8820 100644 --- a/documentation/components/components-features.asciidoc +++ b/documentation/components/components-features.asciidoc @@ -27,7 +27,6 @@ caption. The caption text can usually be given as the first parameter of a constructor of a component or with [methodname]#setCaption()#. - [source, java] ---- // New text field with caption "Name" @@ -47,7 +46,7 @@ rendered. [[figure.components.features.caption.layoutmanaged]] .Caption Management by [classname]#VerticalLayout# and [classname]#FormLayout#. -image::img/features-caption-layoutmanaged.png[] +image::img/features-caption-layoutmanaged.png[width=50%,scaledwidth=65%] Some components, such as [classname]#Button# and [classname]#Panel#, manage the caption themselves and display it inside the component. @@ -111,15 +110,14 @@ The tooltip is shown in <>. [[figure.components.tooltip.plain]] .Component Description as a Tooltip -image::img/tooltip-plain-withpointer-hi.png[] +image::img/tooltip-plain-withpointer-hi.png[width=30%, scaledwidth=100%] A description is rendered as a tooltip in most components. When a component error has been set with [methodname]#setComponentError()#, the error is usually also displayed in the tooltip, below the description. Components that are in error state will also display the error indicator. See -<>. +<>. The description is actually not plain text, but you can use HTML tags to format it. Such a rich text description can contain any HTML elements, including @@ -129,7 +127,8 @@ images. [source, java] ---- button.setDescription( - "

"+ + "

"+ "A richtext tooltip

"+ "
    "+ "
  • Use rich formatting with HTML
    • "+ @@ -143,7 +142,7 @@ The result is shown in <>. [[figure.components.tooltip.richtext]] .A Rich Text Tooltip -image::img/tooltip-richtext-withpointer-hi.png[] +image::img/tooltip-richtext-withpointer-hi.png[width=40%, scaledwidth=75%] Notice that the setter and getter are defined for all fields in the [classname]#Field# interface, not for all components in the @@ -179,7 +178,7 @@ buttons. [[figure.components.features.enabled.simple]] .An Enabled and Disabled [classname]#Button# -image::img/features-enabled-simple.png[] +image::img/features-enabled-simple.png[width=30%, scaledwidth=50%] A disabled component is automatically put in read-only state. No client interaction with such a component is sent to the server and, as an important @@ -206,19 +205,11 @@ have to join the style class names with a dot as done in the example below. This would make the border of all disabled text fields dotted. - -//TODO This may change to -$v-button-disabled-opacity -In Valo theme, the opacity of disabled components is specified with the -$v-disabled-opacity parameter - -ifdef::web[] -, as described in -<> -endif::web[] -. - +// TODO This may change to $v-button-disabled-opacity +In the Valo theme, the opacity of disabled components is specified with the +`$v-disabled-opacity` +ifndef::web[parameter.] +ifdef::web[parameter, as described in <>] [[components.features.icon]] == Icon @@ -260,7 +251,7 @@ so if the root component has an icon, it will not be rendered. [[figure.components.features.icon]] .Displaying an Icon from a Theme Resource. -image::img/features-icon.png[] +image::img/features-icon.png[width=40%, scaledwidth=60%] Some components, such as [classname]#Button# and [classname]#Panel#, manage the icon themselves and display it inside the component. @@ -307,12 +298,11 @@ layout.addComponent(date); ---- See the http://demo.vaadin.com/book-examples-vaadin7/book#component.features.locale.simple[on-line example, window="_blank"]. -The resulting date field is shown in -<>. +The resulting date field is shown in <>. [[figure.components.features.locale.simple]] -.Set Locale for [classname]#InlineDateField# -image::img/features-locale-simple.png[] +.Set locale for [classname]#InlineDateField# +image::img/features-locale-simple.png[width=40%, scaledwidth=60%] ifdef::web[] [[components.features.locale.get]] @@ -330,7 +320,6 @@ to the UI, which is usually the case in most constructors, so it is a bit awkward to use it for internationalization. You can get the locale in [methodname]#attach()#, as shown in the following example: - [source, java] ---- Button cancel = new Button() { @@ -349,7 +338,6 @@ See the http://demo.vaadin.com/book-examples-vaadin7/book#component.features.loc However, it is normally a better practice to use the locale of the current UI to get the localized resource right when the component is created. - [source, java] ---- // Captions are stored in MyAppCaptions resource bundle @@ -364,7 +352,6 @@ Button cancel = layout.addComponent(cancel); ---- See the http://demo.vaadin.com/book-examples-vaadin7/book#component.features.locale.get-ui[on-line example, window="_blank"]. - endif::web[] ifdef::web[] @@ -435,7 +422,7 @@ See the http://demo.vaadin.com/book-examples-vaadin7/book#component.features.loc The user interface is shown in <>. [[figure.components.features.locale.selection]] -.Selecting a Locale +.Selecting a locale image::img/features-locale-selection.png[] endif::web[] @@ -450,7 +437,6 @@ The property defines whether the value of a component can be changed. The property is mainly applicable to [classname]#Field# components, as they have a value that can be edited by the user. - [source, java] ---- TextField readwrite = new TextField("Read-Write"); @@ -468,8 +454,8 @@ The resulting read-only text field is shown in <>. [[figure.components.features.readonly.simple]] -.A Read-Only Component. -image::img/features-readonly-simple.png[] +.A read-only component +image::img/features-readonly-simple.png[width=50%, scaledwidth=80%] Setting a layout or some other component container as read-only does not usually make the contained components read-only recursively. This is different from, for @@ -559,7 +545,6 @@ a [classname]#Panel# component would conflict with the built-in The following CSS rule would apply the style to any component that has the [literal]#++mystyle++# style. - [source, css] ---- .mystyle { @@ -571,13 +556,11 @@ The following CSS rule would apply the style to any component that has the } ---- -The resulting styled component is shown in -<> +The resulting styled component is shown in <> [[figure.components.features.stylename]] -.Component with a Custom Style -image::img/features-stylename-simple.png[] - +.Component with a custom style +image::img/features-stylename-simple.png[width=50%, scaledwidth=75%] [[components.features.visible]] == Visible @@ -592,7 +575,6 @@ rules. This feature is important for security if you have components that contain security-critical information that must only be shown in specific application states. - [source, java] ---- TextField invisible = new TextField("No-see-um"); @@ -605,7 +587,7 @@ The resulting invisible component is shown in <>. [[figure.components.features.visible.simple]] -.An Invisible Component. +.An invisible component image::img/features-visible-simple.png[] Beware that invisible beings can leave footprints. The containing layout cell @@ -664,7 +646,7 @@ mycomponent.setWidth("100%"); mycomponent.setHeight("400px"); ---- -The " [literal]#++100%++#" percentage value makes the component take all +The "[literal]#++100%++#" percentage value makes the component take all available size in the particular direction (see the description of [parameter]#Sizeable.UNITS_PERCENTAGE# in the table below). You can also use the shorthand method [methodname]#setSizeFull()# to set the size to 100% in both @@ -677,39 +659,29 @@ can set the height or width as undefined with [parameter]#Sizeable.SIZE_UNDEFINED# parameter for [methodname]#setWidth()# and [methodname]#setHeight()#. -You always need to keep in mind that __a layout with undefined size may not -contain components with defined relative size__, such as "full size". See -<> for details. +Always keep in mind that _a layout with undefined size may not contain components with defined relative size_, such as "full size", except in some special cases. +See <> for details. -The <> lists the available units and -their codes defined in the [classname]#Sizeable# interface. +The <> table lists the available units and their codes defined in the [interfacename]#Sizeable# interface. [[components.features.sizeable.units.table]] -.Size Units - +.Size units +[cols="5,2,10", options="header"] |=============== -|[parameter]#Unit.PIXELS#|px|The__pixel__is the basic hardware-specific measure of one physical display pixel. -|[parameter]#Unit.POINTS#|pt|The__point__is a typographical unit, which is usually defined as 1/72 inches or about 0.35 mm. However, on displays the size can vary significantly depending on display metrics. -|[parameter]#Unit.PICAS#|pc|The__pica__is a typographical unit, defined as 12 points, or 1/7 inches or about 4.233 mm. On displays, the size can vary depending on display metrics. +|Constant|Unit|Description +|[parameter]#Unit.PIXELS#|px|The _pixel_ is the basic hardware-specific measure of one physical display pixel. +|[parameter]#Unit.POINTS#|pt|The _point_ is a typographical unit, which is usually defined as 1/72 inches or about 0.35 mm. However, on displays the size can vary significantly depending on display metrics. +|[parameter]#Unit.PICAS#|pc|The _pica_ is a typographical unit, defined as 12 points, or 1/7 inches or about 4.233 mm. On displays, the size can vary depending on display metrics. |[parameter]#Unit.EM#|em|A unit relative to the used font, the width of the upper-case "M" letter. |[parameter]#Unit.EX#|ex|A unit relative to the used font, the height of the lower-case "x" letter. |[parameter]#Unit.MM#|mm|A physical length unit, millimeters on the surface of a display device. However, the actual size depends on the display, its metrics in the operating system, and the browser. -|[parameter]#Unit.CM#|cm|A physical length unit,__centimeters__on the surface of a display device. However, the actual size depends on the display, its metrics in the operating system, and the browser. -|[parameter]#Unit.INCH#|in|A physical length unit,__inches__on the surface of a display device. However, the actual size depends on the display, its metrics in the operating system, and the browser. -|[parameter]#Unit.PERCENTAGE#|%|A relative percentage of the available size. For example, for the top-level layout[parameter]#100%#would be the full width or height of the browser window. The percentage value must be between 0 and 100. - +|[parameter]#Unit.CM#|cm|A physical length unit, _centimeters_ on the surface of a display device. However, the actual size depends on the display, its metrics in the operating system, and the browser. +|[parameter]#Unit.INCH#|in|A physical length unit, _inches_ on the surface of a display device. However, the actual size depends on the display, its metrics in the operating system, and the browser. +|[parameter]#Unit.PERCENTAGE#|%|A relative percentage of the available size. For example, for the top-level layout [parameter]#100%# would be the full width or height of the browser window. The percentage value must be between 0 and 100. |=============== - - -If a component inside [classname]#HorizontalLayout# or -[classname]#VerticalLayout# has full size in the namesake direction of the -layout, the component will expand to take all available space not needed by the -other components. See -<> for details. - +If a component inside [classname]#HorizontalLayout# or [classname]#VerticalLayout# has full size in the namesake direction of the layout, the component will expand to take all available space not needed by the other components. +See <> for details. == Managing Input Focus @@ -719,8 +691,7 @@ component allows inputting text, the focus and insertion point are indicated by a cursor. Pressing the Tab key moves the focus to the component next in the __focus order__. -Focusing is supported by all [classname]#Field# components and also by -[classname]#Upload#. +Focusing is supported by all [classname]#Field# components and also by the [classname]#Upload# component. The focus order or __tab index__ of a component is defined as a positive integer value, which you can set with [methodname]#setTabIndex()# and get with diff --git a/documentation/components/components-fields.asciidoc b/documentation/components/components-fields.asciidoc index 229592c74e..3083e331ac 100644 --- a/documentation/components/components-fields.asciidoc +++ b/documentation/components/components-fields.asciidoc @@ -15,8 +15,8 @@ user interface. <> illustrates the inheritance relationships and the important interfaces and base classes. [[figure.components.fields]] -.Field Components -image::img/field-diagram-hi.png[] +.Field components +image::img/field-diagram-hi.png[width=60%, scaledwidth=100%] Field components are built upon the framework defined in the [classname]#Field# interface and the [classname]#AbstractField# base class. @@ -30,7 +30,7 @@ The description of the field interfaces and base classes is broken down in the following sections. [[components.fields.field]] -== [classname]#Field# Interface +== The [classname]#Field# Interface The [classname]#Field# interface inherits the [classname]#Component# superinterface and also the [classname]#Property# interface to have a value for @@ -39,8 +39,8 @@ the field. [classname]#AbstractField# is the only class implementing the <>. [[figure.components.fields.field]] -.[classname]#Field# Interface Inheritance Diagram -image::img/field-interface-hi.png[] +.[classname]#Field# interface inheritance +image::img/field-interface-hi.png[width=60%, scaledwidth=100%] You can set the field value with the [methodname]#setValue()# and read with the [methodname]#getValue()# method defined in the [classname]#Property# interface. @@ -61,9 +61,6 @@ guide. The error message is set as the component error for the field and is usually displayed in a tooltip when the mouse pointer hovers over the error indicator. - - - [[components.fields.databinding]] == Data Binding and Conversions @@ -180,28 +177,30 @@ requires that the value type of the property data source is Vaadin includes the following built-in validators. The property value type is indicated. -[classname]#BeanValidator#:: Validates a bean property according to annotations defined in the Bean -Validation API 1.0 (JSR-303). This validator is usually not used explicitly, but -they are created implicitly when binding fields in a -[classname]#BeanFieldGroup#. Using bean validation requires an implementation -library of the API. See -<> for details. - -[classname]#CompositeValidator#:: Combines validators using logical AND and OR operators. +[classname]#BeanValidator#:: +Validates a bean property according to annotations defined in the Bean Validation API 1.0 (JSR-303). +This validator is usually not used explicitly, but they are created implicitly when binding fields in a [classname]#BeanFieldGroup#. +Using bean validation requires an implementation library of the API. +See <> for details. -[classname]#DateRangeValidator#:[classname]#Date#:: Checks that the date value is within the range at or between two given -dates/times. +[classname]#CompositeValidator#:: +Combines validators using logical AND and OR operators. -[classname]#DoubleRangeValidator#:[classname]#Double#:: Checks that the double value is at or between two given values. +[classname]#DateRangeValidator#: [classname]#Date#:: +Checks that the date value is within the range at or between two given dates/times. -[classname]#EmailValidator#:[classname]#String#:: Checks that the string value is a syntactically valid email address. The -validated syntax is close to the RFC 822 standard regarding email addresses. +[classname]#DoubleRangeValidator#: [classname]#Double#:: +Checks that the double value is at or between two given values. -[classname]#IntegerRangeValidator#:[classname]#Integer#:: Checks that the integer value is at or between two given values. +[classname]#EmailValidator#: [classname]#String#:: +Checks that the string value is a syntactically valid email address. +The validated syntax is close to the RFC 822 standard regarding email addresses. -[classname]#NullValidator#:: Checks that the value is or is not a null value. +[classname]#IntegerRangeValidator#: [classname]#Integer#:: +Checks that the integer value is at or between two given values. +[classname]#NullValidator#:: +Checks whether the value is or is not a null value. + For the validator to be meaningful, the component must support inputting null values. For example, for selection components and [classname]#TextField#, @@ -216,9 +215,11 @@ Setting field as __required__ can be used for similar effect, and it also enables an indicator to indicate that a value is required. endif::web[] -[classname]#RegexpValidator#:[classname]#String#:: Checks that the value matches with the given regular expression. +[classname]#RegexpValidator#: [classname]#String#:: +Checks that the value matches with the given regular expression. -[classname]#StringLengthValidator#:[classname]#String#:: Checks that the length of the input string is at or between two given lengths. +[classname]#StringLengthValidator#: [classname]#String#:: +Checks that the length of the input string is at or between two given lengths. ifdef::web[] + @@ -228,16 +229,13 @@ length, so it will be invalid if the minimum length is greater than zero. Allowing null value is meaningful only if inputting null values is enabled with [methodname]#setNullSettingAllowed(true)#, and typically in such case, you want to set the null representation to empty string with -[methodname]#setNullRepresentation("")#. Note that __this parameter is -deprecated__ and should normally be [parameter]#true#; then you can use +[methodname]#setNullRepresentation("")#. Note that _this parameter is +deprecated_ and should normally be [parameter]#true#; then you can use [methodname]#setRequired()# (for the false case) or [classname]#NullValidator#. endif::web[] - - Please see the API documentation for more details. - [[components.fields.validation.automatic]] === Automatic Validation @@ -275,12 +273,12 @@ final TextField field = new TextField("Name"); field.setNullRepresentation(""); field.setNullSettingAllowed(true); layout.addComponent(field); - + // Define validation as usual field.addValidator(new StringLengthValidator( "The name must be 1-10 letters (was {0})", 1, 10, true)); - + // Run validation explicitly Button validate = new Button("Validate"); validate.addClickListener(new ClickListener() { @@ -321,7 +319,7 @@ class MyValidator implements Validator { } } -final TextField field = new TextField("Say hello"); +TextField field = new TextField("Say hello"); field.addValidator(new MyValidator()); field.setImmediate(true); layout.addComponent(field); @@ -338,8 +336,4 @@ Forms by Binding Fields to Items">>, calling [methodname]#commit()# for the group runs the validation for all the fields in the group, and if successful, writes the input values to the data source. - - (((range="endofrange", startref="term.components.fields"))) - - diff --git a/documentation/components/components-grid.asciidoc b/documentation/components/components-grid.asciidoc index 6cd064c4b7..9b465a71b0 100644 --- a/documentation/components/components-grid.asciidoc +++ b/documentation/components/components-grid.asciidoc @@ -30,8 +30,8 @@ easily. The grid data can be sorted by clicking on a column header; shift-clicking a column header enables secondary sorting criteria. [[figure.components.grid.features]] -.A [classname]#Grid# Component -image::img/grid-features.png[] +.A [classname]#Grid# +image::img/grid-features.png[width=70%, scaledwidth=100%] The data area can be scrolled both vertically and horizontally. The leftmost columns can be frozen, so that they are never scrolled out of the view. The data @@ -263,7 +263,7 @@ Space bar is the default key for toggling the selection, but it can be customize [[figure.components.grid.selection.multi]] .Multiple Selection in [classname]#Grid# -image::img/grid-selection-multi.png[] +image::img/grid-selection-multi.png[width=50%, scaledwidth=75%] The selection is managed through the [classname]#MultiSelectionMode# class. The currently selected rows can be set with [methodname]#setSelected()# by a @@ -296,7 +296,7 @@ Button delSelected = new Button("Delete Selected", e -> { // Delete all selected data items for (Object itemId: selection.getSelectedRows()) grid.getContainerDataSource().removeItem(itemId); - + // Otherwise out of sync with container grid.getSelectionModel().reset(); @@ -498,7 +498,6 @@ Note that, while [classname]#GeneratedPropertyContainer# implements sorting on the generated properties requires special handling. In such cases, generated properties or the entire container might not actually be sortable. - [[components.grid.renderer]] == Column Renderers @@ -506,12 +505,11 @@ A __renderer__ is a feature that draws the client-side representation of a data value. This allows having images, HTML, and buttons in grid cells. [[figure.components.grid.renderer]] -.Column Renderers: Image, Date, HTML, and Button -image::img/grid-renderers.png[] - -Renderers implement the [interfacename]#Renderer# interface. You set the column -renderer in the [classname]#Grid.Column# object as follows: +.Column renderers: image, date, HTML, and button +image::img/grid-renderers.png[width=75%, scaledwidth=100%] +Renderers implement the [interfacename]#Renderer# interface. +You set the column renderer in the [classname]#Grid.Column# object as follows: [source, java] ---- @@ -531,16 +529,14 @@ client-side to be rendered with the renderer. The following renderers are available, as defined in the server-side [package]#com.vaadin.ui.renderers# package: -[classname]#ButtonRenderer#:: Renders the data value as the caption of a button. A -[interfacename]#RendererClickListener# can be given to handle the button clicks. +[classname]#ButtonRenderer#:: Renders the data value as the caption of a button. A [interfacename]#RendererClickListener# can be given to handle the button clicks. ifdef::web[] ++ Typically, a button renderer is used to display buttons for operating on a data item, such as edit, view, delete, etc. It is not meaningful to store the button captions in the data source, rather you want to generate them, and they are usually all identical. - - + [source, java] ---- @@ -579,15 +575,15 @@ grid.getColumn("delete") .removeItem(e.getItemId()))); ---- endif::web[] -[classname]#ImageRenderer#:: Renders the cell as an image. The column type must be a -[interfacename]#Resource#, as described in -<>; only [classname]#ThemeResource# and + +[classname]#ImageRenderer#:: Renders the cell as an image. +The column type must be a [interfacename]#Resource#, as described in +<>; only [classname]#ThemeResource# and [classname]#ExternalResource# are currently supported for images in [classname]#Grid#. ifdef::web[] - ++ [source, java] ---- grid.addColumn("picture", Resource.class) @@ -605,7 +601,6 @@ Instead of creating the resource objects explicitly, as was done above, you could generate them dynamically from file name strings using a [interfacename]#Converter# for the column. - + [source, java] ---- @@ -678,13 +673,14 @@ endif::web[] } ---- endif::web[] + [classname]#DateRenderer#:: Formats a column with a [classname]#Date# type using string formatter. The format string is same as for [methodname]#String.format()# in Java API. The date is passed in the parameter index 1, which can be omitted if there is only one -format specifier, such as " [literal]#++%tF++#". +format specifier, such as "[literal]#++%tF++#". ifdef::web[] - ++ [source, java] ---- Grid.Column bornColumn = grid.getColumn("born"); @@ -698,13 +694,13 @@ Optionally, a locale can be given. Otherwise, the default locale (in the component tree) is used. endif::web[] + [classname]#HTMLRenderer#:: Renders the cell as HTML. This allows formatting cell content, as well as using HTML features such as hyperlinks. ifdef::web[] ++ First, set the renderer in the [classname]#Grid.Column# object: - - + [source, java] ---- @@ -716,7 +712,6 @@ ifdef::web[] Then, in the grid data, give the cell content: endif::web[] - + [source, java] ---- @@ -727,8 +722,8 @@ grid.addRow("Nicolaus Copernicus", 1543, + You could also use a [interfacename]#PropertyFormatter# or a generated column to generate the HTML for the links. - endif::web[] + [classname]#NumberRenderer#:: Formats column values with a numeric type extending [classname]#Number#: [classname]#Integer#, [classname]#Double#, etc. The format can be specified either by the subclasses of [classname]#java.text.NumberFormat#, namely @@ -736,9 +731,8 @@ either by the subclasses of [classname]#java.text.NumberFormat#, namely [methodname]#String.format()#. ifdef::web[] ++ For example: - - + [source, java] ---- @@ -770,9 +764,8 @@ endif::web[] must be between 0.0 and 1.0. ifdef::web[] ++ For example: - - + [source, java] ---- @@ -973,7 +966,7 @@ the container must be of type that implements [[figure.components.grid.filtering]] .Filtering Grid -image::img/grid-filtering.png[] +image::img/grid-filtering.png[width=50%, scaledwidth=80%] The filtering illustrated in <> can be created as follows: @@ -997,16 +990,16 @@ HeaderRow filterRow = grid.appendHeaderRow(); for (Object pid: grid.getContainerDataSource() .getContainerPropertyIds()) { HeaderCell cell = filterRow.getCell(pid); - + // Have an input field to use for filter TextField filterField = new TextField(); filterField.setColumns(8); - + // Update filter When the filter input is changed filterField.addTextChangeListener(change -> { // Can't modify filters so need to replace container.removeContainerFilters(pid); - + // (Re)create the filter if necessary if (! change.getText().isEmpty()) container.addContainerFilter( @@ -1028,7 +1021,7 @@ secondary or more sort criteria. [[figure.components.grid.sorting]] .Sorting Grid on Multiple Columns -image::img/grid-sorting.png[] +image::img/grid-sorting.png[width=50%, scaledwidth=75%] Defining sort criteria programmatically can be done with the various alternatives of the [methodname]#sort()# method. You can sort on a specific @@ -1052,7 +1045,7 @@ direction can be given with an optional parameter. [source, java] ---- -// Sort first by city and then by name +// Sort first by city and then by name grid.sort(Sort.by("city", SortDirection.ASCENDING) .then("name", SortDirection.DESCENDING)); ---- @@ -1098,7 +1091,7 @@ A row under editing is illustrated in <>. [[figure.components.grid.editing]] .Editing a Grid Row -image::img/grid-editor-basic.png[] +image::img/grid-editor-basic.png[width=50%, scaledwidth=75%] [[components.grid.editing.unbuffered]] === Unbuffered Mode @@ -1196,9 +1189,9 @@ public class Person implements Serializable { @NotNull @Size(min=2, max=10) private String name; - + @Min(1) - @Max(130) + @Max(130) private int age; ...] ---- @@ -1241,7 +1234,7 @@ first error in the editor. [[figure.components.grid.errors]] .Editing a Grid Row -image::img/grid-editor-errors.png[] +image::img/grid-editor-errors.png[width=50%, scaledwidth=75%] You can modify the error handling by implementing a custom [interfacename]#EditorErrorHandler# or by extending the @@ -1403,5 +1396,3 @@ element, as well as the buttons. ((())) - - diff --git a/documentation/components/components-label.asciidoc b/documentation/components/components-label.asciidoc index 4545d40924..424e5ae76c 100644 --- a/documentation/components/components-label.asciidoc +++ b/documentation/components/components-label.asciidoc @@ -21,7 +21,6 @@ You can give the label text most conviniently in the constructor, as is done in the following. Label has 100% default width, so the containing layout must also have defined width. - [source, java] ---- // A container that is 100% wide by default @@ -36,13 +35,12 @@ See the http://demo.vaadin.com/book-examples-vaadin7/book#component.label.basic[ accessing the text value, so you can get and set the text with [methodname]#getValue()# and [methodname]#setValue()#. - [source, java] ---- // Get the label's text to initialize a field TextField editor = new TextField(null, // No caption label.getValue()); - + // Change the label's text editor.addValueChangeListener(event -> // Java 8 label.setValue(editor.getValue())); @@ -91,7 +89,7 @@ width of [classname]#Label# is the default 100%, the text in the [[figure.components.label]] .The Label Component -image::img/label-example1.png[] +image::img/label-example1.png[width=50%, scaledwidth=75%] Setting [classname]#Label# to undefined width will cause it to not wrap at the end of the line, as the width of the content defines the width. If placed inside @@ -162,7 +160,7 @@ Label textLabel = new Label( Label preLabel = new Label( "Preformatted text is shown in an HTML 
     tag.\n" +
     "Formatting such as\n" +
-    "  * newlines\n" + 
+    "  * newlines\n" +
     "  * whitespace\n" +
     "and such are preserved. HTML tags, \n"+
     "such as bold, are quoted.",
@@ -184,7 +182,7 @@ The rendering will look as shown in <>.
 
 [[figure.components.label.content-mode]]
 .Label Content Modes
-image::img/label-modes.png[]
+image::img/label-modes.png[width=75%, scaledwidth=100%]
 
 
 ifdef::web[]
@@ -266,7 +264,7 @@ You can specify the data source either in the constructor or by the
 // Some property
 ObjectProperty property =
     new ObjectProperty("some value");
-        
+
 // Label that is bound to the property
 Label label = new Label(property);
 ----
@@ -305,7 +303,3 @@ would be delegated through the label.
 The [classname]#Label# component has a [literal]#++v-label++# overall style. In
 the [parameter]#PREFORMATTED# content mode, the text is wrapped inside a
 [literal]#++
    ++# element.
-
-
-
-
diff --git a/documentation/components/components-link.asciidoc b/documentation/components/components-link.asciidoc
index ce45d91a46..591c407741 100644
--- a/documentation/components/components-link.asciidoc
+++ b/documentation/components/components-link.asciidoc
@@ -55,7 +55,10 @@ caption below it.
 
 [[figure.components.link.basic]]
 .[classname]#Link# Example
-image::img/link.png[]
+image::img/link.png[width=30%, scaledwidth=70%]
+
+[[components.link.new-window]]
+== Opening a New Window
 
 With the simple constructor used in the above example, the resource is opened in
 the current window. Using the constructor that takes the target window as a
@@ -66,7 +69,6 @@ browser, the target can be any window, including windows not managed by the
 application itself. You can use the special underscored target names, such as
 [literal]#++_blank++# to open the link to a new browser window or tab.
 
-
 [source, java]
 ----
 // Hyperlink to a given URL
@@ -75,35 +77,15 @@ Link link = new Link("Take me a away to a faraway land",
 
 // Open the URL in a new window/tab
 link.setTargetName("_blank");
-        
+
 // Indicate visually that it opens in a new window/tab
 link.setIcon(new ThemeResource("icons/external-link.png"));
 link.addStyleName("icon-after-caption");
 ----
 See the http://demo.vaadin.com/book-examples-vaadin7/book#component.link.target[on-line example, window="_blank"].
 
-Normally, the link icon is before the caption. You can have it right of the
-caption by reversing the text direction in the containing element.
-
-
-[source, css]
-----
-/* Position icon right of the link caption. */
-.icon-after-caption {
-    direction: rtl;
-}
-/* Add some padding around the icon. */
-.icon-after-caption .v-icon {
-    padding: 0 3px;
-}
-----
-See the http://demo.vaadin.com/book-examples-vaadin7/book#component.link.target[on-line example, window="_blank"].
-
-The resulting link is shown in <>.
-
-[[figure.components.link.new-window]]
-.Link That Opens a New Window
-image::img/link-new.png[]
+[[components.link.pop-up]]
+== Opening as a Pop-Up Window
 
 With the [literal]#++_blank++# target, a normal new browser window is opened. If
 you wish to open it in a popup window (or tab), you need to give a size for the
@@ -113,7 +95,6 @@ which takes any of the defined border styles [parameter]#TARGET_BORDER_DEFAULT#,
 [parameter]#TARGET_BORDER_MINIMAL#, and [parameter]#TARGET_BORDER_NONE#. The
 exact result depends on the browser.
 
-
 [source, java]
 ----
 // Open the URL in a popup
@@ -124,15 +105,16 @@ link.setTargetWidth(400);
 ----
 See the http://demo.vaadin.com/book-examples-vaadin7/book#component.link.target[on-line example, window="_blank"].
 
-In addition to the [classname]#Link# component, Vaadin allows alternative ways
-to make hyperlinks. The [classname]#Button# component has a
-[parameter]#Reindeer.BUTTON_LINK# style name that makes it look like a
-hyperlink, while handling clicks in a server-side click listener instead of in
-the browser. Also, you can make hyperlinks (or any other HTML) in a
-[classname]#Label# in HTML content mode.
+== Alternatives
 
-== CSS Style Rules
+In addition to the [classname]#Link# component, Vaadin allows alternative ways to make hyperlinks.
+Also, you can make hyperlinks (or any other HTML) in a [classname]#Label# in HTML content mode.
 
+The [classname]#Button# component has a [parameter]#Reindeer.BUTTON_LINK# style name that makes it look like a hyperlink, while handling clicks in a server-side click listener instead of in the browser.
+However, browsers do not generally allow opening new windows from with browser code, so for such tasks you need to use the [classname]#BrowserWindowOpener# extension described in <>
+
+
+== CSS Style Rules
 
 [source, css]
 ----
@@ -156,6 +138,30 @@ please notice that [literal]#++a:hover++# must come after an
 [literal]#++a:link++# and [literal]#++a:visited++#, and [literal]#++a:active++#
 after the [literal]#++a:hover++#.
 
+ifdef::web[]
+=== Icon Position
 
+Normally, the link icon is before the caption.
+You can have it right of the caption by reversing the text direction in the containing element.
 
+[source, css]
+----
+/* Position icon right of the link caption. */
+.icon-after-caption {
+    direction: rtl;
+}
 
+/* Add some padding around the icon. */
+.icon-after-caption .v-icon {
+    padding: 0 3px;
+}
+----
+See the http://demo.vaadin.com/book-examples-vaadin7/book#component.link.target[on-line example, window="_blank"].
+
+The resulting link is shown in <>.
+
+[[figure.components.link.new-window]]
+.Link That Opens a New Window
+image::img/link-new.png[width=25%, scaledwidth=50%]
+
+endif::web[]
diff --git a/documentation/components/components-listselect.asciidoc b/documentation/components/components-listselect.asciidoc
index b67f678957..261b68db46 100644
--- a/documentation/components/components-listselect.asciidoc
+++ b/documentation/components/components-listselect.asciidoc
@@ -23,7 +23,7 @@ visually identical in both modes.
 ----
 // Create the selection component
 ListSelect select = new ListSelect("The List");
-        
+
 // Add some items (here by the item ID as the caption)
 select.addItems("Mercury", "Venus", "Earth", ...);
 
@@ -37,11 +37,10 @@ The number of visible items is set with [methodname]#setRows()#.
 
 [[figure.components.listselect.basic]]
 .The [classname]#ListSelect# Component
-image::img/listselect-basic.png[]
+image::img/listselect-basic.png[width=35%, scaledwidth=50%]
 
 Common selection component features are described in
-<>.
+<>.
 
 == CSS Style Rules
 
@@ -56,7 +55,3 @@ Components">>.
 The component has an overall [literal]#++v-select++# style. The native
 [literal]#++++# element in HTML.
-[classname]#OptionGroup# (Section <>):: Shows the items as a vertically arranged group of radio buttons in the single selection mode and of check boxes in multiple selection mode.
-[classname]#TwinColSelect# (Section <>):: Shows two list boxes side by side where the user can select items from a list of available items and move them to a list of selected items using control buttons.
+// TODO Only use section numbers here, prefixed with "Section", not include section title
 
+[classname]#ComboBox# (<>)::
+A drop-down list with a text box, where the user can type text to find matching items.
+The component also provides an input prompt and the user can enter new items.
 
-In addition, the [classname]#Tree#, [classname]#Table#, and
-[classname]#TreeTable# components allow special forms of selection. They also
-inherit the [classname]#AbstractSelect#.
+[classname]#ListSelect# (<>)::
+A vertical list box for selecting items in either single or multiple selection mode.
+
+[classname]#NativeSelect# (<>)::
+Provides selection using the native selection component of the browser, typically a drop-down list for single selection and a multi-line list in multiselect mode.
+This uses the [literal]#++