|
||||||||||
| 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.Errorss. |
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.Events. |
| Nested classes/interfaces inherited from interface com.vaadin.terminal.Sizeable |
|---|
Sizeable.Unit |
| Field Summary |
|---|
| Fields inherited from interface com.vaadin.terminal.Sizeable |
|---|
SIZE_UNDEFINED, 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 connector that it is connected to an application. |
Application |
getApplication()
Gets the application object to which the component is attached. |
String |
getCaption()
Gets the caption of the component. |
String |
getDebugId()
Get's currently set debug identifier |
Resource |
getIcon()
Gets the icon resource of the component. |
Locale |
getLocale()
Gets the locale of the component. |
HasComponents |
getParent()
Gets the parent component of the component. |
Root |
getRoot()
Gets the Root the component is attached to. |
ComponentState |
getState()
Returns the current shared state bean for the component. |
String |
getStyleName()
Gets all user-defined CSS style names of a 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 |
setDebugId(String id)
Adds an unique id for component that get's transferred to terminal for testing purposes. |
void |
setEnabled(boolean enabled)
Enables or disables the component. |
void |
setIcon(Resource icon)
Sets the icon 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. |
void |
updateState()
Called before the shared state is sent to the client. |
| Methods inherited from interface com.vaadin.terminal.gwt.server.ClientConnector |
|---|
detach, getExtensions, getStateType, isConnectorEnabled, removeExtension, requestRepaint, requestRepaintAll, retrievePendingRpcCalls, setParent |
| Methods inherited from interface com.vaadin.terminal.gwt.client.Connector |
|---|
getConnectorId |
| Methods inherited from interface com.vaadin.terminal.gwt.server.RpcTarget |
|---|
getRpcManager |
| Methods inherited from interface com.vaadin.terminal.Sizeable |
|---|
getHeight, getHeightUnits, getWidth, getWidthUnits, setHeight, setHeight, setSizeFull, setSizeUndefined, setWidth, setWidth |
| 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 updates for disabled components are blocked on the server-side.
Note that this method only returns the status of the component and does not take parents into account. Even though this method returns true the component can be disabled to the user if a parent is disabled.
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 - no information about an invisible component will be sent to the client. The effect is thus the same as removing the component from its parent. 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. This is not checked by this method though, so even if this method returns true, the component can be hidden from the user because a parent is set to invisible.
true if the component has been set to be 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 - no information about an invisible component will be sent to the client. The effect is thus the same as removing the component from its parent.
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()HasComponents 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.
getParent in interface ClientConnectorgetParent in interface Connectorboolean 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)Root getRoot()
If the component is not attached to a Root through a component
containment hierarchy, null is returned.
getRoot in interface ClientConnectornull if it is not
attached to a RootApplication getApplication()
The method will return null if the component is not currently
attached to an application.
Getting a null value is often a problem in constructors of regular
components and in the initializers of custom composite components. A
standard workaround is to use Application.getCurrent() to
retrieve the application instance that the current request relates to.
Another way 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 ClientConnector.setParent(ClientConnector) if the
parent is itself already attached to the application. If not, the parent
will call the ClientConnector.attach() for all its children when it is attached
to the application. This method is always called before the connector's
data is sent to the client-side for the first time.
The attachment logic is implemented in AbstractClientConnector.
Reimplementing the attach() method is useful for tasks that need
to get a reference to the parent, window, or application object with the
getParent(), getRoot(), 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 ClientConnector.detach() method.
If the parent of an added component is already connected to the
application, the attach() is called immediately from
#setParent(Component).
This method must call Root#componentAttached(Component) to let
the Root know that a new Component has been attached.
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);
}
}
attach in interface ClientConnectorLocale 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.ComponentState getState()
getState in interface Connectorvoid updateState()
This method must not alter the component hierarchy in any way.
void setDebugId(String id)
id - An alphanumeric idString getDebugId()
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 | |||||||||