001 /*
002 * Copyright 2002-2004 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
005 * use this file except in compliance with the License. You may obtain a copy of
006 * the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
012 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
013 * License for the specific language governing permissions and limitations under
014 * the License.
015 */
016
017 package org.springframework.richclient.form;
018
019 import java.util.List;
020
021 import org.springframework.binding.form.FormModel;
022 import org.springframework.binding.form.ValidatingFormModel;
023 import org.springframework.binding.validation.ValidationListener;
024 import org.springframework.binding.value.ValueModel;
025 import org.springframework.richclient.core.Guarded;
026 import org.springframework.richclient.dialog.Messagable;
027 import org.springframework.richclient.factory.ControlFactory;
028
029 /**
030 * The graphical representation of the {@link FormModel} by extending
031 * {@link ControlFactory} and providing {@link FormModel} related methods.
032 *
033 * Additional methods that link with the model are:
034 *
035 * <ul>
036 * <li>{@link #newSingleLineResultsReporter(Messagable)}: combine the
037 * validation results of the model with a messagable component to show
038 * validation messages.</li>
039 * <li>{@link #addGuarded(Guarded)}, {@link #addGuarded(Guarded, int)} and
040 * {@link #removeGuarded(Guarded)} to bind objects to the formModel state and
041 * implement a suitable reaction. This can translate in eg a save-button that
042 * will synchronize its enabled state with a dirty and no-error state in the
043 * formModel.</li>
044 * </ul>
045 *
046 * @author Keith Donald
047 */
048 public interface Form extends ControlFactory {
049
050 /**
051 * Returns the id of this form.
052 */
053 String getId();
054
055 /**
056 * Returns the formModel used by the form.
057 */
058 ValidatingFormModel getFormModel();
059
060 /**
061 * Convenience method to return the formObject currently used in the inner
062 * formModel.
063 */
064 Object getFormObject();
065
066 /**
067 * Convenience method to set the formObject on the inner formModel.
068 */
069 void setFormObject(Object formObject);
070
071 /**
072 * Convenience method to get the value of a specific property from the inner
073 * formModel.
074 */
075 Object getValue(String formProperty);
076
077 /**
078 * Convenience method to get the valueModel of a specific property from the
079 * inner formModel.
080 */
081 ValueModel getValueModel(String formProperty);
082
083 /**
084 * Add a ValidationListener.
085 */
086 void addValidationListener(ValidationListener listener);
087
088 /**
089 * Remove a ValidationListener.
090 */
091 public void removeValidationListener(ValidationListener listener);
092
093 /**
094 * Create a {@link ValidationResultsReporter} for this form, sending input
095 * to the given {@link Messagable}.
096 *
097 * TODO check why it's specifically mentioning "singleLine" in the method
098 * name (can be any validationResultsReporter)
099 *
100 * @param messageAreaPane the message receiver used by the created
101 * resultsReporter.
102 * @return a new ResultsReporter.
103 */
104 public ValidationResultsReporter newSingleLineResultsReporter(Messagable messageAreaPane);
105
106 /**
107 * Attach the given {@link Guarded} object with the default mask to the
108 * formModel.
109 *
110 * @see #addGuarded(Guarded, int)
111 * @see FormGuard
112 */
113 public void addGuarded(Guarded guarded);
114
115 /**
116 * Attach the given {@link Guarded} object with the specified mask to the
117 * formModel.
118 *
119 * @see FormGuard
120 */
121 public void addGuarded(Guarded guarded, int mask);
122
123 /**
124 * Detach the {@link Guarded} object.
125 */
126 public void removeGuarded(Guarded guarded);
127
128 /**
129 * Returns the list of ValidationResultsReporters of this Form.
130 */
131 List getValidationResultsReporters();
132
133 /**
134 * Add a ValidationResultsReporter to this Form.
135 */
136 void addValidationResultsReporter(ValidationResultsReporter validationResultsReporter);
137
138 /**
139 * Remove the given ValidationResultsReporter from this Form.
140 */
141 void removeValidationResultsReporter(ValidationResultsReporter validationResultsReporter);
142
143 /**
144 * Add the given Form as a child to this Form. FormModels and other aspects
145 * of this form must behave according to the parent-child relation.
146 */
147 void addChildForm(Form form);
148
149 /**
150 * Remove the given Form as child from this Form. Parent-child relation will
151 * be removed from their FormModels and other aspects as well.
152 */
153 void removeChildForm(Form form);
154
155 /**
156 * Returns <code>true</code> if the inner <code>FormModel</code> has
157 * errors.
158 */
159 boolean hasErrors();
160
161 /**
162 * Commit all values of the <code>FormModel</code>.
163 *
164 * @see FormModel#commit()
165 */
166 void commit();
167
168 /**
169 * Revert the <code>FormModel</code>.
170 *
171 * @see FormModel#revert()
172 */
173 void revert();
174
175 /**
176 * Reset the <code>FormModel</code>.
177 *
178 * @see FormModel#reset()
179 */
180 void reset();
181 }