diff --git a/src/main/java/envoy/client/ui/list/ComponentList.java b/src/main/java/envoy/client/ui/list/ComponentList.java index 7cca24a..47f8c31 100644 --- a/src/main/java/envoy/client/ui/list/ComponentList.java +++ b/src/main/java/envoy/client/ui/list/ComponentList.java @@ -4,10 +4,15 @@ import javax.swing.BoxLayout; import javax.swing.JPanel; /** + * Provides a vertical list layout of components provided in a + * {@link ComponentListModel}. Similar to {@link javax.swing.JList} but capable + * of rendering {@link JPanel}s.
+ *
* Project: envoy-client
* File: ComponentList.java
* Created: 25.01.2020
* + * @param the type of object displayed in this list * @author Kai S. K. Engelbart * @since Envoy v0.3-alpha */ @@ -18,17 +23,38 @@ public class ComponentList extends JPanel { private static final long serialVersionUID = 1759644503942876737L; + /** + * Creates an instance of {@link ComponentList}. + * + * @param renderer the list cell renderer used to display elements provided by + * the {@link ComponentListModel} + * @since Envoy v0.3-alpha + */ public ComponentList(ComponentListCellRenderer renderer) { setLayout(new BoxLayout(this, BoxLayout.Y_AXIS)); this.renderer = renderer; } + /** + * Creates an instance of {@link ComponentList}. + * + * @param model the list model providing the list elements to render + * @param renderer the list cell renderer used to display elements provided by + * the {@link ComponentListModel} + * @since Envoy v0.3-alpha + */ public ComponentList(ComponentListModel model, ComponentListCellRenderer renderer) { this(renderer); this.model = model; setModel(model); } + /** + * Sets the list model providing the list elements to render + * + * @param model the list model to set + * @since Envoy v0.3-alpha + */ public void setModel(ComponentListModel model) { // Remove old model if (this.model != null) { @@ -42,14 +68,24 @@ public class ComponentList extends JPanel { synchronizeModel(); } - void add(E elem) { - add(renderer.getListCellComponent(this, elem, false)); - } + /** + * Adds an object to the list by rendering it with the current + * {@link ComponentListCellRenderer}. + * + * @param elem the element to add + * @since Envoy v0.3-alpha + */ + void add(E elem) { add(renderer.getListCellComponent(this, elem, false)); } + /** + * Removes all child components and then adds all components representing the + * elements of the {@link ComponentListModel}. + * + * @since Envoy v0.3-alpha + */ void synchronizeModel() { removeAll(); - if (model != null) - for (E elem : model) - add(renderer.getListCellComponent(this, elem, false)); + if (model != null) for (E elem : model) + add(renderer.getListCellComponent(this, elem, false)); } } diff --git a/src/main/java/envoy/client/ui/list/ComponentListCellRenderer.java b/src/main/java/envoy/client/ui/list/ComponentListCellRenderer.java index 7fdab1b..a8bdda6 100644 --- a/src/main/java/envoy/client/ui/list/ComponentListCellRenderer.java +++ b/src/main/java/envoy/client/ui/list/ComponentListCellRenderer.java @@ -3,14 +3,28 @@ package envoy.client.ui.list; import javax.swing.JComponent; /** + * Allows a {@link ComponentList} convert its elements into Swing components + * that can be rendered.
+ *
* Project: envoy-client
* File: ComponentListCellRenderer.java
* Created: 25.01.2020
* + * @param the type of object displayed in this list * @author Kai S. K. Engelbart * @since Envoy v0.3-alpha */ public interface ComponentListCellRenderer { + /** + * Provides a Swing component representing a list element. + * + * @param list the list in which the component will be displayed + * @param value the list element that will be converted + * @param isSelected {@code true} if the user has selected the list cell in + * which the list element is rendered + * @return the component representing the list element + * @since Envoy v0.3-alpha + */ JComponent getListCellComponent(ComponentList list, E value, boolean isSelected); } diff --git a/src/main/java/envoy/client/ui/list/ComponentListModel.java b/src/main/java/envoy/client/ui/list/ComponentListModel.java index e4b0594..1845651 100644 --- a/src/main/java/envoy/client/ui/list/ComponentListModel.java +++ b/src/main/java/envoy/client/ui/list/ComponentListModel.java @@ -6,10 +6,13 @@ import java.util.Iterator; import java.util.List; /** + * Stores objects that will be displayed in a {@link ComponentList}.
+ *
* Project: envoy-client
* File: ComponentListModel.java
* Created: 25.01.2020
* + * @param the type of object displayed in this list * @author Kai S. K. Engelbart * @since Envoy v0.3-alpha */ @@ -27,6 +30,7 @@ public final class ComponentListModel implements Iterable, Serializable { * @param e the element to add * @return {@code true} * @see java.util.List#add(java.lang.Object) + * @since Envoy v0.3-alpha */ public boolean add(E e) { if (componentList != null) componentList.add(e); @@ -46,9 +50,10 @@ public final class ComponentListModel implements Iterable, Serializable { } /** - * @param index - * @return + * @param index the index to retrieve the element from + * @return the element located at the index * @see java.util.List#get(int) + * @since Envoy v0.3-alpha */ public E get(int index) { return elements.get(index); } @@ -56,9 +61,10 @@ public final class ComponentListModel implements Iterable, Serializable { * Removes the element at a specific index from this model and the corresponding * component from the {@link ComponentList}. * - * @param index + * @param index the index of the element to remove * @return the removed element * @see java.util.List#remove(int) + * @since Envoy v0.3-alpha */ public E remove(int index) { if (componentList != null) componentList.remove(index); @@ -66,8 +72,9 @@ public final class ComponentListModel implements Iterable, Serializable { } /** - * @return + * @return an iterator over the elements of this list model * @see java.util.List#iterator() + * @since Envoy v0.3-alpha */ @Override public Iterator iterator() { @@ -83,6 +90,13 @@ public final class ComponentListModel implements Iterable, Serializable { }; } + /** + * Sets the component list displaying the elements of this model and triggers a + * synchronization. + * + * @param componentList the component list to set + * @since Envoy v0.3-alpha + */ void setComponentList(ComponentList componentList) { this.componentList = componentList; if (componentList != null) componentList.synchronizeModel();