From 9db4a1a97a134e58f608d6f9404dcbc8f2456429 Mon Sep 17 00:00:00 2001 From: Christina Stiller Date: Wed, 5 Jan 2022 23:33:26 +0100 Subject: [PATCH] Add JavaDoc to ComboBox --- .../ux/component/field/combobox/ComboBox.java | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/teamapps-ux/src/main/java/org/teamapps/ux/component/field/combobox/ComboBox.java b/teamapps-ux/src/main/java/org/teamapps/ux/component/field/combobox/ComboBox.java index 7a4d5a917..07b43111c 100644 --- a/teamapps-ux/src/main/java/org/teamapps/ux/component/field/combobox/ComboBox.java +++ b/teamapps-ux/src/main/java/org/teamapps/ux/component/field/combobox/ComboBox.java @@ -38,6 +38,30 @@ import java.util.Set; import java.util.stream.Collectors; +/** + * A combo box is a drop-down list which can be expanded by pressing a button. It includes a text field + * where the user can type in a search term. The list element chosen by the user is then shown in that field. + * + * A combo box instance can either be created using the constructor or the overloaded {@link #createForList(List)} method + * or the {@link #createForEnum(Class)} method if the constants of an Enum class should be displayed. + * In all cases of the create functions, a {@link ComboBoxModel} is implemented. Its {@link ComboBoxModel#getRecords(String)} + * function matches a query string to the string representation of the records as defined by the function returned by + * {@link #getRecordToStringFunction()}. The toString() method of the RECORD class is the default. + * A combo box can also display hierarchical data where the {@link ComboBoxModel#getTreeNodeInfo(Object)} returns + * a TreeNodeInfo object containing i.a. information about the identity of the parent of the input object. + * + * The way a record is displayed in the drop-down list is highly configurable. Templates serve as placeholders for + * properties that are displayed in a defined way. One template can be universally set for all records using the + * {@link #setTemplate(Template)} function or it can be different for the records in the drop-down list + * ({@link #setDropDownTemplate(Template)}) and the record selected by the user ({@link #setSelectedEntryTemplate(Template)}. + * The choice of template for a record can be further specified by implementing a {@link TemplateDecider} and setting + * it via {@link #setTemplateDecider(TemplateDecider)}, {@link #setSelectedEntryTemplateDecider(TemplateDecider)} or + * {@link #setDropdownTemplateDecider(TemplateDecider)}. + * + * The {@link org.teamapps.data.extract.PropertyProvider} or its specification, the PropertyExtractor, are used to map + * the template's property names to object specific information, e.g. its attributes, that should represent the record + * in the combo box. + */ public class ComboBox extends AbstractComboBox implements TextInputHandlingField { private static final Logger LOGGER = LoggerFactory.getLogger(ComboBox.class);