diff options
Diffstat (limited to 'src/com/itmill/toolkit/ui/Component.java')
| -rw-r--r-- | src/com/itmill/toolkit/ui/Component.java | 324 |
1 files changed, 324 insertions, 0 deletions
diff --git a/src/com/itmill/toolkit/ui/Component.java b/src/com/itmill/toolkit/ui/Component.java new file mode 100644 index 0000000000..d1e6bb8039 --- /dev/null +++ b/src/com/itmill/toolkit/ui/Component.java @@ -0,0 +1,324 @@ +/* ************************************************************************* + + IT Mill Toolkit + + Development of Browser User Intarfaces Made Easy + + Copyright (C) 2000-2006 IT Mill Ltd + + ************************************************************************* + + This product is distributed under commercial license that can be found + from the product package on license/license.txt. Use of this product might + require purchasing a commercial license from IT Mill Ltd. For guidelines + on usage, see license/licensing-guidelines.html + + ************************************************************************* + + For more information, contact: + + IT Mill Ltd phone: +358 2 4802 7180 + Ruukinkatu 2-4 fax: +358 2 4802 7181 + 20540, Turku email: info@itmill.com + Finland company www: www.itmill.com + + Primary source for information and releases: www.itmill.com + + ********************************************************************** */ + +package com.itmill.toolkit.ui; + +import com.itmill.toolkit.Application; +import com.itmill.toolkit.terminal.ErrorMessage; +import com.itmill.toolkit.terminal.Paintable; +import com.itmill.toolkit.terminal.Resource; +import com.itmill.toolkit.terminal.VariableOwner; + +import java.util.Collection; +import java.util.EventListener; +import java.util.EventObject; +import java.util.Locale; + +/** The top-level component interface which must be implemented by all + * MillStone UI components. It contains the methods the MillStone framework + * needs to handle the components in a user interface. + * + * @author IT Mill Ltd. + * @version @VERSION@ + * @since 3.0 + */ +public interface Component extends Paintable, VariableOwner { + + /** Gets the look-and-feel style of the component. + * + * @return component's styleValue of property style. + */ + public String getStyle(); + + /** Sets the look-and-feel style of the component. This method will + * trigger a {@link com.itmill.toolkit.terminal.Paintable.RepaintRequestEvent RepaintRequestEvent}. + * . + * @param style new style of the component + */ + public void setStyle(String style); + + /** <p>Tests if the component is enabled or not. All the variable + * change events are blocked from disabled components. Also the + * component should visually indicate that it is disabled (by shading + * the component for example). + * All hidden (isVisible() == false) components must return false.</p> + * + * <p>Components should be enabled by default.</p> + * + * @return <code>true</code> if the component is enabled, + * <code>false</code> if not + * @see VariableOwner#isEnabled() + */ + public boolean isEnabled(); + + /** Enable or disable the component. Being enabled means that the + * component can be edited. This method will trigger a + * {@link com.itmill.toolkit.terminal.Paintable.RepaintRequestEvent RepaintRequestEvent}. + * + * @param enabled boolean value specifying if the component should be + * enabled after the call or not + */ + public void setEnabled(boolean enabled); + + /** Tests if the component is visible or not. Visibility defines if the + * component is shown in the UI or not. Default is <code>true</code>. + * + * @return <code>true</code> if the component is visible in the UI, + * <code>false</code> if not + */ + public boolean isVisible(); + + /** Sets the components visibility status. Visibility defines if the + * component is shown in the UI or not. + * + * @param visible Boolean value specifying if the component should be + * visible after the call or not + */ + public void setVisible(boolean visible); + + /** Gets the visual parent of the component. The components can be + * nested but one component can have only one parent. + * + * @return the parent component + */ + public Component getParent(); + + /** Sets the component's parent component. + * + * <p>This method calls + * automatically {@link #attach()} if the parent is attached to a + * window (or is itself a window}, and {@link #detach()} if + * <code>parent</code> is set <code>null</code>, but the component + * was in the application.</p> + * + * <p>This method is rarely called directly. Instead the + * {@link ComponentContainer#addComponent(Component)} method is used + * to add components to container, which call this method implicitly. + * + * @param parent the new parent component + */ + public void setParent(Component parent); + + /** Tests if the component is in read-only mode. + * + * @return <code>true</code> if the component is in read-only mode, + * <code>false</code> if not + */ + public boolean isReadOnly(); + + /** Sets the component's to read-only mode to the specified state. This + * method will trigger a + * {@link com.itmill.toolkit.terminal.Paintable.RepaintRequestEvent RepaintRequestEvent}. + * + * @param readOnly boolean value specifying if the component should be + * in read-only mode after the call or not + */ + public void setReadOnly(boolean readOnly); + + /** Gets the caption of the component. Caption is the visible name of + * the component. + * + * @return component's caption <code>String</code> + */ + public String getCaption(); + + /** Gets the component's icon. A component may have a graphical icon + * associated with it, this method retrieves it if it is defined. + * + * @return the component's icon or <code>null</code> if it not defined. + */ + public Resource getIcon(); + + /** Gets the component's parent window. If the component does not yet + * belong to a window <code>null</code> is returned. + * + * @return parent window of the component or <code>null</code> + */ + public Window getWindow(); + + /** Gets the component's parent application. If the component does not + * yet belong to a application <code>null</code> is returned. + * + * @return parent application of the component or <code>null</code> + */ + public Application getApplication(); + + /** Notifies the component that it is connected to an application. This + * method is always called before the component is first time painted + * and is suitable to be extended. The <code>getApplication()</code> and + * <code>getWindow()</code> functions might return <code>null</code> + * before this method is called.</p> + * + * <p>The caller of this method is {@link #setParent(Component)} if the + * parent is already in the application. If the parent is not in the + * application, it must call the {@link #attach()} for all its children + * when it will be added to the application.</p> + */ + public void attach(); + + /** Notifies the component that it is detached from the application. + * <p>The {@link #getApplication()} and {@link #getWindow()} + * methods might return <code>null</code> after this method is + * called.</p> + * + * <p>The caller of this method is {@link #setParent(Component)} if the + * parent is in the application. When the parent is detached from the application + * it is its response to call {@link #detach()} for all the children and + * to detach itself from the terminal.</p> + */ + public void detach(); + + /** Gets the locale of this component. + * + * @return This component's locale. If this component does not have a + * locale, the locale of its parent is returned. Eventually locale + * of application is returned. If application does not have its own + * locale the locale is determined by Locale.getDefautl(). Returns + * null if the component does not have its own locale and has not + * yet been added to a containment hierarchy such that the locale + * can be determined from the containing parent. + */ + public Locale getLocale(); + + /** The children must call this method when they need repainting. The call must be + * made event in the case the children sent the repaint request themselves. + * @param alreadyNotified A collection of repaint request listeners that have been + * already notified by the child. This component should not renotify the listed + * listeners again. The container given as parameter must be modifiable as the + * component might modify it and pass it forwards. Null parameter is interpreted + * as empty collection. + */ + public void childRequestedRepaint(Collection alreadyNotified); + + /* Component event framework *************************************** */ + + /** Superclass of all component originated <code>Event</code>s. */ + public class Event extends EventObject { + + /** + * Serial generated by eclipse. + */ + private static final long serialVersionUID = 4048791277653274933L; + + /** Constructs a new event with a specified source component. + * + * @param source source component of the event + */ + public Event(Component source) { + super(source); + } + } + + /** Listener interface for receiving <code>Component.Event</code>s */ + public interface Listener extends EventListener { + + /** Notifies the listener of a component event. + * + * @param event the event that has occured + */ + public void componentEvent(Component.Event event); + } + + /** Registers a new component event listener for this component. + * + * @param listener the new Listener to be registered + */ + public void addListener(Component.Listener listener); + + /** Removes a previously registered component event listener from this + * component. + * + * @param listener the listener to be removed + */ + public void removeListener(Component.Listener listener); + + /** Class of all component originated <code>ErrorEvent</code>s. */ + public class ErrorEvent extends Event { + + /** + * Serial generated by eclipse. + */ + private static final long serialVersionUID = 4051323457293857333L; + + private ErrorMessage message; + private Throwable throwable; + + /** Constructs a new event with a specified source component. + * + * @param source source component of the event + */ + public ErrorEvent( + ErrorMessage message, + Component component) { + super(component); + this.message = message; + } + + /** Return the error message */ + public ErrorMessage getErrorMessage() { + return this.message; + } + } + + /** Listener interface for receiving <code>Component.Errors</code>s */ + public interface ErrorListener extends EventListener { + + /** Notifies the listener of a component error. + * + * @param event the event that has occured + */ + public void componentError(Component.ErrorEvent event); + } + + /** Interface implemented by components which can obtain input focus. */ + public interface Focusable { + + /** Set focus to this component.*/ + public void focus(); + + /** Get Tabulator index of this Focusable component. + * @return Positive tab order of this focusable. Negative of zero means + * unspecified tab order. + */ + public int getTabIndex(); + + /** Set Tabulator index of this Focusable component. + * @param tabIndex Positive tab order of this focusable. Negative of + * zero means unspecified tab order. + */ + public void setTabIndex(int tabIndex); + + /** Get unique ID of focusable. + * This will be used to move input focus directly to this + * component. + * @return Unique id of focusable. + */ + public long getFocusableId(); + + } +} |