PropertyHandle :: SetAutoSelection - Set auto selection
The function sets a single selection condition for the property handle by key or position. The function can be used instead of passing a selection argument to the property handle like children(0) or children("Paul"). Since passing selection arguments to property handles in a property path after a function call is not possible, autoSelect() may be called.
The function does not select the instance, but supports internal selections when required.
When the property handle is not valid, the function throws an exception.
children.changeAccessKey("first_name").setAutoSelection("Paul",false);
Implementation details
The function sets the auto selection option to the position passed in iPosition.
When required internally or when calling autoSelect(), the instance will be automatically selected. When iPosition is greater or equal the the collection count, a new instance will be created, when bProvide is true. Otherwise, no instance will be selected (and autoSelect() will return an unselected property handle).
- set_pos0
- Position in collection
The position of an instance in a collection depends on the selected index. if the collection is unsorted the position is the only way for accessing the instance.
For sorted collections the position is determined according to the instance key. If is a contradiction between position and key value the position will be ignored.
Special positions are
CUR_INSTANCE (-1) refers to the currently selected instance. If no instance is selected it refers to the first instance.
FIRST_INSTANCE (0) refers to the first instance in a collection according to the selected index (sort order).
FIRST_INSTANCE (0x7fffffff) refers to the last instance in a collection according to the selected index (sort order).
- provide
- Option to request instanziation
If necessary the requested object instance is created.