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 an interface that is used to obtain the content of a list box
21 * or combo box component.
22 * </p>
23 * <p>
24 * When lists or combo boxes or similar components are to be displayed their
25 * content must be specified. This can be a list of static texts in the most
26 * simple cases, but also the results of a data base query. To support all of
27 * these possibilities the form builder library introduces this interface which
28 * serves as an abstraction of a real data source.
29 * </p>
30 * <p>
31 * This interface defines methods for obtaining the data to be displayed. The
32 * displayed data need not be the same that will be stored in the form bean for
33 * this element, so it is also possible to define a specific value for each
34 * element to be displayed. The <code>getType()</code> method will determine
35 * the data type of the corresponding property in the form bean.
36 * </p>
37 *
38 * @author Oliver Heger
39 * @version $Id: ListModel.java 205 2012-01-29 18:29:57Z oheger $
40 */
41 public interface ListModel
42 {
43 /**
44 * Returns the number of entries in this model.
45 *
46 * @return the number of entries
47 */
48 int size();
49
50 /**
51 * Returns the display object with the given index. This object will be
52 * displayed in the list box (or its string representation respective). A
53 * concrete implementation must never return <b>null </b>.
54 *
55 * @param index the index (0 based)
56 * @return the display object at this index
57 */
58 Object getDisplayObject(int index);
59
60 /**
61 * <p>
62 * Returns the value object with the given index.
63 * </p>
64 * <p>
65 * This method makes sense when the display objects are different from the
66 * values that should be stored when corresponding display objects are
67 * selected. E.g. the display objects might be simple strings that represent
68 * complex data objects. When a string is selected the component's data
69 * really is the data object behind this string. In this case the
70 * <code>getValueObject()</code> method would return the complex data
71 * objects, while <code>getDisplayObject()</code> would return
72 * corresponding string representations.
73 * </p>
74 * <p>
75 * When working with a fix set of options from which the user can select one
76 * or some, it is often useful to store the indices of the selected display
77 * objects. Imagine a combo box that offer the choices "yes",
78 * "no", and "maybe". In the bean of the form that
79 * contains this combo box it makes sense to store the values 0, 1, or 2
80 * depending on the user's selection rather than the (language dependend)
81 * string values. To achieve this, the <code>getValueObject()</code>
82 * method can always return <b>null </b>. Then as values always the
83 * corresponding indices will be used as values. Note: an implementation
84 * must not mix these variants; either it must return <b>null </b> for all
85 * of its values or none.
86 * </p>
87 *
88 * @param index the index (0 based)
89 * @return the value object for this index
90 */
91 Object getValueObject(int index);
92
93 /**
94 * Returns the data object of this list model. This is the type of the value
95 * objects stored in the data property for the corresponding component.
96 *
97 * @return the data type of this model
98 */
99 Class<?> getType();
100 }