1 /*
2 * Copyright (c) 2012, 2014, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javafx.scene.control.cell;
27
28 import static javafx.scene.control.cell.CellUtils.createChoiceBox;
29 import javafx.beans.property.ObjectProperty;
30 import javafx.beans.property.SimpleObjectProperty;
31 import javafx.collections.FXCollections;
32 import javafx.collections.ObservableList;
33 import javafx.event.EventHandler;
34 import javafx.scene.control.ChoiceBox;
35 import javafx.scene.control.Label;
36 import javafx.scene.control.TableCell;
37 import javafx.scene.control.TableColumn;
38 import javafx.util.Callback;
39 import javafx.util.StringConverter;
40
41 /**
42 * A class containing a {@link TableCell} implementation that draws a
43 * {@link ChoiceBox} node inside the cell.
44 *
45 * <p>By default, the ChoiceBoxTableCell is rendered as a {@link Label} when not
46 * being edited, and as a ChoiceBox when in editing mode. The ChoiceBox will, by
47 * default, stretch to fill the entire table cell.
48 *
49 * <p>To create a ChoiceBoxTableCell, it is necessary to provide zero or more
50 * items that will be shown to the user when the {@link ChoiceBox} menu is
51 * showing. These items must be of the same type as the TableColumn.
52 *
53 * @param <T> The type of the elements contained within the TableColumn.
54 * @since JavaFX 2.2
55 */
56 public class ChoiceBoxTableCell<S,T> extends TableCell<S,T> {
57
58 /***************************************************************************
59 * *
60 * Static cell factories *
61 * *
62 **************************************************************************/
63
64 /**
65 * Creates a ChoiceBox cell factory for use in {@link TableColumn} controls.
66 * By default, the ChoiceBoxCell is rendered as a {@link Label} when not
67 * being edited, and as a ChoiceBox when in editing mode. The ChoiceBox will,
68 * by default, stretch to fill the entire list cell.
69 *
70 * @param <T> The type of the elements contained within the TableColumn.
71 * @param items Zero or more items that will be shown to the user when the
72 * {@link ChoiceBox} menu is showing. These items must be of the same
73 * type as the TableColumn. Note that it is up to the developer to set
74 * {@link EventHandler event handlers} to listen to edit events in the
75 * TableColumn, and react accordingly. Methods of interest include
76 * {@link TableColumn#setOnEditStart(javafx.event.EventHandler) setOnEditStart},
77 * {@link TableColumn#setOnEditCommit(javafx.event.EventHandler) setOnEditCommit},
78 * and {@link TableColumn#setOnEditCancel(javafx.event.EventHandler) setOnEditCancel}.
79 * @return A {@link Callback} that will return a TableCell that is able to
80 * work on the type of element contained within the TableColumn.
81 */
82 @SafeVarargs
83 public static <S,T> Callback<TableColumn<S,T>, TableCell<S,T>> forTableColumn(final T... items) {
84 return forTableColumn(null, items);
85 }
86
87 /**
88 * Creates a ChoiceBox cell factory for use in {@link TableColumn} controls.
89 * By default, the ChoiceBoxCell is rendered as a {@link Label} when not
90 * being edited, and as a ChoiceBox when in editing mode. The ChoiceBox
91 * will, by default, stretch to fill the entire list cell.
92 *
93 * @param <T> The type of the elements contained within the TableColumn.
94 * @param converter A {@link StringConverter} to convert the given item (of type T)
95 * to a String for displaying to the user.
96 * @param items Zero or more items that will be shown to the user when the
97 * {@link ChoiceBox} menu is showing. These items must be of the same
98 * type as the TableColumn. Note that it is up to the developer to set
99 * {@link EventHandler event handlers} to listen to edit events in the
100 * TableColumn, and react accordingly. Methods of interest include
101 * {@link TableColumn#setOnEditStart(javafx.event.EventHandler) setOnEditStart},
102 * {@link TableColumn#setOnEditCommit(javafx.event.EventHandler) setOnEditCommit},
103 * and {@link TableColumn#setOnEditCancel(javafx.event.EventHandler) setOnEditCancel}.
104 * @return A {@link Callback} that will return a TableCell that is able to
105 * work on the type of element contained within the TableColumn.
106 */
107 @SafeVarargs
108 public static <S,T> Callback<TableColumn<S,T>, TableCell<S,T>> forTableColumn(
109 final StringConverter<T> converter,
110 final T... items) {
111 return forTableColumn(converter, FXCollections.observableArrayList(items));
112 }
113
114 /**
115 * Creates a ChoiceBox cell factory for use in {@link TableColumn} controls.
116 * By default, the ChoiceBoxCell is rendered as a {@link Label} when not
117 * being edited, and as a ChoiceBox when in editing mode. The ChoiceBox will,
118 * by default, stretch to fill the entire list cell.
119 *
120 * @param <T> The type of the elements contained within the TableColumn.
121 * @param items Zero or more items that will be shown to the user when the
122 * {@link ChoiceBox} menu is showing. These items must be of the same
123 * type as the TableColumn. Note that it is up to the developer to set
124 * {@link EventHandler event handlers} to listen to edit events in the
125 * TableColumn, and react accordingly. Methods of interest include
126 * {@link TableColumn#setOnEditStart(javafx.event.EventHandler) setOnEditStart},
127 * {@link TableColumn#setOnEditCommit(javafx.event.EventHandler) setOnEditCommit},
128 * and {@link TableColumn#setOnEditCancel(javafx.event.EventHandler) setOnEditCancel}.
129 * @return A {@link Callback} that will return a TableCell that is able to
130 * work on the type of element contained within the TableColumn.
131 */
132 public static <S,T> Callback<TableColumn<S,T>, TableCell<S,T>> forTableColumn(
133 final ObservableList<T> items) {
134 return forTableColumn(null, items);
135 }
136
137 /**
138 * Creates a ChoiceBox cell factory for use in {@link TableColumn} controls.
139 * By default, the ChoiceBoxCell is rendered as a {@link Label} when not
140 * being edited, and as a ChoiceBox when in editing mode. The ChoiceBox will,
141 * by default, stretch to fill the entire list cell.
142 *
143 * @param <T> The type of the elements contained within the TableColumn.
144 * @param converter A {@link StringConverter} to convert the given item (of type T)
145 * to a String for displaying to the user.
146 * @param items Zero or more items that will be shown to the user when the
147 * {@link ChoiceBox} menu is showing. These items must be of the same
148 * type as the TableColumn. Note that it is up to the developer to set
149 * {@link EventHandler event handlers} to listen to edit events in the
150 * TableColumn, and react accordingly. Methods of interest include
151 * {@link TableColumn#setOnEditStart(javafx.event.EventHandler) setOnEditStart},
152 * {@link TableColumn#setOnEditCommit(javafx.event.EventHandler) setOnEditCommit},
153 * and {@link TableColumn#setOnEditCancel(javafx.event.EventHandler) setOnEditCancel}.
154 * @return A {@link Callback} that will return a TableCell that is able to
155 * work on the type of element contained within the TableColumn.
156 */
157 public static <S,T> Callback<TableColumn<S,T>, TableCell<S,T>> forTableColumn(
158 final StringConverter<T> converter,
159 final ObservableList<T> items) {
160 return list -> new ChoiceBoxTableCell<S,T>(converter, items);
161 }
162
163
164
165 /***************************************************************************
166 * *
167 * Fields *
168 * *
169 **************************************************************************/
170
171 private final ObservableList<T> items;
172
173 private ChoiceBox<T> choiceBox;
174
175
176
177 /***************************************************************************
178 * *
179 * Constructors *
180 * *
181 **************************************************************************/
182
183 /**
184 * Creates a default ChoiceBoxTableCell with an empty items list.
185 */
186 public ChoiceBoxTableCell() {
187 this(FXCollections.<T>observableArrayList());
188 }
189
190 /**
191 * Creates a default {@link ChoiceBoxTableCell} instance with the given items
192 * being used to populate the {@link ChoiceBox} when it is shown.
193 *
194 * @param items The items to show in the ChoiceBox popup menu when selected
195 * by the user.
196 */
197 @SafeVarargs
198 public ChoiceBoxTableCell(T... items) {
199 this(FXCollections.observableArrayList(items));
200 }
201
202 /**
203 * Creates a {@link ChoiceBoxTableCell} instance with the given items
204 * being used to populate the {@link ChoiceBox} when it is shown, and the
205 * {@link StringConverter} being used to convert the item in to a
206 * user-readable form.
207 *
208 * @param converter A {@link StringConverter} that can convert an item of type T
209 * into a user-readable string so that it may then be shown in the
210 * ChoiceBox popup menu.
211 * @param items The items to show in the ChoiceBox popup menu when selected
212 * by the user.
213 */
214 @SafeVarargs
215 public ChoiceBoxTableCell(StringConverter<T> converter, T... items) {
216 this(converter, FXCollections.observableArrayList(items));
217 }
218
219 /**
220 * Creates a default {@link ChoiceBoxTableCell} instance with the given items
221 * being used to populate the {@link ChoiceBox} when it is shown.
222 *
223 * @param items The items to show in the ChoiceBox popup menu when selected
224 * by the user.
225 */
226 public ChoiceBoxTableCell(ObservableList<T> items) {
227 this(null, items);
228 }
229
230 /**
231 * Creates a {@link ChoiceBoxTableCell} instance with the given items
232 * being used to populate the {@link ChoiceBox} when it is shown, and the
233 * {@link StringConverter} being used to convert the item in to a
234 * user-readable form.
235 *
236 * @param converter A {@link StringConverter} that can convert an item of type T
237 * into a user-readable string so that it may then be shown in the
238 * ChoiceBox popup menu.
239 * @param items The items to show in the ChoiceBox popup menu when selected
240 * by the user.
241 */
242 public ChoiceBoxTableCell(StringConverter<T> converter, ObservableList<T> items) {
243 this.getStyleClass().add("choice-box-table-cell");
244 this.items = items;
245 setConverter(converter != null ? converter : CellUtils.<T>defaultStringConverter());
246 }
247
248
249 /***************************************************************************
250 * *
251 * Properties *
252 * *
253 **************************************************************************/
254
255 // --- converter
256 private ObjectProperty<StringConverter<T>> converter =
257 new SimpleObjectProperty<StringConverter<T>>(this, "converter");
258
259 /**
260 * The {@link StringConverter} property.
261 */
262 public final ObjectProperty<StringConverter<T>> converterProperty() {
263 return converter;
264 }
265
266 /**
267 * Sets the {@link StringConverter} to be used in this cell.
268 */
269 public final void setConverter(StringConverter<T> value) {
270 converterProperty().set(value);
271 }
272
273 /**
274 * Returns the {@link StringConverter} used in this cell.
275 */
276 public final StringConverter<T> getConverter() {
277 return converterProperty().get();
278 }
279
280
281
282 /***************************************************************************
283 * *
284 * Public API *
285 * *
286 **************************************************************************/
287
288 /**
289 * Returns the items to be displayed in the ChoiceBox when it is showing.
290 */
291 public ObservableList<T> getItems() {
292 return items;
293 }
294
295 /** {@inheritDoc} */
296 @Override public void startEdit() {
297 if (! isEditable() || ! getTableView().isEditable() || ! getTableColumn().isEditable()) {
298 return;
299 }
300
301 if (choiceBox == null) {
302 choiceBox = createChoiceBox(this, items, converterProperty());
303 }
304
305 choiceBox.getSelectionModel().select(getItem());
306
307 super.startEdit();
308 setText(null);
309 setGraphic(choiceBox);
310 }
311
312 /** {@inheritDoc} */
313 @Override public void cancelEdit() {
314 super.cancelEdit();
315
316 setText(getConverter().toString(getItem()));
317 setGraphic(null);
318 }
319
320 /** {@inheritDoc} */
321 @Override public void updateItem(T item, boolean empty) {
322 super.updateItem(item, empty);
323 CellUtils.updateItem(this, getConverter(), null, null, choiceBox);
324 }
325 }