changeset 207:d3a30f9b38c3

[DOC ONLY] RT-18657: Document ListView defaults (also TreeView and TableView)
author jgiles
date Thu, 29 Dec 2011 17:21:48 +1000
parents 87227803da34
children c479f20557bb
files javafx-ui-controls/src/javafx/scene/control/ListView.java javafx-ui-controls/src/javafx/scene/control/TableView.java javafx-ui-controls/src/javafx/scene/control/TreeView.java
diffstat 3 files changed, 102 insertions(+), 9 deletions(-) [+]
line wrap: on
line diff
--- a/javafx-ui-controls/src/javafx/scene/control/ListView.java	Thu Dec 29 16:57:15 2011 +1000
+++ b/javafx-ui-controls/src/javafx/scene/control/ListView.java	Thu Dec 29 17:21:48 2011 +1000
@@ -117,6 +117,18 @@
  * Whilst it is possible to use this API to set a new selection model, in
  * most circumstances this is not necessary - the default selection and focus
  * models should work in most circumstances.
+ * 
+ * <p>The default {@link SelectionModel} used when instantiating a ListView is
+ * an implementation of the {@link MultipleSelectionModel} abstract class. 
+ * However, as noted in the API documentation for
+ * the {@link MultipleSelectionModel#selectionModeProperty() selectionMode}
+ * property, the default value is {@link SelectionMode#SINGLE}. To enable 
+ * multiple selection in a default ListView instance, it is therefore necessary
+ * to do the following:
+ * 
+ * <pre>
+ * {@code 
+ * listView.getSelectionModel().setSelectionMode(SelectionMode.MULTIPLE);}</pre>
  *
  * <h3>Customizing ListView Visuals</h3>
  * <p>The visuals of the ListView can be entirely customized by replacing the 
@@ -203,6 +215,9 @@
      * {@link #getItems()} if so desired. However, as noted elsewhere, this
      * is not the recommended approach 
      * (instead call {@link #setItems(javafx.collections.ObservableList)}).
+     * 
+     * <p>Refer to the {@link ListView} class documentation for details on the
+     * default state of other properties.
      */
     public ListView() {
         this(FXCollections.<T>observableArrayList());
@@ -214,6 +229,9 @@
      * 
      * <p>Attempts to add a listener to the {@link ObservableList}, such that all
      * subsequent changes inside the list will be shown to the user.
+     * 
+     * <p>Refer to the {@link ListView} class documentation for details on the
+     * default state of other properties.
      */
     public ListView(ObservableList<T> items) {
         getStyleClass().setAll(DEFAULT_STYLE_CLASS);
--- a/javafx-ui-controls/src/javafx/scene/control/TableView.java	Thu Dec 29 16:57:15 2011 +1000
+++ b/javafx-ui-controls/src/javafx/scene/control/TableView.java	Thu Dec 29 17:21:48 2011 +1000
@@ -196,6 +196,49 @@
  *  });
  * }}</pre>
  * 
+ * <h3>TableView Selection / Focus APIs</h3>
+ * <p>To track selection and focus, it is necessary to become familiar with the
+ * {@link SelectionModel} and {@link FocusModel} classes. A TableView has at most
+ * one instance of each of these classes, available from 
+ * {@link #selectionModelProperty() selectionModel} and 
+ * {@link #focusModelProperty() focusModel} properties respectively.
+ * Whilst it is possible to use this API to set a new selection model, in
+ * most circumstances this is not necessary - the default selection and focus
+ * models should work in most circumstances.
+ * 
+ * <p>The default {@link SelectionModel} used when instantiating a TableView is
+ * an implementation of the {@link MultipleSelectionModel} abstract class. 
+ * However, as noted in the API documentation for
+ * the {@link MultipleSelectionModel#selectionModeProperty() selectionMode}
+ * property, the default value is {@link SelectionMode#SINGLE}. To enable 
+ * multiple selection in a default TableView instance, it is therefore necessary
+ * to do the following:
+ * 
+ * <pre>
+ * {@code 
+ * tableView.getSelectionModel().setSelectionMode(SelectionMode.MULTIPLE);}</pre>
+ *
+ * <h3>Customizing TableView Visuals</h3>
+ * <p>The visuals of the TableView can be entirely customized by replacing the 
+ * default {@link #rowFactoryProperty() row factory}. A row factory is used to
+ * generate {@link TableRow} instances, which are used to represent an entire
+ * row in the TableView. 
+ * 
+ * <p>In many cases, this is not what is desired however, as it is more commonly
+ * the case that cells be customized on a per-column basis, not a per-row basis.
+ * It is therefore important to note that a {@link TableRow} is not a 
+ * {@link TableCell}. A  {@link TableRow} is simply a container for zero or more
+ * {@link TableCell}, and in most circumstances it is more likely that you'll 
+ * want to create custom TableCells, rather than TableRows. The primary use case
+ * for creating custom TableRow instances would most probably be to introduce
+ * some form of column spanning support.
+ * 
+ * <p>You can create custom {@link TableCell} instances per column by assigning 
+ * the appropriate function to the TableColumn
+ * {@link TableColumn#cellFactoryProperty() cell factory} property.
+ * 
+ * <p>See the {@link Cell} class documentation for a more complete
+ * description of how to write custom Cells.
  *
  * @see TableColumn
  * @see TablePosition
@@ -588,6 +631,9 @@
 
     /**
      * Creates a default TableView control with no content.
+     * 
+     * <p>Refer to the {@link TableView} class documentation for details on the
+     * default state of other properties.
      */
     public TableView() {
         this(FXCollections.<S>observableArrayList());
@@ -598,6 +644,9 @@
      * This also sets up an observer such that any changes to the items list
      * will be immediately reflected in the TableView itself.
      * 
+     * <p>Refer to the {@link TableView} class documentation for details on the
+     * default state of other properties.
+     * 
      * @param items The items to insert into the TableView, and the list to watch
      *          for changes (to automatically show in the TableView).
      */
--- a/javafx-ui-controls/src/javafx/scene/control/TreeView.java	Thu Dec 29 16:57:15 2011 +1000
+++ b/javafx-ui-controls/src/javafx/scene/control/TreeView.java	Thu Dec 29 17:21:48 2011 +1000
@@ -24,8 +24,6 @@
  */
 package javafx.scene.control;
 
-import java.util.ArrayList;
-import java.util.Collections;
 import java.util.List;
 
 import javafx.beans.property.BooleanProperty;
@@ -43,7 +41,6 @@
 import javafx.scene.control.TreeItem.TreeModificationEvent;
 import javafx.util.Callback;
 
-import com.sun.javafx.css.StyleableProperty;
 import com.sun.javafx.scene.control.WeakEventHandler;
 import com.sun.javafx.scene.control.skin.VirtualContainerBase;
 import java.lang.ref.WeakReference;
@@ -83,12 +80,34 @@
  * nodes of the root node are shown. By default, the root node is shown in the
  * TreeView.
  * 
- * <p>
- * The visuals of a TreeView can be entirely customized by creating a
- * {@link #cellFactoryProperty()  cellFactory} for the TreeView. The cell 
- * factory is used for generating {@link TreeCell} instances which will be used 
- * to represent a single TreeItem in the TreeView. See the {@link Cell} class 
- * documentation for a more complete description of how to write custom cells.
+ * <h3>TreeView Selection / Focus APIs</h3>
+ * <p>To track selection and focus, it is necessary to become familiar with the
+ * {@link SelectionModel} and {@link FocusModel} classes. A TreeView has at most
+ * one instance of each of these classes, available from 
+ * {@link #selectionModelProperty() selectionModel} and 
+ * {@link #focusModelProperty() focusModel} properties respectively.
+ * Whilst it is possible to use this API to set a new selection model, in
+ * most circumstances this is not necessary - the default selection and focus
+ * models should work in most circumstances.
+ * 
+ * <p>The default {@link SelectionModel} used when instantiating a TreeView is
+ * an implementation of the {@link MultipleSelectionModel} abstract class. 
+ * However, as noted in the API documentation for
+ * the {@link MultipleSelectionModel#selectionModeProperty() selectionMode}
+ * property, the default value is {@link SelectionMode#SINGLE}. To enable 
+ * multiple selection in a default TreeView instance, it is therefore necessary
+ * to do the following:
+ * 
+ * <pre>
+ * {@code 
+ * treeView.getSelectionModel().setSelectionMode(SelectionMode.MULTIPLE);}</pre>
+ * 
+ * <h3>Customizing TreeView Visuals</h3>
+ * <p>The visuals of the TreeView can be entirely customized by replacing the 
+ * default {@link #cellFactoryProperty() cell factory}. A cell factory is used to
+ * generate {@link TreeCell} instances, which are used to represent an item in the
+ * TreeView. See the {@link Cell} class documentation for a more complete
+ * description of how to write custom Cells.
  *
  * @see TreeItem
  * @see TreeCell
@@ -193,6 +212,9 @@
 
     /**
      * Creates an empty TreeView.
+     * 
+     * <p>Refer to the {@link ListView} class documentation for details on the
+     * default state of other properties.
      */
     public TreeView() {
         this(null);
@@ -200,6 +222,10 @@
 
     /**
      * Creates a TreeView with the provided root node.
+     * 
+     * <p>Refer to the {@link ListView} class documentation for details on the
+     * default state of other properties.
+     * 
      * @param root The node to be the root in this TreeView.
      */
     public TreeView(TreeItem<T> root) {