001: /*
002: * Copyright (c) 2004 JETA Software, Inc. All rights reserved.
003: *
004: * Redistribution and use in source and binary forms, with or without modification,
005: * are permitted provided that the following conditions are met:
006: *
007: * o Redistributions of source code must retain the above copyright notice,
008: * this list of conditions and the following disclaimer.
009: *
010: * o Redistributions in binary form must reproduce the above copyright notice,
011: * this list of conditions and the following disclaimer in the documentation
012: * and/or other materials provided with the distribution.
013: *
014: * o Neither the name of JETA Software nor the names of its contributors may
015: * be used to endorse or promote products derived from this software without
016: * specific prior written permission.
017: *
018: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
019: * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
020: * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
021: * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
022: * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
023: * INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
024: * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
025: * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
026: * INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
027: * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
028: */
029:
030: package com.jeta.forms.gui.form;
031:
032: import java.awt.Component;
033: import java.awt.Container;
034: import java.util.Iterator;
035:
036: import com.jeta.open.support.SwingComponentSupport;
037: import com.jgoodies.forms.layout.CellConstraints;
038:
039: /**
040: * A FormAccessor is used to programmatically access and modify components on a
041: * form.
042: * <p>
043: *
044: * You should always use FormAccessors instead of modifying the underlying
045: * <tt>Container</tt> directly. The main reason is because the forms component
046: * hierachy may change in the future.
047: * <p>
048: *
049: * FormAccessors only modify the form they are associated with. A form can have
050: * nested forms, but FormAccessors do not access nested forms (except when using
051: * nested iterators).
052: * <p>
053: *
054: * Be careful when using components that have implicit JScrollPanes. The
055: * designer allows you to set a <i>scroll property</i> for those components
056: * that are scrollable (for example JTree, JTable, JList), and the forms runtime
057: * automatically creates JScrollPanes for those components you specifiy as
058: * scrollable. When iterating over a container, implicit scroll pane instances
059: * will be returned rather than the underlying Java bean for those scrollable
060: * components.
061: * <p>
062: *
063: * FormAccessors provide direct access to the underlying FormLayout and its
064: * assciated container. It is not recommended that you programmatically create
065: * CellConstraints and change the layout using hard-coded column and row values.
066: * The reason is because it is very easy to modify the form using the Forms
067: * Designer. Any modificiations can break code that has hard-coded columns and
068: * rows. The best approach is to name all of your components (including the
069: * scrollpanes) and access them by name whenever possible. This applies to
070: * wizard-like GUIs as well. It is recommended that in these cases, you provide
071: * a dummy component on the form such as an empty JLabel. You can then replace
072: * the dummy component with another component at runtime (via
073: * <tt>replaceBean</tt> ).
074: * <p>
075: *
076: * @author Jeff Tassin
077: */
078: public interface FormAccessor extends SwingComponentSupport {
079: /**
080: * Returns the name assigned to the form component associated with this
081: * accessor.
082: *
083: * @return the name assigned to the form component associated with this
084: * accessor.
085: */
086: public String getFormName();
087:
088: /**
089: * Returns a CellConstraints instance associated with the given component.
090: * If the component is not contained by the form associated with this
091: * accessor, null is returned.
092: *
093: * @return the constraints associated with the given component.
094: */
095: public CellConstraints getConstraints(Component comp);
096:
097: /**
098: * Adds a bean to this container using the given constraints.
099: *
100: * @param comp
101: * the bean to add to the form.
102: * @param cc
103: * the constraints for the bean. This must be a valid
104: * CellConstraints instance.
105: */
106: public void addBean(Component comp, CellConstraints cc);
107:
108: /**
109: * Return the actual container that has the given layout. This method should
110: * rarely be called. It is only provided for very limited cased. If you need
111: * to access the underlying FormLayout, you can retrieve it from the
112: * Container returned by this call.
113: *
114: * @return the container associated with the FormLayout
115: */
116: public Container getContainer();
117:
118: /**
119: * Defaults to beanIterator(false). See {@link #beanIterator(boolean)}
120: *
121: * @return an iterator to all the Java Beans in this container. Beans in
122: * nested containers are not included.
123: */
124: public Iterator beanIterator();
125:
126: /**
127: * An iterator for a collection of Java Beans (java.awt.Component objects)
128: * contained by a FormPanel. Only components that occupy a cell in the grid
129: * on the form are returned - not children of those components. For example,
130: * if you have a Java Bean such as a calendar that has several child
131: * components, only the calendar instance will be returned. This iterator
132: * will not return the child components of that bean. However, if a
133: * component is a nested form and the nested parameter is true, then this
134: * iterator will return the components in the nested form (as well as the
135: * form itself).
136: *
137: * If an iterator encounters a nested form instance, that object will be
138: * returned (regardless of whether the nested flag is set). A component is a
139: * nested form if it is an instance of a FormAccessor:
140: *
141: * <PRE>
142: *
143: * Iterator iter = formaccessor.beanIterator(); while( iter.hasNext() ) {
144: * Component comp = (Component)iter.next(); if ( comp instanceof
145: * FormAccessor ) { // found a nested form. // if this iterator is nested,
146: * the next call to <i>next</i> will // return components in the nested
147: * form. } else { // found a standard Java Bean } }
148: *
149: * </PRE>
150: *
151: * The iterator is fail-fast. If any components are added or removed by
152: * invoking the underlying FormAccessors at any time after the Iterator is
153: * created, the iterator will throw a ConcurrentModificationException. If
154: * nested is true, then the iterator will fail if components are added to
155: * <i>any</i> FormAccessor in the form hierarchy. You may safely call
156: * remove on the iterator if you want to remove the component from the form.
157: * Note that you should not modify the underlying form container by calling
158: * the <tt>Container</tt> methods directly. This is not recommended and
159: * can also leave the form in an undefined state.
160: *
161: * @param nested
162: * if true, all components in nested forms will be returned.
163: * @return an iterator to all the Java Beans in this container.
164: */
165: public Iterator beanIterator(boolean nested);
166:
167: /**
168: * Removes a bean from the container associated with this accessor. If the
169: * given component is contained by an implicit JScrollPane or is an implicit
170: * JSCrollPane, the JScrollPane is removed.
171: *
172: * @param comp
173: * the component to remove.
174: * @return the component that was removed. If this method fails for any
175: * reason then null is returned.
176: */
177: public Component removeBean(Component comp);
178:
179: /**
180: * Removes a bean with the given name from the container associated with
181: * this accessor. The bean must be contained within the current form. This
182: * method will not remove beans in nested forms. If compName refers to a
183: * component contained by an implicit JScrollPane or compName directly
184: * refers to an implicit JSCrollPane, the JScrollPane is removed.
185: *
186: * @param compName
187: * the name of the Java Bean to remove.
188: * @return the component that was removed. If this method fails for any
189: * reason then null is returned.
190: */
191: public Component removeBean(String compName);
192:
193: /**
194: * Replaces an existing bean with a new bean. If the old component is
195: * contained by an implicit JScrollPane or is an implicit JSCrollPane, the
196: * JScrollPane is replaced.
197: *
198: * @param oldComp
199: * the component to replace
200: * @param newComponent
201: * the component to add.
202: * @return the component that was replaced. If this method fails for any
203: * reason then null is returned.
204: */
205: public Component replaceBean(Component oldComp,
206: Component newComponent);
207:
208: /**
209: * Locates an existing bean with the given name and replaces it with a new
210: * bean. The bean must be contained within the current form. This method
211: * will not remove beans in nested forms. If the old component is contained
212: * by an implicit JScrollPane or is an implicit JSCrollPane, the JScrollPane
213: * is replaced.
214: *
215: * @param compName
216: * the name of the component to replace.
217: * @param newComponent
218: * the component to add.
219: * @return the component that was replaced. If this method fails for any
220: * reason then null is returned.
221: */
222: public Component replaceBean(String compName, Component newComponent);
223:
224: }
|