Added Javadoc for the ui.list package

This commit is contained in:
Kai S. K. Engelbart 2020-01-27 21:01:38 +01:00
parent df8eb4bac9
commit 82b3a09551
3 changed files with 74 additions and 10 deletions

View File

@ -4,10 +4,15 @@ import javax.swing.BoxLayout;
import javax.swing.JPanel; 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.<br>
* <br>
* Project: <strong>envoy-client</strong><br> * Project: <strong>envoy-client</strong><br>
* File: <strong>ComponentList.java</strong><br> * File: <strong>ComponentList.java</strong><br>
* Created: <strong>25.01.2020</strong><br> * Created: <strong>25.01.2020</strong><br>
* *
* @param <E> the type of object displayed in this list
* @author Kai S. K. Engelbart * @author Kai S. K. Engelbart
* @since Envoy v0.3-alpha * @since Envoy v0.3-alpha
*/ */
@ -18,17 +23,38 @@ public class ComponentList<E> extends JPanel {
private static final long serialVersionUID = 1759644503942876737L; 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<E> renderer) { public ComponentList(ComponentListCellRenderer<E> renderer) {
setLayout(new BoxLayout(this, BoxLayout.Y_AXIS)); setLayout(new BoxLayout(this, BoxLayout.Y_AXIS));
this.renderer = renderer; 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<E> model, ComponentListCellRenderer<E> renderer) { public ComponentList(ComponentListModel<E> model, ComponentListCellRenderer<E> renderer) {
this(renderer); this(renderer);
this.model = model; this.model = model;
setModel(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<E> model) { public void setModel(ComponentListModel<E> model) {
// Remove old model // Remove old model
if (this.model != null) { if (this.model != null) {
@ -42,14 +68,24 @@ public class ComponentList<E> extends JPanel {
synchronizeModel(); 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() { void synchronizeModel() {
removeAll(); removeAll();
if (model != null) if (model != null) for (E elem : model)
for (E elem : model) add(renderer.getListCellComponent(this, elem, false));
add(renderer.getListCellComponent(this, elem, false));
} }
} }

View File

@ -3,14 +3,28 @@ package envoy.client.ui.list;
import javax.swing.JComponent; import javax.swing.JComponent;
/** /**
* Allows a {@link ComponentList} convert its elements into Swing components
* that can be rendered.<br>
* <br>
* Project: <strong>envoy-client</strong><br> * Project: <strong>envoy-client</strong><br>
* File: <strong>ComponentListCellRenderer.java</strong><br> * File: <strong>ComponentListCellRenderer.java</strong><br>
* Created: <strong>25.01.2020</strong><br> * Created: <strong>25.01.2020</strong><br>
* *
* @param <E> the type of object displayed in this list
* @author Kai S. K. Engelbart * @author Kai S. K. Engelbart
* @since Envoy v0.3-alpha * @since Envoy v0.3-alpha
*/ */
public interface ComponentListCellRenderer<E> { public interface ComponentListCellRenderer<E> {
/**
* 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); JComponent getListCellComponent(ComponentList<? extends E> list, E value, boolean isSelected);
} }

View File

@ -6,10 +6,13 @@ import java.util.Iterator;
import java.util.List; import java.util.List;
/** /**
* Stores objects that will be displayed in a {@link ComponentList}.<br>
* <br>
* Project: <strong>envoy-client</strong><br> * Project: <strong>envoy-client</strong><br>
* File: <strong>ComponentListModel.java</strong><br> * File: <strong>ComponentListModel.java</strong><br>
* Created: <strong>25.01.2020</strong><br> * Created: <strong>25.01.2020</strong><br>
* *
* @param <E> the type of object displayed in this list
* @author Kai S. K. Engelbart * @author Kai S. K. Engelbart
* @since Envoy v0.3-alpha * @since Envoy v0.3-alpha
*/ */
@ -27,6 +30,7 @@ public final class ComponentListModel<E> implements Iterable<E>, Serializable {
* @param e the element to add * @param e the element to add
* @return {@code true} * @return {@code true}
* @see java.util.List#add(java.lang.Object) * @see java.util.List#add(java.lang.Object)
* @since Envoy v0.3-alpha
*/ */
public boolean add(E e) { public boolean add(E e) {
if (componentList != null) componentList.add(e); if (componentList != null) componentList.add(e);
@ -46,9 +50,10 @@ public final class ComponentListModel<E> implements Iterable<E>, Serializable {
} }
/** /**
* @param index * @param index the index to retrieve the element from
* @return * @return the element located at the index
* @see java.util.List#get(int) * @see java.util.List#get(int)
* @since Envoy v0.3-alpha
*/ */
public E get(int index) { return elements.get(index); } public E get(int index) { return elements.get(index); }
@ -56,9 +61,10 @@ public final class ComponentListModel<E> implements Iterable<E>, Serializable {
* Removes the element at a specific index from this model and the corresponding * Removes the element at a specific index from this model and the corresponding
* component from the {@link ComponentList}. * component from the {@link ComponentList}.
* *
* @param index * @param index the index of the element to remove
* @return the removed element * @return the removed element
* @see java.util.List#remove(int) * @see java.util.List#remove(int)
* @since Envoy v0.3-alpha
*/ */
public E remove(int index) { public E remove(int index) {
if (componentList != null) componentList.remove(index); if (componentList != null) componentList.remove(index);
@ -66,8 +72,9 @@ public final class ComponentListModel<E> implements Iterable<E>, Serializable {
} }
/** /**
* @return * @return an iterator over the elements of this list model
* @see java.util.List#iterator() * @see java.util.List#iterator()
* @since Envoy v0.3-alpha
*/ */
@Override @Override
public Iterator<E> iterator() { public Iterator<E> iterator() {
@ -83,6 +90,13 @@ public final class ComponentListModel<E> implements Iterable<E>, 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<E> componentList) { void setComponentList(ComponentList<E> componentList) {
this.componentList = componentList; this.componentList = componentList;
if (componentList != null) componentList.synchronizeModel(); if (componentList != null) componentList.synchronizeModel();