123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590 |
- ---
- 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[width=50%,scaledwidth=65%]
-
- 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-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.
- 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[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
- <<../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>");
- ----
-
- The result is shown in <<figure.components.tooltip.richtext>>.
-
- [[figure.components.tooltip.richtext]]
- .A Rich Text Tooltip
- image::img/tooltip-richtext-withpointer-hi.png[width=40%, scaledwidth=75%]
-
-
- [[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[width=30%, scaledwidth=50%]
-
- A disabled component is automatically put in read-only like state. No client
- interaction with a disabled 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 disabled state. This feature exists in all built-in
- components in the Framework meaning all client to server RPC calls are ignored
- for disabled components.
-
- === 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.
-
- In the Valo theme, the opacity of disabled components is specified with the
- `$v-disabled-opacity` parameter.
-
- [[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[width=40%, scaledwidth=60%]
-
- 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
- <<../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);
- ----
-
- 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[width=40%, scaledwidth=60%]
-
-
- [[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);
- ----
-
- 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);
- ----
-
-
- [[component.features.locale.selecting]]
- === Selecting a Locale
-
- A common task in many applications is selecting a locale.
- The locale can be set for the [classname]#UI# or single [classname]#Component#.
- By default each component uses the locale from the [classname]#UI# it has been
- attached to. Setting a locale to a [classname]#Component# only applies the locale
- to that component and its children. Note, that updating the locale for a component
- does not update its children, thus any child component that uses the locale should be updated manually.
-
-
- [[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 only applicable to components implementing the [interfacename]#HasValue# interface.
-
- [source, java]
- ----
- TextField readwrite = new TextField("Read-Write");
- readwrite.setValue("You can change this");
- readwrite.setReadOnly(false); // The default
-
- TextField readonly = new TextField("Read-Only");
- readonly.setValue("You can't touch this!");
- readonly.setReadOnly(true);
- ----
-
- 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[width=50%, scaledwidth=80%]
-
- 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
- [classname]#Grid# with a read-only selection model 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]#HasValue# component. The latter is an important
- security feature, because a malicious user can not fabricate state changes in a
- read-only field.
-
- Also notice that while the read-only status applies automatically to the value
- of a field, it does not apply to other component variables. A
- read-only component can accept some other state changes from the client-side
- and some of such changes could be acceptable, such as change in the scroll bar
- position of a [classname]#ListSelect#. Custom components should check the read-only
- state for variables bound to business data.
-
-
- === 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[width=50%, scaledwidth=75%]
-
- [[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);
- ----
-
- 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.
-
-
- [[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.
-
- [source, java]
- ----
- mycomponent.setWidth(100, Unit.PERCENTAGE);
- mycomponent.setWidth(400, Unit.PIXELS);
- ----
-
- Alternatively, you can specify 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. 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, width, or both as undefined with the methods [methodname]#setWidthUndefined()#,
- [methodname]#setHeightUndefined()#, and [methodname]#setSizeUndefined()#, respectively.
-
- 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 <<../layout/layout-settings#layout.settings.size,"Layout Size">> 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 <<../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]#AbstractField# and [classname]#AbstractListing# components and also by
- components such as [classname]#Button#, [classname]#Upload#, and [classname]#TabSheet#.
-
- 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;
- }
- ----
|