001: /*
002: ItsNat Java Web Application Framework
003: Copyright (C) 2007 Innowhere Software Services S.L., Spanish Company
004: Author: Jose Maria Arranz Santamaria
005:
006: This program is free software: you can redistribute it and/or modify
007: it under the terms of the GNU Affero General Public License as published by
008: the Free Software Foundation, either version 3 of the License, or
009: (at your option) any later version. See the GNU Affero General Public
010: License for more details. See the copy of the GNU Affero General Public License
011: included in this program. If not, see <http://www.gnu.org/licenses/>.
012: */
013:
014: package org.itsnat.comp;
015:
016: import org.itsnat.comp.ui.ItsNatComponentUI;
017: import org.itsnat.core.ItsNatDocument;
018: import java.beans.PropertyChangeListener;
019: import java.beans.VetoableChangeListener;
020: import org.itsnat.core.ItsNatUserData;
021: import org.itsnat.core.event.ParamTransport;
022: import org.w3c.dom.Node;
023: import org.w3c.dom.events.EventListener;
024:
025: /**
026: * Is the base interface which every ItsNat component implements.
027: *
028: * <p>Some components have property change tracking like {@link ItsNatLabel} and
029: * {@link org.itsnat.comp.html.ItsNatHTMLInputTextFormatted} components. If no property is tracked
030: * by the component, listeners registered using {@link #addPropertyChangeListener(PropertyChangeListener)}
031: * {@link #addPropertyChangeListener(String,PropertyChangeListener)}
032: * or {@link #addVetoableChangeListener(VetoableChangeListener)}
033: * are never called.</p>
034: *
035: * @author Jose Maria Arranz Santamaria
036: * @see ItsNatComponentManager#createItsNatComponent(org.w3c.dom.Node,String,org.itsnat.core.NameValue[])
037: */
038: public interface ItsNatComponent extends ItsNatUserData {
039: /**
040: * Returns the associated DOM node to this component.
041: *
042: * @return the associated DOM node.
043: */
044: public Node getNode();
045:
046: /**
047: * Changes the associated DOM node (reattachment).
048: *
049: * @param node the new DOM node.
050: */
051: public void setNode(Node node);
052:
053: /**
054: * Registers the specified event listener to the component node.
055: *
056: * <p>The specified event type is automatically enabled (see {@link #enableEventListener(String)}).</p>
057: * <p>If this component has a default behavior associated to the specified event type, the listener
058: * is executed <i>after</i> this default behavior.</p>
059: * <p>Several listeners may be registered to the same event type.</p>
060: *
061: * @param type the event type to listen.
062: * @param listener the listener to be executed.
063: */
064: public void addEventListener(String type, EventListener listener);
065:
066: /**
067: * Unregisters the specified event listener from the component node.
068: *
069: * @param type the event type of the listener to unregister.
070: * @param listener to unregister.
071: */
072: public void removeEventListener(String type, EventListener listener);
073:
074: /**
075: * Enable the component to receive events of the specified type.
076: *
077: * <p>If this component has a default behavior associated to the specified type
078: * (and is disabled by default) then is enabled.</p>
079: *
080: * @param type the event type to enable.
081: * @see #addEventListener(String,org.w3c.dom.events.EventListener)
082: */
083: public void enableEventListener(String type);
084:
085: /**
086: * Disables the component to receive events of the specified type.
087: *
088: * <p>No event listener added with {@link #addEventListener(String,org.w3c.dom.events.EventListener)}
089: * is unregistered.</p>
090: *
091: * @param type the event type to enable.
092: */
093: public void disableEventListener(String type);
094:
095: /**
096: * Returns the ItsNat document this document is associated to.
097: *
098: * @return the associated ItsNat document.
099: */
100: public ItsNatDocument getItsNatDocument();
101:
102: /**
103: * Returns the ItsNat component manager parent of this component.
104: *
105: * @return the parent ItsNat component manager.
106: */
107: public ItsNatComponentManager getItsNatComponentManager();
108:
109: /**
110: * Returns the user interface manager of this component.
111: *
112: * @return the user interface manager.
113: */
114: public ItsNatComponentUI getItsNatComponentUI();
115:
116: /**
117: * Disposes this component. A disposed component can no longer be used.
118: *
119: * <p>Typical dispose operations are: disable event listeners and disconnect data and selection models.
120: * A component "disposed" <i>should</i> can be garbage collected.</p>
121: *
122: * @see #disableEventListener(String).
123: */
124: public void dispose();
125:
126: /**
127: * Sets the parameters used to fire and receive AJAX events by this component.
128: *
129: * <p>All current registered event listeners are affected.</p>
130: *
131: *
132: * @param type the DOM event type name (click, change etc).
133: * @param useCapture if event capture is enabled. False is the most portable value (MSIE v6 does not support event capture).
134: * @param syncMode synchronization mode.
135: * @param extraParams optional client to server data transport and synchronization rules. May be null.
136: * @param preSendCode custom JavaScript code to execute before an event of this listener type is fired. May be null.
137: * @param ajaxTimeout the timeout of AJAX events. If negative no timeout is defined.
138: * @see org.itsnat.core.ItsNatDocument#addEventListener(org.w3c.dom.events.EventTarget,String,org.w3c.dom.events.EventListener,boolean,int,org.itsnat.core.event.ParamTransport[],String,long)
139: */
140: public void setEventListenerParams(String type, boolean useCapture,
141: int syncMode, ParamTransport[] extraParams,
142: String preSendCode, long ajaxTimeout);
143:
144: /**
145: * Informs whether this component has the focus.
146: *
147: * <p>Returned value is only valid if this component processes "focus" and "blur" events.
148: *
149: * @return true if this component has the focus.
150: */
151: public boolean hasFocus();
152:
153: /**
154: * Registers a new property change listener listening for any property change.
155: *
156: * @param listener the property change listener to register.
157: */
158: public void addPropertyChangeListener(
159: PropertyChangeListener listener);
160:
161: /**
162: * Removes the specified property change listener listening for any property change.
163: *
164: * @param listener the property change listener to unregister.
165: */
166: public void removePropertyChangeListener(
167: PropertyChangeListener listener);
168:
169: /**
170: * Returns all registered listeners listening for any property change.
171: *
172: * @return a listener array.
173: */
174: public PropertyChangeListener[] getPropertyChangeListeners();
175:
176: /**
177: * Registers a new property change listener listening for the specified property name.
178: *
179: * @param propertyName the property name.
180: * @param listener the property change listener to register.
181: */
182: public void addPropertyChangeListener(String propertyName,
183: PropertyChangeListener listener);
184:
185: /**
186: * Removes the specified property change listener listening for the specified property name.
187: *
188: * @param propertyName the property name.
189: * @param listener the property change listener to unregister.
190: */
191: public void removePropertyChangeListener(String propertyName,
192: PropertyChangeListener listener);
193:
194: /**
195: * Returns all registered listeners listening for changes in the specified property.
196: *
197: * @param propertyName the property name.
198: * @return a listener array.
199: */
200: public PropertyChangeListener[] getPropertyChangeListeners(
201: String propertyName);
202:
203: /**
204: * Registers a new vetoable property change listener listening for any property change.
205: *
206: * @param listener the vetoable property change listener to register.
207: */
208: public void addVetoableChangeListener(
209: VetoableChangeListener listener);
210:
211: /**
212: * Removes the specified vetoable property change listener listening for any property change.
213: *
214: * @param listener the vetoable property change listener to unregister.
215: */
216: public void removeVetoableChangeListener(
217: VetoableChangeListener listener);
218:
219: /**
220: * Returns all registered listeners listening for any vetoable property change.
221: *
222: * @return a listener array.
223: */
224: public VetoableChangeListener[] getVetoableChangeListeners();
225:
226: /**
227: * Registers an artifact with the specified name.
228: *
229: * @param name the artifact name
230: * @param value the artifact.
231: * @see #getArtifact(String)
232: * @see #removeArtifact(String)
233: * @see org.itsnat.core.NameValue
234: */
235: public void registerArtifact(String name, Object value);
236:
237: /**
238: * Returns the artifact with the specified name.
239: *
240: * @param name the artifact name to look for.
241: * @return the artifact or null if not found.
242: * @see #registerArtifact(String,Object)
243: * @see #getArtifact(String,boolean)
244: */
245: public Object getArtifact(String name);
246:
247: /**
248: * Removes the artifact with the specified name.
249: *
250: * @param name the artifact name to look for.
251: * @return the removed artifact.
252: * @see #registerArtifact(String,Object)
253: */
254: public Object removeArtifact(String name);
255:
256: /**
257: * Returns the artifact with the specified name.
258: *
259: * <p>If no artifact is found and <code>cascade</code> is true,
260: * the method {@link ItsNatDocument#getArtifact(String,boolean)}
261: * is called with <code>cascade</code> set to true to continue searching.</p>
262: *
263: * @param name the artifact name to look for.
264: * @return the artifact or null if not found.
265: * @see #getArtifact(String)
266: */
267: public Object getArtifact(String name, boolean cascade);
268:
269: }
|