diff options
Diffstat (limited to 'documentation/components/components-features.asciidoc')
| -rw-r--r-- | documentation/components/components-features.asciidoc | 757 |
1 files changed, 0 insertions, 757 deletions
diff --git a/documentation/components/components-features.asciidoc b/documentation/components/components-features.asciidoc deleted file mode 100644 index 9374b93bc1..0000000000 --- a/documentation/components/components-features.asciidoc +++ /dev/null @@ -1,757 +0,0 @@ ---- -title: Common Component Features -order: 3 -layout: page ---- - -[[components.features]] -= Common Component Features - -The component base classes and interfaces provide a large number of features. -Let us look at some of the most commonly needed features. Features not -documented here can be found from the Java API Reference. - -The interface defines a number of properties, which you can retrieve or -manipulate with the corresponding setters and getters. - -[[components.features.caption]] -== Caption - -((("caption property"))) -((("Component interface", "caption"))) -A caption is an explanatory textual label accompanying a user interface -component, usually shown above, left of, or inside the component. The contents -of a caption are automatically quoted, so no raw HTML can be rendered in a -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" -TextField name = new TextField("Name"); -layout.addComponent(name); ----- - -The caption of a component is, by default, managed and displayed by the layout -component or component container inside which the component is placed. For -example, the [classname]#VerticalLayout# component shows the captions -left-aligned above the contained components, while the [classname]#FormLayout# -component shows the captions on the left side of the vertically laid components, -with the captions and their associated components left-aligned in their own -columns. The [classname]#CustomComponent# does not manage the caption of its -composition root, so if the root component has a caption, it will not be -rendered. - -[[figure.components.features.caption.layoutmanaged]] -.Caption Management by [classname]#VerticalLayout# and [classname]#FormLayout#. -image::img/features-caption-layoutmanaged.png[] - -Some components, such as [classname]#Button# and [classname]#Panel#, manage the -caption themselves and display it inside the component. - -Icon (see <<components.features.icon>>) is closely related to caption and is -usually displayed horizontally before or after it, depending on the component -and the containing layout. Also the required indicator in field components is -usually shown before or after the caption. - -An alternative way to implement a caption is to use another component as the -caption, typically a [classname]#Label#, a [classname]#TextField#, or a -[classname]#Panel#. A [classname]#Label#, for example, allows highlighting a -shortcut key with HTML markup or to bind the caption to a data source. The -[classname]#Panel# provides an easy way to add both a caption and a border -around a component. - -=== CSS Style Rules - - -[source, css] ----- -.v-caption {} - .v-captiontext {} - .v-caption-clearelem {} - .v-required-field-indicator {} ----- - -A caption is be rendered inside an HTML element that has the -[literal]#++v-caption++# CSS style class. The containing layout may enclose a -caption inside other caption-related elements. - -Some layouts put the caption text in a [literal]#++v-captiontext++# element. A -[literal]#++v-caption-clearelem++# is used in some layouts to clear a CSS -[literal]#++float++# property in captions. An optional required indicator in -field components is contained in a separate element with -[literal]#++v-required-field-indicator++# style. - - - -[[components.features.description]] -== Description and Tooltips - -((("description property"))) -((("Component interface", "description"))) -((("tooltips"))) -All components (that inherit [classname]#AbstractComponent#) have a description -separate from their caption. The description is usually shown as a tooltip that -appears when the mouse pointer hovers over the component for a short time. - -You can set the description with [methodname]#setDescription()# and retrieve -with [methodname]#getDescription()#. - - -[source, java] ----- -Button button = new Button("A Button"); -button.setDescription("This is the tooltip"); ----- - -The tooltip is shown in <<figure.components.tooltip.plain>>. - -[[figure.components.tooltip.plain]] -.Component Description as a Tooltip -image::img/tooltip-plain-withpointer-hi.png[] - -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 -<<dummy/../../../framework/application/application-errors#application.errors.error-indicator,"Error -Indicator and Message">>. - -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 -images. - - -[source, java] ----- -button.setDescription( - "<h2><img src=\"../VAADIN/themes/sampler/icons/comment_yellow.gif\"/>"+ - "A richtext tooltip</h2>"+ - "<ul>"+ - " <li>Use rich formatting with HTML</li>"+ - " <li>Include images from themes</li>"+ - " <li>etc.</li>"+ - "</ul>"); ----- -See the http://demo.vaadin.com/book-examples-vaadin7/book#component.features.description.richtext[on-line example, window="_blank"]. - -The result is shown in <<figure.components.tooltip.richtext>>. - -[[figure.components.tooltip.richtext]] -.A Rich Text Tooltip -image::img/tooltip-richtext-withpointer-hi.png[] - -Notice that the setter and getter are defined for all fields in the -[classname]#Field# interface, not for all components in the -[classname]#Component# interface. - - -[[components.features.enabled]] -== Enabled - -((("enabled property"))) -((("Component interface", "enabled"))) -The __enabled__ property controls whether the user can actually use the -component. A disabled component is visible, but grayed to indicate the disabled -state. - -Components are always enabled by default. You can disable a component with -[methodname]#setEnabled(false)#. - - -[source, java] ----- -Button enabled = new Button("Enabled"); -enabled.setEnabled(true); // The default -layout.addComponent(enabled); - -Button disabled = new Button("Disabled"); -disabled.setEnabled(false); -layout.addComponent(disabled); ----- - -<<figure.components.features.enabled.simple>> shows the enabled and disabled -buttons. - -[[figure.components.features.enabled.simple]] -.An Enabled and Disabled [classname]#Button# -image::img/features-enabled-simple.png[] - -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 -security feature, the server-side components do not receive state updates from -the client in the read-only state. This feature exists in all built-in -components in Vaadin and is automatically handled for all [classname]#Field# -components for the field property value. For custom widgets, you need to make -sure that the read-only state is checked on the server-side for all -safety-critical variables. - -=== CSS Style Rules - -Disabled components have the [literal]#++v-disabled++# CSS style in addition to -the component-specific style. To match a component with both the styles, you -have to join the style class names with a dot as done in the example below. - - -[source, css] ----- -.v-textfield.v-disabled { - border: dotted; -} ----- - -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 -<<dummy/../../../framework/themes/themes-valo#themes.valo.variables,"Common -Settings">> -endif::web[] -. - - -[[components.features.icon]] -== Icon - -((("icon property"))) -((("Component interface", "icon"))) -An icon is an explanatory graphical label accompanying a user interface -component, usually shown above, left of, or inside the component. Icon is -closely related to caption (see <<components.features.caption>>) and is usually -displayed horizontally before or after it, depending on the component and the -containing layout. - -The icon of a component can be set with the [methodname]#setIcon()# method. The -image is provided as a resource, perhaps most typically a -[classname]#ThemeResource#. - - -[source, java] ----- -// Component with an icon from a custom theme -TextField name = new TextField("Name"); -name.setIcon(new ThemeResource("icons/user.png")); -layout.addComponent(name); - -// Component with an icon from another theme ('runo') -Button ok = new Button("OK"); -ok.setIcon(new ThemeResource("../runo/icons/16/ok.png")); -layout.addComponent(ok); ----- - -The icon of a component is, by default, managed and displayed by the layout -component or component container in which the component is placed. For example, -the [classname]#VerticalLayout# component shows the icons left-aligned above the -contained components, while the [classname]#FormLayout# component shows the -icons on the left side of the vertically laid components, with the icons and -their associated components left-aligned in their own columns. The -[classname]#CustomComponent# does not manage the icon of its composition root, -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[] - -Some components, such as [classname]#Button# and [classname]#Panel#, manage the -icon themselves and display it inside the component. - -In addition to image resources, you can use __font icons__, which are icons -included in special fonts, but which are handled as special resources. See -<<dummy/../../../framework/themes/themes-fonticon#themes.fonticon,"Font Icons">> -for more details. - -=== CSS Style Rules - -An icon will be rendered inside an HTML element that has the -[literal]#++v-icon++# CSS style class. The containing layout may enclose an icon -and a caption inside elements related to the caption, such as -[literal]#++v-caption++#. - - - -[[components.features.locale]] -== Locale - -((("locale property", "in [classname]#Component#"))) -((("Component interface", "locale"))) -The locale property defines the country and language used in a component. You -can use the locale information in conjunction with an internationalization -scheme to acquire localized resources. Some components, such as -[classname]#DateField#, use the locale for component localization. - -You can set the locale of a component (or the application) with -[methodname]#setLocale()# as follows: - - -[source, java] ----- -// Component for which the locale is meaningful -InlineDateField date = new InlineDateField("Datum"); - -// German language specified with ISO 639-1 language -// code and ISO 3166-1 alpha-2 country code. -date.setLocale(new Locale("de", "DE")); - -date.setResolution(Resolution.DAY); -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 -<<figure.components.features.locale.simple>>. - -[[figure.components.features.locale.simple]] -.Set Locale for [classname]#InlineDateField# -image::img/features-locale-simple.png[] - -ifdef::web[] -[[components.features.locale.get]] -=== Getting the Locale - -((("[methodname]#getLocale()#"))) -You can get the locale of a component with [methodname]#getLocale()#. If the -locale is undefined for a component, that is, not explicitly set, the locale of -the parent component is used. If none of the parent components have a locale -set, the locale of the UI is used, and if that is not set, the default system -locale is set, as given by [methodname]#Locale.getDefault()#. - -The [methodname]#getLocale()# returns null if the component is not yet attached -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() { - @Override - public void attach() { - super.attach(); - ResourceBundle bundle = ResourceBundle.getBundle( - MyAppCaptions.class.getName(), getLocale()); - setCaption(bundle.getString(MyAppCaptions.CancelKey)); - } -}; -layout.addComponent(cancel); ----- -See the http://demo.vaadin.com/book-examples-vaadin7/book#component.features.locale.get-attach[on-line example, window="_blank"]. - -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 -// and the UI object is known in this context. -ResourceBundle bundle = - ResourceBundle.getBundle(MyAppCaptions.class.getName(), - UI.getCurrent().getLocale()); - -// Get a localized resource from the bundle -Button cancel = - new Button(bundle.getString(MyAppCaptions.CancelKey)); -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[] -[[component.features.locale.selecting]] -=== Selecting a Locale - -A common task in many applications is selecting a locale. This is done in the -following example with a [classname]#ComboBox#, which gets the available locales -in Java. - - -[source, java] ----- -// The locale in which we want to have the language -// selection list -Locale displayLocale = Locale.ENGLISH; - -// All known locales -final Locale[] locales = Locale.getAvailableLocales(); - -// Allow selecting a language. We are in a constructor of a -// CustomComponent, so preselecting the current -// language of the application can not be done before -// this (and the selection) component are attached to -// the application. -final ComboBox select = new ComboBox("Select a language") { - @Override - public void attach() { - super.attach(); - setValue(getLocale()); - } -}; -for (int i=0; i<locales.length; i++) { - select.addItem(locales[i]); - select.setItemCaption(locales[i], - locales[i].getDisplayName(displayLocale)); - - // Automatically select the current locale - if (locales[i].equals(getLocale())) - select.setValue(locales[i]); -} -layout.addComponent(select); - -// Locale code of the selected locale -final Label localeCode = new Label(""); -layout.addComponent(localeCode); - -// A date field which language the selection will change -final InlineDateField date = - new InlineDateField("Calendar in the selected language"); -date.setResolution(Resolution.DAY); -layout.addComponent(date); - -// Handle language selection -select.addValueChangeListener(new Property.ValueChangeListener() { - public void valueChange(ValueChangeEvent event) { - Locale locale = (Locale) select.getValue(); - date.setLocale(locale); - localeCode.setValue("Locale code: " + - locale.getLanguage() + "_" + - locale.getCountry()); - } -}); -select.setImmediate(true); ----- -See the http://demo.vaadin.com/book-examples-vaadin7/book#component.features.locale.selection[on-line example, window="_blank"]. - -The user interface is shown in <<figure.components.features.locale.selection>>. - -[[figure.components.features.locale.selection]] -.Selecting a Locale -image::img/features-locale-selection.png[] - -endif::web[] - - -[[components.features.readonly]] -== Read-Only - -((("read-only property"))) -((("Component interface", "read-only"))) -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"); -readwrite.setValue("You can change this"); -readwrite.setReadOnly(false); // The default -layout.addComponent(readwrite); - -TextField readonly = new TextField("Read-Only"); -readonly.setValue("You can't touch this!"); -readonly.setReadOnly(true); -layout.addComponent(readonly); ----- - -The resulting read-only text field is shown in -<<figure.components.features.readonly.simple>>. - -[[figure.components.features.readonly.simple]] -.A Read-Only Component. -image::img/features-readonly-simple.png[] - -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 -example, the disabled state, which is usually applied recursively. - -Notice that the value of a selection component is the selection, not its items. -A read-only selection component doesn't therefore allow its selection to be -changed, but other changes are possible. For example, if you have a read-only -[classname]#Table# in editable mode, its contained fields and the underlying -data model can still be edited, and the user could sort it or reorder the -columns. - -Client-side state modifications will not be communicated to the server-side and, -more importantly, server-side field components will not accept changes to the -value of a read-only [classname]#Field# component. The latter is an important -security feature, because a malicious user can not fabricate state changes in a -read-only field. This is handled at the level of [classname]#AbstractField# in -[methodname]#setValue()#, so you can not change the value programmatically -either. Calling [methodname]#setValue()# on a read-only field results in -[classname]#Property.ReadOnlyException#. - -Also notice that while the read-only status applies automatically to the -property value of a field, it does not apply to other component variables. A -read-only component can accept some other variable changes from the client-side -and some of such changes could be acceptable, such as change in the scroll bar -position of a [classname]#Table#. Custom widgets should check the read-only -state for variables bound to business -data.//// -TODO: Note this also in the Advanced: Security section and possibly also in the -GWT -chapter. -//// - -=== CSS Style Rules - -Setting a normally editable component to read-only state can change its -appearance to disallow editing the value. In addition to CSS styling, also the -HTML structure can change. For example, [classname]#TextField# loses the edit -box and appears much like a [classname]#Label#. - -A read-only component will have the [literal]#++v-readonly++# style. The -following CSS rule would make the text in all read-only [classname]#TextField# -components appear in italic. - - -[source, css] ----- -.v-textfield.v-readonly { - font-style: italic; -} ----- - - - -[[components.features.stylename]] -== Style Name - -((("style name property"))) -((("Component interface", "style name"))) -The __style name__ property defines one or more custom CSS style class names for -the component. The [methodname]#getStyleName()# returns the current style names -as a space-separated list. The [methodname]#setStyleName()# replaces all the -styles with the given style name or a space-separated list of style names. You -can also add and remove individual style names with [methodname]#addStylename()# -and [methodname]#removeStyleName()#. A style name must be a valid CSS style -name. - - -[source, java] ----- -Label label = new Label("This text has a lot of style"); -label.addStyleName("mystyle"); -layout.addComponent(label); ----- - -The style name will appear in the component's HTML element in two forms: -literally as given and prefixed with the component-specific style name. For -example, if you add a style name [literal]#++mystyle++# to a -[classname]#Button#, the component would get both [literal]#++mystyle++# and -[literal]#++v-button-mystyle++# styles. Neither form may conflict with built-in -style names of Vaadin. For example, [literal]#++focus++# style would conflict -with a built-in style of the same name, and an [literal]#++content++# style for -a [classname]#Panel# component would conflict with the built-in -[literal]#++v-panel-content++# style. - -The following CSS rule would apply the style to any component that has the -[literal]#++mystyle++# style. - - -[source, css] ----- -.mystyle { - font-family: fantasy; - font-style: italic; - font-size: 25px; - font-weight: bolder; - line-height: 30px; -} ----- - -The resulting styled component is shown in -<<figure.components.features.stylename>> - -[[figure.components.features.stylename]] -.Component with a Custom Style -image::img/features-stylename-simple.png[] - - -[[components.features.visible]] -== Visible - -((("visible property"))) -((("Component interface", "visible"))) -Components can be hidden by setting the __visible__ property to __false__. Also -the caption, icon and any other component features are made hidden. Hidden -components are not just invisible, but their content is not communicated to the -browser at all. That is, they are not made invisible cosmetically with only CSS -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"); -invisible.setValue("You can't see this!"); -invisible.setVisible(false); -layout.addComponent(invisible); ----- - -The resulting invisible component is shown in -<<figure.components.features.visible.simple>>. - -[[figure.components.features.visible.simple]] -.An Invisible Component. -image::img/features-visible-simple.png[] - -Beware that invisible beings can leave footprints. The containing layout cell -that holds the invisible component will not go away, but will show in the layout -as extra empty space. Also expand ratios work just like if the component was -visible - it is the layout cell that expands, not the component. - -If you need to make a component only cosmetically invisible, you should use a -custom theme to set it [literal]#++display: none++# style. This is mainly useful -for some special components that have effects even when made invisible in CSS. -If the hidden component has undefined size and is enclosed in a layout that also -has undefined size, the containing layout will collapse when the component -disappears. If you want to have the component keep its size, you have to make it -invisible by setting all its font and other attributes to be transparent. In -such cases, the invisible content of the component can be made visible easily in -the browser. - -A component made invisible with the __visible__ property has no particular CSS -style class to indicate that it is hidden. The element does exist though, but -has [literal]#++display: none++# style, which overrides any CSS styling. - - -[[components.features.sizeable]] -== Sizing Components - -((("[classname]#Sizeable# interface"))) -Vaadin components are sizeable; not in the sense that they were fairly large or -that the number of the components and their features are sizeable, but in the -sense that you can make them fairly large on the screen if you like, or small or -whatever size. - -The [classname]#Sizeable# interface, shared by all components, provides a number -of manipulation methods and constants for setting the height and width of a -component in absolute or relative units, or for leaving the size undefined. - -The size of a component can be set with [methodname]#setWidth()# and -[methodname]#setHeight()# methods. The methods take the size as a floating-point -value. You need to give the unit of the measure as the second parameter for the -above methods. The available units are listed in -<<components.features.sizeable.units.table>> below. - - -[source, java] ----- -mycomponent.setWidth(100, Sizeable.UNITS_PERCENTAGE); -mycomponent.setWidth(400, Sizeable.UNITS_PIXELS); ----- - -Alternatively, you can speficy the size as a string. The format of such a string -must follow the HTML/CSS standards for specifying measures. - - -[source, java] ----- -mycomponent.setWidth("100%"); -mycomponent.setHeight("400px"); ----- - -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 -directions. - -The size can be __undefined__ in either or both dimensions, which means that the -component will take the minimum necessary space. Most components have undefined -size by default, but some layouts have full size in horizontal direction. You -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 -<<dummy/../../../framework/layout/layout-settings#layout.settings.size,"Layout -Size">> for details. - -The <<components.features.sizeable.units.table>> lists the available units and -their codes defined in the [classname]#Sizeable# interface. - -[[components.features.sizeable.units.table]] -.Size Units - -|=============== -|[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. - -|=============== - - - -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 -<<dummy/../../../framework/layout/layout-settings#layout.settings.size,"Layout -Size">> for details. - - -== Managing Input Focus - -When the user clicks on a component, the component gets the __input focus__, -which is indicated by highlighting according to style definitions. If the -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#. - -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 -[methodname]#getTabIndex()#. The tab index is managed in the context of the page -in which the components are contained. The focus order can therefore jump -between two any lower-level component containers, such as sub-windows or panels. - -The default focus order is determined by the natural hierarchical order of -components in the order in which they were added under their parents. The -default tab index is 0 (zero). - -Giving a negative integer as the tab index removes the component from the focus -order entirely. - -=== CSS Style Rules - -The component having the focus will have an additional style class with the -[literal]#++-focus++# suffix. For example, a [classname]#TextField#, which -normally has the [literal]#++v-textfield++# style, would additionally have the -[literal]#++v-textfield-focus++# style. - -For example, the following would make a text field blue when it has focus. - - -[source, css] ----- -.v-textfield-focus { - background: lightblue; -} ----- - - - - - |