Re: ACTION-2275: Draft new text for <copy/>

LGTM.

On Tue, Mar 17, 2020 at 3:13 AM Steven Pemberton <steven.pemberton@cwi.nl>
wrote:

> Second draft, following the call last week. Only changes in the topmost
> section.
>
> Example with attributes still to be added.
>
> Steven
>
> ===========================================
> 9.9 Selection Controls  (Some changes here)
>
> There are two selection controls:
> * select which allows the selection of zero or more values from a
> collection, which are combined into a single value and stored in the
> bound
> value;
> * select1 which allows for the selection of zero or one from the
> collection, which is then stored in the bound value.
>
> The collection of values to be selected from are provided either by a
> number of item elements, each of which supplies one value, or a single
> itemset element, which provides a sequence of values.
>
> A selection control can be "simple" or "complex":
> * a simple selection only selects simpleContent values (typically
> strings), in which case the item or itemset elements use a value child or
> attribute;
> * a complex selection selects more general values (typically with
> children
> nodes), and the item or itemset elements use a copy child or attribute.
> If
> one item element has a copy attribute or child, then all of them must
> have, and the bound target of the containing selection control must be an
> element node, otherwise an xforms-binding-error event is dispatched to
> the
> containing selection control.
>
> A simple selection can be either "open" or "closed", as indicated by the
> selection attribute: an open selection allows inclusion of values outside
> the collection given. A complex selection is always closed.
>
> The items from the child or children of the selection control are
> evaluated, each being a pair of a label and a value.
>
> The label for each pair must be made available to the user, with an
> indication of whether the item is selected or not.
>
> Interaction with a label toggles the selected state. On selection, items
> receive the xforms-select event; on deselection, the xforms-deselect event.
>
> A selection control is out-of-range if it is bound to data whose value
> for
> any reason is not in the collection of possible values.
>
> Typically, a style sheet is used to control the appearance of controls,
> though a means is provided to suggest an appearance through the
> appearance
> attribute. The value of the attribute consists of one of the following
> values:
> * "full": all labels should be rendered at all times;
> * "compact": a fixed number of labels should be rendered, with scrolling
> facilities as needed;
> * "minimal": a minimum number of labels should be rendered, with a
> facility to temporarily render additional choices.
>
> 9.9.1 The select Element (No change)
>
> [...]
>
> All items whose values match a value in the bound instance data are
> initially selected; if a particular value in the bound data matches more
> than one item, at least one is selected, but it is not further defined
> which, nor how many. If there is no match, no items are initially
> selected. Items with an empty storage data subtree or a storage value
> that
> is either empty or contains only white space characters are never selected.
>
> If the bound instance data contains values that do not match any item's
> value:
> * for open selections, all such non-matching values are retained and made
> available to the user; since there are no associated labels, the value
> itself is used as the label;
> * for closed selections, the control is out-of-range.
>
> Any number of the items may be selected, including none.
>
> For open selections, the control must also allow free data entry, as
> described in The input Element. The control must permit multiple values
> to
> be entered through free entry. The label of such an entered value is
> considered identical to the value itself.
>
> Selected values are represented in the bound instance location:
> * for simple selections as a space-separated list,
> * for complex selections as copies of the subtrees of the selected values.
>
> The content of the bound instance node must only be changed by the
> addition or deletion of storage data associated with items that have been
> selected or deselected; content not associated with selection items must
> be preserved.
>
> For a simple selection, the net effect of newly selected and deselected
> items is computed into a string, preserving content not associated with
> selection items. For complex selections, the individual subtrees
> associated with the newly selected and deselected items are added or
> removed individually by using insert and delete; after which an update is
> done, followed by a refresh.
>
> [...]
>
> 9.9.2 The select1 Element (No change)
>
> [...]
>
> Any item whose value matches the value of the bound instance data is
> initially selected; if more than one matches, at least one is selected,
> but it is not further defined which, nor how many of the matching items
> is
> selected. If there is no match, no item is initially selected. For both
> closed and open selections, any item with an empty storage data subtree
> or
> a storage value that is either empty or contains only white space
> characters is treated identically to any other value.
>
> If the bound instance data is non-empty and does not match any item's
> value:
> * for open selections, the non-matching value is retained and made
> available to the user; the value is also used as the label;
> * for closed selections, the control is out-of-range;
>
> Interaction with the label of an unselected item deselects any
> already-selected item and then selects the new item; interaction with the
> label of a selected item deselects that item.
>
> For open selections, the control must also allow free data entry, as
> described in The input Element; entering a value selects that value after
> deselecting any already-selected value. The label of such an entered
> value
> is considered identical to the value itself.
>
> The selected value is stored in the bound instance location, for complex
> selections as a copy of the subtree of the selected value.
>
> 9.9.4 The item Element (add copy as a child element and attribute)
>
> [...]
>
> Special Attributes:
> copy
>   Optional expression giving a value to be copied. Takes precedence over
> any copy child element.
>
> Content: (value|copy), (UI Common)*
>
> [...]
>
> 9.9.5.1 The copy Element (for item and itemset)
>
> This element is similar to the value element, except that it works with
> subtrees of instance data rather than simple values.
>
> Common Attributes: Common, Single Item Binding
>
> Content: EMPTY
>
> The storage value is obtained by evaluating the Single Item Binding.
> ===========================================
>
>