/*
* Copyright 2000-2016 Vaadin Ltd.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations under
* the License.
*/
package com.vaadin.ui;
import java.io.Serializable;
import java.util.Locale;
import org.jsoup.nodes.Element;
import com.vaadin.event.ConnectorEvent;
import com.vaadin.event.ConnectorEventListener;
import com.vaadin.event.FieldEvents;
import com.vaadin.server.ClientConnector;
import com.vaadin.server.ErrorMessage;
import com.vaadin.server.Resource;
import com.vaadin.server.Sizeable;
import com.vaadin.server.VariableOwner;
import com.vaadin.shared.Registration;
import com.vaadin.ui.declarative.DesignContext;
/**
* {@code Component} is the top-level interface that is and must be implemented
* by all Vaadin components. {@code Component} is paired with
* {@link AbstractComponent}, which provides a default implementation for all
* the methods defined in this interface.
*
* <p>
* Components are laid out in the user interface hierarchically. The layout is
* managed by layout components, or more generally by components that implement
* the {@link ComponentContainer} interface. Such a container is the
* <i>parent</i> of the contained components.
* </p>
*
* <p>
* The {@link #getParent()} method allows retrieving the parent component of a
* component. While there is a {@link #setParent(HasComponents)}, you rarely
* need it as you normally add components with the
* {@link ComponentContainer#addComponent(Component) addComponent()} method of
* the layout or other {@code ComponentContainer}, which automatically sets the
* parent.
* </p>
*
* <p>
* A component becomes <i>attached</i> to an application (and the
* {@link #attach()} is called) when it or one of its parents is attached to the
* main window of the application through its containment hierarchy.
* </p>
*
* @author Vaadin Ltd.
* @since 3.0
*/
public interface Component extends ClientConnector, Sizeable, Serializable {
/**
* Gets all user-defined CSS style names of a component. If the component
* has multiple style names defined, the return string is a space-separated
* list of style names. Built-in style names defined in Vaadin or GWT are
* not returned.
*
* <p>
* 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.
* </p>
*
* @return the style name or a space-separated list of user-defined style
* names of the component
* @see #setStyleName(String)
* @see #addStyleName(String)
* @see #removeStyleName(String)
*/
public String getStyleName();
/**
* Sets one or more user-defined style names of the component, replacing any
* previous user-defined styles. Multiple styles can be specified as a
* space-separated list of style names. The style names must be valid CSS
* class names and should not conflict with any built-in style names in
* Vaadin or GWT.
*
* <pre>
* Label label = new Label("This text has a lot of style");
* label.setStyleName("myonestyle myotherstyle");
* </pre>
*
* <p>
* 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 {@code Button} component and give it "{@code mystyle}" style, the
* component will have both "{@code mystyle}" and "{@code v-button-mystyle}"
* styles. You could then style the component either with:
* </p>
*
* <pre>
* .myonestyle {background: blue;}
* </pre>
*
* <p>
* or
* </p>
*
* <pre>
* .v-button-myonestyle {background: blue;}
* </pre>
*
* <p>
* It is normally a good practice to use {@link #addStyleName(String)
* addStyleName()} rather than this setter, as different software
* abstraction layers can then add their own styles without accidentally
* removing those defined in other layers.
* </p>
*
* @param style
* the new style or styles of the component as a space-separated
* list
* @see #getStyleName()
* @see #addStyleName(String)
* @see #removeStyleName(String)
*/
public void setStyleName(String style);
/**
* Adds one or more style names to this component. Multiple styles can be
* specified as a space-separated list of style names. The style name will
* be rendered as a HTML class name, which can be used in a CSS definition.
*
* <pre>
* Label label = new Label("This text has style");
* label.addStyleName("mystyle");
* </pre>
*
* <p>
* 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 {@code Button} component and give it "{@code mystyle}" style, the
* component will have both "{@code mystyle}" and "{@code v-button-mystyle}"
* styles. You could then style the component either with:
* </p>
*
* <pre>
* .mystyle {font-style: italic;}
* </pre>
*
* <p>
* or
* </p>
*
* <pre>
* .v-button-mystyle {font-style: italic;}
* </pre>
*
* @param style
* the new style to be added to the component
* @see #getStyleName()
* @see #setStyleName(String)
* @see #removeStyleName(String)
*/
public void addStyleName(String style);
/**
* Removes one or more style names from component. Multiple styles can be
* specified as a space-separated list of style names.
*
* <p>
* The parameter must be a valid CSS style name. Only user-defined style
* names added with {@link #addStyleName(String) addStyleName()} or
* {@link #setStyleName(String) setStyleName()} can be removed; built-in
* style names defined in Vaadin or GWT can not be removed.
* </p>
*
* @param style
* the style name or style names to be removed
* @see #getStyleName()
* @see #setStyleName(String)
* @see #addStyleName(String)
*/
public void removeStyleName(String style);
/**
* Gets the primary style name of the component. See
* {@link Component#setPrimaryStyleName(String)} for a better description of
* the primary stylename.
*/
public String getPrimaryStyleName();
/**
* Changes the primary style name of the component.
*
* <p>
* The primary style name identifies the component when applying the CSS
* theme to the Component. By changing the style name all CSS rules targeted
* for that style name will no longer apply, and might result in the
* component not working as intended.
* </p>
*
* <p>
* To preserve the original style of the component when changing to a new
* primary style you should make your new primary style inherit the old
* primary style using the SASS @include directive. See more in the SASS
* tutorials.
* </p>
*
* @param style
* The new primary style name
*/
public void setPrimaryStyleName(String style);
/**
* Tests whether the component is enabled or not. A user can not interact
* with disabled components. Disabled components are rendered in a style
* that indicates the status, usually in gray color. Children of a disabled
* component are also disabled. Components are enabled by default.
*
* <p>
* As a security feature, all updates for disabled components are blocked on
* the server-side.
* </p>
*
* <p>
* 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.
* </p>
*
* @return <code>true</code> if the component and its parent are enabled,
* <code>false</code> otherwise.
* @see VariableOwner#isEnabled()
*/
public boolean isEnabled();
/**
* Enables or disables the component. The user can not interact with
* disabled components, which are shown with a style that indicates the
* status, usually shaded in light gray color. Components are enabled by
* default.
*
* <pre>
* Button enabled = new Button("Enabled");
* enabled.setEnabled(true); // The default
* layout.addComponent(enabled);
*
* Button disabled = new Button("Disabled");
* disabled.setEnabled(false);
* layout.addComponent(disabled);
* </pre>
*
* @param enabled
* a boolean value specifying if the component should be enabled
* or not
*/
public void setEnabled(boolean enabled);
/**
* Tests the <i>visibility</i> property of the component.
*
* <p>
* 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.
* </p>
*
* <p>
* 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.
* </p>
*
* @return <code>true</code> if the component has been set to be visible in
* the user interface, <code>false</code> if not
* @see #setVisible(boolean)
* @see #attach()
*/
public boolean isVisible();
/**
* Sets the visibility of the component.
*
* <p>
* 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.
* </p>
*
* <pre>
* TextField readonly = new TextField("Read-Only");
* readonly.setValue("You can't see this!");
* readonly.setVisible(false);
* layout.addComponent(readonly);
* </pre>
*
* <p>
* 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.
* </p>
*
* @param visible
* the boolean value specifying if the component should be
* visible after the call or not.
* @see #isVisible()
*/
public void setVisible(boolean visible);
/**
* Sets the parent connector of the component.
*
* <p>
* This method automatically calls {@link #attach()} if the component
* becomes attached to the session, regardless of whether it was attached
* previously. Conversely, if the component currently is attached to the
* session, {@link #detach()} is called for the connector before attaching
* it to a new parent.
* </p>
* <p>
* This method is rarely called directly.
* {@link ComponentContainer#addComponent(Component)} or a
* {@link HasComponents} specific method is normally used for adding
* components to a parent and the used method will call this method
* implicitly.
* </p>
*
* @param parent
* the parent connector
* @throws IllegalStateException
* if a parent is given even though the connector already has a
* parent
*/
public void setParent(HasComponents parent);
/**
* Gets the parent component of the component.
*
* <p>
* 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 {@link ComponentContainer} interface.
* </p>
*
* @return the parent component
*/
@Override
public HasComponents getParent();
/**
* Gets the caption of the component.
*
* <p>
* See {@link #setCaption(String)} for a detailed description of the
* caption.
* </p>
*
* @return the caption of the component or {@code null} if the caption is
* not set.
* @see #setCaption(String)
*/
public String getCaption();
/**
* Sets the caption of the component.
*
* <p>
* A <i>caption</i> is an explanatory textual label accompanying a user
* interface component, usually shown above, left of, or inside the
* component. <i>Icon</i> (see {@link #setIcon(Resource) setIcon()} is
* closely related to caption and is usually displayed horizontally before
* or after it, depending on the component and the containing layout.
* </p>
*
* <p>
* The caption can usually also be given as the first parameter to a
* constructor, though some components do not support it.
* </p>
*
* <pre>
* 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>");
* </pre>
*
* <p>
* The contents of a caption are automatically quoted, so no raw HTML can be
* rendered in a caption. The validity of the used character encoding,
* usually UTF-8, is not checked.
* </p>
*
* <p>
* 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 {@link VerticalLayout} component shows the captions
* left-aligned above the contained components, while the {@link 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 {@link 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
* {@link Button} and {@link Panel}, manage the caption themselves and
* display it inside the component.
* </p>
*
* @param caption
* the new caption for the component. If the caption is
* {@code null}, no caption is shown and it does not normally
* take any space
*/
public void setCaption(String caption);
/**
* Gets the icon resource of the component.
*
* <p>
* See {@link #setIcon(Resource)} for a detailed description of the icon.
* </p>
*
* @return the icon resource of the component or {@code null} if the
* component has no icon
* @see #setIcon(Resource)
*/
public Resource getIcon();
/**
* Sets the icon of the component.
*
* <p>
* 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 {@link #setCaption(String) setCaption()})
* and is usually displayed horizontally before or after it, depending on
* the component and the containing layout.
* </p>
*
* <p>
* The image is loaded by the browser from a resource, typically a
* {@link com.vaadin.server.ThemeResource}.
* </p>
*
* <pre>
* // 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);
* </pre>
*
* <p>
* 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 {@link VerticalLayout} component shows the icons
* left-aligned above the contained components, while the {@link 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 {@link CustomComponent} does not manage the
* icon of its composition root, so if the root component has an icon, it
* will not be rendered.
* </p>
*
* <p>
* An icon will be rendered inside an HTML element that has the
* {@code v-icon} CSS style class. The containing layout may enclose an icon
* and a caption inside elements related to the caption, such as
* {@code v-caption} .
* </p>
*
* @param icon
* the icon of the component. If null, no icon is shown and it
* does not normally take any space.
* @see #getIcon()
* @see #setCaption(String)
*/
public void setIcon(Resource icon);
/**
* Gets the UI the component is attached to.
*
* <p>
* If the component is not attached to a UI through a component containment
* hierarchy, <code>null</code> is returned.
* </p>
*
* @return the UI of the component or <code>null</code> if it is not
* attached to a UI
*/
@Override
public UI getUI();
/**
* {@inheritDoc}
*
* <p>
* Reimplementing the {@code attach()} method is useful for tasks that need
* to get a reference to the parent, window, or application object with the
* {@link #getParent()} and {@link #getUI()} methods. A component does not
* yet know these objects in the constructor, so in such case, the methods
* will return {@code null}. For example, the following is invalid:
* </p>
*
* <pre>
* 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);
* }
* }
* </pre>
*
* <p>
* Adding a component to an application triggers calling the
* {@link #attach()} method for the component. Correspondingly, removing a
* component from a container triggers calling the {@link #detach()} method.
* If the parent of an added component is already connected to the
* application, the {@code attach()} is called immediately from
* {@link #setParent(HasComponents)}.
* </p>
*
* <pre>
* 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);
* }
* }
* </pre>
*/
@Override
public void attach();
/**
* Gets the locale of the component.
*
* <p>
* 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 <code>Locale.getDefault()</code>.
* </p>
*
* <p>
* 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.
* </p>
*
* @return Locale of this component or {@code null} if the component and
* none of its parents has a locale set and the component is not yet
* attached to an application.
*/
public Locale getLocale();
/**
* Adds an unique id for component that is used in the client-side for
* testing purposes. Keeping identifiers unique is the responsibility of the
* programmer.
*
* @param id
* An alphanumeric id
*/
public void setId(String id);
/**
* Gets currently set debug identifier
*
* @return current id, null if not set
*/
public String getId();
/**
* <p>
* Gets the components description, used in tooltips and can be displayed
* directly in certain other components such as forms. The description can
* be used to briefly describe the state of the component to the user. The
* description string may contain certain XML tags:
* </p>
*
* <p>
* <table border=1>
* <tr>
* <td width=120><b>Tag</b></td>
* <td width=120><b>Description</b></td>
* <td width=120><b>Example</b></td>
* </tr>
* <tr>
* <td><b></td>
* <td>bold</td>
* <td><b>bold text</b></td>
* </tr>
* <tr>
* <td><i></td>
* <td>italic</td>
* <td><i>italic text</i></td>
* </tr>
* <tr>
* <td><u></td>
* <td>underlined</td>
* <td><u>underlined text</u></td>
* </tr>
* <tr>
* <td><br></td>
* <td>linebreak</td>
* <td>N/A</td>
* </tr>
* <tr>
* <td><ul><br>
* <li>item1<br>
* <li>item1<br>
* </ul></td>
* <td>item list</td>
* <td>
* <ul>
* <li>item1
* <li>item2
* </ul>
* </td>
* </tr>
* </table>
* </p>
*
* <p>
* These tags may be nested.
* </p>
*
* @return component's description <code>String</code>
*/
public String getDescription();
/* Declarative support */
/**
* Reads the component state from the given design.
* <p>
* The component is responsible not only for updating its own state but also
* for ensuring that its children update their state based on the design.
* <p>
* It is assumed that the component is in its default state when this method
* is called. Reading should only take into consideration attributes
* specified in the design and not reset any unspecified attributes to their
* defaults.
* <p>
* This method must not modify the design.
*
* @since 7.4
* @param design
* The element to obtain the state from
* @param designContext
* The DesignContext instance used for parsing the design
*/
public void readDesign(Element design, DesignContext designContext);
/**
* Writes the component state to the given design.
* <p>
* The component is responsible not only for writing its own state but also
* for ensuring that its children write their state to the design.
* <p>
* This method must not modify the component state.
*
* @since 7.4
* @param design
* The element to write the component state to. Any previous
* attributes or child nodes are <i>not</i> cleared.
* @param designContext
* The DesignContext instance used for writing the design
*
*/
public void writeDesign(Element design, DesignContext designContext);
/* Component event framework */
/**
* Superclass of all component originated events.
*
* <p>
* Events are the basis of all user interaction handling in Vaadin. To
* handle events, you provide a listener object that receives the events of
* the particular event type.
* </p>
*
* <pre>
* Button button = new Button("Click Me!");
* button.addListener(new Button.ClickListener() {
* public void buttonClick(ClickEvent event) {
* getWindow().showNotification("Thank You!");
* }
* });
* layout.addComponent(button);
* </pre>
*
* <p>
* Notice that while each of the event types have their corresponding
* listener types; the listener interfaces are not required to inherit the
* {@code Component.Listener} interface.
* </p>
*
* @see Component.Listener
*/
@SuppressWarnings("serial")
public static class Event extends ConnectorEvent {
/**
* Constructs a new event with the specified source component.
*
* @param source
* the source component of the event
*/
public Event(Component source) {
super(source);
}
/**
* Gets the component where the event occurred.
*
* @return the source component of the event
*/
public Component getComponent() {
return (Component) getSource();
}
}
/**
* Listener interface for receiving <code>Component.Event</code>s.
*
* <p>
* Listener interfaces are the basis of all user interaction handling in
* Vaadin. You have or create a listener object that receives the events.
* All event types have their corresponding listener types; they are not,
* however, required to inherit the {@code Component.Listener} interface,
* and they rarely do so.
* </p>
*
* <p>
* This generic listener interface is useful typically when you wish to
* handle events from different component types in a single listener method
* ({@code componentEvent()}. If you handle component events in an anonymous
* listener class, you normally use the component specific listener class,
* such as {@link com.vaadin.ui.Button.ClickEvent}.
* </p>
*
* <pre>
* class Listening extends CustomComponent implements Listener {
* Button ok; // Stored for determining the source of an event
*
* 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);
* 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
* && event.getClass() == Button.ClickEvent.class)
* getWindow().showNotification("Click!");
*
* // Display source component and event class names
* status.setValue(
* "Event from " + event.getSource().getClass().getName()
* + ": " + event.getClass().getName());
* }
* }
*
* Listening listening = new Listening();
* layout.addComponent(listening);
* </pre>
*
* @see Component#addListener(Listener)
*/
public interface Listener extends ConnectorEventListener {
/**
* Notifies the listener of a component event.
*
* <p>
* As the event can typically come from one of many source components,
* you may need to differentiate between the event source by component
* reference, class, etc.
* </p>
*
* <pre>
* public void componentEvent(Event event) {
* // Act according to the source of the event
* if (event.getSource() == ok
* && event.getClass() == Button.ClickEvent.class)
* getWindow().showNotification("Click!");
*
* // Display source component and event class names
* status.setValue(
* "Event from " + event.getSource().getClass().getName() + ": "
* + event.getClass().getName());
* }
* </pre>
*
* @param event
* the event that has occurred.
*/
public void componentEvent(Component.Event event);
}
/**
* Registers a new (generic) component event listener for the component.
*
* <pre>
* 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);
* 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);
* </pre>
*
* @param listener
* the new Listener to be registered.
* @return a registration object for removing this listener
* @see Component.Event
* @see Registration
* @since 8.0
*/
public Registration addListener(Component.Listener listener);
/**
* Removes a previously registered component event listener from this
* component.
*
* @param listener
* the listener to be removed.
* @see #addListener(Listener)
*
* @deprecated As of 8.0, replaced by {@link Registration#remove()} in the
* registration object returned from
* {@link #addListener(Component.Listener)}.
*/
@Deprecated
public void removeListener(Component.Listener listener);
/**
* Class of all component originated error events.
*
* <p>
* The component error event is normally fired by
* {@link AbstractComponent#setComponentError(ErrorMessage)}. The component
* errors are set by the framework in some situations and can be set by user
* code. They are indicated in a component with an error indicator.
* </p>
*/
@SuppressWarnings("serial")
public static class ErrorEvent extends Event {
private final ErrorMessage message;
/**
* Constructs a new event with a specified source component.
*
* @param message
* the error message.
* @param component
* the source component.
*/
public ErrorEvent(ErrorMessage message, Component component) {
super(component);
this.message = message;
}
/**
* Gets the error message.
*
* @return the error message.
*/
public ErrorMessage getErrorMessage() {
return message;
}
}
/**
* A sub-interface implemented by components that can obtain input focus.
* This includes all {@code LegacyField} components as well as some other
* components, such as {@code Upload}.
*
* <p>
* Focus can be set with {@link #focus()}. This interface does not provide
* an accessor that would allow finding out the currently focused component;
* focus information can be acquired for some (but not all)
* {@code LegacyField} components through the
* {@link com.vaadin.event.FieldEvents.FocusListener} and
* {@link com.vaadin.event.FieldEvents.BlurListener} interfaces.
* </p>
*
* @see FieldEvents
*/
public interface Focusable extends Component {
/**
* Sets the focus to this component.
*
* <pre>
* Form loginBox = new Form();
* loginBox.setCaption("Login");
* layout.addComponent(loginBox);
*
* // Create the first field which will be focused
* TextField username = new TextField("User name");
* loginBox.addField("username", username);
*
* // Set focus to the user name
* username.focus();
*
* TextField password = new TextField("Password");
* loginBox.addField("password", password);
*
* Button login = new Button("Login");
* loginBox.getFooter().addComponent(login);
* </pre>
*
* <p>
* Notice that this interface does not provide an accessor that would
* allow finding out the currently focused component. Focus information
* can be acquired for some (but not all) components through the
* {@link com.vaadin.event.FieldEvents.FocusListener} and
* {@link com.vaadin.event.FieldEvents.BlurListener} interfaces.
* </p>
*
* @see com.vaadin.event.FieldEvents
* @see com.vaadin.event.FieldEvents.FocusEvent
* @see com.vaadin.event.FieldEvents.FocusListener
* @see com.vaadin.event.FieldEvents.BlurEvent
* @see com.vaadin.event.FieldEvents.BlurListener
*/
public void focus();
/**
* Gets the <i>tabulator index</i> of the {@code Focusable} component.
*
* @return tab index set for the {@code Focusable} component
* @see #setTabIndex(int)
*/
public int getTabIndex();
/**
* Sets the <i>tabulator index</i> of the {@code Focusable} component.
* The tab index property is used to specify the order in which the
* fields are focused when the user presses the Tab key. Components with
* a defined tab index are focused sequentially first, and then the
* components with no tab index.
*
* <pre>
* Form loginBox = new Form();
* loginBox.setCaption("Login");
* layout.addComponent(loginBox);
*
* // Create the first field which will be focused
* TextField username = new TextField("User name");
* loginBox.addField("username", username);
*
* // Set focus to the user name
* username.focus();
*
* TextField password = new TextField("Password");
* loginBox.addField("password", password);
*
* Button login = new Button("Login");
* loginBox.getFooter().addComponent(login);
*
* // An additional component which natural focus order would
* // be after the button.
* CheckBox remember = new CheckBox("Remember me");
* loginBox.getFooter().addComponent(remember);
*
* username.setTabIndex(1);
* password.setTabIndex(2);
* remember.setTabIndex(3); // Different than natural place
* login.setTabIndex(4);
* </pre>
*
* <p>
* After all focusable user interface components are done, the browser
* can begin again from the component with the smallest tab index, or it
* can take the focus out of the page, for example, to the location bar.
* </p>
*
* <p>
* If the tab index is not set (is set to zero), the default tab order
* is used. The order is somewhat browser-dependent, but generally
* follows the HTML structure of the page.
* </p>
*
* <p>
* A negative value means that the component is completely removed from
* the tabulation order and can not be reached by pressing the Tab key
* at all.
* </p>
*
* @param tabIndex
* the tab order of this component. Indexes usually start
* from 1. Zero means that default tab order should be used.
* A negative value means that the field should not be
* included in the tabbing sequence.
* @see #getTabIndex()
*/
public void setTabIndex(int tabIndex);
}
}