Unlike the functionality for binding form controls to database columns, value bindings are external to the form control/model. A control that can be bound (note that not all existing controls actually can) supports a certain interface, and a binding supports another one. That is all both parties need to know.
The illustration below shows the most important interfaces and services collaborating here.
Note that there is yet no notion about form controls at all. Those interfaces are only concerned with components representing a value, and components implementing a binding for this value. In fact, the generic mechanism for binding values is described with a complete disregard of form controls. The components supporting the XBindableValue interface are called value components.
The central interface is XValueBinding, which is to be supported by components that want to impose their value on a value component. The following table describes its methods:
|Methods of com.sun.star.form.binding.XValueBinding|
|getSupportedValueTypes()||Allows negotiation of a type in which values are exchanged. Usually, both a binding and a value component only support a certain set of types, in which the values can be exchanged. If the sets of a given binding and a given value component do not intersect, both can not be knit together.|
|supportsType()||Allows a value component to explicitly ask whether a given binding supports a given type.
This method can be used as shortcut: components do not need to examine the complete type sequence of a binding.
Additionally, this method is usually used to implement a precedence of types. A value component can ask a potential binding for certain supported types, in a certain order. The first type that is accepted by the binding (if any) can then be used for exchanging the value.
|getValue()||Retrieves the current value as represented by the binding. Callers specify a type of the value, and the binding must provide the value in exactly this type, or throw an com.sun.star.form.binding.IncompatibleTypesException if this is not possible.|
|setValue()||Propagates a new value to the binding.|
- This allows a value binding to actively notify changes in its value. A value component can register itself as XModifyListener at the binding. In fact, that is the only way that the relationship between the binding and the value component can become bidirectional. Without the support of the XModifyBroadcaster interface, value components can only actively propagate their value to the binding, but not the reverse.
support for read-only bindings
- The ReadOnly property can be used to specify that the value represented by a binding currently cannot be modified. If the read-only state of a binding's value can change during its lifetime, it should allow registering XPropertyChangeListeners for the ReadOnly property, so value components using the binding can act on the current state.
|Content on this page is licensed under the Public Documentation License (PDL).|