summaryrefslogtreecommitdiffstats
path: root/documentation/components/components-label.asciidoc
diff options
context:
space:
mode:
authorIlia Motornyi <elmot@vaadin.com>2015-12-03 14:59:05 +0000
committerVaadin Code Review <review@vaadin.com>2015-12-03 14:59:12 +0000
commit2af72ba9636bec70046394c41744f89ce4572e35 (patch)
treeccb3dc2d2239585f8c3f79eb5f131ff61ca9ce86 /documentation/components/components-label.asciidoc
parent8aa5fabe89f2967e966a64842a608eceaf80d08f (diff)
downloadvaadin-framework-2af72ba9636bec70046394c41744f89ce4572e35.tar.gz
vaadin-framework-2af72ba9636bec70046394c41744f89ce4572e35.zip
Revert "Merge branch 'documentation'"7.6.0.beta2
This reverts commit f6874bde3d945c8b2d1b5c17ab50e2d0f1f8ff00. Change-Id: I67ee1c30ba3e3bcc3c43a1dd2e73a822791514bf
Diffstat (limited to 'documentation/components/components-label.asciidoc')
-rw-r--r--documentation/components/components-label.asciidoc306
1 files changed, 0 insertions, 306 deletions
diff --git a/documentation/components/components-label.asciidoc b/documentation/components/components-label.asciidoc
deleted file mode 100644
index 9de3fc47da..0000000000
--- a/documentation/components/components-label.asciidoc
+++ /dev/null
@@ -1,306 +0,0 @@
----
-title: Label
-order: 7
-layout: page
----
-
-[[components.label]]
-= [classname]#Label#
-
-[classname]#Label# component displays non-editable text. This text can be used
-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.
-
-
-[source, java]
-----
-// A container that is 100% wide by default
-VerticalLayout layout = new VerticalLayout();
-
-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"].
-
-[classname]#Label# implements the [interfacename]#Property# interface to allow
-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()));
-editor.setImmediate(true); // Send on Enter
-----
-See the http://demo.vaadin.com/book-examples-vaadin7/book#component.label.basic[on-line example, window="_blank"].
-
-Label also supports data binding to a property data source, as described later
-in <<components.label.databinding>>. However, in that case the value can not be
-set through the label, as [classname]#Label# is not a
-[interfacename]#Property.Editor# and is not allowed to write to a bound
-property.
-
-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
-[methodname]#setCaption()#. As with most other components, the caption is
-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.
-
-
-[source, java]
-----
-// A container with a defined width.
-Panel panel = new Panel("Panel Containing a Label");
-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."));
-----
-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
-<<figure.components.label>>.
-
-[[figure.components.label]]
-.The Label Component
-image::img/label-example1.png[]
-
-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.
-
-
-[[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
-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
-[classname]#ContentMode# enumeration type in
-[package]#com.vaadin.shared.ui.label# package:
-
-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
-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,
-rendered with a fixed-width typewriter font. Preformatted text can contain line
-breaks, written in Java with the [literal]#++\n++# escape sequence for a newline
-character (ASCII 0x0a), or tabulator characters written with [literal]#++\t++#
-(ASCII 0x09).
-
-HTML:: Content mode where the label contains HTML.
-
-+
-Please note the following security and validity warnings regarding the HTML
-content mode.
-
-
-
-
-[WARNING]
-.Cross-Site Scripting Warning
-====
-Having [classname]#Label# in HTML content mode allows pure HTML content. If the
-content comes from user input, you should always carefully sanitize it to
-prevent cross-site scripting (XSS) attacks. Please see
-<<dummy/../../../framework/advanced/advanced-security#advanced.security.sanitizing,"Sanitizing
-User Input to Prevent Cross-Site Scripting">>.
-
-Also, the validity of the HTML content is not checked when rendering the
-component and any errors can result in an error in the browser. If the content
-comes from an uncertain source, you should always validate it before displaying
-it in the component.
-
-====
-
-
-
-The following example demonstrates the use of [classname]#Label# in different
-modes.
-
-
-[source, java]
-----
-Label textLabel = new Label(
- "Text where formatting characters, such as \\n, " +
- "and HTML, such as <b>here</b>, are quoted.",
- ContentMode.TEXT);
-
-Label preLabel = new Label(
- "Preformatted text is shown in an HTML <pre> tag.\n" +
- "Formatting such as\n" +
- " * newlines\n" +
- " * whitespace\n" +
- "and such are preserved. HTML tags, \n"+
- "such as <b>bold</b>, are quoted.",
- ContentMode.PREFORMATTED);
-
-Label htmlLabel = new Label(
- "In HTML mode, all HTML formatting tags, such as \n" +
- "<ul>"+
- " <li><b>bold</b></li>"+
- " <li>itemized lists</li>"+
- " <li>etc.</li>"+
- "</ul> "+
- "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>>.
-
-[[figure.components.label.content-mode]]
-.Label Content Modes
-image::img/label-modes.png[]
-
-
-ifdef::web[]
-[[components.label.spacing]]
-== Spacing with a [classname]#Label#
-
-You can use a [classname]#Label# to create vertical or horizontal space in a
-layout. If you need a empty "line" in a vertical layout, having just a label
-with empty text is not enough, as it will collapse to zero height. The same goes
-for a label with only whitespace as the label text. You need to use a
-non-breaking space character, either [literal]#++&nbsp;++# or
-[literal]#++&#160;++#:
-
-
-[source, java]
-----
-layout.addComponent(new Label("&nbsp;", ContentMode.HTML));
-----
-
-Using the [parameter]#ContentMode.PREFORMATTED# mode has the same effect;
-preformatted spaces do not collapse in a vertical layout. In a
-[classname]#HorizontalLayout#, the width of a space character may be
-unpredictable if the label font is proportional, so you can use the preformatted
-mode to add em-width wide spaces.
-
-If you want a gap that has adjustable width or height, you can use an empty
-label if you specify a height or width for it. For example, to create vertical
-space in a [classname]#VerticalLayout#:
-
-
-[source, java]
-----
-Label gap = new Label();
-gap.setHeight("1em");
-verticalLayout.addComponent(gap);
-----
-
-You can make a flexible expanding spacer by having a relatively sized empty
-label with [literal]#++100%++# height or width and setting the label as
-expanding in the layout.
-
-
-[source, java]
-----
-// A wide component bar
-HorizontalLayout horizontal = new HorizontalLayout();
-horizontal.setWidth("100%");
-
-// Have a component before the gap (a collapsing cell)
-Button button1 = new Button("I'm on the left");
-horizontal.addComponent(button1);
-
-// An expanding gap spacer
-Label expandingGap = new Label();
-expandingGap.setWidth("100%");
-horizontal.addComponent(expandingGap);
-horizontal.setExpandRatio(expandingGap, 1.0f);
-
-// A component after the gap (a collapsing cell)
-Button button2 = new Button("I'm on the right");
-horizontal.addComponent(button2);
-----
-
-endif::web[]
-
-[[components.label.databinding]]
-== Data Binding
-
-While [classname]#Label# is not a field component, it is a
-[interfacename]#Property.Viewer# and can be bound to a property data source,
-described in
-<<dummy/../../../framework/datamodel/datamodel-properties#datamodel.properties,"Properties">>.
-You can specify the data source either in the constructor or by the
-[methodname]#setPropertyDataSource()# method.
-
-
-[source, java]
-----
-// Some property
-ObjectProperty<String> property =
- new ObjectProperty<String>("some value");
-
-// Label that is bound to the property
-Label label = new Label(property);
-----
-See the http://demo.vaadin.com/book-examples-vaadin7/book#component.label.binding[on-line example, window="_blank"].
-
-Further, as [classname]#Label# is a [interfacename]#Property#, you can edit its
-value with a property editor, such as a field:
-
-
-[source, java]
-----
-Label label = new Label("some value");
-TextField editor = new TextField();
-editor.setPropertyDataSource(label);
-editor.setImmediate(true);
-----
-See the http://demo.vaadin.com/book-examples-vaadin7/book#component.label.delegation[on-line example, window="_blank"].
-
-However, [classname]#Label# is __not__ a [interfacename]#Property.Editor#, so it
-is read-only when bound to a data source. Therefore, you can not use
-[methodname]#setValue()# to set the value of a connected data source through a
-[classname]#Label# nor bind the label to an editor field, in which case writes
-would be delegated through the label.
-
-
-[[components.label.css]]
-== CSS Style Rules
-
-
-[source, css]
-----
-.v-label { }
- pre { } /* In PREFORMATTED content mode */
-----
-
-The [classname]#Label# component has a [literal]#++v-label++# overall style. In
-the [parameter]#PREFORMATTED# content mode, the text is wrapped inside a
-[literal]#++<pre>++# element.
-
-
-
-