ManualLayerModelAdapterNullValue

Null Values

RCPForms supports dealing with Null Values, which are usually used to indicate that the user has not entered any value yet or that some information is not available at all. Since SWT, JFace and Databinding are not too well suited for this,
some tricks and workarounds have been necessary to make this work.

If you debug handling of null values, you might find some surprises, thus null value handling is explained here.

Model

Null Values in the model are always defined as Java null, no tricks, no exception, only maybe bugs in RCPForms ;-).
This means, if you use primitive types for attributes, you will not get null value support, that simple. If a user interface component offers a special state for the null value, e.g. a combo box with no selection, setting this value will be considered a bug, result in a databinding error and an error marker will show up (which should be avoided to show up with the end user).

Text Fields

Text fields provide no means of entering a null value, thus the null value for text fields is identified with the empty string "". This actually means that there is no way in the UI to enter an empty string into a string attribute in the model. A default converter will convert empty strings to null whenever they show up. You should avoid using empty strings in your model since this might lead to confusing bugs when the empty string is transferred to the UI and back and converted to a null even if the user did not change anything in the text field at all, or he enters a character, deletes it again and --> wow, the attribute changed from "" to null. Thus: Take care '''

Check Boxes

In Eclipse 3.3 checkboxes have only 2 states, checked and unchecked; the data type of a checkbox in databinding is "boolean". To enable binding Boolean to a checkbox, a default converter will convert Boolean null values to boolean false, thus you can bind a Boolean to a checkbox without receiving an error. Still the same applies as said above in Text Fields.

Viewers

JFace viewers are model based; you set an input to the viewer, a content provider adapts this input into the structure (a list for table, combo, list widgets or a tree for tree widgets) the viewer needs it, and a label provider defines how to render the elements, usually providing an icon and a text; see this JFace article for details.

RCPForms automatically creates viewers for the appropriate controls, and for attributes supporting a range adapter this adapter is used to create content provider, label provider and input automatically; this is why the Gender combobox in the example application shows all enum values in the drop down list; because during binding a range adapter was available and used to create this stuff.

In a combo box, there is usually no way to select "no choice"; if a model value is bound to the combo which is not in the list of the content provider, no element in the list is selected; but the user cannot "unset" the combo box.

Since this behavior of not setting a value is a common use case, RCPForms offers support for Null Values here. A Jface Viewer needs a model element for every item displayed; using Java null as the model element does not work, viewers do not like null elements. Thus RCPForms introduces the NullValue placeholder class with exactly one instance, which is used instead of null.

This null value placeholder is used in combo boxes and radio groups to enable the user to select no value explicitly.
During bind converters will automatically be created to convert NullValue --> null from ui control to model attribute and null --> NullValue vice versa.

This also works in Tables and Table editors.

Creating Wrappers supporting Null Values

Since the information if a use ris allowed to enter null values or not often depend on the form, not the model, this information can be added to some wrappers at creation time. Currently Radio Groups and Combos support this flag. The control itself just stores the flag, but during auto creation using a range adapter this information is used to determine if the content provider should provide a NullValue placeholder or not (for combo) or if a radio button is created associated with the NullValue placeholder or not.

Presentation

Since a NullValue can be shown to the user with different text, a concept of "presentation" is defined, which actually is an index into a list of texts. Presentations can be registered in the NullValue class and the index can be passed to combo and radio group, actually to all wrappers implementing IPresentationConfiguration.

The label provider created by the range adapter should use this information to determine the text to show; if you provide your own label provider make sure you implement handling of the NullValue object.