From d8e1ca9ad8ce76185837053a730676fa9fa18352 Mon Sep 17 00:00:00 2001
From: Pekka Hyvönen <pekka@vaadin.com>
Date: Mon, 19 Dec 2016 19:31:36 +0200
Subject: Fix documentation for /components (#8051)

Added warning where not updated.
Removed outdated documentation.
Tried to fix parts where it was feasible.
---
 documentation/components/components-label.asciidoc | 41 ++++++++++------------
 1 file changed, 18 insertions(+), 23 deletions(-)

(limited to 'documentation/components/components-label.asciidoc')

diff --git a/documentation/components/components-label.asciidoc b/documentation/components/components-label.asciidoc
index f225c6ba73..ee2113fa84 100644
--- a/documentation/components/components-label.asciidoc
+++ b/documentation/components/components-label.asciidoc
@@ -17,19 +17,19 @@ for short simple labels or for displaying long text, such as paragraphs. The
 text can be formatted in HTML or as preformatted text, depending on the
 __content mode__ of the label.
 
-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.
+You can give the label text most conveniently in the constructor, as is done in
+the following. Label has undefined default width, so it will only take the space it needs.
+
 
 [source, java]
 ----
 // A container that is 100% wide by default
 VerticalLayout layout = new VerticalLayout();
 
+// label will only take the space it needs
 Label label = new Label("Labeling can be dangerous");
 layout.addComponent(label);
 ----
-See the http://demo.vaadin.com/book-examples-vaadin7/book#component.label.basic[on-line example, window="_blank"].
 
 You can get and set the text of a [classname]#Label# with the
 [methodname]#getValue()# and [methodname]#setValue()# methods.
@@ -41,10 +41,8 @@ TextField editor = new TextField(null, // No caption
                                  label.getValue());
 
 // Change the label's text
-editor.onChange(label::setValue);
-// or onChange(value -> label.setValue(value));
+editor.addValueChangeListener(event -> label.setValue(event.getValue()));
 ----
-See the http://demo.vaadin.com/book-examples-vaadin7/book#component.label.basic[on-line example, window="_blank"].
 
 Even though [classname]#Label# is text and is often used as a caption, it is a
 normal component and therefore also has a caption that you can set with
@@ -54,11 +52,9 @@ managed by the containing layout.
 [[components.label.wrap]]
 == Text Width and Wrapping
 
-[classname]#Label# has 100% default width, so the containing layout must also
-have a defined width. If the width of the label's text exceeds the width of the
-label, the text will wrap around and continue on the next line. Some layout
-components have undefined width by default, such as
-[classname]#HorizontalLayout#, so you need to pay special care with them.
+[classname]#Label# has undefined default width, so it will only take the space it needs.
+If the width of the label's text exceeds the available width for the label in the layout,
+the text overflows, and normally, gets truncated.
 
 
 [source, java]
@@ -70,30 +66,30 @@ panel.setWidth("300px");
 panel.setContent(
     new Label("This is a Label inside a Panel. There is " +
               "enough text in the label to make the text " +
-              "wrap when it exceeds the width of the panel."));
+              "get truncated when it exceeds the width of the panel."));
 ----
-See the http://demo.vaadin.com/book-examples-vaadin7/book#component.label.wrap[on-line example, window="_blank"].
 
 As the size of the [classname]#Panel# in the above example is fixed and the
-width of [classname]#Label# is the default 100%, the text in the
-[classname]#Label# will wrap to fit the panel, as shown in
+width of [classname]#Label# is the default undefined, the [classname]#Label#
+ will overflow the layout horizontally and be truncated.
 <<figure.components.label>>.
 
+////
+// TODO update figure to match new label settings in Vaadin Framwork 8
 [[figure.components.label]]
 .The Label Component
 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
-a layout with defined width, the [classname]#Label# will overflow the layout
-horizontally and, normally, be truncated.
+Setting [classname]#Label# to defined width will cause it to not overflow the layout,
+but to wrap to the next line. 
 
 
 [[components.label.content-mode]]
 == Content Mode
 
 The content of a label is formatted depending on a __content mode__. By default,
-the text is assumed to be plain text and any contained XML-specific characters
+the text is assumed to be plain text and any contained HTML-specific characters
 will be quoted appropriately to allow rendering the contents of a label in HTML
 in a web browser. The content mode can be set in the constructor or with
 [methodname]#setContentMode()#, and can have the values defined in the
@@ -102,7 +98,7 @@ in a web browser. The content mode can be set in the constructor or with
 
 TEXT:: The default content mode where the label contains only plain text. All
 characters are allowed, including the special [literal]#++<++#,
-[literal]#++>++#, and [literal]#++&++# characters in XML or HTML, which are
+[literal]#++>++#, and [literal]#++&++# characters in HTML, which are
 quoted properly in HTML while rendering the component. This is the default mode.
 
 PREFORMATTED:: Content mode where the label contains preformatted text. It will be, by default,
@@ -168,7 +164,6 @@ Label htmlLabel = new Label(
     "are preserved.",
     ContentMode.HTML);
 ----
-See the http://demo.vaadin.com/book-examples-vaadin7/book#component.label.content-modes.contentmodes[on-line example, window="_blank"].
 
 The rendering will look as shown in <<figure.components.label.content-mode>>.
 
-- 
cgit v1.2.3

