|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface Component
Component
is the top-level interface that is and must be implemented
by all Vaadin components. Component
is paired with
AbstractComponent
, which provides a default implementation for all
the methods defined in this interface.
Components are laid out in the user interface hierarchically. The layout is
managed by layout components, or more generally by components that implement
the ComponentContainer
interface. Such a container is the
parent of the contained components.
The getParent()
method allows retrieving the parent component of a
component. While there is a setParent()
, you
rarely need it as you normally add components with the
addComponent()
method of
the layout or other ComponentContainer
, which automatically sets the
parent.
A component becomes attached to an application (and the
attach()
is called) when it or one of its parents is attached to the
main window of the application through its containment hierarchy.
Nested Class Summary | |
---|---|
static class |
Component.ErrorEvent
Class of all component originated error events. |
static interface |
Component.ErrorListener
Listener interface for receiving Component.Errors s. |
static class |
Component.Event
Superclass of all component originated events. |
static interface |
Component.Focusable
A sub-interface implemented by components that can obtain input focus. |
static interface |
Component.Listener
Listener interface for receiving Component.Event s. |
Nested classes/interfaces inherited from interface com.vaadin.terminal.Paintable |
---|
Paintable.RepaintRequestEvent, Paintable.RepaintRequestListener |
Field Summary |
---|
Fields inherited from interface com.vaadin.terminal.Sizeable |
---|
SIZE_UNDEFINED, UNIT_SYMBOLS, UNITS_CM, UNITS_EM, UNITS_EX, UNITS_INCH, UNITS_MM, UNITS_PERCENTAGE, UNITS_PICAS, UNITS_PIXELS, UNITS_POINTS |
Method Summary | |
---|---|
void |
addListener(Component.Listener listener)
Registers a new (generic) component event listener for the component. |
void |
addStyleName(String style)
Adds a style name to component. |
void |
attach()
Notifies the component that it is connected to an application. |
void |
childRequestedRepaint(Collection<Paintable.RepaintRequestListener> alreadyNotified)
The child components of the component must call this method when they need repainting. |
void |
detach()
Notifies the component that it is detached from the application. |
Application |
getApplication()
Gets the application object to which the component is attached. |
String |
getCaption()
Gets the caption of the component. |
Resource |
getIcon()
Gets the icon resource of the component. |
Locale |
getLocale()
Gets the locale of the component. |
Component |
getParent()
Gets the parent component of the component. |
String |
getStyleName()
Gets all user-defined CSS style names of a component. |
Window |
getWindow()
Gets the parent window of the component. |
boolean |
isEnabled()
Tests whether the component is enabled or not. |
boolean |
isReadOnly()
Tests whether the component is in the read-only mode. |
boolean |
isVisible()
Tests the visibility property of the component. |
void |
removeListener(Component.Listener listener)
Removes a previously registered component event listener from this component. |
void |
removeStyleName(String style)
Removes one or more style names from component. |
void |
setCaption(String caption)
Sets the caption of the component. |
void |
setEnabled(boolean enabled)
Enables or disables the component. |
void |
setIcon(Resource icon)
Sets the icon of the component. |
void |
setParent(Component parent)
Sets the parent component of the component. |
void |
setReadOnly(boolean readOnly)
Sets the read-only mode of the component to the specified mode. |
void |
setStyleName(String style)
Sets one or more user-defined style names of the component, replacing any previous user-defined styles. |
void |
setVisible(boolean visible)
Sets the visibility of the component. |
Methods inherited from interface com.vaadin.terminal.Paintable |
---|
addListener, getDebugId, paint, removeListener, requestRepaint, requestRepaintRequests, setDebugId |
Methods inherited from interface com.vaadin.terminal.VariableOwner |
---|
changeVariables, isImmediate |
Methods inherited from interface com.vaadin.terminal.Sizeable |
---|
getHeight, getHeightUnits, getWidth, getWidthUnits, setHeight, setHeight, setHeight, setHeightUnits, setSizeFull, setSizeUndefined, setWidth, setWidth, setWidth, setWidthUnits |
Method Detail |
---|
String getStyleName()
The style names are returned only in the basic form in which they were added; each user-defined style name shows as two CSS style class names in the rendered HTML: one as it was given and one prefixed with the component-specific style name. Only the former is returned.
setStyleName(String)
,
addStyleName(String)
,
removeStyleName(String)
void setStyleName(String style)
Label label = new Label("This text has a lot of style"); label.setStyleName("myonestyle myotherstyle");
Each style name will occur in two versions: one as specified and one that
is prefixed with the style name of the component. For example, if you
have a Button
component and give it "mystyle
" style, the
component will have both "mystyle
" and "v-button-mystyle
"
styles. You could then style the component either with:
.myonestyle {background: blue;}
or
.v-button-myonestyle {background: blue;}
It is normally a good practice to use addStyleName()
rather than this setter, as different software
abstraction layers can then add their own styles without accidentally
removing those defined in other layers.
This method will trigger a
RepaintRequestEvent
.
style
- the new style or styles of the component as a space-separated
listgetStyleName()
,
addStyleName(String)
,
removeStyleName(String)
void addStyleName(String style)
Label label = new Label("This text has style"); label.addStyleName("mystyle");
Each style name will occur in two versions: one as specified and one that
is prefixed wil the style name of the component. For example, if you have
a Button
component and give it "mystyle
" style, the
component will have both "mystyle
" and "v-button-mystyle
"
styles. You could then style the component either with:
.mystyle {font-style: italic;}
or
.v-button-mystyle {font-style: italic;}
This method will trigger a
RepaintRequestEvent
.
style
- the new style to be added to the componentgetStyleName()
,
setStyleName(String)
,
removeStyleName(String)
void removeStyleName(String style)
The parameter must be a valid CSS style name. Only user-defined style
names added with addStyleName()
or
setStyleName()
can be removed; built-in
style names defined in Vaadin or GWT can not be removed.
RepaintRequestEvent
.
style
- the style name or style names to be removedgetStyleName()
,
setStyleName(String)
,
addStyleName(String)
boolean isEnabled()
As a security feature, all variable change events for disabled components are blocked on the server-side.
isEnabled
in interface VariableOwner
true
if the component and its parent are enabled,
false
otherwise.VariableOwner.isEnabled()
void setEnabled(boolean enabled)
Button enabled = new Button("Enabled"); enabled.setEnabled(true); // The default layout.addComponent(enabled); Button disabled = new Button("Disabled"); disabled.setEnabled(false); layout.addComponent(disabled);
This method will trigger a
RepaintRequestEvent
for the component and, if it is a
ComponentContainer
, for all its children recursively.
enabled
- a boolean value specifying if the component should be enabled
or notboolean isVisible()
Visible components are drawn in the user interface, while invisible ones are not. The effect is not merely a cosmetic CSS change, but the entire HTML element will be empty. Making a component invisible through this property can alter the positioning of other components.
A component is visible only if all its parents are also visible. Notice that if a child component is explicitly set as invisible, changes in the visibility status of its parents do not change its status.
This method does not check whether the component is attached (see
attach()
). The component and all its parents may be considered
"visible", but not necessarily attached to application. To test if
component will actually be drawn, check both its visibility and that
getApplication()
does not return null
.
true
if the component is visible in the user
interface, false
if notsetVisible(boolean)
,
attach()
void setVisible(boolean visible)
Visible components are drawn in the user interface, while invisible ones are not. The effect is not merely a cosmetic CSS change, but the entire HTML element will be empty.
TextField readonly = new TextField("Read-Only"); readonly.setValue("You can't see this!"); readonly.setVisible(false); layout.addComponent(readonly);
A component is visible only if all of its parents are also visible. If a component is explicitly set to be invisible, changes in the visibility of its parents will not change the visibility of the component.
visible
- the boolean value specifying if the component should be
visible after the call or not.isVisible()
Component getParent()
Components can be nested but a component can have only one parent. A
component that contains other components, that is, can be a parent,
should usually inherit the ComponentContainer
interface.
setParent(Component)
void setParent(Component parent)
This method automatically calls attach()
if the parent becomes
attached to the application, regardless of whether it was attached
previously. Conversely, if the parent is null
and the component
is attached to the application, detach()
is called for the
component.
This method is rarely called directly. The
ComponentContainer.addComponent(Component)
method is normally
used for adding components to a container and it will call this method
implicitly.
It is not possible to change the parent without first setting the parent
to null
.
parent
- the parent component
IllegalStateException
- if a parent is given even though the component already has a
parentboolean isReadOnly()
Field
components normally have a value that can be input or changed by the
user, this is mostly relevant only to field components, though not
restricted to them.
Notice that the read-only mode only affects whether the user can change the value of the component; it is possible to, for example, scroll a read-only table.
The method will return true
if the component or any of its
parents is in the read-only mode.
true
if the component or any of its parents is in
read-only mode, false
if not.setReadOnly(boolean)
void setReadOnly(boolean readOnly)
As only Field
components normally have a value that can be input
or changed by the user, this is mostly relevant only to field components,
though not restricted to them.
Notice that the read-only mode only affects whether the user can change the value of the component; it is possible to, for example, scroll a read-only table.
This method will trigger a
RepaintRequestEvent
.
readOnly
- a boolean value specifying whether the component is put
read-only mode or notString getCaption()
See setCaption(String)
for a detailed description of the
caption.
null
if the caption is
not set.setCaption(String)
void setCaption(String caption)
A caption is an explanatory textual label accompanying a user
interface component, usually shown above, left of, or inside the
component. Icon (see setIcon()
is
closely related to caption and is usually displayed horizontally before
or after it, depending on the component and the containing layout.
The caption can usually also be given as the first parameter to a constructor, though some components do not support it.
RichTextArea area = new RichTextArea(); area.setCaption("You can edit stuff here"); area.setValue("<h1>Helpful Heading</h1>" + "<p>All this is for you to edit.</p>");
The contents of a caption are automatically quoted, so no raw XHTML can be rendered in a caption. The validity of the used character encoding, usually UTF-8, is not checked.
The caption 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 VerticalLayout
component shows the captions
left-aligned above the contained components, while the 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 CustomComponent
does not
manage the caption of its composition root, so if the root component has
a caption, it will not be rendered. Some components, such as
Button
and Panel
, manage the caption themselves and
display it inside the component.
This method will trigger a
RepaintRequestEvent
. A reimplementation should call the superclass
implementation.
caption
- the new caption for the component. If the caption is
null
, no caption is shown and it does not normally
take any spaceResource getIcon()
See setIcon(Resource)
for a detailed description of the icon.
null
if the
component has no iconsetIcon(Resource)
void setIcon(Resource 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 setCaption()
)
and is usually displayed horizontally before or after it, depending on
the component and the containing layout.
The image is loaded by the browser from a resource, typically a
ThemeResource
.
// 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 VerticalLayout
component shows the icons
left-aligned above the contained components, while the 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 CustomComponent
does not manage the
icon of its composition root, so if the root component has an icon, it
will not be rendered.
An icon will be rendered inside an HTML element that has the
v-icon
CSS style class. The containing layout may enclose an icon
and a caption inside elements related to the caption, such as
v-caption
.
RepaintRequestEvent
.
icon
- the icon of the component. If null, no icon is shown and it
does not normally take any space.getIcon()
,
setCaption(String)
Window getWindow()
If the component is not attached to a window through a component
containment hierarchy, null
is returned.
The window can be either an application-level window or a sub-window. If the component is itself a window, it returns a reference to itself, not to its containing window (of a sub-window).
null
if it is
not attached to a window or is itself a windowApplication getApplication()
The method will return null
if the component is not currently
attached to an application. This is often a problem in constructors of
regular components and in the initializers of custom composite
components. A standard workaround is to move the problematic
initialization to attach()
, as described in the documentation of
the method.
null
.attach()
void attach()
The caller of this method is setParent(Component)
if the parent
is itself already attached to the application. If not, the parent will
call the attach()
for all its children when it is attached to
the application. This method is always called before the component is
painted for the first time.
Reimplementing the attach()
method is useful for tasks that need
to get a reference to the parent, window, or application object with the
getParent()
, getWindow()
, and getApplication()
methods. A component does not yet know these objects in the constructor,
so in such case, the methods will return null
. For example, the
following is invalid:
public class AttachExample extends CustomComponent { public AttachExample() { // ERROR: We can't access the application object yet. ClassResource r = new ClassResource("smiley.jpg", getApplication()); Embedded image = new Embedded("Image:", r); setCompositionRoot(image); } }
Adding a component to an application triggers calling the
attach()
method for the component. Correspondingly, removing a
component from a container triggers calling the detach()
method.
If the parent of an added component is already connected to the
application, the attach()
is called immediately from
setParent(Component)
.
public class AttachExample extends CustomComponent { public AttachExample() { } @Override public void attach() { super.attach(); // Must call. // Now we know who ultimately owns us. ClassResource r = new ClassResource("smiley.jpg", getApplication()); Embedded image = new Embedded("Image:", r); setCompositionRoot(image); } }
The attachment logic is implemented in AbstractComponent
.
getApplication()
void detach()
The getApplication()
and getWindow()
methods might
return null
after this method is called.
The caller of this method is setParent(Component)
if the parent
is in the application. When the parent is detached from the application
it is its response to call detach()
for all the children and to
detach itself from the terminal.
Locale getLocale()
If a component does not have a locale set, the locale of its parent is
returned, and so on. Eventually, if no parent has locale set, the locale
of the application is returned. If the application does not have a locale
set, it is determined by Locale.getDefault()
.
As the component must be attached before its locale can be acquired, using this method in the internationalization of component captions, etc. is generally not feasible. For such use case, we recommend using an otherwise acquired reference to the application locale.
null
if the component and
none of its parents has a locale set and the component is not yet
attached to an application.void childRequestedRepaint(Collection<Paintable.RepaintRequestListener> alreadyNotified)
A repaint request is ignored if the component is invisible.
This method is called automatically by AbstractComponent
, which
also provides a default implementation of it. As this is a somewhat
internal feature, it is rarely necessary to reimplement this or call it
explicitly.
alreadyNotified
- the collection of repaint request listeners that have been
already notified by the child. This component should not
re-notify the listed listeners again. The container given as
parameter must be modifiable as the component might modify it
and pass it forward. A null
parameter is interpreted
as an empty collection.void addListener(Component.Listener listener)
class Listening extends CustomComponent implements Listener { // Stored for determining the source of an event Button ok; Label status; // For displaying info about the event public Listening() { VerticalLayout layout = new VerticalLayout(); // Some miscellaneous component TextField name = new TextField("Say it all here"); name.addListener(this); name.setImmediate(true); layout.addComponent(name); // Handle button clicks as generic events instead // of Button.ClickEvent events ok = new Button("OK"); ok.addListener(this); layout.addComponent(ok); // For displaying information about an event status = new Label(""); layout.addComponent(status); setCompositionRoot(layout); } public void componentEvent(Event event) { // Act according to the source of the event if (event.getSource() == ok) getWindow().showNotification("Click!"); status.setValue("Event from " + event.getSource().getClass().getName() + ": " + event.getClass().getName()); } } Listening listening = new Listening(); layout.addComponent(listening);
listener
- the new Listener to be registered.Component.Event
,
removeListener(Listener)
void removeListener(Component.Listener listener)
listener
- the listener to be removed.addListener(Listener)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |