Java tutorial
/* * Copyright 2000-2018 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.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 { /** * 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 or removes a style name. Multiple styles can be specified as a * space-separated list of style names. * * If the {@code add} parameter is true, the style name is added to the * component. If the {@code add} parameter is false, the style name is * removed from the component. * <p> * Functionally this is equivalent to using {@link #addStyleName(String)} or * {@link #removeStyleName(String)} * * @since 8.5 * @param style * the style name to be added or removed * @param add * <code>true</code> to add the given style, <code>false</code> * to remove it * @see #addStyleName(String) * @see #removeStyleName(String) */ public default void setStyleName(String style, boolean add) { if (add) { addStyleName(style); } else { removeStyleName(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); /** * Adds one or more style names to this component by using one or multiple * parameters. * * @param styles * the style name or style names to be added to the component * @see #addStyleName(String) * @see #setStyleName(String) * @see #removeStyleName(String) * @since 8.1 */ public default void addStyleNames(String... styles) { for (String style : styles) { addStyleName(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); /** * Removes one or more style names from component. Multiple styles can be * specified by using multiple parameters. * * @param styles * the style name or style names to be removed * @see #removeStyleName(String) * @see #setStyleName(String) * @see #addStyleName(String) * @since 8.1 */ public default void removeStyleNames(String... styles) { for (String style : styles) { removeStyleName(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> * FormLayout loginBox = new FormLayout(); * loginBox.setCaption("Login"); * layout.addComponent(loginBox); * * // Create the first field which will be focused * TextField username = new TextField("User name"); * loginBox.addComponent(username); * * // Set focus to the user name * username.focus(); * * TextField password = new TextField("Password"); * loginBox.addComponent(password); * * Button login = new Button("Login"); * loginBox.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); } }