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 extends E> 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();