com.jeta.forms.gui.form
Interface FormAccessor

All Superinterfaces:
ComponentFinder, SwingComponentSupport

public interface FormAccessor
extends SwingComponentSupport

A FormAccessor is used to programmatically access and modify components on a form.

You should always use FormAccessors instead of modifying the underlying Container directly. The main reason is because the forms component hierachy may change in the future.

FormAccessors only modify the form they are associated with. A form can have nested forms, but FormAccessors do not access nested forms (except when using nested iterators).

Be careful when using components that have implicit JScrollPanes. The designer allows you to set a scroll property for those components that are scrollable (for example JTree, JTable, JList), and the forms runtime automatically creates JScrollPanes for those components you specifiy as scrollable. When iterating over a container, implicit scroll pane instances will be returned rather than the underlying Java bean for those scrollable components.

FormAccessors provide direct access to the underlying FormLayout and its assciated container. It is not recommended that you programmatically create CellConstraints and change the layout using hard-coded column and row values. The reason is because it is very easy to modify the form using the Forms Designer. Any modificiations can break code that has hard-coded columns and rows. The best approach is to name all of your components (including the scrollpanes) and access them by name whenever possible. This applies to wizard-like GUIs as well. It is recommended that in these cases, you provide a dummy component on the form such as an empty JLabel. You can then replace the dummy component with another component at runtime (via replaceBean ).


Method Summary
 void addBean(Component comp, CellConstraints cc)
          Adds a bean to this container using the given constraints.
 Iterator beanIterator()
          Defaults to beanIterator(false).
 Iterator beanIterator(boolean nested)
          An iterator for a collection of Java Beans (java.awt.Component objects) contained by a FormPanel.
 CellConstraints getConstraints(Component comp)
          Returns a CellConstraints instance associated with the given component.
 Container getContainer()
          Return the actual container that has the given layout.
 String getFormName()
          Returns the name assigned to the form component associated with this accessor.
 Component removeBean(Component comp)
          Removes a bean from the container associated with this accessor.
 Component removeBean(String compName)
          Removes a bean with the given name from the container associated with this accessor.
 Component replaceBean(Component oldComp, Component newComponent)
          Replaces an existing bean with a new bean.
 Component replaceBean(String compName, Component newComponent)
          Locates an existing bean with the given name and replaces it with a new bean.
 
Methods inherited from interface com.jeta.open.support.SwingComponentSupport
enableComponent, getBoolean, getButton, getCheckBox, getComboBox, getInteger, getLabel, getList, getPanel, getProgressBar, getRadioButton, getSelectedItem, getSpinner, getTabbedPane, getTable, getText, getTextComponent, getTextField, getTree, isSelected, setSelected, setSelectedItem, setText, setVisible
 
Methods inherited from interface com.jeta.open.support.ComponentFinder
getAllNamedComponents, getComponentByName, getComponentsByName, reset
 

Method Detail

getFormName

String getFormName()
Returns the name assigned to the form component associated with this accessor.

Returns:
the name assigned to the form component associated with this accessor.

getConstraints

CellConstraints getConstraints(Component comp)
Returns a CellConstraints instance associated with the given component. If the component is not contained by the form associated with this accessor, null is returned.

Returns:
the constraints associated with the given component.

addBean

void addBean(Component comp,
             CellConstraints cc)
Adds a bean to this container using the given constraints.

Parameters:
comp - the bean to add to the form.
cc - the constraints for the bean. This must be a valid CellConstraints instance.

getContainer

Container getContainer()
Return the actual container that has the given layout. This method should rarely be called. It is only provided for very limited cased. If you need to access the underlying FormLayout, you can retrieve it from the Container returned by this call.

Returns:
the container associated with the FormLayout

beanIterator

Iterator beanIterator()
Defaults to beanIterator(false). See beanIterator(boolean)

Returns:
an iterator to all the Java Beans in this container. Beans in nested containers are not included.

beanIterator

Iterator beanIterator(boolean nested)
An iterator for a collection of Java Beans (java.awt.Component objects) contained by a FormPanel. Only components that occupy a cell in the grid on the form are returned - not children of those components. For example, if you have a Java Bean such as a calendar that has several child components, only the calendar instance will be returned. This iterator will not return the child components of that bean. However, if a component is a nested form and the nested parameter is true, then this iterator will return the components in the nested form (as well as the form itself). If an iterator encounters a nested form instance, that object will be returned (regardless of whether the nested flag is set). A component is a nested form if it is an instance of a FormAccessor:
 
 Iterator iter = formaccessor.beanIterator(); while( iter.hasNext() ) {
 Component comp = (Component)iter.next(); if ( comp instanceof
 FormAccessor ) { // found a nested form. // if this iterator is nested,
 the next call to next will // return components in the nested
 form. } else { // found a standard Java Bean } }
 
 
The iterator is fail-fast. If any components are added or removed by invoking the underlying FormAccessors at any time after the Iterator is created, the iterator will throw a ConcurrentModificationException. If nested is true, then the iterator will fail if components are added to any FormAccessor in the form hierarchy. You may safely call remove on the iterator if you want to remove the component from the form. Note that you should not modify the underlying form container by calling the Container methods directly. This is not recommended and can also leave the form in an undefined state.

Parameters:
nested - if true, all components in nested forms will be returned.
Returns:
an iterator to all the Java Beans in this container.

removeBean

Component removeBean(Component comp)
Removes a bean from the container associated with this accessor. If the given component is contained by an implicit JScrollPane or is an implicit JSCrollPane, the JScrollPane is removed.

Parameters:
comp - the component to remove.
Returns:
the component that was removed. If this method fails for any reason then null is returned.

removeBean

Component removeBean(String compName)
Removes a bean with the given name from the container associated with this accessor. The bean must be contained within the current form. This method will not remove beans in nested forms. If compName refers to a component contained by an implicit JScrollPane or compName directly refers to an implicit JSCrollPane, the JScrollPane is removed.

Parameters:
compName - the name of the Java Bean to remove.
Returns:
the component that was removed. If this method fails for any reason then null is returned.

replaceBean

Component replaceBean(Component oldComp,
                      Component newComponent)
Replaces an existing bean with a new bean. If the old component is contained by an implicit JScrollPane or is an implicit JSCrollPane, the JScrollPane is replaced.

Parameters:
oldComp - the component to replace
newComponent - the component to add.
Returns:
the component that was replaced. If this method fails for any reason then null is returned.

replaceBean

Component replaceBean(String compName,
                      Component newComponent)
Locates an existing bean with the given name and replaces it with a new bean. The bean must be contained within the current form. This method will not remove beans in nested forms. If the old component is contained by an implicit JScrollPane or is an implicit JSCrollPane, the JScrollPane is replaced.

Parameters:
compName - the name of the component to replace.
newComponent - the component to add.
Returns:
the component that was replaced. If this method fails for any reason then null is returned.


Copyright © 2005-2007 Jeff Tassin & Todd Viegut. All Rights Reserved.