Form Controls accepting Value Bindings

From Apache OpenOffice Wiki
Jump to: navigation, search

How do form controls and value bindings relate to each other? When looking at all the form control functionality that has so far been discussed, the following questions come need to be answered:

  • Which control types do support value bindings?
  • For a given control type, which aspect actually is its value, which is exchanged with an external binding?
  • How do external value bindings interact with data awareness, for example, controls that exchange their value with a database column?
  • What can you do with all this?

The first two questions are easy: Every control that allows user input also supports value bindings. The data that the user entered (this may be, for instance, plain text, or an image, or a check state) is considered the value of the control, and thus exchanged with the external binding.

The basic service is the, which specifies a control model supporting external value bindings. For a concrete control type, for instance, a check box, a service such as BindableCheckBox would be expected, which specifies how a check box control model exchanges its value with an external binding.

However, all controls that potentially could support a binding also are data aware (see Data Aware Controls). Thus, the first step is to answer the third question from above. The service is about data aware control models with value binding capabilities. You are referred to the documentation of the BindableDataAwareControlModel service for all the details, but the two most interesting details are as follows:

Priority External value bindings overrule any active SQL-column binding. If an external component is bound to a control model that currently has an active SQL binding, this SQL binding is suspended until the external binding is revoked.

Immediacy When a BindableDataAwareControlModel is bound to an external value, then every change in the control model's value is immediately reflected in the external binding. This is a difference to SQL bindings of most DataAwareControlModels, where changes in the model's value are only propagated to the bound column upon explicit request via commit.

The illustration below shows the service hierarchy for control models that are also value components. It also shows how concrete control types fit in, for example by using check boxes.

Form control models supporting value bindings

The following covers the last question from the above list: What is this good for?

Apache OpenOffice already contains two practical applications:

Spreadsheet cell bindings

In a Apache OpenOffice spreadsheet document, you always could insert form controls. Since version 2.0.0, you can, in their properties, bind form controls to arbitrary cells within the document. That is, every change made in this cell is propagated to the control, and vice versa. This is implemented using the value binding mechanism described in this chapter. See for more details.
The following piece of code creates a cell value binding in a spreadsheet document, for cell A1 on the first sheet, and knits it to a numeric control model:
  // insert our sample control
  XPropertySet numericControl = m_formLayer.insertControlLine( "DatabaseFormattedField",
      "enter a value", "", 10 );
  // a value binding for cell A1 on the first
  CellAddress address = new CellAddress( (short)0, (short)0, (short)0 );
  Object[] initParam = new Object[] { new NamedValue( "BoundCell", address ) };
  XValueBinding cellBinding = (XValueBinding)UnoRuntime.queryInterface(
          "", initParam ) );
  // bind it to the control model
  XBindableValue bindable = (XBindableValue)UnoRuntime.queryInterface(
      XBindableValue.class, numericControl
  bindable.setValueBinding( cellBinding );

XML form bindings

Apache OpenOffice features XML forms. These are form documents whose data model is a DOM tree. They are realized with the usual form controls and logical forms, and this time the controls are bound to DOM nodes using the value binding mechanism.
Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages