1 /*
2 * Copyright 2006-2016 The JGUIraffe Team.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License")
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package net.sf.jguiraffe.gui.builder.components.model;
17
18 /**
19 * <p>
20 * Definition of a specialized {@code ListModel} extension interface to be used
21 * by editable combo boxes.
22 * </p>
23 * <p>
24 * A {@code ListModel} per default contains a mapping from display objects (to
25 * be presented on the UI) to value objects (the application uses internally)
26 * and vice versa. This is fine as long the user can only select an element from
27 * a given set of available options.
28 * </p>
29 * <p>
30 * For an editable combo box situation is different. Here the user can enter
31 * arbitrary values, and therefore it is possible that there is no mapping from
32 * the display object to a value object in the model. This extended interface
33 * addresses this problem. It defines explicit methods for mapping from display
34 * objects to value objects or vice versa. These methods are called if no match
35 * in the current {@code ListModel} is found. A concrete implementation can then
36 * perform a transformation as it pleases.
37 * </p>
38 *
39 * @author Oliver Heger
40 * @version $Id: $
41 */
42 public interface EditableComboBoxModel
43 {
44 /**
45 * Transforms a value object to a display object. This method is called at
46 * initialization of a component if the object obtained from the data model
47 * cannot be matched in the list model. An implementation is then
48 * responsible for mapping it to a correct object that can be displayed by
49 * the combo box.
50 *
51 * @param value the value object to be transformed
52 * @return the corresponding display object for this value
53 */
54 Object toDisplay(Object value);
55
56 /**
57 * Transforms a display object to a value object. This method is called when
58 * data entered by the user is to be written back into the data model and
59 * the selected object of the combo box cannot be matched in the list model.
60 * An implementation then has to create a value object to be passed to the
61 * data model.
62 *
63 * @param displ the display object to be transformed
64 * @return the corresponding value object
65 */
66 Object toValue(Object displ);
67 }