diff options
author | Lionel Elie Mamane <lionel@mamane.lu> | 2013-04-21 15:46:47 +0200 |
---|---|---|
committer | Lionel Elie Mamane <lionel@mamane.lu> | 2013-04-22 17:55:19 +0200 |
commit | 0ed5028e8e5b782d63b2d00602e7ef52f0e4d016 (patch) | |
tree | 34862cafb36456d2345ccf8575a3977e7984ec41 | |
parent | bfc0bf6a164f25c6e2af86fb0298ecb0f88c9df9 (diff) |
Note on design philosophy of data-aware ListBox
Change-Id: I773c6b0704a31ab501cc51c6c7cd5e4be390a166
-rw-r--r-- | forms/source/component/ListBox.hxx | 48 |
1 files changed, 48 insertions, 0 deletions
diff --git a/forms/source/component/ListBox.hxx b/forms/source/component/ListBox.hxx index 51cf5a8fc016..2540ad8eb4ca 100644 --- a/forms/source/component/ListBox.hxx +++ b/forms/source/component/ListBox.hxx @@ -42,6 +42,54 @@ #include <vector> +/** ListBox is a bit confusing / different from other form components, + so here are a few notes: + + The general design philosophy is that a ListBox is a mechanism + to translate back and forth between: + 1) *display* values (strings that the user sees and chooses) + 2) *binding* values, which is what the program (for a dialog), + the database, ... cares about. + + A non-data aware ListBox exposes this mechanism through + com.sun.star.awt.XItemList (get|set)ItemData. + + In a data-aware ListBox, this is naturally embodied by the + StringItemList on the one hand, and the ValueList on the other + hand (where, depending on ListSourceType, the ValueList is + possibly automatically filled from the BoundColumn of the + ListSource). + + This source file implements data-aware ListBox, and the rest + of this comment applies to data-aware ListBox (only). + + In all public APIs of the *model* (OListBoxModel), + the value of the control is the *binding* value. + That is what the bound database field gets, + that is what a validator validates, + that is what an external value binding + (com.sun.star.form.binding.XValueBinding) + exchanges with the control. + + As an *implementation* choice, we keep the current value of the + ListBox as a sequence of *indices* in the value list, and do the + lookup on demand: + + - ListBox's content propery (or value property, sorry the + terminology is not always consistent) is SelectedItems which is + a sequence of *indices* in the value list. + + - That is used to synchronise with our peer (UnoControlListBoxModel). + + In particular, note that getCurrentValue() is a public API (and + deals with bound values), but getControlValue and + (do)setControlValue are *internal* implementation helpers that + deal with *indices*. + + Note that the *view* (OListBoxControl) presents a different story + than the model. E.g. the "SelectedItems" property is *display* *values*. +*/ + //......................................................................... namespace frm { |