001: /* *************************************************************************
002:
003: Millstone(TM)
004: Open Sourced User Interface Library for
005: Internet Development with Java
006:
007: Millstone is a registered trademark of IT Mill Ltd
008: Copyright (C) 2000-2005 IT Mill Ltd
009:
010: *************************************************************************
011:
012: This library is free software; you can redistribute it and/or
013: modify it under the terms of the GNU Lesser General Public
014: license version 2.1 as published by the Free Software Foundation.
015:
016: This library is distributed in the hope that it will be useful,
017: but WITHOUT ANY WARRANTY; without even the implied warranty of
018: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
019: Lesser General Public License for more details.
020:
021: You should have received a copy of the GNU Lesser General Public
022: License along with this library; if not, write to the Free Software
023: Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
024:
025: *************************************************************************
026:
027: For more information, contact:
028:
029: IT Mill Ltd phone: +358 2 4802 7180
030: Ruukinkatu 2-4 fax: +358 2 4802 7181
031: 20540, Turku email: info@itmill.com
032: Finland company www: www.itmill.com
033:
034: Primary source for MillStone information and releases: www.millstone.org
035:
036: ********************************************************************** */
037:
038: package org.millstone.base.ui;
039:
040: import org.millstone.base.terminal.ErrorMessage;
041: import org.millstone.base.terminal.Resource;
042: import org.millstone.base.terminal.Paintable;
043: import org.millstone.base.terminal.VariableOwner;
044: import org.millstone.base.Application;
045:
046: import java.util.Collection;
047: import java.util.EventListener;
048: import java.util.EventObject;
049: import java.util.Locale;
050:
051: /** The top-level component interface which must be implemented by all
052: * MillStone UI components. It contains the methods the MillStone framework
053: * needs to handle the components in a user interface.
054: *
055: * @author IT Mill Ltd.
056: * @version 3.1.1
057: * @since 3.0
058: */
059: public interface Component extends Paintable, VariableOwner {
060:
061: /** Gets the look-and-feel style of the component.
062: *
063: * @return component's styleValue of property style.
064: */
065: public String getStyle();
066:
067: /** Sets the look-and-feel style of the component. This method will
068: * trigger a {@link org.millstone.base.terminal.Paintable.RepaintRequestEvent RepaintRequestEvent}.
069: * .
070: * @param style new style of the component
071: */
072: public void setStyle(String style);
073:
074: /** <p>Tests if the component is enabled or not. All the variable
075: * change events are blocked from disabled components. Also the
076: * component should visually indicate that it is disabled (by shading
077: * the component for example).
078: * All hidden (isVisible() == false) components must return false.</p>
079: *
080: * <p>Components should be enabled by default.</p>
081: *
082: * @return <code>true</code> if the component is enabled,
083: * <code>false</code> if not
084: * @see VariableOwner#isEnabled()
085: */
086: public boolean isEnabled();
087:
088: /** Enable or disable the component. Being enabled means that the
089: * component can be edited. This method will trigger a
090: * {@link org.millstone.base.terminal.Paintable.RepaintRequestEvent RepaintRequestEvent}.
091: *
092: * @param enabled boolean value specifying if the component should be
093: * enabled after the call or not
094: */
095: public void setEnabled(boolean enabled);
096:
097: /** Tests if the component is visible or not. Visibility defines if the
098: * component is shown in the UI or not. Default is <code>true</code>.
099: *
100: * @return <code>true</code> if the component is visible in the UI,
101: * <code>false</code> if not
102: */
103: public boolean isVisible();
104:
105: /** Sets the components visibility status. Visibility defines if the
106: * component is shown in the UI or not.
107: *
108: * @param visible Boolean value specifying if the component should be
109: * visible after the call or not
110: */
111: public void setVisible(boolean visible);
112:
113: /** Gets the visual parent of the component. The components can be
114: * nested but one component can have only one parent.
115: *
116: * @return the parent component
117: */
118: public Component getParent();
119:
120: /** Sets the component's parent component.
121: *
122: * <p>This method calls
123: * automatically {@link #attach()} if the parent is attached to a
124: * window (or is itself a window}, and {@link #detach()} if
125: * <code>parent</code> is set <code>null</code>, but the component
126: * was in the application.</p>
127: *
128: * <p>This method is rarely called directly. Instead the
129: * {@link ComponentContainer#addComponent(Component)} method is used
130: * to add components to container, which call this method implicitly.
131: *
132: * @param parent the new parent component
133: */
134: public void setParent(Component parent);
135:
136: /** Tests if the component is in read-only mode.
137: *
138: * @return <code>true</code> if the component is in read-only mode,
139: * <code>false</code> if not
140: */
141: public boolean isReadOnly();
142:
143: /** Sets the component's to read-only mode to the specified state. This
144: * method will trigger a
145: * {@link org.millstone.base.terminal.Paintable.RepaintRequestEvent RepaintRequestEvent}.
146: *
147: * @param readOnly boolean value specifying if the component should be
148: * in read-only mode after the call or not
149: */
150: public void setReadOnly(boolean readOnly);
151:
152: /** Gets the caption of the component. Caption is the visible name of
153: * the component.
154: *
155: * @return component's caption <code>String</code>
156: */
157: public String getCaption();
158:
159: /** Gets the component's icon. A component may have a graphical icon
160: * associated with it, this method retrieves it if it is defined.
161: *
162: * @return the component's icon or <code>null</code> if it not defined.
163: */
164: public Resource getIcon();
165:
166: /** Gets the component's parent window. If the component does not yet
167: * belong to a window <code>null</code> is returned.
168: *
169: * @return parent window of the component or <code>null</code>
170: */
171: public Window getWindow();
172:
173: /** Gets the component's parent application. If the component does not
174: * yet belong to a application <code>null</code> is returned.
175: *
176: * @return parent application of the component or <code>null</code>
177: */
178: public Application getApplication();
179:
180: /** Notifies the component that it is connected to an application. This
181: * method is always called before the component is first time painted
182: * and is suitable to be extended. The <code>getApplication()</code> and
183: * <code>getWindow()</code> functions might return <code>null</code>
184: * before this method is called.</p>
185: *
186: * <p>The caller of this method is {@link #setParent(Component)} if the
187: * parent is already in the application. If the parent is not in the
188: * application, it must call the {@link #attach()} for all its children
189: * when it will be added to the application.</p>
190: */
191: public void attach();
192:
193: /** Notifies the component that it is detached from the application.
194: * <p>The {@link #getApplication()} and {@link #getWindow()}
195: * methods might return <code>null</code> after this method is
196: * called.</p>
197: *
198: * <p>The caller of this method is {@link #setParent(Component)} if the
199: * parent is in the application. When the parent is detached from the application
200: * it is its response to call {@link #detach()} for all the children and
201: * to detach itself from the terminal.</p>
202: */
203: public void detach();
204:
205: /** Gets the locale of this component.
206: *
207: * @return This component's locale. If this component does not have a
208: * locale, the locale of its parent is returned. Eventually locale
209: * of application is returned. If application does not have its own
210: * locale the locale is determined by Locale.getDefautl(). Returns
211: * null if the component does not have its own locale and has not
212: * yet been added to a containment hierarchy such that the locale
213: * can be determined from the containing parent.
214: */
215: public Locale getLocale();
216:
217: /** The children must call this method when they need repainting. The call must be
218: * made event in the case the children sent the repaint request themselves.
219: * @param alreadyNotified A collection of repaint request listeners that have been
220: * already notified by the child. This component should not renotify the listed
221: * listeners again. The container given as parameter must be modifiable as the
222: * component might modify it and pass it forwards. Null parameter is interpreted
223: * as empty collection.
224: */
225: public void childRequestedRepaint(Collection alreadyNotified);
226:
227: /* Component event framework *************************************** */
228:
229: /** Superclass of all component originated <code>Event</code>s. */
230: public class Event extends EventObject {
231:
232: /**
233: * Serial generated by eclipse.
234: */
235: private static final long serialVersionUID = 4048791277653274933L;
236:
237: /** Constructs a new event with a specified source component.
238: *
239: * @param source source component of the event
240: */
241: public Event(Component source) {
242: super (source);
243: }
244: }
245:
246: /** Listener interface for receiving <code>Component.Event</code>s */
247: public interface Listener extends EventListener {
248:
249: /** Notifies the listener of a component event.
250: *
251: * @param event the event that has occured
252: */
253: public void componentEvent(Component.Event event);
254: }
255:
256: /** Registers a new component event listener for this component.
257: *
258: * @param listener the new Listener to be registered
259: */
260: public void addListener(Component.Listener listener);
261:
262: /** Removes a previously registered component event listener from this
263: * component.
264: *
265: * @param listener the listener to be removed
266: */
267: public void removeListener(Component.Listener listener);
268:
269: /** Class of all component originated <code>ErrorEvent</code>s. */
270: public class ErrorEvent extends Event {
271:
272: /**
273: * Serial generated by eclipse.
274: */
275: private static final long serialVersionUID = 4051323457293857333L;
276:
277: private ErrorMessage message;
278: private Throwable throwable;
279:
280: /** Constructs a new event with a specified source component.
281: *
282: * @param source source component of the event
283: */
284: public ErrorEvent(ErrorMessage message, Component component) {
285: super (component);
286: this .message = message;
287: }
288:
289: /** Return the error message */
290: public ErrorMessage getErrorMessage() {
291: return this .message;
292: }
293: }
294:
295: /** Listener interface for receiving <code>Component.Errors</code>s */
296: public interface ErrorListener extends EventListener {
297:
298: /** Notifies the listener of a component error.
299: *
300: * @param event the event that has occured
301: */
302: public void componentError(Component.ErrorEvent event);
303: }
304:
305: /** Interface implemented by components which can obtain input focus. */
306: public interface Focusable {
307:
308: /** Set focus to this component.*/
309: public void focus();
310:
311: /** Get Tabulator index of this Focusable component.
312: * @return Positive tab order of this focusable. Negative of zero means
313: * unspecified tab order.
314: */
315: public int getTabIndex();
316:
317: /** Set Tabulator index of this Focusable component.
318: * @param tabIndex Positive tab order of this focusable. Negative of
319: * zero means unspecified tab order.
320: */
321: public void setTabIndex(int tabIndex);
322:
323: /** Get unique ID of focusable.
324: * This will be used to move input focus directly to this
325: * component.
326: * @return Unique id of focusable.
327: */
328: public long getFocusableId();
329:
330: }
331: }
|